Metadata-Version: 2.4
Name: spanforge
Version: 1.0.1
Summary: SpanForge — AI lifecycle and governance platform (RFC-0001 SPANFORGE)
Project-URL: Homepage, https://github.com/veerarag1973/spanforge
Project-URL: Documentation, https://github.com/veerarag1973/spanforge/blob/main/docs/index.md
Project-URL: Source, https://github.com/veerarag1973/spanforge
Project-URL: Bug Tracker, https://github.com/veerarag1973/spanforge/issues
Project-URL: Changelog, https://github.com/veerarag1973/spanforge/blob/main/docs/changelog.md
Author: viswanathanstartup
License: PolyForm-Noncommercial-1.0.0
License-File: LICENSE
Keywords: agentic-ai,ai-compliance,ai-lifecycle,events,governance,llm,opentelemetry,schema,spanforge
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: Other/Proprietary License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Logging
Classifier: Typing :: Typed
Requires-Python: >=3.9
Provides-Extra: all
Requires-Dist: anthropic>=0.25; extra == 'all'
Requires-Dist: crewai>=0.28; extra == 'all'
Requires-Dist: cryptography>=46.0.7; extra == 'all'
Requires-Dist: httpx>=0.27; extra == 'all'
Requires-Dist: jsonschema>=4.21; extra == 'all'
Requires-Dist: kafka-python>=2.0; extra == 'all'
Requires-Dist: langchain-core>=0.2; extra == 'all'
Requires-Dist: langgraph>=0.2; extra == 'all'
Requires-Dist: llama-index-core>=0.10; extra == 'all'
Requires-Dist: openai>=1.0; extra == 'all'
Requires-Dist: opentelemetry-sdk>=1.24; extra == 'all'
Requires-Dist: pydantic>=2.7; extra == 'all'
Requires-Dist: redis>=4.0; extra == 'all'
Provides-Extra: anthropic
Requires-Dist: anthropic>=0.25; extra == 'anthropic'
Provides-Extra: bedrock
Requires-Dist: boto3>=1.34; extra == 'bedrock'
Provides-Extra: compliance
Requires-Dist: reportlab>=4.0; extra == 'compliance'
Provides-Extra: crewai
Requires-Dist: crewai>=0.28; extra == 'crewai'
Provides-Extra: datadog
Provides-Extra: dev
Requires-Dist: httpx>=0.27; extra == 'dev'
Requires-Dist: hypothesis>=6.100; extra == 'dev'
Requires-Dist: jsonschema>=4.21; extra == 'dev'
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pre-commit>=3.7; extra == 'dev'
Requires-Dist: pydantic>=2.7; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest-benchmark>=4.0; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest-xdist>=3.5; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.4.0; extra == 'dev'
Provides-Extra: docs
Requires-Dist: pydata-sphinx-theme>=0.15; extra == 'docs'
Requires-Dist: sphinx>=7.0; extra == 'docs'
Provides-Extra: gemini
Requires-Dist: google-generativeai>=0.5; extra == 'gemini'
Provides-Extra: groq
Requires-Dist: groq>=0.9; extra == 'groq'
Provides-Extra: http
Requires-Dist: httpx>=0.27; extra == 'http'
Provides-Extra: identity
Requires-Dist: cryptography>=46.0.7; extra == 'identity'
Provides-Extra: jsonschema
Requires-Dist: jsonschema>=4.21; extra == 'jsonschema'
Provides-Extra: kafka
Requires-Dist: kafka-python>=2.0; extra == 'kafka'
Provides-Extra: langchain
Requires-Dist: langchain-core>=0.2; extra == 'langchain'
Provides-Extra: langgraph
Requires-Dist: langgraph>=0.2; extra == 'langgraph'
Provides-Extra: llamaindex
Requires-Dist: llama-index-core>=0.10; extra == 'llamaindex'
Provides-Extra: ollama
Requires-Dist: ollama>=0.2; extra == 'ollama'
Provides-Extra: openai
Requires-Dist: openai>=1.0; extra == 'openai'
Provides-Extra: otel
Requires-Dist: opentelemetry-sdk>=1.24; extra == 'otel'
Provides-Extra: presidio
Requires-Dist: presidio-analyzer>=2.2; extra == 'presidio'
Requires-Dist: presidio-anonymizer>=2.2; extra == 'presidio'
Provides-Extra: pydantic
Requires-Dist: pydantic>=2.7; extra == 'pydantic'
Provides-Extra: redis
Requires-Dist: redis>=4.0; extra == 'redis'
Provides-Extra: together
Requires-Dist: together>=1.2; extra == 'together'
Provides-Extra: worm-gcs
Requires-Dist: google-cloud-storage>=2.14; extra == 'worm-gcs'
Provides-Extra: worm-s3
Requires-Dist: boto3>=1.34; extra == 'worm-s3'
Description-Content-Type: text/markdown

<h1 align="center">spanforge</h1>

<p align="center">
  <strong>The AI Compliance Platform for Agentic Systems.</strong><br/>
  Ship AI applications that are auditable, regulator-ready, and privacy-safe — from day one.
</p>

<p align="center">
  <em>Built on <a href="https://www.getspanforge.com/standard">RFC-0001 — the SpanForge AI Compliance Standard</a> for agentic AI systems.</em>
</p>

<p align="center">
  <img src="https://img.shields.io/badge/python-3.9%2B-4c8cbf?logo=python&logoColor=white" alt="Python 3.9+"/>
  <a href="https://pypi.org/project/spanforge/"><img src="https://img.shields.io/pypi/v/spanforge?color=4c8cbf&logo=pypi&logoColor=white" alt="PyPI"/></a>
  <a href="https://www.getspanforge.com/standard"><img src="https://img.shields.io/badge/standard-SpanForge_RFC--0001-4c8cbf" alt="spanforge RFC-0001"/></a>
  <img src="https://img.shields.io/badge/coverage-91%25-brightgreen" alt="91% test coverage"/>
  <img src="https://img.shields.io/badge/tests-6541%20passing-brightgreen" alt="6541 tests"/>
  <img src="https://img.shields.io/badge/version-1.0.1-4c8cbf" alt="Version 1.0.1"/>
  <img src="https://img.shields.io/badge/dependencies-zero-brightgreen" alt="Zero dependencies"/>
  <a href="docs/index.md"><img src="https://img.shields.io/badge/docs-local-4c8cbf" alt="Documentation"/></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/license-PolyForm%20NC%201.0-blue" alt="PolyForm Noncommercial 1.0"/></a>
  <img src="https://img.shields.io/badge/free%20for-personal%20%7C%20research%20%7C%20open--source-brightgreen" alt="Free for personal, research, and open-source use"/>
  <a href="https://getspanforge.com/pricing"><img src="https://img.shields.io/badge/commercial%20use-license%20required-orange" alt="Commercial use requires a license"/></a>
</p>

---

## The problem

You're building AI applications in a world where regulators are catching up fast. The EU AI Act is in force. GDPR applies to every LLM that touches personal data. SOC 2 auditors want evidence that your AI systems are governed. And your team is stitching together ad-hoc logs, hoping they'll hold up in an audit.

**spanforge** solves this. It is a **compliance-first platform** — not a monitoring add-on — that gives every AI action in your stack a cryptographically signed, privacy-safe, regulator-ready record.

---

## If you're a solo developer or early-stage startup

You might think compliance is a later problem — something to worry about when you have a legal team. Here's why it isn't:

- **You'll hit it sooner than you think.** The first B2B customer, the first SaaS sign-up from an EU user, the first healthcare or fintech pilot — they'll ask "how do you govern your AI?" If you have no answer, you lose the deal.
- **Retrofitting is expensive.** Adding audit trails, PII scrubbing, and signed evidence chains to an existing system takes weeks. Adding them with spanforge from day one takes minutes.
- **It's zero-cost to start.** The entire SDK is free for noncommercial use, zero dependencies, and works in-memory with no infrastructure. You don't pay anything until you need hosted storage.
- **It de-risks you personally.** GDPR fines apply to individuals running services, not just corporations. PII redaction and tamper-proof logs are your protection too.

In short: spanforge is the `logging` import you should have added on day one — except it also signs your audit trail and maps it to the regulations that will eventually matter to you.

```python
pip install spanforge  # free for noncommercial use, zero deps
```

```python
import spanforge
spanforge.configure()  # that's it — you're now compliant-by-default
```

---

## What spanforge does

<table>
<tr>
<td width="50%">

### Compliance & Regulatory Mapping
- Map telemetry to **EU AI Act**, **GDPR**, **SOC 2**, **HIPAA**, **ISO 42001**, **NIST AI RMF** clauses automatically
- Generate HMAC-signed **evidence packages** with gap analysis
- Track **consent boundaries**, **HITL oversight**, **model registry** governance, and **explainability** coverage
- Produce audit-ready attestations with model owner, risk tier, and status metadata
- **Compliance Evidence Chain (sf-cec)** — signed ZIP bundles with regulatory clause maps, DPA generation, and RFC 3161 timestamps for auditor hand-off; `spanforge audit cec generate` CLI generates CEC bundles without Python code
- **Human-in-the-Loop Workflow Engine (`spanforge.workflow`)** — approval workflows for gate reviews, policy sign-offs, and escalations; full state machine (PENDING → APPROVED / REJECTED → CLOSED) with SLA auto-escalation and role-based action matrix
- **Observability SDK (sf-observe)** — span export (OTLP/Datadog/Grafana/Splunk/Elastic), W3C TraceContext, OTel GenAI attrs, sampling strategies, annotation store, and health probes
- **CI/CD Gate Pipeline (sf-gate)** — evaluate release quality gates (schema, secrets, performance, PRRI, trust), YAML pipeline engine, artifact store, and blocking trust gate to prevent unsafe releases
- **T.R.U.S.T. Scorecard (sf-trust)** — five-pillar trust dimensions (Transparency · Reliability · UserTrust · Security · Traceability), configurable weights, SVG badge, history time-series, and 5 HallucCheck pipeline integrations (score, bias, monitor, risk, benchmark)
- **Enterprise Hardening (sf-enterprise)** — multi-tenancy with project-level isolation, data residency enforcement (EU/US/AP/IN), AES-256-GCM encryption at rest, envelope encryption via cloud KMS, mTLS, FIPS 140-2 mode, air-gap offline mode, and container health endpoints
- **Security Review (sf-security)** — OWASP API Security Top 10 audit, STRIDE threat modelling, dependency vulnerability scanning, static analysis, and secrets-in-logs detection

