SpanForge PlatformSpanForge SDK
spanforge · Python 3.9+ · Generally Available

The reference implementation.

pip install spanforge — zero required dependencies, all 15 spanforge namespaces, a full CLI, and integrations for OpenAI, Anthropic, LangChain, LangGraph, LlamaIndex, CrewAI, Datadog, and more.

Debug tooling →Read the standard →
Installation

Get started in one command.

Install the base SDK with no required dependencies. Add optional extras for the integrations and export targets you need.

pip install spanforge

Verify the installation:

bash
spanforge --version
# spanforge 1.0.4

Optional extras

ExtraWhat it adds
spanforge[jsonschema]Enables runtime schema validation of every emitted event against the published JSON Schema.
spanforge[identity]SFIdentityClient RS256 JWT support via cryptography; required when connecting to a remote sf-identity service (local mode uses stdlib HS256).
spanforge[openai]Auto-instrumentation for the openai Python client — wraps chat completions, embeddings, and responses. Includes unified pricing table covering OpenAI, Anthropic, Groq, and Together AI.
spanforge[anthropic]Anthropic Claude SDK integration — instrumented Claude calls with cost normalisation and cross-provider trace context.
spanforge[gemini]Google Gemini SDK integration — instrumented Gemini calls with full trace context.
spanforge[bedrock]AWS Bedrock integration — instrumented Bedrock model calls.
spanforge[ollama]Ollama local model integration — instrumented local inference calls.
spanforge[groq]Groq inference integration — high-speed inference tracing with cost normalisation.
spanforge[together]Together AI integration — instrumented Together AI model calls.
spanforge[http]OTLP/HTTP export and webhook export targets.
spanforge[pydantic]Pydantic v2 model support for typed payload validation.
spanforge[otel]Full OpenTelemetry SDK integration — exports spans as OTLP proto via gRPC or HTTP.
spanforge[kafka]Apache Kafka export backend for streaming event pipelines.
spanforge[langchain]LangChain callback handler — instruments chain, tool, and LLM calls automatically.
spanforge[llamaindex]LlamaIndex event handler — instruments query, retrieval, and LLM calls.
spanforge[crewai]CrewAI task-and-agent lifecycle instrumentation.
spanforge[presidio]Presidio NLP PII backend — 15 entity types (SSN, email, phone, AADHAAR, PAN, UK NI, credit card, IBAN, and more) with ≥ 95% true-positive rate and < 0.5% false-positive rate. Requires python -m spacy download en_core_web_lg.
spanforge[redis]RedisExporter and RedisBackend for semantic cache.
spanforge[compliance]Extended compliance mapping dependencies for framework clause engines.
spanforge[worm-s3]Append-only S3 export backend with Object Lock (WORM) for tamper-proof audit storage.
spanforge[worm-gcs]Append-only GCS export backend (WORM) for tamper-proof audit storage.
spanforge[datadog]Datadog exporter — ships events to DD APM as custom spans.
spanforge[all]Installs all optional extras in a single command.
Quickstart

Your first event.

Every event in the spanforge standard is an Event object with three required arguments: event_type, source, and payload.

python
from spanforge import Event, EventType

# Minimal event
event = Event(
    event_type=EventType.TRACE_SPAN_COMPLETED,
    source="my-service@0.1.0",
    payload={"span_name": "summarise", "status": "ok"},
)

# Event is ready to emit or inspect
print(event.event_id)    # ULID e.g. 01HZQSN7PQVR2K4M0BXJD3GSTA
print(event.timestamp)   # ISO-8601 UTC
print(event.trace_id)    # W3C-compatible 128-bit hex

Typed namespace payloads

Use the typed payload classes from each namespace for full schema validation and IDE autocompletion. The classes map 1-to-1 to the published JSON Schema.

python
from spanforge import Event, EventType
from spanforge.namespaces.trace import SpanPayload, TokenUsage, ModelInfo, GenAISystem

event = Event(
    event_type=EventType.TRACE_SPAN_COMPLETED,
    source="spanforge@1.0.0",
    payload=SpanPayload(
        span_name="summarise_document",
        span_kind="LLM",
        status="ok",
        duration_ms=830,
        token_usage=TokenUsage(input_tokens=411, output_tokens=128, total_tokens=539),
        model_info=ModelInfo(system=GenAISystem.OPENAI, name="gpt-4o"),
    ).to_dict(),
    tags=["prod", "summarisation"],
)

# Export to OTLP
from spanforge.export import OTLPExporter
exporter = OTLPExporter(endpoint="http://localhost:4317")
exporter.export(event)
Integrations

Works with your existing stack.

Install the relevant extra and add one line of code. spanforge events are emitted automatically — you retain full compliance instrumentation without rewriting your existing code.

OpenAI · spanforge[openai]

OpenAI

One-line auto-instrumentation for the openai Python client. Wraps chat completions, embeddings, and the Responses API. Emits llm.trace.span and llm.cost.* events automatically.

Anthropic · spanforge[anthropic]

Anthropic

Anthropic Claude SDK integration with cross-provider cost normalisation and full trace context propagation.

Azure OpenAI · spanforge[openai]

Azure OpenAI

Instance-level instrumentation for Azure-hosted OpenAI clients via spanforge.integrations.azure_openai — token, model, and cost telemetry attached automatically to active spans.

LangChain · spanforge[langchain]

LangChain

