Developer Documentation

Quickstart

Wrap your AI client. Every inference is witnessed automatically. Your response is untouched.

from swt3_ai import Witness
from openai import OpenAI

witness = Witness(
    endpoint="https://sovereign.tenova.io",
    api_key="axm_live_...",
    tenant_id="YOUR_ENCLAVE",
)
client = witness.wrap(OpenAI())

# Every inference is now witnessed. Response is untouched.
response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello"}],
)
print(response.choices[0].message.content)

import { Witness } from "@tenova/swt3-ai";
import OpenAI from "openai";

const witness = new Witness({
  endpoint: "https://sovereign.tenova.io",
  apiKey: "axm_live_...",
  tenantId: "YOUR_ENCLAVE",
});
const client = witness.wrap(new OpenAI()) as OpenAI;

// Every inference is now witnessed. Response is untouched.
const response = await client.chat.completions.create({
  model: "gpt-4o",
  messages: [{ role: "user", content: "Hello" }],
});
console.log(response.choices[0].message.content);

CLI: Compliance Status at a Glance

After installing the SDK, run swt3 status to see your compliance posture. Like terraform plan for compliance.

# Brief summary (default)
$ swt3 status

# Full detail with per-procedure breakdown
$ swt3 status --full

# Machine-readable for CI/CD
$ swt3 status --json

# Filter by framework
$ swt3 status --framework EU-AI-ACT

Supported Providers

OpenAI

client = witness.wrap(OpenAI())
response = client.chat.completions.create(model="gpt-4o", messages=[...])

const client = witness.wrap(new OpenAI()) as OpenAI;
const res = await client.chat.completions.create({ model: "gpt-4o", messages: [...] });

Anthropic

client = witness.wrap(Anthropic())
message = client.messages.create(model="claude-sonnet-4-20250514", max_tokens=1024, messages=[...])

const client = witness.wrap(new Anthropic()) as Anthropic;
const msg = await client.messages.create({ model: "claude-sonnet-4-20250514", max_tokens: 1024, messages: [...] });

AWS Bedrock

import boto3
bedrock = boto3.client("bedrock-runtime", region_name="us-east-1")
client = witness.wrap(bedrock)

response = client.converse(
    modelId="anthropic.claude-3-5-sonnet-20241022-v2:0",
    messages=[{"role": "user", "content": [{"text": "Hello"}]}],
)

import { BedrockRuntimeClient, ConverseCommand } from "@aws-sdk/client-bedrock-runtime";
const client = witness.wrap(new BedrockRuntimeClient({ region: "us-east-1" }));

const res = await client.send(new ConverseCommand({
  modelId: "anthropic.claude-3-5-sonnet-20241022-v2:0",
  messages: [{ role: "user", content: [{ text: "Hello" }] }],
}));

xAI (Grok)

# Grok uses the OpenAI-compatible API
client = witness.wrap(OpenAI(
    base_url="https://api.x.ai/v1",
    api_key="xai-...",
))
response = client.chat.completions.create(model="grok-3", messages=[...])

const client = witness.wrap(new OpenAI({
  baseURL: "https://api.x.ai/v1",
  apiKey: "xai-...",
})) as OpenAI;
const res = await client.chat.completions.create({ model: "grok-3", messages: [...] });

Ollama / Local Models

# Ollama exposes an OpenAI-compatible API
from openai import OpenAI

client = witness.wrap(OpenAI(base_url="http://localhost:11434/v1"))
response = client.chat.completions.create(model="llama3", messages=[...])

Clearing Levels (Amnesia Protocol)

Clearing controls what leaves your infrastructure. Your code always gets the full response. Clearing only affects the wire payload sent to the witness ledger.

# Level 2: Healthcare / Legal - no provider names on wire
witness = Witness(
    endpoint="...", api_key="axm_...", tenant_id="...",
    clearing_level=2,
)

// Level 2: Healthcare / Legal - no provider names on wire
const witness = new Witness({
  endpoint: "...", apiKey: "axm_...", tenantId: "...",
  clearingLevel: 2,
});

Configuration Reference

Witnessed Procedures

Each inference produces anchors for these procedures. Full factor definitions are in the UCT Registry.

Inference & Model

Guardrails & Security

Agent & Access

Governance & Lifecycle

Data & Fairness

