Technical reference / System & configuration

Technical reference

The components, execution boundaries and data flow behind an experiment and its reports.

Reviewed 2026-09-21Process executor 0.1.5 · Analysis generator 0.1.4 · Report generator 0.1.16

Architecture and data flow

Documented in E 0.1.5 · A 0.1.4 · R 0.1.16

The implementation separates collaboration, persistence, post-run analysis and presentation. Configuration supplies the council and storage; the task supplies the challenge. The executor records its output. The optional analyst reads that trace and stores a separate assessment. The renderer reads both and computes additional views without changing the experiment.

PROMPTCONFIGURATION

↓

Process executorPropose → refine → vote → select

planner/

↓ persist

↳

Saved run traceProposals · votes · selected plan · call metadata

storage/

↓

Analysis generatorOPTIONAL ANALYSISReads the trace; saves its assessment

↓ saved analysis

Original trace↓

Report generatorComputed views + optional analyst interpretation

report/

↓

INTERACTIVE HTML REPORTS

Component	Responsibility
`__main__.py`Reviewed E 0.1.5 · A 0.1.4 · R 0.1.16	Parse a task path and optional base, load configuration, register/run the case, and optionally render reports afterwards.
`planner/config.py`Reviewed E 0.1.5 · A 0.1.4 · R 0.1.16	Resolve base chains and API keys, describe the effective configuration and populate planner module globals.
`planner/graph.py`Reviewed E 0.1.5 · A 0.1.4 · R 0.1.16	LangGraph orchestration: initial proposals, repeated refinements, voting, selection and error routing.
`planner/calls.py`Reviewed E 0.1.5 · A 0.1.4 · R 0.1.16	Build stage prompts, invoke providers, retry transient failures and collect raw exchanges and usage.
`planner/models.py`Reviewed E 0.1.5 · A 0.1.4 · R 0.1.16	Pydantic answer models, strict JSON schema conversion, parsing, step UUID assignment and context formatting.
`prompts/`Reviewed E 0.1.5 · A 0.1.4 · R 0.1.16	Source-controlled execution, analysis and writing-style templates. They are not loaded from a generic process-definition JSON.
`llm/`Reviewed E 0.1.5 · A 0.1.4 · R 0.1.16	Provider registry and adapters for client construction, effective settings, structured output and pricing rules.
`storage/`Reviewed E 0.1.5 · A 0.1.4 · R 0.1.16	Common record builders and Storage interface with JSON and PostgreSQL implementations.
`report/analysis.py`Reviewed E 0.1.5 · A 0.1.4 · R 0.1.16	Analysis models, prompt assembly, parallel round calls and sequential final evaluation stages.
`report/diff.py` / `contributions.py`Reviewed E 0.1.5 · A 0.1.4 · R 0.1.16	Deterministic title comparisons, immediate origins, recursive introducers, composition and convergence.
`report/graph.py` / `process.py`Reviewed E 0.1.5 · A 0.1.4 · R 0.1.16	Geometry and evidence for dependency and collaboration diagrams.
`report/usage.py` / `render.py`Reviewed E 0.1.5 · A 0.1.4 · R 0.1.16	Usage aggregation, presentation view models and HTML rendering.
`report/templates/`Reviewed E 0.1.5 · A 0.1.4 · R 0.1.16	Self-contained HTML/CSS/JavaScript and SVG markup for reports and history pages.

Execution boundaries

Documented in E 0.1.5 · A 0.1.4 · R 0.1.16

The LangGraph state holds the task ID and prompt, input elements, current round, proposal lists per round, final alternatives, votes, selected proposal and status/error messages. asyncio.gather parallelizes calls inside a stage; the graph waits at each stage boundary. Results are processed in configured slot order.

Each model invocation is a new prompt, not a persistent per-agent chat. Refinement context includes the immediately preceding round, not the full transcript of every earlier round. The reporting layer reconstructs longer lineage afterwards. source_proposal_ids records which proposals were made available, not which ones causally influenced the answer.

Configuration is held in module globals, so the current package is designed around one configured planning run per process. Treat a service supporting concurrent, independently configured runs as an integration change, not as a capability implied by asynchronous agent calls.

Structured output and failure handling

Documented in E 0.1.5 · A 0.1.4 · R 0.1.16

strict_json_schema() removes defaults, flattens references, makes object properties required and disallows extra properties for provider schema requests. Most adapters request json_schema; DeepSeek requests JSON mode and appends the schema to the human prompt. Responses are then parsed and validated locally.

The executor checks structural shape, not whether a plan is factually correct, complete or acyclic. Unknown/self dependency labels are dropped when UUIDs are assigned. Other cycles can remain and are flagged by the report layout. estimated_complexity is a string, not a validated enum or computed measure.

The wrapper retries up to three attempts for HTTP 408, 429, 500, 502, 503, 504 and 529, and for exceptions without an integer status. Other status codes fail immediately. Its waits are one then two seconds. Raw errors are converted to an ERROR_ response for callers; failed or invalid proposal/vote results are skipped. Provider SDK retries can occur underneath this wrapper.

Reference map

Documented in E 0.1.5 · A 0.1.4 · R 0.1.16

Topic	Reference
Inputs and merge behaviorReviewed E 0.1.5 · A 0.1.4 · R 0.1.16	Configuration and provider adapters.
Persistent identity and recordsReviewed E 0.1.5 · A 0.1.4 · R 0.1.16	Data model.
Interpretation calls and answer fieldsReviewed E 0.1.5 · A 0.1.4 · R 0.1.16	Analysis pipeline.
Title matching and all count definitionsReviewed E 0.1.5 · A 0.1.4 · R 0.1.16	Attribution methods.
Cost estimationReviewed E 0.1.5 · A 0.1.4 · R 0.1.16	Pricing methods.
Graph layout, indexes and renderingReviewed E 0.1.5 · A 0.1.4 · R 0.1.16	Report rendering.
Evolving the experimentReviewed E 0.1.5 · A 0.1.4 · R 0.1.16	Extension points.
Historical behaviorReviewed E 0.1.5 · A 0.1.4 · R 0.1.16	Versions and changelog.

Source files used for this reference

Reviewed at 7361ea0b71a5.

← Documentation home Find a report element →