</td>
<td width="50%">

### Privacy & Audit Infrastructure- **Secrets scanning** — 20-pattern registry detects API keys, tokens, private keys; SARIF output; pre-commit hook- **PII redaction** — detect and strip sensitive data before it leaves your app. Includes a Presidio NLP backend (`spanforge[presidio]`) covering 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 verified at GA
- **HMAC audit chains** — tamper-evident, blockchain-style event signing- **Audit SDK (`sf-audit`)** — `sf_audit.append()`, schema key registry, T.R.U.S.T. scorecard, GDPR Article 30 RoPA, BYOS cloud routing- **GDPR subject erasure** — right-to-erasure with tombstone events that preserve chain integrity
- **Air-gapped deployment** — runs fully offline with zero egress

</td>
</tr>
<tr>
<td>

### Governance & Controls
- **Consent boundary monitoring** — `consent.granted`, `consent.revoked`, `consent.violation` events
- **Human-in-the-loop hooks** — `hitl.queued`, `hitl.reviewed`, `hitl.escalated`, `hitl.timeout` events
- **Model registry** — register, deprecate, retire models; attestations auto-warn on ungoverned models
- **Explainability tracking** — measure what % of AI decisions have explanations attached

</td>
<td>

### Developer Experience
- **Zero required dependencies** — pure Python 3.9+ stdlib
- **One-line setup** — `spanforge.configure()` and you're compliant
- **Integration config** — `.halluccheck.toml` config block, service registry, local fallbacks for all 11 services
- **T.R.U.S.T. Scorecard (sf-trust)** — five-pillar trust assessment (Transparency, Reliability, UserTrust, Security, Traceability), SVG badge generation, HallucCheck pipeline integrations
- **Mock library** — `spanforge.testing_mocks` — 11 drop-in mock service clients + `mock_all_services()` context manager for zero-network unit tests
- **Sandbox mode** — `[spanforge] sandbox = true` routes all service calls to local in-memory sandbox
- **`spanforge doctor`** — environment diagnostics: config valid, services reachable, patterns loaded, gate YAML valid
- **Auto-instrumentation** — patch OpenAI, Anthropic, LangChain, CrewAI, and more; `@trace_rag` decorator and automatic LlamaIndex/LangChain retriever instrumentation for zero-change RAG tracing
- **Async SDK** — every major SDK method now has a non-blocking `*_async()` variant (`scan_async`, `evaluate_async`, `build_bundle_async`, `get_scorecard_async`, `sso_delegate_session_async`) for seamless use in async frameworks
- **User feedback REST endpoint** — `POST /v1/feedback` accepts star/thumbs/Likert ratings and free-text comments (SHA-256 hashed); links to T.R.U.S.T. dimensions
- **38 CLI commands** — compliance checks, PII scans, secrets scanning, audit-chain verification, event generation, audit log extraction, CEC bundle generation, gap detection, gate policy audit, CI/CD gate pipelines, trust scorecards, config validation, enterprise health, security scanning, doctor diagnostics, all CI-ready

</td>
</tr>
</table>

---

## How it compares

spanforge is the only **open-standard, zero-dependency AI compliance platform**. Other tools are monitoring platforms that bolt on compliance as an afterthought. spanforge is compliance infrastructure that happens to capture the telemetry needed to prove it.

| Capability | **spanforge** | LangSmith | Langfuse | OpenLLMetry | Arize Phoenix |
|---|:---:|:---:|:---:|:---:|:---:|
| Regulatory framework mapping (EU AI Act, GDPR, SOC 2…) | ✅ | ❌ | ❌ | ❌ | ❌ |
| HMAC-signed evidence packages & attestations | ✅ | ❌ | ❌ | ❌ | ❌ |
| Consent boundary monitoring | ✅ | ❌ | ❌ | ❌ | ❌ |
| Human-in-the-loop compliance events | ✅ | ❌ | ❌ | ❌ | ❌ |
| Model registry with risk-tier governance | ✅ | ❌ | ❌ | ❌ | ❌ |
| Explainability coverage metrics | ✅ | ❌ | ❌ | ❌ | ❌ |
| Built-in PII redaction | ✅ | ❌ | ❌ | ❌ | ❌ |
| Tamper-proof audit chain | ✅ | ❌ | ❌ | ❌ | ❌ |
| GDPR subject erasure (right-to-erasure) | ✅ | ❌ | ❌ | ❌ | ❌ |
| Works fully offline / air-gapped | ✅ | ❌ | Self-host | Partial | Self-host |
| Open schema standard (RFC-driven) | ✅ | ❌ | ❌ | Partial | ❌ |
| Zero required dependencies | ✅ | ❌ | ❌ | ❌ | ❌ |
| OTLP export (any OTel backend) | ✅ | ❌ | ✅ | ✅ | ✅ |
| Source-available, no call-home | ✅ | Partial | ✅ | ✅ | ✅ |
| CI/CD release quality gates (schema, secrets, PRRI, trust gate) | ✅ | ❌ | ❌ | ❌ | ❌ |

> **Bottom line**: Others help you *watch* your AI. spanforge helps you *govern* it.

---

## Install

```bash
pip install spanforge
```

**Requires Python 3.9+.** Zero mandatory dependencies.

Documented CLI entrypoints, version consistency, and known stale doc patterns
are also checked in CI so public docs drift fails fast during PR validation.

### Optional extras

```bash
pip install "spanforge[openai]"       # OpenAI auto-instrumentation
pip install "spanforge[langchain]"    # LangChain callback handler
pip install "spanforge[crewai]"       # CrewAI callback handler
pip install "spanforge[http]"         # Webhook + OTLP export
pip install "spanforge[datadog]"      # Datadog APM + metrics
pip install "spanforge[kafka]"        # Kafka EventStream source
pip install "spanforge[pydantic]"     # Pydantic v2 model layer
pip install "spanforge[otel]"         # OpenTelemetry SDK integration
pip install "spanforge[jsonschema]"   # Strict JSON Schema validation
pip install "spanforge[llamaindex]"   # LlamaIndex event handler
pip install "spanforge[gemini]"       # Google Gemini auto-instrumentation
pip install "spanforge[bedrock]"      # AWS Bedrock Converse API
pip install "spanforge[presidio]"     # Presidio-powered PII detection
pip install "spanforge[all]"          # everything above
```

---

## Runtime Governance GA Surface

The GA implementation spine is the runtime-governance control plane:

- `sf_explain` for signed runtime explanations — now with `ExplainModelType` classification (LLM, RAG, MULTI_AGENT, CLASSIFIER, EMBEDDING), configurable retry, and fail-safe emit
- `sf_scope` for agent capability enforcement — now with circuit-breaker fail-secure mode and `ACTION_CATEGORIES` dictionary
- `sf_rbac` for role enforcement on sensitive actions — now with `STANDARD_ROLE_MATRIX` (10 canonical actor types), YAML manifest loading, and JWT claim extraction
- `sf_rag` for grounding evidence and thresholds
- `sf_lineage` for provenance capture
- `sf_policy` for policy activation, replay, simulation, and review
- `sf_operator` for trace inspection and signed operator exports
- `sf_enterprise` for deployment posture and enterprise evidence packaging

Start here if you want the end-to-end story instead of the full product surface:

- [docs/runtime-governance.md](docs/runtime-governance.md)
- [docs/runtime-governance-contracts.md](docs/runtime-governance-contracts.md)
- [docs/replay-simulation.md](docs/replay-simulation.md)
- [docs/evidence-export.md](docs/evidence-export.md)
- [docs/enterprise-integrations.md](docs/enterprise-integrations.md)
- [docs/competitor-comparison.md](docs/competitor-comparison.md)
- [docs/ga-release-notes.md](docs/ga-release-notes.md)
- [docs/demos/runtime-governance-demo.md](docs/demos/runtime-governance-demo.md)
- [docs/demos/enterprise-evidence-demo.md](docs/demos/enterprise-evidence-demo.md)

---

## Quick start — compliance in 5 minutes

### 1. Configure and instrument

```python
import spanforge

spanforge.configure(
    service_name="my-agent",
    signing_key="your-org-secret",      # HMAC audit chain — tamper-proof
    redaction_policy="gdpr",            # PII stripped before export
    exporter="jsonl",
    endpoint="audit.jsonl",
)
```

Every event your app emits is now **signed**, **PII-redacted**, and **stored** — with zero per-call boilerplate.

### 2. Trace AI decisions

```python
with spanforge.start_trace("loan-approval-agent") as trace:
    with trace.llm_call("gpt-4o", temperature=0.2) as span:
        decision = call_llm(prompt)
        span.set_token_usage(input=512, output=200, total=712)
        span.set_status("ok")
```

### 3. Generate compliance evidence

```python
from spanforge.core.compliance_mapping import ComplianceMappingEngine

engine = ComplianceMappingEngine()
package = engine.generate_evidence_package(
    model_id="gpt-4o",
    framework="eu_ai_act",
    from_date="2026-01-01",
    to_date="2026-03-31",
    audit_events=events,
)

print(package.attestation.coverage_pct)            # e.g. 87.5%
print(package.attestation.explanation_coverage_pct) # e.g. 75.0%
print(package.attestation.model_risk_tier)          # e.g. "high"
print(package.gap_report)                           # what's missing
```

Or from the CLI:

```bash
spanforge compliance generate \
  --model-id gpt-4o \
  --framework eu_ai_act \
  --from 2026-01-01 --to 2026-03-31 \
  --events-file audit.jsonl
```

### 4. Hand to your auditor

The evidence package contains:
- **Clause mappings** — which telemetry events satisfy which regulatory clauses
- **Gap analysis** — which clauses lack evidence and need attention
- **HMAC-signed attestation** — cryptographic proof the evidence hasn't been tampered with
- **Model governance metadata** — owner, risk tier, status, warnings for deprecated/retired models
- **Explanation coverage** — percentage of AI decisions with explainability records
### 5. Package for auditors with sf-cec (v2.0.4+)

