Technical reference / Data & methods
Saved records & storage
The trace layout, identifiers, structured records and storage implementations.
runs/
├── index.json
├── prompts/<prompt_key>.json
├── configurations/<configuration_key>.json
└── <task_id>/
├── task.json
├── proposals.json
├── votes.json
├── plan.json
└── analyses/<analysis_id>.json
Prompt and configuration keys are the first 16 hexadecimal characters of SHA-256 over canonical JSON: sorted object keys, no separator spaces, UTF-8 with non-ASCII characters retained. Array order remains significant. Task, proposal, vote, plan and analysis IDs are UUIDs.
| Record | Identity and contents |
|---|---|
| PromptReviewed E 0.1.5 | prompt_key, name, about, initial_prompt, input_elements, created_at. Only statement and input elements define the key. Metadata changes do not create a new prompt identity. |
| ConfigurationReviewed E 0.1.5 | configuration_key, sanitized effective configuration and created_at. Label is part of identity; base_files is excluded. |
| TaskReviewed E 0.1.5 | task_id, prompt/configuration keys, package/executor/trace versions, base-file provenance, status, final output/evaluation summary and creation/update timestamps. |
| Index entryReviewed E 0.1.5 | Derived summary of a task: prompt metadata, label/configuration identity, versions/status/times, recorded models/council counts, winner and analysis count/presence. It is a navigation index, not an independent source of proposal content. |
The storage reader enriches a task with its referenced prompt and configuration for rendering. The physical task.json therefore differs from the joined task dictionary used inside the report tool.
| Field | Meaning |
|---|---|
proposal_id / task_idReviewed E 0.1.5 |
Identity of this proposal and its parent execution. |
proposing_agent_idReviewed E 0.1.5 |
Role/name/slot label; trailing number is the stable agent identity used by report algorithms. |
llm_usedReviewed E 0.1.5 |
Provider/model and sanitized effective settings. |
round_numberReviewed E 0.1.5 |
Zero for independent proposals; positive refinements. |
proposal_content.stepsReviewed E 0.1.5 |
Ordered list of step_id, title, description, dependencies. Dependencies refer within the same proposal. |
proposal_content.estimated_complexityReviewed E 0.1.5 |
Model-written string. |
proposal_content.success_metricsReviewed E 0.1.5 |
Model-written string, often Markdown or an enumerated list. |
proposal_content.notesReviewed E 0.1.5 |
Historical field from the notes period; absent from the current answer model. |
source_proposal_idsReviewed E 0.1.5 |
All preceding proposal IDs supplied as context; empty for round 0. This is availability, not observed influence. |
raw_llm_prompt_text / raw_llm_response_textReviewed E 0.1.5 |
Captured exchange, with structured response serialization where applicable. |
llm_call_infoReviewed E 0.1.5 |
Usage/timing record described below. |
timestampReviewed E 0.1.5 |
Proposal record time. PostgreSQL stores the corresponding value in created_at and converts it back through the interface. |
The proposal parser validates the Pydantic shape, then replaces model step labels with UUIDs and rewrites dependencies. Unknown/self references are dropped with console notices. It does not guarantee a cycle-free graph, distinct concepts or correct content. Step UUIDs do not express continuity across rounds; the report estimates that from titles.
| Record or field | Meaning |
|---|---|
| VoteReviewed E 0.1.5 | vote_id, voting_agent_id, llm_used, voted_proposal_id, justification, raw exchange, call info and timestamp. Storage also associates it with task_id. |
| Plan identityReviewed E 0.1.5 | plan_id, task_id, plan_type (execution in this path) and created_at. The type name does not mean steps were executed. |
| Plan stepsReviewed E 0.1.5 | Copy of the selected proposal's steps. The plan record does not copy complexity and success metrics; the renderer looks those up on the winner. |
selection_metadataReviewed E 0.1.5 |
Winning proposal ID, proposing agent, votes received and total valid votes. |
| AnalysisReviewed E 0.1.5 | analysis_id, task_id, package/analyst versions, llm_used, structured content, raw exchanges, llm_calls, created_at. Every successful assessment is a separate record. |
content.versionReviewed E 0.1.5 |
Analysis schema version, separate from component version. Current structure is 5. See analysis schema. |
| Field | Definition |
|---|---|
input_tokens / output_tokens / total_tokensReviewed E 0.1.5 |
Values from LangChain's normalized provider usage metadata, or zero when absent. |
reasoning_tokensReviewed E 0.1.5 |
Reasoning detail when reported. Pricing assumes it is part of output; the logger does not reconcile the two counts. |
cached_input_tokensReviewed E 0.1.5 |
Input served from cache, used for pricing. |
cache_write_tokensReviewed E 0.1.5 |
Input recorded as cache creation, used for pricing. |
duration_secondsReviewed E 0.1.5 |
Wrapper duration rounded to one decimal; includes retry waiting on a eventually successful call. |
started_at / finished_atReviewed E 0.1.5 |
ISO timestamps with timezone in current records, to second precision. |
Analysis call callReviewed E 0.1.5 |
Stage label such as round 0, final: outcome, final: process, vote comparison, brief. |
JSON writes lists/objects directly and refreshes the shared index as tasks change. This is convenient local experiment storage, not an atomic multi-process append log. Back up a trace before manual changes or migration. Some storage methods report failures and return false; JSON proposal writes re-raise errors. Do not interpret a successful-looking console phase as proof that every file was durably written—inspect the saved records when a storage error occurred.
For PostgreSQL, use a new database with schema db/db.sql (schema 1.8, trace format 2). The adapter passes db_config to psycopg2.connect, with standard keys such as host, port, database, user, password. Keep credentials outside public task files. Connections are opened per operation.
psql -d slow_thinker -f db/db.sql
This schema creates tables; it is not an automatic upgrade of an existing older schema. Tables are prompts, configurations, tasks, plan_proposals, votes_log, plans, evolution_analyses and execution_steps_log. The last is reserved by the schema; the present planner does not execute the selected plan's actions.
Analyses are append-only at the application level. Tasks and indexes update during execution, so the entire trace should not be described as immutable. scripts/migrate_trace_1_to_2.py migrates old JSON storage in place, moves historical analysis files, removes obsolete comparison pages and rebuilds the index; back up the directory first. It cannot invent versions or usage never recorded.
An export intended for reuse should contain the task directory, its referenced prompt/configuration records, the relevant index information and the price/source revision used for interpretation. Report HTML alone is a presentation artifact; it is not the canonical JSON trace.
Source files used for this reference
Reviewed at 7361ea0b71a5.