DEV Community: Bogdan

We stopped drawing graphs: an event-driven runtime for agents

Bogdan — Tue, 22 Sep 2026 14:27:29 +0000

TL;DR — Most agent frameworks ask you to draw a graph. A knowledge question
doesn't have a fixed path, and you can't ship an answer you can't audit. We built
reactifact: think Celery, but tasks wake on typed artifacts, not messages.
It's pip install reactifact, 3 core deps, and a run you can reproduce.

We kept drawing graphs we couldn't finish

We were building a devops knowledge assistant. Ask it a real question —
"why did our infra costs jump in Q2?" — and answering it needs a Confluence
page, two GitLab MRs, a CSV of cloud costs, some arithmetic, a verification step,
and maybe a follow-up question. The next question needs a different subset of
all that.

Every framework we tried asked us to draw that path: nodes, edges,
conditional routing, a shared state dict. But there is no universal graph. The
path depends on the question and on the data. Encoding every combination as edges
turned into a wiring exercise — and the framework still couldn't tell us why it
produced the answer it produced.

So we stopped describing execution and described state instead.

The idea: state is primary, execution is derived

Instead of "node A then node B", you declare:

what artifacts exist — typed objects like Question, Evidence, Claim, Calculation, Answer;
what each agent consumes and produces — Consume(Evidence), produces=Answer.

The runtime looks at what just changed and derives what runs next. Nothing calls
anything. There is no graph to draw — the schedule is a function of state.

If you know Celery, you already know the model:

Celery	reactifact
a task	`@produce(Model)`
`delay()` / `apply_async()`	you don't call it — creating the input artifact is the trigger
routing key / queue	`Consume(Type)`
chain / group / chord	several `consumes` / `produces`; the runtime derives the order
retries, `acks_late`	guards + `Budget`, an honest `None` instead of a wrong result
result backend	the `Context` — typed, versioned artifacts
worker	`Runtime`

Single process today (no broker, no worker pool) — it's a Celery-shaped model,
not its distributed runtime.

The second thing we couldn't get: an answer you can audit

The other half of the problem is trust. An LLM writes confident prose and
unreliable arithmetic, and most frameworks leave "who computed this number, from
which source?" to whatever logs you remembered to add.

In reactifact, the answer is an artifact like everything else:

Calculations are computed, not generated. A Produce doing arithmetic over a CSV computes it in plain Python and hands the model the result to explain — never the raw numbers to guess from.
Every derived artifact links to its inputs — Answer —supported_by→ Variance —calculated_from→ Spend, Table. That's a queryable graph, not a log line.
A run is reproducible. Artifacts are versioned, and a content hash (context_hash) is identical across deterministic runs, so you can re-run and verify: reactifact replay <store> --session <id> --verify <hash>.
The audit is a report. reactifact.audit renders the answer with a sha256 per artifact, its producing author, and the provenance edges.

Proof, offline, in one command

examples/fintech_audit answers a finance question — "what's the Q2 cloud spend
variance, and does policy require approval?" — from a transactions CSV, a budget
CSV, and a policy document. No API key, nothing leaves the machine:

$ python -m examples.fintech_audit.main   # from a repo checkout, no API key

variance vs budget: +12.5%   ($45,000 actual vs $40,000 budget, 10% policy threshold → over)
answer:  Q2 cloud spend was $45,000 against a $40,000 budget (+12.5%) —
         exceeds the 10% policy threshold. CFO approval is required.
audit:   Answer —supported_by→ {Variance, Spend, Table, Policy}
         answer sha256 5461290d…  ·  context sha256 24449f6f…

Run it twice: the hash is the same. Change a fact, and only what actually
consumed it recomputes — because Artifact.version tracks real reads, not a
graph edge someone drew by hand.

The number is computed, and its provenance recorded, in plain Python (trimmed
from examples/fintech_audit/produce.py):

@produce(Variance, reacts_to=Spend)              # wakes when a Spend artifact exists
async def compute_variance(call: ProduceCall) -> None:
    spend = call.trigger                         # the artifact that triggered this run
    budget = cloud_budget(call.context)          # read from budget.csv
    pct = (spend.data.total - budget) / budget   # deterministic — never the model
    variance = call.effects.create_once_from(
        spend,                                   # stable id → idempotent re-runs
        Variance(actual=spend.data.total, budget=budget, pct=pct,
                 threshold=0.10, within_policy=abs(pct) <= 0.10),
    )
    variance.link("calculated_from", spend)      # provenance edge, queryable

What you get beyond the model

A task queue gives you execution. Layering state, versions, and provenance on top
of the type system gives you a few things for free:

Determinism where it matters — compute in code, let the model reason.
Branching and merge — fork an exploration, run different agents on each fork, three-way merge() with an explicit conflict instead of silent last-write-wins.
Human-in-the-loop as state — effects.ask(...) is just another effect; a human is another reaction, not a special case.
Replay — reproduce a past run from its recorded model calls and commit chain, offline.
MCP both ways — call any MCP server's tools, or expose your own Context as one.

And it's small: three core dependencies (pydantic, httpx, python-dotenv),
fully typed, no framework-of-the-week dependency tree.

Honest limits

reactifact is pre-1.0 (0.10.0), maintained by one person, and
single-process today — no broker, no worker pool, no managed platform. If you
need a mature ecosystem and hosted execution right now, use LangGraph; it's a
better fit. reactifact is for teams building open-ended, auditable knowledge
agents — internal assistants over docs, ops/incident tooling, finance/compliance
workflows — where "why did it say that?" has to have an answer.

Try it

pip install reactifact

Repo: https://github.com/bzdvdn/reactifact · Docs and offline demos:
https://bzdvdn.github.io/reactifact/

If you build agents over docs, CSVs, or repos, I want to hear what breaks for
you. That's more useful to me than a star.