Bundle your audit records into a regulator-ready, HMAC-signed ZIP:

```python
from spanforge.sdk import sf_cec

# Build a compliance evidence bundle for Q1 2026
result = sf_cec.build_bundle(
    project_id="my-agent",
    date_range=("2026-01-01", "2026-03-31"),
    frameworks=["eu_ai_act", "iso_42001", "soc2"],
)

print(result.bundle_id)       # sfcec_my-agent_20260401T000000Z_abc123
print(result.zip_path)        # /tmp/sfcec/halluccheck_cec_my-agent_2026-01-01_2026-03-31.zip
print(result.hmac_manifest)   # hmac-sha256:a3f9…
print(result.record_counts)   # {"halluccheck.score.v1": 214, "halluccheck.bias.v1": 87, …}

# Verify bundle integrity before sharing
verify = sf_cec.verify_bundle(result.zip_path)
assert verify.overall_valid

# Generate a GDPR Art. 28 Data Processing Agreement
dpa = sf_cec.generate_dpa(
    project_id="my-agent",
    controller_details={"name": "Acme Corp", "contact": "dpo@acme.com"},
    processor_details={"name": "ML Platform Team"},
)
print(dpa.document_id)  # sfcec-dpa-my-agent-20260401
```

The ZIP bundle contains:
- `manifest.json` — record inventory with HMAC-SHA256 signature
- `clause_map.json` — per-framework clause satisfaction (SATISFIED / PARTIAL / GAP)
- `chain_proof.json` — audit chain verification result
- `attestation.json` — HMAC-signed attestation metadata
- `rfc3161_timestamp.tsr` — trusted timestamp stub (RFC 3161)
- `score_records/`, `bias_reports/`, `prri_records/`, `drift_events/`, `pii_detections/`, `gate_evaluations/` — NDJSON evidence per schema key

### 6. Observe spans with sf-observe (v2.0.5+)

Export spans to any OTLP-compatible backend, emit structured annotations, and
trace LLM calls with OTel GenAI semantic conventions:

```python
from spanforge.sdk import sf_observe

# Emit a span for an LLM call — W3C traceparent + OTel GenAI attrs added automatically
span_id = sf_observe.emit_span(
    "chat.completion",
    {
        "gen_ai.system": "openai",
        "gen_ai.request.model": "gpt-4o",
        "gen_ai.usage.input_tokens": 512,
        "gen_ai.usage.output_tokens": 64,
    },
)
print(span_id)  # "a3f1b2c4d5e6f708"

# Mark a model deployment
annotation_id = sf_observe.add_annotation(
    "model_deployed",
    {"model": "gpt-4o", "environment": "production"},
    project_id="my-agent",
)

# Health probe
print(sf_observe.healthy)         # True
print(sf_observe.last_export_at)  # ISO-8601 or None

# Export to any OTLP endpoint per-call
from spanforge.sdk import ReceiverConfig
result = sf_observe.export_spans(
    my_spans,
    receiver_config=ReceiverConfig(
        endpoint="https://otel.collector.example.com/v1/traces",
        headers={"Authorization": "Bearer tok"},
    ),
)
print(result.exported_count, result.backend)
```

Select backend and sampler via environment:

```bash
export SPANFORGE_OBSERVE_BACKEND=otlp          # otlp | datadog | grafana | splunk | elastic | local
export SPANFORGE_OBSERVE_SAMPLER=trace_id_ratio
export SPANFORGE_OBSERVE_SAMPLE_RATE=0.25
```

---

### 7. Route alerts with sf-alert (v2.0.6+)

Publish topic-based alerts to Slack, PagerDuty, OpsGenie, Teams, SMS, and
custom webhooks — with built-in deduplication, escalation policy, and
maintenance-window suppression:

```python
from spanforge.sdk import sf_alert

# Publish a CRITICAL drift alert
result = sf_alert.publish(
    "halluccheck.drift.red",
    {"model": "gpt-4o", "drift_score": 0.91},
    severity="critical",
    project_id="my-agent",
)
print(result.alert_id)    # UUID4
print(result.suppressed)  # True if deduplicated / maintenance window

# Acknowledge to cancel the 15-minute escalation timer
sf_alert.acknowledge(result.alert_id)

# Register a custom topic
sf_alert.register_topic(
    "myapp.pipeline.failed",
    "ML pipeline execution failure",
    "high",
    runbook_url="https://runbooks.example.com/pipeline",
)
```

Configure sinks via environment variables (zero code required):

```bash
export SPANFORGE_ALERT_TEAMS_WEBHOOK=https://xxx.webhook.office.com/...
export SPANFORGE_ALERT_OPSGENIE_KEY=og-key-...
export SPANFORGE_ALERT_DEDUP_SECONDS=300
```

---

### 8. Enforce release gates with sf-gate (v2.0.7+)

Run YAML-declared quality gates before every release. Block on schema violations,
secrets leaks, performance regressions, unsafe PRRI scores, and trust failures
— all in a single pipeline command:

```python
from spanforge.sdk import sf_gate

# Run a full YAML gate pipeline — blocks on any FAIL gate
result = sf_gate.run_pipeline("gates/ci-pipeline.yaml")
for g in result.gate_results:
    print(f"[{g.verdict.value}] {g.gate_id}")  # e.g. [PASS] schema-validation

# Evaluate a single gate programmatically
verdict = sf_gate.evaluate("schema-validation", event.to_dict())
print(verdict.verdict)   # GateVerdict.PASS

# Standalone PRRI evaluation
prri = sf_gate.evaluate_prri(prri_score=28.5)
print(prri.verdict)      # PRRIVerdict.GREEN

# Composite trust gate — checks HRI rate, PII, and secrets windows
trust = sf_gate.get_status()
print(trust.healthy)     # True if all thresholds are within bounds
```

Or from CI directly:

```bash
# Runs the pipeline, exits 1 if any blocking gate fails
spanforge gate run gates/ci-pipeline.yaml

# Enforce the composite trust gate as a deployment prerequisite
spanforge gate trust-gate --project-id my-agent
```

A minimal `ci-pipeline.yaml`:

```yaml
version: "1.0"
gates:
  - id: schema-validation
    type: schema_validation
    on_fail: block
  - id: secrets-scan
    type: secrets_scan
    on_fail: block
  - id: prri-check
    type: halluccheck_prri
    params:
      red_threshold: 65
    on_fail: block
  - id: trust-gate
    type: halluccheck_trust
    on_fail: block
```

---

### 9. Unified config & local fallback (v2.0.8+)

Bootstrap all 8 services from a single `.halluccheck.toml` config block.
When a remote service is unreachable, the SDK automatically falls back to
a local-mode equivalent — no code changes required:

```toml
# .halluccheck.toml
[spanforge]
enabled    = true
project_id = "my-agent"
endpoint   = "https://api.spanforge.example.com"

[spanforge.services]
sf_pii     = true
sf_secrets = true
sf_audit   = true
sf_observe = true

[spanforge.local_fallback]
enabled     = true
max_retries = 3
timeout_ms  = 2000
```

```python
from spanforge.sdk import load_config_file, validate_config

# Parse, validate, and apply env-var overrides in one call
config = load_config_file()                # auto-discovers .halluccheck.toml
errors = validate_config(config)           # [] when valid
print(config.services.sf_pii)             # True
print(config.local_fallback.timeout_ms)   # 2000
```

Validate from the CLI:

```bash
spanforge config validate                          # auto-discover
spanforge config validate --file .halluccheck.toml # explicit path
```

When a service is down, fallback activates automatically:

```python
from spanforge.sdk import pii_fallback, secrets_fallback, audit_fallback

# Local regex PII scan (no remote service required)
result = pii_fallback("Contact alice@example.com")
print(result["entities"])  # [{"type": "EMAIL", ...}]

# Local secrets scan
result = secrets_fallback("AKIA1234567890ABCDEF")
print(result["clean"])     # False

# Local HMAC-chained JSONL audit
audit_fallback(
    {"score": 0.92, "model": "gpt-4o"},
    schema_key="halluccheck.score.v1",
)
```

The `ServiceRegistry` tracks health for all services and re-checks every 60 s:

```python
from spanforge.sdk import ServiceRegistry

reg = ServiceRegistry.get_instance()
status = reg.status_response()
# {"sf_pii": {"status": "up", "latency_ms": 45, "last_checked_at": "..."}, ...}
```

---

### 10. T.R.U.S.T. Scorecard & HallucCheck pipelines (v2.0.9+)

The T.R.U.S.T. scorecard aggregates five trust dimensions into a single weighted score with colour-band verdicts. Each pillar maps to existing audit telemetry:

| Pillar | What it measures | Source |
|--------|-----------------|--------|
| **T**ransparency | Gate pass rate | `sf_gate` evaluations |
| **R**eliability | Hallucination rate | `halluccheck.score.v1` records |
| **U**serTrust | Bias disparity | `halluccheck.bias.v1` records |
| **S**ecurity | PII + secrets hygiene | `sf_pii` / `sf_secrets` scans |
| **T**raceability | Compliance posture | Attestation coverage |

Colour bands: **green** ≥ 80, **amber** ≥ 60, **red** < 60.

```python
from spanforge.sdk import sf_trust

# Full scorecard with all five dimensions
scorecard = sf_trust.get_scorecard(project_id="my-agent")
print(scorecard.overall_score)   # 82.5
print(scorecard.colour_band)     # "green"
print(scorecard.reliability)     # TrustDimension(score=90.0, trend="up", ...)

# SVG badge for dashboards / README shields
badge = sf_trust.get_badge(project_id="my-agent")
with open("trust-badge.svg", "w") as f:
    f.write(badge.svg)

# Historical time-series (10 buckets)
history = sf_trust.get_history(project_id="my-agent", buckets=10)
for entry in history:
    print(entry.timestamp, entry.overall)
```

Five HallucCheck pipeline integrations orchestrate cross-service workflows:

