Skip to content

Reference Index

This page is the compact reference entrypoint. Start with Quickstart if you are new to CaseGraph.

Package Install

The package name is casegraph. PyPI publication has not happened yet; local release validation builds and checks wheel plus source-distribution artifacts.

Base installs support the first workflow without provider, server, or framework extras. Install extras only when needed:

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

Release Operations

CaseGraph has a guarded release path, but no PyPI publication has happened yet. Release artifacts are built locally with:

make release-build
make release-check
make release-smoke

release-check verifies the static pyproject.toml version, release tag policy, exactly one wheel and one source distribution, packaged migrations, scaffold/reference resources, forbidden cache paths, and twine check.

GitHub release publishing uses PyPI Trusted Publishing through GitHub Actions OIDC. The workflow is .github/workflows/release.yml; it publishes only from protected testpypi or pypi environments and does not use PyPI username/password/token secrets. Configure PyPI Trusted Publishing with:

  • repository: Symblee/CaseGraph
  • workflow: release.yml
  • environment: pypi
  • package/project name: casegraph

Use TestPyPI as a dry-run target. If the real PyPI project does not exist yet, first publication should use PyPI's pending publisher setup for the casegraph project.

CLI

casegraph init intake_review --output .casegraph/intake_review_pack --json
casegraph db check --json
casegraph db upgrade --json
casegraph cases inspect <case-id> --json
casegraph packs scaffold --kind transactional --pack-id my_transactional --output .casegraph/my_transactional_pack --json
casegraph packs validate --pack-root .casegraph/my_transactional_pack --json
casegraph packs author-check --pack-root .casegraph/my_transactional_pack --json
casegraph packs adapter-dry-run --pack-root .casegraph/covered_system_pack --json
casegraph packs adapter-preflight --pack-root .casegraph/covered_system_pack --mode dry_run --json
casegraph cover inspect ./path --entrypoint module:object --json
casegraph cover scaffold --from .casegraph/cover/latest.json --output .casegraph/covered_system_pack --json
casegraph cover suggest --pack-root .casegraph/covered_system_pack --output cover-review.suggested.yaml --json
casegraph cover boundaries suggest --pack-root .casegraph/covered_system_pack --output cover-boundaries.suggested.yaml --json
casegraph cover boundaries review template --pack-root .casegraph/covered_system_pack --suggestions cover-boundaries.suggested.yaml --output cover-boundaries.review.yaml --json
casegraph cover boundaries review apply --pack-root .casegraph/covered_system_pack --mapping-file cover-boundaries.review.yaml --json
casegraph cover review template --pack-root .casegraph/covered_system_pack --output cover-review.yaml --json
casegraph cover review apply --pack-root .casegraph/covered_system_pack --mapping-file cover-review.yaml --json
casegraph demo seed --json

First Workflow Edit Loop

After casegraph init, edit:

  • src/<package>/workers.py for recorded evidence.
  • src/<package>/actions.py for local/fake action input, preview, receipt, verification, and compensation.
  • src/<package>/capabilities.py for proposal wording, policy rule id, and action wiring.

Then run:

casegraph packs validate --pack-root .casegraph/intake_review_pack --json
casegraph packs author-check --pack-root .casegraph/intake_review_pack --json
python .casegraph/intake_review_pack/developer_api_demo.py
casegraph cases inspect <case-id> --json

Case Inspection

Use this after a generated demo prints case_id=...:

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

The report summarizes worker evidence, proposal actions, preview diffs, policy status, commit status, replay health, and recent timeline events. The same compact read model is available at GET /cases/<case-id>/inspection?timeline_limit=12.

Browser Pack Registration

Generated/custom pack execution in the browser requires explicit API startup registration:

CASEGRAPH_PACK_ROOTS=.casegraph/intake_review_pack \
  uv run --all-groups --python 3.13 uvicorn casegraph.api.app:app --reload

CASEGRAPH_PACK_ROOTS accepts one or more pack roots separated with the platform path separator. The browser reads GET /packs, opens generated demo cases through POST /packs/<engine-id>/<engine-version>/demo-case, and then runs the existing case operator routes. Unregistered generated/custom cases remain read-only and show registration guidance.

