apsimo 1.3.0__py3-none-any.whl

apsimo/gate/models.py

@@ -0,0 +1,64 @@
+"""Gate data models — GatePayload, GateDecision, DispatchResult."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from enum import Enum
+from typing import Optional
+
+from apsimo.gate.communication_policy import CommunicationPolicyContextV1
+from apsimo.intelligence.relationships.trust_tiers import TrustTier
+
+
+class GateResultCode(str, Enum):
+    PASS = "pass"
+    BLOCK_RECIPIENT = "block_recipient"
+    BLOCK_PII = "block_pii"
+    BLOCK_CROSS_CONTEXT = "block_cross_context"
+    BLOCK_TRUST_TIER = "block_trust_tier"
+    BLOCK_INJECTION = "block_injection"
+    BLOCK_REVIEW = "block_review"
+    PENDING_DELAY = "pending_delay"
+
+
+@dataclass
+class GatePayload:
+    """The only view of a response that the gate pipeline sees.
+
+    MUST NOT contain any workspace or reasoning content.
+    Fields are immutable after construction.
+    """
+    response_text: str
+    target_contact_id: str
+    target_gateway: str
+    session_id: str
+    trust_tier: TrustTier
+    mentioned_entities: frozenset  # entities from THIS session's history
+    turn_id: str
+    incoming_message_text: str     # original incoming message (for Layer 5)
+    # Immutable host-owned purpose/disclosure constraints.  Checkers and any
+    # restricted review model see the exact same object whose digest is bound
+    # into the ResponseGuard result.  None preserves the legacy contract.
+    communication_policy: Optional[CommunicationPolicyContextV1] = None
+    created_at: datetime = field(default_factory=lambda: datetime.now(tz=timezone.utc))
+
+
+@dataclass
+class GateDecision:
+    """Result of gate pipeline evaluation."""
+    payload_turn_id: str
+    result_code: GateResultCode
+    blocked: bool
+    blocking_layer: Optional[int]           # 1–7, None if PASS
+    block_reason: Optional[str]             # human-readable, used in rejection
+    flagged_excerpt: Optional[str]          # redacted excerpt for rejection feedback
+    layer_results: dict                     # per-layer detail for audit log
+    evaluated_at: datetime = field(default_factory=lambda: datetime.now(tz=timezone.utc))
+
+
+@dataclass
+class DispatchResult:
+    blocked: bool
+    reason: Optional[str] = None
+    gate_decision: Optional[GateDecision] = None

apsimo/gate/pending_dispatch.py

@@ -0,0 +1,5 @@
+"""PendingDispatch — re-exported from l7_delay for external consumers."""
+
+from apsimo.gate.layers.l7_delay import PendingDispatch, PendingDispatchStore, PendingDispatchContext
+
+__all__ = ["PendingDispatch", "PendingDispatchStore", "PendingDispatchContext"]

apsimo/gate/pipeline.py

@@ -0,0 +1,206 @@
+"""ResponseGate — seven-layer response gate pipeline orchestrator."""
+
+from __future__ import annotations
+
+import hashlib
+import logging
+import time
+from typing import Any, Optional
+
+# Dedicated audit logger for security-relevant gate events (SEC-13-L-03)
+_audit_log = logging.getLogger("colony.gate.audit")
+
+from apsimo.gate.models import GateDecision, GatePayload, GateResultCode, DispatchResult
+from apsimo.gate.layers.l1_recipient import RecipientVerifier
+from apsimo.gate.layers.l2_pii import PIIScanner
+from apsimo.gate.layers.l3_cross_context import CrossContextDetector
+from apsimo.gate.layers.l4_trust_tier import TrustTierChecker
+from apsimo.gate.layers.l5_injection import InjectionDetector
+from apsimo.gate.layers.l6_review import SecondaryReviewer
+from apsimo.gate.layers.l7_delay import SendDelayGate, PendingDispatchStore
+
+logger = logging.getLogger(__name__)
+
+
+class ResponseGate:
+    """Seven-layer response gate pipeline.
+
+    Usage::
+
+        gate = ResponseGate(config, session_store, audit_log)
+        result = await gate.evaluate(payload)
+        if not result.blocked:
+            await dispatch(payload)
+    """
+
+    def __init__(
+        self,
+        config: Any,
+        session_store: Any,
+        audit_log: logging.Logger,
+        secondary_reviewer: Optional[SecondaryReviewer] = None,
+        dispatch_store: Optional[PendingDispatchStore] = None,
+    ) -> None:
+        """Initialize the ResponseGate pipeline.
+
+        Args:
+            config:              Gate configuration object (GateConfig or compatible).
+            session_store:       Session store used by L1 and L3 layers.
+            audit_log:           Logger to record gate decisions for the audit trail.
+            secondary_reviewer:  Optional override for L6; defaults to SecondaryReviewer(config).
+            dispatch_store:      Optional persistent store for L7 delayed dispatches.
+        """
+        self._config = config
+        self._l1 = RecipientVerifier(session_store)
+        self._l2 = PIIScanner(config)
+        self._l3 = CrossContextDetector(session_store, config)
+        self._l4 = TrustTierChecker(config)
+        self._l5 = InjectionDetector(config)
+        self._l6 = secondary_reviewer or SecondaryReviewer(config)
+        self._l7 = SendDelayGate(config, dispatch_store)
+        self._audit = audit_log
+        # Only explicitly enabled review needs a client. Do not report a
+        # completed review when that optional dependency is unavailable.
+        if (getattr(config, "enable_secondary_review", False)
+                and getattr(self._l6, "_llm_client", None) is None):
+            logger.warning(
+                "Gate L6 secondary review is ENABLED but no review LLM is "
+                "configured; L6 reports review_unavailable. Inject a client or disable "
+                "enable_secondary_review.")
+
+    async def evaluate(self, payload: GatePayload) -> GateDecision:
+        """Run all gate layers. Returns decision; does NOT dispatch."""
+        response_hash = hashlib.sha256(payload.response_text.encode()).hexdigest()
+
+        layer_results: dict = {
+            "_session_id": payload.session_id,
+            "_contact_id": payload.target_contact_id,
+            "_sensitivity": self._config.sensitivity,
+            "_overrides_applied": [],
+            "_response_hash": response_hash,
+        }
+
+        # Check per-contact overrides
+        override = self._config.get_contact_override(payload.target_contact_id)
+        bypass_layers: list[int] = []
+        if override:
+            raw_bypass = override.get("bypass_layers", [])
+            layer_results["_overrides_applied"] = [f"contact:{payload.target_contact_id}"]
+            # Layer 1 can NEVER be bypassed
+            bypass_layers = [layer_id for layer_id in raw_bypass if layer_id != 1]
+
+            # Emit structured audit entry for each active bypass (SEC-13-L-03)
+            for layer_id in bypass_layers:
+                _audit_log.warning(
+                    "gate_layer_bypassed",
+                    extra={
+                        "contact_id": payload.target_contact_id,
+                        "layer_id": layer_id,
+                        "override_source": override.get("source", "unknown"),
+                        "message_id": payload.turn_id,
+                        "timestamp": time.time(),
+                    },
+                )
+
+        # Layers 1–5: deterministic, short-circuit on first block
+        deterministic_layers = [
+            (1, self._l1),
+            (2, self._l2),
+            (3, self._l3),
+            (4, self._l4),
+            (5, self._l5),
+        ]
+        for layer_num, checker in deterministic_layers:
+            if layer_num in bypass_layers:
+                # GATE-01: audit log every operator bypass exercise
+                logger.warning(
+                    "GATE_OPERATOR_BYPASS: layer=%d session_id=%s contact_id=%s",
+                    layer_num,
+                    payload.session_id,
+                    payload.target_contact_id,
+                )
+                layer_results[f"layer_{layer_num}"] = {"bypassed": True}
+                continue
+            result = await checker.check(payload)
+            layer_results[f"layer_{layer_num}"] = {
+                "blocked": result.blocked,
+                "code": result.code,
+                "reason": result.reason,
+                "suspicious": result.suspicious,
+            }
+            if result.blocked:
+                decision = GateDecision(
+                    payload_turn_id=payload.turn_id,
+                    result_code=GateResultCode(result.code),
+                    blocked=True,
+                    blocking_layer=layer_num,
+                    block_reason=result.reason,
+                    flagged_excerpt=result.flagged_excerpt,
+                    layer_results=layer_results,
+                )
+                await self._audit.record(decision)
+                return decision
+
+        # Layer 6: explicitly enabled secondary review.
+        l5_result = layer_results.get("layer_5", {})
+        injection_suspicious = l5_result.get("suspicious", False) if isinstance(l5_result, dict) else False
+
+        if self._config.enable_secondary_review and 6 not in bypass_layers:
+            l6_result = await self._l6.review(
+                payload, injection_suspicious=injection_suspicious
+            )
+            layer_results["layer_6"] = {
+                "flagged": l6_result.flagged,
+                "category": l6_result.category,
+                "status": l6_result.status,
+            }
+            if l6_result.flagged:
+                decision = GateDecision(
+                    payload_turn_id=payload.turn_id,
+                    result_code=GateResultCode.BLOCK_REVIEW,
+                    blocked=True,
+                    blocking_layer=6,
+                    block_reason=("secondary_review_flagged" if l6_result.status == "reviewed"
+                                  else "secondary_review_" + l6_result.status),
+                    flagged_excerpt=None,
+                    layer_results=layer_results,
+                )
+                await self._audit.record(decision)
+                return decision
+        else:
+            layer_results["layer_6"] = {"skipped": True}
+
+        # Layer 7: send delay
+        if 7 not in bypass_layers:
+            l7_result = await self._l7.hold(payload)
+            layer_results["layer_7"] = {
+                "cancelled": l7_result.cancelled,
+                "pending_id": l7_result.pending_id,
+            }
+            if l7_result.cancelled:
+                decision = GateDecision(
+                    payload_turn_id=payload.turn_id,
+                    result_code=GateResultCode.PENDING_DELAY,
+                    blocked=True,
+                    blocking_layer=7,
+                    block_reason=l7_result.cancel_reason or "async_cancellation_during_delay",
+                    flagged_excerpt=None,
+                    layer_results=layer_results,
+                )
+                await self._audit.record(decision)
+                return decision
+        else:
+            layer_results["layer_7"] = {"bypassed": True}
+
+        # All layers passed
+        decision = GateDecision(
+            payload_turn_id=payload.turn_id,
+            result_code=GateResultCode.PASS,
+            blocked=False,
+            blocking_layer=None,
+            block_reason=None,
+            flagged_excerpt=None,
+            layer_results=layer_results,
+        )
+        await self._audit.record(decision)
+        return decision

apsimo/gate/rejection.py

@@ -0,0 +1,259 @@
+"""Rejection feedback loop — regenerate once when the ResponseGuard blocks.
+
+Rebuilt ResponseGuard-native: the original loop was an orphan of the retired
+7-layer ResponseGate and depended on subsystems that no longer exist
+(GatePayload sessions, MetaLearner.record_gate_rejection, an escalation
+manager). The dataclasses are kept as the stable contract; the loop now runs
+against ``ResponseGuard.evaluate`` and a caller-supplied ``regenerate`` hook,
+and rejections persist in a small ``RejectionStore`` instead of MetaLearner.
+
+Error contract (mirrors the guard's own):
+  * A guard BLOCK is never overridden by a loop-internal error — if anything
+    inside the loop raises after a block, the result stays blocked (fail
+    CLOSED on the block side).
+  * If the loop errors while the latest guard verdict is an allow, the allow
+    stands (fail OPEN on the allow side) — a loop fault must never silence a
+    reply the guard already cleared.
+"""
+
+from __future__ import annotations
+
+import logging
+import sqlite3
+import threading
+import uuid
+from dataclasses import dataclass, field
+from datetime import datetime, timedelta, timezone
+from typing import Any, Awaitable, Callable, Dict, List, Optional
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class RejectionNotice:
+    """Structured rejection fed back to the LLM for regeneration."""
+    notice_id: str
+    turn_id: str
+    session_id: str
+    contact_display_name: str
+    block_reason_type: str
+    blocking_layer: int
+    redacted_excerpt: Optional[str]
+    trust_tier: str
+    retry_number: int
+    created_at: datetime = field(default_factory=lambda: datetime.now(tz=timezone.utc))
+
+    def to_llm_prompt_fragment(self) -> str:
+        excerpt_line = ""
+        if self.redacted_excerpt:
+            excerpt_line = f'\nFlagged content: "{self.redacted_excerpt}"'
+        return (
+            f"Your response to {self.contact_display_name} was blocked by the "
+            f"response gate.\n\n"
+            f"Reason: {self.block_reason_type}{excerpt_line}\n\n"
+            f"Please generate a new response that does not contain this content. "
+            f"The recipient's trust tier is {self.trust_tier}. Adjust accordingly."
+        )
+
+
+@dataclass
+class GateRejectionEvent:
+    """Learning signal for a gate rejection (persisted in RejectionStore)."""
+    event_id: str = field(default_factory=lambda: str(uuid.uuid4()))
+    session_id: str = ""
+    contact_id: str = ""
+    trust_tier: str = ""
+    blocking_layer: int = 0
+    block_reason: str = ""
+    retry_number: int = 0
+    eventually_succeeded: bool = False
+    turn_id: str = ""
+    timestamp: datetime = field(default_factory=lambda: datetime.now(tz=timezone.utc))
+
+
+@dataclass
+class FeedbackLoopResult:
+    passed: bool
+    payload: Optional[object]     # the (possibly regenerated) response text
+    attempts: int
+
+
+class RejectionStore:
+    """SQLite persistence for gate rejections (replaces the MetaLearner
+    dependency of the retired loop). Also the counting surface for the
+    enforce circuit breaker."""
+
+    def __init__(self, db_path: Optional[str] = None) -> None:
+        self._lock = threading.RLock()
+        self._conn = sqlite3.connect(db_path or ":memory:",
+                                     check_same_thread=False)
+        self._conn.row_factory = sqlite3.Row
+        with self._lock:
+            self._conn.execute(
+                """CREATE TABLE IF NOT EXISTS gate_rejections (
+                    event_id TEXT PRIMARY KEY, session_id TEXT,
+                    contact_id TEXT, trust_tier TEXT, blocking_layer INTEGER,
+                    block_reason TEXT, retry_number INTEGER,
+                    eventually_succeeded INTEGER, turn_id TEXT, ts TEXT
+                )""")
+            self._conn.commit()
+
+    def record(self, event: GateRejectionEvent) -> None:
+        with self._lock:
+            self._conn.execute(
+                """INSERT INTO gate_rejections
+                   (event_id, session_id, contact_id, trust_tier,
+                    blocking_layer, block_reason, retry_number,
+                    eventually_succeeded, turn_id, ts)
+                   VALUES (?,?,?,?,?,?,?,?,?,?)
+                   ON CONFLICT(event_id) DO UPDATE SET
+                    eventually_succeeded=excluded.eventually_succeeded,
+                    retry_number=excluded.retry_number""",
+                (event.event_id, event.session_id, event.contact_id,
+                 event.trust_tier, event.blocking_layer, event.block_reason,
+                 event.retry_number, 1 if event.eventually_succeeded else 0,
+                 event.turn_id, event.timestamp.isoformat()))
+            self._conn.commit()
+
+    def recent(self, limit: int = 50) -> List[Dict[str, Any]]:
+        with self._lock:
+            rows = self._conn.execute(
+                "SELECT * FROM gate_rejections ORDER BY ts DESC LIMIT ?",
+                (int(limit),)).fetchall()
+        return [dict(r) for r in rows]
+
+    def count_since(self, hours: float = 24.0) -> int:
+        cutoff = (datetime.now(tz=timezone.utc)
+                  - timedelta(hours=hours)).isoformat()
+        with self._lock:
+            r = self._conn.execute(
+                "SELECT COUNT(*) FROM gate_rejections WHERE ts >= ?",
+                (cutoff,)).fetchone()
+        return int(r[0]) if r else 0
+
+    def close(self) -> None:
+        try:
+            self._conn.close()
+        except Exception:
+            pass
+
+
+# regenerate(prompt_fragment, blocked_text) -> new text (or None to give up)
+RegenerateFn = Callable[[str, str], Awaitable[Optional[str]]]
+
+
+class RejectionFeedbackLoop:
+    """One regenerate-and-re-check cycle after a ResponseGuard block.
+
+    Usage::
+
+        loop = RejectionFeedbackLoop(guard, store=store, regenerate=regen)
+        result = await loop.run(text, initial_result=guard_result,
+                                target_contact_id=..., ...)
+
+    ``regenerate`` is a deployment-supplied async hook; without one the loop
+    cannot revise, so a block simply stands.
+    """
+
+    def __init__(self, guard: Any, store: Optional[RejectionStore] = None,
+                 regenerate: Optional[RegenerateFn] = None,
+                 max_retries: int = 1) -> None:
+        self._guard = guard
+        self._store = store
+        self._regenerate = regenerate
+        self._max_retries = max(0, int(max_retries))
+
+    def _record(self, event: Optional[GateRejectionEvent]) -> None:
+        if event is None or self._store is None:
+            return
+        try:
+            self._store.record(event)
+        except Exception:
+            logger.debug("rejection store record failed", exc_info=True)
+
+    @staticmethod
+    def _block_reason(result: Any) -> tuple[str, Optional[str]]:
+        for f in getattr(result, "findings", None) or []:
+            if getattr(f, "severity", "") == "block":
+                return (getattr(f, "check", "blocked"),
+                        getattr(f, "excerpt", None))
+        return ("blocked", None)
+
+    async def run(self, response_text: str, *,
+                  initial_result: Any = None,
+                  contact_display_name: str = "the recipient",
+                  **eval_kwargs: Any) -> FeedbackLoopResult:
+        """Evaluate (or take ``initial_result``), regenerate on block, re-check.
+
+        ``eval_kwargs`` are forwarded verbatim to ``guard.evaluate`` so the
+        re-check runs under exactly the same identity/context as the original.
+        """
+        text = response_text
+        result = initial_result
+        attempts = 0
+        event: Optional[GateRejectionEvent] = None
+        # Tracks the LAST KNOWN guard verdict so the exception handler can
+        # honor the error contract (closed on block, open on allow).
+        blocked = bool(getattr(result, "blocked", True))
+        try:
+            if result is None:
+                result = await self._guard.evaluate(
+                    response_text=text, **eval_kwargs)
+                attempts = 1
+                blocked = result.blocked
+
+            for retry in range(self._max_retries + 1):
+                if not result.blocked:
+                    if event is not None:
+                        event.eventually_succeeded = True
+                        self._record(event)
+                    return FeedbackLoopResult(passed=True, payload=text,
+                                              attempts=max(attempts, 1))
+
+                reason, excerpt = self._block_reason(result)
+                event = GateRejectionEvent(
+                    session_id=str(eval_kwargs.get("session_id", "")),
+                    contact_id=str(eval_kwargs.get("target_contact_id", "")),
+                    trust_tier=str(eval_kwargs.get("trust_tier", "")),
+                    blocking_layer=0,
+                    block_reason=reason,
+                    retry_number=retry,
+                    turn_id=str(eval_kwargs.get("turn_id", "")),
+                )
+                self._record(event)
+
+                if retry >= self._max_retries or self._regenerate is None:
+                    break
+
+                notice = RejectionNotice(
+                    notice_id=str(uuid.uuid4()),
+                    turn_id=str(eval_kwargs.get("turn_id", "")),
+                    session_id=str(eval_kwargs.get("session_id", "")),
+                    contact_display_name=contact_display_name,
+                    block_reason_type=reason,
+                    blocking_layer=0,
+                    redacted_excerpt=excerpt,
+                    trust_tier=str(eval_kwargs.get("trust_tier", "")),
+                    retry_number=retry + 1,
+                )
+                new_text = await self._regenerate(
+                    notice.to_llm_prompt_fragment(), text)
+                if not new_text or not str(new_text).strip():
+                    break
+                text = str(new_text).strip()
+                result = await self._guard.evaluate(
+                    response_text=text, **eval_kwargs)
+                attempts += 1
+                blocked = result.blocked
+
+            return FeedbackLoopResult(passed=False, payload=None,
+                                      attempts=max(attempts, 1))
+        except Exception:
+            logger.warning("RejectionFeedbackLoop internal error", exc_info=True)
+            if not blocked:
+                # allow verdict stands: fail open on the allow side
+                return FeedbackLoopResult(passed=True, payload=text,
+                                          attempts=max(attempts, 1))
+            # a guard BLOCK is never overridden by a loop error
+            return FeedbackLoopResult(passed=False, payload=None,
+                                      attempts=max(attempts, 1))