# Base install (SQLite backend)
pip install autopil

# With Postgres support
pip install autopil[postgres]

# With OpenTelemetry (gRPC exporter)
pip install autopil[otel]

# With OpenTelemetry (HTTP exporter — Grafana Cloud)
pip install autopil[otel-http]

# All dev dependencies (tests, linting)
pip install autopil[dev]

from autopil import ContextGuard, SensitivityLevel

# Point at a policy file or directory
guard = ContextGuard(
    policy_path="policies/",
    audit_db="autopil.db",
)

@guard.protect(
    agent_role="loan_underwriter",
    user_id="user_001",
    source_id="credit_scores",
    sensitivity_level=SensitivityLevel.HIGH,
    session_id=session_id,
)
def get_credit_score(customer_id: str) -> dict:
    return credit_db.query(customer_id)

# ALLOW — policy matched, audit event logged, OTEL span emitted
score = get_credit_score("cust_abc")

# DENY — raises PermissionError, denial logged, alert rules checked
# source='executive_comms' is on the denylist for this role

autopil-serve --policy policies/

⚠  First start — created 'default' tenant and superadmin key:
   apl_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
   Save this — it will not be shown again.

docker compose logs | grep "AUTOPIL ADMIN KEY"

# Create a tenant
curl -X POST http://localhost:8000/v1/admin/tenants \
  -H "X-API-Key: apl_superadmin_key" \
  -H "Content-Type: application/json" \
  -d '{"name": "my_app"}'
# → { "tenant_id": "ten_abc123", "admin_key": "apl_..." }

# Create an agent-specific key
curl -X POST http://localhost:8000/v1/keys \
  -H "X-API-Key: apl_tenant_admin_key" \
  -H "Content-Type: application/json" \
  -d '{"name": "production_agent"}'
# → { "key": "apl_...", "key_id": "key_..." }  (shown once)

curl -X PATCH https://api.autopil.ai/v1/admin/tenants/{tenant_id}/settings \
  -H "X-API-Key: $SUPERADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"require_agent_id": true}'

policies:
  - name: loan_underwriter_policy
    agent_role: loan_underwriter
    allowed_sources:
      - credit_scores
      - loan_history
      - property_valuations
      - income_verification
    denied_sources:
      - other_customer_data
      - internal_risk_models
      - executive_communications
    allowed_tasks:
      - credit_decision
      - collateral_check
      - risk_assessment
    denied_tasks:
      - account_freeze
      - fraud_flag
    max_sensitivity: high
    session_ttl_minutes: 240        # optional: overrides global server TTL
    sensitivity_decay:               # optional: tightens ceiling as session ages
      - after_minutes: 60
        max_sensitivity: medium
      - after_minutes: 120
        max_sensitivity: low

  - name: fraud_analyst_policy
    agent_role: fraud_analyst
    allowed_sources:
      - transaction_history
      - device_signals
      - watchlist
    denied_sources:
      - executive_communications
      - internal_risk_models
    max_sensitivity: high

policies/
  financial_services/
    consumer_banking.yaml    # 4 roles
    wealth.yaml              # 4 roles
    risk_compliance.yaml     # 4 roles
    operations.yaml          # 4 roles
  healthcare/
    clinical_operations.yaml # 4 roles
    compliance_privacy.yaml  # 3 roles
    revenue_cycle.yaml       # 4 roles
  technology/
    saas_platform.yaml       # 5 roles
  telecom/
    network_operations.yaml  # 3 roles
    fraud_assurance.yaml     # 3 roles
    customer_experience.yaml # 3 roles
  logistics/
    supply_chain.yaml        # 3 roles
    fleet_operations.yaml    # 3 roles
    customs_compliance.yaml  # 3 roles

@guard.protect(
    agent_role="loan_underwriter",
    user_id="user_001",
    source_id="credit_scores",
    sensitivity_level=SensitivityLevel.HIGH,
    task_type="credit_decision",  # checked against allowed_tasks / denied_tasks
    session_id=session_id,
)
def get_credit_score(customer_id: str) -> dict: ...

