admina-framework 0.10.1__tar.gz → 0.11.0__tar.gz

{admina_framework-0.10.1/admina_framework.egg-info → admina_framework-0.11.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: admina-framework
-Version: 0.10.1
+Version: 0.11.0
 Summary: Admina — governed AI development framework
 Author-email: Stefano Noferi <info@admina.org>
 Maintainer-email: Stefano Noferi <info@admina.org>
@@ -52,7 +52,7 @@ Requires-Dist: opentelemetry-sdk<2,>=1.20; extra == "telemetry"
 Requires-Dist: opentelemetry-exporter-otlp-proto-grpc<2,>=1.20; extra == "telemetry"
 Requires-Dist: opentelemetry-instrumentation-fastapi<1,>=0.40b0; extra == "telemetry"
 Provides-Extra: rust
-Requires-Dist: admina-core<0.11,>=0.9.3; extra == "rust"
+Requires-Dist: admina-core<0.12,>=0.9.3; extra == "rust"
 Provides-Extra: full
 Requires-Dist: admina-framework[nlp,proxy,telemetry]; extra == "full"
 Provides-Extra: openai
@@ -69,8 +69,10 @@ Provides-Extra: bedrock
 Requires-Dist: boto3<2,>=1.34; extra == "bedrock"
 Provides-Extra: adapters
 Requires-Dist: admina-framework[anthropic,bedrock,gemini,mistral,ollama,openai]; extra == "adapters"
+Provides-Extra: presidio
+Requires-Dist: presidio-analyzer<3,>=2.2; extra == "presidio"
 Provides-Extra: all
-Requires-Dist: admina-framework[adapters,nlp,proxy,telemetry]; extra == "all"
+Requires-Dist: admina-framework[adapters,nlp,presidio,proxy,telemetry]; extra == "all"
 Dynamic: license-file
 
 <!--

{admina_framework-0.10.1 → admina_framework-0.11.0}/admina/__init__.py

@@ -23,7 +23,7 @@ from __future__ import annotations
 
 from admina.sdk import ComplianceKit, GovernedAgent, GovernedData, GovernedModel
 
-__version__ = "0.10.1"
+__version__ = "0.11.0"
 
 __all__ = [
     "__version__",

{admina_framework-0.10.1 → admina_framework-0.11.0}/admina/core/types.py

@@ -63,6 +63,7 @@ class EventType(str, Enum):
     # Proxy / MCP events
     MCP_REQUEST = "mcp_request"
     MCP_RESPONSE = "mcp_response"
+    GATEWAY_REQUEST = "gateway_request"
     INJECTION_DETECTED = "injection_detected"
     PII_REDACTED = "pii_redacted"
     LOOP_DETECTED = "loop_detected"

{admina_framework-0.10.1 → admina_framework-0.11.0}/admina/domains/compliance/forensic.py

@@ -18,8 +18,10 @@ Hash-chain integrity, immutable audit trail.
 """
 
 import hashlib
+import hmac
 import json
 import logging
+import os
 import threading
 import time
 from datetime import UTC, datetime
@@ -31,6 +33,8 @@ logger = logging.getLogger("admina.forensic_blackbox")
 
 # Key used to persist the chain state in the object store.
 _CHAIN_STATE_KEY = "_chain_state.json"
+# Sidecar holding the HMAC-SHA256 signature of the chain-state payload.
+_CHAIN_STATE_SIG_KEY = "_chain_state.json.sig"
 
 
 class ForensicBlackBox(BaseForensicStore):
@@ -63,6 +67,8 @@ class ForensicBlackBox(BaseForensicStore):
         # Retry policy for transient S3 errors
         s3_max_retries: int = 5,
         s3_base_delay_s: float = 0.2,
+        # Optional HMAC key for the chain-state file (else ADMINA_FORENSIC_STATE_KEY)
+        state_signing_key: str | None = None,
     ):
         self.boto3_client = boto3_client
         self.bucket = bucket
@@ -75,6 +81,7 @@ class ForensicBlackBox(BaseForensicStore):
         self.chain_head: str = "GENESIS"
         self.record_count: int = 0
         self._write_lock = threading.Lock()
+        self._state_signing_key = state_signing_key or os.environ.get("ADMINA_FORENSIC_STATE_KEY")
         if self.filesystem_dir is not None:
             self.filesystem_dir.mkdir(parents=True, exist_ok=True)
         self._ensure_bucket()
@@ -160,12 +167,35 @@ class ForensicBlackBox(BaseForensicStore):
         )
         return True
 
+    def _read_s3_state_sig(self) -> str | None:
+        """Read the HMAC sidecar object for the chain state (S3), or None."""
+        try:
+            obj = self.boto3_client.get_object(Bucket=self.bucket, Key=_CHAIN_STATE_SIG_KEY)
+            return obj["Body"].read().decode("utf-8").strip()
+        except Exception:  # noqa: BLE001 — NoSuchKey or similar
+            return None
+
     def _restore_chain_state(self):
         """Restore chain_head and record_count from the configured backend."""
         if self.boto3_client is not None:
             try:
                 obj = self.boto3_client.get_object(Bucket=self.bucket, Key=_CHAIN_STATE_KEY)
-                state = json.loads(obj["Body"].read().decode("utf-8"))
+                payload = obj["Body"].read()
+            except Exception:  # noqa: BLE001 — NoSuchKey or similar
+                logger.info("No existing forensic chain state in S3, starting fresh")
+                self._reconstruct_chain_state_from_records()
+                return
+            if self._state_signing_key and not self._state_sig_is_valid(
+                payload, self._read_s3_state_sig()
+            ):
+                logger.critical(
+                    "Forensic chain state signature INVALID or MISSING (S3) "
+                    "— possible tampering; reconstructing from records"
+                )
+                self._reconstruct_chain_state_from_records()
+                return
+            try:
+                state = json.loads(payload)
                 self.chain_head = state.get("chain_head", "GENESIS")
                 self.record_count = state.get("record_count", 0)
                 logger.info(
@@ -173,15 +203,37 @@ class ForensicBlackBox(BaseForensicStore):
                     self.record_count,
                     self.chain_head[:16],
                 )
-            except Exception:  # noqa: BLE001 — NoSuchKey or similar
-                logger.info("No existing forensic chain state in S3, starting fresh")
+            except (json.JSONDecodeError, UnicodeDecodeError):
+                logger.error("Corrupt forensic chain state (S3) — reconstructing from records")
                 self._reconstruct_chain_state_from_records()
             return
         if self.filesystem_dir is not None:
             state_path = self.filesystem_dir / _CHAIN_STATE_KEY
             if state_path.exists():
                 try:
-                    state = json.loads(state_path.read_text(encoding="utf-8"))
+                    payload = state_path.read_bytes()
+                except OSError:
+                    logger.error(
+                        "Cannot read forensic chain state at %s — reconstructing from records",
+                        state_path,
+                    )
+                    self._reconstruct_chain_state_from_records()
+                    return
+                if self._state_signing_key:
+                    sig_path = self.filesystem_dir / _CHAIN_STATE_SIG_KEY
+                    signature = (
+                        sig_path.read_text(encoding="utf-8").strip() if sig_path.exists() else None
+                    )
+                    if not self._state_sig_is_valid(payload, signature):
+                        logger.critical(
+                            "Forensic chain state signature INVALID or MISSING at %s "
+                            "— possible tampering; reconstructing from records",
+                            state_path,
+                        )
+                        self._reconstruct_chain_state_from_records()
+                        return
+                try:
+                    state = json.loads(payload)
                     self.chain_head = state.get("chain_head", "GENESIS")
                     self.record_count = state.get("record_count", 0)
                     logger.info(
@@ -189,7 +241,7 @@ class ForensicBlackBox(BaseForensicStore):
                         self.record_count,
                         self.chain_head[:16],
                     )
-                except (OSError, json.JSONDecodeError):
+                except json.JSONDecodeError:
                     logger.error(
                         "Corrupt forensic chain state at %s — reconstructing from records",
                         state_path,
@@ -220,12 +272,24 @@ class ForensicBlackBox(BaseForensicStore):
                     Body=payload,
                     ContentType="application/json",
                 )
+                sig = self._sign_state_payload(payload)
+                if sig is not None:
+                    self._s3_call(
+                        self.boto3_client.put_object,
+                        Bucket=self.bucket,
+                        Key=_CHAIN_STATE_SIG_KEY,
+                        Body=sig.encode("utf-8"),
+                        ContentType="text/plain",
+                    )
             except Exception as e:  # noqa: BLE001
                 logger.warning("Failed to persist chain state (S3): %s", e)
             return
         if self.filesystem_dir is not None:
             try:
                 (self.filesystem_dir / _CHAIN_STATE_KEY).write_bytes(payload)
+                sig = self._sign_state_payload(payload)
+                if sig is not None:
+                    (self.filesystem_dir / _CHAIN_STATE_SIG_KEY).write_text(sig, encoding="utf-8")
             except OSError as e:
                 logger.warning("Failed to persist chain state (filesystem): %s", e)
 
@@ -233,6 +297,23 @@ class ForensicBlackBox(BaseForensicStore):
         """SHA-256 hash for chain integrity."""
         return hashlib.sha256(data.encode("utf-8")).hexdigest()
 
+    def _sign_state_payload(self, payload: bytes) -> str | None:
+        """HMAC-SHA256 hex digest of *payload*, or None when no signing key
+        is configured (``ADMINA_FORENSIC_STATE_KEY`` unset)."""
+        if not self._state_signing_key:
+            return None
+        return hmac.new(
+            self._state_signing_key.encode("utf-8"), payload, hashlib.sha256
+        ).hexdigest()
+
+    def _state_sig_is_valid(self, payload: bytes, signature: str | None) -> bool:
+        """True iff a signing key is set and *signature* matches *payload*
+        (constant-time)."""
+        expected = self._sign_state_payload(payload)
+        if expected is None or not signature:
+            return False
+        return hmac.compare_digest(signature, expected)
+
     def record(self, event: dict) -> dict:
         """
         Record an event to the forensic black box.
@@ -439,7 +520,7 @@ class ForensicBlackBox(BaseForensicStore):
             resp = self._s3_call(self.boto3_client.list_objects_v2, **kwargs)
             for item in resp.get("Contents", []) or []:
                 key = item["Key"]
-                if key.endswith(_CHAIN_STATE_KEY):
+                if key.endswith(_CHAIN_STATE_KEY) or key.endswith(_CHAIN_STATE_SIG_KEY):
                     continue
                 obj = self._s3_call(self.boto3_client.get_object, Bucket=self.bucket, Key=key)
                 out.append(json.loads(obj["Body"].read().decode("utf-8")))

{admina_framework-0.10.1 → admina_framework-0.11.0}/admina/domains/governance.py

@@ -40,6 +40,20 @@ logger = logging.getLogger("admina.proxy")
 _MAX_SCAN_DEPTH = 6
 
 
+def normalize_guard_fail_mode(value: str | None) -> str:
+    """Normalize the guard fail-mode setting to ``"open"`` or ``"closed"``.
+
+    ``"open"`` (default): a guard that raises its contract is skipped and
+    recorded as an ``ERROR`` check; the pipeline continues. ``"closed"``:
+    a guard exception yields ``action=BLOCK``. ``None`` and the empty string
+    resolve to ``"open"``. Any other value raises ``ValueError``.
+    """
+    normalized = (value or "open").strip().lower()
+    if normalized not in ("open", "closed"):
+        raise ValueError(f"guard fail mode must be 'open' or 'closed' (got {value!r})")
+    return normalized
+
+
 @dataclass
 class GovernanceResult:
     """Result of running the full governance pipeline on a request."""
@@ -72,6 +86,7 @@ async def run_pipeline(
     pii_enabled: bool = True,
     loop_enabled: bool = True,
     mode: str = "enforce",
+    guard_fail_mode: str = "open",
 ) -> GovernanceResult:
     """Execute the full governance pipeline and return a GovernanceResult.
 
@@ -83,6 +98,11 @@ async def run_pipeline(
     ``False`` for single-shot callers (e.g. GovernedModel) that have no
     cross-call session state; the stage is skipped and ``loop_result`` is
     set to a no-op dict so downstream code is unaffected.
+
+    ``guard_fail_mode`` selects request-side behavior when a governance guard
+    raises: ``"open"`` (default) records an ``ERROR`` check and continues;
+    ``"closed"`` sets ``action=BLOCK`` (risk HIGH) while still recording the
+    ``ERROR`` check.
     """
     start_time = time.perf_counter()
     result = GovernanceResult()
@@ -137,11 +157,16 @@ async def run_pipeline(
                     exc,
                     exc_info=True,
                 )
-                # follow-up: optional fail-closed mode
                 result.checks[f"guard_{guard.name}"] = {
                     "action": "ERROR",
                     "error": str(exc),
                 }
+                if guard_fail_mode == "closed":
+                    # Fail-closed: a guard that breaks its contract blocks the
+                    # request. The ERROR entry above stays as the audit trail.
+                    result.action = GovernanceAction.BLOCK
+                    result.risk_level = RiskLevel.HIGH
+                    break
 
     # 5. Apply governance MODE — observe / dry-run downgrade BLOCK to ALLOW
     # but record what would have happened in `would_action` so dashboards

{admina_framework-0.10.1 → admina_framework-0.11.0}/admina/engines/__init__.py

@@ -373,13 +373,25 @@ def _spacy_regex_pii() -> PIIBridge:
 _PII_ENGINE_FACTORIES["spacy-regex"] = _spacy_regex_pii
 
 
+def _presidio_pii() -> PIIBridge:
+    from admina.engines.presidio import get_presidio_pii_engine
+
+    return get_presidio_pii_engine()
+
+
+_PII_ENGINE_FACTORIES["presidio"] = _presidio_pii
+
+
 def get_pii_engine(name: str | None = None) -> PIIBridge:
     """Get the configured PII engine.
 
-    Resolution order: explicit *name* arg > admina.yaml ``pii_engine`` >
-    ``spacy-regex``. An engine selected by name takes precedence over
-    Rust auto-detection (Rust accelerates only the ``spacy-regex`` path).
+    Resolution order: explicit *name* arg > ``ADMINA_PII_ENGINE`` env >
+    admina.yaml ``pii_engine`` > ``spacy-regex``. An engine selected by name
+    takes precedence over Rust auto-detection (Rust accelerates only the
+    ``spacy-regex`` path).
     """
+    if name is None:
+        name = os.environ.get("ADMINA_PII_ENGINE") or None
     if name is None:
         try:
             from admina.core.config import load_config
@@ -391,9 +403,7 @@ def get_pii_engine(name: str | None = None) -> PIIBridge:
     factory = _PII_ENGINE_FACTORIES.get(name)
     if factory is None:
         raise ValueError(
-            f"Unknown pii_engine {name!r}. Available: "
-            f"{sorted(_PII_ENGINE_FACTORIES)}. "
-            "(A Presidio-backed engine is planned for a later release.)"
+            f"Unknown pii_engine {name!r}. Available: {sorted(_PII_ENGINE_FACTORIES)}."
         )
     return factory()
 

admina_framework-0.11.0/admina/engines/presidio.py

@@ -0,0 +1,181 @@
+# 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 — Microsoft Presidio PII engine (analyzer-only).
+
+Presidio performs *detection*; Admina performs the *masking*, so the output
+format is identical to the spaCy+regex engine (the per-category mask from
+``PII_CATEGORIES``, e.g. ``[EMAIL]`` / ``[PERSON]``). Registered on the
+synchronous ``PIIBridge`` factory path (admina/engines/__init__.py), NOT the
+async ``BasePIIEngine`` plugin ABC.
+
+Languages: EN + IT. Each configured language whose spaCy model is installed is
+analyzed and the results are unioned, so an entity a recognizer only registers
+for one language (e.g. IT_FISCAL_CODE under "it") is still caught. Presidio and
+its models are an optional extra:
+    pip install 'admina-framework[presidio]'
+    python -m spacy download en_core_web_sm it_core_news_sm
+"""
+
+from __future__ import annotations
+
+import logging
+from functools import lru_cache
+from typing import Any
+
+from admina.domains.data_sovereignty.pii import PII_CATEGORIES
+
+logger = logging.getLogger("admina.engines.presidio")
+
+# Presidio entity_type -> Admina PII_CATEGORIES key. Unmapped Presidio types
+# (DATE_TIME, URL, NRP, ...) are intentionally ignored so the category set and
+# false-positive profile stay aligned with the spaCy+regex engine.
+_PRESIDIO_TO_ADMINA: dict[str, str] = {
+    "EMAIL_ADDRESS": "EMAIL",
+    "PHONE_NUMBER": "PHONE",
+    "CREDIT_CARD": "CREDIT_CARD",
+    "IBAN_CODE": "IBAN",
+    "IP_ADDRESS": "IP_ADDRESS",
+    "US_SSN": "SSN",
+    "PERSON": "PERSON",
+    "LOCATION": "GPE",
+    "ORGANIZATION": "ORG",
+    "IT_FISCAL_CODE": "IT_CODICE_FISCALE",
+    "ES_NIF": "ES_DNI_NIE",
+    "ES_NIE": "ES_DNI_NIE",
+}
+
+# Languages Admina configures for Presidio, each mapped to its spaCy model.
+_LANG_MODELS: dict[str, str] = {
+    "en": "en_core_web_sm",
+    "it": "it_core_news_sm",
+}
+
+
+def _build_analyzer(languages: tuple[str, ...]):
+    """Build a Presidio AnalyzerEngine over the given (installed) languages."""
+    from presidio_analyzer import AnalyzerEngine
+    from presidio_analyzer.nlp_engine import NlpEngineProvider
+
+    configuration = {
+        "nlp_engine_name": "spacy",
+        "models": [{"lang_code": lang, "model_name": _LANG_MODELS[lang]} for lang in languages],
+    }
+    nlp_engine = NlpEngineProvider(nlp_configuration=configuration).create_engine()
+    return AnalyzerEngine(nlp_engine=nlp_engine, supported_languages=list(languages))
+
+
+class PresidioPIIEngine:
+    """Synchronous ``PIIBridge`` backed by Microsoft Presidio (analyzer-only)."""
+
+    def __init__(self) -> None:
+        try:
+            import presidio_analyzer  # noqa: F401
+        except ImportError as exc:
+            raise ImportError(
+                "The Presidio PII engine requires the [presidio] extra. Install it with "
+                "`pip install 'admina-framework[presidio]'` and download the models "
+                "`python -m spacy download en_core_web_sm it_core_news_sm`."
+            ) from exc
+
+        import spacy
+
+        languages = tuple(
+            lang for lang, model in _LANG_MODELS.items() if spacy.util.is_package(model)
+        )
+        if not languages:
+            raise ImportError(
+                "Presidio is installed but no supported spaCy model is present. Run "
+                "`python -m spacy download en_core_web_sm it_core_news_sm`."
+            )
+        self.languages: list[str] = list(languages)
+        self._analyzer = _build_analyzer(languages)
+        self.total_redacted: int = 0
+        self.redactions_by_type: dict[str, int] = {}
+        logger.info("[OK] Presidio PII engine ready (languages: %s)", self.languages)
+
+    def redact(self, text: str) -> dict[str, Any]:
+        if not text:
+            return {"redacted_text": text, "entities": [], "categories": [], "count": 0}
+
+        # Union of per-language analyses: a recognizer registered for only one
+        # language is missed by the other pass, so both are run and merged.
+        raw = []
+        for lang in self.languages:
+            raw.extend(self._analyzer.analyze(text=text, language=lang))
+
+        spans: list[tuple[int, int, str, str]] = []
+        for r in raw:
+            category = _PRESIDIO_TO_ADMINA.get(r.entity_type)
+            if category is None:
+                continue
+            cfg = PII_CATEGORIES.get(category, {})
+            if not cfg.get("enabled", False):
+                continue
+            spans.append((r.start, r.end, category, cfg.get("mask", f"[{category}]")))
+
+        # Resolve overlaps deterministically: earliest start first, longest on
+        # ties; greedily drop any span overlapping an already-accepted one. This
+        # also dedupes the same span produced by two language passes.
+        spans.sort(key=lambda s: (s[0], -(s[1] - s[0])))
+        accepted: list[tuple[int, int, str, str]] = []
+        last_end = -1
+        for start, end, category, mask in spans:
+            if start >= last_end:
+                accepted.append((start, end, category, mask))
+                last_end = end
+
+        entities = [
+            {
+                "type": category,
+                "start": start,
+                "end": end,
+                "original_length": end - start,
+                "method": "presidio",
+            }
+            for (start, end, category, mask) in accepted
+        ]
+        redacted = text
+        for start, end, _category, mask in sorted(accepted, key=lambda s: s[0], reverse=True):
+            redacted = redacted[:start] + mask + redacted[end:]
+
+        count = len(entities)
+        if count:
+            self.total_redacted += count
+            for ent in entities:
+                self.redactions_by_type[ent["type"]] = (
+                    self.redactions_by_type.get(ent["type"], 0) + 1
+                )
+        categories = sorted({ent["type"] for ent in entities})
+        return {
+            "redacted_text": redacted,
+            "entities": entities,
+            "categories": categories,
+            "count": count,
+        }
+
+    def get_stats(self) -> dict[str, Any]:
+        return {
+            "total_redacted": self.total_redacted,
+            "redactions_by_type": self.redactions_by_type,
+            "spacy_available": True,
+            "engine": "presidio",
+            "languages": list(self.languages),
+        }
+
+
+@lru_cache(maxsize=1)
+def get_presidio_pii_engine() -> PresidioPIIEngine:
+    """Return a process-wide cached Presidio engine (analyzer construction is costly)."""
+    return PresidioPIIEngine()

{admina_framework-0.10.1 → admina_framework-0.11.0}/admina/integrations/cheshirecat/admina-plugin/admina_governance.py

@@ -117,7 +117,7 @@ def agent_fast_reply(fast_reply: dict, cat) -> dict:
             )
         }
 
-    if result.get("action") == "MODIFY" and result.get("redacted_content"):
+    if result.get("action") == "REDACT" and result.get("redacted_content"):
         # Replace PII in the working memory so the LLM never sees it
         user_msg["text"] = result["redacted_content"]
         cat.working_memory["user_message_json"] = user_msg
@@ -149,7 +149,7 @@ def before_cat_sends_message(message: dict, cat) -> dict:
     result = _validate(text, session_id=session_id)
 
     if result is not None:
-        if result.get("action") == "MODIFY" and result.get("redacted_content"):
+        if result.get("action") == "REDACT" and result.get("redacted_content"):
             message["content"] = result["redacted_content"]
 
         if result.get("action") == "BLOCK":
@@ -201,7 +201,7 @@ def before_cat_recalls_memories(default_query: str, cat) -> str:
         )
         return ""  # empty query = no retrieval
 
-    if result.get("action") == "MODIFY" and result.get("redacted_content"):
+    if result.get("action") == "REDACT" and result.get("redacted_content"):
         return result["redacted_content"]
 
     return default_query

{admina_framework-0.10.1 → admina_framework-0.11.0}/admina/plugins/base.py

@@ -29,6 +29,7 @@ it in ``admina.yaml`` under the ``plugins:`` section.
 from __future__ import annotations
 
 from abc import ABC, abstractmethod
+from collections.abc import AsyncIterator
 from typing import TYPE_CHECKING, Any
 
 if TYPE_CHECKING:
@@ -102,6 +103,29 @@ class BaseModelAdapter(ABC):
             model_name: A model identifier, e.g. ``"llama3"`` or ``"gpt-4o"``.
         """
 
+    async def send_stream(
+        self,
+        prompt: str,
+        context: Any = None,
+        **kwargs: Any,
+    ) -> AsyncIterator[str]:
+        """Stream text deltas from the model.
+
+        Base default: a non-streaming fallback that calls :meth:`send`
+        once and yields the whole text as a single chunk. Adapters backed
+        by SDKs with mature streaming override this to yield incrementally.
+
+        Args:
+            prompt: The text prompt to send.
+            context: Optional conversation context or system prompt.
+            **kwargs: Provider-specific parameters (temperature, model, …).
+
+        Yields:
+            Raw (un-redacted) text deltas. The fallback yields exactly one.
+        """
+        result = await self.send(prompt, context=context, **kwargs)
+        yield result.get("text", "")
+
     @property
     @abstractmethod
     def name(self) -> str:

admina_framework-0.11.0/admina/plugins/builtin/adapters/_streaming.py

@@ -0,0 +1,49 @@
+# 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.
+
+"""Shared sync→async streaming bridge for the built-in adapters.
+
+The provider SDKs (openai, ollama, anthropic) expose *blocking* streaming
+iterators. ``aiter_sync`` builds the iterator and pulls each item off the
+event loop via ``asyncio.to_thread`` so a slow network read never blocks
+other coroutines.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import AsyncIterator, Callable, Iterator
+from typing import Any
+
+__all__ = ["aiter_sync"]
+
+_SENTINEL = object()
+
+
+async def aiter_sync(make_iter: Callable[[], Iterator[Any]]) -> AsyncIterator[Any]:
+    """Bridge a blocking iterator factory to an async iterator.
+
+    Args:
+        make_iter: No-arg callable that (blockingly) creates and returns the
+            provider's streaming iterator.
+
+    Yields:
+        Items from the iterator, each fetched in a worker thread.
+    """
+    iterator = await asyncio.to_thread(make_iter)
+    while True:
+        item = await asyncio.to_thread(next, iterator, _SENTINEL)
+        if item is _SENTINEL:
+            return
+        yield item

{admina_framework-0.10.1 → admina_framework-0.11.0}/admina/plugins/builtin/adapters/anthropic.py

@@ -29,6 +29,7 @@ import time
 from typing import Any
 
 from admina.plugins.base import BaseModelAdapter
+from admina.plugins.builtin.adapters._streaming import aiter_sync
 
 logger = logging.getLogger("admina.plugins.adapters.anthropic")
 
@@ -137,6 +138,41 @@ class AnthropicAdapter(BaseModelAdapter):
             },
         }
 
+    async def send_stream(
+        self,
+        prompt: str,
+        context: Any = None,
+        **kwargs: Any,
+    ) -> Any:
+        """Stream text deltas from the Anthropic Messages API."""
+        client = self._get_client()
+        model = kwargs.pop("model", None) or self._default_model
+        if not model:
+            raise ValueError(
+                "AnthropicAdapter needs a model: pass model=... or set ADMINA_ANTHROPIC_MODEL"
+            )
+        max_tokens = kwargs.pop("max_tokens", self._max_tokens)
+
+        messages = [{"role": "user", "content": prompt}]
+        create_kwargs: dict[str, Any] = {
+            "model": model,
+            "max_tokens": max_tokens,
+            "messages": messages,
+            "stream": True,
+            **kwargs,
+        }
+        if context:
+            create_kwargs["system"] = str(context)
+
+        def _make() -> Any:
+            return client.messages.create(**create_kwargs)
+
+        async for event in aiter_sync(_make):
+            if getattr(event, "type", None) == "content_block_delta":
+                text = getattr(getattr(event, "delta", None), "text", None)
+                if text:
+                    yield text
+
     def supports_model(self, model_name: str) -> bool:
         """Return ``True`` for model names with the ``claude-`` prefix."""
         return model_name.startswith("claude-")