framework-agents 0.1.0__py3-none-any.whl

framework_agents/checkpoint.py

@@ -0,0 +1,231 @@
+"""Checkpointed HITL threads + local file locks.
+
+Parity: packages/typescript/src/checkpoint/index.ts — recreated after a
+build-script accident wiped the file; EVERY property below is load-bearing
+for tests (conversation sessions, gaps, pause/resume examples):
+
+- ThreadId is a single directory name under <root>/threads/: "", ".", ".."
+  and anything containing "/" raise THREAD_ID_INVALID (path traversal guard).
+- save() OVERWRITES thread_id/saved_at on the wire (camelCase JSON), forcing
+  ISO-8601 with ms precision ("2026-10-12T21:50:59.123Z").
+- Serialization is STRICT: non-JSON payload values (datetime, Path, models)
+  raise CHECKPOINT_SERIALIZABLE — never `default=str`, which would round-trip
+  Python reprs into tools on resume.
+- with_file_lock: O_CREAT|O_EXCL exclusive create; fresh lock -> "Lock held";
+  stale (>stale_ms, default 30000) -> unlink + retry; finally-unlock.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+import time
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Awaitable, Callable
+
+from .errors import AgentError
+from .types import ChatMessage, deserialize_messages
+
+
+def _iso_now() -> str:
+    now = datetime.now(timezone.utc)
+    return f"{now.strftime('%Y-%m-%dT%H:%M:%S')}.{int(now.microsecond / 1000):03d}Z"
+
+
+@dataclass
+class PendingCall:
+    """A suspended tool call awaiting a human decision."""
+
+    interrupt_id: str
+    tool: str
+    args: Any = None
+
+
+@dataclass
+class ThreadCheckpoint:
+    thread_id: str
+    saved_at: str
+    messages: list[Any] = field(default_factory=list)
+    state: dict[str, Any] = field(default_factory=dict)
+    pending: list[PendingCall] = field(default_factory=list)
+
+
+class Checkpointer:
+    """Protocol-style base: save/load/delete per threadId (duck-typed)."""
+
+    async def save(self, thread_id: str, checkpoint: ThreadCheckpoint) -> None:  # pragma: no cover
+        raise NotImplementedError
+
+    async def load(self, thread_id: str) -> ThreadCheckpoint | None:  # pragma: no cover
+        raise NotImplementedError
+
+    async def delete(self, thread_id: str) -> None:  # pragma: no cover
+        raise NotImplementedError
+
+
+def _validate_thread_id(thread_id: str) -> None:
+    if thread_id in ("", ".", "..") or "/" in thread_id or "\0" in thread_id:
+        raise AgentError("THREAD_ID_INVALID", f"Invalid threadId: {thread_id!r}", retryable=False)
+
+
+class FileCheckpointer(Checkpointer):
+    """JSON-file checkpointer: <root>/threads/<threadId>/checkpoint.json, lock-guarded."""
+
+    def __init__(self, root: str) -> None:
+        self.root = Path(root)
+
+    def _file(self, thread_id: str) -> Path:
+        _validate_thread_id(thread_id)
+        return self.root / "threads" / thread_id / "checkpoint.json"
+
+    def _lock(self, thread_id: str) -> Path:
+        _validate_thread_id(thread_id)
+        return self.root / "threads" / thread_id / ".lock"
+
+    async def save(self, thread_id: str, checkpoint: ThreadCheckpoint) -> None:
+        record = ThreadCheckpoint(
+            thread_id=thread_id,
+            saved_at=_iso_now(),
+            messages=[_dump_message(m) for m in checkpoint.messages],
+            state=dict(checkpoint.state or {}),
+            pending=[PendingCall(p.interrupt_id, p.tool, p.args) for p in (checkpoint.pending or [])],
+        )
+        try:
+            payload = json.dumps(
+                {
+                    "threadId": record.thread_id,
+                    "savedAt": record.saved_at,
+                    "messages": record.messages,
+                    "state": record.state,
+                    "pending": [
+                        {"interruptId": p.interrupt_id, "tool": p.tool, "args": p.args}
+                        for p in record.pending
+                    ],
+                }
+            )
+        except (TypeError, ValueError) as err:
+            # STRICT serialization: a datetime/Path in pending args would
+            # otherwise resume as its "__repr__ string" and crash the tool.
+            raise AgentError(
+                "CHECKPOINT_SERIALIZABLE",
+                f"Checkpoint for thread {thread_id!r} contains non-JSON values: {err}",
+                retryable=False,
+            ) from err
+
+        def write() -> None:
+            target = self._file(thread_id)
+            target.parent.mkdir(parents=True, exist_ok=True)
+            finite_retries = 3
+            for _ in range(finite_retries):
+                try:
+                    with open(target, "w", encoding="utf-8") as fh:
+                        fh.write(payload)
+                    return
+                except OSError:
+                    time.sleep(0.01)
+            raise AgentError("CHECKPOINT_WRITE", f"Could not write checkpoint for {thread_id!r}", retryable=True)
+
+        async def locked() -> None:
+            lock = self._lock(thread_id)
+
+            def body() -> None:
+                write()
+
+            await with_file_lock(lock, body)
+
+        await asyncio.to_thread(locked) if False else await locked()
+
+    async def load(self, thread_id: str) -> ThreadCheckpoint | None:
+        def read() -> ThreadCheckpoint | None:
+            try:
+                raw = self._file(thread_id).read_text(encoding="utf-8")
+            except (FileNotFoundError, NotADirectoryError):
+                return None
+            except OSError:
+                return None
+            try:
+                data = json.loads(raw)
+            except ValueError:
+                return None  # corrupt -> treat as absent (TS matches: JSON.parse try/catch)
+            pending = [
+                PendingCall(p.get("interruptId", ""), p.get("tool", ""), p.get("args"))
+                for p in (data.get("pending") or [])
+            ]
+            raw_messages = data.get("messages") or []
+            messages = [
+                m if isinstance(m, ChatMessage) else ChatMessage.model_validate(m)
+                for m in raw_messages
+            ]
+            return ThreadCheckpoint(
+                thread_id=data.get("threadId", thread_id),
+                saved_at=data.get("savedAt", ""),
+                messages=messages,
+                state=data.get("state") or {},
+                pending=pending,
+            )
+
+        return await asyncio.to_thread(read)
+
+    async def delete(self, thread_id: str) -> None:
+        def remove() -> None:
+            try:
+                self._file(thread_id).unlink()
+            except (FileNotFoundError, NotADirectoryError, OSError):
+                pass  # missing checkpoint is not an error (TS parity)
+
+        async def locked() -> None:
+            lock = self._lock(thread_id)
+            await with_file_lock(lock, remove)
+
+        await locked()
+
+
+def _dump_message(message: Any) -> Any:
+    dump = getattr(message, "model_dump", None)
+    if dump is not None:
+        return dump(by_alias=True, exclude_none=True)
+    return message
+
+
+async def with_file_lock(lock_path: Path | str, fn: Callable[[], Awaitable[Any] | Any], stale_ms: float = 30000) -> Any:
+    """Exclusive local lock via O_CREAT|O_EXCL. Stale locks (older than
+    stale_ms) are reclaimed. Single-machine correctness; distributed locking
+    is explicitly out of scope (TS parity, roadmap P3)."""
+    path = Path(lock_path)
+    remaining = 20  # bounded retry against reclaim races
+    while remaining > 0:
+        remaining -= 1
+        try:
+            path.parent.mkdir(parents=True, exist_ok=True)
+            fd = os.open(path, os.O_CREAT | os.O_EXCL | os.O_WRONLY)
+            os.close(fd)
+            break
+        except FileExistsError:
+            try:
+                age_ms = (time.time() - path.stat().st_mtime) * 1000
+            except FileNotFoundError:
+                continue  # raced with a releaser; retry acquisition
+            if age_ms < stale_ms:
+                raise RuntimeError(f"Lock held: {path}")  # plain error: callers may hold for a long time
+            try:
+                path.unlink()
+            except FileNotFoundError:
+                continue  # raced with another releaser
+        except OSError as err:
+            raise AgentError("LOCK_ERROR", f"Lock error on {path}: {err}", retryable=False) from err
+    else:
+        raise AgentError("LOCK_ERROR", f"Could not acquire lock: {path}", retryable=False)
+
+    try:
+        result = fn()
+        if asyncio.iscoroutine(result) or asyncio.isfuture(result):
+            return await result
+        return result
+    finally:
+        try:
+            path.unlink()
+        except FileNotFoundError:
+            pass  # already released or reclaimed; ignore (TS parity)

framework_agents/config.py

@@ -0,0 +1,200 @@
+"""Env config + provider factory. Parity: src/config + src/models/factory.
+
+Walk-up .env loading (cwd, then 3 parents), TogetherAI preferred when its
+key is set — same defaults as TS loadConfig/initChatModel.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from .models import ModelProvider
+from .models.openai_compatible import OpenAICompatibleOptions, OpenAICompatibleProvider
+from .models.anthropic import AnthropicOptions, AnthropicProvider
+from .models.ollama import OllamaOptions, OllamaProvider
+
+
+def parse_env_file(text: str) -> dict[str, str]:
+    """Parse .env text into key/value pairs.
+
+    Divergences fixed against the classic dotenv loaders (TS parity checks):
+    - ``export KEY=v`` (sh-style export prefix) is supported
+    - unquoted trailing comments are stripped: ``KEY=v # note`` -> ``v``
+    - duplicate keys within ONE file: LAST wins (the real process env still
+      wins over every file value — callers apply these with setdefault)
+    """
+    values: dict[str, str] = {}
+    for raw_line in text.splitlines():
+        line = raw_line.strip()
+        if not line or line.startswith("#") or "=" not in line:
+            continue
+        if line.startswith("export "):
+            line = line[len("export "):].strip()
+            if "=" not in line:
+                continue
+        key, _, value = line.partition("=")
+        key = key.strip()
+        value = value.strip()
+        if len(value) >= 2 and value[0] in "'\"" and value[-1] == value[0]:
+            value = value[1:-1]  # fully quoted: keep everything inside
+        elif " #" in value:
+            # Unquoted trailing comment: only " #" (hash after whitespace) so
+            # "a#b" values and quoted "# within value" stay intact.
+            value = value.split(" #", 1)[0].rstrip()
+        values[key] = value
+    return values
+
+
+def _try_setuptools_free_dotenv() -> None:  # minimal, dependency-free
+    import os
+
+    def load_env_file(path: Path) -> None:
+        try:
+            for key, value in parse_env_file(path.read_text(encoding="utf-8")).items():
+                # setdefault: real process env always wins over file values.
+                os.environ.setdefault(key, value)
+        except OSError:
+            pass
+
+    override = os.environ.get("FRAMEWORK_ENV_PATH")
+    if override:
+        load_env_file(Path(override))
+        return
+    load_env_file(Path.cwd() / ".env")
+    node = Path.cwd()
+    for _ in range(3):
+        node = node.parent
+        candidate = node / ".env"
+        if candidate.exists():
+            load_env_file(candidate)
+
+
+_ENV_LOADED = False
+
+
+def _ensure_env() -> None:
+    global _ENV_LOADED
+    if not _ENV_LOADED:
+        _try_setuptools_free_dotenv()
+        _ENV_LOADED = True
+
+
+_DEFAULTS = {
+    "TOGETHER_BASE_URL": "https://api.together.xyz/v1",
+    "TOGETHER_MODEL": "Qwen/Qwen3.5-9B",
+    "OPENAI_BASE_URL": "https://api.openai.com/v1",
+    "OPENAI_MODEL": "gpt-4o-mini",
+    "OLLAMA_BASE_URL": "http://localhost:11434/v1",
+    "OLLAMA_MODEL": "qwen2.5",
+}
+
+
+@dataclass
+class Config:
+    together_api_key: str
+    together_base_url: str
+    together_model: str
+    openai_api_key: str
+    openai_base_url: str
+    openai_model: str
+    anthropic_api_key: str
+    anthropic_base_url: str
+    anthropic_model: str
+    ollama_base_url: str
+    ollama_model: str
+
+    @property
+    def active(self) -> tuple[str, str, str, str]:
+        """(source, base_url, api_key, model) — Together wins when keyed."""
+        import os
+
+        if self.together_api_key:
+            return ("together", self.together_base_url, self.together_api_key, self.together_model)
+        return ("openai", self.openai_base_url, self.openai_api_key, self.openai_model)
+
+
+_cache: Config | None = None
+
+
+def load_config() -> Config:
+    global _cache
+    if _cache is None:
+        _ensure_env()
+        import os
+
+        _cache = Config(
+            together_api_key=os.environ.get("TOGETHER_API_KEY", ""),
+            together_base_url=os.environ.get("TOGETHER_BASE_URL", _DEFAULTS["TOGETHER_BASE_URL"]),
+            together_model=os.environ.get("TOGETHER_MODEL", _DEFAULTS["TOGETHER_MODEL"]),
+            openai_api_key=os.environ.get("OPENAI_API_KEY", ""),
+            openai_base_url=os.environ.get("OPENAI_BASE_URL", _DEFAULTS["OPENAI_BASE_URL"]),
+            openai_model=os.environ.get("OPENAI_MODEL", _DEFAULTS["OPENAI_MODEL"]),
+            anthropic_api_key=os.environ.get("ANTHROPIC_API_KEY", ""),
+            anthropic_base_url=os.environ.get("ANTHROPIC_BASE_URL", "https://api.anthropic.com"),
+            anthropic_model=os.environ.get("ANTHROPIC_MODEL", "claude-sonnet-4-6"),
+            ollama_base_url=os.environ.get("OLLAMA_BASE_URL", _DEFAULTS["OLLAMA_BASE_URL"]),
+            ollama_model=os.environ.get("OLLAMA_MODEL", _DEFAULTS["OLLAMA_MODEL"]),
+        )
+    return _cache
+
+
+def init_chat_model(
+    spec: str,
+    *,
+    api_key: str | None = None,
+    base_url: str | None = None,
+    max_tokens: int | None = None,
+    stream: bool = False,
+    thinking_budget: int | None = None,
+) -> ModelProvider:
+    """Resolve `provider:model` strings (bare ids default to together)."""
+    cfg = load_config()
+    provider, _, model = (spec if ":" in spec else f"together:{spec}").partition(":")
+    extra = OpenAICompatibleOptions(
+        base_url=base_url or "",
+        api_key=api_key or "",
+        model=model,
+        max_tokens=max_tokens,
+        stream=stream,
+    )
+    if provider == "together":
+        key = api_key or cfg.together_api_key
+        if not key:
+            raise ValueError("init_chat_model: set TOGETHER_API_KEY in .env (or pass api_key)")
+        return OpenAICompatibleProvider(
+            OpenAICompatibleOptions(base_url=base_url or cfg.together_base_url, api_key=key, model=model,
+                                    max_tokens=max_tokens, stream=stream)
+        )
+    if provider == "openai":
+        key = api_key or cfg.openai_api_key
+        if not key:
+            raise ValueError("init_chat_model: set OPENAI_API_KEY in .env (or pass api_key)")
+        return OpenAICompatibleProvider(
+            OpenAICompatibleOptions(base_url=base_url or cfg.openai_base_url, api_key=key, model=model,
+                                    max_tokens=max_tokens, stream=stream)
+        )
+    if provider == "anthropic":
+        key = api_key or cfg.anthropic_api_key
+        if not key:
+            raise ValueError("init_chat_model: set ANTHROPIC_API_KEY in .env (or pass api_key)")
+        return AnthropicProvider(AnthropicOptions(
+            api_key=key,
+            model=model,
+            base_url=base_url or cfg.anthropic_base_url,
+            max_tokens=max_tokens if max_tokens is not None else 1024,
+            stream=stream,
+            thinking_budget=thinking_budget,
+        ))
+    if provider == "ollama":
+        return OllamaProvider(OllamaOptions(
+            model=model,
+            base_url=base_url or cfg.ollama_base_url,
+            max_tokens=max_tokens,
+            stream=stream,
+        ))
+    if provider == "custom":
+        if not base_url or not api_key:
+            raise ValueError("init_chat_model: custom: needs base_url + api_key")
+        return OpenAICompatibleProvider(extra)
+    raise ValueError(f'init_chat_model: unknown provider "{provider}" (use together:|openai:|anthropic:|ollama:|custom:)')

