Metadata-Version: 2.4
Name: aigp-server
Version: 0.1.0
Summary: AIGP Governance Server — agentic governance engine (scope envelopes, circuit breakers, delegation)
Project-URL: Homepage, https://github.com/owner-spec/aigp-protocol
Project-URL: Repository, https://github.com/owner-spec/aigp-protocol
Author-email: Evan Erwee <evan@erwee.com>
License: Proprietary
Keywords: agentic,ai,aigp,circuit-breaker,governance,protocol,scope-envelope
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: Other/Proprietary License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.11
Provides-Extra: dev
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: pytest-asyncio; extra == 'dev'
Description-Content-Type: text/markdown

# aigp-server — AIGP Governance Engine

Server-side governance engine for the AI Governance Protocol (AIGP). Evaluates agentic governance decisions: tool authorization, plan approval, delegation with scope narrowing, circuit breakers, and memory governance.

## Install

```bash
pip install aigp-server
```

## Usage

```python
from aigp_server import (
    GovernanceEngine, GovernanceStore, AigpRouter,
    ScopeEnvelopeManager, CircuitBreakerService,
)

# 1. Implement the storage interface for your DB
class MyStore(GovernanceStore):
    async def put_scope_envelope(self, envelope: dict) -> None: ...
    async def get_active_scope(self, agent_id: str) -> dict | None: ...
    # ... (see store.py for full interface)

# 2. Wire up the engine
store = MyStore()
scope_mgr = ScopeEnvelopeManager(store)
cb = CircuitBreakerService(store)
engine = GovernanceEngine(store, scope_mgr, cb, mode="ENFORCE")

# 3. Create the router (framework-agnostic)
router = AigpRouter(engine, hmac_secret="your-secret")

# 4. Handle requests — returns (status_code, response_dict)
status, response = await router.handle_tool_request(headers_dict, body_bytes)
status, response = await router.handle_plan_submit(headers_dict, body_bytes)
status, response = await router.handle_escalate(headers_dict, body_bytes)
status, response = await router.handle_delegate(headers_dict, body_bytes)
status, response = await router.handle_memory_write(headers_dict, body_bytes)
```

## Architecture

```
aigp-server/
  store.py             — GovernanceStore ABC (implement for your DB)
  governance_engine.py — Core decision engine (6 handlers)
  scope_manager.py     — Scope envelope lifecycle + SoD + templates
  circuit_breaker.py   — 3-state machine with cascading halt
  routes.py            — Framework-agnostic router (HMAC + dispatch)
  hmac_auth.py         — HMAC-SHA256 verify/sign utilities
```

## Handlers

| Handler | RFC §15 | Decision |
|---------|---------|----------|
| `handle_tool_request` | §15.6 | ALLOW / DENY (scope + budget + circuit breaker) |
| `handle_plan_submit` | §15.8 | APPROVED / APPROVED_WITH_MODIFICATIONS / REJECTED |
| `handle_step_complete` | — | Budget decrement + circuit breaker outcome |
| `handle_escalate` | §15.9 | Creates pending task for human review |
| `handle_delegate` | §15.10 | Scope narrowing (A ∩ B), depth limit (max 5) |
| `handle_memory_write` | §15.13 | Classification + retention + isolation check |

## Modes

| Mode | Behavior |
|------|----------|
| `REPORT` | Log denials but return ALLOW (shadow mode) |
| `REPORT-TRACE` | Same as REPORT + emit trace telemetry |
| `ENFORCE` | Deny violations (fail-closed) |

## License

Proprietary — © 2025-2026 Evan Erwee. All rights reserved.
