Quickstart

Build, edit, check, and rerun your first CaseGraph workflow.

The goal is not to learn every CaseGraph surface. The first loop is:

create workflow -> upgrade DB -> run demo -> edit worker/action -> validate -> rerun demo -> inspect

When working from this repo, prefix product commands with uv run --all-groups --python 3.13. Installed usage is the plain casegraph CLI. The package name is casegraph; PyPI publication has not happened yet. Current release validation uses built wheel and source-distribution artifacts.

If you are testing a checked local wheel:

uv pip install dist/casegraph-*.whl

1. Create A Workflow

casegraph init intake_review --output .casegraph/intake_review_pack --json

From the repo checkout:

uv sync --all-groups --python 3.13
uv run --all-groups --python 3.13 casegraph init intake_review \
  --output .casegraph/intake_review_pack \
  --json

Expected fragments:

{
  "workflow_id": "intake_review",
  "ready": true,
  "worker_edit_path": ".casegraph/intake_review_pack/src/casegraph_intake_review/workers.py",
  "action_edit_path": ".casegraph/intake_review_pack/src/casegraph_intake_review/actions.py",
  "check_command": "casegraph packs author-check --pack-root .casegraph/intake_review_pack --json",
  "scaffold": {
    "kind": "transactional",
    "action_kind": "mark_intake_ready"
  }
}

casegraph init creates a transactional pack, then immediately runs casegraph packs validate and casegraph packs author-check for you.

2. Prepare The Case Database

CaseGraph uses Postgres because cases are persisted as append-only events and replayable graph projections.

For local repo development:

docker compose up -d postgres
uv run --all-groups --python 3.13 casegraph db upgrade --json

Installed usage is:

casegraph db upgrade --json

If Postgres is unreachable, run docker compose up -d postgres or set CASEGRAPH_DATABASE_URL. You can check readiness without upgrading:

casegraph db check --json

3. Run The Generated Workflow

python .casegraph/intake_review_pack/developer_api_demo.py

Expected output:

worker=intake_reviewer
proposal_action=mark_intake_ready
policy_status=auto
commit_status=committed
replay_status=in_sync
inspect_command=casegraph cases inspect <case-id> --json

That output means the worker recorded evidence, CaseGraph proposed a typed action, policy allowed it, local/fake commit execution recorded a receipt, and replay rebuilt the graph from events.

4. Make One Worker Edit

Open:

.casegraph/intake_review_pack/src/casegraph_intake_review/workers.py

Find _review_intake(...) and change the generated claim text:

claim="The intake record has enough evidence to be marked ready.",

Workers are normal Python functions marked with @worker(...). context.step(...) records named internal work. Keep the generated source, tool call, observation, and claim together unless you are intentionally changing what evidence the worker emits.

5. Make One Action Edit

Open:

.casegraph/intake_review_pack/src/casegraph_intake_review/actions.py

Find preview_mark_intake_ready(...) and change the preview summary:

summary="Preview the edited intake readiness transition.",

Use actions.py for local/fake transactional behavior:

Callback	What it controls
mark_intake_ready_input	Typed action input proposed from case metadata.
preview_mark_intake_ready	Before/after diff shown before commit.
apply_mark_intake_ready	Local/fake commit receipt.
verify_mark_intake_ready	Deterministic verification result.
compensate_mark_intake_ready	Local/fake compensation on forced failure.

Use capabilities.py later for proposal wording, policy rule id, and action wiring.

6. Check Edits

casegraph packs validate --pack-root .casegraph/intake_review_pack --json
casegraph packs author-check --pack-root .casegraph/intake_review_pack --json

validate checks pack structure. author-check renders prompts, imports the pack, dry-runs the worker, and checks transactional helper wiring.

7. Rerun The Workflow

python .casegraph/intake_review_pack/developer_api_demo.py

The same output fragments should still appear:

worker=intake_reviewer
proposal_action=mark_intake_ready
policy_status=auto
commit_status=committed
replay_status=in_sync
inspect_command=casegraph cases inspect <case-id> --json

8. Inspect What Happened

Use the case_id printed by the demo:

casegraph cases inspect <case-id> --json

The inspection report is the first debugging surface. It summarizes worker evidence, proposal actions, preview diffs, policy status, commit receipt status, recent timeline events, and replay health without making you read raw graph events. Human output is useful locally:

casegraph cases inspect <case-id> --timeline-limit 12

Open the Browser Casefile later for a visual operator flow. Start the API with CASEGRAPH_PACK_ROOTS=.casegraph/intake_review_pack, click the registered workflow, open its demo case, then run the same worker/proposal/policy/commit sequence in the browser.

Optional Extras

The base install supports this first workflow. Add extras only when you need provider, server, or framework surfaces:

uv add "casegraph[openai]"
uv add "casegraph[server]"
uv add "casegraph[pydantic-ai]"

Read Core Concepts if the vocabulary is unclear, Developer API for the Python flow, or Pack Authoring for generated file responsibilities.