@smilintux/skcapstone 0.1.0 → 0.2.3

package/src/skcapstone/context_window.py

@@ -0,0 +1,314 @@
+"""
+ContextWindowManager — per-sender token tracking and history compression.
+
+Tracks cumulative token usage for each sender's conversation history.
+When a sender's history reaches 80% of ``max_context_tokens``, the oldest
+messages are summarised into a single paragraph by the LLM and replaced in
+the ConversationStore, keeping only the most recent ``_KEEP_RECENT``
+messages verbatim.
+
+Token counting: uses ``tiktoken`` (cl100k_base) when installed, otherwise
+falls back to ``len(content) // 4`` (the same char-based estimate used
+throughout the rest of skcapstone).
+
+Usage (inside ConsciousnessLoop)::
+
+    ctx_mgr = ContextWindowManager(home, config.max_context_tokens)
+    # After storing a new assistant reply:
+    ctx_mgr.check_and_compress(sender, conv_store, bridge)
+    # Via MCP tool:
+    stats = ctx_mgr.get_all_stats(conv_store)
+"""
+
+from __future__ import annotations
+
+import logging
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Optional, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .conversation_store import ConversationStore
+
+logger = logging.getLogger("skcapstone.context_window")
+
+# System prompt for the compression LLM call
+_SUMMARIZE_SYSTEM_PROMPT = (
+    "You are a concise summarization assistant for a sovereign AI agent framework. "
+    "Summarize the following conversation history into exactly one paragraph (3-5 sentences). "
+    "Capture: the main topics discussed, any decisions or outcomes reached, and the overall tone. "
+    "This summary replaces older messages to free up context window space. "
+    "Be factual and direct. Do not use bullet points or headers."
+)
+
+# How many recent messages to keep verbatim (not included in summarization)
+_KEEP_RECENT = 4
+
+# Context window fill threshold that triggers compression (80 %)
+_THRESHOLD_PCT = 0.80
+
+
+# ---------------------------------------------------------------------------
+# Token helpers (module-level, reusable)
+# ---------------------------------------------------------------------------
+
+
+def count_tokens(text: str) -> int:
+    """Count tokens in *text*.
+
+    Uses ``tiktoken`` (cl100k_base encoding) when the package is installed.
+    Falls back to ``max(1, len(text) // 4)`` (4 chars ≈ 1 token) otherwise.
+
+    Args:
+        text: Input text.
+
+    Returns:
+        Token count (always >= 1 for non-empty input).
+    """
+    try:
+        import tiktoken  # optional dep
+        enc = tiktoken.get_encoding("cl100k_base")
+        return max(1, len(enc.encode(text)))
+    except ImportError:
+        return max(1, len(text) // 4)
+
+
+def count_history_tokens(history: list[dict]) -> int:
+    """Sum token counts for all messages in a history list.
+
+    Args:
+        history: List of message dicts, each expected to have a ``"content"`` key.
+
+    Returns:
+        Total token estimate across all messages.
+    """
+    return sum(count_tokens(str(msg.get("content", ""))) for msg in history)
+
+
+# ---------------------------------------------------------------------------
+# ContextWindowManager
+# ---------------------------------------------------------------------------
+
+
+class ContextWindowManager:
+    """Tracks per-sender token usage and compresses history at the 80 % threshold.
+
+    Maintains an in-memory stats table for every peer that has been checked.
+    Stats are refreshed on every :meth:`check_and_compress` call and after a
+    successful compression.
+
+    Args:
+        home: Agent home directory (used for any future persistence needs).
+        max_context_tokens: Model context window token budget.  The
+            compression threshold is set to 80 % of this value.
+    """
+
+    def __init__(self, home: Path, max_context_tokens: int = 8000) -> None:
+        self._home = Path(home)
+        self._max_context_tokens = max_context_tokens
+        self._threshold = int(max_context_tokens * _THRESHOLD_PCT)
+        # peer -> stats snapshot
+        self._stats: dict[str, dict] = {}
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    def check_and_compress(
+        self,
+        peer: str,
+        store: "ConversationStore",
+        bridge=None,
+    ) -> bool:
+        """Check peer history token count; compress if at or over threshold.
+
+        Loads the full history for *peer* from *store*, counts tokens, and
+        updates the in-memory stats table.  When the count meets or exceeds
+        the 80 % threshold and *bridge* is provided, the oldest messages are
+        summarised by the LLM (keeping ``_KEEP_RECENT`` verbatim) and the
+        history is atomically replaced on disk via
+        :meth:`ConversationStore.replace`.
+
+        Args:
+            peer: Sanitised peer name.
+            store: :class:`~skcapstone.conversation_store.ConversationStore`
+                instance for reading/writing history.
+            bridge: :class:`~skcapstone.consciousness_loop.LLMBridge` used to
+                generate the summary.  If ``None`` compression is skipped but
+                stats are still updated.
+
+        Returns:
+            ``True`` if the history was compressed, ``False`` otherwise.
+        """
+        history = store.load(peer)
+        token_count = count_history_tokens(history)
+
+        self._stats[peer] = {
+            "tokens": token_count,
+            "messages": len(history),
+            "threshold": self._threshold,
+            "max_context_tokens": self._max_context_tokens,
+            "pct_used": round(token_count / self._max_context_tokens * 100, 1),
+            "last_compressed_at": self._stats.get(peer, {}).get("last_compressed_at"),
+        }
+
+        if token_count < self._threshold:
+            return False
+
+        if bridge is None:
+            logger.warning(
+                "Context window at %.1f%% for %s but no bridge — skipping compression",
+                self._stats[peer]["pct_used"],
+                peer,
+            )
+            return False
+
+        if len(history) <= _KEEP_RECENT:
+            logger.debug(
+                "Context window at %.1f%% for %s but only %d messages — skipping",
+                self._stats[peer]["pct_used"],
+                peer,
+                len(history),
+            )
+            return False
+
+        to_summarize = history[:-_KEEP_RECENT]
+        recent = history[-_KEEP_RECENT:]
+
+        logger.info(
+            "Context window %.1f%% for %s — compressing %d older messages",
+            self._stats[peer]["pct_used"],
+            peer,
+            len(to_summarize),
+        )
+
+        summary_text = self._call_llm_summarize(peer, to_summarize, bridge)
+        if not summary_text:
+            logger.warning("LLM summarization returned empty result for %s — skipping", peer)
+            return False
+
+        now = datetime.now(timezone.utc).isoformat()
+        summary_entry: dict = {
+            "role": "system",
+            "content": (
+                f"[Earlier context — {len(to_summarize)} messages summarized]: {summary_text}"
+            ),
+            "timestamp": now,
+            "is_summary": True,
+            "summarized_count": len(to_summarize),
+        }
+        new_history = [summary_entry] + recent
+        store.replace(peer, new_history)
+
+        new_token_count = count_history_tokens(new_history)
+        self._stats[peer].update(
+            {
+                "tokens": new_token_count,
+                "messages": len(new_history),
+                "pct_used": round(new_token_count / self._max_context_tokens * 100, 1),
+                "last_compressed_at": now,
+            }
+        )
+        logger.info(
+            "Context compressed for %s: %d→%d messages, %d→%d tokens (%.1f%%)",
+            peer,
+            len(history),
+            len(new_history),
+            token_count,
+            new_token_count,
+            self._stats[peer]["pct_used"],
+        )
+        return True
+
+    def update_stats(self, peer: str, store: "ConversationStore") -> dict:
+        """Refresh and return stats for *peer* without triggering compression.
+
+        Args:
+            peer: Peer name.
+            store: :class:`~skcapstone.conversation_store.ConversationStore`.
+
+        Returns:
+            Stats dict for this peer.
+        """
+        history = store.load(peer)
+        token_count = count_history_tokens(history)
+        self._stats[peer] = {
+            "tokens": token_count,
+            "messages": len(history),
+            "threshold": self._threshold,
+            "max_context_tokens": self._max_context_tokens,
+            "pct_used": round(token_count / self._max_context_tokens * 100, 1),
+            "last_compressed_at": self._stats.get(peer, {}).get("last_compressed_at"),
+        }
+        return self._stats[peer]
+
+    def get_all_stats(
+        self, store: Optional["ConversationStore"] = None
+    ) -> dict[str, dict]:
+        """Return current stats for all tracked senders.
+
+        When *store* is provided any peers that have on-disk history but are
+        not yet in the in-memory stats table (e.g. written by a previous
+        process) are lazily loaded and included.
+
+        Args:
+            store: Optional :class:`~skcapstone.conversation_store.ConversationStore`
+                used to discover and load previously unseen peers.
+
+        Returns:
+            Mapping of peer name → stats dict.
+        """
+        if store is not None:
+            for peer in store.all_peers():
+                if peer not in self._stats:
+                    self.update_stats(peer, store)
+        return dict(self._stats)
+
+    # ------------------------------------------------------------------
+    # Private helpers
+    # ------------------------------------------------------------------
+
+    def _call_llm_summarize(
+        self, peer: str, messages: list[dict], bridge
+    ) -> str:
+        """Call *bridge* to produce a one-paragraph summary of *messages*.
+
+        Args:
+            peer: Peer name (included in the summarisation prompt for context).
+            messages: Older messages to summarise.
+            bridge: :class:`~skcapstone.consciousness_loop.LLMBridge`.
+
+        Returns:
+            Summary string, or empty string on any failure.
+        """
+        try:
+            from .model_router import TaskSignal
+
+            lines = [f"Conversation with {peer} ({len(messages)} messages to summarize):"]
+            lines.append("")
+            for msg in messages:
+                role = msg.get("role", "unknown")
+                content = str(msg.get("content", "")).strip()
+                # Skip existing summary sentinels (nested compression guard)
+                if msg.get("is_summary"):
+                    lines.append(f"[Previous summary]: {content}")
+                    continue
+                label = "Agent" if role == "assistant" else peer.capitalize()
+                lines.append(f"{label}: {content}")
+            lines.append("")
+            lines.append(
+                "Summarize the above into one paragraph (3-5 sentences). "
+                "Preserve key topics, decisions, and tone."
+            )
+            prompt_text = "\n".join(lines)
+
+            signal = TaskSignal(
+                description="Compress conversation context window",
+                tags=["summary", "context"],
+                estimated_tokens=count_tokens(prompt_text),
+            )
+            result = bridge.generate(_SUMMARIZE_SYSTEM_PROMPT, prompt_text, signal)
+            return result or ""
+        except Exception as exc:
+            logger.warning("Context compression LLM call failed for %s: %s", peer, exc)
+            return ""

package/src/skcapstone/conversation_manager.py

@@ -0,0 +1,238 @@
+"""
+ConversationManager — centralized manager for all peer conversation histories.
+
+Owns the {home}/conversations/ directory. Provides a clean API for adding,
+retrieving, searching, and exporting conversations instead of ad-hoc file
+writes scattered across the codebase.
+
+Used by ConsciousnessLoop (via SystemPromptBuilder) and daemon API endpoints.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import re
+from collections import defaultdict
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Optional
+
+logger = logging.getLogger("skcapstone.conversation_manager")
+
+# Allowlist for peer name characters (alphanumeric + safe punctuation)
+_PEER_NAME_SAFE_RE = re.compile(r"[^a-zA-Z0-9_\-@\.]")
+
+
+def _sanitize_peer_name(peer: str) -> str:
+    """Sanitize a peer name for safe use as a filesystem key.
+
+    Strips path separators (/ \\), null bytes, and any character not in the
+    alphanumeric + ``-_@.`` set. Caps length at 64 characters. Returns
+    ``"unknown"`` if the result would be empty.
+
+    Args:
+        peer: Raw peer name.
+
+    Returns:
+        Filesystem-safe peer name, at most 64 characters long.
+    """
+    if not peer or not isinstance(peer, str):
+        return "unknown"
+    sanitized = peer.replace("\x00", "").replace("/", "").replace("\\", "")
+    sanitized = _PEER_NAME_SAFE_RE.sub("", sanitized)
+    sanitized = sanitized.strip(".")
+    return sanitized[:64] or "unknown"
+
+
+class ConversationManager:
+    """Centralized manager for all peer conversation histories.
+
+    Stores conversations as JSON files under {home}/conversations/{peer}.json.
+    Provides atomic writes, in-memory caching, search, and export.
+
+    Args:
+        home: Agent home directory (~/.skcapstone).
+        max_history_messages: Maximum messages to retain per peer in memory
+            and on disk.
+    """
+
+    def __init__(self, home: Path, max_history_messages: int = 10) -> None:
+        self._home = Path(home)
+        self._conversations_dir = self._home / "conversations"
+        self._max_history_messages = max_history_messages
+        self._history: dict[str, list[dict]] = defaultdict(list)
+        self._load_all()
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    def list_peers(self) -> list[dict]:
+        """List all peers that have conversation history.
+
+        Returns:
+            List of summary dicts, each with keys:
+            ``peer``, ``message_count``, ``last_message_time``,
+            ``last_message_preview``. Sorted most-recent-first.
+        """
+        peers = []
+        for peer, messages in self._history.items():
+            if not messages:
+                continue
+            last = messages[-1]
+            peers.append({
+                "peer": peer,
+                "message_count": len(messages),
+                "last_message_time": last.get("timestamp"),
+                "last_message_preview": last.get("content", "")[:80],
+            })
+        peers.sort(key=lambda p: p["last_message_time"] or "", reverse=True)
+        return peers
+
+    def get_history(self, peer: str) -> list[dict]:
+        """Get full conversation history for a peer.
+
+        Args:
+            peer: Peer agent name.
+
+        Returns:
+            List of message dicts with ``role``, ``content``, ``timestamp``.
+            Returns an empty list if the peer is unknown.
+        """
+        peer = _sanitize_peer_name(peer)
+        return list(self._history.get(peer, []))
+
+    def add_message(self, peer: str, role: str, content: str) -> dict:
+        """Add a message to the peer's conversation history.
+
+        Appends to in-memory history, caps at ``max_history_messages``, and
+        atomically persists to disk.
+
+        Args:
+            peer: Peer agent name.
+            role: ``"user"`` or ``"assistant"``.
+            content: Message content.
+
+        Returns:
+            The message dict that was stored (includes ``timestamp``).
+        """
+        peer = _sanitize_peer_name(peer)
+        msg: dict = {
+            "role": role,
+            "content": content,
+            "timestamp": datetime.now(timezone.utc).isoformat(),
+        }
+        self._history[peer].append(msg)
+        if len(self._history[peer]) > self._max_history_messages:
+            self._history[peer] = self._history[peer][-self._max_history_messages:]
+        self._persist(peer)
+        return msg
+
+    def search(self, query: str) -> list[dict]:
+        """Search for a query string across all conversation histories.
+
+        Case-insensitive substring match against message content.
+
+        Args:
+            query: Search string.
+
+        Returns:
+            List of match dicts, each with ``peer``, ``role``, ``content``,
+            ``timestamp``.
+        """
+        query_lower = query.lower()
+        matches: list[dict] = []
+        for peer, messages in self._history.items():
+            for msg in messages:
+                if query_lower in msg.get("content", "").lower():
+                    matches.append({
+                        "peer": peer,
+                        "role": msg.get("role"),
+                        "content": msg.get("content"),
+                        "timestamp": msg.get("timestamp"),
+                    })
+        return matches
+
+    def export_all(self) -> dict[str, list[dict]]:
+        """Export all conversations as a plain dict.
+
+        Returns:
+            Dict mapping peer name → list of message dicts.
+            Peers with no messages are excluded.
+        """
+        return {peer: list(msgs) for peer, msgs in self._history.items() if msgs}
+
+    def delete(self, peer: str) -> bool:
+        """Delete a peer's conversation history from memory and disk.
+
+        Args:
+            peer: Peer agent name.
+
+        Returns:
+            ``True`` if the conversation existed and was deleted.
+        """
+        peer = _sanitize_peer_name(peer)
+        existed = bool(self._history.pop(peer, None))
+        target = self._conversations_dir / f"{peer}.json"
+        if target.exists():
+            target.unlink()
+            return True
+        return existed
+
+    def format_history_for_prompt(self, peer: str, max_messages: int = 10) -> str:
+        """Format recent conversation history for inclusion in a system prompt.
+
+        Args:
+            peer: Peer agent name.
+            max_messages: Maximum messages to include.
+
+        Returns:
+            Formatted history string, or empty string if no history.
+        """
+        history = self._history.get(peer, [])
+        if not history:
+            return ""
+        recent = history[-max_messages:]
+        lines = [f"Recent conversation with {peer}:"]
+        for msg in recent:
+            role = msg.get("role", "?")
+            content = msg.get("content", "")[:200]
+            lines.append(f"  [{role}] {content}")
+        return "\n".join(lines)
+
+    # ------------------------------------------------------------------
+    # Private helpers
+    # ------------------------------------------------------------------
+
+    def _load_all(self) -> None:
+        """Load all peer conversation files from the conversations directory."""
+        if not self._conversations_dir.exists():
+            return
+        for conv_file in self._conversations_dir.glob("*.json"):
+            peer = conv_file.stem
+            try:
+                data = json.loads(conv_file.read_text(encoding="utf-8"))
+                if isinstance(data, list):
+                    self._history[peer] = data[-self._max_history_messages:]
+            except Exception as exc:
+                logger.debug("Failed to load conversation %s: %s", conv_file, exc)
+
+    def _persist(self, peer: str) -> None:
+        """Atomically write peer history to {home}/conversations/{peer}.json.
+
+        Uses a temp file + rename for atomic update, preventing corruption if
+        the process is interrupted mid-write.
+
+        Args:
+            peer: Peer agent name (already sanitized).
+        """
+        try:
+            self._conversations_dir.mkdir(parents=True, exist_ok=True)
+            target = self._conversations_dir / f"{peer}.json"
+            tmp = target.with_suffix(".json.tmp")
+            payload = json.dumps(self._history[peer], ensure_ascii=False, indent=2)
+            tmp.write_text(payload, encoding="utf-8")
+            tmp.replace(target)
+        except Exception as exc:
+            logger.debug("Failed to persist conversation for %s: %s", peer, exc)