solution-factory

A corpus-grounded, adversarially-reviewed architect for agentic AI pipelines, built on LangGraph. You describe a problem in plain English; it runs a Socratic intake, designs a solution grounded in a curated knowledge corpus, tears that design apart with an independent critic panel until no blocking objections remain, and hands you an approved build spec. Two human approval gates bracket the autonomous work.

Plain-English brief → Socratic intake (GATE 1) → corpus-grounded architect → adversarial critique loop → consensus → build spec (GATE 2).

What this is for. It produces architectural reference — a reasoned design and build spec for an agentic system, with citations and flagged gaps. It is not a code generator and it does not deploy anything. Treat its output as a senior architect's proposal you still own and review.

Why it is built this way

• Adversarial separation. The architect that designs a solution never grades its own work. Critique runs as a separate subgraph with private state — a panel of persona critics whose only job is to find blockers. Consensus is concrete: zero open BLOCKER findings, not a vibe.
• Durable by construction. A Postgres checkpointer persists every step. The two human gates are durable interrupts — you can start a run in one terminal and approve it from another process, a cron job, or days later. Crash recovery is just rerunning the same thread id.
• Grounded, with honest gaps. The architect grounds claims in a curated atom corpus and cites them as [[kind:slug]]. When the corpus does not cover something, it says so and falls back to web/docs, tagging the provenance instead of bluffing.
• A real ledger. Markdown artifacts are the source of truth, written first; structured rows are dual-written to a Postgres ledger at each phase boundary and reconciled against the artifacts. The ledger is a rebuildable projection, never the only copy.

See docs/SYSTEM-SPEC.md for the full architecture (typed state, critique subgraph, persistence, observability, evals) and ROADMAP.md for the staged build and locked design decisions.

The seed corpus

This repo bundles a small seed corpus of agentic-engineering knowledge atoms under data/brain/atoms/agentic/ (markdown files with structured frontmatter), queried by the read-only helpers in tools/brain-query/.

Provenance and ownership. The seed atoms summarize techniques and ideas gathered autonomously from publicly available sources. Upswing Solutions claims no ownership of the underlying ideas, tools, or intellectual property they describe. The corpus is provided for architectural reference only — a starting point so the architect grounds out of the box. It is a small, curated sample, not an exhaustive or authoritative dataset.

Bring your own. Point the CORPUS_HOST environment variable at any other checkout that follows the same layout (data/brain/atoms/agentic/<kind>/*.md + tools/brain-query/) to ground the architect against your own vault instead of the seed.

LLM transport — hybrid

Two transports, on purpose:

• Critic panel + cheap routing/selection calls go through headless Claude Code (claude -p), billing a flat-rate Claude subscription.
• The architect + reviser go through the native Anthropic API (langchain-anthropic), billed to a separate metered key.

Billing invariant (load-bearing). Never set the global ANTHROPIC_API_KEY env var — it flips the whole process (the claude -p critics included) onto metered billing. The metered key lives under its own name, ANTHROPIC_API_KEY_SF, and is passed explicitly to the architect. See .env.example.

You can also run the whole thing on metered API billing if you prefer; the split is an optimization, not a requirement.

Requirements

• Python ≥ 3.12 and uv
• PostgreSQL (local is fine) for the checkpointer + ledger
• bun for the corpus query helpers and the ledger recorder
• Claude Code on PATH if you use the hybrid transport

Quickstart

git clone https://github.com/upswing-solutions/solution-factory.git
cd solution-factory
uv sync
cp .env.example .env            # then fill in ANTHROPIC_API_KEY_SF

# one-time database + ledger setup
createdb factory_ckpt
createdb solution_factory_lg
psql solution_factory_lg -f tools/sf-ledger/schema.sql
(cd tools/sf-ledger && bun add pg)
(cd tools/brain-query && bun install)

Run — full pipeline (plain-English brief → approved build spec)

# 1. start from a brief; pauses at the intake questions
uv run python -m factory.run --brief briefs/sample-intake-triage.md --thread t1 --critics real

# 2. drive the interrupts from any process via the driver CLI
uv run python -m factory.driver list
uv run python -m factory.driver resume --thread t1 --answers "<answers to the intake questions>"
uv run python -m factory.driver resume --thread t1 --decision approved        # GATE 1
#    ... architect + critique loop run autonomously ...
uv run python -m factory.driver resume --thread t1 --decision accept_risk     # if it caps at escalation
uv run python -m factory.driver resume --thread t1 --decision approved        # GATE 2 -> build spec

# reconcile the ledger against the artifacts, then evaluate
uv run python -m factory.reconcile --thread t1
uv run python -m factory.evals --threads t1

Run — review-only (fixture schematic, no intake)

createdb factory_ckpt   # once
# adversarial-review run on a fixture schematic:
uv run python -m factory.run --schematic fixtures/SCHEMATIC.md --thread t1 --critics real
# paused at the escalation interrupt? resume from ANY process:
uv run python -m factory.run --thread t1 --resume accept-risk   # | revise-anyway | abandon
# crash recovery: rerun with the same --thread

Browser surface (LangGraph Studio)

uv run langgraph dev      # watch the graph execute node by node, answer each gate in the UI

The CLI and Studio drive the same graph but do not share runs (Studio uses the dev server's own persistence). See docs/SYSTEM-SPEC.md §6.

Configuration

Variable	Default	Purpose
ANTHROPIC_API_KEY_SF	—	Metered key for the architect + reviser. Never name it ANTHROPIC_API_KEY.
FACTORY_CKPT_DSN	postgresql:///factory_ckpt	LangGraph checkpointer (opaque persistence).
SF_DATABASE_URL	postgresql:///solution_factory_lg	The ledger projection.
CORPUS_HOST	this repo	Point at an external vault following the same layout to ground against your own corpus.
FACTORY_MODEL	haiku	Critic-panel model.
FACTORY_REVISE_MODEL	sonnet	Reviser model.
LANGSMITH_API_KEY / LANGSMITH_TRACING / LANGSMITH_PROJECT	—	Optional LangSmith tracing (with on-the-wire redaction).

Repository layout

factory/          # the LangGraph package: graph, typed state, stage nodes, critique subgraph
personas/         # critic/architect persona prompt templates
tools/brain-query/ # read-only corpus retrieval helpers (by-domain, semantic), vendored
tools/sf-ledger/  # ledger schema.sql + record/query (TypeScript)
data/brain/atoms/agentic/  # the bundled seed corpus (architectural-reference atoms)
briefs/           # sample intake briefs
fixtures/         # regression fixtures for review-only runs
docs/SYSTEM-SPEC.md  # full architecture + runbook
ROADMAP.md        # staged build plan + locked decisions

Contributing

See CONTRIBUTING.md. Issues and PRs welcome.

License

Apache License 2.0. Copyright 2026 Upswing Solutions. See NOTICE for attribution, including the seed-corpus provenance statement.