```python
from spanforge.sdk.pipelines import (
    score_pipeline,
    bias_pipeline,
    monitor_pipeline,
    risk_pipeline,
    benchmark_pipeline,
)

# Score pipeline: PII scan → secrets scan → observe span → audit append
result = score_pipeline("The model output to check", model="gpt-4o")
print(result.audit_id, result.details)

# Risk pipeline: PRRI evaluation → alert if RED → gate block → CEC bundle
result = risk_pipeline(prri_score=75.0, project_id="my-agent")
print(result.details["verdict"])  # "RED"
```

From the CLI:

```bash
# T.R.U.S.T. scorecard (text table)
spanforge trust scorecard --project-id my-agent

# SVG badge to stdout
spanforge trust badge --project-id my-agent > trust.svg

# Composite trust gate (exit 1 = trust below threshold)
spanforge trust gate --project-id my-agent
```

---

### 11. Test with zero-network mocks (v2.0.11+)

Drop-in mock service clients for every SpanForge SDK service — no network,
no configuration, no side-effects:

```python
from spanforge.testing_mocks import mock_all_services

with mock_all_services():
    from spanforge.sdk import sf_pii, sf_audit, sf_gate

    # All calls are local, recorded, and return sensible defaults
    result = sf_pii.scan_text("Contact alice@example.com")
    assert result.clean  # mock returns clean=True by default

    sf_audit.append({"score": 0.92}, schema_key="halluccheck.score.v1")
    assert len(sf_audit.calls) == 1  # inspect recorded calls

    prri = sf_gate.evaluate_prri(prri_score=28.5)
    assert prri.allow  # GREEN by default
```

Override default returns per-method:

```python
from spanforge.testing_mocks import MockSFPII

mock = MockSFPII()
mock.configure_response("scan_text", {"clean": False, "entities": ["EMAIL"]})
result = mock.scan_text("test")
assert not result["clean"]
```

Run `spanforge doctor` for a full environment diagnostic:

```bash
spanforge doctor
# ✅ Config valid
# ✅ All 11 services reachable
# ✅ API key not expired
# ✅ PII/secrets patterns loaded
# ✅ Gate YAML valid
```

---

## Regulatory framework coverage

The `ComplianceMappingEngine` maps your telemetry events to specific regulatory clauses:

| Framework | Clause | Mapped events | What it proves |
|-----------|--------|---------------|----------------|
| **GDPR** | Art. 22 | `consent.*`, `hitl.*` | Automated decisions have consent + human oversight |
| **GDPR** | Art. 25 | `llm.redact.*`, `consent.*` | Privacy by design — PII handled before export |
| **EU AI Act** | Art. 13 | `explanation.*` | AI decisions are transparent and explainable |
| **EU AI Act** | Art. 14 | `hitl.*`, `consent.*` | Human oversight of high-risk AI |
| **EU AI Act** | Annex IV.5 | `llm.guard.*`, `llm.audit.*`, `hitl.*` | Technical documentation — safety + oversight |
| **SOC 2** | CC6.1 | `llm.audit.*`, `llm.trace.*`, `model_registry.*` | Logical access controls + model governance |
| **NIST AI RMF** | MAP 1.1 | `llm.trace.*`, `llm.eval.*`, `model_registry.*`, `explanation.*` | Risk identification and mapping |
| **HIPAA** | §164.312 | `llm.redact.*`, `llm.audit.*` | PHI access controls and audit |
| **ISO 42001** | A.5–A.10 | Full event set | AI management system controls |

---

## Compliance event types

spanforge defines purpose-built event types for AI governance — these aren't afterthought log messages, they are first-class compliance primitives:

| Category | Event types | Purpose |
|----------|------------|---------|
| **Consent** | `consent.granted`, `consent.revoked`, `consent.violation` | Track user consent for automated processing |
| **Human-in-the-Loop** | `hitl.queued`, `hitl.reviewed`, `hitl.escalated`, `hitl.timeout` | Prove human oversight of AI decisions |
| **Model Registry** | `model_registry.registered`, `model_registry.deprecated`, `model_registry.retired` | Govern model lifecycle and risk |
| **Explainability** | `explanation.generated` | Attach explanations to AI decisions |
| **Guardrails** | `llm.guard.*` | Safety classifier outputs and block decisions |
| **PII** | `llm.redact.*` | Audit trail of what PII was found and removed |
| **Audit** | `llm.audit.*` | Access logs and chain-of-custody records |
| **Traces** | `llm.trace.*` | Model calls, tokens, latency, cost |

---

## Core capabilities

### Tamper-proof audit chains

Every event is HMAC-SHA256 signed and chained to its predecessor — the same principle as certificate chains. Alter one event and the entire chain breaks.

```python
from spanforge.signing import AuditStream, verify_chain

stream = AuditStream(org_secret="your-secret")
for event in events:
    stream.append(event)

result = verify_chain(stream.events, org_secret="your-secret")
assert result.valid  # any tampering → False
```

### PII redaction

Strip personal data before events leave your application boundary. Deep scanning with Luhn and Verhoeff validation for credit cards and Aadhaar numbers, SSN range validation (`_is_valid_ssn`), calendar validation for dates of birth (`_is_valid_date`), and built-in patterns for `date_of_birth` and street `address`.

```python
from spanforge.redact import RedactionPolicy, Sensitivity

policy = RedactionPolicy(min_sensitivity=Sensitivity.PII, redacted_by="policy:gdpr-v1")
result = policy.apply(event)
# All PII fields → "[REDACTED by policy:gdpr-v1]"
```

### Model registry governance

Register models with ownership and risk metadata. Attestations automatically warn when models are deprecated, retired, or unregistered.

```python
from spanforge.model_registry import ModelRegistry

registry = ModelRegistry()
registry.register("gpt-4o", owner="ml-platform", risk_tier="high")
registry.deprecate("gpt-3.5-turbo", reason="Successor available")

# Evidence packages now include:
#   model_owner: "ml-platform"
#   model_risk_tier: "high"
#   model_status: "active"
#   model_warnings: []  (or ["model 'gpt-3.5-turbo' is deprecated"])
```

### Explainability tracking

Measure what percentage of your AI decisions have explanations attached:

```python
from spanforge.explain import generate_explanation

explanation = generate_explanation(
    decision_event_id="evt_01HX...",
    method="feature_importance",
    content="Top factors: credit_score (0.42), income (0.31)...",
)
# explanation_coverage_pct in attestations = explained / total decisions
```

### GDPR subject erasure

Right-to-erasure with tombstone events that preserve audit chain integrity:

```bash
spanforge audit erase audit.jsonl --subject-id user123
```

---

## Auto-instrumentation

Patch supported providers once — compliance data flows automatically:

```python
# Instrument all installed providers in one call
import spanforge.auto
spanforge.auto.setup()

# Or patch individually
from spanforge.integrations import openai as sf_openai
sf_openai.patch()    # every OpenAI call → signed, redacted, compliant
sf_openai.unpatch()  # restore original behaviour
```

**Supported providers:** OpenAI, Anthropic, Google Gemini, AWS Bedrock, Ollama, Groq, Together AI

**Supported frameworks:** LangChain, LlamaIndex, CrewAI

---

## Using SpanForge alongside OpenTelemetry

spanforge is not an OTel replacement. OTel handles performance monitoring. spanforge adds the compliance layer OTel cannot provide — audit chains, PII redaction, consent tracking, and regulator-ready attestations.

```python
# Your existing OTel pipeline stays untouched
from opentelemetry.sdk.trace import TracerProvider
provider = TracerProvider()

# Add spanforge's compliance layer alongside it
import spanforge
spanforge.configure(mode="otel_passthrough")

# Dual-stream: OTel for monitoring, spanforge for compliance
spanforge.configure(exporters=["otel_passthrough", "jsonl"], endpoint="audit.jsonl")
```

---

## Export

Ship compliance events to any backend:

```python
from spanforge.stream import EventStream
from spanforge.export.jsonl import JSONLExporter
from spanforge.export.otlp import OTLPExporter
from spanforge.export.datadog import DatadogExporter
from spanforge.export.grafana import GrafanaLokiExporter
from spanforge.export.cloud import CloudExporter
from spanforge.export.siem_splunk import SplunkHECExporter
from spanforge.export.siem_syslog import SyslogExporter

stream = EventStream(events)

await stream.drain(JSONLExporter("audit.jsonl"))                    # local file
await stream.drain(OTLPExporter("http://collector:4318/v1/traces")) # OTel collector
await stream.drain(DatadogExporter(service="my-app"))               # Datadog APM
await stream.drain(GrafanaLokiExporter(url="http://loki:3100"))     # Grafana Loki
await stream.drain(CloudExporter(api_key="sf_live_xxx"))            # spanforge Cloud
await stream.drain(SplunkHECExporter())                             # Splunk HEC (env-var config)
await stream.drain(SyslogExporter())                                # Syslog/CEF (env-var config)
```

Fan-out routing for compliance alerting:

```python
from spanforge.export.webhook import WebhookExporter

# Route guardrail violations to Slack
await stream.route(
    WebhookExporter("https://hooks.slack.com/your-webhook"),
    predicate=lambda e: e.event_type == "llm.guard.output.blocked",
)
```

---

## CLI

38 commands — all CI-pipeline ready:

