Research workflow

A durable job, not a browser calculation

Creating research stores a job in PostgreSQL with validated input and a snapshot of the active runtime configuration. A separate worker claims the job and executes a server-side LangGraph workflow. Closing a tab does not itself cancel the job.

Browser → owner-scoped API → PostgreSQL job
                                  ↓
                         Worker + graph execution
                                  ↓
                     Evidence, report, gates, events
                                  ↓
                       Browser / PDF download

Collect evidence

Source tools resolve the address and collect enabled building, grid, solar and official-guidance records. Solar estimates and historical roof models are collected when relevant, rather than manufactured for every project.

Transient source failures are explicitly recorded. The graph can retry collection within its configured retry limit and remaining budget before calling the writer. Missing evidence stays missing if retries do not resolve it.

Write the report

The simplified workflow asks one report writer to analyze the project and evidence directly. It returns seven keyed report sections plus structured claims, options and operator questions. Code assigns section identities from the contract rather than asking the model to invent them.

The writer must keep numeric units, exact sentence text and claim-level references consistent. User assumptions are not source findings. Public source text is untrusted input, not permission to follow embedded instructions.

Review independently

The independent reviewer evaluates bounded batches of four sentences. Code supplies stable evaluation slots and reattaches the authoritative sentence, section and references to the result.

Recognized pure questions and narrow disclosures have separate checks. Unfamiliar prose is still sent for independent classification: factual, question, recommendation or disclaimer. A missing writer claim receives an empty-reference slot, not a borrowed section-wide source list. If it is factual, the omission still blocks publication as a validated report.

Apply gates and repair

Deterministic gates run alongside the semantic review. With retries enabled, the simplified workflow allows at most one report repair followed by fresh review and checks. It does not keep rewriting indefinitely until a model says “supported.”

The final candidate and gate results are saved even when blocked. A provider failure during an optional repair can retain the previous checked candidate as blocked; it does not authorize release of unreviewed prose.

Progress, cancellation and historical runs

Progress comes from persisted events, not a timer pretending to know which agent is working. The browser consumes server-sent events and can retrieve saved run state when streaming is unavailable. Cancellation is checked by the worker and propagated through abort signals.

Workers use renewable leases, and graph state is checkpointed in PostgreSQL. Do not stop an actively executing worker merely to reload code; drain work first and inspect failed or expired jobs before restarting.

Older snapshots without the simplified workflow setting retain the legacy graph path. Publishing new prompts does not edit an earlier run’s saved input, configuration or report. See Configuration and security.