apsimo 1.3.0__py3-none-any.whl

apsimo/cognition/introspection.py

@@ -0,0 +1,214 @@
+"""Inline per-turn introspection.
+
+After a turn is synced, judge it with a local LLM and record any owed follow-up
+directly — durable commitments and, above all, IMMEDIATE OWED DELIVERABLES ("text me
+the result") — without depending on an external cognition subagent. This is the
+sidecar-side counterpart to the event-based ``cognition.requested`` path: that path
+emits an event for a host plugin to consume, which not every deployment wires up; this
+path runs the judgment in-process against any OpenAI-compatible chat endpoint.
+
+Disabled by default. Activated with ``COLONY_INTROSPECT_ENABLED=true`` and a configured
+endpoint; deployment-agnostic (point ``COLONY_INTROSPECT_BASE_URL`` at a local model):
+
+  COLONY_INTROSPECT_ENABLED     "true"|"false"      (default false)
+  COLONY_INTROSPECT_BASE_URL    OpenAI-compatible base, e.g. http://127.0.0.1:8000/v1
+  COLONY_INTROSPECT_MODEL       model id the endpoint serves (required to run)
+  COLONY_INTROSPECT_API_KEY     bearer token, blank for a local model
+  COLONY_INTROSPECT_TIMEOUT     seconds (default 30)
+  COLONY_INTROSPECT_MAX_TOKENS  response cap (default 400)
+
+Because an inline call cannot use tools, it uses a focused JSON-only prompt and creates
+the commitments itself.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+from typing import Any, Dict, List, Optional
+
+import httpx
+
+logger = logging.getLogger(__name__)
+
+# Purpose-built, JSON-only prompt (the tool-calling COGNITION_SYSTEM_PROMPT is too hedged and
+# mentions tools, which makes a no-think local model return nothing). Self-contained.
+_SYSTEM_PROMPT = (
+    "You audit ONE finished assistant turn and extract any follow-up worth recording, as STRICT JSON.\n"
+    "You get what the person SAID and what the assistant REPLIED. Decide only from the literal words.\n\n"
+    "Record an item only when the turn clearly contains one of:\n"
+    "1. A DURABLE COMMITMENT — an explicit promise, obligation, or reminder to do something later "
+    "(\"remind me to X\", \"I'll get back to you on X\", \"follow up on X by Friday\", \"we need to fix X\").\n"
+    "2. An IMMEDIATE OWED DELIVERABLE — the person asked to be SENT something through a channel the reply "
+    "did NOT satisfy (email it, text a DIFFERENT number, send it to someone else, send it later), AND the "
+    "actual content to send is present in the exchange. IMPORTANT: in a chat the assistant's reply already "
+    "IS a message to the person, so a plain \"text me\"/\"message me\" is ALREADY satisfied — do NOT record "
+    "that; only record a deliverable for a genuinely different channel, recipient, or time.\n\n"
+    "Do NOT record small talk, questions, hypotheticals, vague intentions, or anything the reply already "
+    "fully handled. Fewer items beats wrong items.\n\n"
+    "Output ONLY a JSON array, nothing else (no prose, no markdown, no code fence). Empty array [] when "
+    "nothing qualifies. Each element:\n"
+    '{"description": string, "due_at": ISO-8601-UTC string or null, "priority": integer 0-100, '
+    '"source_type": "cognition" | "introspection", "metadata": null or '
+    '{"kind":"deliverable","content":"<exact text to send, ready as-is>","channel_hint":"sms"|"dm"|"email"}}\n'
+    "Use \"introspection\" + the deliverable metadata (due_at about two minutes from now) for case 2; "
+    "\"cognition\" + metadata null for case 1.\n\n"
+    "Examples:\n"
+    "They said: Remind me to call the dentist Friday at 9am. | Assistant replied: Got it.\n"
+    '[{"description":"Remind them to call the dentist Friday 9am","due_at":"2026-06-26T13:00:00+00:00",'
+    '"priority":70,"source_type":"cognition","metadata":null}]\n'
+    "They said: Email me the Q3 revenue number. | Assistant replied: Q3 revenue was 4.2 million.\n"
+    '[{"description":"Email them the Q3 revenue","due_at":"2026-06-21T21:40:00+00:00","priority":80,'
+    '"source_type":"introspection","metadata":{"kind":"deliverable","content":"Q3 revenue was 4.2 million.",'
+    '"channel_hint":"email"}}]\n'
+    "They said: What's the weather? | Assistant replied: 72 and sunny.\n"
+    "[]\n"
+    "They said: Text me that. | Assistant replied: The address is 5 Main St.\n"
+    "[]   (a plain text-me in chat is already satisfied by the reply)")
+
+
+def _build_user_prompt(user_message: str, assistant_message: str,
+                       conversation_text: str, existing: list,
+                       rejections: Optional[list] = None) -> str:
+    parts = []
+    if conversation_text:
+        parts.append(f"Recent conversation:\n{conversation_text}\n")
+    parts.append("This turn, verbatim:\n"
+                 f"  They said: {user_message}\n"
+                 f"  Assistant replied: {assistant_message}\n")
+    if existing:
+        parts.append("\nAlready-recorded OPEN items for this person (do not duplicate; "
+                     "mentioning an open item again is NOT a new item):")
+        for c in existing[:6]:
+            parts.append(f"\n- {(c.get('description') or '?')[:80]}")
+    if rejections:
+        parts.append("\n\nRecently REJECTED items (judged invalid or duplicate — do NOT "
+                     "record these or anything similar again):")
+        for r in rejections[:6]:
+            parts.append(f"\n- {(r.get('description') or '?')[:80]} "
+                         f"[{r.get('outcome') or 'rejected'}]")
+    return "".join(parts)
+
+
+def introspect_enabled() -> bool:
+    from apsimo.util.autonomy_preset import resolve_bool
+    return resolve_bool("COLONY_INTROSPECT_ENABLED", False)
+
+
+def _config() -> Dict[str, Any]:
+    return {
+        "base_url": os.environ.get("COLONY_INTROSPECT_BASE_URL", "http://127.0.0.1:8000/v1").rstrip("/"),
+        "model": os.environ.get("COLONY_INTROSPECT_MODEL", "").strip(),
+        "api_key": os.environ.get("COLONY_INTROSPECT_API_KEY", "").strip(),
+        "timeout": float(os.environ.get("COLONY_INTROSPECT_TIMEOUT", "30")),
+        "max_tokens": int(os.environ.get("COLONY_INTROSPECT_MAX_TOKENS", "400")),
+    }
+
+
+
+
+def _parse_json_array(text: str) -> List[Dict[str, Any]]:
+    """Pull the first JSON array out of the model's reply; [] on anything malformed."""
+    if not text:
+        return []
+    try:
+        chunk = text[text.index("["): text.rindex("]") + 1]
+        data = json.loads(chunk)
+        return [x for x in data if isinstance(x, dict)] if isinstance(data, list) else []
+    except Exception:
+        return []
+
+
+async def run_turn_introspection(
+    *,
+    user_message: str,
+    assistant_message: str,
+    conversation_text: str,
+    person_id: str,
+    existing_commitments: Optional[List[Dict[str, Any]]],
+    commitment_store: Any,
+    recent_rejections: Optional[List[Dict[str, Any]]] = None,
+) -> Dict[str, Any]:
+    """Judge one completed turn and record any owed follow-ups as commitments.
+
+    Best-effort and exception-safe: a failure here never affects the turn. Returns a small
+    dict describing what it did, mostly for tests/logging.
+
+    Dedup is enforced in code, not just in the prompt: a candidate matching an
+    existing OPEN item, or a recently REJECTED one, is skipped. Without this,
+    every conversational mention of an overdue item re-records it and resolving
+    one copy leaves another — the "resolve does nothing" loop.
+    """
+    cfg = _config()
+    if not cfg["model"] or commitment_store is None:
+        return {"ok": False, "reason": "introspection not configured"}
+    if not (user_message or assistant_message or conversation_text):
+        return {"ok": False, "reason": "empty turn"}
+
+    user_prompt = _build_user_prompt(
+        user_message or "", assistant_message or "", conversation_text or "",
+        existing_commitments or [], recent_rejections or [])
+
+    try:
+        async with httpx.AsyncClient(timeout=cfg["timeout"]) as client:
+            resp = await client.post(
+                cfg["base_url"] + "/chat/completions",
+                headers={"Authorization": f"Bearer {cfg['api_key'] or 'x'}",
+                         "Content-Type": "application/json"},
+                json={
+                    "model": cfg["model"], "temperature": 0.1, "max_tokens": cfg["max_tokens"],
+                    "messages": [{"role": "system", "content": _SYSTEM_PROMPT},
+                                 {"role": "user", "content": user_prompt}],
+                },
+            )
+            resp.raise_for_status()
+            content = (resp.json()["choices"][0]["message"]["content"] or "").strip()
+    except Exception as exc:
+        logger.warning("introspection LLM call failed: %s", exc)
+        return {"ok": False, "reason": str(exc)}
+
+    items = _parse_json_array(content)
+    created: List[str] = []
+    skipped_duplicates = 0
+    from apsimo.commitments.store import _normalize_desc, _similar_desc
+    _known = [_normalize_desc(c.get("description") or "")
+              for c in (existing_commitments or [])]
+    _known += [_normalize_desc(r.get("description") or "")
+               for r in (recent_rejections or [])]
+    _known = [k for k in _known if k]
+    for it in items:
+        desc = str(it.get("description") or "").strip()
+        if not desc:
+            continue
+        norm = _normalize_desc(desc)
+        if any(_similar_desc(norm, k) for k in _known):
+            skipped_duplicates += 1
+            continue
+        try:
+            row = commitment_store.create(
+                person_id=person_id,
+                description=desc[:1000],
+                dedupe=True,
+                due_at=(it.get("due_at") or None),
+                priority=int(it.get("priority") or 60),
+                source_type=(it.get("source_type") or "introspection"),
+                source_context="inline turn introspection",
+                metadata=(it.get("metadata") if isinstance(it.get("metadata"), dict) else None),
+            )
+            if row.get("deduped"):
+                skipped_duplicates += 1
+            else:
+                created.append(row.get("id"))
+            _known.append(norm)   # a later candidate in the same batch can also dupe this one
+        except Exception as exc:
+            # e.g. a non-future due_at is rejected by the store — skip that one, keep going.
+            logger.debug("introspection commitment skipped: %s", exc)
+
+    if created:
+        logger.info("introspection recorded %d commitment(s) for %s", len(created), person_id)
+    if skipped_duplicates:
+        logger.info("introspection skipped %d duplicate candidate(s) for %s",
+                    skipped_duplicates, person_id)
+    return {"ok": True, "created": created, "candidates": len(items),
+            "skipped_duplicates": skipped_duplicates}

