docs/ARCHITECTURE.md

Architecture

Current State

Iris has a validated constraint engine and a custom Gradio product experience around it. The current codebase is a small Python package that calls an OpenAI-compatible MiniCPM endpoint, prints full idea spirals from a CLI harness, scores seed runs with an automated gate, and serves a Gradio interface through app.py. The current UI checkpoint is Iris UI v2 pressure studio: a focused threaded workspace with multiple idea threads, user idea cards, model-authored four-direction pressure sets, contextual iteration stacking, final brief export, and hidden default Gradio chrome.

Initial Structure

iris/     Constraint engine package
tests/    Automated tests
docs/     Project documentation and decisions
scripts/  Local maintenance and validation scripts
app.py    Gradio / Hugging Face Spaces entrypoint
stitch_iris_atomic_infinite_zoom/
          Earlier Google Stitch atomic UI export/reference

Architecture Principles

• Keep the first version small and easy to run locally.
• Prefer conventional structure for the chosen stack.
• Separate source code, tests, scripts, and docs.
• Document runtime requirements as soon as they are known.
• Keep configuration explicit and keep secrets out of Git.

Hackathon Constraints

• Preserve the local MiniCPM path for the small/offline submission story.
• Keep the custom UI clearly beyond default Gradio.
• Avoid runtime frontend CDN dependencies so the Space remains demo-resilient.
• Keep MiniCPM load-bearing: the model writes pressure, while Python validates, formats, and re-prompts.
• Build toward the screen-recordable demo moment: idea, four pressures, sharper next iteration.
• See BUILD_SMALL_FIELD_GUIDE.md for badge and submission guidance.

Engine Flow

idea + prior constraints + ring depth
  -> pressure prompt
  -> OpenAI-compatible chat completions endpoint
  -> safe JSON parser
  -> one pressure + why_it_bites
     - Ring 3 also includes a model-chosen existing alternative
  -> quality guard rejects generic, repeated, unrelated, or advice-shaped output
  -> repeat until center
  -> distill prompt
  -> model-filled actor + situation + assumption_to_test
  -> mechanical next_step formatter
  -> automated gate scores ring separation, advice language, concrete nouns,
     existing alternative, repetition, and center concreteness

UI Flow

app.py
  -> iris.ui.create_app()
  -> Gradio Blocks wrapper
  -> embedded HTML/CSS/JS pressure studio
  -> in-memory JS state tracks idea threads and card stacks
  -> New Idea creates an independent idea thread
  -> user idea card Apply Pressure calls the named Gradio API endpoint
  -> iris.ui.run_canvas_engine()
  -> original idea + current iteration + idea history + prior AI pressure
     trail become the frame memory for this call
  -> prior pressure cards also become forbidden prior pressure context
  -> IrisEngine.pressure_directions() for every open-ended UI depth
  -> response JSON returns four model pressure cards
  -> JS renders the returned pressure set and adds the next editable idea card
  -> Finalize asks the engine for a model-authored brief and next step
  -> Save PDF uses the browser's local print-to-PDF path

Four-Direction Pressure Set

For each UI depth, the app asks the engine for one pressure in each standard direction:

Constraints
Limitations
Capabilities
Reality Contact

Each direction is still authored by MiniCPM. The Python layer enforces JSON shape, direction-specific question openings, non-advice language, repeat checks, and missing-field repairs by re-prompting MiniCPM. It does not invent the pressure question or why_it_bites line.

UI iteration is intentionally open-ended. The older CLI spiral still runs the four-ring plus center validation flow, but the UI keeps asking for pressure sets as the user adds more idea cards. Short follow-up phrases are grounded by the full frame context, including the original idea and previous idea iterations plus the prior AI pressure trail. Prior model pressure cards are also passed separately as forbidden pressure context so MiniCPM can avoid repeats without treating them as examples to imitate.

The UI path fails closed for malformed JSON, advice language, or wrong direction shape. If the final retry is otherwise valid but still only fails the repeat-similarity, broad idea-grounding, or current-iteration grounding check, the UI accepts that last model-authored card so an open-ended thread keeps stacking instead of collapsing into an error card.

Configuration

• IRIS_API_BASE_URL: OpenAI-compatible base URL ending in /v1.
• IRIS_MODEL: model ID served by the endpoint.
• IRIS_API_KEY: local-only credential, never committed.
• IRIS_TIMEOUT_SECONDS: optional request timeout.
• IRIS_MAX_TOKENS: optional response token limit.
• IRIS_ENABLE_THINKING: appends /think to MiniCPM4.1 prompts for reasoning mode when supported by the backend.

Source Intake Checklist

• Runtime and version identified.
• Package manager identified.
• Install command documented.
• Run command documented.
• Test command documented.
• Build command documented, if applicable.
• Deployment target documented, if known.