speckeep: a spec-driven development workflow for coding agents

Bogdan — Mon, 21 Sep 2026 12:07:03 +0000

speckeep: a spec-driven development workflow for coding agents

TL;DR — speckeep is a small spec-driven workflow for coding agents: specs, plans, tasks and proof live in plain markdown, agents get them as /spk-<phase> commands, and a CLI gate makes "done" checkable in CI. Single Go binary, MIT. Try it with speckeep demo ./my-demo.

Every team using a coding agent hits the same three failures, usually in the same week:

Amnesia. You explain the same feature three sessions in a row, because context lives in a chat window that closed.
Drift. The agent builds something reasonable — just not what you asked for. Nobody notices until review.
Phantom "done". The agent says it's finished. No tests, no evidence, no trace from requirement to code.

Prompting harder doesn't fix this. The problem isn't the model — it's that there is no durable artifact between "what we want" and "what the agent did", and nothing that forces the agent to prove the second matches the first.

That's the gap speckeep fills. The workflow is a strict chain:

constitution -> spec -> [inspect] -> plan -> tasks -> implement -> archive

constitution — the project's non-negotiables (stack, conventions, quality bar).
spec — one feature, with stable IDs: requirements RQ-* and acceptance criteria AC-*.
inspect (optional) — a deep quality review before you commit to a plan.
plan — surfaces (files) to touch, decisions, risks.
tasks — ordered, phased, each with a Touches: surface map.
implement — executes tasks, one phase at a time.
archive — closes the feature once every task has proof.

Optional verify is an on-demand audit; propose is a one-shot fast lane for small changes; converge is the cheap closing loop.

Here's what that looks like in practice — init a workspace, read the health check, dry-run a refresh:

The idea: discipline per token

Most process fails on agents for one reason — it asks for too much context at once. speckeep's design rule is the opposite: every phase loads only the minimum it needs, and every phase leaves behind one compact artifact.

Each phase is a command you invoke in your agent. In Claude Code, Codex, Cursor, Copilot and others, that looks like:

/spk-constitution
/spk-spec Add CSV export to the reports table
/spk-plan csv-export
/spk-tasks csv-export
/spk-implement csv-export

The part that makes it different: proof, not vibes

Here's the mechanism that changed agent behaviour more than any prompt.

Every task in tasks.md must carry a Proof: line before it can be checked off, and every task maps to the surfaces it touches:

## Surface Map

| Surface                               | Tasks |
| ------------------------------------- | ----- |
| apps/api/src/routes/reports.ts        | T2.2  |
| packages/reporting/src/csv.ts         | T2.1  |
| apps/web/src/reports/ExportButton.tsx | T2.3  |

## Phase 2: MVP Slice

- [x] T2.1 Implement CSV serialization — the exporter produces headers + rows. Touches: packages/reporting/src/csv.ts
      Proof: test packages/reporting/src/csv.test.ts TestSerializeReports
- [x] T2.2 Wire the export endpoint — the route streams the CSV. Touches: apps/api/src/routes/reports.ts
      Proof: test apps/api/src/routes/reports.test.ts TestExportRoute
- [ ] T2.3 Add the button + empty state — the UI triggers export and handles zero rows. Touches: apps/web/src/reports/ExportButton.tsx

The CLI reads exactly those lines. If a task is marked done without proof, check says so by name:

$ speckeep check export-report .
verdict:  blocked
detail:   error [] closed task(s) without Proof in specs/active/export-report/tasks.md:
          T1.1, T1.2 — add a Proof: line to tasks.md

speckeep guard is the same idea for CI — it exits non-zero while any active feature isn't closeable:

$ speckeep guard .
╔═════════════════════════════════════════════════════╗
║ speckeep guard                                      ║
║ verdict: fail — 1 feature(s) are not ready to close ║
╚═════════════════════════════════════════════════════╝

- export-report            implement    implement    blocked

So the agent's claims are checked by a machine, not by your patience — and because the gates are deterministic, the agent can run them itself and self-correct before it ever reports back.

Built for the repo you actually have: a large monorepo

This is where speckeep earns its keep for us. Our main repo is a monorepo with a lot of code across many packages. For an agent, that's a trap: read too little and it edits the wrong package; read too much and the context window is full of irrelevant files before the real work starts.

Three pieces fix that:

1. REPOSITORY_MAP.md — a navigation index the agent can trust.
Run /spk-repo-map (directly, or when a task changes structure) and speckeep generates/updates a compact map: entry points, top-level modules, key paths, and a "where to edit" table — all derived from the actual tree, kept under a line budget so it stays cheap to read. Instead of walking the repo, the agent opens the map, picks the right 2–3 surfaces, and starts.

2. CONSTITUTION.md — one source of truth for conventions.
In a monorepo, conventions differ per package and nobody remembers all of them. The constitution captures them once (language rules, layering, test expectations, what not to do), so every phase and every agent reads the same rules instead of guessing — and specs get checked against them.

3. spec.md + Touches: — an explicit, tiny surface area per task.
The spec pins the acceptance criteria; the task list pins the exact files each task may touch. The agent's working set is now "this feature, these surfaces" — not "this repo".

Put together, that's how a complex, cross-package task gets closed without the agent reading the whole monorepo: the map narrows where to look, the constitution narrows how to build, the spec and Touches: narrow what to change. And because the same artifacts persist, the next session doesn't start from zero.

A real cycle, end to end

Say you want CSV export on a reports page.

1. Init and spec

speckeep init . --lang en --shell sh --agents claude

/spk-spec --name "CSV export for reports"

The agent writes specs/active/csv-export-for-reports/spec.md:

## Goal

Allow users to download the reports table as a CSV file.

## Acceptance Criteria

