apsimo 1.3.0__py3-none-any.whl

apsimo/feeds/template.py

@@ -0,0 +1,202 @@
+"""Render distill / digest / discovery agent prompts from a FeedSpec.
+
+The structure is distilled from a battle-tested single-feed deployment:
+actionable framing ("what changes because of this"), hard link requirements,
+tiered promotion rules for human-shared links, a privacy block, and a
+learning-loop hook that records source promotions so the registry evolves.
+"""
+
+from __future__ import annotations
+
+from .spec import FeedSpec
+
+
+def _archive_hint(spec: FeedSpec, suffix: str = "") -> str:
+    tail = f"-{suffix}" if suffix else "-HHMM"
+    return f"{spec.briefs_dir}/YYYY-MM-DD{tail}.md"
+
+
+def _privacy_block(spec: FeedSpec) -> str:
+    lines = ["PRIVACY (hard rules for anything you post):"]
+    for item in spec.privacy.get("forbidden", []):
+        lines.append(f"- Never mention {item}.")
+    aliases = spec.privacy.get("aliases") or []
+    if aliases:
+        lines.append("- Reference hardware/platforms by public product name only "
+                     f"({', '.join(aliases)}).")
+    note = spec.privacy.get("note")
+    if note:
+        lines.append(f"- {note}")
+    return "\n".join(lines)
+
+
+def _registry_block(spec: FeedSpec) -> str:
+    if not spec.registry:
+        return ""
+    by_tier: dict[str, list[str]] = {"P0": [], "P1": [], "P2": []}
+    for e in spec.registry:
+        label = e.get("handle") or e.get("name")
+        cat = e.get("category", "")
+        by_tier.setdefault(e.get("weight", "P1"), []).append(
+            f"{label}" + (f" ({cat})" if cat else ""))
+    lines = ["SOURCE REGISTRY (tiered; used by the promotion rules):"]
+    tier_meaning = {"P0": "always include, even a bare link",
+                    "P1": "include; promote to P0 when a curator flags it",
+                    "P2": "background only"}
+    for tier in ("P0", "P1", "P2"):
+        if by_tier.get(tier):
+            lines.append(f"- {tier} ({tier_meaning[tier]}): " + ", ".join(by_tier[tier]))
+    return "\n".join(lines)
+
+
+def _promotion_block(spec: FeedSpec) -> str:
+    return """PROMOTION RULES for human-shared links (apply in order, first match wins):
+1. Link's domain/author matches a P0 source AND content is a new SOTA / reproducible recipe / breakthrough -> P0
+2. Link's domain/author matches a P0 source -> P0
+3. Link's domain/author matches a P1 source AND a curator flagged it important/!!!/P0 -> P0
+4. Link's domain/author matches a P1 source -> P1
+5. Link's domain/author matches a P2 source -> P2
+6. A curator flagged it important/!!! -> P0
+7. A curator provided any context note -> P1
+8. Bare link from an unknown source -> P2
+
+Treat every human message as a link share and PRESERVE their context notes verbatim:
+text before a URL is their note about it; text after is an annotation (e.g. "and the
+first reply" means follow that reply too). Never summarize their notes away - they are
+first-class signal."""
+
+
+def _community_block(spec: FeedSpec) -> str:
+    read_back = spec.destination.get("read_back", "")
+    if spec.audience != "group" or not read_back:
+        return ""
+    return f"""Read the destination group's recent messages from human participants since the last
+brief. Use: {read_back}
+
+{_promotion_block(spec)}
+
+COMMUNITY INPUT section: every link humans posted in this window, in order, each with
+its priority and a one-line framing answering "{spec.brief['framing']}".
+
+ABSOLUTE RULES for the group:
+- The group is a one-way broadcast channel for you: read for intel, post briefs, nothing else.
+- Do NOT react to, reply to, or engage with any message in the group, ever.
+- If a participant asks you a direct question there, do not answer it in the group."""
+
+
+def _delivery_block(spec: FeedSpec, what: str = "brief") -> str:
+    kind = spec.destination.get("kind")
+    if kind == "command":
+        return (f"Post the {what} to its destination by piping it to:\n"
+                f"  {spec.destination['send_command']}")
+    if kind == "deliver":
+        return (f"Your final response IS the {what}; the scheduler delivers it automatically. "
+                "Do not send it yourself with any messaging tool.")
+    return (f"Do NOT post the {what} anywhere; this feed is archive-only. "
+            "Your final response should be the brief text.")
+
+
+def _context_files_block(spec: FeedSpec) -> str:
+    files = spec.brief.get("context_files") or []
+    if not files:
+        return ""
+    lines = ["Also read these context files if they exist and fold relevant movement into the brief:"]
+    for f in files:
+        lines.append(f"- {f.get('label', 'context')}: {f['path']}")
+    return "\n".join(lines)
+
+
+def _learning_block(spec: FeedSpec) -> str:
+    if not spec.learning_loop:
+        return ""
+    return f"""LEARNING LOOP HOOK: after archiving, whenever you promoted a link from an unknown
+source to P0/P1 on content weight alone, append one line to {spec.deltas_log}:
+  TIMESTAMP  new_source=domain-or-handle (reason)  promoted_to=P1  link=...
+This is how the source registry evolves. Skip the log when nothing was promoted."""
+
+
+def render_distill(spec: FeedSpec) -> str:
+    parts = [
+        f"You are the {spec.title} distillation agent.",
+        f"TOPIC CHARTER: {spec.topic}",
+        f"""Your job each run:
+1. Read the feed queue at {spec.queue_path}
+2. Distill the top items into a brief. Plain text, no markdown. Structure:
+   - Header line with feed title and date/time (local timezone)
+   - HIGH PRIORITY section (P0 and P1 items), each with: title, 1-2 sentence summary,
+     a "why it matters" line, benchmark numbers if any, and SOURCE LINK
+   - STANDARD section (P2 items): one line each with link, cap at the top
+     {spec.brief['standard_cap']} and drop the rest silently
+3. ALWAYS include a source link for every item so readers can click through.
+
+OUTPUT FRAMING: for every HIGH PRIORITY item the "why it matters" line MUST answer:
+  "{spec.brief['framing']}"
+Not "what does this article say" - the framing has to be actionable.""",
+    ]
+    for block in (_context_files_block(spec), _community_block(spec),
+                  _privacy_block(spec), _registry_block(spec)):
+        if block:
+            parts.append(block)
+    parts.append(_delivery_block(spec))
+    parts.append(f"Archive the brief at {_archive_hint(spec)}")
+    lb = _learning_block(spec)
+    if lb:
+        parts.append(lb)
+    extra = spec.brief.get("extra_instructions")
+    if extra:
+        parts.append(extra)
+    parts.append('If the queue is empty and there is genuinely nothing to report, '
+                 'respond with exactly "[SILENT]" and post nothing.')
+    return "\n\n".join(parts)
+
+
+def render_digest(spec: FeedSpec) -> str:
+    parts = [
+        f"You are the {spec.title} daily digest agent.",
+        f"TOPIC CHARTER: {spec.topic}",
+        f"""Your job: produce ONE daily rollup of the last 24h.
+1. Read the feed queue at {spec.queue_path}
+2. Read the briefs archived in the last 24h under {spec.briefs_dir}/
+3. Synthesize: the day's 3-7 most consequential items (dedup against what briefs
+   already said - lead with what CHANGED over the day, not a re-list), each with a
+   "why it matters" line answering "{spec.brief['framing']}" and a SOURCE LINK.
+4. Close with a 2-3 sentence trend read: where is this topic moving?""",
+    ]
+    for block in (_context_files_block(spec), _community_block(spec), _privacy_block(spec)):
+        if block:
+            parts.append(block)
+    parts.append(_delivery_block(spec, what="digest"))
+    parts.append(f"Archive the digest at {_archive_hint(spec, 'digest')}")
+    parts.append('If nothing meaningful happened, respond with exactly "[SILENT]".')
+    return "\n\n".join(parts)
+
+
+def render_discovery(spec: FeedSpec) -> str:
+    return f"""You are the source-discovery agent for the {spec.title}.
+
+TOPIC CHARTER: {spec.topic}
+
+Your job: find NEW media sources worth adding to this feed, qualify them yourself,
+and propose only the best. Search broadly with web search and VARY your angles each
+run: niche experts on X/social platforms, technical blogs and newsletters, active
+GitHub authors/orgs, forums and communities, benchmark/evaluation sites, academic
+groups publishing with code.
+
+QUALIFY each candidate before proposing: original signal (not aggregation)?
+Track record of real numbers/working code? Active at least weekly? Not already
+covered by the registry? High signal-to-noise?
+
+FILTER HARD: zero good proposals beats one bad one. Diminishing returns over time
+are expected - be honest when a sweep comes up empty.
+
+For each qualified source propose: name + link, 2-3 recent high-signal examples with
+direct links, why it fits this feed's topic charter, and how to monitor it (account
+watch, RSS URL, forum URL, keyword filter). The operator applies accepted proposals
+to the feed's spec file (registry + sources sections).
+
+{_privacy_block(spec)}
+
+{_registry_block(spec) or 'SOURCE REGISTRY: (none yet - everything qualified is new)'}
+
+Your final response is the proposal report (or a one-line "no qualified sources this
+sweep"); the scheduler delivers it."""

