Metadata-Version: 2.4
Name: deed-runtime
Version: 0.1.2
Summary: Contractual runtime for AI agents — pre/post contracts, policy enforcement, credits metering, checkpoint & replay
License: MIT
Project-URL: Homepage, https://deed-docs.onrender.com/
Project-URL: Repository, https://github.com/Deadly-Reiter/deed
Project-URL: Documentation, https://deed-docs.onrender.com/
Project-URL: Bug Tracker, https://github.com/Deadly-Reiter/deed/issues
Keywords: ai,agents,contracts,orchestration,llm,policy,safety
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# DEED

> Contractual runtime for AI agents.

```
pip install deed-runtime
```

Zero dependencies. Python 3.10+.

---

## The problem

Your AI agent ran. Something unexpected happened.
No pre-conditions checked. No audit trail. No rollback.

## The answer

Every action passes through a contract:

```
agent score_agent
  contract score_contract
    pre  company_name_present
    post score_generated

  policy
    cap  budget_tokens <= 5000
    deny score_company if region == "restricted"
    allow score_company if company_name_present
```

- Pre-condition fails → action rejected, no side effects, no credits charged
- Post-condition fails → DLQ entry written, credits refunded
- Policy violation → blocked before execution

## Five lines

```python
from deed import DeedRuntime

runtime = DeedRuntime(".")
runtime.register("score_company", my_scorer, charge=1)
result = runtime.run("my_pipeline", "input/state.json")
print(result["score"])  # 0.82
```

## What you get

- **Pre/post contracts** on every agent action
- **Policy engine** (cap / allow / deny) enforced before execution
- **DEED Credits metering** — charge per deed, refund on violation
- **Checkpoint & replay** — resume from last known good state
- **DLQ** — failed stages captured with full context

---

## Examples

### Mushroom Safety Triage — main working example

A four-stage safety-critical pipeline demonstrating contracts and the failure path.

```bash
cd examples/mushroom_safety
python run.py           # happy path → completed
python run.py --fail    # ContractViolation → DLQ
```

Stages: `intake → taxonomy → risk → advisory`

---

### Sales Intelligence Agent — working example

A three-stage B2B sales pipeline with ICP scoring and outreach brief generation.

```bash
cd examples/sales_agent
python run.py               # happy path → completed, score 1.0
python run.py --restricted  # policy deny → failed (region == "restricted")
```

Stages: `enrich → score → brief`

---

### Orchid Rescue Lab — .dd reference only

Agent specs and pipeline for a conservation triage workflow.
No `run.py` — use the `.dd` files as reference for writing your own vertical.

```
examples/orchid_rescue/
├── deeds/agents/       legality_agent.dd, triage_agent.dd, curator_agent.dd
└── deeds/pipelines/    orchid_rescue_intelligence.dd
```

---

## How `register()` works

```python
runtime = DeedRuntime(
    project_root=".",           # must contain deeds/ with .dd files
    initial_credits=100,
    named_predicates_fn=my_fn,  # optional: callable(context) -> dict[str, bool]
)

(runtime
    .register("normalize",    normalize_fn,  charge=1)
    .register("score",        score_fn,      charge=1, retry=2)
    .register("send_alert",   alert_fn,      charge=1, idempotency_key="alert_id")
)

result = runtime.run("my_pipeline", "input/state.json")
```

---

## .dd syntax

```
agent my_agent
  capabilities ["action_a", "action_b"]

  contract my_contract
    pre  input_present
    post result_generated

  policy
    cap  budget_tokens <= 3000
    deny action_b if region == "restricted"
    allow action_a if input_present

pipeline my_pipeline
  stage step_one
    agent my_agent
    -> action_a()
    checkpoint after
    on_error retry

  stage step_two
    agent my_agent
    -> action_b()
    on_error deadletter
```

---

## Error types

```python
from deed import ContractViolation, PolicyViolation, DeedError

try:
    result = runtime.run("my_pipeline", "input/state.json")
except ContractViolation as e:
    # pre or post condition failed
    # pre: action was NOT executed, no credits charged
    # post: action ran but outcome invalid, credits refunded
    print(e)
except PolicyViolation as e:
    # cap / deny / allow rule blocked the action
    # action was NOT executed, no credits charged
    print(e)
```

---

## Replay after failure

```python
# Resume from last checkpoint — skips completed steps, credits not re-charged
runtime = DeedRuntime(".", replay=True, initial_credits=100, ...)
runtime.register(...)
result = runtime.run("my_pipeline", "input/state.json")
```

---

## Writing .dd files with an LLM

`docs/MASTER_MANUAL_FOR_LLM.md` is a complete authoring guide for generating `.dd` files.
Use it as a system prompt to make any LLM produce idiomatic DEED agent specs from a domain description.

Includes: canonical model, naming conventions, anti-patterns, few-shot examples, validation checklist, templates for agent and pipeline blocks.

---

## DEED Credits

Every deed execution costs credits (default: 1 credit per action, configurable per `register()`).

```python
print(runtime.x402.credits)   # remaining balance
print(runtime.x402.spent)     # total spent this run
```

Credits are charged after the pre-condition passes and refunded automatically on post-condition failure. The metering layer uses the `X402Client` interface, which is designed for forward compatibility with the [x402 payment protocol](https://x402.org).

---

## Docs

**[deed-docs.onrender.com](https://deed-docs.onrender.com)**

## License

MIT — [Deadly-Reiter](https://github.com/Deadly-Reiter/deed)
