cairo-sdk 1.0.0__tar.gz

cairo_sdk-1.0.0/PKG-INFO

@@ -0,0 +1,95 @@
+Metadata-Version: 2.4
+Name: cairo-sdk
+Version: 1.0.0
+Summary: CAIRO Protocol SDK — forensic AI governance telemetry, deterministic interception, and EU AI Act enforcement for agentic AI systems
+Author-email: XSData Factory Private Limited <sdk@cairoprotocol.com>
+License: Proprietary
+Project-URL: Homepage, https://cairoprotocol.com
+Project-URL: Documentation, https://cairoprotocol.com/docs
+Project-URL: SDK Quickstart, https://cairoprotocol.com/docs/sdk-quickstart
+Project-URL: Source Code, https://cairoprotocol.com/platform
+Keywords: ai-governance,forensic-ai,eu-ai-act,cairo-protocol,agentic-ai,compliance,telemetry
+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 :: Security
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: pydantic>=2.0
+
+# CAIRO Protocol SDK
+
+**Forensic AI governance for agentic systems** — deterministic interception, real-time telemetry, and EU AI Act 2026 enforcement.
+
+## Install
+```bash
+pip install cairo-sdk
+```
+
+## Quick Start
+```python
+from cairo_sdk import TelemetryStream, ValueTracker, RiskPulse
+
+# Initialize telemetry
+stream = TelemetryStream(
+    value_tracker=ValueTracker(
+        annual_turnover_eur=500_000_000,
+        usd_per_eur=1.08,
+    )
+)
+
+# Emit a risk pulse
+pulse = RiskPulse(
+    pillar="Containment",
+    component="prompt_injection",
+    sub_component="boundary_check",
+    risk_level=0.7,
+    eu_ai_act_status="high",
+)
+stream.emit(pulse)
+
+# Get dashboard summary
+summary = stream.value_tracker.dashboard_summary()
+print(f"Total intercepts: {summary['total_intercepts']}")
+print(f"Risk exposure avoided: ${summary['total_risk_usd']:,.2f}")
+```
+
+## Five CAIRO Pillars
+
+| Pillar | Purpose | Module |
+|--------|---------|--------|
+| **Containment** | Boundaries, scope lits, sandboxing | `cairo_sdk.containment` |
+| **Attestation** | Compliance proof, audit trail | `cairo_sdk.attestation` |
+| **Interception** | Pre/post request hooks, middleware | `cairo_sdk.interception` |
+| **Resilience** | Fault handling, retries, fallback | `cairo_sdk.resilience` |
+| **Output-Logic** | Output validation, guardrails | `cairo_sdk.output_logic` |
+
+## Key Features
+
+- **ValueTracker** — real-time EU AI Act fine-avoidance calculation
+- **TelemetryStream** — high-speed forensic event streaming
+- **LogicDriftDetector** — behavioral drift detection across agent sessions
+- **Deterministic interception** — zero-trust validation at every CAIRO pillar
+- **Compliance metadata** — NIST AI RMF, ISO 42001, EU AI Act mapping
+
+## Requirements
+
+- Python 3.9+
+- pydantic >= 2.0
+
+## Documentation
+
+- [SDK Quickstart](https://cairoprotocol.com/docs/sdk-quickstart)
+- [Integration Guides](https://cairoprotocol.com/docs/integration-guides)
+- [API Reference](https://cairoprotocol.com/docs/api-reference)
+
+#
+Proprietary — XSData Factory Private Limited. See [cairoprotocol.com/trust](https://cairoprotocol.com/trust) for terms.

cairo_sdk-1.0.0/README.md

@@ -0,0 +1,68 @@
+# CAIRO Protocol SDK
+
+**Forensic AI governance for agentic systems** — deterministic interception, real-time telemetry, and EU AI Act 2026 enforcement.
+
+## Install
+```bash
+pip install cairo-sdk
+```
+
+## Quick Start
+```python
+from cairo_sdk import TelemetryStream, ValueTracker, RiskPulse
+
+# Initialize telemetry
+stream = TelemetryStream(
+    value_tracker=ValueTracker(
+        annual_turnover_eur=500_000_000,
+        usd_per_eur=1.08,
+    )
+)
+
+# Emit a risk pulse
+pulse = RiskPulse(
+    pillar="Containment",
+    component="prompt_injection",
+    sub_component="boundary_check",
+    risk_level=0.7,
+    eu_ai_act_status="high",
+)
+stream.emit(pulse)
+
+# Get dashboard summary
+summary = stream.value_tracker.dashboard_summary()
+print(f"Total intercepts: {summary['total_intercepts']}")
+print(f"Risk exposure avoided: ${summary['total_risk_usd']:,.2f}")
+```
+
+## Five CAIRO Pillars
+
+| Pillar | Purpose | Module |
+|--------|---------|--------|
+| **Containment** | Boundaries, scope lits, sandboxing | `cairo_sdk.containment` |
+| **Attestation** | Compliance proof, audit trail | `cairo_sdk.attestation` |
+| **Interception** | Pre/post request hooks, middleware | `cairo_sdk.interception` |
+| **Resilience** | Fault handling, retries, fallback | `cairo_sdk.resilience` |
+| **Output-Logic** | Output validation, guardrails | `cairo_sdk.output_logic` |
+
+## Key Features
+
+- **ValueTracker** — real-time EU AI Act fine-avoidance calculation
+- **TelemetryStream** — high-speed forensic event streaming
+- **LogicDriftDetector** — behavioral drift detection across agent sessions
+- **Deterministic interception** — zero-trust validation at every CAIRO pillar
+- **Compliance metadata** — NIST AI RMF, ISO 42001, EU AI Act mapping
+
+## Requirements
+
+- Python 3.9+
+- pydantic >= 2.0
+
+## Documentation
+
+- [SDK Quickstart](https://cairoprotocol.com/docs/sdk-quickstart)
+- [Integration Guides](https://cairoprotocol.com/docs/integration-guides)
+- [API Reference](https://cairoprotocol.com/docs/api-reference)
+
+#
+Proprietary — XSData Factory Private Limited. See [cairoprotocol.com/trust](https://cairoprotocol.com/trust) for terms.

cairo_sdk-1.0.0/cairo_sdk/__init__.py

@@ -0,0 +1,37 @@
+"""
+CAIRO SDK — telemetry, deterministic interception, EU AI Act enforcement, and ValueTracker.
+100% aligned with CAIRO Protocol Technical Architecture v1.0.
+"""
+
+from cairo_sdk.telemetry import (
+    TelemetryStream,
+    RiskPulse,
+    ComplianceMetadata,
+    SafetyOverheadEvent,
+    LogicDriftDetector,
+    EUAIActStatus,
+    PulseSeverity,
+    get_global_stream,
+    # ValueTracker & EU AI Act 2026 cost reporting
+    ValueTracker,
+    InterceptRecord,
+    EnforcementTier,
+    EU_FINES_2026,
+    ACTION_CONTROL_MAP,
+)
+
+__all__ = [
+    "TelemetryStream",
+    "RiskPulse",
+    "ComplianceMetadata",
+    "SafetyOverheadEvent",
+    "LogicDriftDetector",
+    "EUAIActStatus",
+    "PulseSeverity",
+    "get_global_stream",
+    "ValueTracker",
+    "InterceptRecord",
+    "EnforcementTier",
+    "EU_FINES_2026",
+    "ACTION_CONTROL_MAP",
+]

cairo_sdk-1.0.0/cairo_sdk/analytics.py

@@ -0,0 +1,475 @@
+"""
+cairo_sdk/analytics.py — CAIRO SDK: CairoAnalyticsLogger
+
+DynamoDB-backed audit log for the CairoAnalytics table.  Every ArmorMiddleware
+run writes one structured event containing:
+
+  event_type              "agent_response" | "compliance_event" | "armor_run"
+  correlation_id          from AgentRequest
+  compliance_label        EU AI Act Art. 50 declaration
+  pillar_results          per-pillar pass/fail summary
+  timestamp_utc           ISO-8601
+  regulatory_tags         AXON Compliance Engine — NIST / ISO 42001 / EU AI Act controls
+  risk_level              "Low" | "Medium" | "High"
+  risk_mitigation_value   representative per-incident "Saved Fine" in USD
+
+Non-blocking write path
+───────────────────────
+log_request() is the production entry point for all middleware instrumentation.
+After resolving regulatory tags (CPU-only, synchronous, < 1 ms), it submits the
+DynamoDB put_item call to a module-level ThreadPoolExecutor so the operation is
+fully fire-and-forget.  The caller's async event loop is never blocked by network
+I/O — CAIRO Shield adds zero latency to the user's AI experience.
+
+Error handling
+──────────────
+All DynamoDB calls catch specific botocore exceptions (ClientError, BotoCoreError)
+and log warnings via the standard Python logging system rather than silently
+swallowing errors or surfacing them to the caller.  Analytics failure is never
+allowed to affect the primary agent response path.
+
+Public API
+──────────
+  log_event(event_type, data)
+      Low-level synchronous writer — stores exactly what you pass in.
+      Backward-compatible; mocked in tests via unittest.mock.MagicMock.
+
+  log_request(event_type, data, pillar, action_type)
+      High-level AXON entry point — non-blocking.
+      Resolves regulatory tags, enriches `data`, then submits the DynamoDB
+      write to the background thread pool.
+
+  scan_events(limit)
+      Read path — full table scan for the AXON dashboard.
+
+In production, set CAIRO_DYNAMO_TABLE and CAIRO_DYNAMO_REGION env vars.
+In tests, inject a unittest.mock.MagicMock in place of this class.
+
+CAIRO Protocol Technical Architecture v1.0.
+"""
+
+from __future__ import annotations
+
+import atexit
+import concurrent.futures
+import datetime
+import json
+import logging
+import uuid
+from typing import Any
+
+# ---------------------------------------------------------------------------
+# Module-level infrastructure
+# ---------------------------------------------------------------------------
+
+_logger: logging.Logger = logging.getLogger(__name__)
+
+# Thread pool for fire-and-forget DynamoDB writes.
+# max_workers=4 handles burst writes without overwhelming DynamoDB capacity.
+# The pool is shared across ALL CairoAnalyticsLogger instances (process-wide).
+_EXECUTOR: concurrent.futures.ThreadPoolExecutor = (
+    concurrent.futures.ThreadPoolExecutor(
+        max_workers=4,
+        thread_name_prefix="cairo-analytics-writer",
+    )
+)
+# Graceful shutdown: cancel queued futures, do NOT wait for in-flight ones.
+atexit.register(_EXECUTOR.shutdown, wait=False)
+
+# ---------------------------------------------------------------------------
+# botocore exception guard
+# ---------------------------------------------------------------------------
+# Try to import the specific exception hierarchy so callers receive informative
+# warnings.  If botocore is not installed we fall back to catching Exception,
+# which is equivalent behaviour but loses the structured log context.
+
+try:
+    from botocore.exceptions import BotoCoreError, ClientError as _BotoClientError  # type: ignore[import-untyped]
+    _BOTOCORE_ERRORS: tuple[type[Exception], ...] = (BotoCoreError, _BotoClientError)
+except ImportError:
+    _BOTOCORE_ERRORS = (Exception,)
+
+
+# ===========================================================================
+# CairoAnalyticsLogger
+# ===========================================================================
+
+class CairoAnalyticsLogger:
+    """
+    Writes compliance events to the CairoAnalytics DynamoDB table and reads
+    them back for the AXON Executive Dashboard.
+
+    Interface is intentionally minimal so the class can be swapped with a
+    ``unittest.mock.MagicMock`` in test environments without any additional
+    dependencies or AWS access.
+
+    Write path  — ``log_event`` (sync, low-level) and ``log_request``
+                  (async/fire-and-forget, high-level with regulatory tags).
+    Read path   — ``scan_events`` (full table scan, dashboard use only).
+
+    Parameters
+    ----------
+    table_name : str
+        DynamoDB table name.  Defaults to ``"CairoAnalytics"`` — must match
+        the table created by ``scripts/deploy_aws.sh``.
+    region : str
+        AWS region where the table lives.  Defaults to ``"us-east-1"``.
+    endpoint_url : str or None
+        Override DynamoDB endpoint for local testing (e.g.
+        ``"http://localhost:8000"``).  Leave ``None`` in production.
+
+    Environment Variables
+    ---------------------
+    CAIRO_DYNAMO_TABLE       Table name override.
+    CAIRO_DYNAMO_REGION      Region override.
+    CAIRO_DYNAMO_ENDPOINT_URL  Local endpoint override.
+    """
+
+    def __init__(
+        self,
+        table_name: str = "CairoAnalytics",
+        region: str = "us-east-1",
+        endpoint_url: str | None = None,
+    ) -> None:
+        self.table_name = table_name
+        self.region = region
+        self.endpoint_url = endpoint_url or None
+        self._table: Any = None  # lazy-initialised on first use
+
+    # ------------------------------------------------------------------
+    # Internal: DynamoDB resource initialisation
+    # ------------------------------------------------------------------
+
+    def _get_table(self) -> Any:
+        """
+        Return a boto3 DynamoDB Table resource, initialising the connection
+        lazily on first call.
+
+        Raises
+        ------
+        RuntimeError
+            If ``boto3`` is not installed.
+        BotoCoreError / ClientError
+            If the AWS connection or table lookup fails.  Callers that need
+            resilience should catch ``_BOTOCORE_ERRORS``.
+        """
+        if self._table is None:
+            try:
+                import boto3  # type: ignore[import-untyped]
+
+                kwargs: dict[str, Any] = {"region_name": self.region}
+                if self.endpoint_url:
+                    kwargs["endpoint_url"] = self.endpoint_url
+                dynamodb = boto3.resource("dynamodb", **kwargs)
+                self._table = dynamodb.Table(self.table_name)
+            except ImportError:
+                raise RuntimeError(
+                    "boto3 is required for DynamoDB logging. "
+                    "Install it with:  pip install boto3"
+                )
+            except _BOTOCORE_ERRORS as exc:
+                _logger.error(
+                    "Failed to initialise DynamoDB resource "
+                    "[table=%s region=%s]: %s: %s",
+                    self.table_name, self.region,
+                    type(exc).__name__, exc,
+                )
+                raise
+        return self._table
+
+    # ------------------------------------------------------------------
+    # Low-level writer (synchronous — kept for test-mock compatibility)
+    # ------------------------------------------------------------------
+
+    def log_event(
+        self,
+        event_type: str,
+        data: dict[str, Any],
+    ) -> None:
+        """
+        Write one compliance event to the CairoAnalytics DynamoDB table.
+
+        This is the low-level synchronous writer.  It is kept synchronous so
+        that ``unittest.mock.MagicMock`` replacements in test suites can
+        directly assert ``log_event.call_args`` without threading concerns.
+
+        For production middleware instrumentation, prefer ``log_request()``
+        which is non-blocking and automatically attaches regulatory tags.
+
+        Parameters
+        ----------
+        event_type : str
+            ``"agent_response"`` | ``"compliance_event"`` | ``"armor_run"``.
+        data : dict
+            Arbitrary payload — serialised to a JSON string for DynamoDB
+            storage.  The dict is not mutated.
+
+        Error Handling
+        --------------
+        botocore ``ClientError`` / ``BotoCoreError`` are caught and logged as
+        WARNING messages so a DynamoDB outage never surfaces to the caller.
+        Any other unexpected exception is logged at WARNING level and swallowed.
+        """
+        item: dict[str, Any] = {
+            "event_id":    str(uuid.uuid4()),
+            "event_type":  event_type,
+            "timestamp_utc": datetime.datetime.now(datetime.timezone.utc).isoformat(
+                timespec="milliseconds"
+            ),
+            "data": json.dumps(data, default=str),
+        }
+        try:
+            table = self._get_table()
+            table.put_item(Item=item)
+        except _BOTOCORE_ERRORS as exc:
+            _logger.warning(
+                "DynamoDB put_item failed [event_type=%s table=%s]: %s: %s",
+                event_type, self.table_name, type(exc).__name__, exc,
+            )
+        except Exception as exc:  # noqa: BLE001
+            _logger.warning(
+                "Unexpected error in DynamoDB write [event_type=%s]: %s",
+                event_type, exc,
+            )
+
+    # ------------------------------------------------------------------
+    # Internal: thread-pool target (runs in background thread)
+    # ------------------------------------------------------------------
+
+    def _write_item(self, event_type: str, data: dict[str, Any]) -> None:
+        """
+        Internal method executed in the background thread pool.
+
+        Calls ``log_event()`` and suppresses all exceptions so a thread crash
+        never propagates to the ``ThreadPoolExecutor`` error log.
+
+        This method is not part of the public API; it exists solely as the
+        callable submitted to ``_EXECUTOR``.
+        """
+        try:
+            self.log_event(event_type, data)
+        except Exception as exc:  # noqa: BLE001
+            _logger.warning("Background DynamoDB write raised: %s", exc)
+
+    # ------------------------------------------------------------------
+    # High-level AXON entry point (non-blocking, fire-and-forget)
+    # ------------------------------------------------------------------
+
+    def log_request(
+        self,
+        event_type: str,
+        data: dict[str, Any],
+        pillar: str | None = None,
+        action_type: str | None = None,
+    ) -> None:
+        """
+        AXON Compliance Engine entry point — **non-blocking**.
+
+        Resolves the full set of regulatory tags for the given ``pillar`` /
+        ``action_type`` from ``governance_map.py``, merges them into a copy of
+        ``data``, then submits the DynamoDB ``put_item`` call to the module-level
+        ``ThreadPoolExecutor`` and returns immediately.
+
+        The caller's thread (and any async event loop) is never blocked by
+        network I/O.  CAIRO Shield adds zero latency to the user's AI response.
+
+        Enrichment
+        ──────────
+        Every item written by this method contains three additional top-level
+        DynamoDB attributes that make the CairoAnalytics table directly
+        queryable for compliance reporting:
+
+        ``regulatory_tags``
+            Full NIST AI RMF / ISO 42001 / EU AI Act control cross-walk dict.
+        ``risk_level``
+            ``"Low"`` | ``"Medium"`` | ``"High"``
+        ``risk_mitigation_value``
+            ``{"amount_usd": float, "currency": "USD", "description": str}``
+
+        Parameters
+        ----------
+        event_type : str
+            ``"agent_response"`` | ``"compliance_event"`` | ``"armor_run"``.
+        data : dict
+            Payload dict.  **Not mutated** — a copy is enriched before writing.
+        pillar : str or None
+            CAIRO pillar name: ``"containment"`` | ``"attestation"`` |
+            ``"interception"`` | ``"resilience"`` | ``"output_logic"``.
+            Used when ``action_type`` is not known or a pillar-level override
+            is needed.
+        action_type : str or None
+            Action key from ``ACTION_RISK_MAP`` (e.g. ``"prompt_injection_blocked"``,
+            ``"pii_blocked"``, ``"transparency_banner_added"``).  When supplied,
+            the most granular action-level controls are used.
+
+        Resolution Precedence
+        ─────────────────────
+        ``action_type`` (most granular) → ``pillar`` (defaults) → containment fallback.
+
+        Thread Safety
+        ─────────────
+        The method is thread-safe: each call builds its own independent ``enriched``
+        dict before submitting to the shared executor.  The ``data`` argument is
+        never shared between threads.
+
+        Notes
+        ─────
+        The regulatory-tag resolution (CPU-only, < 1 ms) runs synchronously on
+        the caller's thread so any ``ValueError`` from invalid pillar/action names
+        surfaces immediately.  Only the DynamoDB I/O is deferred.
+        """
+        # Deferred import prevents circular dependency at module load time.
+        from cairo_sdk.governance_map import resolve_regulatory_tags  # noqa: PLC0415
+
+        # Regulatory tag resolution is CPU-only: stays on caller's thread.
+        tags = resolve_regulatory_tags(pillar=pillar, action_type=action_type)
+
+        enriched: dict[str, Any] = dict(data)
+        enriched["regulatory_tags"] = tags.model_dump()
+        enriched["risk_level"] = tags.risk_level
+        enriched["risk_mitigation_value"] = {
+            "amount_usd": tags.risk_mitigation_value_usd,
+            "currency": "USD",
+            "description": (
+                f"Theoretical per-incident 'Saved Fine' for "
+                f"{action_type or pillar or 'unknown'} — represents mitigated "
+                f"regulatory risk.  Risk level: {tags.risk_level}."
+            ),
+        }
+
+        # Fire-and-forget: DynamoDB I/O runs in background thread.
+        _EXECUTOR.submit(self._write_item, event_type, enriched)
+
+    # ------------------------------------------------------------------
+    # Internal: item normaliser (static — shared by scan_events and tests)
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def _normalize_item(item: dict[str, Any]) -> dict[str, Any] | None:
+        """
+        Flatten one raw DynamoDB item into a dashboard-ready dict.
+
+        The DynamoDB item has the shape written by ``log_event`` / ``log_request``:
+        ``{ event_id, event_type, timestamp_utc, data: "<JSON string>" }``
+
+        The returned dict exposes every nested field at the top level so the
+        dashboard and report generator can work with plain pandas DataFrames
+        without any further transformation.
+
+        Parameters
+        ----------
+        item : dict
+            Raw DynamoDB item — ``"data"`` may be a JSON string or an already-
+            decoded dict (both are handled transparently).
+
+        Returns
+        -------
+        dict or None
+            Flat normalised record, or ``None`` if parsing fails.  Callers
+            silently skip ``None`` entries.
+
+        Returned Keys
+        -------------
+        ``event_id``, ``event_type``, ``timestamp_utc``, ``pillar``,
+        ``action_type``, ``risk_level``, ``risk_mitigation_value_usd``,
+        ``nist_categories``, ``iso_annex_controls``, ``eu_articles``,
+        ``eu_enforcement_tier``, ``correlation_id``.
+        """
+        try:
+            raw_data = item.get("data", "{}")
+            data: dict[str, Any] = (
+                json.loads(raw_data) if isinstance(raw_data, str) else raw_data
+            )
+            tags: dict[str, Any] = data.get("regulatory_tags", {})
+            rmv:  dict[str, Any] = data.get("risk_mitigation_value", {})
+
+            return {
+                "event_id":      item.get("event_id", ""),
+                "event_type":    item.get("event_type", "compliance_event"),
+                "timestamp_utc": item.get("timestamp_utc", ""),
+                "pillar":        tags.get("pillar") or data.get("pillar", "unknown"),
+                "action_type":   (
+                    tags.get("action_type") or data.get("action_type", "unknown")
+                ),
+                "risk_level":    (
+                    tags.get("risk_level") or data.get("risk_level", "Medium")
+                ),
+                "risk_mitigation_value_usd": float(
+                    rmv.get("amount_usd")
+                    or tags.get("risk_mitigation_value_usd", 0.0)
+                    or 0.0
+                ),
+                "nist_categories":     tags.get("nist_categories", []),
+                "iso_annex_controls":  tags.get("iso_annex_controls", []),
+                "eu_articles":         tags.get("eu_articles", []),
+                "eu_enforcement_tier": tags.get("eu_enforcement_tier", ""),
+                "correlation_id":      data.get("correlation_id"),
+            }
+        except Exception:  # noqa: BLE001
+            return None
+
+    # ------------------------------------------------------------------
+    # Read path — dashboard data fetching
+    # ------------------------------------------------------------------
+
+    def scan_events(self, limit: int = 500) -> list[dict[str, Any]]:
+        """
+        Scan the CairoAnalytics DynamoDB table and return normalised records.
+
+        Intended for the AXON Executive Dashboard, which calls this method at
+        most every 60 seconds (``@st.cache_data(ttl=60)``).
+
+        Parameters
+        ----------
+        limit : int
+            Maximum number of records to return after sorting.  Pagination
+            exhausts all DynamoDB pages first, then trims to ``limit``.
+
+        Returns
+        -------
+        list[dict]
+            Normalised records (output of ``_normalize_item``), sorted by
+            ``timestamp_utc`` descending (most-recent first).
+            Returns ``[]`` if DynamoDB is unavailable — the dashboard then
+            falls back to demo data automatically.
+
+        Notes
+        ─────
+        Uses a full table scan (acceptable for compliance audit tables with
+        < 100 k items).  For larger deployments, add a GSI on ``timestamp_utc``
+        and switch to a ``query`` call for O(log n) reads.
+
+        Error Handling
+        ──────────────
+        ``BotoCoreError`` / ``ClientError`` are caught and logged as WARNING.
+        Any other exception is also caught and logged.  The method **never
+        raises** — a connectivity blip must not crash the dashboard.
+        """
+        results: list[dict[str, Any]] = []
+        try:
+            table = self._get_table()
+            scan_kwargs: dict[str, Any] = {}
+
+            while True:
+                response = table.scan(**scan_kwargs)
+                for raw_item in response.get("Items", []):
+                    norm = self._normalize_item(raw_item)
+                    if norm:
+                        results.append(norm)
+
+                if "LastEvaluatedKey" not in response:
+                    break
+                scan_kwargs["ExclusiveStartKey"] = response["LastEvaluatedKey"]
+
+            results.sort(key=lambda x: x.get("timestamp_utc", ""), reverse=True)
+            return results[:limit]
+
+        except _BOTOCORE_ERRORS as exc:
+            _logger.warning(
+                "DynamoDB scan failed [table=%s]: %s: %s",
+                self.table_name, type(exc).__name__, exc,
+            )
+            return []
+        except Exception as exc:  # noqa: BLE001
+            _logger.warning("Unexpected error in scan_events: %s", exc)
+            return []

cairo_sdk-1.0.0/cairo_sdk/attestation/__init__.py

@@ -0,0 +1 @@
+# CAIRO SDK — Attestation pillar (compliance proof, audit)