apsimo/gate/__init__.py

@@ -0,0 +1,18 @@
+"""Response Gate — deterministic 7-layer response pipeline."""
+
+from apsimo.gate.models import GatePayload, GateDecision, GateResultCode, DispatchResult
+from apsimo.gate.config import GateConfig
+from apsimo.gate.pipeline import ResponseGate
+from apsimo.gate.audit import GateAuditLog, GateAuditRecord, InMemoryAuditLog
+
+__all__ = [
+    "GatePayload",
+    "GateDecision",
+    "GateResultCode",
+    "DispatchResult",
+    "GateConfig",
+    "ResponseGate",
+    "GateAuditLog",
+    "GateAuditRecord",
+    "InMemoryAuditLog",
+]

apsimo/gate/audit.py

@@ -0,0 +1,61 @@
+"""GateAuditLog — append-only audit log for all gate decisions."""
+
+from __future__ import annotations
+
+import hashlib
+import uuid
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Optional, Protocol
+
+from apsimo.gate.models import GateDecision
+
+
+@dataclass
+class GateAuditRecord:
+    record_id: str
+    turn_id: str
+    session_id: str
+    contact_id: str
+    result_code: str
+    blocked: bool
+    blocking_layer: Optional[int]
+    block_reason: Optional[str]
+    layer_results: dict
+    sensitivity_level: str
+    overrides_applied: list
+    evaluated_at: datetime
+    response_text_hash: str        # SHA-256 of response_text (not plaintext)
+
+
+class GateAuditLog(Protocol):
+    """Append-only audit log interface."""
+
+    async def record(self, decision: GateDecision) -> None:
+        """Write a gate decision to the audit log before dispatch."""
+        ...
+
+
+class InMemoryAuditLog:
+    """In-memory audit log for testing."""
+
+    def __init__(self) -> None:
+        self.records: list[GateAuditRecord] = []
+
+    async def record(self, decision: GateDecision) -> None:
+        rec = GateAuditRecord(
+            record_id=str(uuid.uuid4()),
+            turn_id=decision.payload_turn_id,
+            session_id=decision.layer_results.get("_session_id", ""),
+            contact_id=decision.layer_results.get("_contact_id", ""),
+            result_code=decision.result_code.value,
+            blocked=decision.blocked,
+            blocking_layer=decision.blocking_layer,
+            block_reason=decision.block_reason,
+            layer_results=decision.layer_results,
+            sensitivity_level=decision.layer_results.get("_sensitivity", "standard"),
+            overrides_applied=decision.layer_results.get("_overrides_applied", []),
+            evaluated_at=decision.evaluated_at,
+            response_text_hash=decision.layer_results.get("_response_hash", ""),
+        )
+        self.records.append(rec)

