437 Param Forge Reference Bb2e5ad1

# Param Forge reference notes (for Brood)

Note: The original Param Forge snapshot is no longer shipped in this repo. This file preserves compatibility notes from that historical reference.

This doc records the Param Forge receipt schema and loop patterns to mirror. These notes were extracted from the archived Param Forge code/docs (`forge_image_api/*`, `param_forge.py`, and supporting docs).

## Receipt schema (Param Forge)
Defined in historical Param Forge sources `forge_image_api/core/receipts.py` and `core/contracts.py`.

Top-level keys (schema_version = 1):
- `schema_version` (int)
- `request` (ImageRequest serialized)
  - prompt, mode, size, n, seed, output_format, background
  - inputs (init_image, mask, reference_images)
  - provider, provider_options, user, out_dir, stream, partial_images, model
  - metadata (free-form)
- `resolved` (ResolvedRequest serialized)
  - provider, model, size, width, height, output_format, background, seed, n
  - user, prompt, inputs, stream, partial_images
  - provider_params (provider-specific resolved params)
  - warnings
- `provider_request` (sanitized provider payload)
- `provider_response` (sanitized provider payload)
- `warnings` (list of strings)
- `artifacts`
  - image_path
  - receipt_path
- `result_metadata` (free-form; expanded post-run)

Observed `result_metadata` fields from Param Forge:
- `render_seconds` (float)
- `render_started_at` / `render_completed_at` (ISO strings; documented in `docs/llm_review_context.md`)
- `llm_scores` (object: adherence, quality, model, version)
- `llm_retrieval` (object: score, axes, packet, model, gated, gate_reasons)
- `image_quality_metrics` (object: metrics, gates, version)

Notes:
- Provider request/response are sanitized to omit raw image bytes.
- Receipts are immutable in intent, but Param Forge appends metadata fields after generation.

## Loop patterns to mirror

### 1) Interactive optimize loop (core UX)
Pattern in `scripts/param_forge.py`:
- Collect provider/model/size/params and prompt.
- Generate images + receipts.
- Post-run analysis (optional): LLM-based receipt analysis recommends param changes.
- Show diffs (settings + prompt) between current and recommended.
- User accepts or rejects recommendations; repeat if accepted.

Loop shape: `generate -> evaluate -> recommend -> accept -> regenerate`.

### 2) Batch run (plan -> execute -> resume)
Pattern in `docs/experiment_mode_spec.md`:
- Build a plan from prompts + matrix + limits.
- Write a run manifest (run.json) before execution.
- Execute with concurrency + budget enforcement.
- Resume by skipping completed jobs.

Loop shape: `plan -> execute -> summarize -> resume if needed`.

### 3) Viewer & winner selection
Pattern in `param_forge.py view`:
- Load receipts + manifest.
- Render grid, enable compare, winner pick, and copy snippet.
- Use receipts as the source of truth for prompt + params.

Loop shape: `browse -> compare -> select winner -> copy/branch`.

These patterns inform Brood's receipt-driven event stream, iterative agent loops, and deterministic versioning.