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);

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" }] }],
}));

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.

Governance Attestations

36 AI procedures + 5 FinTech (SR 11-7) + 5 Construction (OSHA) + 3 Healthcare (HIPAA) + 113 Infrastructure = 162 total across 13 frameworks. View full catalog.

FinTech Model Risk (SR 11-7)

Factor Handoff (Clearing Level 2+)

At Clearing Level 2 and above, factors are purged from the wire. The Factor Handoff protocol lets you retain full evidence custody on your own infrastructure by writing uncleared factor data to a local file before clearing proceeds.

Safety guarantee: The handoff writes factors BEFORE clearing. If the write fails, the payload is NOT transmitted. Evidence custody is preserved or nothing happens.

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/",
});

Each inference produces a JSON file with the full uncleared data (factors + metadata). The file is written atomically (temp + rename) with 0600 permissions. Your infrastructure retains the evidence; Axiom only receives the cleared version.

Full protocol spec: Factor Handoff Protocol

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 WitnessError 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

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/MY_TENANT

# 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]