```bash
# Compliance
spanforge compliance generate --model-id gpt-4o --framework eu_ai_act \
  --from 2026-01-01 --to 2026-03-31 --events-file events.jsonl
spanforge compliance check --framework eu_ai_act \
  --from 2026-01-01 --to 2026-03-31 --events-file events.jsonl
spanforge compliance validate-attestation evidence.json
spanforge compliance status --events-file events.jsonl   # compliance summary JSON

# Audit chain
spanforge audit-chain events.jsonl             # verify chain integrity
spanforge audit erase events.jsonl --subject-id user123  # GDPR erasure
spanforge audit rotate-key events.jsonl        # key rotation
spanforge audit verify --input events.jsonl    # verify integrity
spanforge audit extract events.jsonl --type llm.trace.span.completed --since 2026-01-01  # filter & extract
spanforge audit cec generate --project-id my-agent --sign  # CEC compliance bundle ZIP
spanforge audit gap-finder events.jsonl --threshold-minutes 30  # detect time gaps + missing fields

# Privacy & Secrets
spanforge scan events.jsonl --fail-on-match    # CI-gate PII scan
spanforge secrets scan <file>                  # scan file for secrets (exit 0=clean, 1=found)
spanforge secrets scan <file> --format sarif   # SARIF output for GitHub Code Scanning
spanforge secrets scan <file> --redact         # print redacted version to stdout

# Event generation
spanforge event create --type llm.trace.span.completed --count 10 --format jsonl  # generate test events

# Validation
spanforge check                                # 9-step end-to-end health check (--verbose for timing)
spanforge check-compat events.json             # v2.0 compatibility
spanforge validate events.jsonl                # JSON Schema validation
spanforge validate events.jsonl --report detailed --format json  # detailed report
spanforge validate --dataset training.jsonl                    # scan JSONL training data for PII
spanforge validate --dataset training.jsonl --fail-on-violations  # exit 1 if PII/schema issues found
spanforge validate --dataset training.jsonl --required-fields prompt,response --format json  # required fields + JSON output

# Configuration
spanforge config validate                      # validate .halluccheck.toml (auto-discover)
spanforge config validate --file path/to.toml  # validate specific config file

# Analysis
spanforge stats events.jsonl                   # counts, tokens, cost
spanforge stats events.jsonl --group-by model --format json  # grouped stats, JSON output
spanforge inspect <EVENT_ID> events.jsonl      # pretty-print one event
spanforge inspect <EVENT_ID> events.jsonl --format csv  # CSV export
spanforge cost events.jsonl                    # token spend report
spanforge cost run --run-id <id> --input events.jsonl  # per-run cost report

# Evaluation
spanforge eval save --input events.jsonl --output dataset.jsonl  # extract eval dataset
spanforge eval run --file dataset.jsonl --scorers faithfulness,pii_leakage  # run scorers

# Migration
spanforge migrate events.jsonl --sign          # v1→v2 migration
spanforge migrate-langsmith export.jsonl       # LangSmith → SpanForge conversion
spanforge list-deprecated                      # deprecated event types
spanforge migration-roadmap                    # v2 migration plan
spanforge check-consumers                      # consumer compatibility

# CI/CD Gate Pipeline
spanforge gate run gates/ci-pipeline.yaml               # run YAML gate pipeline (exit 1 = blocking gate failed)
spanforge gate run gates/ci-pipeline.yaml --format json  # JSON output for CI dashboards
spanforge gate evaluate schema-validation --payload event.json  # evaluate single gate
spanforge gate trust-gate --project-id my-agent         # composite trust gate check
spanforge gate audit events.jsonl --fail-on-violation   # policy audit of gate records (CI gate)

# T.R.U.S.T. Scorecard
spanforge trust scorecard --project-id my-agent         # five-pillar trust scorecard (text table)
spanforge trust badge --project-id my-agent             # SVG badge to stdout
spanforge trust gate --project-id my-agent              # composite trust gate (exit 1 = below threshold)

# Enterprise (Phase 11)
spanforge enterprise status                            # enterprise subsystem status JSON
spanforge enterprise health                            # enterprise health check (all services)

# Security (Phase 11)
spanforge security owasp                               # OWASP API Security Top 10 audit
spanforge security scan                                # full security scan (deps + static + secrets-in-logs)
spanforge security threat-model                        # STRIDE threat model summary
spanforge security audit-logs --path /var/log/myapp/   # secrets-in-logs detection

# Developer Experience (Phase 12)
spanforge doctor                                       # environment diagnostics (config, services, keys, patterns)

# Viewer
spanforge serve                                # local SPA trace viewer
spanforge ui                                   # standalone HTML viewer
```

---

## Event namespaces

Every event carries a typed ``payload``. The built-in namespaces:

| Prefix | Dataclass | What it records |
|---|---|---|
| `consent.*` | `ConsentPayload` | User consent grants, revocations, violations |
| `hitl.*` | `HITLPayload` | Human-in-the-loop review, escalation, timeout |
| `model_registry.*` | `ModelRegistryEntry` | Model registration, deprecation, retirement |
| `explanation.*` | `ExplainabilityRecord` | Explainability records for AI decisions |
| `llm.trace.*` | `SpanPayload` | Model calls — tokens, latency, cost **(frozen v2)** |
| `llm.guard.*` | `GuardPayload` | Safety classifier outputs, block decisions |
| `llm.redact.*` | `RedactPayload` | PII audit — what was found and removed |
| `llm.audit.*` | `AuditChainPayload` | Access logs and chain-of-custody |
| `llm.eval.*` | `EvalScenarioPayload` | Scores, labels, evaluator identity |
| `llm.cost.*` | `CostPayload` | Per-call cost in USD |
| `llm.cache.*` | `CachePayload` | Cache hit/miss, backend, TTL |
| `llm.prompt.*` | `PromptPayload` | Prompt template version, rendered text |
| `llm.fence.*` | `FencePayload` | Topic constraints, allow/block lists |
| `llm.diff.*` | `DiffPayload` | Prompt/response delta between events |
| `llm.template.*` | `TemplatePayload` | Template registry metadata |

---

## Architecture

```
spanforge/
+-- core/
│   +-- compliance_mapping.py  — ComplianceMappingEngine, evidence packages, attestations
+-- compliance/                — Programmatic compliance test suite
+-- signing.py                 — HMAC audit chains, key management, multi-tenant KeyResolver
+-- redact.py                  — PII detection + redaction policies
+-- model_registry.py          — Model lifecycle governance
+-- explain.py                 — Explainability records
+-- consent.py                 — Consent boundary events
+-- hitl.py                    — Human-in-the-loop events
+-- governance.py              — Policy-based event gating
+-- event.py                   — Event envelope
+-- types.py                   — EventType enum (consent.*, hitl.*, model_registry.*, explanation.*, llm.*)
+-- config.py                  — configure() / get_config()
+-- _span.py                   — Span, AgentRun, AgentStep context managers
+-- _trace.py                  — Trace + start_trace()
+-- _tracer.py                 — Top-level tracing entry point
+-- _stream.py                 — Internal dispatch: sample — redact — sign — export
+-- _store.py                  — TraceStore ring buffer
+-- _hooks.py                  — HookRegistry (lifecycle hooks)
+-- _server.py                 — HTTP server (/traces, /compliance/summary)
+-- _cli.py                    ← 38 CLI sub-commands
+-- workflow.py                — Human-in-the-Loop Workflow Engine (CORE-15); WorkflowEngine, WorkflowType, state machine, SLA escalation
+-- cost.py                    — CostTracker, BudgetMonitor, @budget_alert
+-- cache.py                   — SemanticCache, @cached decorator
+-- retry.py                   — @retry, FallbackChain, CircuitBreaker
+-- toolsmith.py               — @tool, ToolRegistry
+-- http.py                    — Zero-dependency OpenAI-compatible HTTP client
+-- io.py                      — JSONL read/write/append utilities
+-- plugins.py                 — Entry-point plugin discovery
+-- schema.py                  — Lightweight zero-dependency JSON Schema validator
+-- regression.py              — Pass/fail regression detector
+-- stats.py                   — Percentile, latency summary utilities
+-- presidio_backend.py        — Optional Presidio-powered PII detection
+-- _ansi.py                   — ANSI color helpers (NO_COLOR aware)
+-- lint/                      — AST-based instrumentation linter (AO000–AO005)
+-- export/                    — JSONL, OTLP, Webhook, Datadog, Grafana Loki, Cloud, Redis, Splunk HEC, Syslog/CEF
+-- integrations/              — OpenAI, Anthropic, Gemini, Bedrock, LangChain, LlamaIndex, CrewAI, Ollama, Groq, Together
+-- namespaces/                — Typed payload dataclasses
+-- gate.py                    — GateRunner YAML pipeline engine, 6 gate executors, artifact store (Phase 8)
+-- sdk/                       — Service SDK clients (sf-identity, sf-pii, sf-secrets, sf-audit, sf-cec, sf-observe, sf-alert, sf-gate, sf-trust, sf-enterprise, sf-security)
│   +-- explain.py             —   SFExplainClient – ExplainModelType enum (LLM/RAG/MULTI_AGENT/CLASSIFIER/EMBEDDING), signed explanations, retry+timeout emit (Phase 1B)
│   +-- scope.py               —   SFScopeClient – ACTION_CATEGORIES (5 categories), circuit-breaker fail-secure, resolve_action_category() (Phase 1B)
│   +-- rbac.py                —   SFRBACClient – STANDARD_ROLE_MATRIX (10 actor types), register_actor_from_yaml(), register_actor_from_jwt() (Phase 1C)
│   +-- identity.py            —   SFIdentityClient – keys, JWT, TOTP, MFA, magic-link
│   +-- pii.py                 —   SFPIIClient – scan, redact, anonymize
│   +-- secrets.py             —   SFSecretsClient – 20-pattern secret scanning, SARIF output
│   +-- audit.py               —   SFAuditClient – HMAC-chained records, T.R.U.S.T. scorecard, Article 30, BYOS
│   +-- cec.py                 —   SFCECClient – signed CEC ZIP bundles, clause mapping, DPA generation (Phase 5)
│   +-- observe.py             —   SFObserveClient – span export, OTel GenAI attrs, W3C TraceContext, sampling (Phase 6)
│   +-- alert.py               —   SFAlertClient – topic-based routing, dedup, escalation policy, 6 sink integrations (Phase 7)
│   +-- gate.py                —   SFGateClient – YAML pipeline runner, evaluate(), evaluate_prri(), trust-gate, artifact management (Phase 8)
│   +-- config.py              —   .halluccheck.toml parser, SFConfigBlock, SFServiceToggles, SFLocalFallbackConfig, validate_config() (Phase 9)
│   +-- registry.py            —   ServiceRegistry singleton, health checks, background checker, status_response() (Phase 9)
│   +-- fallback.py            —   8 local fallback implementations: pii, secrets, audit, observe, alert, identity, gate, cec (Phase 9)
│   +-- trust.py               —   SFTrustClient – T.R.U.S.T. five-pillar scorecard, SVG badge, history time-series, configurable weights (Phase 10)
│   +-- pipelines.py           —   5 HallucCheck pipeline integrations: score, bias, monitor, risk, benchmark (Phase 10)
│   +-- enterprise.py          —   SFEnterpriseClient – multi-tenancy, encryption, air-gap, health probes (Phase 11)
│   +-- security.py            —   SFSecurityClient – OWASP audit, STRIDE threat model, dependency/static scanning, secrets-in-logs (Phase 11)
│   +-- testing_mocks.py       —   11 mock service clients, _MockBase, mock_all_services() context manager (Phase 12)
│   +-- _base.py               —   SFClientConfig, SFServiceClient, circuit breaker, sandbox mode (Phase 12)
│   +-- _types.py              —   SecretStr, APIKeyBundle, JWTClaims, BundleResult, ClauseMapEntry, ExportResult, Annotation, AlertSeverity, …
│   +-- _exceptions.py         —   SFError hierarchy (incl. SFConfigError, SFConfigValidationError, SFStartupError, SFServiceUnavailableError, SFTrustComputeError, SFPipelineError)
│   +-- __init__.py            —   sf_identity / sf_pii / sf_secrets / sf_audit / sf_cec / sf_observe / sf_alert / sf_gate / sf_trust / sf_enterprise / sf_security / sf_rag / sf_feedback singletons + configure()
+-- migrate.py                 — Schema migration (v1 — v2), LangSmith migration
```

