Documentation Index
spanforge (
spanforge) — The reference implementation of the spanforge Standard (RFC-0001), the open event-schema standard for compliance and governance of agentic AI systems.
Current release: 2.0.14 — Changelog ·
This index links to every documentation page in this folder.
Getting Started
| Page | Description |
|---|---|
| Quickstart | Create your first event, sign a chain, and export — in 5 minutes |
| Installation | Install from PyPI, optional extras, and dev setup |
| Runtime Governance GA Guide | The end-to-end Phase 1–6 control-plane story: GA services, policy actions, replay/simulation, operator workflow, and evidence exports |
| GA Release Notes | The May 2, 2026 GA scope, what shipped, and what stayed out of scope |
User Guide
| Page | Description |
|---|---|
| User Guide | Overview of all user guide topics |
| Events | Event envelope, event types, serialisation, validation, ULIDs |
| Tracing API | Trace, start_trace(), async context managers, span.add_event(), error categories, timeout deadline |
| HMAC Signing & Audit Chains | Sign events, build tamper-evident chains, detect tampering |
| PII Redaction | Sensitivity levels, redaction policies, PII detection |
| Compliance & Tenant Isolation | Compatibility checklist, chain integrity, tenant isolation, ComplianceMappingEngine, evidence packages, regulatory framework mappings (EU AI Act, ISO 42001, NIST AI RMF, GDPR, SOC 2), HMAC-signed attestations, consent/HITL/model-registry/explainability clause integration, model owner & risk-tier enrichment, explanation_coverage_pct metric |
| Export Backends & EventStream | JSONL, Webhook, OTLP, Datadog, Grafana Loki, Cloud exporters; EventStream; Kafka source |
| Governance, Consumer Registry & Deprecations | Block/warn event types, declare schema dependencies, track deprecations |
| Migration Guide | v2 migration roadmap, deprecation records, v1_to_v2() scaffold |
| Debugging & Visualization | print_tree(), summary(), visualize(), and sampling controls |
| Metrics & Analytics | metrics.aggregate(), MetricsSummary, TraceStore, get_trace() |
| Semantic Cache | SemanticCache, @cached decorator, InMemoryBackend, SQLiteBackend, RedisBackend |
| Linting & Static Analysis | run_checks(), AO001–AO005 error codes, flake8 plugin, CI integration |
| Audit Service (sf-audit) | sf_audit.append(), schema keys, T.R.U.S.T. scorecard, chain verification, GDPR Article 30, BYOS routing |
| Alert Routing Service (sf-alert) | sf_alert.publish(), topic registry, deduplication, rate limiting, escalation policy, maintenance windows, sinks (Slack, Teams, PagerDuty, OpsGenie, VictorOps, Incident.io, SMS, Webhook) |
| Gate Pipeline (sf-gate) | sf_gate.evaluate(), YAML pipeline runner, 6 gate executors, PRRI gate, trust gate, artifact store, CI/CD integration (Phase 8) |
| Runtime Governance GA Guide | Core GA services, policy actions, operator workflow, replay/simulation, evidence packaging |
| Runtime Governance Contracts | Stable GA service contracts, policy actions, evidence contract, and failure/fallback semantics |
| Replay, Simulation, and Calibration | Phase 3 workflow for replay, candidate simulation, policy comparison, and false-positive review |
| Evidence Export Guide | Operator packages, enterprise packages, JSONL archives, SIEM export, and OpenInference bridge |
| Enterprise Integrations | OpenAI, Anthropic, Azure OpenAI, LangChain, LangGraph, OTLP, JSONL, SIEM, and OpenInference coverage |
| Runtime Governance Comparison | Positioning and comparison for the runtime-governance control-plane story |
| RAG Tracing | sf_rag.trace_query(), retrieval scoring, grounding, session lifecycle, privacy controls (Phase 13) |
| User Feedback | sf_feedback.submit(), rating enums (NPS/CSAT/thumbs), T.R.U.S.T. integration (Phase 13) |
| SSO & Identity | SFIdentityClient — SAML 2.0, SCIM 2.0, OIDC PKCE, SSO session delegation, session revocation (Phase 13 / v2.0.14) |
API Reference
| Page | Module |
|---|---|
| API Reference | Module summary and full listing |
| event | spanforge.event — Event envelope and serialisation |
| types | spanforge.types — EventType enum, custom type validation |
| signing | spanforge.signing — HMAC signing and AuditStream |
| redact | spanforge.redact — Redactable, RedactionPolicy, PII helpers |
| compliance | spanforge.compliance — Compatibility and isolation checks |
| export | spanforge.export — OTLP, Webhook, JSONL, Datadog, Grafana Loki, Cloud backends |
| stream | spanforge.stream — EventStream multiplexer with Kafka support |
| validate | spanforge.validate — JSON Schema validation |
| migrate | spanforge.migrate — Migration scaffold, SunsetPolicy, v2_migration_roadmap() |
| consumer | spanforge.consumer — ConsumerRegistry, IncompatibleSchemaError |
| governance | spanforge.governance — EventGovernancePolicy, GovernanceViolationError |
| deprecations | spanforge.deprecations — DeprecationRegistry, warn_if_deprecated() |
| integrations | spanforge.integrations — LangChain, LlamaIndex, OpenAI, CrewAI adapters |
| trace | spanforge._trace — Trace class and start_trace() |
| debug | spanforge.debug — print_tree(), summary(), visualize() |
| metrics | spanforge.metrics — aggregate(), MetricsSummary, LatencyStats |
| store | spanforge._store — TraceStore and MCP trace access functions |
| hooks | spanforge._hooks — HookRegistry, hooks singleton, sync and async lifecycle hooks |
| testing | spanforge.testing — MockExporter, capture_events(), assert_event_schema_valid(), trace_store() |
| auto | spanforge.auto — setup() / teardown() integration auto-discovery |
| ulid | spanforge.ulid — ULID generation and helpers |
| exceptions | spanforge.exceptions — Exception hierarchy |
| models | spanforge.models — Pydantic v2 model layer |
| cache | spanforge.cache — SemanticCache, @cached, backends, CacheEntry, CacheBackendError |
| lint | spanforge.lint — run_checks(), LintError, AO001–AO005, flake8 plugin, CLI |
| http | spanforge.http — HTTP trace viewer and /traces endpoint |
| io | spanforge.io — Event I/O helpers (read/write JSONL) |
| plugins | spanforge.plugins — Plugin discovery and loading |
| schema | spanforge.schema — Schema utilities and version helpers |
| regression | spanforge.regression — Regression detection and alerting |
| stats | spanforge.stats — Statistical helpers and summary functions |
| eval | spanforge.eval — Evaluation scorers and dataset management |
| consent | spanforge.consent — Consent tracking and data-subject management |
| hitl | spanforge.hitl — Human-in-the-loop review queues |
| model_registry | spanforge.model_registry — Model registration, risk tiers, ownership |
| explain | spanforge.explain — Explainability records and coverage metrics |
| presidio_backend | spanforge.presidio_backend — Presidio-based PII detection backend |
| cost | spanforge.cost — Cost tracking and budget management |
| identity | spanforge.sdk.identity — SFIdentityClient, API keys, sessions, TOTP, magic links, SAML 2.0 ACS, SCIM 2.0 User/Group CRUD, OIDC PKCE relying party, SSO session delegation |
| secrets | spanforge.secrets — SecretsScanner, SecretsScanResult, SecretHit, 20-pattern registry, SARIF output |
| pii | spanforge.sdk.pii — SFPIIClient, PII scanning, anonymisation, GDPR Art.17 erasure, CCPA DSAR, HIPAA safe harbor, DPDP consent gate, PIPL entity types (Phase 3) |
| audit | spanforge.sdk.audit — SFAuditClient, HMAC chain, schema key registry, T.R.U.S.T. scorecard, Article 30, BYOS routing (Phase 4) |
| cec | spanforge.sdk.cec — SFCECClient, signed ZIP compliance bundles, 5-framework clause mapping, verify_bundle(), generate_dpa(), get_bundle(), reissue_download_url(), HMAC signing, BYOS detection (Phase 5) |
| observe | spanforge.sdk.observe — SFObserveClient, span export (OTLP/Datadog/Grafana/Splunk/Elastic/local), emit_span(), annotation store, W3C TraceContext, OTel GenAI attrs, sampling strategies, health probes (Phase 6) |
| alert | spanforge.sdk.alert — SFAlertClient, topic-based publish, deduplication, rate limiting, escalation policy, maintenance windows, circuit breakers, 6 sink integrations (Phase 7) |
| gate | spanforge.sdk.gate — SFGateClient, GateRunner YAML engine, 6 gate executors, PRRI evaluation, trust gate, GateArtifact store (Phase 8) |
| explain | spanforge.sdk.explain — SFExplainClient, runtime explanation records |
| policy | spanforge.sdk.policy — runtime policy bundles, decisions, replay, simulation, review |
| scope | spanforge.sdk.scope — SFScopeClient, capability enforcement |
| rbac | spanforge.sdk.rbac — SFRBACClient, role enforcement |
| lineage | spanforge.sdk.lineage — SFLineageClient, provenance capture |
| operator | spanforge.sdk.operator — SFOperatorClient, operator inspect/export workflow |
| config | spanforge.sdk.config — .halluccheck.toml parser, SFConfigBlock, SFServiceToggles, SFLocalFallbackConfig, load_config_file(), validate_config(), validate_config_strict() (Phase 9) |
| registry | spanforge.sdk.registry — ServiceRegistry singleton, health checks, background checker, status_response(), ServiceHealth, ServiceStatus (Phase 9) |
| fallback | spanforge.sdk.fallback — 8 local fallback implementations: pii_fallback(), secrets_fallback(), audit_fallback(), observe_fallback(), alert_fallback(), identity_fallback(), gate_fallback(), cec_fallback() (Phase 9) |
| trust | spanforge.sdk.trust — SFTrustClient, T.R.U.S.T. five-pillar scorecard, SVG badge, history time-series, configurable weights (Phase 10) |
| pipelines | spanforge.sdk.pipelines — 5 HallucCheck pipeline integrations (Phase 10) |
| enterprise | spanforge.sdk.enterprise — SFEnterpriseClient, multi-tenancy, encryption, air-gap, health probes (Phase 11) |
| security | spanforge.sdk.security — SFSecurityClient, OWASP audit, STRIDE threat model, dependency scanning, secrets-in-logs (Phase 11) |
| testing_mocks | spanforge.testing_mocks — 11 mock service clients, mock_all_services() context manager, _MockBase call recording (Phase 12) |
| sdk-reference | SDK reference overview — all 11 service clients, configuration, testing, CLI quick reference (Phase 12) |
| rag | spanforge.sdk.rag — SFRAGClient, session lifecycle, retrieval/generation tracing (Phase 13) |
| feedback | spanforge.sdk.feedback — SFFeedbackClient, rating enums, NPS/CSAT/thumbs, T.R.U.S.T. linking (Phase 13) |
| identity | spanforge.sdk.identity — SFIdentityClient, SAML 2.0, SCIM 2.0, OIDC PKCE, SSO session delegation/revocation, SCIMUser, SCIMGroup, OIDCAuthRequest, SSOSession (Phase 13 / v2.0.14) |
Namespace Payload Catalogue
| Page | Namespace | Purpose |
|---|---|---|
| Namespace index | — | Overview and quick-reference table |
| trace | llm.trace.* | Model inputs, outputs, latency, token counts |
| cost | llm.cost.* | Per-event cost estimates and budget tracking |
| cache | llm.cache.* | Cache hit/miss, key, TTL, backend metadata |
| diff | llm.diff.* | Prompt/response delta between two events |
| eval | llm.eval.* | Scoring, grading, and human-feedback payloads |
| fence | llm.fence.* | Perimeter checks, topic constraints, allow/block lists |
| guard | llm.guard.* | Safety classifier outputs and block decisions |
| prompt | llm.prompt.* | Prompt versioning, template rendering, variable sets |
| redact_ns | llm.redact.* | PII detection and redaction audit records |
| template | llm.template.* | Template registry metadata and render snapshots |
| audit | llm.audit.* | HMAC audit chain events |
| retrieval | llm.retrieval.* | RAG query, chunk, generation, and session payloads |
| feedback | llm.feedback.* | User feedback rating payloads and summaries |
Command-Line Interface
| Page | Description |
|---|---|
| CLI | spanforge command reference: check, check-compat, validate, audit-chain, audit, scan, migrate, inspect, stats, list-deprecated, migration-roadmap, check-consumers, compliance, cost, dev, module, serve, init, quickstart, report, eval, migrate-langsmith, ui, consent, hitl, model, explain, secrets, gate, config, trust, enterprise, security, doctor |
Demos
| Page | Description |
|---|---|
| Runtime Governance Demo | Trace-to-operator-package walkthrough using the GA runtime-governance services |
| Enterprise Evidence Demo | Enterprise deployment and evidence-packaging walkthrough |
Deployment Architecture
| Page | Description |
|---|---|
| Reference Architectures | Self-hosted, Kubernetes, and air-gapped deployment references used by enterprise evidence packages |
| Air-Gapped Deployment | No-egress deployment guidance |
| Kubernetes Deployment | Self-hosted Kubernetes and Helm deployment guidance |
Development
| Page | Description |
|---|---|
| Contributing | Dev setup, code standards, PR checklist |
| Changelog | Version history and release notes |