Metadata-Version: 2.4
Name: authgraph
Version: 0.3.0
Summary: authgraph — simulate TrigGuard authorization before AI agents execute. Plans, graphs, explainability.
Author: TrigGuard AI
License-Expression: Apache-2.0
Project-URL: Homepage, https://www.trigguardai.com
Project-URL: Repository, https://github.com/TrigGuard-AI/TrigGuard
Project-URL: Documentation, https://trigguardai.com/docs
Project-URL: Issues, https://github.com/TrigGuard-AI/TrigGuard/issues
Keywords: authgraph,trigguard,permit,execution-graph,dag,orchestration,authorization,ai-governance,workflow-engine,simulation,explainability
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: trigguard>=0.2.1
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: ruff>=0.4.0; extra == "dev"
Requires-Dist: mypy>=1.8; extra == "dev"
Dynamic: license-file

# authgraph

**Show me what will happen before the AI executes anything.**

Python execution planning + TrigGuard authorization simulation. No permit, no run.

```bash
pip install authgraph
```

```python
from authgraph import Plan, simulate

plan = Plan()
plan.add("file.read", read_file, title="read_file")
plan.add("git.push", push_branch, title="push_branch")

result = simulate(plan)
print(result)          # predicted PERMIT / ESCALATE / BLOCKED per step
print(plan.visualize())  # execution graph
```

Before anything runs, authgraph asks TrigGuard. **Simulation never executes your callables.**

```
Your code → authgraph → TrigGuard → Gateway
```

Not a CrewAI/LangGraph/Quanta product. Optional integration hooks live under `authgraph.integrations` and do **not** bundle external runtimes.

**Requires** `TRIGGUARD_API_KEY`, `TRIGGUARD_ORG_ID`, and gateway `https://api.trigguardai.com` (default).

Full guide: [`docs/QUICKSTART.md`](docs/QUICKSTART.md)

---

## APIs (0.3)

| API | Use when |
|-----|----------|
| `Plan` + `simulate()` | Preview authorization for a multi-step agent pipeline |
| `plan.execute()` | Run steps after PERMIT; cascade BLOCKED on DENY/ESCALATE |
| `explain()` | Human-readable DENY/ESCALATE with suggested actions |
| `plan.visualize()` / `export_dot()` | Console tree or Graphviz DOT |
| `@guard()` | Single function — zero graph boilerplate |
| `AuthgraphRuntime` + `run_step` | Multi-step DAG workflows |

```python
from authgraph import Plan, PlanBuilder, simulate, explain, guard
```

CLI:

```bash
authgraph simulate examples/deployment.py
authgraph explain receipt_123 --action deploy.release
authgraph graph examples/deployment.py --dot
```

Demos: [`examples/demos/`](examples/demos/) (agents, GitHub Actions, DB migrate, Terraform, K8s, robotics)

---

## Quick start (@guard)

```python
import os
from authgraph import AuthgraphRuntime, run_step

os.environ["TRIGGUARD_API_KEY"] = "tg_live_..."
os.environ["TRIGGUARD_ORG_ID"] = "org_..."

runtime = AuthgraphRuntime()
graph = runtime.create_graph(title="Deploy", description="Plan then ship")
repo = os.environ.get("TRIGGUARD_REPOSITORY", "your-org/your-repo")
plan = runtime.add_node(
    graph, title="Plan", description="Define scope",
    authority_surface="deploy.release", metadata={"repository": repo},
)
runtime.start(graph)

result = run_step(
    runtime, graph, plan, agent_id="my-agent",
    fn=lambda: {"spec": "ship it"},
)
print(result.receipt, result.execution_time)
```

More examples: [`examples/`](examples/)

---

## What is shipped (0.3)

- **Execution plans** — `Plan`, `PlanBuilder`, sequential steps with metadata
- **Simulation** — `simulate()` / `plan.simulate()` never runs callables; queries TrigGuard
- **Graph execution** — `plan.execute()` with downstream BLOCKED cascade
- **Explainability** — `explain()` for receipts, decisions, gateway JSON
- **Risk breakdown** — `result.risk_score`, `result.risk_factors` (local heuristic, not policy)
- **Visualization** — console tree + Graphviz DOT export
- **CLI** — `authgraph simulate|explain|graph`
- Universal execution engine (`authgraph.execution`) — one claim/execute/complete path
- `@guard`, `authorization()`, sync + async + batch
- Optional integrations (CrewAI, LangGraph, …) — thin hooks only
- Fail-closed TrigGuard gate

Not shipped: hosted service, bundled agent frameworks, policy duplication, GitHub Apps, K8s controllers, Terraform providers (build when design partners ask).

---

## Environment

| Variable | Required | Description |
|---|---|---|
| `TRIGGUARD_API_KEY` | yes | Customer API key |
| `TRIGGUARD_ORG_ID` | yes | Org id (`X-Consumer`) |
| `TRIGGUARD_GATEWAY_URL` | no | Default `https://api.trigguardai.com` |
| `TRIGGUARD_REPOSITORY` | no | Auto metadata for deploy surfaces |
| `TRIGGUARD_ACTOR` | no | Default actor for `@guard` / context manager |

---

## License

See [LICENSE](LICENSE).