**AC-001** Export produces a file
Given the Reports page has at least one row
When the user clicks "Export CSV"
Then a .csv file downloads with column headers and all visible rows

**AC-002** Empty state is handled
Given the reports table is empty
When the user clicks "Export CSV"
Then a friendly message is shown and no file is downloaded

2. Plan → tasks

/spk-plan csv-export-for-reports
/spk-tasks csv-export-for-reports

You now have a small, readable package — and it lives in your repo, not in a chat:

specs/active/csv-export-for-reports/
  spec.md      # goal + AC-001..AC-00N
  plan.md      # surfaces, decisions, risks
  tasks.md     # phases, Touches:, Proof:
  verify.md    # optional audit report

3. Implement, then close

/spk-implement csv-export-for-reports

Each task gets code and a Proof: line. When the last one is checked, the agent closes the loop:

$ speckeep converge csv-export-for-reports .
OK: feature is converged: tasks complete with valid Proof coverage — safe to archive
$ speckeep archive csv-export-for-reports . --compact

If there's a gap, it appends follow-up tasks and loops — with a hard stop after two rounds instead of grinding forever. And if you want a formal audit before archiving, set workflow.verify: required and the archive gate demands a verify: pass report first.

--compact keeps just summary.md plus a git pointer instead of copying every artifact. The whole feature is a handful of markdown files you can read in two minutes. That's the point.

Day one: adopt it in 5 minutes

Install (details in Install below):

   curl -fsSL "https://raw.githubusercontent.com/bzdvdn/speckeep/main/scripts/install.sh" | bash

Init your real repo and confirm it's healthy:

   speckeep init . --agents claude,opencode
   speckeep doctor .

Write the rules down once — run /spk-constitution and point it at your stack, layering and test expectations. In a monorepo this is the highest-leverage ten minutes you'll spend.
Map the codebase — run /spk-repo-map to generate REPOSITORY_MAP.md, and re-run it whenever the structure changes.
Take one real (small) task through the chain:

   /spk-spec <task>  ->  /spk-plan  ->  /spk-tasks  ->  /spk-implement

Watch the first Proof: line appear — that's the moment it clicks.

Wire the CI gate — copy contrib/ci/speckeep-guard.yml into .github/workflows/, or add the action directly:

   - uses: bzdvdn/speckeep/.github/actions/speckeep@main
     with:
       root: .

Now "done" is enforced on every pull request.

If step 5 feels heavy for a first try, use /spk-propose instead — same proof requirement, one command.

What changed for us

Before	After
Re-explaining the same feature every session	The spec and tasks are already in the repo
Review = "did the agent do what we asked?"	Review = "do we agree with the spec?"
Cross-package work stalled on "which package owns this?"	`REPOSITORY_MAP.md` answers it
"It's done" → "actually, no" loops	`Proof:` catches it before a human does

Why not just use AGENTS.md, ready-made skills, or another spec tool?

Fair question — and it's the one I'd ask.

vs. hand-rolled AGENTS.md / your agent's built-in skills. You absolutely can encode a process there, and there's zero setup. What you don't get is enforcement: nothing turns "you should add tests" into a failing exit code, and nothing survives as a durable artifact when the session ends. speckeep is skills — it ships as skill files and commands for 19 agents — but it also adds the two things skills alone can't: persistent artifacts and deterministic gates.

vs. personal skill packs (e.g. mattpocock/skills). Great resources, and genuinely complementary. Those skills make your agent sharper inside a session — interviewing you about a plan, driving TDD, reviewing code. speckeep makes your definition of done survive the session and gives CI a way to enforce it. You can run both: use interactive skills for the conversation, speckeep for the spec → tasks → proof spine.

vs. other spec tools (OpenSpec, Spec Kit). Same family, different tradeoff:

Dimension	speckeep	OpenSpec	Spec Kit
Workflow style	Strict phase chain, narrow context	Fluid, artifact-guided	Thorough multi-step SDD
Default context	Smallest	Moderate	Largest
Artifact overhead	Low	Medium	High
Brownfield / monorepo	High (repo-map + constitution)	High	Medium
Machine-checkable "done"	`speckeep guard` (exit code in CI)	—	—
Runtime	One Go binary	Node	Python

The short version:

Other skills make your agent smarter in a session. speckeep makes your definition of done survive the session — and gives CI a way to enforce it.

Works with the agent you already use

speckeep ships adapters for 19 targets: Claude Code, Codex, Cursor, Copilot, OpenCode, Windsurf, Cline, Amazon Q, Gemini, aider, Devin, Goose, Jules, Refact, Roo Code, Kilo Code, Qwen Code, Trae, Codiumate.

It's skills-first and it does the per-tool research for you, because the tools genuinely differ. In Claude Code, top-level skills are directly slash-invocable. In OpenCode, skills are model-invoked and not in the / palette — so /spk-<phase> is reached through the /skills picker. speckeep handles that so you don't find out the hard way.

speckeep init my-project --agents claude,opencode,cursor

It also writes an AGENTS.md block so any agent — even ones without a skills system — knows the workflow and the gates.

