Skip to content
jimbakerPublic

About

Durable, replayable agentic workflows in Python: algebraic effects as composable generators, PEP 750 t-strings as typed prompt channels.

Topics

Resources

Stars

7 stars

Watchers

0 watching

Forks

Repository files navigation

Effective

Build agentic workflows from composable Python generators. A handler records each model call, Jev judgment, tool, and human approval, so a run is replayable and durable.

An agent loop is a state machine. A workflow writes it as a plain Python generator whose frames hold the state, and which yields an op for each effect: call a model, call a tool, wait for a human, append to the ledger, the run's append-only record. A handler interprets each op, so the same generator is recorded in a test, replayed from that recording, or run durably, where a crashed worker resumes by replaying the steps it already took.

The prompts are t-strings. A prompt is a t"..." whose interpolations are typed channels: inputs render in, and outputs declare the schema the response is parsed into. A Gated output runs a check over the response, which is a guardrail on the data boundary.

An agent loop is a state machine

A ReAct agent reasons, acts and observes, and something drives it: it calls the model, runs the tool, and sends the result back. Agent frameworks let you customize that machine with hooks on its edges: before a call, after a call, on a prompt, before stopping. Claude Code calls them PreToolUse, PostToolUse, UserPromptSubmit and Stop.

block-beta
    columns 5
    space:2 world["<b>World</b><br/>the model, tools, people"] prompt(["on a prompt"]) space
    space before(["before a call"]) space after(["after a call"]) space
    workflow["<b>Workflow</b><br/>a generator: its frames<br/>hold the state"] space handler["<b>Handler</b><br/>drives the loop,<br/>interprets ops"] space:2
    stopping(["before stopping"]) space:4
    space:5
    tape["<b>Tape</b><br/>one row per result; on replay it serves results first"]:5
    workflow -- "yield op ⇄ send" --- handler
    handler -- "call ⇄ result" --- world
    handler -- "append ⇄ replay" --- tape
    classDef hook fill:#fdebd9,stroke:#c2410c,color:#9a3412
    classDef hub stroke:#1d6fd6,stroke-width:2px
    classDef dashed stroke-dasharray:5 4
    class before,after,prompt,stopping hook
    class handler hub
    class tape dashed
Loading

The orange tags name those hooks: a call's two hooks flank the edge to the world, and "before stopping" sits by the workflow, whose return ends the run. The tape is how a run survives a crash, below.

Python already has a construct that holds a state machine's state for you: a generator. Each yield is an edge, and the suspended frame is the state.

def react(goal: str) -> Generator[Request, str]:
    observation = None
    while True:
        action = yield Reason(goal, observation)
        observation = yield Act(action)

Reason and Act are frozen dataclasses that describe a request. The loop performs no I/O, so whatever calls send decides what they mean: a test script, a live model, or the tape of an earlier run. examples/react_toy.py drives it with a script. In Effective, the code that calls send is a handler.

a state machine with hooks a generator
where the state lives fields you declare and keep current the frame's locals and the line it is paused on
a check before a call a hook function on an event the framework offers an expression at the yield, or a layer
a nested workflow the framework's subagent, if it has one; else a nested machine, forwarded by hand yield from another workflow, or spawn it as a child task
a new check a new hook function, or a new phase with its arm and fields a new line, which in-flight runs meet on replay
what a type checker proves a total transition table over a closed set of phases a total match over the closed set of ops; control flow only as far as the tests reach
durability checkpoint the state object replay the tape through the same code
changing code while runs are in flight load the stored state into the new code, migrating its shape if it changed the new code yields the recorded ops under their recorded names; an op it renames runs again
inspecting a paused run read the state object read the tape; the frame's locals are never stored

Effective's hooks are generators too. A layer sees each model call, tool call, sleep and ledger append on its way out and its result on the way back, and keeps whatever it needs between the two in its own frame:

@op_layer
def audit(op: WorkflowOp) -> Generator[WorkflowOp, Any, Any]:
    print("before a call:", describe(op))
    result = yield op
    print("after a call: ", describe(op), "->", result)
    return result

A layer runs again when a run replays: it sees each replayed op and its recorded result, so a side effect that must happen once belongs in an op. A layer that yields an AwaitEvent parks the run until a person answers. govern composes several checks into one gate that proceeds, parks or refuses. Retry belongs one level down, in retry_domain on the interpreter that interprets the op (MeteredInterpreter(..., domain_layers=[retry_domain()])): it retries inside the op's one checkpoint, where a re-yielded op would take a new checkpoint name and a crash would run it again.

