Core Concepts¶

CaseGraph changes the unit of work from an agent run to a case.

A normal agent workflow often hides important decisions inside a run log. CaseGraph makes those decisions explicit so a developer can inspect, test, approve, commit, and replay them.

Case¶

A case is the durable unit of work. It has an intent, a contract, unresolved gaps, events, and a projected graph.

You create one with:

case = host.open_case(...)

Worker¶

A worker investigates one part of the case. It records evidence as source refs, tool calls, observations, and claims. A worker should not directly mutate external systems.

Greenfield workers use the @worker(...) decorator:

@worker(id="intake_reviewer", resolves="intake")
def review_intake(context: WorkerContext) -> WorkerOutput:
    ...

You run workers with:

run = host.run(case, max_steps=1)

Pack¶

A pack is your workflow package. It tells CaseGraph which engine specs, workers, prompts, actions, and capabilities belong together.

Generated packs live outside src/casegraph; they are user code, not CaseGraph core.

Frontier And Gaps¶

The frontier is what the case still needs. A gap is one unresolved item, such as missing intake evidence or an unreviewed incident risk.

Workers consume gaps and produce evidence.

Evidence¶

Evidence is the typed record of what happened during investigation:

source refs identify where information came from;
tool calls record local or external lookups;
observations record facts found by the worker;
claims record conclusions supported by observations.

Worker Step¶

A worker step is a named operation inside a larger worker. Use it when a worker does more than one thing and you want the case to show the internal shape of the investigation.

with context.step("review_intake", input_summary=metadata) as step:
    review = review_intake(metadata)
    step.output_summary(review)
    step.observation(...)
    step.claim(...)

CaseGraph records the step as provenance using the same source ref, tool call, observation, claim, and worker-run records. It does not persist raw local variables automatically.

Proposal¶

A proposal suggests a case-changing action without executing it.

proposal = host.generate_proposal(case)

Preview¶

A preview records the expected before/after change for proposed actions.

preview = host.preview(case, proposal)

Policy And Approval¶

Policy decides whether a preview is allowed, blocked, or ready for approval. Approval records the operator decision.

assessment = host.assess_policy(case, preview)
approval = host.approve_all(case, assessment)

Commit¶

A commit records plan, attempt, receipt, verification, and optional compensation. In the current starter packs this is local/fake execution, not a real external write.

result = host.commit(case, approval)

Replay¶

Replay rebuilds the case from append-only events and checks the projected graph.

replay = host.replay(case)

replay_status=in_sync is the first health signal that the workflow is auditable.