monkeybot 2.1.1__py3-none-any.whl

monkeybot/core/context/campaign_context.py

@@ -0,0 +1,8 @@
+"""Per-invocation campaign / memory context for tools that are not path-rewritten by middleware."""
+
+from __future__ import annotations
+
+from contextvars import ContextVar
+
+# Set by MemoryPathMiddleware from config["configurable"]["memory_context_dir"] (or campaign_dir).
+memory_context_dir_ctx: ContextVar[str | None] = ContextVar("memory_context_dir_ctx", default=None)

monkeybot/core/context/common.py

@@ -0,0 +1,14 @@
+"""Shared context-shaping types and helpers."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import Literal
+
+from monkeybot.core.types.content_blocks import ContentBlock, Text
+
+ContextPressureTier = Literal["light", "moderate", "aggressive"]
+
+
+def text_from_blocks(blocks: Sequence[ContentBlock]) -> str:
+    return "".join(block.text for block in blocks if isinstance(block, Text))

monkeybot/core/context/curator.py

@@ -0,0 +1,255 @@
+"""Optional secondary LLM pass to pick memory lines for the system prompt."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import os
+import re
+import time
+from contextlib import aclosing
+from dataclasses import dataclass
+from typing import Any, cast
+
+from monkeybot.core.types.content_blocks import Text
+from monkeybot.core.context import TurnContext
+from monkeybot.core.logging_utils import kv
+from monkeybot.core.memory.subsystem import MemorySubsystem
+from monkeybot.core.llm.provider import Done, Message, Provider, TextDelta, ToolCall, UsageEvent
+from monkeybot.core.runtime.context_budget import estimate_tokens
+
+_log = logging.getLogger(__name__)
+
+
+def curation_enabled_from_env() -> bool:
+    v = os.getenv("CONTEXT_CURATION_ENABLED", "1").strip().lower()
+    return v not in ("0", "false", "no", "off")
+
+
+def _env_int(name: str, default: int) -> int:
+    raw = os.getenv(name, str(default)).strip()
+    try:
+        return int(raw)
+    except ValueError:
+        return default
+
+
+def _env_float(name: str, default: float) -> float:
+    raw = os.getenv(name, str(default)).strip()
+    try:
+        return float(raw)
+    except ValueError:
+        return default
+
+
+def memory_index_token_estimate(lines: list[str]) -> int:
+    """Cheap local estimate of memory-index prompt size (no provider call)."""
+    if not lines:
+        return 0
+    return estimate_tokens("\n".join(lines))
+
+
+# Cap on search hits added to the curator MEMORY_POOL (not user-configurable).
+_CURATOR_SEARCH_MAX_HITS = 8
+
+
+def curator_model_id(ctx: TurnContext) -> str:
+    return os.getenv("CONTEXT_CURATOR_MODEL", "").strip() or ctx.model
+
+
+@dataclass(frozen=True)
+class CuratedPromptParts:
+    """Subset of memory lines chosen for this user message (frozen for follow-up turns)."""
+
+    memory_lines: list[str]
+    success: bool
+    """False on timeout, provider error, invalid JSON, or invalid selections when the model proposed content."""
+
+
+def _parse_json_object(text: str) -> dict[str, object] | None:
+    raw = text.strip()
+    if raw.startswith("```"):
+        raw = re.sub(r"^```(?:json)?\s*", "", raw, flags=re.IGNORECASE)
+        raw = re.sub(r"\s*```\s*$", "", raw).strip()
+    start = raw.find("{")
+    end = raw.rfind("}")
+    if start < 0 or end <= start:
+        return None
+    try:
+        out = json.loads(raw[start : end + 1])
+    except json.JSONDecodeError:
+        return None
+    return out if isinstance(out, dict) else None
+
+
+async def _gather_search_pool_lines(
+    memory: MemorySubsystem | None, user_text: str, *, max_hits: int
+) -> list[str]:
+    if memory is None or not user_text.strip():
+        return []
+    q = user_text.strip()[:400]
+    payload = await memory.search_files(q, max_hits=max_hits, skip_raw=True)
+    hits = payload.get("hits") or []
+    lines: list[str] = []
+    if not isinstance(hits, list):
+        return []
+    for h in hits:
+        if not isinstance(h, dict):
+            continue
+        path = str(h.get("path", "")).strip()
+        snip = str(h.get("snippet", "")).strip()
+        if path and snip:
+            lines.append(f"{path} — {snip}")
+    return lines
+
+
+def _coerce_index(value: object) -> int | None:
+    if isinstance(value, bool):
+        return None
+    if isinstance(value, int):
+        return value
+    if isinstance(value, float) and value.is_integer():
+        return int(value)
+    if isinstance(value, str) and value.strip().isdigit():
+        return int(value.strip())
+    return None
+
+
+def _lines_from_indices(indices: list[object], pool: list[str], cap: int) -> list[str]:
+    out: list[str] = []
+    for item in indices:
+        idx = _coerce_index(item)
+        if idx is None or idx < 1 or idx > len(pool):
+            continue
+        line = pool[idx - 1]
+        if line not in out:
+            out.append(line)
+        if len(out) >= cap:
+            break
+    return out
+
+
+async def run_context_curator(
+    *,
+    ctx: TurnContext,
+    provider: Provider,
+    curator_model: str,
+    user_message: str,
+    max_memory_lines: int,
+    curator_provider: Provider | None = None,
+) -> CuratedPromptParts:
+    """Call a small JSON-only completion to pick numbered memory pool lines.
+
+    ``max_memory_lines`` is the caller's window size (no env re-read here).
+    ``curator_provider`` is an optional dedicated provider instance tuned for this
+    auxiliary call (e.g. ``thinking_budget=0, max_output_tokens=1024``). Falls back
+    to ``provider`` when not supplied.
+    """
+    _provider = curator_provider if curator_provider is not None else provider
+    max_mem = max(1, max_memory_lines)
+    search_hits = _CURATOR_SEARCH_MAX_HITS
+    timeout_sec = max(1.0, _env_float("CONTEXT_CURATION_TIMEOUT_SEC", 10.0))
+
+    index_lines = list(ctx.memory_index)
+    search_lines: list[str] = []
+    memory_scan_sec = 0.0
+    if ctx.memory is not None:
+        t_scan = time.monotonic()
+        search_lines = await _gather_search_pool_lines(ctx.memory, user_message, max_hits=search_hits)
+        memory_scan_sec = time.monotonic() - t_scan
+
+    pool = index_lines + search_lines
+
+    catalog_user = []
+    catalog_user.append("## MEMORY_POOL (1-based line numbers)")
+    for i, ln in enumerate(pool, 1):
+        catalog_user.append(f"{i}. {ln}")
+    catalog_user.append("\n## USER_MESSAGE")
+    catalog_user.append(user_message.strip() or "(empty)")
+
+    system = Message(
+        role="system",
+        content=[
+            Text(
+                text=(
+                    "You narrow context for another assistant. Reply with ONLY a JSON object, no markdown fences. "
+                    f'Schema: {{"memory_line_indices": number[]}}. '
+                    f"At most {max_mem} indices. "
+                    "Each index must be a 1-based line number from MEMORY_POOL. "
+                    "If nothing helps, return an empty array."
+                )
+            )
+        ],
+    )
+    catalog_text = "\n".join(catalog_user)
+    catalog_chars = len(catalog_text)
+    user = Message(role="user", content=[Text(text=catalog_text)])
+
+    async def _stream_once() -> str:
+        buf: list[str] = []
+        async with aclosing(
+            cast(Any, _provider.stream([system, user], [], model=curator_model))
+        ) as stream:
+            async for ev in stream:
+                if isinstance(ev, TextDelta):
+                    buf.append(ev.text)
+                elif isinstance(ev, ToolCall):
+                    _log.warning(
+                        "curation unexpected tool call %s",
+                        kv(curator_model=curator_model),
+                    )
+                    return ""
+                elif isinstance(ev, UsageEvent):
+                    pass
+                elif isinstance(ev, Done):
+                    break
+        return "".join(buf)
+
+    try:
+        raw = await asyncio.wait_for(_stream_once(), timeout=timeout_sec)
+    except TimeoutError:
+        _log.warning(
+            "curation timeout %s",
+            kv(
+                timeout_sec=timeout_sec,
+                curator_model=curator_model,
+                index_lines=len(index_lines),
+                search_pool_lines=len(search_lines),
+                catalog_chars=catalog_chars,
+                memory_scan_sec=f"{memory_scan_sec:.2f}",
+            ),
+        )
+        return CuratedPromptParts([], success=False)
+    except Exception as exc:
+        _log.warning("curation provider error %s", kv(error=exc))
+        return CuratedPromptParts([], success=False)
+
+    parsed = _parse_json_object(raw)
+    if parsed is None:
+        _log.warning("curation invalid JSON %s", kv(curator_model=curator_model))
+        return CuratedPromptParts([], success=False)
+
+    raw_indices = parsed.get("memory_line_indices", [])
+    if not isinstance(raw_indices, list):
+        raw_indices = []
+
+    mem_out = _lines_from_indices(raw_indices, pool, max_mem)
+
+    proposed = bool(raw_indices)
+    if proposed and not mem_out:
+        _log.warning(
+            "curation indices unmatched %s",
+            kv(curator_model=curator_model, proposed=len(raw_indices), pool=len(pool)),
+        )
+        return CuratedPromptParts([], success=False)
+
+    _log.info(
+        "curation selected %s",
+        kv(
+            selected=len(mem_out),
+            pool=len(pool),
+            curator_model=curator_model,
+        ),
+    )
+    return CuratedPromptParts(mem_out, success=True)