The escape hatches (because process shouldn't be dogma)

Real teams need to move fast sometimes. speckeep has explicit, bounded ways to skip:

/spk-propose — one-shot: idea → spec.md + tasks.md, straight to implement. Falls back to /spk-spec if the idea is ambiguous.
Express lane — small changes close from spec.md + tasks.md; plan.md is optional.
/spk-hotfix — emergency fix outside the chain (≤ 3 files, no re-planning).
/spk-challenge — adversarial review of a spec/plan when you want a hostile second opinion.
/spk-scope, /spk-glossary, /spk-handoff, /spk-recap, /spk-rollback — small, single-purpose tools.

The discipline is strict where it pays off and skippable where it doesn't.

Migrating in

speckeep import openspec .   # openspec/changes/<slug>/ -> speckeep layout
speckeep import speckit .    # specs/<slug>/ -> speckeep layout

It rebuilds requirement/acceptance IDs where it can and never overwrites existing features. Coming from DraftSpec (this project's predecessor), speckeep migrate handles the move.

Install and try it in 30 seconds

One Go binary, no runtime, MIT licensed.

# Linux / macOS
curl -fsSL "https://raw.githubusercontent.com/bzdvdn/speckeep/main/scripts/install.sh" | bash

# or: brew install bzdvdn/speckeep/speckeep
# or: npx speckeep ...

Try a fully populated example without touching your project:

speckeep demo ./my-demo
speckeep dashboard ./my-demo
speckeep check export-report ./my-demo

Docs (EN/RU): https://bzdvdn.github.io/speckeep/
Repo: https://github.com/bzdvdn/speckeep

What it is not

I'd rather you adopt it knowing the tradeoffs:

It's not an orchestrator. No daemon, no agents-on-agents, no vector DB. It's files plus a CLI.
It is strict by design. If you hate checklists and IDs, this will feel like overhead — until the first time an agent's "done" turns out to be fiction.
It optimises for brownfield monorepos. The value is highest on real codebases with messy history and many packages, not greenfield demos.
It's young. The workflow is stable; the ecosystem around it is still growing.

Why we built it

We used agents daily in a large monorepo and kept paying the same tax: re-explaining context, re-reviewing drift, and re-verifying work that was reported as finished. The trio that finally moved the needle was repo-map + constitution + spec — a map of the codebase, one set of rules, and a durable spec with proof.

speckeep is the smallest structure we found that actually changes agent behaviour — because it's the one the agent can't argue with. Either the Proof: line is there or the gate fails.

If that resonates: star the repo, run speckeep demo, and tell me two things — which agent you use, and where the workflow breaks on your codebase. That feedback is what shapes the next release.

GitHub: https://github.com/bzdvdn/speckeep
Docs: https://bzdvdn.github.io/speckeep/
Changelog: https://github.com/bzdvdn/speckeep/blob/master/CHANGELOG.md

Edit One Input, Only Its Real Dependents Recompute — No Graph, No Command

Bogdan — Mon, 07 Sep 2026 10:43:20 +0000

(not committed — local draft, review before pushing to dev.to)

Most agent frameworks — LangGraph included — model a pipeline as nodes
connected by edges, sharing one big state object (a TypedDict). That's a
fine mental model until you ask a very ordinary question:

If I edit one input, which parts of my pipeline actually need to
recompute?

The honest answer in a shared-state graph is: the framework has no
idea. Nodes don't declare "I read field X" anywhere the framework can
see — they just receive the whole state and return updates to it. So
either you re-run everything downstream of wherever you re-enter the
graph (coarse — you recompute things nothing about your edit ever
touched), or you hand-roll the missing piece yourself: dirty flags, a
manual dependency map, comparing old-vs-new values inside every node,
Command(goto=...) to jump back into specific nodes.

That bookkeeping is exactly what you get for free when state lives in
typed, versioned artifacts and a node's dependency is what it declares
it consumes — which is the core idea behind ctxloom, a small
Python agent framework I've been building. This post walks through one
concrete, checkable example of why that matters, with real numbers, not
just an architecture diagram.

The example: a cost model

Hours × Rate → LaborCost → Tax, Discount → Total

Every artifact in ctxloom carries a version number, bumped only when it's
actually recomputed. Start the model, then edit only TaxRate:

--- initial calculation ---
  LaborCost    value=500.0      version=0
  Tax          value=40.0       version=0
  Discount     value=25.0       version=0
  Total        value=515.0      version=0

>>> editing ONLY TaxRate (0.08 -> 0.12)

--- after editing TaxRate ---
  LaborCost    value=500.0      version=0   ← untouched
  Tax          value=60.0       version=1   ← recomputed
  Discount     value=25.0       version=0   ← untouched
  Total        value=535.0      version=1   ← recomputed (consumes Tax)

LaborCost and Discount don't consume TaxRate — they are never
invoked for this edit, not invoked-and-decided-nothing-changed. Edit
Hours instead and it correctly cascades through everything, because
everything really does depend on it transitively through LaborCost —
the model isn't "isolated by construction," it's precise about what
actually depends on what.

Side by side

Here's the same shape in LangGraph — state is one shared dict, and a node
reads whatever fields it wants from it while the framework can't see
which ones:

class State(TypedDict):
    hours: float
    rate: float
    tax_rate: float
    discount_rate: float
    labor_cost: float
    tax: float
    discount: float
    total: float

def labor_cost_node(state: State) -> dict:
    return {"labor_cost": state["hours"] * state["rate"]}

def tax_node(state: State) -> dict:
    return {"tax": state["labor_cost"] * state["tax_rate"]}

def discount_node(state: State) -> dict:
    return {"discount": state["labor_cost"] * state["discount_rate"]}

def total_node(state: State) -> dict:
    return {"total": state["labor_cost"] + state["tax"] - state["discount"]}

graph = StateGraph(State)
graph.add_node("labor_cost", labor_cost_node)
graph.add_node("tax", tax_node)
graph.add_node("discount", discount_node)
graph.add_node("total", total_node)
graph.add_edge(START, "labor_cost")
graph.add_edge("labor_cost", "tax")
graph.add_edge("labor_cost", "discount")
graph.add_edge("tax", "total")
graph.add_edge("discount", "total")
compiled = graph.compile()

Now the user edits tax_rate and you want to refresh the total. What do
you invoke? compiled.invoke(state) re-enters at START and recomputes
labor_cost too, even though nothing about it changed — the graph has no
concept of "this input changed, that one didn't." To actually skip
labor_cost, you're writing the missing piece by hand: pass an extra
"what changed" flag through the state, add an if at the top of each
node comparing its own inputs to what they were last time, wire a
Command(goto=...) to jump in below labor_cost — a dependency tracker
you now own and maintain, node by node, forever.

Here's the same model in ctxloom. No graph, no state dict, no dirty
flags — each formula is a tiny class, and its consumes list is the
dependency declaration:

class LaborCost(BaseModel):
    value: float

class Tax(BaseModel):
    value: float

@produce(Tax)
async def compute_tax(context, inputs, effects):
    labor_cost = context.latest(LaborCost)
    tax_rate = context.latest(TaxRate)
    if labor_cost is None or tax_rate is None:
        return None
    effects.upsert(Tax(value=labor_cost.data.value * tax_rate.data.value), id="tax")

tax_agent = create_agent(
    "tax", consumes=[Consume(LaborCost), Consume(TaxRate)], produces=[compute_tax]
)

Editing a fact is a normal call:

context.update(tax_rate_artifact.id, TaxRate(value=0.12))
await runtime.arun()

The runtime fires ARTIFACT_UPDATED for TaxRate; only agents whose
consumes names TaxRate (or something downstream of it) ever run.
labor_cost_agent isn't in that set, so it's never invoked — not
"invoked, compared, decided no-op." Add a fifth formula tomorrow that
depends on Tax, and nothing above changes; it just declares
Consume(Tax) and starts reacting.

One honest caveat: convergence isn't always a single step. Editing
Hours made Total jump from version 0 straight to version 3, not to 1
— because Tax and Discount land their updates in separate passes as
the pipeline reaches a fixpoint, and Total reacts to each one. Same
phenomenon a spreadsheet's own multi-pass recalculation engine has. It
doesn't undermine the core claim (LaborCost/Discount really do stay
untouched when only TaxRate changes), but a sharp reader will ask, so
it's worth stating instead of glossing over.

The other half: branching

The same "state lives in artifacts, not one shared blob" design pays off
a second way that has nothing to do with recompute (see
examples/forklab):
context.branch()
forks an isolated copy of the whole state, you run different
agents/strategies on each fork independently, and merge() reconciles
them — a real three-way merge, raising an explicit conflict if both
forks touched the same artifact differently, instead of silently picking
one.

LangGraph's checkpointer gives you linear time-travel through one
thread's history — genuinely useful, but not the same thing as two
divergent branches getting reconciled back into one. There's no
comparable primitive to point at there; it's not "awkward to do," it's
just not something the framework does.

Where this doesn't matter

If your pipeline is genuinely fixed — step 1 always then step 2 always
then step 3, no branching by data, no expectation that inputs get edited
independently after the fact — none of this buys you anything, and a
drawn graph you can see in one file is more readable. This is
specifically about systems where "what needs to recompute" is a real
question with a data-dependent answer, not a fixed sequence.

Try it

The cost-model example above is a real, runnable file, no LLM required —
it lives at
examples/ledger
in the repo:

git clone https://github.com/bzdvdn/ctxloom
cd ctxloom
pip install -e .
python -m examples.ledger.main

Repo: github.com/bzdvdn/ctxloom. I'd be
curious whether people run into the "which nodes actually need to rerun"
problem often enough for this to matter in their own agent pipelines, or
whether it's a non-issue in practice because most pipelines stay small
enough that a full re-run is cheap either way.

Why "why did our infra costs jump in Q2?" doesn't fit a graph

Bogdan — Fri, 04 Sep 2026 21:44:29 +0000

TL;DR: some questions don't have a fixed path through your data (search docs, hit a table, compute, verify, answer — in whatever order/combination the question needs), and drawing a graph for that class of question means either enumerating every path up front or hiding an if/else forest inside one node. ctxloom replaces the graph with typed artifacts and agents that react to their appearance — below is the same use case built both ways, side by side.

The problem

Picture a typical question from a finance lead in an internal chat assistant:

"Why did our infra costs jump in Q2?"

Answering this honestly requires:

Finding relevant documents — the pricing guide, the discount policy (Confluence/docs).
Pulling structured data — a CSV/table of monthly spend (GitLab/S3/DB).
Computing an aggregate — not "roughly", an exact number from the table.
Cross-checking textual claims against the numbers — not letting the model invent a cause the data doesn't support.
Returning the answer together with proof: where each part came from.

The next question — "what if we hadn't moved to the Pro plan?" — needs a different path: a different source, a different calculation, a different verification chain. There is no universal graph for this class of questions — you can draw a graph for one specific question, but not for the class.

This is exactly what typical graph frameworks (LangGraph, CrewAI, etc.) make you pay for in complexity: either you draw a graph for every possible path up front, or you end up with a hidden branching if/else inside one node that nobody can later explain.

How this looks in ctxloom

ctxloom has no execution graph — it has artifacts (typed, versioned objects) and agents that react to their appearance. The breakdown above is just a chain of artifacts:

Question
   │
   ▼
SourceRef (ranked references to sources)
   │
   ▼
TypedDoc / Spreadsheet (lazily resolved content)
   │
   ├──► Evidence (facts extracted from text)
   │        │
   │        ▼
   │      Claim (a statement + verification against Evidence)
   │
   └──► Calculation (an aggregate computed by code, not the model)
            │
            ▼
          Answer ──supported_by──► Claim, Calculation

Each node in this chain is a separate Produce: a small, testable unit of logic that only knows "what I need on input" and "what I create on output". Agents declare consumes/produces, and which agent runs next isn't decided by the programmer up front — the runtime figures it out from which artifact just appeared.

The repo's examples/knowledge demo has 9 agents and not a single explicit edge between them — here's the actual flow map (python -m ctxloom graph examples.knowledge.agents):

planner ──creates──► ResearchTurn ──consumed by──► search_scout, progress_evaluator
search_scout ──creates──► SourceRef ──consumed by──► resolver, table_resolver
resolver ──creates──► TypedDoc ──consumed by──► evidence_builder
evidence_builder ──creates──► Evidence ──consumed by──► verifier
table_resolver ──creates──► Spreadsheet ──consumed by──► calculator
calculator ──creates──► Calculation ──consumed by──► answer_builder
verifier ──creates──► Claim ──consumed by──► answer_builder
answer_builder ──consumes ResearchTurn──► creates Answer

The question "how much does GPU cost in total?" goes through text search, table search, a deterministic calculation, and verification — in a single run — because each agent reacts to what appeared, not to what someone expected to see at this step.

Provenance: not "a source mentioned in the prompt", a traceable chain

The key difference from a typical RAG chatbot: the answer doesn't just reference a source in text ("according to the CSV...") — it's linked to it structurally:

answer = ctx.latest(Answer)
evidence = ctx.related(answer.id, "supported_by")[0]

The chain Answer → supported_by → Claim → derived_from → Evidence → extracted_from → TypedDoc → materialized_from → SourceRef isn't a log line — it's a graph of relations you can walk programmatically: show "where this answer came from" in a UI, run an audit of "which documents back the last 100 answers", or find every answer that depends on a document that later turned out to be stale.

Calculations are calculated, not guessed

The model here isn't the source of truth for numbers. calculator is plain code aggregating a CSV; the LLM is used only where reasoning is actually needed (phrasing the answer, extracting a fact from text), not where arithmetic is needed. If the aggregate disagreed with what the text evidence claims, verifier catches it before the answer ever reaches the user — because checking a claim against numbers is its own deterministic Produce, not part of a prompt that "usually works out".

What this buys you in practice

Reproducibility — the same question against the same context version takes the same execution path; Context is versioned like git, so you can diff/rollback/replay.
Auditability — every derived artifact knows what it was derived from; you don't have to reconstruct the reasoning chain from logs.
Extensibility without rewriting the graph — a new data source is just another Source that fan_out_sources picks up automatically; there's no graph to edit because there's no graph.
Honest failure — if a source is unavailable or a calculation doesn't add up, a Produce returns None instead of the model "filling in" a plausible but wrong answer; the question escalates via HITL (effects.ask) if a human is needed.

Head-to-head: the same use case, two implementations

On ctxloom

No router, no shared dict, no fan-out/fan-in node. search_docs and search_table both react to the same Question independently — "GPU cost" needing both docs and the table just happens, it isn't a case anyone routes to.

(Simplified for readability into 5 agents — the real examples/knowledge demo is 9, because it also handles chat-turn routing, a lifecycle agent that decides when a turn has enough evidence to answer even if only one branch applies, and HITL escalation. Names here don't match the repo 1:1; see the link at the end for the literal code.)

from ctxloom import Consume, create_agent, produce


@produce(SourceRef)
async def search_docs(context, inputs, event, effects):
    question = find(inputs, Question)
    if question is None:
        return None
    for ref in docs_source.search(question.data.text):  # your retrieval logic
        effects.create(ref)


@produce(Spreadsheet)
async def search_table(context, inputs, event, effects):
    question = find(inputs, Question)
    if question is None:
        return None
    effects.create(load_costs_table())                  # resolves the CSV


@produce(Evidence)
async def extract_evidence(context, inputs, event, effects):
    doc = find(inputs, TypedDoc)
    if doc is None:
        return None
    for fact in extract_facts(doc.data.text):           # your extraction logic
        effects.create(Evidence(text=fact)).link("extracted_from", doc)


@produce(Calculation)
async def calculate(context, inputs, event, effects):
    sheet = find(inputs, Spreadsheet)
    if sheet is None:
        return None
    total = sum(row["cost"] for row in sheet.data.rows)  # real arithmetic, not the LLM
    effects.create(Calculation(total=total)).link("computed_from", sheet)


@produce(Claim)
async def verify_claim(context, inputs, event, effects):
    evidence, calc = find_all(inputs, Evidence), find(inputs, Calculation)
    if not evidence or calc is None:
        return None                                      # the other half hasn't landed yet — fine, we'll be re-triggered
    claim = effects.create(Claim(text=..., verified=matches(evidence, calc)))
    for e in evidence:
        claim.link("derived_from", e)
    claim.link("checked_against", calc)


@produce(Answer)
async def build_answer(context, inputs, event, effects):
    claim = find(inputs, Claim)
    if claim is None or not claim.data.verified:
        return None
    effects.create(Answer(text=claim.data.text)).link("supported_by", claim)


search_agent = create_agent("search", consumes=[Consume(Question)], produces=[search_docs, search_table])
evidence_agent = create_agent("evidence", consumes=[Consume(TypedDoc)], produces=[extract_evidence])
calc_agent = create_agent("calc", consumes=[Consume(Spreadsheet)], produces=[calculate])
verify_agent = create_agent("verify", consumes=[Consume(Evidence), Consume(Calculation)], produces=[verify_claim])
answer_agent = create_agent("answer", consumes=[Consume(Claim)], produces=[build_answer])

verify_claim still has a two-line readiness guard — that part isn't magic, someone has to know what "ready" means. What ctxloom removes is the graph wiring around that guard: there's no join node, no conditional edge deciding who calls verify_claim, no entry in a router that has to know both search_docs and search_table exist. verify_agent just declares it consumes both artifact types; the runtime re-triggers it on either one showing up, and the guard clause is the only place "readiness" is decided — once, locally, next to the logic that uses it.

On LangGraph

To be concrete about the cost, here's roughly what the same use case takes in LangGraph. You model state as one shared, untyped dict, and you draw every path explicitly:

from langgraph.graph import StateGraph, END

class State(TypedDict):
    question: str
    doc_hits: list
    table_hits: list
    evidence: list
    claims: list
    calculation: dict | None
    answer: str | None

def route_question(state: State) -> str:
    # you write this: does the question need the table, the docs, or both?
    if looks_numeric(state["question"]):
        return "search_table"
    return "search_docs"

def search_docs(state): ...       # -> doc_hits
def search_table(state): ...      # -> table_hits
def extract_evidence(state): ...  # -> evidence, reads doc_hits
def calculate(state): ...         # -> calculation, reads table_hits
def verify_claim(state): ...      # -> claims, reads evidence + calculation
def build_answer(state): ...      # -> answer, reads claims

graph = StateGraph(State)
graph.add_node("search_docs", search_docs)
graph.add_node("search_table", search_table)
graph.add_node("extract_evidence", extract_evidence)
graph.add_node("calculate", calculate)
graph.add_node("verify_claim", verify_claim)
graph.add_node("build_answer", build_answer)

graph.set_conditional_entry_point(route_question, {
    "search_docs": "search_docs",
    "search_table": "search_table",
})
graph.add_edge("search_docs", "extract_evidence")
graph.add_edge("search_table", "calculate")
# but "how much does GPU cost in total?" needs BOTH docs and table in one turn —
# so route_question's binary choice is already wrong, and you need a fan-out/
# fan-in node instead, plus a join condition that waits for both branches.
graph.add_conditional_edges("extract_evidence", lambda s: "calculate" if needs_table(s) else "verify_claim")
graph.add_edge("calculate", "verify_claim")
graph.add_edge("verify_claim", "build_answer")
graph.add_edge("build_answer", END)

This already shows the pain, before adding a single new question type:

route_question grows combinatorially. The real question — "how much does GPU cost in total?" — needs both branches, so the binary router above is already wrong on the first real input. Fixing it means a fan-out/fan-in pair: a node that dispatches to both, and a join node whose only job is re-implementing the readiness check ctxloom gets from consumes for free — except now it's graph topology, reviewed by reading edges, not by reading the function that uses the result.
State is an untyped shared dict, and that's a real bug source, not a style complaint. Say someone renames calculation to cost_calculation while touching calculate. verify_claim still reads state["calculation"] — no import error, no type error, no test failure until the field is None at runtime and verify_claim silently verifies against stale or missing data. In ctxloom the equivalent break is find(inputs, Calculation) returning None where a type actually changed — caught by the type checker, not by production behavior.
Provenance isn't a thing. state["evidence"] and state["calculation"] are just values that get overwritten; if you want "what exactly did the answer depend on", you build that bookkeeping yourself, by hand, in every node, and keep it in sync with the graph by hand too.
A new source or a new claim type means editing the graph. Adding a third search path (say, a ticketing system) means touching route_question, adding a node, and adding edges — not just adding a node next to the existing ones, and not without re-reading the routing logic to make sure the new branch doesn't shadow an existing one.

None of this is a knock on LangGraph for what it's built for — short, mostly-linear or a-few-known-branches flows, it's a fine fit. The mismatch is specifically the "open-ended question over heterogeneous sources, next question needs a different path" shape: a problem that doesn't have a fixed set of paths, forced into a data structure that requires one to be drawn in advance. That mismatch — and having no structural way to say "this answer is backed by exactly these facts" without hand-rolling it — is the actual reason we built ctxloom instead of building this on top of an existing graph framework: state changes already contain everything needed to decide "what runs next" and "what this depended on", so encoding that separately, by hand, as a graph plus a provenance dict, is redundant work that silently drifts from the real state the moment someone touches one side without the other.

Try it

Repo: github.com/bzdvdn/ctxloom
This use case, runnable, no API key required: examples/knowledge — .venv/bin/python examples/knowledge/chat.py (deterministic fallbacks when no LLM key is set)
Feature-by-feature comparison, including where ctxloom is not the right choice: docs/en/comparison.md

If you're building something with a similar "no fixed path" shape, I'd like to hear about it — and if you try ctxloom, a star on the repo or an issue with what didn't work is the most useful feedback I can get.

Stop drawing the graph: reactive agents over versioned artifacts

Bogdan — Tue, 01 Sep 2026 21:53:31 +0000

Stop drawing the graph: reactive agents over versioned artifacts

Most agent frameworks make you draw the graph: connect nodes, wire memory, declare control flow. But a knowledge problem is not a workflow.

Take a realistic question: "Why did infrastructure costs increase in Q2?"

The answer may need Confluence docs, GitLab merge requests, CSV spend data, a calculation, source verification — and a clarifying question. The next question needs a different path. There is no universal graph here, and asking a developer to draw one for every possible question is asking them to predict the future.

So we built an agent runtime where you don't describe execution at all. You describe what artifacts exist and what agents can do with them; the runtime derives what runs next from state changes. Agents react to events. There is no graph and no node pipeline.

This is ctxloom — a reactive, artifact-driven agent runtime, now open source.

What it looks like

The whole loop is: create an artifact → agents react → one atomic patch → context advances.

A knowledge question — say, "how much does GPU inference cost?" — becomes a chain of typed artifacts: UserQuery → TypedDoc → Evidence → Claim → Answer. Each is produced by an agent that reacts to the previous artifact. No graph describes this chain; it falls out of what each agent consumes and produces.

ARTIFACT CREATED / UPDATED
       │
       ▼
     AGENTS REACT ──self.effects──► Effects ──compile──► Patch
       ▲                                                      │
       └──────────────────────────────────────────────────────┘
                                                        Context v+1

The event that wakes an agent is derived from that same change — the causal chain can never drift from the actual state.

from pydantic import BaseModel

from ctxloom import Budget, Consume, Context, Runtime, RuntimeResources, create_agent, produce, structured_llm


class Question(BaseModel):
    text: str


class FindingBody(BaseModel):
    text: str


class Finding(BaseModel):
    text: str
    source: str


class Conclusion(BaseModel):
    text: str


@produce(Finding)
async def analyze_question(context, inputs, event, effects):
    """React to a Question; deterministic fallback when the LLM is absent (§67)."""
    question = next((a for a in inputs if isinstance(a.data, Question)), None)
    if question is None:
        return None
    body = await structured_llm(
        context, schema=FindingBody, user=question.data.text
    )
    effects.create(
        Finding(text=body.text if body else "no answer", source="LLM"),
        id=f"finding:{question.id}",
    )

Now add a second agent that reacts to Finding and links it back — provenance for free:

@produce(Conclusion)
async def conclude(context, inputs, event, effects):
    finding = next((a for a in inputs if isinstance(a.data, Finding)), None)
    if finding is None:
        return None
    conclusion = effects.create(
        Conclusion(text="Summarized.", supported_by=[finding.id]),
        id="conclusion",
    )
    conclusion.link("supported_by", finding)   # provenance edge (§34)


agents = [
    create_agent("analyzer", consumes=[Consume(Question)], produces=[analyze_question]),
    create_agent("concluder", consumes=[Consume(Finding)], produces=[conclude]),
]

ctx = Context(resources=RuntimeResources())   # no LLM wired: offline deterministic run
ctx.create(Question(text="how much does GPU inference cost?"))
Runtime(ctx, agents=agents, budget=Budget(max_runs=20)).run()

answer = ctx.latest(Conclusion)                       # find the terminal artifact
finding = ctx.related(answer.id, "supported_by")[0]   # provenance: what supports it
print(finding.data.text)                              # "GPUs accelerate inference."

Two agents, no graph. The runtime matches Question → analyze_question → Finding → conclude → Conclusion by reacting to state changes — and if the LLM is missing, structured_llm returns None and the run degrades gracefully instead of hallucinating.

You can see this fully worked out in the knowledge demo: search fan-out, evidence extraction, deterministic claim verification, and a supported_by answer with sources.

Why this isn't just another framework

1. Effects instead of "return a change"

Most frameworks ask a unit of work to return its result, and some orchestrator applies it. ctxloom inverts this: a producer states what should change and returns None.

async def produce(self, context, inputs, event=None) -> None:
    evidence = self.effects.create(Evidence(...), id="evidence:q1")
    answer = self.effects.create(Answer(...), id="answer:q1")
    evidence.link("extracted_from", doc)
    answer.link("supported_by", evidence)
    self.effects.update(turn, status="answered")
    return None

One atomic commit. Nothing applies until the produce returns — the whole step lands or none of it does. No half-applied states, no manual rollback ladders.
Handles are objects, not ids. evidence is created above and linked below — the same object, no lookup by number.
Human-in-the-loop is just another effect. self.effects.ask(...) poses a question; effects.resume(...) resolves it. A human is not a special case bolted onto the side.

2. Determinism by default

The dominant pattern is "let the LLM do everything". ctxloom takes the opposite stance:

Calculations are actually calculated. CSVSource → Spreadsheet → Calculation over structured data is deterministic code — not a hallucinated number.
Eligibility is a decision of the state. A produce's guard decides whether it reacts; the LLM is called only on genuinely generative steps.
Honesty beats pretending. On failure a produce returns None rather than a confident guess. The model is a reasoning component, never the source of truth.

The rule of thumb: if it can be computed, compute it; the LLM only does what requires language and judgment.

3. Provenance and versioning for free

Every run is a commit. You get diff, rollback, branch() and merge() for the state of a conversation, plus deterministic replay for auditing.

And every derived artifact links back to what produced it:

Answer → supported_by → Claim → derived_from → Evidence → extracted_from → Doc

"Why did the agent say that?" is not a hand-wave — it's a walk across these links. That is accountability, and it's structural, not cosmetic.

What's in the box

13 runnable examples, all offline-capable (no API keys required): a multi-source knowledge chat, a web researcher, a hypothesis laboratory, an ops assistant, budget-aware replanning, branch-and-merge exploration, and more.
A port matrix mapping canonical agent patterns — ReAct, reflection, map-reduce, supervisor, summarize, time-travel, plan-and-execute — onto this idiom. You don't throw away what you already know; you see how it falls out of state instead of a diagram.
Observability built in. Every run records agent spans, reads/writes, LLM calls and token usage — a local web dashboard, exportable to Langfuse or Postgres.
A thin web layer. ChatAssistant + create_chat_router mount a session-persisted SSE chat on your FastAPI app, with logged fallbacks instead of 500s.

When would you not want this?

Honesty matters:

Fixed pipelines. If your task really is a fixed sequence of five steps and nothing reacts, a plain function or a classic graph is the right tool. Pick what fits.
Pure playgrounds. If you only want the model to "figure it out" and don't care about determinism, provenance or accountability, ctxloom adds ceremony you can skip.

For everything in between — agents that gather evidence, verify claims, calculate, respect budgets, ask humans, and can be audited — reactivity beats drawing a graph.

If this resonates, try it — every example runs offline, no API keys needed:

pip install "ctxloom[web]"
python ./examples/knowledge/web.py    # multi-source chat with sourced answers
python ./examples/repair/web.py       # room renovation: plan, estimate, CSV export

The 30-second takeaway: describe artifacts, not wiring. The knowledge demo
turns a question into evidence → claims → a supported_by answer in minutes,
offline — and the same loop scales to research, ops, or anything where the
answer has to be accountable.

GitHub: github.com/bzdvdn/ctxloom
Design argument: why-ctxloom.md
Port matrix: port-matrix.md