A first workflow

git clone https://github.com/jimbaker/effective && cd effective
uv sync                                    # Python 3.14 and the development environment
uv run python examples/first_workflow.py   # a durable run, a resume after an outage, a guardrail

The workflow asks a model for a thermostat setpoint, checks it, and sets it:

def set_temperature(request_id: str, request: str, ceiling: float = 30) -> Effect[float | Repair]:
    celsius = Gated(float, lambda c: 10 <= c <= ceiling, "celsius outside the allowed range")
    prompt = t"The occupant said: {request}\nSet the thermostat to {celsius}"
    setpoint = render(prompt, output=Setpoint)
    response = yield from ask_llm("setpoint", setpoint.messages, dict)
    match setpoint.resolve(response):
        case Repair() as repair:
            return repair
        case Setpoint(celsius=target):
            yield from call_tool("thermostat", {"celsius": target}, str)
            ...

It runs as a task on the embedded SQLite engine, in a temporary file, and prints three lines; docs/first-workflow.md walks through it line by line:

line what it shows
run each op is a checkpointed step, and the keys printed are the checkpoints
resume the thermostat is offline on the first attempt; the retry replays the setpoint from the file and asks the model nothing more
guardrail the model responds with 45°C, the Gated check fails, and the workflow returns a Repair before it reaches the thermostat

resolve returns Repair(reason) when a check fails; the workflow decides what to do with it: return it, as here, or re-prompt with the reason.

Durability is a tape

A durable handler writes each result down before the workflow sees it. After a crash, a new worker runs the workflow from the top, and the tape serves every op it holds a result for:

sequenceDiagram
    participant W as Workflow
    participant H as Handler
    participant T as Tape
    participant M as Model
    W->>H: yield ask_llm("setpoint")
    H->>M: ask
    M-->>H: {"celsius": 22}
    H->>T: append the result
    H-->>W: send {"celsius": 22}
    Note over W,M: the worker crashes, and a new one runs the workflow from the top
    W->>H: yield ask_llm("setpoint")
    H->>T: read setpoint
    T-->>H: {"celsius": 22}
    H-->>W: send {"celsius": 22}, and the model is never asked
Loading

Nothing is captured from a frame: suspension is replay. A durable handler finds each recorded result by the op's name. It serves an op it has a result for and runs an op it has none for. A changed prompt or tool argument keeps the name, so it is served the recorded result; a changed result type validates that result against the new type, and fails the run if it does not fit. A test is where a change in which ops are yielded, under which names, or in what order is caught: wiki/concepts/testing.md.

The handler and its engines

DurableHandler runs a workflow: each model call, tool call and ledger append is a checkpointed step of a task, and a wait is the engine's own await. The engine holds the tape:

engine for
Absurd on Postgres many workers over one queue (vendored and pinned in infra/absurd)
embedded SQLite (effective.engines.sqlite) one process and one file, with no service to run

The two engines run one conformance suite through the same handler (tests/_conformance.py), and the durable tests crash a run at every op and resume it. Testing a workflow needs neither: two in-memory handlers serve canned results and replay a recording (wiki/concepts/testing.md).

The handler is the semantics

The op set is the syntax of a small language, and a handler is its transition relation: each op steps the run by an answer from the tape when the tape holds the op's name, and from the world otherwise. Record, replay and the two durable engines are four refinements of that one relation, and for workflows whose rows have distinct ids they are meant to agree on the ledger a run leaves, up to the order in which concurrent branches commit. wiki/concepts/semantics.md states the rules and grades each law: proved in Lean, model-checked in Quint, tested, or open.

Context, evals and telemetry

Each place a workflow meets a model is a named, typed seam that a deployment can tune and meter:

seam what it is read
prompts a t"..." whose interpolations are the context's regions: inputs render in, outputs parse back wiki/concepts/context.md
cache order the stable prefix first, the volatile part last; within a role, render refuses the other order wiki/concepts/context.md
skills a catalog in the cached prefix, a disclosed body in the volatile tail, activated once above a fan-out wiki/concepts/context.md
code and files code a model writes runs as an effect in a sandbox; the coder's shell runs in a container wiki/concepts/context.md
evals judgments, improve over a Pareto frontier, and a recorded run scored again, replayed, or forked at one decision wiki/concepts/evals.md
keys and projections every op's name composed by one grammar; views folded from the append-only ledger wiki/concepts/tapes.md, wiki/concepts/graph.md
telemetry OTLP spans under the OpenTelemetry GenAI conventions, each placed span carrying the key that joins it to the run wiki/concepts/tapes.md

