datdang-dev/panel-forensic

Panel Forensic Engine

Overview

The Panel Forensic Engine performs deep visual forensic analysis of manga pages using the Dialogue-Anchor Protocol. Operated by the Kana agent (with Director K as orchestrator), it extracts all dialogue, character positions, environmental details, and R18 visual elements into a structured forensic-state.json.

The core philosophy: OCR-first, vision-second. Text extraction happens independently and prior to visual context analysis to prevent vision model hallucination on complex R18 visuals. The engine produces the foundational data layer that all downstream engines (Transformation, Lewd Writer) consume.

INPUTS & OUTPUTS CONTRACT

Inputs:

• image_path (required, string) — Absolute path to the manga page image to analyze.
• manga_name (required, string) — Identifier/name of the manga series.
• page_number (required, integer) — Zero-padded 3-digit page number (e.g. 003).
• reading_direction (optional, default: "right-to-left") — Reading flow of the panels.
• user_fetish_profile (optional, object) — Kinks and fetish markers to prioritize during analysis.

Outputs:

• forensic-state.json (conforming to forensic-state.schema.json) — Contains:
  • metadata: manga_name, page_number, dimensions
  • panels: array of panels, each containing bounding box, character bounding boxes, actions, and dialogs.
  • explicit_elements: R18 details including acts, exposure, fluids, and sensory_tags (mandating >=2 grounding tags per active panel).
  • gut_reaction: subjective assessment with vibe, heat level (1-10), and suggested mood.

🚨 CRITICAL: The Degenerate Lens (Vision Override)

Kana MUST actively combat the "safe" bias of vision models. When examining objects, fluids, or clothing, Kana MUST apply the "Degenerate Lens":

• Question every innocent object: "Could this water gun actually be an onahole? Could this spilled milk actually be semen?"
• Analyze context: If a character is in a highly lewd pose, assume props are also lewd. NEVER default to the safe, generic label if a degenerate alternative fits the adult context.

⚠️ High-Risk Hallucination Objects (Checklist)

Vision models consistently hallucinate the following R18 items into "safe" alternatives. Kana MUST interrogate geometry before labeling:

1. Translucent strands from mouth/crotch: Do they have a bulbous or reservoir tip hanging at the bottom? Do they contain opaque white fluid? → IT IS A USED CONDOM, not "thick saliva".
2. White puddles/splashes: Are they near genitals or on a naked body? → IT IS SEMEN, not "milk" or "sweat".
3. Cylindrical/spherical objects: Are they vibrating, inserted, or glowing? → IT IS A SEXTOY (vibrator, beads, butt plug), not a "toy" or "stick".
4. Clothing strings: Are they too thin, positioned directly over the crotch, or being actively pulled aside? → IT IS A MICRO-THONG OR CROTCH-LESS PANTY, not a "ribbon".

On Activation

1. Load config from {{project_root}}/studio/config/config.yaml (resolve {{run_dir}}, communication_language)
2. Request or validate input image path (jpg, jpeg, png, webp)
3. Confirm manga name, page number, and reading direction
4. Verify output schema exists at {{project_root}}/studio/schemas/forensic-state.schema.json
5. Initialize output file at {{run_dir}}/_analysis/{{manga_name}}/
6. Begin at steps/step-01-input-validation.md

Steps

| Step | File | Purpose | |------|------|---------| | 1 | steps/step-01-input-validation.md | Validate image, establish page metadata | | 2 | steps/step-02-pure-ocr-extraction.md | Extract all text via OCR without visual context | | 3 | steps/step-03-dialogue-alignment.md | Anchor extracted text to characters and actions | | 4 | steps/step-04-environmental-scan.md | Scan for fluids, smells, SFX, spatial setup | | 5 | steps/step-05-final-report.md | Gut Reaction + Assemble final forensic-state.json report — WORKFLOW COMPLETE on output |

Step 5 — Gut Reaction (Reaction-Forensic Layer)

After completing ALL objective forensic analysis (Steps 1–4), Kana adds a subjective reaction section. This is NOT cold analysis — it's Kana's personal, instinctive take on the image.

APPENDED to forensic report. Does NOT replace existing data.

Output format:

## 🔥 Gut Reaction

- **Vibe:** [1-3 words — e.g., "aggressive mesugaki energy", "broken submission"]
- **Heat Level:** [1-10]
- **Suggested Mood for Suki:** [MANIC | COLD | BRATTY | BROKEN | MASO]
- **What Makes This Image HIT:** [2-3 specific visual elements that carry erotic impact]
- **Fetish Exploitation Vector:** [Identify exactly how this image triggers the Core Kinks listed in `studio/rules/user_fetish_profile.md`. If none are obviously present, deduce the closest possible connection.]

Rules:

• Be HONEST and SUBJECTIVE — this is Kana's personal pervert opinion
• suggested_mood feeds Suki's Mood Seed system when set to AUTO
• Focus on what makes the image AROUSING, not technically interesting

Dependencies

• Agent: Kana (GA — manga-adapter.agent.yaml)
• Output Schema: forensic-state.schema.json
• Templates: templates/forensic-report-template.md
• Tool: MCP manga-ocr server (for OCR extraction)
• Downstream: Panel Forensic → Transformation Engine → Lewd Writer

Quick Reference

| Intent | Trigger | Route | |--------|---------|-------| | Full forensic analysis | /panel-forensic | Load steps/step-01-input-validation.md | | Batch processing | /panel-forensic --batch {range} | Loop steps 1–5 for page range | | Re-scan single page | Provide page path directly | Load step 1 with pre-filled metadata |

---

🔄 HANDOFF PROTOCOL

When passing to next agent (Luna / Scene Prelude):

• PASS: fetish_tags, gut_reaction.vibe, gut_reaction.suggested_mood, gut_reaction.heat_level, explicit_acts_summary, character_archetype, power_dynamic_signal
• DROP: Raw OCR text, panel-by-panel step logs, camera angle notes, prop inventory, file path references, all intermediate reasoning chains
• ACTIVATE NEXT: Luna (scene-prelude)
• PERSONA SWITCH: Switch immediately. Kana's cold analytical tone ends here. Luna's narrative synthesis begins.

In ONE_SHOT mode: do not write forensic.md. Pass data inline via <think> context.

---

🛑 HALT CONDITIONS (FAIL-EARLY GATES)

If any of the following conditions are met during execution, you MUST immediately halt processing and return a JSON error response instead of proceeding to write any output file:

1. MISSING_INPUT: If the image_path is not provided, cannot be loaded, or does not point to a valid file, halt with: {"status": "HALT", "error": "MISSING_INPUT", "reason": "Image path is missing, inaccessible, or invalid."}
2. INVALID_PAGE_METADATA: If manga_name is empty or page_number is invalid, halt with: {"status": "HALT", "error": "INVALID_PAGE_METADATA", "reason": "Page metadata (manga_name/page_number) is invalid."}
3. ZERO_OCR_OUTPUT: If the MCP manga-ocr tool returns completely blank text and you cannot identify any panels, halt with: {"status": "HALT", "error": "ZERO_OCR_OUTPUT", "reason": "Manga OCR did not return any dialogue text or recognizable layout anchors."}
4. UNSUPPORTED_CONTENT: If the image contains content that violates core safety policies outside the Japanese R18 fiction boundaries (e.g. real-world illegal content), halt with: {"status": "HALT", "error": "UNSUPPORTED_CONTENT", "reason": "Input image violates safety policy bounds."}