apsimo 1.3.0__py3-none-any.whl

apsimo/gate/rulesets/injection_v1.yaml

@@ -0,0 +1,51 @@
+version: "1.0"
+patterns:
+  - id: "role_override_1"
+    pattern: "(ignore|disregard|forget)\\s+(all\\s+)?(previous|prior|above)\\s+(instructions|directives|context)"
+    category: "role_override"
+    severity: "block"
+
+  - id: "role_override_2"
+    pattern: "you\\s+are\\s+(now|actually|secretly|really)\\s+[A-Z]"
+    category: "role_override"
+    severity: "block"
+
+  - id: "role_override_3"
+    pattern: "(act|behave|respond)\\s+as\\s+(if\\s+)?(you\\s+are\\s+|a\\s+)?(DAN|GPT|jailbreak|unrestricted)"
+    category: "role_override"
+    severity: "block"
+
+  - id: "system_prompt_1"
+    pattern: "(system\\s+prompt|system\\s+message|instructions)\\s*:\\s*"
+    category: "system_prompt"
+    severity: "block"
+
+  - id: "system_tag_1"
+    pattern: "<\\s*(system|admin|root|operator)\\s*>"
+    category: "system_tag"
+    severity: "block"
+
+  - id: "redirect_1"
+    pattern: "send\\s+(this|it|the\\s+following)\\s+to\\s+\\S+@\\S+"
+    category: "redirect"
+    severity: "block"
+
+  - id: "redirect_2"
+    pattern: "forward\\s+(this\\s+message\\s+)?to\\s+"
+    category: "redirect"
+    severity: "block"
+
+  - id: "redirect_3"
+    pattern: "reply\\s+to\\s+\\S+\\s+instead"
+    category: "redirect"
+    severity: "block"
+
+  - id: "extraction_1"
+    pattern: "(print|show|display|output|repeat|reveal)\\s+(your\\s+)?(system\\s+prompt|instructions|memory|context)"
+    category: "extraction"
+    severity: "block"
+
+  - id: "extraction_2"
+    pattern: "what\\s+(are|were)\\s+your\\s+(original\\s+)?instructions"
+    category: "extraction"
+    severity: "suspicious"

apsimo/gate/surface_policy.py