Building with a coding agent

Effective is for building repeatable agentic workflows with a highly capable coding agent such as Claude Code, often from a one-off: a task the agent has done once, whose session telemetry shows the steps to make repeatable. The agent writes the workflow and its tests; a workflow that performs no I/O runs offline against canned answers, and every seam has a backend that runs in the agent's own sandbox (SQLite for the engine, Monty for sandboxed code), so the agent checks its own work with no container, no key and no spend. The person decides what the workflow may do: which calls need approval, what a run may spend, and what an answer must satisfy. Each of those is a value in the code, and a recording or a fork shows the person what the workflow does. docs/co-development.md walks through the three stages, from a first version to a deployment, and the check that closes each.

What's in the box

All under src/effective/ unless noted.

capability where
the op set and the authoring API: step, ask_llm, call_tool, await_event, await_until, sleep_until, append_ledger ops.py, domain.py, api.py
typed prompt channels: render, Gated, Repair, cache and role directives, skill disclosure channels.py, skills.py
identity: every op key composed from a t-string by one injective grammar, and numbered where it repeats, so two positions in a run never share one keys/
concurrency: gather, race, quorum api.py, choice.py
combinators: recurse, route, descend, fixpoint and mutual (loops in constant stack), respawn (a long loop as a chain of tasks), hoisted (a skill activated once above a fan-out), and sandboxed code as an effect (run_code, on Pydantic Monty) combinators.py, code.py, monty.py
judgments: judge and select ask typed questions from a t-string judgment.py, api.py
layers: retry, permission, budgets and telemetry as generator middleware, and govern to compose them layers.py, govern.py
the ReAct agent loop, with a typed answer repaired inside the loop, interrupts, steering and in-flight cancellation react.py, interrupts.py, steering.py, cancel.py
child tasks, and a parent that hears how its child ended spawning.py
permission: a fail-closed cascade of rules and a human permission.py, parked.py
cost: metered model calls, spend caps that survive a crash, a cache cost.py, budget.py, spend.py, cache.py
telemetry: OTLP/JSON spans under the OpenTelemetry GenAI conventions, joined to the run by key telemetry.py
counterfactuals: fork a recorded run at an op, change one result, run the rest live fork.py, counterfactual.py
optimization: improve (reflective prompt evolution) over a Pareto frontier of cost, quality and latency improve.py, pareto.py, and the benches in src/agent/
the read side: a run as a graph, cards, a dashboard, a terminal viewer graph/, cards/, dashboard.py, runview.py, src/tui/
interpreters for ops: OpenAI, the claude -p and codex exec CLIs, a judge service, a shell, the web interpreters/

Not yet in the box

missing where it stands
memory between runs a run's record is durable and forkable, and nothing carries what one run learned into the next; open is whether recall is a recorded op or a layer that fills the prompt, and how a write to memory is authorized
MCP servers as tools an MCP tool would reach the loop through an interpreter for CallTool, under the permission cascade, with its result recorded; not built, and the coding example does not implement them
a deployment from zero a walkthrough from a fresh managed Postgres to a running worker is not written

Examples

run what it is needs
uv run python examples/react_toy.py the agent loop above, driven by a script nothing
uv run python examples/hooks_as_layers.py the audit layer above, around the first workflow nothing
uv run python examples/first_workflow.py the first workflow nothing
uv run examples/smol_agent.py <url> a whole agent in a few lines, ported from Thomas Schranz's smol.clj an OpenAI-compatible Responses endpoint
uv run python examples/smol_durable.py the same house agent, durable and interruptible, with a judge guarding the door (examples/smol_door.py) nothing: offline without keys; OPENAI_API_KEY and JEV_API_KEY for a real model and judge
uv run python -m examples.coder <dir> "<task>" a small coding agent whose test suite decides when the work is done (src/examples/coder/README.md) OPENAI_API_KEY, Podman
uv run python -m examples.deep_research "<question>" cell="..." a frontier search over web leads, stopped when two hosts agree on every cell (src/examples/deep_research/README.md) BRAVE_SEARCH_API_KEY, JEV_API_KEY, the claude CLI
uv run python -m examples.agent_firm sla-cap an accounts-receivable firm: a payment short of its invoice is applied, the credit the contract grants is approved by someone other than its proposer and posted through an ERP port, and what is still owed is supervised (wiki/concepts/agent-firm.md) nothing; --odoo settles on Odoo Community, after just odoo-up
just tui-demo, just dashboard the terminal viewer and the run dashboard over a demo run the tui extra for the viewer

