Frank Schwenk
ce431d7eec
Delegate expected output filenames to modules so resume works for rembg and composite; normalize G'MIC multi-frame output; add OpenRouter style reference support with tests. Add Crusaders, orange, and team gallery pipelines plus SOUL/AGENTS context files. Co-authored-by: Cursor <cursoragent@cursor.com>
94 lines
4.2 KiB
Markdown
94 lines
4.2 KiB
Markdown
# SOUL.md — Imagepipeline
|
|
|
|
What this project is — not chat mood (see `MOOD.md`).
|
|
|
|
---
|
|
|
|
## Agent Quick Start
|
|
|
|
- **What:** Modular Python framework for batch image pipelines after Darktable export — ImageMagick, G'MIC, rembg, AI edits (OpenRouter, Comfy), compositing.
|
|
- **Run:** `pip install -e ".[dev]"` (optional `[ai]` for torch modules); `pytest`; pipelines via `python pipelines/<name>.py`.
|
|
- **Output:** Timestamped run dirs under `~/pipeline_output/` (`{pipeline_name}_{YYMMDDHHMMSS}/`) with numbered step subfolders and `pipeline_manifest.json`.
|
|
- **Resume:** Pipelines support `CONTINUE_FROM` and `EXISTING_OUTPUTS`; modules must declare correct `expected_output_filenames` when output names differ from inputs (e.g. rembg → `.png`).
|
|
- **Secrets:** `OPENROUTER_API_KEY` in `.env` (see `.env.example`) — never commit.
|
|
- **Tests:** Run `pytest` before handoff on non-trivial module/resume changes.
|
|
- **Commit policy:** No commit unless Fränky asks (this project follows global `AGENTS.md`).
|
|
|
|
---
|
|
|
|
## Product Name
|
|
|
|
**Imagepipeline**
|
|
|
|
## One-Liner
|
|
|
|
Modular Python framework for chaining batch image processing steps after Darktable export.
|
|
|
|
## Vision
|
|
|
|
Photography workflows (Crusaders, f12, team galleries) need repeatable, resumable batch edits — not one-off GUI clicks. Imagepipeline turns a DAG of processing steps into plain Python scripts: each step writes to a numbered folder, runs can be resumed, and external tools (ImageMagick, G'MIC, rembg, OpenRouter) stay composable.
|
|
|
|
## Audience
|
|
|
|
Primarily **Fränky** — batch-processing exported RAW/JPEG folders for sports photography, blog assets, and gallery consistency. Expects CLI clarity, honest errors, and pipelines that survive interruption mid-run.
|
|
|
|
## Tone & Wording
|
|
|
|
CLI logs, errors, and module help text:
|
|
|
|
- **Voice:** Direct, utilitarian — ops tool, not a product landing page
|
|
- **Formality:** English for code/CLI; chat with Fränky in DE or EN
|
|
- **Error messages:** Say what failed, which file/step, and what to check — no blame, no vague "something went wrong"
|
|
- **Forbidden words/phrases:** "leverage", "synergy", corporate coach tone, LinkedIn buzzwords
|
|
|
|
### Wording Examples
|
|
|
|
| Context | Good | Bad |
|
|
|---------|------|-----|
|
|
| Success | `Step rembg_01 complete (42 files)` | `Successfully processed your images!` |
|
|
| Error | `G'MIC produced no output for photo.png in rembg_01/` | `An error occurred during processing` |
|
|
| Empty state | `No images matched in input/` | `Nothing to see here yet!` |
|
|
|
|
## Design (Optional)
|
|
|
|
CLI-only — no UI palette. Logs should be scannable: step id, file index, tool name.
|
|
|
|
## Non-Goals
|
|
|
|
- Not a general photo DAM or replacement for Darktable/Immich
|
|
- Not a hosted SaaS or web upload UI
|
|
- Not real-time single-image editing — batch/resume first
|
|
- No silent API spend — log model and approximate cost hints for AI steps
|
|
|
|
## Project-Specific Rules
|
|
|
|
- **Output naming:** Modules that change extension or stem must override `expected_output_filenames` so resume/skip logic works.
|
|
- **G'MIC multi-frame:** Filters may emit `stem_000000` / `stem_000001`; use `finalize_gmic_output` — keep frame `000001`.
|
|
- **OpenRouter edits:** Optional `template_image` for style reference; preserve source dimensions/format on save.
|
|
- **Pipeline scripts:** Live in `pipelines/` with machine-local `INPUT` paths — OK to commit as examples; don't assume paths exist on other machines.
|
|
- **Dependencies:** Core is stdlib + external CLIs; AI extras via `pip install -e ".[ai]"`.
|
|
|
|
---
|
|
|
|
## Infrastructure (project-local)
|
|
|
|
| Path | Purpose |
|
|
|------|---------|
|
|
| `~/pipeline_output/` | Default run output root (`OUTPUT_BASE` in pipelines) |
|
|
| `~/pics/…/darktable_exported` | Typical input after Darktable export |
|
|
| `.env` | `OPENROUTER_API_KEY` (repo root, gitignored) |
|
|
| External tools on PATH | `magick`/`convert`, `gmic`, `rembg`; optional `torch` for local AI modules |
|
|
|
|
Downstream (not core): **Immich** on `boka` for photo library — see global `INFRASTRUCTURE.md`.
|
|
|
|
---
|
|
|
|
## Agent Instructions
|
|
|
|
When updating this file:
|
|
|
|
- Keep rules **unambiguous**
|
|
- Include **wording** for user-facing text
|
|
- Machine paths belong in **Infrastructure** above, not in global `INFRASTRUCTURE.md`
|
|
- When Fränky says *"in this project, never X"*, add it here or in `BOUNDARIES.md` (agent proposes which)
|