spanforge 1.0.3__tar.gz → 1.0.4__tar.gz

{spanforge-1.0.3 → spanforge-1.0.4}/.sf-gate/artifacts/gate6_trust_result.json

@@ -8,7 +8,7 @@
   "secrets_detected": false,
   "secrets_detections_24h": 0,
   "failures": [],
-  "timestamp": "2026-05-10T04:04:09.036213+00:00",
-  "pipeline_id": "d306e1c3-c437-4317-9c71-6532e5cac4a4",
+  "timestamp": "2026-05-19T01:26:18.801481+00:00",
+  "pipeline_id": "4f0fecb2-3f5b-47d8-91d9-af4732add7d7",
   "project_id": ""
 }

{spanforge-1.0.3 → spanforge-1.0.4}/.sf-gate/artifacts/test-gate_result.json

@@ -4,8 +4,8 @@
   "metrics": {
     "score": 0.95
   },
-  "timestamp": "2026-05-10T04:03:48.163107+00:00",
+  "timestamp": "2026-05-19T01:25:42.885005+00:00",
   "duration_ms": 0,
   "project_id": "",
-  "pipeline_id": "91e805b8-09a4-498e-bdde-f3b64e272e54"
+  "pipeline_id": "9aa2ff1b-3ba1-4e3c-828e-521a8e28db2f"
 }

{spanforge-1.0.3 → spanforge-1.0.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: spanforge
-Version: 1.0.3
+Version: 1.0.4
 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
@@ -118,8 +118,8 @@ Description-Content-Type: text/markdown
   <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-7049%20passing-brightgreen" alt="7049 tests"/>
-  <img src="https://img.shields.io/badge/version-1.0.2-4c8cbf" alt="Version 1.0.2"/>
+  <img src="https://img.shields.io/badge/tests-7095%20passing-brightgreen" alt="7095 tests"/>
+  <img src="https://img.shields.io/badge/version-1.0.4-4c8cbf" alt="Version 1.0.4"/>
   <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-MIT-blue" alt="MIT License"/></a>

{spanforge-1.0.3 → spanforge-1.0.4}/README.md

@@ -14,8 +14,8 @@
   <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-7049%20passing-brightgreen" alt="7049 tests"/>
-  <img src="https://img.shields.io/badge/version-1.0.2-4c8cbf" alt="Version 1.0.2"/>
+  <img src="https://img.shields.io/badge/tests-7095%20passing-brightgreen" alt="7095 tests"/>
+  <img src="https://img.shields.io/badge/version-1.0.4-4c8cbf" alt="Version 1.0.4"/>
   <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-MIT-blue" alt="MIT License"/></a>

{spanforge-1.0.3 → spanforge-1.0.4}/RELEASE.md

@@ -1,6 +1,6 @@
 # spanforge SDK — Release Runbook
 # PyPI distribution: spanforge  |  Import: spanforge
-# Latest: 1.0.2 — see docs/changelog.md for version history
+# Latest: 1.0.4 — see docs/changelog.md for version history
 # This file documents the general release process (originally written for 1.0.0).
 #
 # STATUS: READY TO PUBLISH

{spanforge-1.0.3 → spanforge-1.0.4}/artifacts/g1_result.json

@@ -4,8 +4,8 @@
   "metrics": {
     "score": 0.8
   },
-  "timestamp": "2026-05-10T04:03:56.547201+00:00",
+  "timestamp": "2026-05-19T01:26:04.752717+00:00",
   "duration_ms": 0,
   "project_id": "",
-  "pipeline_id": "8d45499c-d333-4145-a102-f3d83feb2cd5"
+  "pipeline_id": "d422f0ad-be37-4ced-8502-8b74b493439e"
 }

{spanforge-1.0.3 → spanforge-1.0.4}/artifacts/gate5_governance_result.json

@@ -5,7 +5,7 @@
   "dimension_breakdown": {},
   "framework": "",
   "policy_file": "",