The agent firm

A firm exists, Coase argued in 1937, because some coordination costs less by authority than by negotiating each exchange: work that repeats, and commitments someone must answer for. Agents doing a firm's work face the same trade, so an agent firm gives them an organization: roles that decide, approvals that bind, and a record that outlives any one run.

src/examples/agent_firm/ is an accounts-receivable function run by agents under controls a finance team uses: every action has an owner, an approval where policy requires one, and a record that survives a crash. A payment that matches its invoice is applied with nobody asked. A payment short of its invoice is an exception, and goes through these stages:

stage what happens
admit the run's inputs are fixed in its spawn params: the case, how its settlement is run, the snapshot of the firm's rules
apply the payment is applied to the invoice, and what is still owed is recorded as an obligation, before any model is asked
explain a model proposes a credit through a Gated channel: within the shortfall, citing the case's documents
engage an outside critic reviews the proposal; what the models decide is evidence for the approver
authorize the contract computes the credit, and a govern policy parks it until a ruler within their mandate, other than its proposer, approves it; the ruling names the digest of the terms
act the credit memo is posted and applied through an ERP port; a posting that is undone is posted again in the next generation
supervise a collector task watches the obligation from before the credit's approval, offers it up a ladder of offices when it falls overdue, and asks a write-off of its own mandate, none while a filing's settlement is open, kept only when its memo matches what is owed; the invoice's next settlement replaces a collector that ended while the obligation is unsettled
settle the books firm, a fixpoint, repeats the settlement over every open case until two passes agree, and reports what stays open and why

uv run python -m examples.agent_firm sla-cap settles one case through the first six stages and enqueues its collector in a temporary database the command deletes as it returns (settle(config, kept_in=...) keeps it for a worker); --odoo settles it on Odoo Community after just odoo-up; tests/test_agent_firm_fixpoint.py runs the firm over the books. The decisions are ADR-0027: the settlement, what an approval binds and the fixpoint; the controls and the tests that hold each one are in wiki/concepts/agent-firm.md.

A settlement is a record of its own, so every pass reads where it stands: it ends settled, already granted, exhausted, denied by its mandate, stopped when the models give no usable decision, or contended when other runs hold the period's credits past its retries, or unposted when its invoice was written off first; a posting another run holds leaves it in flight. The firm converges when two passes agree and no open case is one a later pass can move, naming the cases that stay open as its dissent; it answers unconverged when its pass budget runs out first.

flowchart TD
    apply["apply the $70,000 payment"] --> owed["record the $30,000 still owed as an obligation"]
    owed --> collect["a collector is enqueued to supervise it;<br/>no write-off while the credit waits on its ruling"]
    owed --> explain["explain: a model proposes a credit"]
    explain --> critique["critique: the critic reviews it against the contract"]
    critique --> computed["the contract computes the $12,000 credit;<br/>the models' decision is evidence"]
    computed --> gate{"approval: a ruler within their mandate,<br/>other than the proposer"}
    gate -- denied --> open["denied: the case stays open"]
    gate -- approved --> memo["post and apply the $12,000 credit memo"]
    memo --> settled(["settled: $18,000 owed"])
    settled --> successor["a collector that ended is replaced, to supervise the $18,000"]
    memo -- undone --> again["posted again in the next generation"]
Loading

The command scripts the models and the controller's approval, so it needs no keys, and it runs the settled path; the other endings run in tests/test_agent_firm_fixpoint.py and tests/test_agent_firm_resolution.py. The $18,000 still owed stays a receivable, held by accounts receivable as an obligation; the command enqueues its collector, and tests/test_agent_firm_assembly.py runs one up to a write-off its mandate asks. The general ledger the firm settles against in testing is Odoo Community, digest-pinned under Podman: just odoo-up, then just odoo-test with just pgt-up. Without it, a scripted Odoo answers the same calls in memory.