curl -X POST http://localhost:8000/v1/policies/reload \
  -H "X-API-Key: apl_yourkey"
# → { "loaded": 45, "policies_count": 45 }

# policies/financial_services/fraud_investigation.yaml
policies:
  - name: transaction_analyst_policy
    agent_role: transaction_analyst
    permitted_agent_ids:          # only these agent IDs may use this policy
      - fraud-analyst-prod         # exact match
      - fraud-analyst-*            # fnmatch wildcard — matches fraud-analyst-v2, etc.
    allowed_sources:
      - transaction_history
      - velocity_signals
    max_sensitivity: critical
    session_ttl_minutes: 60

curl https://api.autopil.ai/v1/... \
  -H "X-API-Key: apl_yourkey"

# Request body
{
  "agent_role":        "loan_underwriter",
  "user_id":           "user_001",
  "source_id":         "credit_scores",
  "sensitivity_level": "high",
  "session_id":        "sess_abc",
  "task_type":         "credit_decision",  # optional
  "agent_id":          "loan-agent-prod-01" # optional — enables identity binding
}

# Response (ALLOW)
{
  "decision":    "ALLOW",
  "policy_name": "loan_underwriter_policy",
  "reason":      "all checks passed",
  "event_id":    "evt_abc123"
}

# Response (DENY)
{
  "decision":    "DENY",
  "policy_name": "loan_underwriter_policy",
  "reason":      "source 'executive_comms' is on denylist",
  "event_id":    "evt_def456"
}

{
  "total": 1247,
  "allowed": 1118,
  "denied": 129,
  "by_source_type": {
    "sdk":           { "total": 847, "allowed": 790, "denied": 57 },
    "api":           { "total": 203, "allowed": 178, "denied": 25 },
    "langchain":     { "total": 87,  "allowed": 80,  "denied": 7  },
    "bedrock":       { "total": 64,  "allowed": 58,  "denied": 6  },
    "rest":          { "total": 46,  "allowed": 12,  "denied": 34 }
  }
}

{
  "retention_days":         365,
  "session_retention_days": 90,
  "audit_policy":           "Audit events older than 365 days are automatically purged daily.",
  "session_policy":         "Expired and revoked sessions older than 90 days are purged daily."
}

{
  "retention_days":         180,
  "session_retention_days": 60
}

{
  "retention_days": 365,
  "policy": "Audit events older than 365 days are automatically purged daily.",
  "anchor": {
    "anchor_hash":   "a3f8c1d2...",
    "purged_before": "2025-03-30T00:00:00",
    "purged_count":  142
  }
}

{
  "query":      "sha256:a3f8c1d2e4b7f091",
  "user_id":    "uid:7c2a9f3d11e04b82",
  "reason":     "policy consumer_banking denied: sensitivity=high exceeds max_allowed=medium, query=sha256:a3f8c1d2e4b7f091",
  "pii_masked": true
}

curl -X POST http://localhost:8000/v1/alerts/rules \
  -H "X-API-Key: apl_yourkey" \
  -H "Content-Type: application/json" \
  -d '{
    "name":             "denial spike",
    "rule_type":        "denial_spike",
    "threshold":        10,
    "window_minutes":   15,
    "cooldown_minutes": 60,
    "webhook_url":      "https://hooks.slack.com/services/..."
  }'

curl -X POST http://localhost:8000/v1/keys \
  -H "X-API-Key: apl_yourkey" \
  -H "Content-Type: application/json" \
  -d '{
    "name":         "agent-runtime",
    "scope":        "evaluate",
    "expires_days": 90
  }'

# Response — store the key now, it will not be shown again
{
  "key_id":     "key_abc123",
  "name":       "agent-runtime",
  "key":        "apl_...",
  "scope":      "evaluate",
  "expires_at": "2026-07-05T00:00:00",
  "created_at": "2026-04-06T00:00:00"
}

curl -X PATCH https://api.autopil.ai/v1/keys/key_abc123/binding \
  -H "X-API-Key: apl_yourkey" \
  -H "Content-Type: application/json" \
  -d '{
    "bound_agent_id":  "fraud-analyst-prod-01",
    "permitted_roles": ["transaction_analyst", "account_profiler"]
  }'
# → { "status": "ok" }

# 1. Register
curl -X POST https://api.autopil.ai/v1/agents \
  -H "X-API-Key: apl_yourkey" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_role":    "transaction_analyst",
    "display_name": "Fraud Transaction Analyst v2",
    "description":  "Analyzes transaction patterns for fraud signals",
    "owner":        "fraud-eng-team",
    "framework":    "langgraph"
  }'
# → { "agent_id": "agt_abc123", "status": "draft", ... }

# 2. Approve (governance review complete)
curl -X PATCH https://api.autopil.ai/v1/agents/agt_abc123/status \
  -H "X-API-Key: apl_yourkey" \
  -H "Content-Type: application/json" \
  -d '{"status": "approved"}'

# 3. Evaluate with agent_id — identity is now verified
curl -X POST https://api.autopil.ai/v1/context/evaluate \
  -H "X-API-Key: apl_yourkey" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_role":        "transaction_analyst",
    "agent_id":          "agt_abc123",
    "user_id":           "user_001",
    "source_id":         "transaction_history",
    "sensitivity_level": "critical",
    "session_id":        "sess_xyz"
  }'

from autopil import ContextGuard

guard = ContextGuard(policy_path="policies/", audit_db="autopil.db")

# agent_role and user_id are fixed here — the agent cannot change them
@guard.protect(
    agent_role="analyst",
    user_id="svc-reporting-agent",   # same for every call
    source_id="financial_reports",
    sensitivity_level="high",
)
def retrieve_report(query: str):
    return vectorstore.search(query)

import httpx

def retrieve_report(query: str, user_id: str, session_id: str):
    r = httpx.post(
        "https://your-app.onrender.com/v1/context/evaluate",
        headers={"X-API-Key": AUTOPIL_API_KEY},
        json={
            "agent_role": "analyst",
            "user_id": user_id,           # varies per caller
            "source_id": "financial_reports",
            "sensitivity_level": "high",
            "query": query,
            "session_id": session_id,
        },
        timeout=10,
    )
    r.raise_for_status()
    result = r.json()
    if result["decision"] == "DENY":
        raise PermissionError(result["reason"])
    return vectorstore.search(query)

AUTOPIL_BASE_URL=https://your-app.onrender.com
AUTOPIL_API_KEY=apl_xxxxxxxxxxxxxxxxxxxx

import os, uuid, httpx

AUTOPIL_BASE_URL = os.environ["AUTOPIL_BASE_URL"]
AUTOPIL_API_KEY  = os.environ["AUTOPIL_API_KEY"]

def evaluate_context(agent_role, user_id, source_id, query,
                      sensitivity_level="high", session_id=None):
    try:
        r = httpx.post(
            f"{AUTOPIL_BASE_URL}/v1/context/evaluate",
            headers={"X-API-Key": AUTOPIL_API_KEY},
            json={"query": query, "agent_role": agent_role,
                  "user_id": user_id, "source_id": source_id,
                  "sensitivity_level": sensitivity_level,
                  "session_id": session_id},
            timeout=10,
        )
        r.raise_for_status()
    except (httpx.TimeoutException, httpx.ConnectError):
        raise PermissionError("[AutoPIL] Governance check unreachable — access blocked")
    result = r.json()
    if result["decision"] == "DENY":
        raise PermissionError(result["reason"])
    return result  # result["event_id"] available for lineage

# Generate session_id once per conversation/workflow — not per call
SESSION_ID = str(uuid.uuid4())

result = evaluate_context(
    agent_role="analyst", user_id="user_123",
    source_id="financial_reports", query="Q3 revenue",
    sensitivity_level="high", session_id=SESSION_ID,
)
# ALLOW — proceed with retrieval
context = your_vectorstore.search(query)

from autopil import ContextGuard

guard = ContextGuard(
    policy_path="policies/",      # file or directory
    audit_db="autopil.db",       # SQLite path
    database_url="postgresql://...", # use Postgres instead
    tenant_id="ten_abc",          # optional — uses default tenant
)

result = get_credit_score("cust_abc")

guard.record_action(
    event_id=guard.last_event_id,   # thread-local, set by protect()
    action_type="loan_decision",
    detail={"outcome": "approved", "amount": 250000},
    outcome="approved",
)

from autopil import ContextGuard, SensitivityLevel

guard = ContextGuard(policy_path="policies/")

@guard.protect_async(
    agent_role="analyst",
    user_id="user_002",
    source_id="reports",
    sensitivity_level=SensitivityLevel.MEDIUM,
    session_id=session_id,
)
async def fetch_report(query: str) -> list:
    return await vector_db.asearch(query)

# Safe to run concurrently — each task gets its own ContextVar slot
results = await asyncio.gather(
    fetch_report("Q1 revenue"),
    fetch_report("Q2 margins"),
)

npm install @autopil/sdk

import { AutoPilClient } from "@autopil/sdk"

const client = new AutoPilClient({
  baseUrl: process.env.AUTOPIL_BASE_URL!,  // https://your-app.onrender.com
  apiKey:  process.env.AUTOPIL_API_KEY!,
})

// Evaluate a retrieval request
const result = await client.context.evaluate({
  agent_role:        "loan_underwriter",
  source_id:         "credit_scores",
  user_id:           "user_001",
  sensitivity_level: "high",
  session_id:        "sess_abc",
})

if (result.decision === "DENY") {
  throw new Error(result.reason)
}

// Query audit events
const events = await client.audit.listEvents({
  agent_role: "loan_underwriter",
  decision:   "DENY",
  limit:      50,
})

pip install autopil[mcp]

autopil-mcp --policy policies/ --db autopil.db

# or with Postgres:
export DATABASE_URL=postgresql://user:pass@host:5432/autopil
autopil-mcp --policy policies/

{
  "mcpServers": {
    "autopil": {
      "command": "autopil-mcp",
      "args": ["--policy", "/path/to/policies/", "--db", "/path/to/autopil.db"],
      "env": {}
    }
  }
}

Before accessing any data source, you MUST call evaluate_context with:
- agent_role: your role in this conversation
- user_id: the current user's ID
- source_id: the data source you want to access
- sensitivity_level: the sensitivity of that data
- session_id: a consistent ID for this conversation

Only proceed if decision is ALLOW. If DENY, inform the user and provide the reason.
After a successful retrieval, call record_action with the event_id.

✅ ALLOW — loan_underwriter may access 'credit_scores'.
Policy: loan_underwriter_policy
Event ID: evt_abc123 (use this in record_action to log what you did with the data)

🚫 DENY — loan_underwriter is not permitted to access 'executive_communications'.
Reason: source 'executive_communications' is on denylist for role 'loan_underwriter'
Policy: loan_underwriter_policy
Do not proceed with this retrieval. Inform the user that access is not permitted.

🚫 DENY — fraud_analyst is not permitted to access session 'sess_abc12…'.
Reason: Session is owned by 'loan_underwriter'. Agent 'fraud_analyst' cannot access another agent's session context.
Policy: cross_agent_isolation

from fastapi import FastAPI
from autopil.middleware import AutoPILMiddleware, RouteRule
from autopil import ContextGuard, SensitivityLevel

guard = ContextGuard(policy_path="policies/")

app = FastAPI()
app.add_middleware(
    AutoPILMiddleware,
    guard=guard,
    rules=[
        RouteRule(
            path_pattern=r"^/api/credit/.*",
            agent_role="loan_underwriter",
            user_id_header="X-User-ID",
            source_id="credit_scores",
            sensitivity_level=SensitivityLevel.HIGH,
            on_deny="reject",          # or "log" for shadow mode
        ),
        RouteRule(
            path_pattern=r"^/api/reports/.*",
            agent_role="analyst",
            user_id_header="X-User-ID",
            source_id="reports",
            sensitivity_level=SensitivityLevel.MEDIUM,
            on_deny="log",             # shadow mode — log but allow through
        ),
    ],
)

from autopil.langchain_guard import LangChainGuard
from langchain_core.tools import tool

guard = LangChainGuard(policy_path="policies/")

@tool
@guard.protect(
    agent_role="research_analyst", user_id="u1",
    source_id="market_data", sensitivity_level=SensitivityLevel.MEDIUM,
    session_id=session_id,
)
def get_market_data(ticker: str) -> dict:
    return data_api.fetch(ticker)
# source_type="langchain" — works with LCEL and LangChain agents

from autopil.llamaindex_guard import LlamaIndexGuard

guard = LlamaIndexGuard(policy_path="policies/")

@guard.protect(
    agent_role="document_analyst", user_id="u1",
    source_id="legal_contracts", sensitivity_level=SensitivityLevel.HIGH,
    session_id=session_id,
)
def retrieve_contract(clause: str) -> str:
    return index.as_query_engine().query(clause)
# source_type="llamaindex" — wraps query engines and retrievers

from autopil.gemini_guard import GeminiGuard

guard = GeminiGuard(policy_path="policies/")

@guard.protect(
    agent_role="content_reviewer", user_id="u1",
    source_id="internal_docs", sensitivity_level=SensitivityLevel.MEDIUM,
    session_id=session_id,
)
def fetch_document(doc_id: str) -> str:
    return docs_api.get(doc_id)
# source_type="gemini" — wraps functions called from Gemini function-calling agents

from autopil.openai_agents_guard import OpenAIAgentsGuard
from agents import function_tool

guard = OpenAIAgentsGuard(policy_path="policies/")

@function_tool
@guard.protect(
    agent_role="compliance_checker", user_id="u1",
    source_id="regulatory_filings", sensitivity_level=SensitivityLevel.RESTRICTED,
    session_id=session_id,
)
def get_filing(filing_id: str) -> dict:
    return filings_db.fetch(filing_id)
# source_type="openai_agents"

import boto3
from autopil.bedrock_guard import BedrockGuard

guard = BedrockGuard(policy_path="policies/")
boto_client = boto3.client("bedrock-agent-runtime")

# Wrap the client — guard extracts inputText as the policy query
client = guard.wrap_invoke_agent(
    boto_client,
    agent_role="compliance_agent", user_id="u1",
    source_id="regulatory_data", sensitivity_level=SensitivityLevel.HIGH,
    session_id=session_id,
)

response = client.invoke_agent(
    agentId="ABCDEF123", agentAliasId="TSTALIASID",
    sessionId=session_id,
    inputText="Summarize Q1 compliance filings",
)
# source_type="bedrock" — ALLOW runs the call; DENY raises PermissionError

import aioboto3
from autopil.bedrock_guard import BedrockGuard

guard = BedrockGuard(policy_path="policies/")

async with aioboto3.Session().client("bedrock-agent-runtime") as boto_client:
    client = guard.wrap_invoke_agent_async(
        boto_client,
        agent_role="compliance_agent", user_id="u1",
        source_id="regulatory_data", sensitivity_level=SensitivityLevel.HIGH,
        session_id=session_id,
    )
    response = await client.invoke_agent(
        agentId="ABCDEF123", agentAliasId="TSTALIASID",
        sessionId=session_id,
        inputText="Summarize Q1 compliance filings",
    )

go get github.com/vibrantcapital/autopil-go

import "github.com/vibrantcapital/autopil-go/autopil"

client := autopil.New(
    os.Getenv("AUTOPIL_BASE_URL"),  // https://your-app.onrender.com
    os.Getenv("AUTOPIL_API_KEY"),
)

// Evaluate a retrieval request
result, err := client.Context.Evaluate(ctx, autopil.EvaluateRequest{
    AgentRole:        "loan_underwriter",
    UserID:           "user_001",
    SourceID:         "credit_scores",
    SensitivityLevel: "high",
    SessionID:        sessionID,
})
if err != nil { return err }
if result.Decision == "DENY" {
    return fmt.Errorf("access denied: %s", result.Reason)
}

// Query audit events
events, err := client.Audit.ListEvents(ctx, autopil.ListEventsParams{
    AgentRole: "loan_underwriter",
    Decision:  "DENY",
    Limit:     50,
})

<dependency>
  <groupId>ai.vibrantcapital</groupId>
  <artifactId>autopil-java</artifactId>
  <version>0.1.0</version>
</dependency>

AutoPILClient client = AutoPILClient.builder()
    .baseUrl(System.getenv("AUTOPIL_BASE_URL"))  // https://your-app.onrender.com
    .apiKey(System.getenv("AUTOPIL_API_KEY"))
    .build();

// Evaluate a retrieval request
EvaluateResponse resp = client.context().evaluate(
    EvaluateRequest.builder()
        .agentRole("loan_underwriter")
        .userId("user_001")
        .sourceId("credit_scores")
        .sensitivityLevel("high")
        .sessionId(sessionId)
        .build()
);

if ("DENY".equals(resp.getDecision())) {
    throw new SecurityException(resp.getReason());
}

// Query audit events
AuditTrail trail = client.audit().getSession(sessionId);
List<AuditEvent> events = client.audit().listEvents("loan_underwriter", "DENY", 50);

python3 -m venv .venv && source .venv/bin/activate
pip install -e "packages/core[server,postgres]"
pip install -e "packages/saas[catalog]"

# Build the dashboard
cd packages/dashboard && npm install && npm run build
cp -r dist/* ../core/autopil/api/static/ && cd ../..

# Start (full stack)
AUTOPIL_DB=./autopil_audit.db \
AUTOPIL_POLICY=./policies \
AUTOPIL_SECRET_KEY=local-dev-secret \
AUTOPIL_RESET_ADMIN_KEY=1 \
autopil-saas-serve

# Build
docker build -t autopil:latest .

# Run with SQLite (minimal)
docker run -p 8000:8000 -e AUTOPIL_SECRET_KEY=your-secret autopil:latest

# Run with persistent data and custom policies
docker run -d \
  --name autopil \
  -p 8000:8000 \
  -v $(pwd)/policies:/app/policies:ro \
  -v autopil-data:/data \
  -e AUTOPIL_SECRET_KEY=your-secret \
  autopil:latest

# Docker Compose (Postgres + persistent data)
docker compose up --build

# Full Stack edition
pip install "autopil-saas[catalog]"
export DATABASE_URL=postgresql://user:pass@host:5432/autopil
export AUTOPIL_SECRET_KEY=your-secret
export AUTOPIL_POLICY=./policies
autopil-saas-serve

# Core edition
pip install "autopil[server,postgres]"
export DATABASE_URL=postgresql://user:pass@host:5432/autopil
autopil-serve --policy policies/

# Datadog
export OTEL_SERVICE_NAME=autopil
export OTEL_EXPORTER_OTLP_ENDPOINT=https://api.datadoghq.com/api/intake/otlp/v1
export OTEL_EXPORTER_OTLP_HEADERS="DD-API-KEY=your_key"

# Grafana Cloud
export OTEL_EXPORTER_OTLP_ENDPOINT=https://otlp-gateway-prod-us-east-0.grafana.net/otlp
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Basic <base64>"

# Local console (no collector needed)
export OTEL_TRACES_EXPORTER=console

AUTOPIL_LOG_PII_MASK=true