apsimo/cognition/prompt.py

@@ -0,0 +1,150 @@
+"""Cognition prompt templates for Colony's background thinking.
+
+The cognition prompt tells the subagent what Colony can do and how to
+think about the context it receives. It is deliberately conservative:
+false negatives are preferred over false positives.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+from apsimo.cognition.charter import build_system_prompt
+
+# The detailed observation guide: worked positive/negative examples for the
+# observer role. Injected as <context> on top of the shared charter, which
+# carries identity, doctrine, and the conservatism rules.
+_GUIDE = """\
+You have access to Apsimo's API through HTTP endpoints running on the same \
+host. Use the tools available to you to take action when appropriate.
+
+## What to Look For
+
+### 1. COMMITMENTS
+Any explicit promise, follow-up, or obligation expressed in conversation.
+
+Examples of commitments:
+- "I'll check on that tomorrow" → commitment with due date tomorrow
+- "Let me get back to you about X" → commitment, no specific deadline
+- "Remind me to call Sarah" → commitment with implicit deadline
+- "I should follow up on the PR review" → commitment, self-directed
+- "We need to fix that bug by Friday" → commitment with deadline
+
+NOT commitments (do not record):
+- Casual future tense without obligation ("I might look into it")
+- Hypotheticals ("What if we tried X?")
+- General intentions without specificity ("I want to be better about Y")
+- Questions about future events ("When is the meeting?")
+
+When recording a commitment:
+- Use the person who made the promise as person_id
+- Include the specific due date if mentioned, otherwise leave null
+- Set source_type to "cognition"
+- Set priority: urgent/critical promises = 70-90, casual = 40-60
+
+### 2. IMMEDIATE OWED DELIVERABLES
+Something the person asked to be DELIVERED to them in THIS just-finished exchange that
+was NOT actually done in it. The classic case: they asked you to send/text/email/show them
+the result, a link, a file, a summary, or a number, and the answer was only spoken or never
+sent. This is distinct from a commitment: it is owed NOW, not on a future date.
+
+Examples of immediate owed deliverables:
+- "text me the findings" / "send me that summary" / "shoot me his number" → deliverable, send now
+- "email me the link" → deliverable via email
+- "send me the chart you described" → deliverable
+
+NOT deliverables (do not record):
+- The assistant ALREADY sent/did it in this exchange (check the assistant's message first)
+- The person only wanted to KNOW or be TOLD something (answering aloud already satisfied it)
+- A vague or future "send it over sometime" (that is a commitment, not an immediate deliverable)
+
+When recording an immediate owed deliverable, use commitment_create with:
+- person_id = the person who is owed it
+- source_type = "introspection"
+- due_at = about two minutes from now (it is owed now; the store rejects a past due_at)
+- priority = 75-90 (they are waiting on it)
+- description = "Deliver to <person>: <short label>"
+- metadata = {"kind": "deliverable", "content": "<the exact, self-contained thing to send,
+  ready to send as-is, drawn from this exchange>", "channel_hint": "sms" | "dm" | "email"
+  as they asked}
+The "content" must be the real material to send, not a description of it. If you cannot
+recover the actual content from this exchange, do not record a deliverable.
+
+### 3. When NOT to Act
+- Casual small talk with no actionable content
+- Information exchange with no commitments or owed deliverables
+- Jokes, humor, or social pleasantries
+- Already-recorded commitments (check before creating duplicates)
+- Anything the assistant already handled in this same exchange
+
+## Critical Rules
+
+1. **Fewer actions are better than wrong actions.** If you are unsure whether \
+something is a commitment, do not record it.
+2. **Do not create duplicate commitments.** Check existing commitments before \
+creating new ones.
+3. **Be specific in descriptions.** "Check DGX cluster status by Friday" is \
+better than "follow up on something."
+4. **Only record commitments when there is clear intent.** Maybes and mights \
+are not commitments.
+"""
+
+COGNITION_SYSTEM_PROMPT = build_system_prompt("observer", extra=_GUIDE)
+
+
+def build_cognition_prompt(
+    trigger_type: str,
+    context: Dict[str, Any],
+    existing_commitments: Optional[list] = None,
+) -> str:
+    """Build the user prompt for a cognition trigger.
+
+    Args:
+        trigger_type: Type of trigger (turn_sync, signal_ingest, anomaly, manual).
+        context: Trigger-specific context (conversation text, person_id, etc.).
+        existing_commitments: Current pending commitments for context.
+
+    Returns:
+        Formatted prompt string for the subagent.
+    """
+    parts = [f"Trigger type: {trigger_type}\n"]
+
+    if trigger_type == "turn_sync":
+        conversation_text = context.get("conversation_text", "")
+        person_id = context.get("person_id", "unknown")
+        parts.append(f"Contact: {person_id}\n")
+        parts.append(f"Recent conversation:\n{conversation_text}\n")
+        # Verbatim last turn (when available) so an owed deliverable and whether the
+        # assistant ALREADY did it can both be judged from the actual words.
+        user_msg = context.get("user_message", "")
+        asst_msg = context.get("assistant_message", "")
+        if user_msg or asst_msg:
+            parts.append(
+                "\nLast turn, verbatim (use this to tell if the person asked to be "
+                "sent something and whether the assistant already did it):\n"
+                f"  They said: {user_msg}\n"
+                f"  Assistant replied: {asst_msg}\n"
+            )
+
+    elif trigger_type == "signal_ingest":
+        signal_type = context.get("signal_type", "unknown")
+        signal_data = context.get("signal_data", {})
+        parts.append(f"Signal type: {signal_type}\n")
+        parts.append(f"Signal data: {signal_data}\n")
+
+    elif trigger_type == "anomaly":
+        anomaly_description = context.get("description", "Unknown anomaly")
+        parts.append(f"Anomaly detected: {anomaly_description}\n")
+
+    elif trigger_type == "manual":
+        manual_prompt = context.get("prompt", "")
+        parts.append(f"Manual cognition request: {manual_prompt}\n")
+
+    # Include existing commitments so the subagent can avoid duplicates
+    if existing_commitments:
+        parts.append("\nExisting pending commitments for this contact:\n")
+        for c in existing_commitments[:5]:
+            due = f" (due {c.get('due_at', 'no deadline')[:10]})" if c.get("due_at") else ""
+            parts.append(f"- {c.get('description', '?')}{due}\n")
+
+    return "".join(parts)

apsimo/cognition/runtime.py

@@ -0,0 +1,108 @@
+"""Versioned deployment contract for the P3 cognition spine.
+
+The feature flags used by the older cognition slices are independent.  That
+is useful for canaries, but it also made unsafe combinations representable --
+for example a live P3 consuming concerns manufactured by a shadow reducer.
+This module turns the flags into one small, inspectable lattice.  It does not
+enable any producer and it never widens a requested mode.
+"""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass
+import hashlib
+import json
+from typing import Any, Mapping, Optional
+
+
+_MODES = {"off", "shadow", "live"}
+
+
+def _mode(value: Any) -> str:
+    normalized = str(value or "off").strip().lower()
+    return normalized if normalized in _MODES else "off"
+
+
+def _digest(value: Mapping[str, Any]) -> str:
+    encoded = json.dumps(
+        dict(value), sort_keys=True, separators=(",", ":"), ensure_ascii=True,
+    ).encode("utf-8")
+    return hashlib.sha256(encoded).hexdigest()
+
+
+@dataclass(frozen=True)
+class CognitionRuntimeContractV1:
+    """Attached/effective mode composition and its immutable revision."""
+
+    requested_mode: str
+    effective_mode: str
+    workspace_mode: str
+    event_concern_mode: str
+    drive_governance_mode: str
+    charter_revision_id: Optional[str]
+    blockers: tuple[str, ...]
+    revision: str
+    schema: str = "CognitionRuntimeContractV1"
+    version: int = 1
+
+    @classmethod
+    def compose(
+        cls,
+        *,
+        requested_mode: str,
+        workspace_mode: str,
+        event_concern_mode: str,
+        drive_governance_mode: str,
+        charter_revision_id: Optional[str] = None,
+        charter_store_attached: bool = False,
+        attachment_blockers: tuple[str, ...] = (),
+    ) -> "CognitionRuntimeContractV1":
+        requested = _mode(requested_mode)
+        workspace = _mode(workspace_mode)
+        events = _mode(event_concern_mode)
+        drives = _mode(drive_governance_mode)
+        blockers = list(dict.fromkeys(str(item) for item in attachment_blockers))
+
+        if requested == "live":
+            if workspace != "live":
+                blockers.append(f"workspace_mode_{workspace}_cannot_feed_live_p3")
+            # Event provenance is checked on the exact Concern. Holding the
+            # whole runtime because an optional shadow reducer is attached
+            # would also stop separately-produced live concerns. Likewise P7
+            # shadow is an observer and must not change P3 admission.
+            if drives == "live":
+                if not charter_store_attached:
+                    blockers.append("live_charter_store_not_attached")
+                elif not charter_revision_id:
+                    blockers.append("active_owner_ratified_charter_required")
+
+        effective = requested
+        if requested != "off" and blockers:
+            effective = "held"
+        authority = {
+            "schema": "CognitionRuntimeContractV1",
+            "version": 1,
+            "requested_mode": requested,
+            "effective_mode": effective,
+            "workspace_mode": workspace,
+            "event_concern_mode": events,
+            "drive_governance_mode": drives,
+            "charter_revision_id": charter_revision_id,
+            "blockers": sorted(set(blockers)),
+        }
+        return cls(
+            requested_mode=requested,
+            effective_mode=effective,
+            workspace_mode=workspace,
+            event_concern_mode=events,
+            drive_governance_mode=drives,
+            charter_revision_id=charter_revision_id,
+            blockers=tuple(authority["blockers"]),
+            revision=f"cognition-runtime:{_digest(authority)[:24]}",
+        )
+
+    def payload(self) -> dict[str, Any]:
+        return asdict(self)
+
+
+__all__ = ["CognitionRuntimeContractV1"]

apsimo/cognition/trigger.py

@@ -0,0 +1,154 @@
+"""Cognition trigger — spawns an OpenClaw subagent for background thinking.
+
+Colony does not run its own LLM. It sends cognition requests to OpenClaw
+via the subagent spawn API, which handles model routing, concurrency,
+and token budgeting.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import time
+from typing import Any, Dict, Optional
+
+from apsimo.cognition.prompt import COGNITION_SYSTEM_PROMPT, build_cognition_prompt
+
+logger = logging.getLogger(__name__)
+
+# Module-level throttle state
+_last_trigger_time: float = 0.0
+_last_trigger_session: Optional[str] = None
+
+
+def _cognition_enabled() -> bool:
+    from apsimo.util.autonomy_preset import resolve_bool
+    return resolve_bool("COLONY_COGNITION_ENABLED", False)
+
+
+def _cognition_model() -> Optional[str]:
+    return os.environ.get("COLONY_COGNITION_MODEL") or None
+
+
+def _throttle_seconds() -> int:
+    try:
+        return int(os.environ.get("COLONY_COGNITION_THROTTLE_SECONDS", "30"))
+    except ValueError:
+        return 30
+
+
+def _update_throttle(now: float, session_id: str) -> None:
+    global _last_trigger_time, _last_trigger_session
+    _last_trigger_time = now
+    _last_trigger_session = session_id
+
+
+async def trigger_cognition(
+    trigger_type: str,
+    context: Dict[str, Any],
+    priority: str = "normal",
+) -> Dict[str, Any]:
+    """Fire a cognition trigger by spawning an OpenClaw subagent.
+
+    This is called from the API endpoint. It builds the cognition prompt,
+    checks throttling, and delegates to OpenClaw's sessions_spawn.
+
+    Args:
+        trigger_type: turn_sync, signal_ingest, anomaly, or manual.
+        context: Trigger-specific context data.
+        priority: high, normal, or low.
+
+    Returns:
+        Dict with accepted status and optional throttle info.
+    """
+    if not _cognition_enabled():
+        return {
+            "accepted": False,
+            "message": "Cognition substrate is disabled",
+            "throttle_seconds": None,
+        }
+
+    model = _cognition_model()
+    if not model:
+        return {
+            "accepted": False,
+            "message": "COLONY_COGNITION_MODEL not configured",
+            "throttle_seconds": None,
+        }
+
+    # Throttle check (skip for high priority)
+    throttle_secs = _throttle_seconds()
+    now = time.time()
+    if priority != "high" and (now - _last_trigger_time) < throttle_secs:
+        remaining = int(throttle_secs - (now - _last_trigger_time))
+        return {
+            "accepted": True,
+            "message": f"Throttled — queued for {remaining}s",
+            "throttle_seconds": remaining,
+        }
+
+    # Get existing commitments for context (avoid duplicates)
+    existing = []
+    person_id = context.get("person_id")
+    if person_id:
+        try:
+            from apsimo.api.routers.host import _commitment_store
+            if _commitment_store is not None:
+                existing = _commitment_store.get_pending_for_person(person_id)
+        except Exception:
+            logger.debug("Failed to fetch existing commitments for cognition", exc_info=True)
+
+    # Build the prompt
+    user_prompt = build_cognition_prompt(
+        trigger_type=trigger_type,
+        context=context,
+        existing_commitments=existing,
+    )
+
+    # Update throttle timestamp
+    session_id = context.get("session_id", "")
+    _update_throttle(now, session_id)
+
+    # Emit cognition.requested event for the plugin to pick up
+    _emit_cognition_event(trigger_type, user_prompt, model, priority)
+
+    return {
+        "accepted": True,
+        "message": "Cognition trigger fired",
+        "throttle_seconds": None,
+    }
+
+
+def _emit_cognition_event(
+    trigger_type: str,
+    prompt: str,
+    model: str,
+    priority: str,
+) -> None:
+    """Emit a cognition.requested event carrying a full spawn spec.
+
+    This is an OPTIONAL integration point: no shipped consumer spawns a
+    dedicated cognition session from it today (the hermes plugin only caches
+    events as context blurbs). The working per-turn judgment path is the
+    inline introspection in cognition/introspection.py; a deployment that
+    wants a real tool-restricted cognition session can subscribe to this
+    event and honor system_prompt/model/tools_allow. See docs/KNOWN-GAPS.md.
+    """
+    try:
+        from apsimo.events.broadcaster import emit
+        emit("cognition.requested", {
+            "trigger_type": trigger_type,
+            "system_prompt": COGNITION_SYSTEM_PROMPT,
+            "user_prompt": prompt,
+            "model": model,
+            "priority": priority,
+            # Names match the registered agent tools so a consumer can pass
+            # this straight through as an allowlist.
+            "tools_allow": [
+                "colony_create_commitment",
+                "colony_list_commitments",
+                "colony_resolve_commitment",
+            ],
+        })
+    except Exception:
+        logger.debug("Failed to emit cognition.requested event", exc_info=True)

apsimo/commitments/__init__.py

@@ -0,0 +1,18 @@
+"""Commitment tracking for Colony.
+
+Records, tracks, and surfaces promises made during conversations.
+Commitments are created by the cognition substrate (automatic extraction),
+the autonomy loop, or manual API calls.
+"""
+
+from apsimo.commitments.store import (
+    CommitmentResolutionSchemaError,
+    CommitmentStore,
+    RESOLUTION_RECOVERY_CAPABILITY,
+)
+
+__all__ = [
+    "CommitmentResolutionSchemaError",
+    "CommitmentStore",
+    "RESOLUTION_RECOVERY_CAPABILITY",
+]