# Agreement Graph

> Open-source Python system that models contracts and agreements as a typed, auditable graph of enforceable state transitions. Built by Amrit Prakash.

## What it is

Agreement Graph treats contracts not as documents but as state machines. Every agreement has a 9-state lifecycle, every state change is guarded by a deterministic rule and recorded in an append-only audit trail, and every relationship between agreements becomes a typed edge in an operator-owned graph.

Core principle: agreements represent enforceable state transitions — identity, intent, authorization, auditability, and state change, in sequence.

## The problem it solves

Most contract software stores agreements as searchable documents. The valuable thing is not the text but the transition: who is bound, under what authority, from what state to what state, and whether you can prove it later. Agreement Graph models that directly.

## Key concepts

- **Agreement lifecycle**: DRAFT → PROPOSED → UNDER_REVIEW → APPROVED → ACTIVE → SUSPENDED / EXPIRED / TERMINATED / SUPERSEDED (9 states, 11 guarded transitions)
- **State machine**: each transition is a pure function — takes the current agreement, checks a guard rule, returns a new agreement plus an audit event. Nothing is written until both succeed.
- **Human checkpoint**: UNDER_REVIEW is a built-in gate; nothing reaches APPROVED without an identified reviewer acting on it.
- **Audit trail**: every transition emits an append-only AuditEvent — actor, from-state, to-state, timestamp, context. Never edited or deleted.
- **Typed graph edges**: parent_of (MSA → SOW), supersedes (renewal → old terms), amends, depends_on, referenced_by.
- **Party roles**: SIGNATORY, COUNTERPARTY, BENEFICIARY, ADMINISTRATOR, REVIEWER, OBSERVER.

## Tech stack

- Python 3.11+, FastAPI, NetworkX, SQLite (raw sqlite3, no ORM)
- No external services required — local-first, operator-owned
- Graph layer isolates NetworkX so a graph DB (Neo4j, Kuzu) can be swapped in later

## Architecture phases

- **Phase 1 (complete)**: core scaffold — state machine, graph, store, FastAPI API, 47 tests
- **Phase 2 (planned)**: LLM extraction pipeline — every extracted fact cites its source span, low-confidence extractions flagged not filled
- **Phase 3 (planned)**: Bronze/Silver/Gold medallion ingestion, W3C DCAT catalog metadata, PROV-O lineage, RDF + SPARQL at the Gold layer

## Author

Amrit Prakash — enterprise architect based in Bengaluru. Background in enterprise architecture, partner enablement, and emerging tech. Core theme: turning institutional rules into programmable systems.

## Links

- Website: https://www.agreementgraph.com
- GitHub: https://github.com/amrit930203/agreement-graph
- Architecture doc: https://github.com/amrit930203/agreement-graph/blob/main/ARCHITECTURE.md