# 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)