-  "timestamp": "2026-05-10T04:03:56.555914+00:00",
+  "timestamp": "2026-05-19T01:26:04.760889+00:00",
   "allow": false,
   "project_id": "proj-1"
 }

{spanforge-1.0.3 → spanforge-1.0.4}/artifacts/gate6_trust_result.json

@@ -8,7 +8,7 @@
   "secrets_detected": false,
   "secrets_detections_24h": 0,
   "failures": [],
-  "timestamp": "2026-05-10T04:03:56.559324+00:00",
-  "pipeline_id": "fe4641af-3a35-4c4c-a874-4fe4f5ca8f4a",
+  "timestamp": "2026-05-19T01:26:04.764375+00:00",
+  "pipeline_id": "4d484d6e-c4d8-4c58-9b14-0deb40c5fd53",
   "project_id": "proj-1"
 }

{spanforge-1.0.3 → spanforge-1.0.4}/docs/changelog.md

@@ -6,7 +6,104 @@ this project adheres to [Semantic Versioning](https://semver.org/).
 
 ---
 
-## [Unreleased]
+## 1.0.4 — 2026-05-19
+
+**SDK Developer-Experience Enhancements (10 features) · Code Quality · Bug Fix**
+
+### Added
+
+- **`SFClientFactory`** (`spanforge.sdk._factory`) — single factory that vends all 8 SpanForge
+  clients (`pii`, `secrets`, `audit`, `cec`, `gate`, `observe`, `alert`, `identity`) from one
+  `SFClientConfig`. Lazy `@property` instantiation with `from_env()` classmethod. Eliminates
+  repetitive per-client boilerplate in application setup.
+
+- **`SFPipeline`** (`spanforge.sdk._pipeline_builder`) — composable middleware builder.
+  Chain any callable or SpanForge client (resolved via `scan` / `check` / `evaluate` / `emit` /
+  `append` / `publish` entry-point lookup) using `.add_stage()`. `.run(payload)` returns an
+  `SFPipelineResult` dataclass with `success`, `payload`, `errors`, `outputs`, `elapsed_ms`.
+  Supports `fail_fast=True` mode. Exported as `SFPipeline`, `SFPipelineResult`,
+  `PipelineStageError` from `spanforge.sdk`.
+
+- **`SFCompositeAuditSink`** (`spanforge.sdk.audit`) — fan-out audit sink that writes to an
+  in-memory `AuditStream` and a remote `SFAuditClient` simultaneously. In-memory write is always
+  attempted; remote write failure is suppressed when `fail_silent=True` (default), returning a
+  synthetic `AuditAppendResult(backend="local")`. Raises on failure when `fail_silent=False`.
+  Exported from `spanforge.sdk`.
+
+- **`spanforge.schemas` constants module** — 12 canonical schema key string constants:
+  `TRACE_V1`, `PII_V1`, `SECRETS_V1`, `AUDIT_V1`, `CONSENT_V1`, `SCORE_V1`, `BIAS_V1`,
+  `PRRI_V1`, `DRIFT_V1`, `GATE_V1`, `TRUST_V1`, `ALERT_V1`. Eliminates typos and enables IDE
+  auto-complete everywhere a `schema_key` argument is accepted.
+
+- **`spanforge.testing` mock factories** — 8 zero-argument factory functions: `fake_pii_client`,
+  `fake_secrets_client`, `fake_audit_client`, `fake_cec_client`, `fake_gate_client`,
+  `fake_observe_client`, `fake_alert_client`, `fake_identity_client`. Each returns a
+  pre-configured mock client ready for use in unit tests without network or credentials.
+  All exported from `spanforge.testing.__all__`.
+
+- **`SFCECClient.export_local(path, *, project_id="")`** (`spanforge.sdk.cec`) — exports the
+  in-memory compliance evidence chain to a local NDJSON file. Output includes one JSON record per
+  evidence item plus a HMAC-signed manifest line (`schema: spanforge.cec.local.v1`). Accepts
+  `str` or `pathlib.Path`; creates parent directories automatically. Returns `ExportResult`.
+  Raises `SFCECExportError` on `OSError`.
+
+- **`PIIEntity.entity_type` property** (`spanforge.sdk._types`) — backward-compatible alias for
+  `PIIEntity.type`. Enables code that uses the more descriptive `.entity_type` attribute name
+  without breaking any existing `.type` usage.
+
+- **TSC-criterion labels on exceptions** — `SFError.__init__` gains an optional
+  `tsc_criterion: str` keyword; the value is stored as `SFError.tsc_criterion`. Four subclasses
+  set SOC 2 TSC defaults: `SFPIIBlockedError` → `"CC6.6"`, `SFSecretsBlockedError` → `"CC6.7"`,
+  `SFGateEvaluationError` → `"CC7.2"`, `SFGateTrustFailedError` → `"CC7.4"`. Lets exception
+  handlers route directly to the relevant compliance criterion.
+
+- **`BehaviouralBaseline.fit(observations, *, window_seconds=86400.0)`** (`spanforge.baseline`)
+  — fits a `BehaviouralBaseline` instance in-place from an iterable of raw observation dicts.
+  Each dict may contain any combination of `token_count`, `latency_ms`, `operation`,
+  `confidence_score`, `decision_type`, `tool_name` keys. Updates `tokens`, `latency_by_operation`,
+  `confidence_by_type`, `tool_rate_per_hour`, `decision_rate_per_hour`, `event_count`,
+  `window_seconds`, and `recorded_at`. Accepts generators (consumed once).
+
+- **`py.typed` PEP 561 marker** — `src/spanforge/py.typed` confirmed present; the package is
+  fully typed and recognized by mypy, pyright, and other type checkers with no extra configuration.
+
+### Fixed
+
+- **`fake_gate_client()` bug** — `GateEvaluationResult` was constructed with non-existent fields
+  (`score`, `details`, `artifacts`). Corrected to the actual signature (`metrics`, `artifact_url`,
+  `duration_ms: int`). The function now works correctly in tests.
+
+### Tests
+
+- **`tests/test_next_sdk_features.py`** — 66 new targeted tests covering all 10 SDK features
+  across 9 test classes (`TestSchemaConstants`, `TestSFClientFactory`, `TestSFPipeline`,
+  `TestSFCompositeAuditSink`, `TestExportLocal`, `TestPIIEntityAlias`, `TestTSCExceptions`,
+  `TestBehaviouralBaselineFit`, `TestTestingFactories`).
+- **Total:** 7095 passing, 8 skipped · **Coverage:** 91.32% (threshold: 90% ✅)
+
+### Code Quality
+
+- `ruff check` — zero violations across all new and modified source files.
+- `mypy` — zero type errors across all new and modified source files.
+- `bandit` — zero security issues (4 485 lines scanned).
+
+---
+
+## 1.0.3 — 2026-05-10 [Released on PyPI](https://pypi.org/project/spanforge/1.0.3/)
+
+**License change to MIT + version bump**
+
+- **Version bumped** from `1.0.2` → `1.0.3` in `pyproject.toml`.
+- **License changed** from PolyForm Noncommercial 1.0.0 to the **MIT License** — spanforge is now free for all use, including commercial.
+- Updated `LICENSE` file with full MIT text.
+- Updated `pyproject.toml` classifier to `License :: OSI Approved :: MIT License`.
+- Updated all license references across: `README.md`, `PRICING.md`, `FOUNDER_PREP_GUIDE.md`, `docs/contributing.md`, `docs/rfc/rfc-0001.md`, `docs/changelog.md`, `docs/index.md`, `docs/installation.md`, `RELEASE.md`.
+- No functional code changes — metadata and documentation only.
+- **Tests:** 7049 passing, 7 skipped · **Coverage:** 91%
+
+---
+
+## 1.0.2 — 2026-05-10 [Released on PyPI](https://pypi.org/project/spanforge/1.0.2/)
 
 ### Added — Integration & Exporter Finalization (CARD 1E-1 · GROUP 1E · 2026-05-10)
 
@@ -2226,17 +2323,9 @@ backward-compatible unless noted; no existing public API was removed.
 
 ---
 
-## 1.0.3 — 2026-03-05
+## 1.0.2 — 2026-05-10 [Released on PyPI](https://pypi.org/project/spanforge/1.0.2/)
 
-**Version bump**
-
-- Updated version references in `docs/index.md` and `docs/changelog.md` to match `pyproject.toml`.
-
----
-
-## 1.0.2 — 2026-03-04
-
-**Packaging fix**
+**Integration & exporter finalization + config/secrets CLI (CARD 1E-1, CARD 1D-1)**
 
 - Added PyPI badge (links to `https://pypi.org/project/spanforge/`) to README, docs index, and installation page.
 - Fixed remaining relative spanforge Standard link in `docs/index.md`.

{spanforge-1.0.3 → spanforge-1.0.4}/docs/index.md

@@ -1,7 +1,7 @@
 # Documentation Index
 
 > **spanforge** (`spanforge`) — The reference implementation of the [spanforge Standard](https://www.getspanforge.com/standard) (RFC-0001), the open event-schema standard for compliance and governance of agentic AI systems.  
-> Current release: **1.0.2** — [Changelog](changelog.md) · [![PyPI](https://img.shields.io/pypi/v/spanforge?color=4c8cbf&logo=pypi&logoColor=white)](https://pypi.org/project/spanforge/)
+> Current release: **1.0.4** — [Changelog](changelog.md) · [![PyPI](https://img.shields.io/pypi/v/spanforge?color=4c8cbf&logo=pypi&logoColor=white)](https://pypi.org/project/spanforge/)
 
 This index links to every documentation page in this folder.
 

{spanforge-1.0.3 → spanforge-1.0.4}/docs/installation.md

@@ -69,7 +69,7 @@ all optional extras.
 
 ```python
 import spanforge  # pip install spanforge  →  import spanforge
-print(spanforge.__version__)   # 1.0.2
+print(spanforge.__version__)   # 1.0.3
 print(spanforge.SCHEMA_VERSION)  # 2.0
 
 from spanforge import Event, EventType

{spanforge-1.0.3 → spanforge-1.0.4}/pyproject.toml

@@ -7,7 +7,7 @@ build-backend = "hatchling.build"
 # ---------------------------------------------------------------------------
 [project]
 name = "spanforge"
-version = "1.0.3"
+version = "1.0.4"
 description = "SpanForge — AI lifecycle and governance platform (RFC-0001 SPANFORGE)"
 readme = "README.md"
 license = { text = "MIT" }

{spanforge-1.0.3 → spanforge-1.0.4}/src/spanforge/baseline.py

@@ -333,3 +333,90 @@ class BehaviouralBaseline:
     def load(cls, path: str | pathlib.Path) -> BehaviouralBaseline:
         """Load a baseline previously saved with :meth:`save`."""
         return cls.from_json(pathlib.Path(path).read_text(encoding="utf-8"))
+
+    def fit(
+        self,
+        observations: Iterable[dict[str, Any]],
+        *,
+        window_seconds: float = 86400.0,
+    ) -> None:
+        """Fit the baseline from raw observation dicts, mutating this instance.
+
+        An alternative to :meth:`from_events` for callers that already have
+        pre-aggregated or synthetic observations rather than full
+        :class:`~spanforge.event.Event` objects.
+
+        Each dict in *observations* may contain any combination of:
+
+        - ``token_count`` (int | float): total tokens for an LLM call
+        - ``latency_ms`` (float): operation latency in milliseconds
+        - ``operation`` (str): operation name for latency grouping (default ``"default"``)
+        - ``confidence_score`` (float): model confidence in ``[0.0, 1.0]``
+        - ``decision_type`` (str): decision category for confidence grouping
+        - ``tool_name`` (str): tool name; increments per-tool invocation rate
+
+        Keys that are absent or ``None`` are silently skipped.
+
+        Args:
+            observations:   Iterable of observation dicts (consumed once).
+            window_seconds: Traffic window used as the rate denominator
+                            (default 86 400 s = 24 h).
+
+        Example::
+
+            baseline = BehaviouralBaseline.load("baseline.json")
+            baseline.fit(
+                [
+                    {"token_count": 512, "latency_ms": 230.0, "operation": "chat"},
+                    {"confidence_score": 0.91, "decision_type": "accept"},
+                    {"tool_name": "web_search"},
+                ],
+                window_seconds=3600.0,
+            )
+            baseline.save("baseline.json")
+        """
+        token_samples: list[float] = []
+        confidence_samples: dict[str, list[float]] = {}
+        latency_samples: dict[str, list[float]] = {}
+        tool_counts: dict[str, int] = {}
+        decision_counts: dict[str, int] = {}
+        count = 0
+
+        for obs in observations:
+            count += 1
+            tc = obs.get("token_count")
+            if tc is not None:
+                token_samples.append(float(tc))
+
+            lat = obs.get("latency_ms")
+            if lat is not None:
+                op = str(obs.get("operation", "default"))
+                latency_samples.setdefault(op, []).append(float(lat))
+
+            cs = obs.get("confidence_score")
+            if cs is not None:
+                dt = str(obs.get("decision_type", "default"))
+                confidence_samples.setdefault(dt, []).append(float(cs))
+
+            tn = obs.get("tool_name")
+            if tn is not None:
+                tool_counts[str(tn)] = tool_counts.get(str(tn), 0) + 1
+
+            if obs.get("decision_type") is not None:
+                dt = str(obs["decision_type"])
+                decision_counts[dt] = decision_counts.get(dt, 0) + 1
+
+        hours = (window_seconds / 3600.0) if window_seconds > 0 else 1.0
+
+        self.tokens = DistributionStats.from_samples(token_samples)
+        self.confidence_by_type = {
+            k: DistributionStats.from_samples(v) for k, v in confidence_samples.items()
+        }
+        self.latency_by_operation = {
+            k: DistributionStats.from_samples(v) for k, v in latency_samples.items()
+        }
+        self.tool_rate_per_hour = {k: v / hours for k, v in tool_counts.items()}
+        self.decision_rate_per_hour = {k: v / hours for k, v in decision_counts.items()}
+        self.event_count = count
+        self.window_seconds = window_seconds
+        self.recorded_at = datetime.datetime.now(datetime.timezone.utc).isoformat()

spanforge-1.0.4/src/spanforge/schemas/__init__.py

@@ -0,0 +1,96 @@
+"""spanforge.schemas — Canonical schema key constants (DX-008).
+
+Use these string constants everywhere you pass a ``schema_key`` argument
+to :meth:`~spanforge.sdk.audit.SFAuditClient.append`,
+:meth:`~spanforge.sdk.cec.SFCECClient.build_bundle`, or any other
+SpanForge API that accepts a schema key.  They eliminate typos, enable
+IDE auto-complete, and ensure your code stays in sync with schema
+versioning changes.
+
+Usage::
+
+    from spanforge.schemas import TRACE_V1, AUDIT_V1, PII_V1
+
+    sf_audit.append(record, schema_key=AUDIT_V1)
+"""
+
+from __future__ import annotations
+
+__all__ = [
+    "ALERT_V1",
+    "AUDIT_V1",
+    "BIAS_V1",
+    "CONSENT_V1",
+    "DRIFT_V1",
+    "GATE_V1",
+    "PII_V1",
+    "PRRI_V1",
+    "SCORE_V1",
+    "SECRETS_V1",
+    "TRACE_V1",
+    "TRUST_V1",
+]
+
+# ---------------------------------------------------------------------------
+# Core trace / telemetry
+# ---------------------------------------------------------------------------
+
+#: Schema key for OpenTelemetry-compatible LLM trace spans.
+TRACE_V1: str = "spanforge.trace.v1"
+
+# ---------------------------------------------------------------------------
+# PII & secrets
+# ---------------------------------------------------------------------------
+
+#: Schema key for Presidio-backed PII scan and redaction records.
+PII_V1: str = "spanforge.pii.v1"
+
+#: Schema key for sf-secrets scanning records.
+SECRETS_V1: str = "spanforge.secrets.v1"
+
+# ---------------------------------------------------------------------------
+# Audit chain
+# ---------------------------------------------------------------------------
+
+#: Schema key for general-purpose audit records written by sf-audit.
+AUDIT_V1: str = "spanforge.audit.v1"
+
+#: Schema key for DPDP / GDPR consent records (subject + purpose pairs).
+CONSENT_V1: str = "spanforge.consent.v1"
+
+# ---------------------------------------------------------------------------
+# Compliance Evidence Chain (HallucCheck scoring artefacts)
+# ---------------------------------------------------------------------------
+
+#: Schema key for HallucCheck hallucination-score evidence records.
+SCORE_V1: str = "halluccheck.score.v1"
+
+#: Schema key for HallucCheck bias-scan evidence records.
+BIAS_V1: str = "halluccheck.bias.v1"
+
+#: Schema key for PRRI (Protected & Restricted Representation Index) records.
+PRRI_V1: str = "halluccheck.prri.v1"
+
+#: Schema key for behavioural-drift detection event records.
+DRIFT_V1: str = "halluccheck.drift.v1"
+
+# ---------------------------------------------------------------------------
+# Gate
+# ---------------------------------------------------------------------------
+
+#: Schema key for CI/CD gate evaluation result records.
+GATE_V1: str = "halluccheck.gate.v1"
+
+# ---------------------------------------------------------------------------
+# Trust
+# ---------------------------------------------------------------------------
+
+#: Schema key for trust-scorecard computation records.
+TRUST_V1: str = "spanforge.trust.v1"
+
+# ---------------------------------------------------------------------------
+# Alerting
+# ---------------------------------------------------------------------------
+
+#: Schema key for sf-alert routed alert records.
+ALERT_V1: str = "spanforge.alert.v1"

{spanforge-1.0.3 → spanforge-1.0.4}/src/spanforge/sdk/__init__.py

@@ -189,7 +189,7 @@ from spanforge.sdk._types import (
     TrustStatusInfo,
 )
 from spanforge.sdk.alert import SFAlertClient
-from spanforge.sdk.audit import SFAuditClient
+from spanforge.sdk.audit import SFAuditClient, SFCompositeAuditSink
 from spanforge.sdk.cec import SFCECClient
 from spanforge.sdk.config import (
     SFConfigBlock,
@@ -244,6 +244,8 @@ from spanforge.sdk.secrets import SFSecretsClient
 from spanforge.sdk.validate import SFValidateClient, ValidateStatusInfo, ValidationResult, Violation
 from spanforge.sdk.security import SFSecurityClient
 from spanforge.sdk.trust import SFTrustClient
+from spanforge.sdk._factory import SFClientFactory
+from spanforge.sdk._pipeline_builder import SFPipeline, SFPipelineResult, PipelineStageError
 from spanforge.secrets import SecretHit, SecretsScanResult
 
 __all__ = [
@@ -335,6 +337,8 @@ __all__ = [
     "SFCECExportError",
     "SFCECVerifyError",
     "SFClientConfig",
+    "SFClientFactory",
+    "SFCompositeAuditSink",
     # Phase 9 — Integration Config & Local Fallback
     "SFConfigBlock",
     "SFConfigError",
@@ -380,6 +384,9 @@ __all__ = [
     "SFPolicyClient",
     # Phase 10 — T.R.U.S.T. Scorecard & HallucCheck Contract
     "SFPipelineError",
+    "SFPipeline",
+    "SFPipelineResult",
+    "PipelineStageError",
     "SFQuotaExceededError",
     "SFRBACClient",
     "SFRateLimitError",

{spanforge-1.0.3 → spanforge-1.0.4}/src/spanforge/sdk/_exceptions.py

@@ -85,8 +85,29 @@ class SFError(Exception):
     All public-facing SDK exceptions derive from this class, enabling callers
     to write a single broad ``except SFError`` guard as a safety net while
     still being able to catch specific sub-types for targeted handling.
+
+    Args:
+        *args:          Forwarded to :class:`Exception`.
+        tsc_criterion:  Optional SOC 2 / ISO 27001 Trust Services Criterion that
+                        this error maps to (e.g. ``"CC6.6"``, ``"CC7.2"``).
+                        Set by SDK clients so callers can map failures directly
+                        to their compliance framework without a hand-written lookup.
+
+    Example::
+
+        try:
+            sf_pii.scan_text(text)
+        except SFPIIError as exc:
+            print(exc.tsc_criterion)   # "CC6.6"
     """
 
+    #: SOC 2 / ISO 27001 criterion label — empty string when not applicable.
+    tsc_criterion: str
+
+    def __init__(self, *args: object, tsc_criterion: str = "") -> None:
+        super().__init__(*args)
+        self.tsc_criterion = tsc_criterion
+
 
 # ---------------------------------------------------------------------------
 # Authentication errors
@@ -404,13 +425,16 @@ class SFSecretsBlockedError(SFSecretsError):
             )
     """
 
-    def __init__(self, secret_types: list[str], count: int = 1) -> None:
+    def __init__(
+        self, secret_types: list[str], count: int = 1, *, tsc_criterion: str = "CC6.7"
+    ) -> None:
         self.secret_types = secret_types
         self.count = count
         types_str = ", ".join(repr(t) for t in secret_types) if secret_types else "(unknown)"
         super().__init__(
             f"Secrets scan blocked: {count} secret(s) detected of type(s) {types_str}. "
-            "Remove the secret and rotate credentials before continuing."
+            "Remove the secret and rotate credentials before continuing.",
+            tsc_criterion=tsc_criterion,
         )
 
 
@@ -445,14 +469,17 @@ class SFPIIBlockedError(SFPIIError):
         count:        Number of blocking hits.
     """
 
-    def __init__(self, entity_types: list[str], count: int = 1) -> None:
+    def __init__(
+        self, entity_types: list[str], count: int = 1, *, tsc_criterion: str = "CC6.6"
+    ) -> None:
         self.entity_types = entity_types
         self.count = count
         types_str = ", ".join(repr(t) for t in entity_types) if entity_types else "(unknown)"
         super().__init__(
             f"PII detected ({count} entity/entities of type(s) {types_str}) — "
             "pipeline action 'block' prevents scoring. "
-            "Remove PII from the input or change the pipeline pii_action to 'flag' or 'redact'."
+            "Remove PII from the input or change the pipeline pii_action to 'flag' or 'redact'.",
+            tsc_criterion=tsc_criterion,
         )
 
 
@@ -772,14 +799,15 @@ class SFGateEvaluationError(SFGateError):
 
     Args:
         detail: Human-readable description of the failure.
+        tsc_criterion: SOC 2 criterion. Defaults to ``"CC7.2"``.
 
     Attributes:
         detail: The detail message passed at construction time.
     """
 
-    def __init__(self, detail: str) -> None:
+    def __init__(self, detail: str, *, tsc_criterion: str = "CC7.2") -> None:
         self.detail = detail
-        super().__init__(f"Gate evaluation failed: {detail}")
+        super().__init__(f"Gate evaluation failed: {detail}", tsc_criterion=tsc_criterion)
 
 
 class SFGatePipelineError(SFGateError):
@@ -819,9 +847,9 @@ class SFGateTrustFailedError(SFGateError):
         failures: The failure reasons passed at construction time.
     """
 
-    def __init__(self, failures: list[str]) -> None:
+    def __init__(self, failures: list[str], *, tsc_criterion: str = "CC7.4") -> None:
         self.failures = failures
-        super().__init__("Trust gate failed: " + "; ".join(failures))
+        super().__init__("Trust gate failed: " + "; ".join(failures), tsc_criterion=tsc_criterion)
 
 
 class SFGateSchemaError(SFGateError):