Standing the firm up

A run of the firm is stood up by a config: the case, whether the critic is engaged, the books, the model behind each role, who approves, the budget, and the Odoo password, which the config names by reference and the transport resolves at each call. given binds a name to a typed value, both joins parts that bind different names or agree, and over lays a named layer's values over a base that declares them; the command line's flags are one more layer, and the run admits the config's digest with its manifest. The whole config, ODOO_PASSWORD included, is in src/examples/agent_firm/__main__.py:

FIRM = both(
    given("case", "sla-cap"),
    given("critic", True),
    given("erp", "scripted"),
    given("models.proposer", "scripted"),
    given("models.critic", "scripted"),
    given("approvers", [str(CONTROLLER)]),
    given("budget", None, optional(FLOAT)),
    given("odoo.password", ODOO_PASSWORD),
)
...
NO_CRITIC = over(FIRM, given("critic", False), layer="no-critic")

uv run python examples/configured_firm.py runs it offline, with no keys, and prints what follows. First, the command and what the run did. The example fixes the run's id and abbreviates the approval's digest, the hash of the credit row it approves, for reading:

$ python -m examples.agent_firm sla-cap
asked:     1. [approve-sla-credit] approve this service credit? {'invoice': 'INV-BOB-2026-09', 'period': 'sep-2026', 'amount': '1200000', 'recipient': 'acct:bob-operating', 'revision': '1', 'decided': '1200000', 'cites': 'MSA-BOB', 'dated': '2026-09-28', 'plan': 'sha256-…', 'proposer': 'ar-clerk'}
approved:  govern:firm,with-critic;ledger;credit:bob,api,sep-2026,rev=1 sha256-… by controller
result:    settled credited 12000.00 owed 18000.00 held by accounts-receivable
entry:     invoice 100000.00
entry:     payment 70000.00
entry:     credit-memo 12000.00
owed:      18000.00 on INV-BOB-2026-09
calls:     {'knowledge': 1, 'claimant': 3, 'erp': 6, 'spawn': 2, 'llm': 1, 'critic': 1, 'task-state': 1}

over records its layer in the history of each name it binds. Here it sets critic to False, so the digest, which identifies the config's values, changes too. Two parts that bind one name to two values are refused rather than ordered:

NO_CRITIC = over(FIRM, given("critic", False), layer="no-critic")
history(NO_CRITIC, 'critic') -> ('no-critic',)
digest(FIRM)      -> 93e9afd9be512fa9
digest(NO_CRITIC) -> a5fb28507c69d5ae
both(FIRM, given("critic", False)) -> Conflict: critic is True in one part and False in another

--show prints where each value came from and runs nothing; the password shows as its reference:

$ python -m examples.agent_firm sla-cap --no-critic --show

name value layers
approvers ["controller"] base
budget null base
case "sla-cap" cli
critic false cli
erp "scripted" base
models.critic "scripted" base
models.proposer "scripted" base
odoo.password {"scope": "firm", "name": "odoo", "purpose": "erp"} base

digest a5fb28507c69d5ae

The run's tape, drawn by effective.graph: one node per recorded step, named by its op, with the ledger's rows as cylinders named by their event and its read as a rounded box. Every row belongs to the one settlement, INV-BOB-2026-09 paid by PAY-BOB-70, which the names leave out. The dashed step is the one only the critic's run takes, the critic's review:

