Metadata-Version: 2.4
Name: consentgraph
Version: 0.1.0
Summary: Consent Graph as Code: deterministic action governance for AI agents
Project-URL: Homepage, https://github.com/mmartoccia/consentgraph
Project-URL: Repository, https://github.com/mmartoccia/consentgraph
Project-URL: Issues, https://github.com/mmartoccia/consentgraph/issues
Author-email: Michael Martoccia <mmartoccia@gmail.com>
License: MIT
License-File: LICENSE
Keywords: agents,ai,autonomy,consent,governance,mcp,safety
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Requires-Dist: click>=8.0
Requires-Dist: pydantic>=2.0
Provides-Extra: dev
Requires-Dist: build; extra == 'dev'
Requires-Dist: hatch; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: twine; extra == 'dev'
Provides-Extra: mcp
Requires-Dist: mcp>=1.0; extra == 'mcp'
Description-Content-Type: text/markdown

# consentgraph

AI agents break trust when they act without permission. Not because they're malicious -- because the authorization boundary was never made explicit. `consentgraph` gives you a simple, auditable way to define exactly what your agent can do autonomously, what requires human approval, and what is permanently off-limits -- in a single JSON file that travels with your deployment.

```python
from consentgraph import check_consent, ConsentGraphConfig

config = ConsentGraphConfig(graph_path="./consent-graph.json")
tier = check_consent("email", "send", confidence=0.9, config=config)
# → "VISIBLE"  (execute, then notify operator)
```

---

## Install

```bash
pip install consentgraph
# With MCP server support:
pip install "consentgraph[mcp]"
```

---

## The 4-Tier Model

Every action resolves to exactly one tier. The engine checks lists in priority order: **blocked → autonomous → requires_approval → unlisted**.

| Tier | What it means | Agent behavior |
|------|--------------|----------------|
| **SILENT** | Pre-approved. Operator trusts this unconditionally. | Execute. Log it. No notification. |
| **VISIBLE** | Allowed at high confidence (≥ 0.85). | Execute, then notify operator: "I did X because Y." |
| **FORCED** | Allowed but needs explicit approval. | Stop. Surface to operator. Wait for response. |
| **BLOCKED** | Absolute prohibition. Never execute. | Refuse. Alert operator that the attempt was made. |

The `confidence` parameter is the agent's self-reported confidence that the action matches operator intent. High confidence on a `requires_approval` action yields VISIBLE; low confidence yields FORCED. Blocked actions are always blocked, regardless of confidence.

---

## consent-graph.json

Define your domains and actions in a single JSON file:

```json
{
  "domains": {
    "email": {
      "autonomous": ["read", "archive_promo"],
      "requires_approval": ["send", "reply"],
      "blocked": ["delete_all", "bulk_send"],
      "trust_level": "high"
    },
    "filesystem": {
      "autonomous": ["read", "list"],
      "requires_approval": ["write", "create"],
      "blocked": ["delete", "format"],
      "trust_level": "low"
    }
  },
  "consent_decay": {
    "enabled": true,
    "review_interval_days": 30
  }
}
```

See [`examples/consent-graph.example.json`](examples/consent-graph.example.json) for a full 5-domain example with design rationale notes.

**Note on JSON comments:** JSON doesn't support comments natively. The example file uses `"_design_note"` keys for inline documentation -- ConsentGraph ignores unknown keys.

---

## Python API

```python
from consentgraph import check_consent, log_override, ConsentGraphConfig

# Configure once
config = ConsentGraphConfig(
    graph_path="./consent-graph.json",
    log_dir="./logs/",
    confidence_threshold=0.85,  # default
)

# Check before any external action
tier = check_consent("calendar", "create_event", confidence=0.9, config=config)

if tier == "BLOCKED":
    raise PermissionError("Action blocked by consent graph")
elif tier == "FORCED":
    # surface approval UI to operator, await response
    ...
elif tier == "VISIBLE":
    do_action()
    notify_operator("Created calendar event because user requested it.")
else:  # SILENT
    do_action()

# Log when a human overrides a consent decision
log_override(
    domain="calendar",
    action="create_event",
    reason="Operator approved via Slack button",
    operator_decision="approved",
    config=config,
)
```