framework_agents/conversation.py

@@ -0,0 +1,249 @@
+"""Conversation managers keep history within context limits.
+
+Parity: src/conversation/index.ts.
+
+- apply(): after-run management (before memory.save).
+- reduce(): explicit shrink (overflow recovery / proactive triggers).
+- before_model(): per-turn management inside the loop (sliding window).
+Pinned messages are never removed. Tool/assistant-tool_call pairs are
+never orphaned: trimming drops leading dangling messages.
+"""
+
+from __future__ import annotations
+
+import inspect
+import math
+import re
+from typing import Any, Callable, Protocol
+
+from .models import CompleteOptions, ModelProvider
+from .types import ChatMessage, TextBlock, ToolCallBlock, text_of
+
+Summarizer = Callable[[list[ChatMessage]], Any]  # str or awaitable str
+
+# Word-ish runs, numbers, single CJK chars, punctuation clusters — close to
+# subword behavior on prose (calibrated so estimate_tokens("abcd") == 1).
+_TOKEN_RE = re.compile(
+    r"[A-Za-z]+(?:'[A-Za-z]+)?|\d+(?:\.\d+)?|[一-鿿぀-ヿ가-힯]|[^A-Za-z\d\s]"
+)
+_WORD_RE = re.compile(r"[A-Za-z]+(?:'[A-Za-z]+)?$")
+_CJK_RE = re.compile(r"[一-鿿぀-ヿ가-힯]")
+
+
+def estimate_tokens(text: str) -> int:
+    """Local token estimate — dependency-free approximation, not a BPE."""
+    if not text:
+        return 0
+    tokens = 0
+    for w in _TOKEN_RE.findall(text):
+        if _CJK_RE.fullmatch(w):
+            tokens += 1
+        elif _WORD_RE.fullmatch(w):
+            tokens += max(1, math.ceil(len(w) / 5))
+        else:
+            tokens += 1
+    return tokens
+
+
+class ConversationManager(Protocol):
+    """History-shrinking hook set. removed_count tracks load skipped so far."""
+
+    name: str
+    removed_count: int
+
+    async def apply(self, messages: list[ChatMessage]) -> list[ChatMessage]: ...
+    async def reduce(self, messages: list[ChatMessage]) -> list[ChatMessage]: ...
+
+
+def _has_only_tool_calls(content: Any) -> bool:
+    if not isinstance(content, list):
+        return False
+    blocks = [
+        b
+        for b in content
+        if (b.get("type") if isinstance(b, dict) else b.type) == "tool_call"
+        or (
+            (b.get("type") if isinstance(b, dict) else b.type) == "text"
+            and ((b.get("text") if isinstance(b, dict) else b.text) or "").strip() == ""
+        )
+    ]
+    return len(blocks) > 0 and len(blocks) == len(content)
+
+
+def trim_dangling(messages: list[ChatMessage]) -> list[ChatMessage]:
+    """Drop leading messages that lost their pair (tool head, call-only
+    assistant head). Pinned messages stop the scan: they are keepers, not
+    orphans."""
+    i = 0
+    while i < len(messages):
+        m = messages[i]
+        if m.pinned:
+            break
+        if m.role == "tool":
+            i += 1
+            continue
+        if m.role == "assistant" and _has_only_tool_calls(m.content):
+            i += 1
+            continue
+        break
+    return messages[i:]
+
+
+def message_tokens(m: ChatMessage) -> int:
+    text = m.content if isinstance(m.content, str) else text_of(m.content)
+    return estimate_tokens(text)
+
+
+def history_tokens(messages: list[ChatMessage]) -> int:
+    return sum(message_tokens(m) for m in messages)
+
+
+class NullConversationManager:
+    """Keeps full history. Pass explicitly to disable the default window."""
+
+    name = "null"
+    removed_count = 0
+
+    async def apply(self, messages: list[ChatMessage]) -> list[ChatMessage]:
+        return list(messages)
+
+    async def reduce(self, messages: list[ChatMessage]) -> list[ChatMessage]:
+        return list(messages)
+
+    async def before_model(self, messages: list[ChatMessage], step: int) -> list[ChatMessage]:
+        return list(messages)
+
+
+class SlidingWindowConversationManager:
+    """Keep the newest `window_size` unpinned messages; pinned survive."""
+
+    name = "sliding-window"
+
+    def __init__(
+        self,
+        window_size: int = 40,
+        pin_first: int = 0,
+        per_turn: bool | int = False,
+    ) -> None:
+        self.window_size = max(1, window_size)
+        self.pin_first = max(0, pin_first)
+        self.per_turn = per_turn
+        self.removed_count = 0
+
+    @staticmethod
+    def _pin(messages: list[ChatMessage], pin_first: int) -> None:
+        for m in messages[: min(pin_first, len(messages))]:
+            m.pinned = True
+
+    def _trim(self, messages: list[ChatMessage]) -> list[ChatMessage]:
+        self._pin(messages, self.pin_first)
+        keep: set[int] = set()
+        rest: list[int] = []
+        for idx, m in enumerate(messages):
+            if m.pinned:
+                keep.add(idx)
+            else:
+                rest.append(idx)
+        dropped = max(0, len(rest) - self.window_size)
+        self.removed_count += dropped
+        keep.update(rest[dropped:])
+        # Merge in ORIGINAL order: hoisting pinned messages to the front would
+        # reorder the conversation whenever a mid-history message is pinned.
+        return trim_dangling([m for i, m in enumerate(messages) if i in keep])
+
+    async def apply(self, messages: list[ChatMessage]) -> list[ChatMessage]:
+        self._pin(messages, self.pin_first)
+        return self._trim(messages)
+
+    async def reduce(self, messages: list[ChatMessage]) -> list[ChatMessage]:
+        return self._trim(list(messages))
+
+    async def before_model(self, messages: list[ChatMessage], step: int) -> list[ChatMessage]:
+        if self.per_turn is False:
+            return messages
+        if isinstance(self.per_turn, int) and (step % self.per_turn != 0 or self.per_turn <= 0):
+            return messages
+        return self._trim(list(messages))
+
+
+class SummarizingConversationManager:
+    """Summarize the oldest fraction away into a single boundary message."""
+
+    name = "summarizing"
+
+    def __init__(
+        self,
+        summary_ratio: float = 0.3,
+        preserve_recent: int = 10,
+        pin_first: int = 0,
+        summarizer: Summarizer | None = None,
+        model: ModelProvider | None = None,
+        summary_prefix: str = "Summary of earlier conversation:",
+    ) -> None:
+        self.ratio = min(0.8, max(0.1, summary_ratio))
+        self.preserve_recent = max(1, preserve_recent)
+        self.pin_first = max(0, pin_first)
+        self.summarizer = summarizer
+        self.model = model
+        self.summary_prefix = summary_prefix
+        self.removed_count = 0
+        # Set when the last apply() summarized (tests/UI can assert on it).
+        self.last_summary: str | None = None
+
+    def _summarizable(self, messages: list[ChatMessage]) -> tuple[list[ChatMessage], list[ChatMessage]]:
+        self._pin(messages)
+        eligible_idx = [i for i, m in enumerate(messages) if not m.pinned]
+        count = min(
+            len(eligible_idx) - self.preserve_recent,
+            math.floor(len(eligible_idx) * self.ratio),
+        )
+        if count <= 0:
+            return [], list(messages)
+        cutoff = set(eligible_idx[:count])
+        head = [m for i, m in enumerate(messages) if i in cutoff]
+        tail = [m for i, m in enumerate(messages) if i not in cutoff]
+        return head, tail
+
+    def _pin(self, messages: list[ChatMessage]) -> None:
+        SlidingWindowConversationManager._pin(messages, self.pin_first)
+
+    def _transcript(self, messages: list[ChatMessage]) -> str:
+        return "\n".join(
+            f"[{m.role}] {m.content if isinstance(m.content, str) else text_of(m.content)}"
+            for m in messages
+        )
+
+    async def _summarize(self, head: list[ChatMessage]) -> str:
+        if self.summarizer is not None:
+            result = self.summarizer(head)
+            return await result if inspect.isawaitable(result) else result
+        if self.model is None:
+            # Extractive stub: first 200 chars of each message.
+            return "\n".join(
+                f"[{m.role}] {(m.content if isinstance(m.content, str) else text_of(m.content))[:200]}"
+                for m in head
+            )
+        completion = await self.model.complete(
+            CompleteOptions(
+                messages=[
+                    ChatMessage(
+                        role="user",
+                        content=f"Summarize concisely, preserving decisions, names, tool outcomes:\n{self._transcript(head)}",
+                    )
+                ],
+                tools=[],
+            )
+        )
+        return completion.text
+
+    async def apply(self, messages: list[ChatMessage]) -> list[ChatMessage]:
+        head, tail = self._summarizable(messages)
+        if not head:
+            return list(messages)
+        summary = await self._summarize(head)
+        self.last_summary = summary
+        self.removed_count += len(head) - 1
+        return [ChatMessage(role="assistant", content=f"{self.summary_prefix}\n{summary}"), *trim_dangling(tail)]
+
+    async def reduce(self, messages: list[ChatMessage]) -> list[ChatMessage]:
+        return list(messages)