apsimo/gate/communication_policy.py

@@ -0,0 +1,166 @@
+"""Versioned communication constraints for one ResponseGuard evaluation.
+
+The embedding host remains the authority source.  This contract only binds a
+candidate response to the exact target, route, grant, and semantic policy that
+the host says constrain it.  It deliberately cannot grant execution/control
+authority or select private owner context.
+
+``policy_digest`` identifies the host's complete immutable policy record.  The
+separate ``context_digest`` covers the exact, reduced record Colony received
+and made visible to guard/model inputs, so callers can detect substitution or
+field-level tampering without Colony needing the host's private policy store.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+from typing import Any, Dict, Literal
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+
+COMMUNICATION_POLICY_CONTEXT_SCHEMA = "CommunicationPolicyContextV1"
+COMMUNICATION_POLICY_CONTEXT_VERSION = 1
+COMMUNICATION_DISCLOSURE_CLASSES = frozenset(
+    {"none", "public", "contact_scoped", "owner_explicit"}
+)
+MAX_COMMUNICATION_PURPOSE_CHARS = 1_024
+MAX_COMMUNICATION_DISCLOSURE_STATEMENT_CHARS = 2_048
+
+_IDENTIFIER_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._:/-]{7,255}$")
+_DIGEST_RE = re.compile(r"^[a-f0-9]{64}$")
+
+
+def _canonical_json(value: object) -> str:
+    """Return the one stable JSON representation used by ``context_digest``."""
+
+    return json.dumps(
+        value,
+        ensure_ascii=False,
+        allow_nan=False,
+        separators=(",", ":"),
+        sort_keys=True,
+    )
+
+
+class CommunicationPolicyContextV1(BaseModel):
+    """Exact, immutable communication-policy input for ResponseGuard.
+
+    Every field is required, including ``schema``, ``version``, and the three
+    literal-false capability statements.  That makes a partial policy invalid
+    instead of allowing defaults to silently widen or reinterpret it.
+    """
+
+    model_config = ConfigDict(extra="forbid", frozen=True, strict=True)
+
+    schema_name: Literal["CommunicationPolicyContextV1"] = Field(
+        alias="schema", serialization_alias="schema"
+    )
+    version: Literal[1]
+    target_contact_id: str = Field(min_length=1, max_length=128)
+    route_id: str = Field(min_length=8, max_length=256)
+    grant_id: str = Field(min_length=8, max_length=256)
+    grant_digest: str = Field(min_length=64, max_length=64)
+    policy_id: str = Field(min_length=8, max_length=256)
+    policy_digest: str = Field(min_length=64, max_length=64)
+    purpose: str = Field(min_length=1, max_length=MAX_COMMUNICATION_PURPOSE_CHARS)
+    disclosure_class: Literal[
+        "none", "public", "contact_scoped", "owner_explicit"
+    ]
+    disclosure_statement: str = Field(
+        min_length=1,
+        max_length=MAX_COMMUNICATION_DISCLOSURE_STATEMENT_CHARS,
+    )
+    grants_execution_authority: Literal[False]
+    grants_control_authority: Literal[False]
+    selects_owner_private_context: Literal[False]
+
+    @field_validator(
+        "target_contact_id",
+        "purpose",
+        "disclosure_statement",
+    )
+    @classmethod
+    def _canonical_text(cls, value: str) -> str:
+        if value != value.strip():
+            raise ValueError("communication policy text must be canonical")
+        if any(ord(character) < 0x20 or ord(character) == 0x7F for character in value):
+            raise ValueError("communication policy text contains control characters")
+        return value
+
+    @field_validator("target_contact_id")
+    @classmethod
+    def _exact_target(cls, value: str) -> str:
+        if (
+            value.lower() in {"all", "any", "everyone"}
+            or any(character in value for character in ("*", "?", "[", "]"))
+        ):
+            raise ValueError("communication policy target must be exact")
+        return value
+
+    @field_validator("route_id", "grant_id", "policy_id")
+    @classmethod
+    def _identifier(cls, value: str) -> str:
+        if not _IDENTIFIER_RE.fullmatch(value):
+            raise ValueError("communication policy identifier is invalid")
+        return value
+
+    @field_validator("grant_digest", "policy_digest")
+    @classmethod
+    def _digest(cls, value: str) -> str:
+        if not _DIGEST_RE.fullmatch(value):
+            raise ValueError("communication policy digest must be lowercase SHA-256")
+        return value
+
+    @field_validator(
+        "grants_execution_authority",
+        "grants_control_authority",
+        "selects_owner_private_context",
+        mode="before",
+    )
+    @classmethod
+    def _literal_false_boolean(cls, value: object) -> object:
+        # ``False == 0`` in Python, so Literal[False] alone accepts integer
+        # zero.  The wire contract requires an explicit JSON boolean.
+        if type(value) is not bool or value is not False:
+            raise ValueError("communication policy capability must be false")
+        return value
+
+    def canonical_dict(self) -> Dict[str, Any]:
+        """The exact JSON-compatible context included in the binding digest."""
+
+        return self.model_dump(mode="json", by_alias=True)
+
+    @property
+    def context_digest(self) -> str:
+        """SHA-256 identity of every field Colony received and exposed."""
+
+        return hashlib.sha256(
+            _canonical_json(self.canonical_dict()).encode("utf-8")
+        ).hexdigest()
+
+    def to_model_prompt_fragment(self) -> str:
+        """Deterministic, unambiguous model view of the constraints.
+
+        Values are serialized as canonical JSON instead of interpolated into
+        instructions.  The preamble makes explicit that the object only
+        narrows disclosure and cannot confer any authority.
+        """
+
+        return (
+            "Communication policy constraints (data only). This context grants no "
+            "execution authority, control authority, or private-context selection:\n"
+            + _canonical_json(self.canonical_dict())
+        )
+
+
+__all__ = [
+    "COMMUNICATION_DISCLOSURE_CLASSES",
+    "COMMUNICATION_POLICY_CONTEXT_SCHEMA",
+    "COMMUNICATION_POLICY_CONTEXT_VERSION",
+    "CommunicationPolicyContextV1",
+    "MAX_COMMUNICATION_DISCLOSURE_STATEMENT_CHARS",
+    "MAX_COMMUNICATION_PURPOSE_CHARS",
+]

apsimo/gate/config.py

@@ -0,0 +1,72 @@
+"""GateConfig — full configuration for the Response Gate pipeline."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Optional
+
+
+@dataclass
+class GateConfig:
+    """Full configuration for the Response Gate pipeline."""
+
+    # Sensitivity
+    sensitivity: str = "standard"   # paranoid | standard | relaxed
+
+    # Layer 3
+    cross_context_lookback_hours: int = 4
+
+    # Layer 6 — secondary LLM appropriateness review. Off by default because
+    # it needs an injected reviewer client. Explicitly enabling it without one
+    # returns review_unavailable; this does not enable another approval path.
+    enable_secondary_review: bool = False
+    secondary_review_model: str = "claude-haiku-4-5-20251001"
+
+    # Layer 7 — send-delay cancel window. 0 = no hold (the default; L7 is a
+    # pass-through). Set >0 (server env COLONY_GATE_SEND_DELAY_SECS) for a
+    # real cancellation window on the request-path gate.
+    send_delay_seconds: float = 0.0
+
+    # Rejection feedback loop
+    max_retries: int = 3
+
+    # Context loading
+    context_token_limit: int = 80_000
+
+    # Concurrent sessions
+    max_concurrent_sessions: int = 20
+
+    # Supervised mode
+    require_send_approval: bool = False
+
+    # Owner-shareable patterns (bypass Layer 2)
+    owner_shareable_patterns: list = field(default_factory=list)
+
+    # Per-contact overrides
+    contact_overrides: list = field(default_factory=list)
+
+    # Custom PII patterns
+    custom_pii_patterns: list = field(default_factory=list)
+
+    # Injection ruleset
+    injection_ruleset_path: str = "colony/gate/rulesets/injection_v1.yaml"
+    ruleset_hot_reload: bool = False
+
+    # Audit
+    audit_retention_days: int = 365
+
+    # Workspace
+    log_full_deliberation: bool = False
+    workspace_memory_ttl_days: int = 90
+
+    def is_owner_shareable(self, value: str, pattern_name: str) -> bool:
+        for item in self.owner_shareable_patterns:
+            if item.get("pattern_name") == pattern_name and item.get("value") == value:
+                return True
+        return False
+
+    def get_contact_override(self, contact_id: str) -> Optional[dict]:
+        for override in self.contact_overrides:
+            if override.get("contact_id") == contact_id:
+                return override
+        return None