admina-framework 0.9.0__py3-none-any.whl

admina/sdk/governed_data.py

@@ -0,0 +1,434 @@
+# Copyright © 2025–2026 Stefano Noferi & Admina contributors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Admina — GovernedData SDK primitive.
+
+Wraps a data connector with automatic data classification, residency
+enforcement, PII redaction, and governance event emission.
+"""
+
+from __future__ import annotations
+
+import time
+import uuid
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from typing import Any
+
+from admina.core.event_bus import EventType, GovernanceEvent, bus
+from admina.sdk._compat import run_sync
+
+__all__ = ["GovernedData", "GovernedDocument", "IngestResult", "BaseDataConnector"]
+
+
+class BaseDataConnector(ABC):
+    """Abstract base for data connectors.
+
+    Concrete connectors (filesystem, ChromaDB, etc.) implement this
+    interface. See :mod:`admina.plugins.base.BaseDataConnector` for the
+    canonical plugin definition used by the registry.
+    """
+
+    @abstractmethod
+    async def ingest(self, source: Any, **kwargs: Any) -> dict:
+        """Ingest data from source.
+
+        Returns:
+            Dict with at least ``doc_count`` and ``chunk_count`` keys.
+        """
+
+    @abstractmethod
+    async def query(self, query: str, **kwargs: Any) -> list[dict]:
+        """Query the data store.
+
+        Returns:
+            List of dicts with ``text``, ``metadata``, and ``score`` keys.
+        """
+
+    @property
+    @abstractmethod
+    def name(self) -> str:
+        """Human-readable connector name."""
+
+
+@dataclass
+class IngestResult:
+    """Result of a GovernedData.ingest() call.
+
+    Attributes:
+        doc_count: Number of documents ingested.
+        chunk_count: Number of chunks produced.
+        classification: Data classification results (PII stats, sensitivity).
+        governance: Governance decisions applied during ingest.
+    """
+
+    doc_count: int = 0
+    chunk_count: int = 0
+    classification: dict[str, Any] = field(default_factory=dict)
+    governance: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class GovernedDocument:
+    """A single document returned by GovernedData.query().
+
+    Attributes:
+        text: Document text (PII-redacted if applicable).
+        metadata: Document metadata from the connector.
+        score: Relevance score from the connector.
+        governance: Governance decisions applied to this document.
+    """
+
+    text: str
+    metadata: dict[str, Any] = field(default_factory=dict)
+    score: float = 0.0
+    governance: dict[str, Any] = field(default_factory=dict)
+
+
+# Allowed residency zones
+VALID_ZONES = {"local", "eu", "us", "custom"}
+
+
+def _load_pii_redactor() -> Any:
+    """Lazily load the PII redactor to avoid import-time spaCy load."""
+    from admina.domains.data_sovereignty.pii import PIIRedactor
+
+    return PIIRedactor()
+
+
+def _classify_content(text: str, pii_result: dict) -> dict[str, Any]:
+    """Classify content sensitivity based on PII scan results.
+
+    Args:
+        text: The original text.
+        pii_result: Result dict from PIIRedactor.redact().
+
+    Returns:
+        Classification dict with sensitivity level and details.
+    """
+    pii_count = pii_result.get("count", 0)
+    pii_types = {e["type"] for e in pii_result.get("entities", [])}
+
+    high_risk_types = {"CREDIT_CARD", "SSN", "IBAN"}
+    has_high_risk = bool(pii_types & high_risk_types)
+
+    if has_high_risk or pii_count >= 5:
+        sensitivity = "HIGH"
+    elif pii_count >= 1:
+        sensitivity = "MEDIUM"
+    else:
+        sensitivity = "LOW"
+
+    return {
+        "sensitivity": sensitivity,
+        "pii_count": pii_count,
+        "pii_types": sorted(pii_types),
+        "has_high_risk_pii": has_high_risk,
+    }
+
+
+class GovernedData:
+    """SDK primitive for governed data access.
+
+    Wraps a data connector with automatic data classification,
+    residency zone enforcement, PII redaction, and event emission.
+
+    Args:
+        connector: A BaseDataConnector instance, or None.
+        residency_zone: Data residency zone (local, eu, us, custom).
+        allowed_zones: Set of zones this instance may access.
+        audit: Whether to emit governance events.
+        pii_redaction: Whether to run PII redaction on query results.
+    """
+
+    def __init__(
+        self,
+        connector: BaseDataConnector | None = None,
+        residency_zone: str = "local",
+        allowed_zones: set[str] | None = None,
+        audit: bool = True,
+        pii_redaction: bool = True,
+    ) -> None:
+        """Initialize GovernedData.
+
+        Args:
+            connector: Data connector instance. Can be resolved via
+                :class:`PluginRegistry` or passed explicitly.
+            residency_zone: Zone where this data resides.
+            allowed_zones: Zones allowed for data access. Defaults to
+                {residency_zone}.
+            audit: If True, emit events to the event bus.
+            pii_redaction: If True, redact PII from query results.
+        """
+        self._connector = connector
+        self.residency_zone = residency_zone
+        self.allowed_zones = allowed_zones or {residency_zone}
+        self._audit = audit
+        self._pii_redaction = pii_redaction
+        self._pii_redactor: Any = None
+
+    def _get_pii_redactor(self) -> Any:
+        """Return the PII redactor, creating it lazily."""
+        if self._pii_redactor is None:
+            self._pii_redactor = _load_pii_redactor()
+        return self._pii_redactor
+
+    def _check_residency(self, target_zone: str) -> bool:
+        """Check if access to target_zone is allowed.
+
+        Args:
+            target_zone: The zone being accessed.
+
+        Returns:
+            True if allowed.
+
+        Raises:
+            PermissionError: If the zone is not in allowed_zones.
+        """
+        if target_zone not in self.allowed_zones:
+            raise PermissionError(
+                f"Data residency violation: zone '{target_zone}' "
+                f"not in allowed zones {self.allowed_zones}"
+            )
+        return True
+
+    async def ingest(
+        self,
+        source: Any,
+        target_zone: str | None = None,
+        **kwargs: Any,
+    ) -> IngestResult:
+        """Ingest data with governance checks.
+
+        Classifies data (PII scan, sensitivity), checks residency rules,
+        emits events, and passes to the connector.
+
+        Args:
+            source: Data source (string content, file path, etc.).
+            target_zone: Zone to ingest into. Defaults to residency_zone.
+            **kwargs: Forwarded to connector.ingest().
+
+        Returns:
+            IngestResult with counts, classification, and governance info.
+
+        Raises:
+            RuntimeError: If no connector is configured.
+            PermissionError: If residency check fails.
+        """
+        if self._connector is None:
+            raise RuntimeError(
+                "No data connector configured. Pass a connector to "
+                "GovernedData() or resolve one via PluginRegistry."
+            )
+
+        zone = target_zone or self.residency_zone
+        session_id = kwargs.pop("session_id", None) or str(uuid.uuid4())
+        start_us = time.time() * 1_000_000
+        governance: dict[str, Any] = {"residency": {"zone": zone, "allowed": True}}
+
+        # 1. Check residency
+        try:
+            self._check_residency(zone)
+        except PermissionError:
+            governance["residency"]["allowed"] = False
+            if self._audit:
+                await bus.emit(
+                    GovernanceEvent(
+                        event_type=EventType.DATA_ACCESS,
+                        session_id=session_id,
+                        domain="data-sovereignty",
+                        action="BLOCK",
+                        risk_level="CRITICAL",
+                        metadata={"reason": "residency_violation", "zone": zone},
+                    )
+                )
+            raise
+
+        # 2. Classify content (PII scan)
+        classification: dict[str, Any] = {}
+        content_for_scan = source if isinstance(source, str) else str(source)
+        pii_result = self._get_pii_redactor().redact(content_for_scan)
+        classification = _classify_content(content_for_scan, pii_result)
+
+        if self._audit:
+            await bus.emit(
+                GovernanceEvent(
+                    event_type=EventType.DATA_CLASSIFY,
+                    session_id=session_id,
+                    domain="data-sovereignty",
+                    metadata={
+                        "sensitivity": classification["sensitivity"],
+                        "pii_count": classification["pii_count"],
+                    },
+                )
+            )
+
+        # 3. Emit DATA_ACCESS event
+        if self._audit:
+            await bus.emit(
+                GovernanceEvent(
+                    event_type=EventType.DATA_ACCESS,
+                    session_id=session_id,
+                    domain="data-sovereignty",
+                    action="ALLOW",
+                    metadata={
+                        "operation": "ingest",
+                        "zone": zone,
+                        "connector": self._connector.name,
+                    },
+                )
+            )
+
+        # 4. Pass to connector
+        connector_result = await self._connector.ingest(source, **kwargs)
+
+        latency_us = time.time() * 1_000_000 - start_us
+        governance["latency_us"] = latency_us
+
+        return IngestResult(
+            doc_count=connector_result.get("doc_count", 0),
+            chunk_count=connector_result.get("chunk_count", 0),
+            classification=classification,
+            governance=governance,
+        )
+
+    async def query(
+        self,
+        query: str,
+        target_zone: str | None = None,
+        **kwargs: Any,
+    ) -> list[GovernedDocument]:
+        """Query data with governance checks.
+
+        Checks residency, retrieves from connector, redacts PII if needed,
+        and emits events.
+
+        Args:
+            query: The query string.
+            target_zone: Zone to query from. Defaults to residency_zone.
+            **kwargs: Forwarded to connector.query().
+
+        Returns:
+            List of GovernedDocument with redacted text and governance info.
+
+        Raises:
+            RuntimeError: If no connector is configured.
+            PermissionError: If residency check fails.
+        """
+        if self._connector is None:
+            raise RuntimeError(
+                "No data connector configured. Pass a connector to "
+                "GovernedData() or resolve one via PluginRegistry."
+            )
+
+        zone = target_zone or self.residency_zone
+        session_id = kwargs.pop("session_id", None) or str(uuid.uuid4())
+
+        # 1. Check residency
+        try:
+            self._check_residency(zone)
+        except PermissionError:
+            if self._audit:
+                await bus.emit(
+                    GovernanceEvent(
+                        event_type=EventType.DATA_ACCESS,
+                        session_id=session_id,
+                        domain="data-sovereignty",
+                        action="BLOCK",
+                        risk_level="CRITICAL",
+                        metadata={"reason": "residency_violation", "zone": zone},
+                    )
+                )
+            raise
+
+        # 2. Emit DATA_ACCESS event
+        if self._audit:
+            await bus.emit(
+                GovernanceEvent(
+                    event_type=EventType.DATA_ACCESS,
+                    session_id=session_id,
+                    domain="data-sovereignty",
+                    action="ALLOW",
+                    metadata={
+                        "operation": "query",
+                        "zone": zone,
+                        "connector": self._connector.name,
+                    },
+                )
+            )
+
+        # 3. Retrieve from connector
+        raw_results = await self._connector.query(query, **kwargs)
+
+        # 4. Redact PII and wrap results
+        documents: list[GovernedDocument] = []
+        for raw in raw_results:
+            raw_text = raw.get("text", "")
+            doc_governance: dict[str, Any] = {"pii": {"redacted": False, "count": 0}}
+
+            if self._pii_redaction and raw_text:
+                pii_result = self._get_pii_redactor().redact(raw_text)
+                text = pii_result["redacted_text"]
+                if pii_result["count"] > 0:
+                    doc_governance["pii"] = {
+                        "redacted": True,
+                        "count": pii_result["count"],
+                    }
+                    if self._audit:
+                        await bus.emit(
+                            GovernanceEvent(
+                                event_type=EventType.DATA_REDACT,
+                                session_id=session_id,
+                                domain="data-sovereignty",
+                                action="REDACT",
+                                metadata={"pii_count": pii_result["count"]},
+                            )
+                        )
+            else:
+                text = raw_text
+
+            documents.append(
+                GovernedDocument(
+                    text=text,
+                    metadata=raw.get("metadata", {}),
+                    score=raw.get("score", 0.0),
+                    governance=doc_governance,
+                )
+            )
+
+        return documents
+
+    def ingest_sync(self, source: Any, **kwargs: Any) -> IngestResult:
+        """Synchronous convenience wrapper around ingest().
+
+        Args:
+            source: Data source.
+            **kwargs: Forwarded to ingest().
+
+        Returns:
+            IngestResult.
+        """
+        return run_sync(self.ingest(source, **kwargs))
+
+    def query_sync(self, query: str, **kwargs: Any) -> list[GovernedDocument]:
+        """Synchronous convenience wrapper around query().
+
+        Args:
+            query: The query string.
+            **kwargs: Forwarded to query().
+
+        Returns:
+            List of GovernedDocument.
+        """
+        return run_sync(self.query(query, **kwargs))

admina/sdk/governed_model.py

@@ -0,0 +1,241 @@
+# Copyright © 2025–2026 Stefano Noferi & Admina contributors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Admina — GovernedModel SDK primitive.
+
+Wraps a model adapter with automatic PII redaction and governance
+event emission on every call.
+"""
+
+from __future__ import annotations
+
+import time
+import uuid
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from typing import Any
+
+from admina.core.event_bus import EventType, GovernanceEvent, bus
+from admina.sdk._compat import run_sync
+
+__all__ = ["GovernedModel", "GovernedResponse", "BaseModelAdapter"]
+
+
+class BaseModelAdapter(ABC):
+    """Abstract base for model adapters.
+
+    Concrete adapters (Ollama, OpenAI, etc.) implement this interface.
+    See :mod:`admina.plugins.base.BaseModelAdapter` for the canonical
+    plugin definition used by the registry.
+    """
+
+    @abstractmethod
+    async def send(self, prompt: str, context: Any = None, **kwargs: Any) -> dict:
+        """Send a prompt and return a response dict.
+
+        Returns:
+            Dict with at least ``text`` key and optional ``metadata``.
+        """
+
+    @abstractmethod
+    def supports_model(self, model_name: str) -> bool:
+        """Return True if this adapter can serve the given model."""
+
+    @property
+    @abstractmethod
+    def name(self) -> str:
+        """Human-readable adapter name."""
+
+
+@dataclass
+class GovernedResponse:
+    """Response from GovernedModel.ask().
+
+    Attributes:
+        text: The model's response text (PII-redacted).
+        metadata: Model metadata (tokens, latency, etc.).
+        governance: Governance decisions applied to this call.
+    """
+
+    text: str
+    metadata: dict[str, Any] = field(default_factory=dict)
+    governance: dict[str, Any] = field(default_factory=dict)
+
+
+def _load_pii_redactor() -> Any:
+    """Lazily load the PII redactor to avoid import-time spaCy load."""
+    from admina.domains.data_sovereignty.pii import PIIRedactor
+
+    return PIIRedactor()
+
+
+class GovernedModel:
+    """SDK primitive for governed model inference.
+
+    Wraps a model adapter with automatic PII redaction on prompts
+    and responses, and emits governance events for every call.
+
+    Args:
+        model_name: Name of the model to use (e.g. "llama3").
+        adapter: A BaseModelAdapter instance, or None for default.
+        audit: Whether to emit governance events.
+        pii_redaction: Whether to run PII redaction on prompts/responses.
+    """
+
+    def __init__(
+        self,
+        model_name: str,
+        adapter: BaseModelAdapter | None = None,
+        audit: bool = True,
+        pii_redaction: bool = True,
+    ) -> None:
+        """Initialize GovernedModel.
+
+        Args:
+            model_name: Model identifier passed to the adapter.
+            adapter: Adapter instance. Can be resolved via
+                :class:`PluginRegistry` or passed explicitly.
+            audit: If True, emit events to the event bus.
+            pii_redaction: If True, redact PII from prompts and responses.
+        """
+        self.model_name = model_name
+        self._adapter = adapter
+        self._audit = audit
+        self._pii_redaction = pii_redaction
+        self._pii_redactor: Any = None
+
+    def _get_pii_redactor(self) -> Any:
+        """Return the PII redactor, creating it lazily."""
+        if self._pii_redactor is None:
+            self._pii_redactor = _load_pii_redactor()
+        return self._pii_redactor
+
+    async def ask(
+        self,
+        prompt: str,
+        context: Any = None,
+        **kwargs: Any,
+    ) -> GovernedResponse:
+        """Send a governed prompt to the model.
+
+        Applies PII redaction, calls the adapter, redacts the response,
+        and emits governance events.
+
+        Args:
+            prompt: The user prompt.
+            context: Optional context passed to the adapter.
+            **kwargs: Additional arguments forwarded to the adapter.
+
+        Returns:
+            GovernedResponse with redacted text, metadata, and governance info.
+
+        Raises:
+            RuntimeError: If no adapter is configured.
+        """
+        if self._adapter is None:
+            raise RuntimeError(
+                "No model adapter configured. Pass an adapter to GovernedModel() "
+                "or resolve one via PluginRegistry."
+            )
+
+        session_id = kwargs.pop("session_id", None) or str(uuid.uuid4())
+        start_us = time.time() * 1_000_000
+        governance: dict[str, Any] = {
+            "pii_prompt": {"redacted": False, "count": 0},
+            "pii_response": {"redacted": False, "count": 0},
+        }
+
+        # 1. Emit MODEL_CALL event
+        if self._audit:
+            await bus.emit(
+                GovernanceEvent(
+                    event_type=EventType.MODEL_CALL,
+                    session_id=session_id,
+                    domain="ai-infra",
+                    metadata={"model": self.model_name, "adapter": self._adapter.name},
+                )
+            )
+
+        # 2. Run PII redaction on prompt
+        redacted_prompt = prompt
+        if self._pii_redaction:
+            pii_result = self._get_pii_redactor().redact(prompt)
+            redacted_prompt = pii_result["redacted_text"]
+            governance["pii_prompt"] = {
+                "redacted": pii_result["count"] > 0,
+                "count": pii_result["count"],
+                "entities": pii_result["entities"],
+            }
+
+        # 3. Call adapter
+        adapter_result = await self._adapter.send(
+            redacted_prompt,
+            context=context,
+            **kwargs,
+        )
+        raw_text = adapter_result.get("text", "")
+        adapter_metadata = adapter_result.get("metadata", {})
+
+        # 4. Run PII redaction on response
+        response_text = raw_text
+        if self._pii_redaction:
+            pii_result = self._get_pii_redactor().redact(raw_text)
+            response_text = pii_result["redacted_text"]
+            governance["pii_response"] = {
+                "redacted": pii_result["count"] > 0,
+                "count": pii_result["count"],
+                "entities": pii_result["entities"],
+            }
+
+        latency_us = time.time() * 1_000_000 - start_us
+        governance["latency_us"] = latency_us
+
+        # 5. Emit MODEL_RESPONSE event
+        if self._audit:
+            action = "ALLOW"
+            if governance["pii_prompt"]["redacted"] or governance["pii_response"]["redacted"]:
+                action = "REDACT"
+            await bus.emit(
+                GovernanceEvent(
+                    event_type=EventType.MODEL_RESPONSE,
+                    session_id=session_id,
+                    domain="ai-infra",
+                    action=action,
+                    metadata={
+                        "model": self.model_name,
+                        "latency_us": latency_us,
+                        "pii_prompt_count": governance["pii_prompt"]["count"],
+                        "pii_response_count": governance["pii_response"]["count"],
+                    },
+                )
+            )
+
+        # 6. Return GovernedResponse
+        return GovernedResponse(
+            text=response_text,
+            metadata=adapter_metadata,
+            governance=governance,
+        )
+
+    def ask_sync(self, prompt: str, **kwargs: Any) -> GovernedResponse:
+        """Synchronous convenience wrapper around ask().
+
+        Args:
+            prompt: The user prompt.
+            **kwargs: Forwarded to ask().
+
+        Returns:
+            GovernedResponse.
+        """
+        return run_sync(self.ask(prompt, **kwargs))