graph TD
  n0["knowledge:main"]
  n1[("settlement")]
  n2(["ledger-read settlement-attempt-ended;paid:INV-BOB-2026-09"])
  n3["tool:claimant"]
  n4[("settlement-attempt")]
  n5["tool:apply-cash"]
  n6(["ledger-read obligation:INV-BOB-2026-09"])
  n7["tool:statement"]
  n8[("obligation:INV-BOB-2026-09")]
  n9(["ledger-read obligation:INV-BOB-2026-09#2"])
  n10(["ledger-read obligation:INV-BOB-2026-09"])
  n11["tool:statement#2"]
  n12[("dispute:INV-BOB-2026-09")]
  n13(["ledger-read obligation:INV-BOB-2026-09#3"])
  n14(["ledger-read obligation:INV-BOB-2026-09"])
  n15(["ledger-read obligation-supervised:INV-BOB-2026-09"])
  n16["tool:claimant#2"]
  n17[("obligation-supervisor:INV-BOB-2026-09")]
  n18["spawn:collect"]
  n19[("obligation-supervised:INV-BOB-2026-09")]
  n20["llm:explain"]
  n21["llm:engage"]
  n22[("settlement-decision")]
  n23(["ledger-read credit:bob"])
  n24[("claim:bob")]
  n25(["ledger-read credit:bob"])
  n26[("approval-asked:firm")]
  n27[("approval-ruled:firm")]
  n28[("credit:bob")]
  n29(["ledger-read obligation:INV-BOB-2026-09#4"])
  n30(["ledger-read obligation:INV-BOB-2026-09"])
  n31(["ledger-read obligation:INV-BOB-2026-09"])
  n32(["ledger-read obligation:INV-BOB-2026-09"])
  n33(["ledger-read obligation:INV-BOB-2026-09"])
  n34(["ledger-read obligation:INV-BOB-2026-09"])
  n35(["ledger-read credit:bob"])
  n36(["ledger-read sla-posted:bob"])
  n37[("sla-generation:bob")]
  n38["tool:post-credit"]
  n39["tool:apply-credit"]
  n40[("sla-posted:bob")]
  n41(["ledger-read obligation:INV-BOB-2026-09#5"])
  n42(["ledger-read obligation:INV-BOB-2026-09"])
  n43(["ledger-read obligation:INV-BOB-2026-09"])
  n44(["ledger-read obligation:INV-BOB-2026-09"])
  n45(["ledger-read obligation:INV-BOB-2026-09"])
  n46(["ledger-read obligation:INV-BOB-2026-09"])
  n47["tool:statement#3"]
  n48[("obligation:INV-BOB-2026-09")]
  n49[("dispute-resolved")]
  n50(["ledger-read notice:INV-BOB-2026-09"])
  n51(["ledger-read notice:INV-BOB-2026-09"])
  n52[("notice:INV-BOB-2026-09")]
  n53(["ledger-read obligation:INV-BOB-2026-09#6"])
  n54(["ledger-read obligation:INV-BOB-2026-09"])
  n55(["ledger-read obligation:INV-BOB-2026-09"])
  n56(["ledger-read obligation:INV-BOB-2026-09"])
  n57(["ledger-read obligation:INV-BOB-2026-09"])
  n58(["ledger-read obligation:INV-BOB-2026-09"])
  n59(["ledger-read obligation:INV-BOB-2026-09"])
  n60(["ledger-read obligation-supervised:INV-BOB-2026-09#2"])
  n61(["ledger-read obligation-supervised:INV-BOB-2026-09"])
  n62["tool:task-state"]
  n63["tool:claimant#3"]
  n64[("obligation-supervisor:INV-BOB-2026-09")]
  n65["spawn:collect#2"]
  n66[("obligation-supervised:INV-BOB-2026-09")]
  n67[("settlement-attempt-ended")]
  n68[("settlement-ended")]
  n69(["ledger-read obligation:INV-BOB-2026-09#7"])
  n70(["ledger-read obligation:INV-BOB-2026-09"])
  n71(["ledger-read obligation:INV-BOB-2026-09"])
  n72(["ledger-read obligation:INV-BOB-2026-09"])
  n73(["ledger-read obligation:INV-BOB-2026-09"])
  n74(["ledger-read obligation:INV-BOB-2026-09"])
  n75(["ledger-read obligation:INV-BOB-2026-09"])
  n76(["ledger-read obligation:INV-BOB-2026-09#8"])
  n77(["ledger-read obligation:INV-BOB-2026-09"])
  n78(["ledger-read obligation:INV-BOB-2026-09"])
  n79(["ledger-read obligation:INV-BOB-2026-09"])
  n80(["ledger-read obligation:INV-BOB-2026-09"])
  n81(["ledger-read obligation:INV-BOB-2026-09"])
  n82(["ledger-read obligation:INV-BOB-2026-09"])
  n83(["ledger-read obligation-supervised:INV-BOB-2026-09#3"])
  n84(["ledger-read obligation-supervised:INV-BOB-2026-09"])
  n85(["ledger-read obligation-supervised:INV-BOB-2026-09"])
  n0 --> n1
  n1 --> n2
  n2 --> n3
  n3 --> n4
  n4 --> n5
  n5 --> n6
  n6 --> n7
  n7 --> n8
  n8 --> n9
  n9 --> n10
  n10 --> n11
  n11 --> n12
  n12 --> n13
  n13 --> n14
  n14 --> n15
  n15 --> n16
  n16 --> n17
  n17 --> n18
  n18 --> n19
  n19 --> n20
  n20 --> n21
  n21 --> n22
  n22 --> n23
  n23 --> n24
  n24 --> n25
  n25 --> n26
  n26 --> n27
  n27 --> n28
  n28 --> n29
  n29 --> n30
  n30 --> n31
  n31 --> n32
  n32 --> n33
  n33 --> n34
  n34 --> n35
  n35 --> n36
  n36 --> n37
  n37 --> n38
  n38 --> n39
  n39 --> n40
  n40 --> n41
  n41 --> n42
  n42 --> n43
  n43 --> n44
  n44 --> n45
  n45 --> n46
  n46 --> n47
  n47 --> n48
  n48 --> n49
  n49 --> n50
  n50 --> n51
  n51 --> n52
  n52 --> n53
  n53 --> n54
  n54 --> n55
  n55 --> n56
  n56 --> n57
  n57 --> n58
  n58 --> n59
  n59 --> n60
  n60 --> n61
  n61 --> n62
  n62 --> n63
  n63 --> n64
  n64 --> n65
  n65 --> n66
  n66 --> n67
  n67 --> n68
  n68 --> n69
  n69 --> n70
  n70 --> n71
  n71 --> n72
  n72 --> n73
  n73 --> n74
  n74 --> n75
  n75 --> n76
  n76 --> n77
  n77 --> n78
  n78 --> n79
  n79 --> n80
  n80 --> n81
  n81 --> n82
  n82 --> n83
  n83 --> n84
  n84 --> n85
  classDef critic stroke-width:3px,stroke-dasharray:4 2
  class n21 critic