113 AI procedures across 61 namespaces and 36 regulatory frameworks. View full catalog.

Agent Witnessing

For AI agents that use tools, access resources, or operate in multi-agent chains. Every agent action produces a cryptographic anchor.

Agent Identity & Signing (AI-ID.1)

Bind a cryptographic identity to every anchor. Combined with a signing key, this provides non-repudiation: proof that a specific agent produced a specific output.

witness = Witness(
    endpoint="...", api_key="axm_...", tenant_id="...",
    agent_id="compliance-agent-v3",
    signing_key="hmac-secret-key-here",  # HMAC-SHA256
)

const witness = new Witness({
  endpoint: "...", apiKey: "axm_...", tenantId: "...",
  agentId: "compliance-agent-v3",
  signingKey: "hmac-secret-key-here",  // HMAC-SHA256
});

Tool Witnessing (AI-TOOL.1)

Witness every tool or function call your agent makes. Captures tool name, arguments hash, and outcome.

# Wrap a tool function
@witness.wrap_tool(name="search_database")
def search_db(query: str) -> list:
    return db.search(query)

# Every call to search_db() now produces an AI-TOOL.1 anchor
results = search_db("compliance violations Q1")

// Wrap a tool function
const searchDb = witness.wrapTool(
  "search_database",
  async (query: string) => db.search(query)
);

// Every call produces an AI-TOOL.1 anchor
const results = await searchDb("compliance violations Q1");

Access Control Witnessing (AI-ACC.1)

Witness resource access with scope. Proves what your agent accessed and with what permissions.

# Wrap a resource accessor
@witness.wrap_access(resource="patient_records", scope="read")
def get_patient(patient_id: str) -> dict:
    return ehr.get(patient_id)

# AI-ACC.1 anchor: resource=patient_records, scope=read, outcome=success

// Wrap a resource accessor
const getPatient = witness.wrapAccess(
  { resource: "patient_records", scope: "read" },
  async (patientId: string) => ehr.get(patientId)
);

// AI-ACC.1 anchor: resource, scope, outcome witnessed

Anchor Revocation (AI-REV.1)

Revoke a previously-issued anchor. The revocation itself is witnessed, creating an immutable record of the recall.

# Revoke an anchor by fingerprint
witness.revoke(
    fingerprint="a1b2c3d4e5f6",
    reason="model_recall",  # 7 reason codes
)

# Reason codes: unspecified, model_recall, policy_violation,
# data_contamination, consent_withdrawal, regulatory_order, error_correction

// Revoke an anchor by fingerprint
witness.revoke(
  "a1b2c3d4e5f6",
  "model_recall"  // 7 reason codes
);

// unspecified, model_recall, policy_violation,
// data_contamination, consent_withdrawal, regulatory_order, error_correction

CJT Fields (EU AI Act Compliance)

Jurisdiction, legal basis, and purpose classification fields survive all clearing levels. Required for EU AI Act Art. 12 record-keeping and GDPR lawful basis documentation.

witness = Witness(
    endpoint="...", api_key="axm_...", tenant_id="...",
    jurisdiction="DE",            # ISO 3166-1
    legal_basis="GDPR-6-1-f",     # Legitimate interest
    purpose_class="fraud_detection",
    authorization_id="AUTH-2026-0042",  # Pre-inference gate
)

const witness = new Witness({
  endpoint: "...", apiKey: "axm_...", tenantId: "...",
  jurisdiction: "DE",            // ISO 3166-1
  legalBasis: "GDPR-6-1-f",     // Legitimate interest
  purposeClass: "fraud_detection",
  authorizationId: "AUTH-2026-0042",  // Pre-inference gate
});

Gatekeeper Mode

Block inference if the witness endpoint is unreachable. For regulated environments where unwitnessed inferences are not acceptable.

witness = Witness(
    endpoint="...", api_key="axm_...", tenant_id="...",
    strict=True,  # Raises GatekeeperError if endpoint unreachable
)

# Default (strict=False): inference proceeds, witness retries in background
# Gatekeeper (strict=True): inference blocked until witness confirms

Multi-Agent Chains

Link anchors across agents in a workflow using cycle_id. Each agent in the chain references the same cycle, creating a traceable execution graph.

witness_a = Witness(endpoint="...", agent_id="planner", signing_key="...")
witness_b = Witness(endpoint="...", agent_id="executor", signing_key="...")

# Both agents share the same cycle_id
cycle = "cycle-2026-04-26-001"
client_a = witness_a.wrap(OpenAI(), cycle_id=cycle)
client_b = witness_b.wrap(OpenAI(), cycle_id=cycle)

# Anchors from both agents are linked in the ledger

Governance (v0.6.x)

Production AI systems delegate permissions, burn tokens across providers, and run on heterogeneous infrastructure. These features make governance evidence part of the witness record.

Delegation Trees (AI-DEL.1)

Witness hierarchical permission delegation with scope binding, depth tracking, and cascade revocation intent. When Agent A delegates to Agent B and B sub-delegates to Agent C, auditors need to see the full tree.

# Witness a delegation grant scoped to specific tools
witness.witness_delegation_tree(
    delegator_id="orchestrator-main",
    scope="read_file,write_file,execute_query",
    delegation_depth=2,
    delegates=["worker-alpha", "worker-beta"],
    cascade_revocation=True,
    time_bound_minutes=120,
)

# Convenience: scope from a tool list (sorted, joined automatically)
Witness.delegation_tree_from_tools(
    witness, "orchestrator", ["execute_query", "read_file", "write_file"],
    delegates=["worker-1"],
)

// Witness a delegation grant scoped to specific tools
witness.witnessDelegationTree({
  delegatorId: "orchestrator-main",
  scope: "read_file,write_file,execute_query",
  delegationDepth: 2,
  delegates: ["worker-alpha", "worker-beta"],
  cascadeRevocation: true,
  timeBoundMinutes: 120,
});

// Convenience: scope from a tool list
witness.delegationTreeFromTools({
  delegatorId: "orchestrator",
  tools: ["execute_query", "read_file", "write_file"],
  delegates: ["worker-1"],
});

Factor semantics: fa = SHA256(delegator_id)[:8] as uint32, fb = SHA256(scope)[:8] as uint32, fc = delegation depth. Delegate identities are SHA-256 hashed in context. All factors survive every clearing level.

Resource Consumption Witnessing (AI-COST.1)

Witness cumulative resource consumption -- tokens, API calls, estimated cost -- as cryptographic evidence. Verdict is always PASS. This is a notary, not a budget enforcer.

witness.witness_resource_consumption(
    tokens_in=1500,
    tokens_out=800,
    api_calls=3,
    cost_cents=12,
    provider="openai",
    model_id="gpt-4o",
    compute_seconds=2.4,
)

witness.witnessResourceConsumption({
  tokensIn: 1500,
  tokensOut: 800,
  apiCalls: 3,
  costCents: 12,
  provider: "openai",
  modelId: "gpt-4o",
  computeSeconds: 2.4,
});

Factor semantics: fa = total tokens (in + out), fb = API call count, fc = cost in cents (-1 if unknown). Supports optional deployment context for infrastructure attribution.

Deployment Context Detection

Auto-detects cloud provider, region, runtime environment, and accelerator hardware from environment variables. Results are embedded in witness payloads. Container IDs and hostnames are SHA-256 hashed before inclusion.

from swt3_ai.deployment import detect_deployment_context

ctx = detect_deployment_context()
# DeploymentContext(cloud_provider='aws', region='us-east-1',
#   runtime='kubernetes', accelerator_type='nvidia-gpu', ...)

# Pass to resource consumption witnessing
witness.witness_resource_consumption(
    tokens_in=1500, tokens_out=800, api_calls=3,
    deployment_context=ctx.to_dict(),
)

import { detectDeploymentContext } from "@tenova/swt3-ai/deployment";

const ctx = detectDeploymentContext();
// { cloud_provider: 'aws', region: 'us-east-1',
//   runtime: 'kubernetes', accelerator_type: 'nvidia-gpu', ... }

// Pass to resource consumption witnessing
witness.witnessResourceConsumption({
  tokensIn: 1500, tokensOut: 800, apiCalls: 3,
  deploymentContext: ctx,
});

Detected providers: AWS, GCP, Azure, Vultr. Runtimes: Kubernetes, Lambda, ECS, Cloud Run, Azure Functions, container, bare-metal. Accelerators: NVIDIA GPU, TPU, AWS Neuron. Cached for 5 minutes.

Lifecycle Chains (v0.6.0)

Multi-anchor governance sequences linked by shared cycle IDs. Three lifecycle procedures for operational governance:

# Emergency Override (AI-EMRG.1)
witness.witness_emergency_override(
    override_trigger="safety_incident",
    authorization_level="ciso",
    fallback_state="model_disabled",
    model_id="gpt-4o",
)

# Consequence-Mapped Drift (AI-DRIFT.2)
witness.witness_drift_consequence(
    drift_metric="psi",
    drift_value=0.23,
    threshold=0.15,
    consequence_category="financial_loss",
    response_action="retrain",
    model_id="fraud-model-v3",
)

# Champion-Challenger Assessment (AI-ASSESS.1)
witness.witness_assessment(
    champion_id="model-v2",
    challenger_id="model-v3",
    metric_name="auc_roc",
    champion_score=0.92,
    challenger_score=0.95,
    decision="promote_challenger",
)

// Emergency Override (AI-EMRG.1)
witness.witnessEmergencyOverride({
  overrideTrigger: "safety_incident",
  authorizationLevel: "ciso",
  fallbackState: "model_disabled",
  modelId: "gpt-4o",
});

// Consequence-Mapped Drift (AI-DRIFT.2)
witness.witnessDriftConsequence({
  driftMetric: "psi",
  driftValue: 0.23,
  threshold: 0.15,
  consequenceCategory: "financial_loss",
  responseAction: "retrain",
  modelId: "fraud-model-v3",
});

// Champion-Challenger Assessment (AI-ASSESS.1)
witness.witnessAssessment({
  championId: "model-v2",
  challengerId: "model-v3",
  metricName: "auc_roc",
  championScore: 0.92,
  challengerScore: 0.95,
  decision: "promote_challenger",
});

Auto-Chaining Context Manager (v0.6.2)

Scope multiple witness calls into a single auditable cycle. All anchors within a chain block share a cycle_id for forensic reconstruction.

# All anchors within this block share a cycle_id
with witness.chain("loan-review-workflow") as ctx:
    result = client.chat.completions.create(model="gpt-4o", messages=[...])
    witness.witness(procedure="AI-FAIR.1", factor_a="bias-check", ...)
    witness.wrap_tool(tool_name="credit_lookup", ...)
    # 3 anchors, 1 cycle_id, complete audit trail

// All anchors within this block share a cycle_id
await witness.chain("loan-review-workflow", async () => {
  const result = await client.chat.completions.create({model: "gpt-4o", messages: [...]});
  witness.witness({procedure: "AI-FAIR.1", factorA: "bias-check", ...});
  witness.wrapTool({toolName: "credit_lookup", ...});
});

Chains support nesting. If an exception occurs, the chain is marked incomplete (flagged during forensic reconstruction). Use swt3 reconstruct --cycle CYCLE_ID to view the full chain.

Gate Configuration (v0.6.2)

Define compliance policy as code in a .swt3-gate.yml file. Generate, validate, and evaluate against your live ledger.

# Generate a gate config from a framework crosswalk
swt3 gate --init --framework EU-AI-ACT

# Validate offline (no API key needed)
swt3 gate --validate

# Evaluate against live ledger (CI/CD gate)
swt3 gate --framework eu-ai-act
# Exit code 0 = PASS, 1 = FAIL/WARN

36 frameworks supported. The gate config is the shared artifact between developer and assessor. Full specification: Gate Config Guide

Crosswalk Resolve (v0.5.9)

Map any procedure to every regulatory framework it satisfies. Offline, no network call.

from swt3_ai import Witness

# Which frameworks does AI-INF.1 satisfy?
mappings = Witness.resolve("AI-INF.1")
# [{"framework": "EU-AI-ACT", "article": "Art.12(1)"}, ...]

# Coverage report for a framework
report = Witness.coverage("EU-AI-ACT")
# {"framework": "EU-AI-ACT", "total": 50, "covered": 42, "score": 0.84, ...}

import { Witness } from "@tenova/swt3-ai";

// Which frameworks does AI-INF.1 satisfy?
const mappings = Witness.resolve("AI-INF.1");
// [{ framework: "EU-AI-ACT", article: "Art.12(1)" }, ...]

// Coverage report for a framework
const report = Witness.coverage("EU-AI-ACT");
// { framework: "EU-AI-ACT", total: 50, covered: 42, score: 0.84, ... }

Factor Handoff (Clearing Level 2+)

At Clearing Level 2+, factors are purged from the wire. Factor Handoff writes uncleared factor data to a local file before clearing proceeds. The handoff writes BEFORE clearing. If the write fails, the payload is NOT transmitted.

witness = Witness(
    endpoint="...",
    api_key="axm_...",
    tenant_id="...",
    clearing_level=2,
    factor_handoff="file",
    factor_handoff_path="/secure/handoff/",
)

const witness = new Witness({
  endpoint: "...",
  apiKey: "axm_...",
  tenantId: "...",
  clearingLevel: 2,
  factorHandoff: "file",
  factorHandoffPath: "/secure/handoff/",
});

Full protocol spec: Factor Handoff Protocol

Advanced

Custom Pipelines

# Decorator for custom inference functions
@witness.inference()
def my_pipeline(prompt: str) -> str:
    # Your custom logic
    return result

# Or manual recording
from swt3_ai.types import InferenceRecord
from swt3_ai.fingerprint import sha256_truncated

record = InferenceRecord(
    model_id="my-model-v2",
    model_hash=sha256_truncated("my-model-v2"),
    prompt_hash=sha256_truncated(prompt),
    response_hash=sha256_truncated(response),
    latency_ms=elapsed_ms,
    provider="custom",
)
witness.record(record)

// Manual recording for custom pipelines
witness.record({
  modelId: "my-model-v2",
  modelHash: sha256Truncated("my-model-v2"),
  promptHash: sha256Truncated(prompt),
  responseHash: sha256Truncated(response),
  latencyMs: elapsedMs,
  provider: "custom",
});

NVIDIA Dynamo Integration

Two-layer architecture for infrastructure-level witnessing on NVIDIA Dynamo inference servers.

# Layer 1: Decorator (zero Dynamo dependencies)
from swt3_ai.adapters.dynamo import witness_endpoint

@witness_endpoint()
async def generate(request):
    async for chunk in model.generate(request.prompt):
        yield chunk

# Configure via SWT3_DSN (single env var)
# SWT3_DSN=https://axm_live_xxx@sovereign.tenova.io/YOUR_TENANT_ID
# Replace YOUR_TENANT_ID with the tenant ID from your dashboard Settings page

# Layer 2: Service-graph (Dynamo-native, pip install swt3-ai[dynamo])
from swt3_ai.adapters.dynamo_infra import WitnessInterceptor
# Injects as @service into Dynamo's depends() graph
# Adds swt3_witness_total, swt3_clearing_level metrics

OTel Export

Export witness telemetry to any OpenTelemetry-compatible backend (Jaeger, Grafana, Datadog).

from swt3_ai.exporters.otel import OTelExporter

witness = Witness(
    endpoint="...", api_key="axm_...", tenant_id="...",
    on_flush=OTelExporter(
        endpoint="http://localhost:4318/v1/traces"
    ),
)

import { OTelExporter } from "@tenova/swt3-ai/exporters/otel";

const witness = new Witness({
  endpoint: "...", apiKey: "axm_...", tenantId: "...",
  onFlush: new OTelExporter({
    endpoint: "http://localhost:4318/v1/traces",
  }),
});

Flight Recorder (Resilience)

The SDK never blocks your inference. Witnessing happens in a background thread/microtask. If the endpoint is unreachable, payloads move to a dead-letter queue and drain automatically when connectivity is restored.

# Python: Check dead-letter status
print(f"Pending: {witness.pending}")

# Graceful shutdown (also happens at exit)
receipts = witness.flush()

Platform Security

Axiom container images are scanned daily for vulnerabilities. Zero-critical-CVE policy enforced. All findings are automatically documented as POA&M entries with severity-based remediation timelines (CRITICAL: 7d, HIGH: 30d, MEDIUM: 90d). Scan results are self-anchored in the witness ledger (RA-5/SI-2).

Verification

Every anchor can be independently verified without an Axiom account.

# CLI
$ axiom verify SWT3-E-CLOUD-AI-AI-INF.2-PASS-1774995559-a1b2c3d4e5f6

# Browser (zero server calls)
sovereign.tenova.io/verify

# Formula
SHA256("WITNESS:{tenant}:{procedure}:{fa}:{fb}:{fc}:{ts_ms}")[0:12]