everalgo-agent-memory 0.1.0__py3-none-any.whl

everalgo/agent_memory/__init__.py

@@ -0,0 +1,16 @@
+"""Agent-side memory extractors — 2 Extractors + boundary facade."""
+
+import logging
+
+from everalgo.agent_memory.boundary import AgentBoundaryDetector
+from everalgo.agent_memory.case import AgentCaseExtractor
+from everalgo.agent_memory.skill import AgentSkillExtractor
+
+__all__ = [
+    "AgentBoundaryDetector",
+    "AgentCaseExtractor",
+    "AgentSkillExtractor",
+]
+
+# Library logging setup (ADR-013): NullHandler on each subpackage logger.
+logging.getLogger(__name__).addHandler(logging.NullHandler())

everalgo/agent_memory/_text.py

@@ -0,0 +1,52 @@
+"""Token-aware text utilities for agent_memory extractors (head/tail truncation, json_default)."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any
+
+from everalgo._tokenize import _get_tokenizer, count_tokens
+
+__all__ = ["count_tokens", "json_default", "truncate_text"]
+
+
+def truncate_text(
+    text: str,
+    max_tokens: int,
+    *,
+    head_ratio: float = 0.7,
+    suffix: str | None = None,
+) -> str:
+    r"""Truncate ``text`` to ``max_tokens`` tokens, preserving head + tail with a marker.
+
+    When ``suffix`` is ``None``: keep ``head_ratio`` of tokens from the start and the remainder from
+    the end, joined by ``"\\n[... trimmed N tokens ...]\\n"`` (or ``"..."`` when ``head_ratio == 1.0``).
+    When ``suffix`` is set: keep the head only and append ``suffix``.
+    Short / empty inputs are returned unchanged.
+    """
+    if not text:
+        return text
+    tokenizer = _get_tokenizer()
+    tokens = tokenizer.encode(text)
+    if len(tokens) <= max_tokens:
+        return text
+
+    if suffix is not None:
+        head = tokenizer.decode(tokens[:max_tokens])
+        return head.rstrip() + suffix
+
+    head_count = int(max_tokens * head_ratio)
+    tail_count = max_tokens - head_count
+    head_text = tokenizer.decode(tokens[:head_count])
+    if tail_count <= 0:
+        return head_text.rstrip() + "..."
+    tail_text = tokenizer.decode(tokens[-tail_count:])
+    trimmed = len(tokens) - max_tokens
+    return f"{head_text}\n[... trimmed {trimmed} tokens ...]\n{tail_text}"
+
+
+def json_default(obj: Any) -> Any:
+    """``json.dumps(default=...)`` fallback: datetime → ISO string, anything else → ``str``."""
+    if isinstance(obj, datetime):
+        return obj.isoformat()
+    return str(obj)

everalgo/agent_memory/boundary.py

@@ -0,0 +1,129 @@
+"""Agent trajectory boundary detection facade.
+
+Wraps the low-level ``everalgo.boundary.detect_boundaries`` primitive with a filter → detect → remap
+pipeline to handle mixed trajectories (``ChatMessage`` + ``ToolCallRequest`` + ``ToolCallResult``).
+
+Tool items are filtered out before the LLM detection step so the LLM sees a clean conversation
+view; boundary indices from the chat-only result are then remapped back to the original
+``ConversationItem`` index space so that the output ``MemCell.items`` preserves the full
+trajectory (including tool calls).
+
+Uses explicit composition rather than inheritance: filter → detect → remap layers are separate
+functions rather than an extended class hierarchy.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING
+
+from asgiref.sync import async_to_sync
+
+from everalgo.boundary import DetectionResult, detect_boundaries
+from everalgo.types import ChatMessage, MemCell
+
+if TYPE_CHECKING:
+    from everalgo.llm.protocols import LLMClient
+    from everalgo.types import ConversationItem
+
+logger = logging.getLogger(__name__)
+
+__all__ = ["AgentBoundaryDetector"]
+
+
+class AgentBoundaryDetector:
+    """Boundary detection on an agent trajectory (mixed ``ConversationItem`` list).
+
+    The filter → detect → remap pipeline:
+
+    1. **Filter** — extract only ``ChatMessage`` items and remember their original indices.
+    2. **Detect** — run ``everalgo.boundary.detect_boundaries`` on the chat-only view.
+    3. **Remap** — translate chat-space cell boundaries back to the original ``ConversationItem``
+       index space; ``ToolCallRequest`` / ``ToolCallResult`` items between adjacent chat
+       messages are folded into the cell that contains the preceding chat message.
+
+    Invariant: ``sum(len(c.items) for c in result.cells) + len(result.tail) == len(items)``.
+
+    The LLM client is bound to the instance at construction time.
+    """
+
+    def __init__(self, *, llm: LLMClient) -> None:
+        self._llm = llm
+
+    async def adetect(
+        self,
+        items: list[ConversationItem],
+        *,
+        is_final: bool = False,
+        prompt: str | None = None,
+    ) -> DetectionResult:
+        """Detect boundaries on a mixed agent trajectory.
+
+        Args:
+            items: Ordered ``ConversationItem`` list for one trajectory slice — may contain
+                ``ChatMessage``, ``ToolCallRequest``, and ``ToolCallResult`` in any mix.
+            is_final: When ``True``, the caller guarantees no more items will arrive; trailing tool items
+                after the last cell's final chat message are folded into that cell rather than the tail.
+                When ``False`` (default), trailing tool items go to the tail.
+            prompt: Per-call boundary detection prompt override; ``None`` uses the built-in default.
+
+        Returns:
+            ``cells`` — remapped ``MemCell`` list preserving tool calls inside each cell.
+            ``tail`` — remainder items (not yet committed to a cell) for the non-final case.
+        """
+        chat_items: list[ChatMessage] = []
+        chat_to_orig: list[int] = []
+        for orig_idx, item in enumerate(items):
+            if isinstance(item, ChatMessage):
+                chat_items.append(item)
+                chat_to_orig.append(orig_idx)
+
+        if not chat_items:
+            # No chat messages → no LLM signal; everything goes to tail per should_wait semantics.
+            logger.debug("adetect: no ChatMessage items in trajectory (n_items=%d)", len(items))
+            return DetectionResult(cells=[], tail=list(items))  # type: ignore[arg-type]
+
+        chat_result = await detect_boundaries(chat_items, llm=self._llm, is_final=is_final, prompt=prompt)
+
+        remapped_cells: list[MemCell] = []
+        chat_cursor = 0
+        for cell in chat_result.cells:
+            cell_chat_count = len(cell.items)
+            start_chat_idx = chat_cursor
+            end_chat_idx = chat_cursor + cell_chat_count - 1
+            chat_cursor += cell_chat_count
+
+            start_orig = chat_to_orig[start_chat_idx]
+
+            if chat_cursor < len(chat_to_orig):
+                # More cells follow: include everything up to (exclusive) the next cell's first chat.
+                end_orig_exclusive = chat_to_orig[chat_cursor]
+            elif is_final:
+                # Last cell, caller says stream is done: absorb all remaining items.
+                end_orig_exclusive = len(items)
+            else:
+                # Last cell, stream is ongoing: include only up to (inclusive) the last chat in
+                # this cell; trailing tool items go to the tail so they can be re-processed.
+                end_orig_exclusive = chat_to_orig[end_chat_idx] + 1
+
+            remapped_cells.append(MemCell(items=list(items[start_orig:end_orig_exclusive]), timestamp=cell.timestamp))
+
+        # Tail: items after the last consumed original index.
+        if remapped_cells:
+            if is_final:
+                last_consumed_exclusive = len(items)
+            elif chat_cursor < len(chat_to_orig):
+                last_consumed_exclusive = chat_to_orig[chat_cursor]
+            else:
+                # chat_cursor == len(chat_to_orig): all chats consumed; last cell boundary already
+                # set to chat_to_orig[end_chat_idx] + 1, so tail starts right after.
+                last_consumed_exclusive = chat_to_orig[-1] + 1
+            tail = list(items[last_consumed_exclusive:])
+        else:
+            # detect_boundaries returned no cells — everything is tail.
+            tail = list(items)
+
+        return DetectionResult(cells=remapped_cells, tail=tail)  # type: ignore[arg-type]
+
+    detect = async_to_sync(adetect)
+    """Sync bridge — only callable from non-event-loop contexts."""