Getting Started with SCP¶

This guide walks you through setting up SCP and making your first context request.

Prerequisites¶

Python 3.10+
Docker & Docker Compose
Git

Quick Start¶

1. Clone the Repository¶

git clone https://github.com/tim-mccrimmon/supervisory-control-plane.git
cd supervisory-control-plane

2. Configure Environment¶

cd control-plane
cp .env.pilot.template .env

Generate required secrets before starting — the API will reject startup if placeholders are left in place:

# DB_PASSWORD
python -c "import secrets; print(secrets.token_urlsafe(24))"

# JWT_SECRET
python -c "import secrets; print(secrets.token_hex(32))"

# DEPLOYMENT_ID
python -c "import uuid; print(uuid.uuid4())"

Set each in .env.

3. Start Infrastructure¶

# Start all services
docker compose up -d

# Verify services are running
docker compose ps

You should see: - scp-postgres — PostgreSQL with Apache AGE (port 5432) - scp-redis — Redis for pub/sub (port 6379) - scp-api — Control Plane API (port 8000) - scp-rules — Rules Engine (port 8001) - scp-context — Context Service (ports 8002/8003) - scp-telemetry — Telemetry Service (port 8004) - scp-caddy — TLS reverse proxy (ports 443/8443)

4. Install Dependencies (local development only)¶

# Install Python dependencies
pip install -r requirements.txt

5. Initialize the Database¶

# Run database migrations
python -m database.init

6. 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

This creates: - 3 roles (prior-auth-agent, claims-processor, eligibility-agent) - 8 SCDs with relationships (HIPAA, clinical guidelines, formulary, etc.) - 5 test agents with API keys (saved to scripts/test_api_keys.json)

7. Verify Everything Works¶

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

All 13 tests should pass.

Your First Context Request¶

Using the REST API¶

import httpx
import json

# Load test API keys
with open("scripts/test_api_keys.json") as f:
    keys = json.load(f)

api_key = keys["agent_prior_auth_prod"]["api_key"]

# Request context for a task
response = httpx.post(
    "http://localhost:8000/api/context",
    headers={"X-API-Key": api_key},
    json={
        "task_type": "prior_auth_check",
        "params": {"drug": "Keytruda", "diagnosis": "lung cancer"}
    }
)

result = response.json()
print(f"Success: {result['success']}")
print(f"Role: {result['role_id']}")
print(f"SCDs: {result['scd_ids']}")

Using cURL¶

# Get API key from test_api_keys.json (generated by seed_agents.py)
API_KEY=$(jq -r '.agent_prior_auth_prod.api_key' scripts/test_api_keys.json)

curl -X POST http://localhost:8000/api/context \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $API_KEY" \
  -d '{"task_type": "prior_auth_check"}'

Expected Response¶

{
  "success": true,
  "request_id": "ctx_abc123",
  "agent_id": "agent:prior-auth-prod",
  "role_id": "role:prior-auth-agent",
  "task_type": "prior_auth_check",
  "scd_ids": [
    "scd:standards:hipaa-privacy-rule",
    "scd:project:clinical-guidelines-v1.2",
    "scd:project:formulary-2024"
  ],
  "scd_content": { ... },
  "processing_time_ms": 34
}

Register Your Own Agent¶

1. Create an Agent¶

curl -X POST http://localhost:8000/api/agents \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agent:my-custom-agent",
    "name": "My Custom Agent",
    "role_id": "role:prior-auth-agent",
    "allowed_intents": ["prior_auth_check", "formulary_lookup"],
    "status": "active"
  }'

2. Generate an API Key¶

curl -X POST http://localhost:8000/api/agents/agent:my-custom-agent/api-keys \
  -H "Content-Type: application/json" \
  -d '{"key_id": "my-key-1"}'

Save the returned API key - it won't be shown again.

3. Use Your Agent¶

curl -X POST http://localhost:8000/api/context \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{"task_type": "prior_auth_check"}'

Create Your First Bundle¶

Using the CLI¶

# Create a new project with healthcare scaffolding
scs new my-healthcare-project --type healthcare

# Navigate to project directory
cd my-healthcare-project

# Create a bundle interactively
scs bundle create

# Validate your bundle
scs validate ./bundles/my-bundle.yaml

Bundle Structure¶

id: bundle:my-company-context
type: concern
version: "DRAFT"
title: "My Company Context"
description: "Company-specific context for AI agents"

scds:
  - scd:project:company-overview
  - scd:project:company-values

imports: []  # Empty for concern bundles

provenance:
  created_by: "Your Name"
  created_at: "2026-01-26T10:00:00Z"

Understanding the Flow¶

┌─────────────────────────────────────────────────────────────────┐
│  1. Agent authenticates with API key                            │
│  2. SCP validates intent against allowed_intents                │
│  3. SCP queries graph for role-appropriate SCDs                 │
│  4. SCP applies policy (overrides/restrictions)                 │
│  5. SCP streams context to agent                                │
│  6. Request logged for audit trail                              │
└─────────────────────────────────────────────────────────────────┘

Key Concepts¶

Agent - An AI system that requests context
Role - Determines base context (prior-auth-agent, claims-processor)
Intent - Task type the agent wants to perform (prior_auth_check, formulary_lookup)
SCD - Structured Context Document (HIPAA rules, clinical guidelines, etc.)
Graph - Stores relationships between roles and SCDs

Common Commands¶

Infrastructure¶

# Start services
docker-compose up -d

# Stop services
docker-compose down

# View logs
docker-compose logs -f postgres

API Server¶

# Start API server
uvicorn api_server.main:app --port 8000

# Start with auto-reload (development)
uvicorn api_server.main:app --port 8000 --reload

Testing¶

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

# Run only direct tests (no server needed)
python scripts/test_e2e_context.py --direct

# Run only HTTP tests
python scripts/test_e2e_context.py --http

CLI (Bundle Management)¶

# Create a new project
scs new <project-name> --type healthcare|fintech|saas|government|minimal

# Create bundle
scs bundle create

# Validate bundle
scs validate ./bundles/my-bundle.yaml

Troubleshooting¶

Docker Issues¶

# Check container status
docker-compose ps

# View container logs
docker-compose logs postgres
docker-compose logs redis

# Restart containers
docker-compose restart

Database Connection Issues¶

# Test database connection
psql -h localhost -U postgres -d control_plane

# Check AGE extension
psql -h localhost -U postgres -d control_plane -c "SELECT * FROM ag_catalog.ag_graph;"

API Issues¶

# Check API health
curl http://localhost:8000/api/context/health

# Check if agents exist
curl http://localhost:8000/api/agents

Common Errors¶

Error	Cause	Solution
`ValueError: JWT_SECRET must be set`	Placeholder left in `.env`	Generate secret: `python -c "import secrets; print(secrets.token_hex(32))"`
`ValueError: DB_PASSWORD must be set`	Placeholder left in `.env`	Generate password: `python -c "import secrets; print(secrets.token_urlsafe(24))"`
`AUTH_FAILED`	Invalid or missing API key	Check X-API-Key header
`INTENT_NOT_ALLOWED`	Task type not in agent's allowed_intents	Update agent or use allowed intent
`Connection refused`	Service not running	`docker compose up -d`
`relation does not exist`	Database not initialized	Run migrations and seed scripts

Next Steps¶

Read Bundle Types Guide to understand the 5 bundle types
Review Architecture Overview for system design
Explore control-plane/examples/pilot/ for real-world bundle examples
Check API Reference for all endpoints

Getting Help¶

Check the CLI reference
Review control-plane/examples/pilot/ for bundle examples
Open an issue for bugs