---

## What is inside the box

<table>
<thead>
<tr><th>Module</th><th>What it does</th><th>For whom</th></tr>
</thead>
<tbody>
<tr>
  <td><strong>Compliance & Governance</strong></td><td colspan="2"></td>
</tr>
<tr>
  <td><code>spanforge.compliance</code></td>
  <td><code>ComplianceMappingEngine</code> maps telemetry to regulatory frameworks (EU AI Act, ISO 42001, NIST AI RMF, GDPR, SOC 2, HIPAA). Generates evidence packages with HMAC-signed attestations. Consent, HITL, model registry, and explainability events integrated into clause mappings. Attestations include model owner, risk tier, status, warnings, and <code>explanation_coverage_pct</code>. Also: programmatic v2.0 compatibility checks — no pytest required.</td>
  <td>Compliance / legal / platform teams</td>
</tr>
<tr>
  <td><code>spanforge.signing</code></td>
  <td>HMAC-SHA256 event signing, tamper-evident audit chains, key strength validation, key expiry checks, environment-isolated key derivation, multi-tenant <code>KeyResolver</code> protocol, and <code>AsyncAuditStream</code></td>
  <td>Security / compliance teams</td>
</tr>
<tr>
  <td><code>spanforge.redact</code></td>
  <td>PII detection, sensitivity levels, redaction policies, deep <code>scan_payload()</code> with Luhn / Verhoeff / SSN-range / date-calendar validation, built-in <code>date_of_birth</code> and <code>address</code> patterns, and <code>contains_pii()</code> / <code>assert_redacted()</code> with raw string scanning</td>
  <td>Data privacy / GDPR teams</td>
</tr>
<tr>
  <td><code>spanforge.secrets</code></td>
  <td><code>SecretsScanner</code> — 20-pattern registry (7 spec-defined + 13 industry-standard), Shannon entropy scoring, three-tier confidence model, zero-tolerance auto-block for 10 high-risk types, <code>SecretsScanResult</code> with <code>to_dict()</code> and SARIF 2.1.0 output, span deduplication, configurable allowlist</td>
  <td>Security / DevSecOps teams</td>
</tr>
<tr>
  <td><code>spanforge.governance</code></td>
  <td>Policy-based event gating — block prohibited types, warn on deprecated usage, enforce custom rules</td>
  <td>Platform / compliance teams</td>
</tr>
<tr>
  <td><strong>Instrumentation & Tracing</strong></td><td colspan="2"></td>
</tr>
<tr>
  <td><code>spanforge.event</code></td>
  <td>The core <code>Event</code> envelope — the one structure all tools share</td>
  <td>Everyone</td>
</tr>
<tr>
  <td><code>spanforge.types</code></td>
  <td>All built-in event types — compliance events (<code>consent.*</code>, <code>hitl.*</code>, <code>model_registry.*</code>, <code>explanation.*</code>) and telemetry events (<code>llm.trace.*</code>, <code>llm.guard.*</code>, etc.)</td>
  <td>Everyone</td>
</tr>
<tr>
  <td><code>spanforge._span</code></td>
  <td>Span, AgentRun, AgentStep context managers. <code>contextvars</code>-based async/thread-safe propagation. <code>async with</code>, <code>span.add_event()</code>, <code>span.set_timeout_deadline()</code></td>
  <td>App developers</td>
</tr>
<tr>
  <td><code>spanforge._trace</code></td>
  <td><code>Trace</code> + <code>start_trace()</code> — high-level tracing entry point; accumulates child spans</td>
  <td>App developers</td>
</tr>
<tr>
  <td><code>spanforge.config</code></td>
  <td><code>configure()</code> and <code>get_config()</code> — signing key, redaction policy, exporters, sample rate</td>
  <td>Everyone</td>
</tr>
<tr>
  <td><strong>Export & Integration</strong></td><td colspan="2"></td>
</tr>
<tr>
  <td><code>spanforge.export</code></td>
  <td>Ship events to JSONL, HTTP webhooks, OTLP collectors, Datadog APM, Grafana Loki, Splunk HEC, Syslog/CEF, Redis, or spanforge Cloud</td>
  <td>Infra / compliance teams</td>
</tr>
<tr>
  <td><code>spanforge.export.siem_splunk</code></td>
  <td><code>SplunkHECExporter</code> — thread-safe batched Splunk HTTP Event Collector exporter; env-var config; HEC token never logged; <code>SplunkHECError</code> on delivery failure</td>
  <td>Security / compliance teams</td>
</tr>
<tr>
  <td><code>spanforge.export.siem_syslog</code></td>
  <td><code>SyslogExporter</code> — RFC 5424 and ArcSight CEF exporter over UDP or TCP; severity derived from event type; CEF extension values properly escaped; <code>SyslogExporterError</code> on socket failure</td>
  <td>Security / compliance teams</td>
</tr>
<tr>
  <td><code>spanforge.stream</code></td>
  <td>Fan-out router — one <code>drain()</code> call reaches multiple backends; Kafka source</td>
  <td>Platform engineers</td>
</tr>
<tr>
  <td><code>spanforge.integrations</code></td>
  <td>Auto-instrumentation for OpenAI, Anthropic, LangChain, LlamaIndex, CrewAI, Groq, Ollama, Together</td>
  <td>App developers</td>
</tr>
<tr>
  <td><code>spanforge.auto</code></td>
  <td><code>setup()</code> auto-patches all installed LLM integrations; <code>teardown()</code> cleanly unpatches</td>
  <td>App developers</td>
</tr>
<tr>
  <td><strong>Developer Tools</strong></td><td colspan="2"></td>
</tr>
<tr>
  <td><code>spanforge.cost</code></td>
  <td><code>CostTracker</code>, <code>BudgetMonitor</code>, <code>@budget_alert</code> — track and alert on token spend</td>
  <td>App developers / FinOps</td>
</tr>
<tr>
  <td><code>spanforge.cache</code></td>
  <td><code>SemanticCache</code> + <code>@cached</code> — deduplicate LLM calls via cosine similarity; <code>InMemoryBackend</code>, <code>SQLiteBackend</code>, <code>RedisBackend</code></td>
  <td>App developers / FinOps</td>
</tr>
<tr>
  <td><code>spanforge.retry</code></td>
  <td><code>@retry</code>, <code>FallbackChain</code>, <code>CircuitBreaker</code>, <code>CostAwareRouter</code> — resilient LLM routing with compliance events</td>
  <td>App developers / SREs</td>
</tr>
<tr>
  <td><code>spanforge.toolsmith</code></td>
  <td><code>@tool</code> + <code>ToolRegistry</code> — register functions as typed tools; render JSON schemas for function-calling APIs</td>
  <td>App developers</td>
</tr>
<tr>
  <td><code>spanforge.lint</code></td>
  <td>AST-based instrumentation linter; AO001–AO005 codes; flake8 plugin; CLI</td>
  <td>All teams / CI</td>
</tr>
<tr>
  <td><strong>Utilities (v2.0.2+)</strong></td><td colspan="2"></td>
</tr>
<tr>
  <td><code>spanforge.http</code></td>
  <td><code>chat_completion()</code> — zero-dependency, synchronous OpenAI-compatible HTTP client with retry and back-off</td>
  <td>App developers</td>
</tr>
<tr>
  <td><code>spanforge.io</code></td>
  <td><code>read_jsonl()</code>, <code>write_jsonl()</code>, <code>append_jsonl()</code>, <code>write_events()</code>, <code>read_events()</code> — JSONL I/O utilities</td>
  <td>Everyone</td>
</tr>
<tr>
  <td><code>spanforge.schema</code></td>
  <td>Lightweight zero-dependency JSON Schema validator — <code>validate()</code>, <code>validate_strict()</code></td>
  <td>Tool authors / CI</td>
</tr>
<tr>
  <td><code>spanforge.regression</code></td>
  <td><code>RegressionDetector</code> — per-case pass/fail regression detection between baseline and current eval runs</td>
  <td>ML / eval teams</td>
</tr>
<tr>
  <td><code>spanforge.stats</code></td>
  <td><code>percentile()</code>, <code>latency_summary()</code> — statistical utilities for eval and performance analysis</td>
  <td>Analytics engineers</td>
</tr>
<tr>
  <td><code>spanforge.plugins</code></td>
  <td><code>discover(group)</code> — entry-point plugin discovery across Python 3.9–3.12+</td>
  <td>Plugin authors</td>
</tr>
<tr>
  <td><code>spanforge.presidio_backend</code></td>
  <td>Optional Presidio-powered PII detection backend — <code>presidio_scan_payload()</code> with standard <code>PIIScanResult</code></td>
  <td>Data privacy teams</td>
</tr>
<tr>
  <td><code>spanforge.eval</code></td>
  <td>Built-in scorers: <code>FaithfulnessScorer</code>, <code>RefusalDetectionScorer</code>, <code>PIILeakageScorer</code>, <code>BehaviourScorer</code> base class</td>
  <td>ML / eval teams</td>