monkeybot/core/context/epoch.py

@@ -0,0 +1,226 @@
+"""Context Epoch — stable baseline + mid-conversation volatile updates.
+
+An epoch is the span during which one rendered system-prompt baseline remains the
+immutable provider-cache prefix. Volatile sources (memory, skills, current-request)
+may change within an epoch and produce chronological system-context updates without
+rewriting the baseline. Compaction (or an incompatible stable-source change) starts
+a new epoch.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+import hashlib
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from typing import Literal
+
+
+# Heading for the chronological mid-epoch update text (see
+# ``_format_system_context_update``). Exported so callers that need to locate
+# the stable/volatile boundary in a flattened prompt string (e.g. Anthropic
+# cache-block splitting in ``providers._utils.split_system_prompt_for_cache``)
+# import this instead of re-declaring the literal and risking drift.
+SYSTEM_CONTEXT_UPDATE_HEADING = "\n\n## System context update\n"
+
+
+def fingerprint_text(*parts: str) -> str:
+    """Stable short hash of concatenated text parts (empty parts allowed)."""
+    h = hashlib.sha256()
+    for part in parts:
+        h.update(part.encode("utf-8"))
+        h.update(b"\0")
+    return h.hexdigest()[:16]
+
+
+@dataclass(frozen=True)
+class EpochAdmit:
+    """Result of reconciling system context at a safe provider-turn boundary."""
+
+    kind: Literal["unchanged", "volatile_updated", "new_epoch"]
+    epoch_id: int
+    """Full system text for the leading system message (baseline within the epoch)."""
+    leading_system_text: str
+    """Chronological update text when volatile sources changed mid-epoch; else empty."""
+    mid_conversation_update: str
+    changed_sources: tuple[str, ...]
+
+
+@dataclass
+class _EpochState:
+    epoch_id: int
+    stable_baseline: str
+    stable_fingerprint: str
+    """Volatile text admitted into the leading baseline at epoch start."""
+    baseline_volatile: str
+    volatile_fingerprint: str
+    """Per-source fingerprints as of the last admitted volatile render (for
+
+    diagnosing which specific source changed on the next reconcile — memory,
+    skills, current-request — rather than reporting the opaque catch-all
+    ``"volatile"``.
+    """
+    volatile_part_fingerprints: dict[str, str] = field(default_factory=dict)
+
+
+class ContextEpochTracker:
+    """Track one session turn's context epoch across inner provider calls.
+
+    Call :meth:`reconcile` at each safe provider-turn boundary. Call
+    :meth:`begin_new_epoch` after compaction (or session move) so the next
+    reconcile folds current context into a fresh baseline.
+    """
+
+    def __init__(self) -> None:
+        self._state: _EpochState | None = None
+        self._force_new = True
+
+    def begin_new_epoch(self) -> None:
+        """Mark that the next reconcile must open a new epoch (post-compaction)."""
+        self._force_new = True
+
+    def reconcile(
+        self,
+        *,
+        stable_baseline: str,
+        volatile_text: str,
+        stable_fingerprint: str,
+        volatile_fingerprint: str,
+        volatile_part_fingerprints: Mapping[str, str] | None = None,
+    ) -> EpochAdmit:
+        """Admit current stable/volatile renders at a provider-turn boundary.
+
+        ``volatile_part_fingerprints`` (e.g. ``{"memory": ..., "skills": ...,
+        "current_request": ...}``) is optional; when supplied it makes
+        ``EpochAdmit.changed_sources`` name the specific volatile source(s) that
+        changed instead of the catch-all ``"volatile"``.
+        """
+        admit, next_state, force_new = self._compute(
+            stable_baseline=stable_baseline,
+            volatile_text=volatile_text,
+            stable_fingerprint=stable_fingerprint,
+            volatile_fingerprint=volatile_fingerprint,
+            volatile_part_fingerprints=volatile_part_fingerprints,
+        )
+        self._state = next_state
+        self._force_new = force_new
+        return admit
+
+    def peek(
+        self,
+        *,
+        stable_baseline: str,
+        volatile_text: str,
+        stable_fingerprint: str,
+        volatile_fingerprint: str,
+        volatile_part_fingerprints: Mapping[str, str] | None = None,
+    ) -> EpochAdmit:
+        """Compute the :class:`EpochAdmit` for the given renders without mutating state.
+
+        Use for out-of-band accounting (e.g. token recounts) that must reflect the
+        true wire shape — leading baseline plus any mid-conversation update — without
+        advancing the epoch or admitting a volatile update that wasn't actually sent.
+        """
+        admit, _next_state, _force_new = self._compute(
+            stable_baseline=stable_baseline,
+            volatile_text=volatile_text,
+            stable_fingerprint=stable_fingerprint,
+            volatile_fingerprint=volatile_fingerprint,
+            volatile_part_fingerprints=volatile_part_fingerprints,
+        )
+        return admit
+
+    def _compute(
+        self,
+        *,
+        stable_baseline: str,
+        volatile_text: str,
+        stable_fingerprint: str,
+        volatile_fingerprint: str,
+        volatile_part_fingerprints: Mapping[str, str] | None,
+    ) -> tuple[EpochAdmit, _EpochState | None, bool]:
+        parts = dict(volatile_part_fingerprints) if volatile_part_fingerprints else {}
+        if (
+            self._force_new
+            or self._state is None
+            or stable_fingerprint != self._state.stable_fingerprint
+        ):
+            next_id = 1 if self._state is None else self._state.epoch_id + 1
+            next_state = _EpochState(
+                epoch_id=next_id,
+                stable_baseline=stable_baseline,
+                stable_fingerprint=stable_fingerprint,
+                baseline_volatile=volatile_text,
+                volatile_fingerprint=volatile_fingerprint,
+                volatile_part_fingerprints=parts,
+            )
+            admit = EpochAdmit(
+                kind="new_epoch",
+                epoch_id=next_id,
+                leading_system_text=self._leading(next_state),
+                mid_conversation_update="",
+                changed_sources=("epoch",),
+            )
+            return admit, next_state, False
+
+        state = self._state
+        if volatile_fingerprint == state.volatile_fingerprint:
+            admit = EpochAdmit(
+                kind="unchanged",
+                epoch_id=state.epoch_id,
+                leading_system_text=self._leading(state),
+                mid_conversation_update="",
+                changed_sources=(),
+            )
+            return admit, state, self._force_new
+
+        # Mid-epoch volatile update: keep leading baseline byte-identical for cache.
+        changed = _diff_source_names(state.volatile_part_fingerprints, parts)
+        next_state = dataclasses.replace(
+            state,
+            volatile_fingerprint=volatile_fingerprint,
+            volatile_part_fingerprints=parts,
+        )
+        admit = EpochAdmit(
+            kind="volatile_updated",
+            epoch_id=next_state.epoch_id,
+            leading_system_text=self._leading(next_state),
+            mid_conversation_update=_format_system_context_update(volatile_text),
+            changed_sources=changed,
+        )
+        return admit, next_state, self._force_new
+
+    @staticmethod
+    def _leading(state: _EpochState) -> str:
+        return f"{state.stable_baseline}{state.baseline_volatile}"
+
+
+def _diff_source_names(
+    prior: Mapping[str, str], current: Mapping[str, str]
+) -> tuple[str, ...]:
+    """Names of volatile sources whose fingerprint changed (added/removed/edited).
+
+    Falls back to the catch-all ``"volatile"`` when the caller didn't supply
+    per-source fingerprints (``current`` and ``prior`` both empty) — the
+    volatile text still changed (caller already checked the whole-text
+    fingerprint), we just can't attribute it to a named source.
+    """
+    names = sorted(set(prior) | set(current))
+    changed = tuple(name for name in names if prior.get(name) != current.get(name))
+    return changed or ("volatile",)
+
+
+def _format_system_context_update(volatile_text: str) -> str:
+    heading = SYSTEM_CONTEXT_UPDATE_HEADING.lstrip("\n")
+    body = volatile_text.lstrip("\n")
+    if not body.strip():
+        return (
+            f"{heading}"
+            "Volatile context sections (memory, skills, current request) were cleared."
+        )
+    return (
+        f"{heading}"
+        "The following replaces prior mid-epoch memory, skills, and current-request "
+        "sections for this conversation.\n\n"
+        f"{body}"
+    )