framework-agents 0.1.0__py3-none-any.whl

framework_agents/memory.py

@@ -0,0 +1,103 @@
+"""Memory: append + window. Parity: src/memory/index.ts (post-fix).
+
+Pinned semantics (the TS sweep found these the hard way):
+- save() APPENDS (windows to max); the agent loop does CLEAR-then-SAVE, never
+  plain save, or every run duplicates the transcript.
+- FileMemory: corrupted files fail LOUDLY (MEMORY_CORRUPT) instead of wiping
+  whatever is still on disk on the next save; missing file = fresh memory.
+- tmp file per flush is unique — concurrent flushes can't race on rename.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import tempfile
+from pathlib import Path
+from typing import Protocol
+
+from .errors import AgentError
+from .types import ChatMessage, deserialize_messages, serialize_messages
+
+
+class Memory(Protocol):
+    async def load(self) -> list[ChatMessage]: ...
+    async def save(self, messages: list[ChatMessage]) -> None: ...
+    async def clear(self) -> None: ...
+
+
+class InMemoryMemory:
+    def __init__(self, max_messages: int = 50) -> None:
+        self._messages: list[ChatMessage] = []
+        self.max_messages = max_messages
+
+    async def load(self) -> list[ChatMessage]:
+        return list(self._messages)
+
+    async def save(self, messages: list[ChatMessage]) -> None:
+        self._messages = [*self._messages, *messages][-self.max_messages:]
+
+    async def clear(self) -> None:
+        self._messages = []
+
+
+class FileMemory:
+    """JSON-file backed memory: same windowing as in-memory, atomic writes."""
+
+    _MAX_UTF16_UNITS = 2048
+
+    def __init__(self, directory: str, max_messages: int = 50) -> None:
+        self.directory = Path(directory)
+        self.file = self.directory / "memory.json"
+        self.max_messages = max_messages
+        self._cache: list[ChatMessage] | None = None
+
+    async def load(self) -> list[ChatMessage]:
+        return list(await self._read_all())
+
+    async def save(self, messages: list[ChatMessage]) -> None:
+        all_messages = [*(await self._read_all()), *messages][-self.max_messages:]
+        self._cache = all_messages
+        await self._flush()
+
+    async def clear(self) -> None:
+        self._cache = []
+        await self._flush()
+
+    async def _read_all(self) -> list[ChatMessage]:
+        if self._cache is not None:
+            return self._cache
+        try:
+            raw = self.file.read_text(encoding="utf-8")
+        except FileNotFoundError:
+            self._cache = []
+            return self._cache
+        except OSError as err:
+            self._cache = []
+            return self._cache
+        try:
+            data = json.loads(raw)
+            # Valid JSON with the WRONG shape is still corrupt data. TS
+            # throws here (deserializeMessages rejects non-arrays); silently
+            # treating a dict as "empty" would clobber the file on save.
+            if not isinstance(data, list):
+                raise ValueError("top-level JSON is not a message array")
+            self._cache = deserialize_messages(data)
+        except (ValueError, TypeError) as err:
+            # Corrupted file must FAIL loudly: returning [] would make the
+            # next save overwrite whatever was still on disk.
+            raise AgentError("MEMORY_CORRUPT", f"Memory file is not valid JSON for messages ({self.file}): {err}", retryable=False) from err
+        return self._cache
+
+    async def _flush(self) -> None:
+        self.directory.mkdir(parents=True, exist_ok=True)
+        # Unique tmp per flush: concurrent saves sharing one fixed name race
+        # on the rename and can publish a torn or half-written file.
+        fd, tmp_path = tempfile.mkstemp(dir=self.directory, prefix="memory.json.", suffix=".tmp")
+        try:
+            with os.fdopen(fd, "w", encoding="utf-8") as fh:
+                json.dump(serialize_messages(self._cache or []), fh)
+            os.replace(tmp_path, self.file)
+        finally:
+            if os.path.exists(tmp_path):  # replace succeeded -> gone already
+                os.unlink(tmp_path)

framework_agents/memory_compaction.py

@@ -0,0 +1,63 @@
+"""Compaction: keep long runs inside the context window without losing meaning.
+
+Parity: src/memory/compaction.ts.
+
+Strategy (P1): oldest messages -> model/pluggable summarizer -> single
+boundary message.
+"""
+
+from __future__ import annotations
+
+import inspect
+from typing import Any, Callable
+
+from .memory import Memory
+from .types import ChatMessage, text_of
+
+SummarizeFn = Callable[[list[ChatMessage]], Any]  # str or awaitable str
+
+
+def default_summarize(messages: list[ChatMessage]) -> str:
+    """Extractive stub: first five non-system messages, 200 chars each."""
+    head = "\n".join(
+        f"[{m.role}] {text_of(m.content)[:200]}"
+        for m in [m for m in messages if m.role != "system"][:5]
+    )
+    return f"Prior context summary ({len(messages)} msgs):\n{head}"
+
+
+class CompactedMemory:
+    """Wrap any Memory with auto-compaction on save."""
+
+    def __init__(
+        self,
+        inner: Memory,
+        max_messages: int = 40,
+        summarize: SummarizeFn | None = None,
+    ) -> None:
+        self.inner = inner
+        self.max_messages = max_messages
+        self.summarize = summarize
+
+    async def load(self) -> list[ChatMessage]:
+        return await self.inner.load()
+
+    async def save(self, messages: list[ChatMessage]) -> None:
+        await self.inner.save(messages)
+        max = self.max_messages
+        current = await self.inner.load()
+        if len(current) <= max:
+            return
+        summarize = self.summarize or default_summarize
+        # Overflow is replaced by ONE summary message so the stored history
+        # shrinks back to exactly `max` (1 summary + max-1 newest).
+        overflow = current[: len(current) - max + 1]
+        rest = current[len(current) - max + 1 :]
+        summary = summarize(overflow)
+        if inspect.isawaitable(summary):
+            summary = await summary
+        await self.inner.clear()
+        await self.inner.save([ChatMessage(role="assistant", content=summary), *rest])
+
+    async def clear(self) -> None:
+        await self.inner.clear()