Loading

Both runs' books are the same: the critic changes what the models decide, which the approver reads beside the credit, and the contract fixes the credit itself.

run credit memo still owed
the critic 12000.00 18000.00
no critic 12000.00 18000.00

Learn more

read for
docs/intro.md the model in ten minutes: generator, handler, tape, layers, combinators
docs/first-workflow.md the first workflow, line by line
wiki/concepts/testing.md testing a workflow, and how the substrate is verified: crash at every op, two engines, schedules, models and proofs
docs/effective-101.md the concepts in depth: the op set, the combinator algebra, the temporal shapes
wiki/concepts/semantics.md the handler as the transition relation, and how each law is known
wiki/concepts/rosetta.md DSPy, Pydantic AI and LangGraph, term by term, with a DSPy module ported
docs/co-development.md building a workflow with a coding agent, stage by stage
wiki/index.md one concept a page, and the index of architecture decisions
wiki/references.md the work Effective builds on: Recursive Language Models, GEPA, ReAct, Absurd, tdom and more

Requirements

need for
uv and git everything; uv installs the pinned Python 3.14 (.python-version)
just the recipes; just alone lists them
rootless Podman the durable lane (a digest-pinned Postgres), Odoo Community for the AR firm, the coder's sandbox, rendering diagrams, the sandboxed formal checks
elan (Lean), node and npm, a JDK 17+ the formal gates only (just formal-setup, just formal)
extra for
tui the terminal viewer (textual, rich)
judge the Jev judge interpreter
bridge the arrivals bridge (redis)
coding the lint and the coding machine's tools (ast-grep)
binary psycopg with its own libpq, for a machine without one

Contributing

just check        # the gate: lint, ty, the docs and key checks, the suite
just pgt-up       # the test Postgres under Podman, for the durable lane
just formal       # Lean proofs and the Quint typecheck
just odoo-up      # Odoo Community under Podman; with `pgt-up`, `just odoo-test` runs the AR firm against it

How the substrate is verified, from crash sweeps to the formal models, is on the testing page (wiki/concepts/testing.md).

Run just check from a git clone: its docs gate reads git ls-files. Without a test Postgres, it skips the Postgres-backed tests and runs everything else. AGENTS.md is the contributor guide, for people and coding agents alike: the layout, every recipe, the invariants and the code-prose rules.

License

MIT. See LICENSE. Copyright (c) 2026 Jim Baker.

About

Durable, replayable agentic workflows in Python: algebraic effects as composable generators, PEP 750 t-strings as typed prompt channels.

Topics

Resources

Stars

7 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages