Skip to content

SCP Documentation

Welcome to the SCP documentation - your guide to governing AI agents through context control.

What is SCP?

SCP (Supervisory Control Plane) is an AI governance platform that streams governed context to AI agents in real-time—preventing hallucination and drift in regulated, high-stakes professional work (healthcare, sales, legal, finance).

The Core Insight

"The agent doesn't change. The context changes. That's the control."

  • Agent drifting? → Tighten its context
  • Agent hallucinating? → Check what context it received, adjust
  • New compliance requirement? → Update the graph, all agents get it immediately
  • One agent misbehaving? → Adjust its specific context without affecting others
  • Need to audit? → Full history of what agent, what context, what task, when

How It Works

┌─────────────────────────────────────────────────────────────────┐
│  Agent Request → Auth → Intent Check → Graph Query → Stream    │
└─────────────────────────────────────────────────────────────────┘
  1. Agent authenticates with API key
  2. Intent validated against allowed task types
  3. Graph queried for role-appropriate SCDs
  4. Policy applied (agent-specific overrides/restrictions)
  5. Context streamed to agent
  6. Request logged for full audit trail

Documentation Structure

📚 Guides

🏗️ Architecture

📖 Reference

💡 Examples

See control-plane/examples/pilot/ for real-world bundle examples: - acme-bundle.yaml — Comprehensive healthcare bundle with compliance rules - simple-bundle.yaml — Minimal bundle template

Quick Start

1. Start Infrastructure

cd control-plane

# Start PostgreSQL (with Apache AGE) and Redis
docker-compose up -d

2. Seed Test Data

# Seed the graph with roles and SCDs
python scripts/seed_graph.py

# Seed test agents with API keys
python scripts/seed_agents.py

3. Start Services

# Terminal 1: API Server
uvicorn api_server.main:app --port 8000

# Terminal 2: Context Service (gRPC)
python -m context_service.grpc_server

4. Test the Flow

# Run end-to-end tests
python scripts/test_e2e_context.py --direct --http --grpc

5. Request Context (Example)

import httpx

response = httpx.post(
    "http://localhost:8000/api/context",
    headers={"X-API-Key": "sk_your_api_key"},
    json={"task_type": "prior_auth_check"}
)

# Returns role-appropriate SCDs
print(response.json()["scd_ids"])

The 5 Bundle Types

Meta Bundle (SCS Foundation)
  ↓ imports
Standards Bundles (HIPAA, SOC2, CHAI)
  ↓ imports
Domain Bundle (1 per company) ⭐
  ↓ imports
Concern Bundles (Architecture, Security, Clinical)
  ↓ imported by
Project Bundles (entry point for AI)
  1. Meta Bundle - SCS specification language (1 per ecosystem)
  2. Standards Bundle - External compliance (HIPAA, SOC2, CHAI)
  3. Domain Bundle - Company knowledge aggregator (1 per company) ⭐
  4. Concern Bundle - Functional area standards (Architecture, Security, Clinical)
  5. Project Bundle - Individual initiatives (entry point for AI)

See Bundle Types Guide for details.

Key Concepts

Agent Registry

Agents are registered with: - Identity - Unique agent ID - Role - Determines base context (prior-auth-agent, claims-processor) - Allowed Intents - Task types the agent can request context for - API Key - Authentication credential

Graph-Based Context Selection

Instead of manually mapping roles to context, SCP uses a graph database: - Bundles and SCDs stored as nodes - Relationships (APPLIES_TO, GOVERNED_BY, REFERENCES) stored as edges - Context selection via graph traversal - Dynamic selection without manual mapping

Policy Filtering

Individual agents can have: - Overrides - Additional SCDs beyond their role's default - Restrictions - SCDs to exclude from their context

Services

Service Port(s) Purpose
Control Plane API 8000 Bundle Registry, Agent Registry, REST context API
Context Service 8002 (gRPC), 8003 (webhook) Real-time streaming
Rules Engine 8001 Custom business rules
Telemetry Service 8004 Usage reporting
Graph Database 5432 PostgreSQL + Apache AGE
Redis 6379 Pub/sub for updates
Caddy 443, 8443 TLS reverse proxy

Current Status (v0.3.1)

✅ All core features complete and tested

Component Status
Graph Infrastructure (Apache AGE) ✅ Complete
Agent Registry (API keys, roles, intents) ✅ Complete
Context Orchestrator (auth → graph → policy → stream) ✅ Complete
REST API for context requests ✅ Complete
gRPC streaming ✅ Complete
Integration tests (13/13 passing) ✅ Complete
Security hardening (audit chain, TLS, admin auth, license) ✅ Complete

Planned Enhancements

  • OAuth2/OIDC for admin console SSO
  • Multi-tenancy with organization isolation
  • Monitoring/Observability (Prometheus/Grafana)

Contributing

See control-plane/scripts/test_e2e_context.py for end-to-end tests.

Support