### ConsentGraphConfig defaults

| Parameter | Default | Description |
|-----------|---------|-------------|
| `graph_path` | `~/.consentgraph/consent-graph.json` | Path to consent graph |
| `log_dir` | `~/.consentgraph/logs/` | Audit log directory |
| `confidence_threshold` | `0.85` | Min confidence for VISIBLE vs FORCED |

---

## CLI

```bash
# Create a starter consent-graph.json
consentgraph init

# Check consent for an action
consentgraph check email send --confidence 0.9

# Print graph summary
consentgraph summary

# Validate graph schema
consentgraph validate

# Check if graph needs review (decay)
consentgraph decay

# Analyze override patterns
consentgraph overrides

# Override graph location
consentgraph --graph /path/to/consent-graph.json summary
```

---

## MCP Server

ConsentGraph ships an MCP server that exposes `check_consent` as a native tool. Any MCP-compatible framework (LangChain, CrewAI, Claude Desktop, custom) can call it.

**Start the server:**
```bash
consentgraph mcp
# or
python -m "consentgraph.mcp_server
```

**MCP client config (e.g. Claude Desktop):**
```json
{
  "mcpServers": {
    "consentgraph": {
      "command": "consentgraph",
      "args": ["mcp"],
      "env": {
        "CONSENTGRAPH_GRAPH_PATH": "/path/to/consent-graph.json"
      }
    }
  }
}
```

**Tool: `check_consent`**

Input:
```json
{
  "domain": "email",
  "action": "send",
  "confidence": 0.9
}
```

Output:
```json
{
  "tier": "VISIBLE",
  "domain": "email",
  "action": "send",
  "confidence": 0.9,
  "guidance": "Proceed, then notify the operator."
}
```

---

## Schema Validation

```python
from consentgraph import validate_graph
import json

with open("consent-graph.json") as f:
    raw = json.load(f)

graph = validate_graph(raw)  # raises pydantic.ValidationError if invalid
print(f"{len(graph.domains)} domains configured")
```

Or via CLI:
```bash
consentgraph validate
```

---

## Audit Trail

Every consent check is logged to `{log_dir}/consent-attempts.jsonl`. Every human override is logged to `{log_dir}/consent-overrides.jsonl`.

```jsonl
{"timestamp": "2025-01-15T14:23:01", "domain": "email", "action": "send", "confidence": 0.9, "tier": "VISIBLE", "reason": "high_confidence_approval"}
```

Use the override log to identify patterns and refine your graph:

```bash
consentgraph overrides
# → "email/send: approved 5x → consider upgrading to autonomous"
```

---

## Why This Matters

Enterprise and government deployments of AI agents face a common failure mode: the authorization boundary is implicit, embedded in prompts or agent code, invisible to auditors, and impossible to update without a code deploy. When something goes wrong -- and it will -- there's no audit trail and no clear policy to point to.

ConsentGraph makes the boundary explicit, version-controlled, human-readable, and independently auditable. The consent graph is the policy. The audit log is the evidence. The override log is the feedback loop that improves the policy over time.

For regulated industries, this pattern maps directly onto existing control frameworks (SOC 2 access controls, FedRAMP least-privilege, NIST AI RMF). The consent graph is a machine-readable policy artifact that compliance teams can review without reading agent code.

---

## Project Status

v0.1.0 -- production logic extracted and packaged. API is stable. MCP server is functional. Breaking changes will be versioned.

**Roadmap:**
- Async support for `check_consent`
- Time-window constraints (e.g., "only during business hours")
- Graph inheritance (base + environment overrides)
- Web UI for graph editing

Contributions welcome.