</tr>
<tr>
  <td><code>spanforge.debug</code></td>
  <td><code>print_tree()</code>, <code>summary()</code>, <code>visualize()</code> — terminal tree, stats dict, HTML Gantt timeline</td>
  <td>App developers</td>
</tr>
<tr>
  <td><code>spanforge.metrics</code></td>
  <td><code>aggregate()</code> — success rates, latency percentiles, token totals, cost breakdowns</td>
  <td>Analytics engineers</td>
</tr>
<tr>
  <td><code>spanforge.testing</code></td>
  <td><code>MockExporter</code>, <code>capture_events()</code>, <code>assert_event_schema_valid()</code>, <code>trace_store()</code></td>
  <td>Test authors</td>
</tr>
<tr>
  <td><code>spanforge.testing_mocks</code></td>
  <td>11 drop-in mock service clients (<code>MockSFIdentity</code>, <code>MockSFPII</code>, <code>MockSFSecrets</code>, <code>MockSFAudit</code>, <code>MockSFObserve</code>, <code>MockSFGate</code>, <code>MockSFCEC</code>, <code>MockSFAlert</code>, <code>MockSFTrust</code>, <code>MockSFEnterprise</code>, <code>MockSFSecurity</code>). <code>mock_all_services()</code> context manager patches all 11 singletons. <code>_MockBase</code> with <code>.calls</code> recording and <code>.configure_response()</code>. 100% test coverage. <em>(Phase 12, v2.0.11+)</em></td>
  <td>Test authors / all teams</td>
</tr>
<tr>
  <td><code>spanforge.validate</code></td>
  <td>JSON Schema validation against the published v2.0 schema</td>
  <td>All teams</td>
</tr>
<tr>
  <td><code>spanforge.namespaces</code></td>
  <td>Typed payload dataclasses for all built-in event namespaces</td>
  <td>Tool authors</td>
</tr>
<tr>
  <td><code>spanforge.models</code></td>
  <td>Optional Pydantic v2 models for validated schemas</td>
  <td>API / backend teams</td>
</tr>
<tr>
  <td><code>spanforge.consumer</code></td>
  <td>Declare schema-namespace dependencies; fail fast at startup if version requirements are not met</td>
  <td>Platform teams</td>
</tr>
<tr>
  <td><code>spanforge.deprecations</code></td>
  <td>Per-event-type deprecation notices at runtime</td>
  <td>Library maintainers</td>
</tr>
<tr>
  <td><code>spanforge._hooks</code></td>
  <td>Lifecycle hooks: <code>@hooks.on_llm_call</code>, <code>@hooks.on_tool_call</code>, <code>@hooks.on_agent_start</code> (sync + async)</td>
  <td>App developers / platform</td>
</tr>
<tr>
  <td><code>spanforge._store</code></td>
  <td><code>TraceStore</code> ring buffer — <code>get_trace()</code>, <code>list_tool_calls()</code>, <code>list_llm_calls()</code></td>
  <td>Platform / tooling engineers</td>
</tr>
<tr>
  <td><code>spanforge._cli</code></td>
  <td>CLI sub-commands including eval, compliance status, migrate-langsmith, cost run, and more</td>
  <td>DevOps / CI teams</td>
</tr>
<tr>
  <td><strong>Service SDK (v2.0.3+)</strong></td><td colspan="2"></td>
</tr>
<tr>
  <td><code>spanforge.sdk.identity</code></td>
  <td><code>SFIdentityClient</code> — API key lifecycle (<code>issue_api_key</code>, <code>rotate_api_key</code>, <code>revoke_api_key</code>), session JWT (HS256 stdlib / RS256 remote), magic-link issuance + single-use exchange, TOTP enrolment + verification (RFC 6238, 6-digit, 30 s), backup codes, per-key IP allowlist, sliding-window rate limiting, brute-force lockout. Fully local-mode capable — no external service required.</td>
  <td>Security / platform teams</td>
</tr>
<tr>
  <td><code>spanforge.sdk.pii</code></td>
  <td><code>SFPIIClient</code> — <code>scan_text()</code>, <code>anonymise()</code>, <code>scan_batch()</code>, <code>apply_pipeline_action()</code>, <code>get_status()</code>, <code>erase_subject()</code> (GDPR Art. 17), <code>export_subject_data()</code> (CCPA DSAR), <code>safe_harbor_deidentify()</code> (HIPAA 18-PHI), <code>audit_training_data()</code> (EU AI Act Art. 10), <code>get_pii_stats()</code>. PIPL patterns for Chinese national ID / mobile / bank card. Pipeline action routing (<code>flag</code> / <code>redact</code> / <code>block</code>) with confidence threshold gate. Scan results never include raw PII — only type labels, field paths, and SHA-256 hashes. Runs locally or delegates to a remote sf-pii service.</td>
  <td>Data privacy / GDPR teams</td>
</tr>
<tr>
  <td><code>spanforge.sdk.secrets</code></td>
  <td><code>SFSecretsClient</code> — <code>scan(text)</code> → <code>SecretsScanResult</code>, <code>scan_batch(texts)</code> with asyncio parallel execution. 20-pattern registry covering all spec-required types plus 13 industry-standard additions. Three-tier confidence model (0.75 / 0.90 / 0.97). Zero-tolerance auto-block for 10 high-risk secret types. SARIF 2.1.0 output. Runs fully locally — no external service required.</td>
  <td>Security / DevSecOps teams</td>
</tr>
<tr>
  <td><code>spanforge.sdk.audit</code></td>
  <td><code>SFAuditClient</code> — <code>append(record, schema_key)</code> with HMAC-SHA256 chaining, <code>query()</code> SQLite index with full-text and date-range filters, <code>verify_chain()</code> tamper detection, <code>get_trust_scorecard()</code> T.R.U.S.T. dimensions (hallucination · PII hygiene · secrets hygiene · gate pass-rate · compliance posture), <code>generate_article30_record()</code> GDPR Article 30 RoPA, <code>export()</code> JSONL/CSV/compressed, <code>sign()</code>, <code>get_status()</code>. BYOS routing via <code>SPANFORGE_AUDIT_BYOS_PROVIDER</code> (S3 / Azure / GCS / R2). Strict-schema mode, configurable retention years, optional SQLite persistence. 123 tests, 85 % coverage, mypy strict clean.</td>
  <td>Compliance / security / audit teams</td>
</tr>
<tr>
  <td><code>spanforge.sdk.observe</code></td>
  <td><code>SFObserveClient</code> — <code>emit_span(name, attributes)</code> builds OTel-compliant spans with W3C traceparent / baggage injection and OTel GenAI semantic attributes; <code>export_spans(spans, receiver_config=...)</code> routes to <code>local</code> / <code>otlp</code> / <code>datadog</code> / <code>grafana</code> / <code>splunk</code> / <code>elastic</code>; <code>add_annotation(event_type, payload)</code> / <code>get_annotations(event_type, from_dt, to_dt)</code> annotation store; <code>get_status()</code>, <code>healthy</code>, <code>last_export_at</code> health probes. Sampling via <code>SPANFORGE_OBSERVE_SAMPLER</code> (<code>always_on</code> / <code>always_off</code> / <code>parent_based</code> / <code>trace_id_ratio</code>). 139 tests, 97% coverage, mypy strict + bandit clean. <em>(Phase 6, v2.0.5+)</em></td>
  <td>Platform / MLOps / observability teams</td>
</tr>
<tr>
  <td><code>spanforge.sdk.alert</code></td>
  <td><code>SFAlertClient</code> — <code>publish(topic, payload, *, severity, project_id) → PublishResult</code> routes to all configured sinks with deduplication, rate-limiting, alert grouping, and maintenance-window suppression; <code>acknowledge(alert_id)</code> cancels CRITICAL escalation; <code>register_topic()</code> custom topic registry; <code>set_maintenance_window()</code> / <code>remove_maintenance_windows()</code>; <code>get_alert_history()</code> with filtering; <code>get_status()</code> / <code>healthy</code> health probes. Built-in sinks: <code>WebhookAlerter</code> (HMAC), <code>OpsGenieAlerter</code>, <code>VictorOpsAlerter</code>, <code>IncidentIOAlerter</code>, <code>SMSAlerter</code> (Twilio), <code>TeamsAdaptiveCardAlerter</code>. Auto-discovery from <code>SPANFORGE_ALERT_*</code> env vars. Per-sink circuit breakers. 95 tests, mypy strict + bandit clean. <em>(Phase 7, v2.0.6+)</em></td>
  <td>Platform / SRE / on-call teams</td>
</tr>
<tr>
  <td><code>spanforge.sdk.gate</code></td>
  <td><code>SFGateClient</code> — <code>evaluate(gate_id, payload) → GateEvaluationResult</code>, <code>evaluate_prri(prri_score) → PRRIResult</code>, <code>run_pipeline(gate_config_path) → GateRunResult</code>, <code>get_artifact(gate_id)</code>, <code>list_artifacts()</code>, <code>purge_artifacts(older_than_days)</code>, <code>get_status() → GateStatusInfo</code>, <code>configure(config)</code>. Six built-in gate executors: <code>schema_validation</code>, <code>dependency_security</code>, <code>secrets_scan</code>, <code>performance_regression</code>, <code>halluccheck_prri</code>, <code>halluccheck_trust</code>. PRRI three-tier verdict (<code>GREEN</code>/<code>AMBER</code>/<code>RED</code>), <code>GateArtifact</code> store with configurable retention, composite trust gate (HRI rate + PII window + secrets window), five exception types. 174 tests, mypy strict + bandit clean. <em>(Phase 8, v2.0.7+)</em></td>
  <td>DevOps / CI / platform teams</td>
</tr>
<tr>
  <td><code>spanforge.sdk.config</code></td>
  <td><code>load_config_file(path?)</code> — auto-discovers <code>.halluccheck.toml</code> or falls back to env-var defaults. <code>validate_config(block)</code> / <code>validate_config_strict(block)</code> schema validation. <code>SFConfigBlock</code>, <code>SFServiceToggles</code>, <code>SFLocalFallbackConfig</code>, <code>SFPIIConfig</code>, <code>SFSecretsConfig</code> typed dataclasses. Env-var overrides: <code>SPANFORGE_ENDPOINT</code>, <code>SPANFORGE_API_KEY</code>, <code>SPANFORGE_PROJECT_ID</code>, <code>SPANFORGE_PII_THRESHOLD</code>, <code>SPANFORGE_SECRETS_AUTO_BLOCK</code>, <code>SPANFORGE_LOCAL_TOKEN</code>, <code>SPANFORGE_FALLBACK_TIMEOUT_MS</code>. <em>(Phase 9, v2.0.8+)</em></td>
  <td>All teams / platform engineers</td>