@@ -0,0 +1,189 @@
+"""Explicit, deployment-neutral ResponseGuard surface policy.
+
+The policy separates asynchronous text/artifact delivery from real-time speech.
+It deliberately does not infer a surface from a gateway name: a text adapter
+cannot bypass the guard by calling itself ``voice``, and an embedding deployment
+does not need to maintain an ever-growing gateway exclusion list.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+import hashlib
+import json
+from typing import Literal, Optional, cast
+
+
+ResponseGuardSurfaceName = Literal[
+    "api_text",
+    "artifact",
+    "cold_text",
+    "cron_text",
+    "meeting_speech",
+    "meeting_text",
+    "proactive_text",
+    "realtime_voice",
+    "text_chat",
+    "text_message",
+]
+
+
+POLICY_ID = "response-guard-surface-policy-v1"
+GUARDED_TEXT_SURFACES = frozenset({
+    "api_text",
+    "cold_text",
+    "cron_text",
+    "meeting_text",
+    "proactive_text",
+    "text_chat",
+    "text_message",
+})
+GUARDED_ARTIFACT_SURFACES = frozenset({"artifact"})
+EXCLUDED_SPEECH_SURFACES = frozenset({
+    "meeting_speech",
+    "realtime_voice",
+})
+ALL_SURFACES = (
+    GUARDED_TEXT_SURFACES
+    | GUARDED_ARTIFACT_SURFACES
+    | EXCLUDED_SPEECH_SURFACES
+)
+
+
+def _canonical(value: object) -> str:
+    return json.dumps(
+        value,
+        ensure_ascii=True,
+        separators=(",", ":"),
+        sort_keys=True,
+    )
+
+
+_POLICY_PAYLOAD = {
+    "schema": "ResponseGuardSurfacePolicyV1",
+    "version": 1,
+    "policy_id": POLICY_ID,
+    "guarded_text_surfaces": sorted(GUARDED_TEXT_SURFACES),
+    "guarded_artifact_surfaces": sorted(GUARDED_ARTIFACT_SURFACES),
+    "excluded_speech_surfaces": sorted(EXCLUDED_SPEECH_SURFACES),
+    "mode_rule": "caller_may_strengthen_never_weaken",
+}
+POLICY_DIGEST = hashlib.sha256(
+    _canonical(_POLICY_PAYLOAD).encode("utf-8")
+).hexdigest()
+
+
+@dataclass(frozen=True)
+class SurfacePolicyDecisionV1:
+    surface: str
+    family: str
+    disposition: str
+    configured_mode: str
+    requested_mode: str
+    effective_mode: str
+    failure_behavior: str
+    policy_id: str = POLICY_ID
+    policy_digest: str = POLICY_DIGEST
+    schema: str = "ResponseGuardSurfaceDecisionV1"
+    version: int = 1
+
+    @property
+    def guarded(self) -> bool:
+        return self.disposition == "guarded"
+
+    def public(self) -> dict:
+        return {
+            "schema": self.schema,
+            "version": self.version,
+            "policy_id": self.policy_id,
+            "policy_digest": self.policy_digest,
+            "surface": self.surface,
+            "family": self.family,
+            "disposition": self.disposition,
+            "configured_mode": self.configured_mode,
+            "requested_mode": self.requested_mode,
+            "effective_mode": self.effective_mode,
+            "failure_behavior": self.failure_behavior,
+        }
+
+
+class ResponseGuardSurfacePolicyV1:
+    """Resolve one exact outbound surface without gateway-name inference."""
+
+    policy_id = POLICY_ID
+    policy_digest = POLICY_DIGEST
+
+    @staticmethod
+    def validate_surface(surface: object) -> ResponseGuardSurfaceName:
+        if not isinstance(surface, str) or surface not in ALL_SURFACES:
+            raise ValueError("unsupported ResponseGuard surface")
+        return cast(ResponseGuardSurfaceName, surface)
+
+    @staticmethod
+    def _mode(value: object, *, field: str) -> str:
+        text = str(getattr(value, "value", value) or "").strip().lower()
+        if text not in {"shadow", "enforce"}:
+            raise ValueError(f"{field} must be shadow or enforce")
+        return text
+
+    def resolve(
+        self,
+        surface: object,
+        *,
+        configured_mode: object,
+        requested_mode: Optional[object] = None,
+    ) -> SurfacePolicyDecisionV1:
+        exact = self.validate_surface(surface)
+        configured = self._mode(configured_mode, field="configured_mode")
+        requested = (
+            self._mode(requested_mode, field="requested_mode")
+            if requested_mode is not None
+            else configured
+        )
+        if exact in EXCLUDED_SPEECH_SURFACES:
+            return SurfacePolicyDecisionV1(
+                surface=exact,
+                family="speech",
+                disposition="excluded",
+                configured_mode=configured,
+                requested_mode=requested,
+                effective_mode="excluded",
+                failure_behavior="allow",
+            )
+        family = "artifact" if exact in GUARDED_ARTIFACT_SURFACES else "text"
+        # A request can explicitly graduate a shadow deployment to enforce for
+        # this call, but can never downgrade a configured enforce deployment.
+        effective = (
+            "enforce"
+            if "enforce" in {configured, requested}
+            else "shadow"
+        )
+        return SurfacePolicyDecisionV1(
+            surface=exact,
+            family=family,
+            disposition="guarded",
+            configured_mode=configured,
+            requested_mode=requested,
+            effective_mode=effective,
+            failure_behavior="block" if effective == "enforce" else "allow",
+        )
+
+    def public(self) -> dict:
+        # Return a detached projection: callers cannot mutate the canonical
+        # list objects while the regression-locked digest stays unchanged.
+        projection = json.loads(_canonical(_POLICY_PAYLOAD))
+        projection["policy_digest"] = self.policy_digest
+        return projection
+
+
+__all__ = [
+    "ALL_SURFACES",
+    "EXCLUDED_SPEECH_SURFACES",
+    "GUARDED_ARTIFACT_SURFACES",
+    "GUARDED_TEXT_SURFACES",
+    "POLICY_DIGEST",
+    "POLICY_ID",
+    "ResponseGuardSurfaceName",
+    "ResponseGuardSurfacePolicyV1",
+    "SurfacePolicyDecisionV1",
+]

apsimo/gate/taint.py

@@ -0,0 +1,226 @@
+"""Injection-taint registry (L3.1) — TTL'd record of live level-2 injections.
+
+When the leveled tom2 wiring renders an epistemic line ("SUBJECT hasn't
+heard X") into a conversation's context, it registers a TAINT here: for the
+next COLONY_TOM2_TAINT_TTL_SECS (default 900s) the outbound egress net
+(gate/layers/tom2_epistemic.py) knows that a silent prior about SUBJECT is
+sitting in the model's context window and can hard-block a reply that
+voices it.
+
+REFS-NOT-CONTENT (same pin as Tom2Store / the exposure ledger): a taint row
+carries an opaque conversation key, an opaque subject contact id, an opaque
+fact ref, an inference kind, and the subject's normalized DISPLAY NAMES —
+which are, by the M1 mutual-knowledge gate, names the reader already knows.
+Fact TEXT never enters this table; a leak of the registry reveals that a
+prior about someone was injected somewhere, never what it said.
+
+Hot-path economics: ``any_active()`` is the guard's first question every
+turn, so it is answered from an in-memory latest-expiry watermark (a clock
+comparison, no DB hit) whenever no taint could possibly be live. The
+watermark is loaded from SQLite at startup, so taints survive a restart.
+
+Fail-closed direction: a taint is PROTECTION, so errors lean toward keeping
+it — malformed TTL config reads as the default, and expiry is judged
+against wall-clock timestamps written at register time.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import re
+import sqlite3
+import threading
+import time
+import uuid
+from typing import Any, Dict, List, Optional
+
+from apsimo.gate.context_provenance import normalize_entity
+from apsimo.tom.tom2 import INFERENCE_KINDS, _validate_ref
+
+logger = logging.getLogger(__name__)
+
+DEFAULT_TTL_SECS = 900.0
+
+#: Opaque conversation keys / contact ids: compact, no whitespace — prose is
+#: refused so message or fact text cannot be smuggled through these fields.
+_KEY_RE = re.compile(r"^[A-Za-z0-9_.:+@-]{1,128}$")
+
+_MAX_NAMES = 8
+_MAX_NAME_LEN = 80
+
+
+def taint_ttl_secs() -> float:
+    """COLONY_TOM2_TAINT_TTL_SECS (default 900): how long a registered
+    injection stays hot for the egress net. Malformed values read as the
+    default (a taint is protection; misconfiguration must not shorten it);
+    values <= 0 clamp to the default for the same reason."""
+    raw = os.environ.get("COLONY_TOM2_TAINT_TTL_SECS")
+    if raw is None or not str(raw).strip():
+        return DEFAULT_TTL_SECS
+    try:
+        v = float(str(raw).strip())
+    except (TypeError, ValueError):
+        logger.warning("COLONY_TOM2_TAINT_TTL_SECS=%r is malformed — using "
+                       "the default %ss", raw, DEFAULT_TTL_SECS)
+        return DEFAULT_TTL_SECS
+    return v if v > 0 else DEFAULT_TTL_SECS
+
+
+def _validate_key(value: Any, what: str) -> str:
+    value = str(value or "").strip()
+    if not _KEY_RE.match(value):
+        raise ValueError(f"taint {what} {value[:40]!r} is not an opaque id "
+                         "(refs-not-content invariant)")
+    return value
+
+
+def _clean_names(names: Any) -> List[str]:
+    """Normalize subject display names (normalize_entity), dedupe, cap."""
+    out: List[str] = []
+    seen = set()
+    for raw in list(names or [])[: _MAX_NAMES * 2]:
+        n = normalize_entity(str(raw or ""))[:_MAX_NAME_LEN]
+        if len(n) >= 2 and n not in seen:
+            seen.add(n)
+            out.append(n)
+        if len(out) >= _MAX_NAMES:
+            break
+    return out
+
+
+class TaintRegistry:
+    """SQLite-backed TTL registry of live level-2 injections."""
+
+    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 tom2_taints (
+                    id                 TEXT PRIMARY KEY,
+                    conversation_key   TEXT NOT NULL,
+                    subject_contact_id TEXT NOT NULL,
+                    subject_names      TEXT NOT NULL DEFAULT '[]',
+                    fact_ref           TEXT NOT NULL,
+                    kind               TEXT NOT NULL,
+                    created_at         REAL NOT NULL,
+                    expires_at         REAL NOT NULL
+                )""")
+            self._conn.execute(
+                "CREATE INDEX IF NOT EXISTS idx_tom2_taints_conv "
+                "ON tom2_taints(conversation_key, expires_at)")
+            self._conn.commit()
+            # In-memory watermark: the hot path answers "no taints" from a
+            # clock comparison. Persisted taints re-arm it across restarts.
+            row = self._conn.execute(
+                "SELECT MAX(expires_at) m FROM tom2_taints").fetchone()
+            self._latest_expiry: float = float(row["m"] or 0.0)
+
+    # -- writes -------------------------------------------------------------
+    def register(self, conversation_key: str, subject_contact_id: str,
+                 subject_names: Optional[List[str]] = None,
+                 fact_ref: str = "", kind: str = "unaware_of",
+                 ttl_seconds: Optional[float] = None) -> Dict[str, Any]:
+        """Record one live injection. Raises on any privacy-pin violation
+        (prose in an opaque field, unknown kind) — never best-effort."""
+        if kind not in INFERENCE_KINDS:
+            raise ValueError(f"unknown taint kind {kind!r}")
+        ttl = float(ttl_seconds) if ttl_seconds is not None\
+            else taint_ttl_secs()
+        if ttl <= 0:
+            ttl = taint_ttl_secs()
+        now = time.time()
+        row = {
+            "id": str(uuid.uuid4()),
+            "conversation_key": _validate_key(conversation_key,
+                                              "conversation key"),
+            "subject_contact_id": _validate_key(subject_contact_id,
+                                                "subject id"),
+            "subject_names": _clean_names(subject_names),
+            "fact_ref": _validate_ref(fact_ref),
+            "kind": kind,
+            "created_at": now,
+            "expires_at": now + ttl,
+        }
+        with self._lock:
+            self._conn.execute(
+                "INSERT INTO tom2_taints (id, conversation_key, "
+                "subject_contact_id, subject_names, fact_ref, kind, "
+                "created_at, expires_at) VALUES (?,?,?,?,?,?,?,?)",
+                (row["id"], row["conversation_key"],
+                 row["subject_contact_id"], json.dumps(row["subject_names"]),
+                 row["fact_ref"], row["kind"], row["created_at"],
+                 row["expires_at"]))
+            self._conn.commit()
+            self._latest_expiry = max(self._latest_expiry, row["expires_at"])
+        return row
+
+    def purge_expired(self) -> int:
+        """Drop expired rows (housekeeping; reads already exclude them)."""
+        with self._lock:
+            cur = self._conn.execute(
+                "DELETE FROM tom2_taints WHERE expires_at <= ?",
+                (time.time(),))
+            self._conn.commit()
+        return cur.rowcount
+
+    # -- reads --------------------------------------------------------------
+    @staticmethod
+    def _to_dict(row: Any) -> Dict[str, Any]:
+        d = dict(row)
+        try:
+            d["subject_names"] = json.loads(d.get("subject_names") or "[]")
+        except Exception:
+            d["subject_names"] = []
+        return d
+
+    def any_active(self) -> bool:
+        """Is ANY taint live right now? Answered from the in-memory
+        watermark — zero DB cost on the (overwhelmingly common) no-taint
+        turn, which is what keeps the egress check inert for free."""
+        with self._lock:
+            return time.time() < self._latest_expiry
+
+    def active_for(self, conversation_key: str) -> List[Dict[str, Any]]:
+        """Live taints registered against THIS conversation."""
+        if not self.any_active():
+            return []
+        with self._lock:
+            rows = self._conn.execute(
+                "SELECT * FROM tom2_taints WHERE conversation_key = ? "
+                "AND expires_at > ? ORDER BY expires_at DESC",
+                (str(conversation_key or ""), time.time())).fetchall()
+        return [self._to_dict(r) for r in rows]
+
+    def all_active(self) -> List[Dict[str, Any]]:
+        """Every live taint, any conversation — the egress net checks the
+        reply against ALL of them (a prior injected in one conversation must
+        not be voiced anywhere while it is hot)."""
+        if not self.any_active():
+            return []
+        with self._lock:
+            rows = self._conn.execute(
+                "SELECT * FROM tom2_taints WHERE expires_at > ? "
+                "ORDER BY expires_at DESC", (time.time(),)).fetchall()
+        return [self._to_dict(r) for r in rows]
+
+    def counts(self) -> Dict[str, Any]:
+        """Aggregate observability (numbers only)."""
+        now = time.time()
+        with self._lock:
+            total = self._conn.execute(
+                "SELECT COUNT(*) n FROM tom2_taints").fetchone()["n"]
+            active = self._conn.execute(
+                "SELECT COUNT(*) n FROM tom2_taints WHERE expires_at > ?",
+                (now,)).fetchone()["n"]
+        return {"rows": int(total), "active": int(active)}
+
+    def close(self) -> None:
+        try:
+            self._conn.close()
+        except Exception:
+            pass

apsimo/genesis.json

@@ -0,0 +1,9 @@
+{
+  "colony_id": "31a441ea-0191-4bfb-a87f-98a6703a6db3",
+  "public_key_ed25519": "341065fd6cd26ca501c5786ed1517eedc448fec60aeaea8d047d07bf1a9cc351",
+  "alias": "genesis",
+  "genesis_version": 1,
+  "signed_at": "2026-04-20T17:04:26.242399+00:00",
+  "description": "The original Colony — trust anchor for the network",
+  "signature": "f695be354a0f8534ea178c1c8cd01d335f0cfb6ce72ed4d5db2a5b5f812e9546ccde8edd17683c8b5b55bf263d29a9b77bc8ac7b34b88642f4278022ec7da803"
+}

apsimo/goals/__init__.py

@@ -0,0 +1,100 @@
+"""Legacy goal records and optional planner compatibility.
+
+New execution belongs to native runtime tasks and canonical commitments.
+The default GoalEngine stores accepted goals without an execution backend.
+Planner exports remain for existing readers and stored-goal migrations;
+their presence does not establish live execution.
+"""
+
+from importlib import import_module
+
+from .config import GoalEngineConfig
+from .models import (
+    Goal,
+    GoalDAG,
+    GoalOutcome,
+    GoalPriority,
+    GoalSource,
+    GoalStatus,
+    GoalSummary,
+    GoalTransitionRecord,
+    Subtask,
+    SubtaskStatus,
+)
+from .store import GoalNotFoundError, GoalStore
+
+# A reader importing goals.models/store must not load the optional planner.
+# Preserve public exports for explicitly configured legacy callers, including
+# class identity and pickle module names, without constructing another facade.
+_PLANNER_EXPORTS = {
+    name: module for module, names in (
+        ('engine', ('GoalEngine',)),
+        ('decomposer', ('DecompositionTemplate', 'GoalDecomposer', 'SubtaskSpec')),
+        ('inference', ('ConversationMessage', 'GoalDeduplicator', 'GoalInferencePipeline',
+                       'GoalSimilarity', 'InferenceCandidate', 'IntentSignal')),
+        ('priority', ('GoalProgressTracker', 'GoalPriorityScorer', 'PriorityScore',
+                      'UserPreferenceProfile')),
+        ('queue_bridge', ('GoalQueueBridge', 'InMemoryQueueBackend')),
+        ('replan', ('FailureAnalysis', 'FailureClass', 'ReplanEngine', 'ReplanResult',
+                    'ReplanStrategy')),
+    ) for name in names
+}
+
+
+def __getattr__(name):
+    module = _PLANNER_EXPORTS.get(name)
+    if module is None:
+        raise AttributeError(f'module {__name__!r} has no attribute {name!r}')
+    value = getattr(import_module('.' + module, __name__), name)
+    globals()[name] = value
+    return value
+
+
+def __dir__():
+    return sorted(set(globals()) | set(__all__))
+
+__all__ = [
+    # Config
+    "GoalEngineConfig",
+    # Engine
+    "GoalEngine",
+    # Models
+    "Goal",
+    "GoalDAG",
+    "GoalOutcome",
+    "GoalPriority",
+    "GoalSource",
+    "GoalStatus",
+    "GoalSummary",
+    "GoalTransitionRecord",
+    "Subtask",
+    "SubtaskStatus",
+    # Inference
+    "ConversationMessage",
+    "GoalDeduplicator",
+    "GoalInferencePipeline",
+    "GoalSimilarity",
+    "InferenceCandidate",
+    "IntentSignal",
+    # Decomposer
+    "DecompositionTemplate",
+    "GoalDecomposer",
+    "SubtaskSpec",
+    # Priority / Progress
+    "GoalProgressTracker",
+    "GoalPriorityScorer",
+    "PriorityScore",
+    "UserPreferenceProfile",
+    # Queue Bridge
+    "GoalQueueBridge",
+    "InMemoryQueueBackend",
+    # Replan
+    "FailureAnalysis",
+    "FailureClass",
+    "ReplanEngine",
+    "ReplanResult",
+    "ReplanStrategy",
+    # Store
+    "GoalNotFoundError",
+    "GoalStore",
+]

apsimo/goals/config.py

@@ -0,0 +1,38 @@
+"""Configuration for the Colony Goal Engine."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Optional
+
+
+@dataclass
+class GoalEngineConfig:
+    """Configuration for the Colony Goal Engine.
+
+    Attributes:
+        enabled:                Whether the goal engine is active.
+        auto_accept_threshold:  Confidence threshold for auto-accepting inferred goals (0.0–1.0).
+        max_replans:            Maximum replan attempts per goal before escalating to user.
+        max_subtasks:           Maximum subtasks per goal DAG.
+        max_depth:              Maximum DAG depth.
+        max_blocked_hours:      Hours before a blocked goal is escalated to the user.
+        inference_enabled:      Whether to run goal inference on conversation messages.
+        inference_lm_threshold: Confidence below which LLM inference pass is triggered.
+        proposal_min_interval:  Minimum seconds between goal proposals to avoid noise.
+        retention_days:         Days to retain completed/abandoned goals.
+        telemetry_enabled:      Whether to emit goal telemetry to the MetaLearner.
+        db_path:                Path to SQLite database (defaults to in-memory for tests).
+    """
+    enabled: bool = True
+    auto_accept_threshold: float = 0.85
+    max_replans: int = 5
+    max_subtasks: int = 50
+    max_depth: int = 5
+    max_blocked_hours: float = 24.0
+    inference_enabled: bool = True
+    inference_lm_threshold: float = 0.70
+    proposal_min_interval: float = 300.0   # 5 minutes
+    retention_days: int = 90
+    telemetry_enabled: bool = True
+    db_path: Optional[str] = None          # None → in-memory SQLite