Add Krea2 evaluation loop

docs/krea2-prompt-guide.md

@@ -0,0 +1,150 @@
+# Krea2 Prompt Guide
+
+This document records prompt rules discovered from actual SxCP generator
+outputs tested in Krea2. It is not a generic prompt cookbook. Add a rule only
+when an A/B image comparison shows that the wording improves or breaks Krea2
+behavior.
+
+## Core Rule
+
+Krea2 responds best when the prompt gives one clear visual hierarchy:
+
+1. subject/cast descriptor,
+2. action or pose,
+3. clothing state,
+4. location,
+5. camera/layout,
+6. expression,
+7. composition/crop,
+8. style.
+
+Avoid letting two sections describe incompatible camera or framing intents.
+
+## Prompt Output Contract
+
+- `sxcp_eval_out` must contain only the prompt being tested.
+- Analysis, scoring, and generator notes belong in chat or `sxcp_eval_log`.
+- Keep one experiment variable per cycle when possible.
+- Lock seed, character, location, and camera when testing wording changes.
+
+## Camera And Composition
+
+### Orbit / Multiangle Camera
+
+When Krea2 receives an orbit or multiangle camera, avoid selfie-specific wording
+unless the intended camera is actually a handheld or mirror selfie.
+
+Works better:
+
+- `lifestyle portrait frame`
+- `creator portrait frame`
+- `outfit-check pose`
+- `wide environmental coworking camera layout`
+- `camera placed several meters away`
+- `full seated body from head to knees`
+- `room depth surrounding the subject`
+
+Conflicting wording:
+
+- `selfie frame`
+- `phone selfie`
+- `holding the phone`
+- `creator-shot phone photo`
+- `handheld camera realism`
+
+Observed result: selfie words pulled a back-right elevated wide shot into an
+arm-length selfie. Removing selfie terms made the image follow the rear-quarter
+view much better.
+
+### Wide Shots
+
+Krea2 tends to keep attractive subjects large in frame. To get a real wide or
+environmental frame, be explicit about distance and visible environment.
+
+Useful phrasing:
+
+- `camera placed several meters away across the desk aisle`
+- `full seated body from head to knees remains visible`
+- `nearby desk edge, laptop corner, repeated desk rows, and tall-window depth clearly readable`
+- `wide environmental room framing`
+
+Avoid relying on `wide shot` alone.
+
+## Location Layout
+
+Location-aware camera text works when it describes the room around the subject
+without stealing the foreground from the subject.
+
+For coworking lounge:
+
+- Keep `warm desks`, `laptop tables`, `glass partition seams`, `repeated desk rows`,
+  `plants`, and `tall windows`.
+- Mention foreground anchors only when the camera should actually see them.
+- In POV, keep location anchors beside or behind the bodies, not in the lower
+  foreground.
+
+## Clothing Continuity
+
+When a softcore outfit is reused in a later branch, name what happens to actual
+outfit pieces instead of using generic fabric language.
+
+Works better:
+
+- `denim shorts are pulled aside or removed below the hips`
+- `button-down shirt tied at the waist and fitted bralette remain visible from the same outfit`
+
+Avoid generic fallback wording:
+
+- `fabric slipping off`
+- `partly exposed`
+- `outfit pushed aside where needed`
+
+Use generic wording only when no source outfit exists.
+
+## POV
+
+In POV prompts, the visible subject should still be established first. The POV
+participant is the camera viewpoint, not a normal visible cast member.
+
+Works better:
+
+- visible subject descriptor first,
+- then POV action,
+- then foreground hands/body/clothing cues.
+
+For POV clothing, describe only visible body/clothing fragments:
+
+- `foreground hands, hips, thighs, or lowered waistband`
+- `foreground hands, forearms, sleeves, or torso edge`
+
+Avoid:
+
+- full third-person `Man A wears...` phrasing for the POV participant,
+- making `the viewer` the first subject before the visible character is
+  established.
+
+## Style
+
+Style should describe rendering, not camera mechanics.
+
+Use style presets to choose between:
+
+- natural photo,
+- creator/social-media photo,
+- documentary/direct-flash photo,
+- cinematic realism,
+- illustration/comic.
+
+If a controlled camera is active, avoid style suffixes that imply a conflicting
+camera such as `phone photo` or `handheld selfie`.
+
+## Guide Update Format
+
+When adding a new rule, include:
+
+- observed prompt,
+- observed image failure,
+- edited prompt wording,
+- image improvement or regression,
+- generator path if known,
+- final rule.

docs/sxcp-eval-loop.md

@@ -0,0 +1,77 @@
+# SxCP Eval Loop
+
+This loop is for tuning the SxCP generator toward stronger Krea2 images.
+ComfyUI sends a generated prompt and image to Codex, Codex analyzes the result,
+then sends back exactly one edited prompt for the next A/B test. Confirmed
+findings become either generator changes or durable prompt rules in
+[`krea2-prompt-guide.md`](krea2-prompt-guide.md).
+
+## Channels
+
+- `sxcp_eval_in`: ComfyUI to Codex. Contains the prompt text and image path.
+- `sxcp_eval_out`: Codex to ComfyUI. Prompt-only. Do not put analysis here.
+- `sxcp_eval_log`: optional analysis/log channel.
+
+## Manual Loop
+
+Start the helper after sending a test prompt:
+
+```bash
+tools/sxcp_eval_loop.sh 3
+```
+
+Every three minutes it prints a structured request asking Codex to:
+
+1. Pull `sxcp_eval_in`.
+2. Inspect the image.
+3. Compare it to the prompt and previous edit.
+4. Push one prompt-only edit to `sxcp_eval_out`.
+5. Classify the finding as prompt-only, prompt-guide rule, or generator fix.
+6. Change generator code/data only when the issue is systemic.
+7. Record the finding and update the Krea2 prompt guide when a rule is confirmed.
+
+Runtime logs are written under `.sxcp_eval/` and ignored by git.
+
+## Optional Command Hook
+
+If you have a one-shot Codex command you want to run automatically, set:
+
+```bash
+SXCP_EVAL_CODEX_CMD="codex exec" tools/sxcp_eval_loop.sh 3
+```
+
+The request is sent on stdin. The command also receives:
+
+- `SXCP_EVAL_IN_CHANNEL`
+- `SXCP_EVAL_OUT_CHANNEL`
+- `SXCP_EVAL_LOG_CHANNEL`
+- `SXCP_EVAL_GUIDE_FILE`
+- `SXCP_EVAL_REQUEST_FILE`
+- `SXCP_EVAL_CYCLE_DIR`
+- `SXCP_EVAL_CYCLE`
+
+## Evaluation Axes
+
+- Identity consistency
+- Outfit continuity
+- Pose/action accuracy
+- Camera compliance
+- Location coherence
+- Crop/framing
+- Prompt noise/repetition
+- Model confusion tokens
+- Overall Krea2 image usefulness
+
+## Generator Fix Rule
+
+Only edit the generator when the image shows a repeatable, systemic prompt
+failure. Examples:
+
+- Selfie wording overrides orbit camera.
+- Clothing continuity loses the selected softcore outfit.
+- POV wording makes the off-camera participant the visual subject.
+- Location camera layout inserts foreground anchors in the wrong place.
+
+For one-off model drift, send a cleaner prompt to `sxcp_eval_out` and keep the
+generator unchanged. For repeated prompt behavior, update the generator and add
+the rule to `docs/krea2-prompt-guide.md`.