</tr>
<tr>
  <td><code>spanforge.sdk.registry</code></td>
  <td><code>ServiceRegistry.get_instance()</code> — thread-safe singleton holding all 11 service clients. <code>run_startup_check()</code> pings all enabled services (status: up / degraded / down). <code>status_response()</code> returns per-service <code>{status, latency_ms, last_checked_at}</code>. <code>start_background_checker()</code> launches a daemon thread re-checking every 60 s. <code>ServiceHealth</code>, <code>ServiceStatus</code> typed enums. <em>(Phase 9, v2.0.8+)</em></td>
  <td>Platform / SRE teams</td>
</tr>
<tr>
  <td><code>spanforge.sdk.fallback</code></td>
  <td>8 local-mode fallback implementations: <code>pii_fallback()</code> (regex scan), <code>secrets_fallback()</code> (regex scan), <code>audit_fallback()</code> (HMAC-chained JSONL), <code>observe_fallback()</code> (OTLP JSON to stdout), <code>alert_fallback()</code> (log to stderr), <code>identity_fallback()</code> (trust local token), <code>gate_fallback()</code> (local gate engine), <code>cec_fallback()</code> (local JSONL). All emit WARNING when active. <em>(Phase 9, v2.0.8+)</em></td>
  <td>All teams (automatic)</td>
</tr>
<tr>
  <td><code>spanforge.sdk.trust</code></td>
  <td><code>SFTrustClient</code> — <code>get_scorecard(project_id, *, from_dt, to_dt, weights) → TrustScorecardResponse</code> aggregates five T.R.U.S.T. dimensions (Transparency · Reliability · UserTrust · Security · Traceability) with configurable weights. <code>get_badge(project_id) → TrustBadgeResult</code> generates an SVG badge with colour-band (green ≥ 80, amber ≥ 60, red &lt; 60). <code>get_history(project_id, *, buckets) → list[TrustHistoryEntry]</code> returns time-series snapshots. <code>get_status()</code> health probe. Reads from sf-audit trust records. 28 tests, mypy strict + bandit clean. <em>(Phase 10, v2.0.9+)</em></td>
  <td>Compliance / platform / ML teams</td>
</tr>
<tr>
  <td><code>spanforge.sdk.pipelines</code></td>
  <td>5 HallucCheck ↔ SpanForge pipeline integrations: <code>score_pipeline(text)</code> (PII → secrets → observe → audit), <code>bias_pipeline(report)</code> (PII → audit → alert → anonymise), <code>monitor_pipeline(event)</code> (observe → alert → OTel export), <code>risk_pipeline(prri_score)</code> (PRRI → alert → gate → CEC), <code>benchmark_pipeline(results)</code> (audit → alert → anonymise). Each returns <code>PipelineResult</code> with audit trail. <em>(Phase 10, v2.0.9+)</em></td>
  <td>ML / eval / platform teams</td>
</tr>
  <td><code>SFCECClient</code> — <code>build_bundle(project_id, date_range, frameworks)</code> assembles a signed ZIP with <code>manifest.json</code>, <code>clause_map.json</code>, <code>chain_proof.json</code>, <code>attestation.json</code>, <code>rfc3161_timestamp.tsr</code>, and 6 NDJSON evidence directories. HMAC-SHA256 manifest signing, BYOS detection. <code>verify_bundle(zip_path)</code> re-verifies HMAC + chain + timestamp. <code>generate_dpa(project_id, controller_details, processor_details)</code> produces a GDPR Article 28 Data Processing Agreement. <code>get_status()</code> returns bundle count, BYOS provider, and last bundle timestamp. Supports all 5 frameworks: <code>eu_ai_act</code>, <code>iso_42001</code>, <code>nist_ai_rmf</code>, <code>iso27001</code>, <code>soc2</code>. 148 tests, 87% coverage, mypy strict + bandit clean. <em>(Phase 5, v2.0.4+)</em></td>
  <td>Compliance / legal / audit teams</td>
</tr>
<tr>
  <td><code>spanforge.sdk</code></td>
  <td>Pre-built <code>sf_identity</code>, <code>sf_pii</code>, <code>sf_secrets</code>, <code>sf_audit</code>, <code>sf_cec</code>, <code>sf_observe</code>, <code>sf_alert</code>, <code>sf_gate</code>, <code>sf_trust</code>, <code>sf_enterprise</code>, <code>sf_security</code>, <code>sf_rag</code>, and <code>sf_feedback</code> singletons loaded from env vars on first import. <code>SFClientConfig</code>, <code>SecretStr</code>, full exception hierarchy (<code>SFAuthError</code>, <code>SFBruteForceLockedError</code>, <code>SFPIINotRedactedError</code>, <code>SFPIIBlockedError</code>, <code>SFPIIDPDPConsentMissingError</code>, <code>SFSecretsBlockedError</code>, <code>SFAuditSchemaError</code>, <code>SFAuditAppendError</code>, <code>SFAuditQueryError</code>, <code>SFCECError</code>, <code>SFCECBuildError</code>, <code>SFCECVerifyError</code>, <code>SFCECExportError</code>, <code>SFObserveError</code>, <code>SFObserveExportError</code>, <code>SFObserveEmitError</code>, <code>SFObserveAnnotationError</code>, <code>SFAlertError</code>, <code>SFAlertPublishError</code>, <code>SFAlertRateLimitedError</code>, <code>SFAlertQueueFullError</code>, <code>SFGateError</code>, <code>SFGateEvaluationError</code>, <code>SFGatePipelineError</code>, <code>SFGateTrustFailedError</code>, <code>SFGateSchemaError</code>, <code>SFConfigError</code>, <code>SFConfigValidationError</code>, <code>SFStartupError</code>, <code>SFServiceUnavailableError</code>, <code>SFTrustComputeError</code>, <code>SFPipelineError</code>, <code>SFEnterpriseError</code>, <code>SFIsolationError</code>, <code>SFDataResidencyError</code>, <code>SFEncryptionError</code>, <code>SFFIPSError</code>, <code>SFAirGapError</code>, <code>SFSecurityScanError</code>, <code>SFSecretsInLogsError</code>, …), and all value-object types exported from the top-level package. <code>load_config_file()</code>, <code>validate_config()</code>, <code>validate_config_strict()</code>, <code>ServiceRegistry</code>, and 8 fallback functions re-exported for convenience.</td>
  <td>All teams</td>
</tr>
</tbody>
</table>

---

## Quality

- **5 863 tests** passing (14 skipped) — unit, integration, property-based (Hypothesis), performance benchmarks
- **≥ 91% line and branch coverage** — 90% minimum enforced in CI
- **Zero required dependencies** — entire core runs on Python stdlib
- **Typed** — full `py.typed` marker; mypy + pyright clean
- **Frozen v2 trace schema** — `llm.trace.*` payload fields never break between minor releases
- **Async-safe** — `contextvars`-based context propagation across asyncio, threads, and executors

---

## Development

```bash
git clone https://github.com/veerarag1973/spanforge.git
cd spanforge
python -m venv .venv && .venv\Scripts\activate
pip install -e ".[dev]"
pytest                      # 5 351 tests
```

<details>
<summary><strong>Code quality</strong></summary>

```bash
ruff check . && ruff format .
mypy spanforge
pytest --cov                # >=90% required
```

</details>

<details>
<summary><strong>Build docs</strong></summary>

```bash
pip install -e ".[docs]"
cd docs && sphinx-build -b html . _build/html
```

</details>

---

## Versioning

spanforge implements **RFC-0001** (AI Compliance Standard for Agentic AI Systems). Current schema version: **2.0**.

This project follows [Semantic Versioning](https://semver.org/). The `llm.trace.*` namespace is additionally **frozen at v2** — even major releases won't remove fields from `SpanPayload`, `AgentRunPayload`, or `AgentStepPayload`.

See [docs/changelog.md](docs/changelog.md) for the full version history.

---

## Contributing

Contributions welcome — see the [Contributing Guide](docs/contributing.md). All new code must maintain ≥ 90% coverage. Run `ruff` and `mypy` before submitting.

---

## Community

- **[Discussions](https://github.com/veerarag1973/spanforge/discussions)** — questions, ideas, show-and-tell
- **[Issues](https://github.com/veerarag1973/spanforge/issues)** — bug reports and feature requests
- **[SECURITY.md](SECURITY.md)** — responsible disclosure process
- **[Code of Conduct](CODE_OF_CONDUCT.md)** — Contributor Covenant v2.1

> Topics: `ai-compliance` `ai-governance` `eu-ai-act` `gdpr` `soc2` `audit-trail` `pii-redaction` `hmac-signing` `llm-governance` `python`

---

## License

**[PolyForm Noncommercial License 1.0.0](LICENSE)**

- ✅ Free for personal use, research, education, open-source projects, and non-profit organisations.
- ❌ Commercial use (running as a paid service, internal business use, SaaS integration) requires a commercial license.

To obtain a commercial license: **sriram@getspanforge.com** | [getspanforge.com/pricing](https://getspanforge.com/pricing)

> Enterprise features (SSO, air-gapped deployment, dedicated support, SLAs) are available in **SpanForge Enterprise** — a separate commercial product.

---

<p align="center">
  Built for teams that take AI governance seriously.<br/>
  <a href="docs/index.md">Docs</a> —
  <a href="docs/runtime-governance.md">Runtime Governance</a> —
  <a href="docs/quickstart.md">Quickstart</a> —
  <a href="docs/api/index.md">API Reference</a> —
  <a href="https://github.com/veerarag1973/spanforge/discussions">Discussions</a> —
  <a href="https://github.com/veerarag1973/spanforge/issues">Report a bug</a>
</p>
