Metadata-Version: 2.5
Name: actiongraph-ai
Version: 0.3.0
Summary: The open decision record for AI agents: playbook, evidence, rules, earned autonomy, approvals, outcomes, flows and MCP.
Project-URL: Homepage, https://github.com/actiongraphai/actiongraph
Project-URL: Source, https://github.com/actiongraphai/actiongraph
Project-URL: Issues, https://github.com/actiongraphai/actiongraph/issues
Project-URL: Changelog, https://github.com/actiongraphai/actiongraph/blob/main/CHANGELOG.md
Author: ActionGraph contributors
License: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Keywords: agentops,ai-agents,approvals,audit,decision-record,governance,human-in-the-loop,mcp
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: FastAPI
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.11
Requires-Dist: fastapi>=0.110
Requires-Dist: numpy>=1.26
Requires-Dist: pydantic>=2.5
Requires-Dist: pyyaml>=6.0
Requires-Dist: sqlalchemy>=2.0
Requires-Dist: uvicorn>=0.27
Provides-Extra: llm
Requires-Dist: anthropic>=1.0; extra == 'llm'
Provides-Extra: postgres
Requires-Dist: psycopg[binary]>=3.1; extra == 'postgres'
Provides-Extra: test
Requires-Dist: httpx>=0.27; extra == 'test'
Requires-Dist: pytest>=8; extra == 'test'
Description-Content-Type: text/markdown

<p align="center">
  <img src="docs/banner.svg" width="800" alt="ActionGraph: every decision remembered, every action earned. Ask, record why, a person approves, outcome, earned autonomy.">
</p>

<h1 align="center">ActionGraph</h1>

<p align="center"><b>Every decision remembered. Every action earned.</b><br>
The open-source memory and conscience for AI agents.</p>

<p align="center">
<a href="https://github.com/actiongraphai/actiongraph/actions/workflows/ci.yml"><img src="https://github.com/actiongraphai/actiongraph/actions/workflows/ci.yml/badge.svg" alt="ci"></a>
<a href="https://pypi.org/project/actiongraph-ai/"><img src="https://img.shields.io/pypi/v/actiongraph-ai" alt="PyPI"></a>
<img src="https://img.shields.io/badge/python-3.11%20%7C%203.12-blue" alt="Python">
<a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-blue" alt="License"></a>
</p>

---

## Intelligence is cheap now. Trust isn't.

For the first time, software can decide. It can issue the refund, roll back the deploy, grant the access, reroute the
truck. The models are ready. The world isn't, because nobody can answer three simple questions about an agent:

1. **Should it be allowed to do this?**
2. **Why did it do that?**
3. **Has it earned the right to do it alone?**

Today the answer is a toggle someone flipped and a log nobody reads. That's why most agents still wait for a human to
click "OK" on every action, and why the ones that don't keep their builders up at night.

**ActionGraph answers those three questions with evidence.** Before an agent acts, it asks. It gets the options your
rules allow, ranked by what actually worked in cases like this. It records what it chose and why. A person approves
where it matters. The outcome comes back and is graded. And autonomy, the right to act alone, is earned one proven
decision at a time, and taken back the moment results slip.

```
ask  ──▶  record why  ──▶  person approves  ──▶  outcome  ──▶  earned autonomy
 ▲                                                                   │
 └──────────────────────── every decision makes the next one smarter ┘
```

## Imagine a world that runs on ActionGraph

Every hospital, bank, airline and factory runs on decisions: millions a day, each one made, mostly forgotten, rarely
measured. Now imagine every one of them, whether made by a person or an agent, landing in an open, shared record of
*what was decided, why, by whom, and whether it worked.*

- **Companies stop forgetting.** When your best claims adjuster retires, their judgement doesn't leave with them.
  Ten thousand of their decisions, with outcomes, train the next adjuster and the next agent.
- **Trust becomes measurable.** "Can this agent approve refunds under $200?" stops being a meeting and becomes a
  number: *worked 412 of 431 times, 90% confident it clears the bar.*
- **Autonomy grows safely, like a career.** Every agent starts as an intern. It proposes, a person approves. As its
  record proves itself, it earns more room, one decision type at a time. A bad week costs it that room automatically.
- **Accountability is built in, not bolted on.** An auditor asking *"why did the AI do this?"* gets the full answer
  in one read: the situation, the options, the rules checked, who approved, and what happened next.
- **Humans move up the stack.** People stop rubber-stamping the routine and spend their attention where it counts:
  the new, the risky, the irreversible.

That's **enterprise autonomy**: not AI that replaces judgement, but AI that inherits it, proves itself, and earns its
freedom. ActionGraph is the open layer that makes it possible, the way TCP/IP made the internet possible: boring,
reliable, everywhere, and owned by no one.

## Three principles we won't bend

- **No agent grades its own homework.** Outcomes come from the systems that saw them. An agent's own reports earn it
  nothing, and hidden random audits check its word.
- **No agent approves itself.** Ever. Approvals bind to the exact request a person saw.
- **Autonomy is a record, not a setting.** It is granted by evidence with stated confidence, and revoked by evidence
  just as fast.

## See it in 30 seconds

```bash
pip install actiongraph-ai
```