Database

CaseGraph uses Postgres to persist append-only case events and replayable graph projections:

casegraph db check --json
casegraph db upgrade --json

If Postgres is unreachable, start the repo dev database with docker compose up -d postgres or set CASEGRAPH_DATABASE_URL.

Cover Inspect

Use cover when you already have an agentic codebase and want reviewable migration artifacts before writing wrappers. Inspection is static only: no imports, providers, generated packs, or trusted semantics.

casegraph cover inspect ./existing_system --entrypoint module:object --json

Reports are written under .casegraph/cover/. cover scaffold turns that report into a read-only draft pack:

casegraph cover scaffold --from .casegraph/cover/latest.json --output .casegraph/covered_system_pack --json

The draft pack should validate; author-check is expected to fail until reviewed mappings are applied:

casegraph cover review status --pack-root .casegraph/covered_system_pack --json
casegraph cover suggest --pack-root .casegraph/covered_system_pack --output cover-review.suggested.yaml --json
casegraph cover boundaries suggest --pack-root .casegraph/covered_system_pack --output cover-boundaries.suggested.yaml --json
casegraph cover review template --pack-root .casegraph/covered_system_pack --output cover-review.yaml --json
casegraph cover review apply --pack-root .casegraph/covered_system_pack --mapping-file cover-review.yaml --json
casegraph cover boundaries review template --pack-root .casegraph/covered_system_pack --suggestions cover-boundaries.suggested.yaml --output cover-boundaries.review.yaml --json
casegraph cover boundaries review apply --pack-root .casegraph/covered_system_pack --mapping-file cover-boundaries.review.yaml --json
casegraph packs author-check --pack-root .casegraph/covered_system_pack --json

Suggestions are inert until a developer promotes mappings. Boundary review can generate helper-backed local/fake actions.py, capabilities.py, engine action_ids, dry-run external_adapters.py, tests, and a full demo without executing inspected code.

After boundary review apply, run the adapter harness:

casegraph packs adapter-dry-run --pack-root .casegraph/covered_system_pack --json
casegraph packs adapter-preflight --pack-root .casegraph/covered_system_pack --mode dry_run --json
CASEGRAPH_ALLOW_REAL_ADAPTERS=1 casegraph packs adapter-preflight --pack-root .casegraph/covered_system_pack --mode real --policy external-adapter-policy.yaml --json

The harness checks preview, apply, verify, idempotency, and compensation. adapter-preflight is guardrail-only and writes .casegraph/adapter-preflight/.

Real external adapter execution has no standalone CLI. A pack author wires explicit real adapter code with authorize_external_real_execution(...) and build_external_real_callbacks(...); execution happens only through EngineHost.commit(...) after proposal, preview, policy, and approval.

Reviewed cover packs also include inert REAL_ADAPTER_RUNBOOK.md, templates/real_external_adapters.py, templates/real_capabilities.py, and templates/real_developer_api_demo.py.

API

The FastAPI app exposes case, graph, runtime, proposal, preview, policy, approval, commit, model-run, timeline, and replay routes.

Start locally:

uv run --all-groups --python 3.13 uvicorn casegraph.api.app:app --reload
curl http://127.0.0.1:8000/health
curl http://127.0.0.1:8000/cases

Use the API for service integration. Use the Python Developer API for the shortest local programming path.

Model Calls

Model calls are server-side and opt-in. Local live checks require:

OPENAI_API_KEY=...
CASEGRAPH_RUN_LIVE_OPENAI=1

Provider-free checks remain the default:

casegraph model-evals run --suite support_escalation --backend fake --json

Troubleshooting

  • Missing tables: run docker compose up -d postgres and casegraph db upgrade --json.
  • Port conflict: start Uvicorn with --port 8001 and point Vite at that API.
  • Missing provider key: use fake/default paths or set OPENAI_API_KEY.
  • Replay drift: inspect the replay result and event timeline for the affected case.