imagepipeline/SOUL.md

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)