```python
from actiongraph import ActionGraph, ApprovalRequired

DB = "sqlite:///quickstart.db"                      # a local file: no server, no API key
agent  = ActionGraph(DB, agent="support_bot")        # it can ask, never approve
person = ActionGraph(DB)                             # a person: their name goes on the record

@agent.guard(subject="Order:{order_id}", autonomy_after=3)
def issue_refund(order_id: str, amount: float):
    print(f"  refunded ${amount} on {order_id}")

for order_id in ["A-1001", "A-1002", "A-1003", "A-1004"]:
    try:
        issue_refund(order_id, 40.0)
        print(f"{order_id}: ran on its own: the agent earned it")
    except ApprovalRequired as e:
        print(f"{order_id}: waiting for a person")
        person.approve(e.decision_id, by="dana")
        issue_refund(order_id, 40.0)
```

```text
A-1001: waiting for a person
A-1002: waiting for a person
A-1003: waiting for a person
A-1004: ran on its own: the agent earned it
```

Three approved runs that worked, and on the fourth the agent acts alone. One failure, and it asks again. That's the
whole idea, in fifteen lines.

## What you get

| | |
|---|---|
| **A decision ledger** | Every decision kept whole: the situation, the options offered, every rule check, who decided, who approved, why, and the outcome. Exportable as open decision events. |
| **Evidence, not opinion** | Options ranked by how often they worked in cases like this, with honest confidence. When the record is thin, it says so. |
| **Playbooks** | Versioned YAML: the decisions you govern, the options allowed, rules that block or route to a person, and what "worked" means. A person activates each version. |
| **Earned autonomy** | recommend → approve → auto, per agent and per action, earned from outcomes with 90% confidence and taken back automatically. |
| **Learned ranking** | Optional contextual RL that learns from outcomes, can start from an outside model like Jev, and ranks only after a person promotes it. |
| **Flows and swarms** | Multi-step, multi-agent processes with gates. Agents vote; agreement decides, a split goes to a person. |
| **From approval to execution** | Every answer says what happens next. A decision hands the executor a single-use grant for exactly the approved action and parameters, and a webhook tells it to run. |
| **Works with every agent** | Claude, GPT, LangGraph, CrewAI or your own code: in-process Python, HTTP, or MCP. `actiongraph mcp-gate` puts a person in front of any MCP server in one line. |

## Explore in nine examples

Each runs on its own with nothing but `pip install actiongraph-ai`.

| Example | Shows |
|---|---|
| [1. Your first approval](examples/get_started/01_first_approval.py) | A guard, approve and reject, the record |
| [2. Rules and evidence](examples/get_started/02_playbook_rules_evidence.py) | Options ranked by what worked; a rule that blocks; a rule that routes to a person |
| [3. Earning autonomy, and losing it](examples/get_started/03_earn_and_lose_autonomy.py) | recommend → approve → auto, and auto taken back when results turn |
| [4. Who grades the agent?](examples/get_started/04_who_grades_the_agent.py) | Its own word earns nothing; hidden audits; the honesty test |
| [5. Safety rails](examples/get_started/05_safety_rails.py) | No self-approval, approvals bound to the request, one approval, one run |
| [6. Learned ranking](examples/get_started/06_learned_ranking.py) | Contextual RL, with and without a Jev prior |
| [7. The decision ledger](examples/get_started/07_decision_ledger.py) | One entry in full, its timeline, totals, export and ingest |
| [8. From approval to execution](examples/get_started/08_execution_grants.py) | `next` on every answer, and a single-use grant to run exactly what was approved |
| [9. Approvals in Slack](examples/get_started/09_slack_approvals.py) | Approve and Reject in Slack, then a webhook hands your executor the grant |

## Where it's going

ActionGraph today is the decision record and authority layer for one organization. The road ahead:

- **Tamper-evident ledger:** hash-chained decision events, so the record proves it hasn't been edited.
- **Decision intelligence at scale:** discovery of the decisions your company already makes, and backtesting
  against your own history.
- **A hosted version:** many organizations, per-person sign-in, Slack approvals, on-call routing and outcome
  connectors.
- **An open standard:** decision events any agent framework can emit, so every decision, everywhere, can be
  remembered and learned from.

## Honest about today

ActionGraph is a **beta (0.2), a research prototype.** Use it today with a person approving, and as the record of what
your agents decided. It holds against an agent when run as a server with separate keys; on one machine with no server
it is a record, not a lock. The ledger isn't tamper-evident yet. Read
[What it protects, and what it doesn't](docs/REFERENCE.md#what-it-protects-and-what-it-doesnt) before letting an agent act
alone on anything costly or irreversible. Provided as is, without warranty ([Apache-2.0](LICENSE)).

## Go deeper

- The full technical reference: [docs/REFERENCE.md](docs/REFERENCE.md): guards, MCP gate, playbooks, flows, server, dashboard, API
- [Docs](docs/introduction.mdx) · [Playbook spec](spec/playbook.md) · [Decision events spec](spec/decision-events.md)
- [Fourteen scenarios](examples/scenarios/README.md) · [How good is the evidence?](docs/evals.md)

## Join us

The future where agents earn trust instead of being granted it gets built in the open. Star the repo, try an
example, open an issue, send a pull request ([CONTRIBUTING.md](CONTRIBUTING.md)). Report security problems
privately ([SECURITY.md](SECURITY.md)).

<p align="center"><b>Software learned to think. ActionGraph teaches it to be trusted.</b></p>
