Files

T

Frank Schwenk 1c36fc1968 docs: add RECIPES.md declarative pipeline recipes

Catalog of single-step and composite/pipeline recipes for agents to
expand into pipelines, with human notes, recipe inclusion, and xcf_stack.

Co-authored-by: Cursor <cursoragent@cursor.com>

2026-07-12 11:32:01 +02:00

4.3 KiB

Raw Permalink Blame History

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.
Recipes: Declarative pipeline building blocks in RECIPES.md — load via @RECIPES.md when creating or editing pipelines.
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)

4.3 KiB Raw Permalink Blame History