Metadata-Version: 2.5
Name: agentcrash-core
Version: 0.2.0
Summary: Installable reliability framework for agentic workflows
Requires-Python: >=3.11
Requires-Dist: jsonschema
Requires-Dist: pyyaml
Provides-Extra: dev
Requires-Dist: black; extra == 'dev'
Requires-Dist: dspy; extra == 'dev'
Requires-Dist: fastapi; extra == 'dev'
Requires-Dist: numpy>=1.26; extra == 'dev'
Requires-Dist: pyshacl; extra == 'dev'
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Requires-Dist: uvicorn; extra == 'dev'
Provides-Extra: host-odrl
Requires-Dist: dspy; extra == 'host-odrl'
Requires-Dist: numpy>=1.26; extra == 'host-odrl'
Requires-Dist: pyshacl; extra == 'host-odrl'
Provides-Extra: server
Requires-Dist: fastapi; extra == 'server'
Requires-Dist: uvicorn; extra == 'server'
Description-Content-Type: text/markdown

# agentcrash-core — Reliability framework for agentic workflows

`agentcrash-core` (import package `agentcrash`) is the reusable core
extracted from the AgentCrash reliability project. It observes host
workflows without owning them: buffered SDK instrumentation, a
versioned event schema, domain-free invariants, deterministic fault
injection, and a loopback control plane (Lab + `/v1` API).

Domain workflows live in their own repos and depend on this package —
e.g. the NL-to-ODRL agent in
[`nl2odrl-responsible-ai`](https://github.com/SahilSatyam/nl2odrl-responsible-ai).
Any agentic workflow can do the same.

## Install

```bash
pip install agentcrash-core            # SDK + control-plane client
pip install "agentcrash-core[server]"  # control-plane service extras
```

## Use it in your workflow

```python
from agentcrash import AgentCrash, WorkflowConfig

ac = AgentCrash(WorkflowConfig(project="my-workflow", fault_injection=True))

with ac.run(name="my-run") as run:
    with run.step("my-step"):
        ...  # your business logic; AgentCrash never orchestrates it
```

Disabled mode (`AGENTCRASH_DISABLED=1`) turns every call into a no-op
passthrough, so hosts work with or without the framework installed.

## Judge a trace

```bash
# verify registry invariants against an SDK-schema JSONL trace
agentcrash check --trace run.jsonl --invariant required_step:my-step --report-out verdict.json

# run the control plane (Lab + /v1 API, local only)
agentcrash serve --port 8901
```

Hosts register their own invariants (e.g. `odrl_valid`,
`exactly_once_save`) alongside the generic core checks
(`required_step:*`, `duplicate_mutating_effect`, `fresh_write_only`,
`no_lost_update`).

## Core principle

**Model-generated diagnosis is strictly separated from deterministic
verification.** The model can explain a failure and propose candidate
policy edits, but independent checks against recorded trace events and
environment state determine whether a run passes or fails.

## Develop

Prerequisites: WSL Ubuntu-24.04, Python 3.11+, `uv`.

```bash
git clone https://github.com/SahilSatyam/AgentCrash.git && cd AgentCrash
uv venv && uv pip install -e ".[dev]"
pytest -q
```

## Layout

- `src/agentcrash/` — `sdk`, `events`, `invariants`, `evaluate`,
  `server`, `verifiers` (registry + generic checks), `tracer`,
  `clock`, `injector`, `ledger`, `policy`, `scan_pii`, `db`,
  `lab/` (control-plane UI assets), `schemas/` (bundled policy schemas)
- `examples/minimal_agent/` — second-app sample with zero domain imports
- `examples/README.md` — writing your own host

## Docs

See [`docs/`](docs/) — start with
[`docs/architecture-decoupling.md`](docs/architecture-decoupling.md),
which defines the core/host boundary.