Drop-in callback handler. Instruments chain invocations, tool calls, and LLM calls. Compatible with LangChain v0.1 and v0.2.

LangGraph · spanforge[langchain]

LangGraph

Governance-aware agent graph instrumentation — node-level scope, RBAC, and lineage coverage for agentic workflow tracing.

LlamaIndex · spanforge[llamaindex]

LlamaIndex

Event handler for the LlamaIndex instrumentation API. Captures query, retrieval, embedding, and LLM events with full trace context.

CrewAI · spanforge[crewai]

CrewAI

Task and agent lifecycle instrumentation for CrewAI. Captures agent run start/end, task assignment, and tool delegation events.

Datadog · spanforge[datadog]

Datadog

Export spanforge span events as custom Datadog APM spans. Compatible with the Datadog Agent and the dd-trace-py client.

OpenTelemetry · spanforge[otel]

OpenTelemetry

Full OTLP bridge. Converts spanforge span events to OpenTelemetry proto-compatible dicts and exports via gRPC or HTTP. Works with any OTEL-compatible backend.

Command-line interface

Operational tooling included.

The spanforge CLI is installed automatically with the SDK. Use it for health checks, schema validation, audit-chain verification, compliance evidence generation, and PII scanning.

spanforge checkEnd-to-end health check: config, event creation, schema validation, export pipeline, trace store.
spanforge check-compatValidate a batch of events against the v1.0 compatibility checklist (CHK-1 through CHK-5).
spanforge validateValidate every event in a JSONL file against the published JSON Schema.
spanforge audit-chainVerify HMAC-SHA256 signing chain integrity of events in a JSONL file.
spanforge complianceGenerate HMAC-signed compliance evidence packages mapped to EU AI Act, GDPR, SOC 2, HIPAA, ISO 42001, and NIST AI RMF.
spanforge compliance readinessScored pre-production readiness checklist for any supported framework — exits 0 (all pass), 1 (failures), or 2 (unknown framework).
spanforge compliance reportGenerate a compliance gap report in JSON, Markdown, or both formats, including remediation steps for every open clause.
spanforge operator inspectInspect a trace: review the policy decision, explanation, grounding, scope, RBAC, and lineage evidence.
spanforge operator exportExport a signed operator evidence package from a trace for auditor hand-off.
spanforge auditAudit chain management: erase, rotate-key, check-health, verify.
spanforge scanScan a JSONL file for PII using built-in regex detectors.
spanforge validate --datasetTraining Data Compliance Scanner — scan a training dataset JSONL for PII, consent records, and data provenance. New in v1.0.3.
spanforge doctorHealth check including live compliance posture: EU AI Act clause pass/total count and gap summary.
spanforge inspectPretty-print a single event by event_id from a JSONL file.
spanforge statsPrint event-type counts, trace count, and time range for a JSONL file.
spanforge reportGenerate a static HTML trace report from a JSONL events file.
spanforge serveStart a local HTTP trace viewer at /traces (default port 8888).
spanforge check-consumersAssert all registered consumers are compatible with the installed schema.
spanforge config initInteractive wizard (or --non-interactive) to generate ~/.spanforge/config.yaml with exporter, service name, environment, endpoint, signing key, and log level.
spanforge config validateValidate ~/.spanforge/config.yaml against the SpanForge schema. --check-connectivity probes TCP connectivity to the OTLP endpoint. Exit codes: 0 valid, 1 schema errors, 2 read error.
spanforge secrets setStore a named secret in the local secrets store (~/.spanforge/secrets.db, permissions 0o600).
spanforge secrets getRetrieve and print a stored secret value by name.
spanforge secrets listList stored secret key names (values not shown).
spanforge secrets deleteRemove a named secret from the local secrets store.
spanforge dev resetDelete ~/.spanforge/config.yaml (interactive prompt). --dry-run lists files that would be removed without deleting them.
spanforge export siemStream CEF or LEEF formatted lines from a JSONL events file (or stdin) to any SIEM. Options: --format cef|leef, --input FILE.
spanforge audit cec generateGenerate a Compliance Evidence Chain bundle without Python code — signed ZIP with regulatory clause maps, DPA generation, and RFC 3161 timestamps for auditor hand-off.
bash
# End-to-end health check
spanforge check
# [1/5] Config ............. OK
# [2/5] Event creation ..... OK
# [3/5] Schema validation .. OK
# [4/5] Export pipeline .... OK
# [5/5] Trace store ........ OK
# All checks passed.

# Validate a JSONL event stream
spanforge validate production-events.jsonl

# Scan for PII before export
spanforge scan production-events.jsonl

# Generate compliance evidence package
spanforge compliance production-events.jsonl --framework eu-ai-act
Code quality

SDK instrumentation linter.

The built-in linter parses your Python source with ast and runs five checks to catch common instrumentation mistakes before they reach production. Integrates natively with flake8 and ruff.

AO001Event() missing one of event_type, source, or payload.
AO002Bare str literal passed to actor_id, session_id, or user_id — wrap in Redactable().
AO003event_type= string not present in registered EventType values.
AO004LLM provider API call outside a tracer.span() / agent_run() context.
AO005emit_span / emit_agent_* called outside agent_run() / agent_step() context.
Next steps

Inspect. Validate. Ship.

Use SpanForge Debug to inspect and replay compliance traces, and SpanForge Validate to enforce schema compliance in your CI pipeline.

SpanForge Debug →SpanForge Validate →
← RFC-0001 StandardSpanForge Debug →