selectools 0.16.4__tar.gz → 0.16.6__tar.gz

{selectools-0.16.4/src/selectools.egg-info → selectools-0.16.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: selectools
-Version: 0.16.4
+Version: 0.16.6
 Summary: Production-ready AI agents with tool calling, structured output, execution traces, and RAG. Provider-agnostic (OpenAI, Anthropic, Gemini, Ollama) with fallback chains, batch processing, tool policies, streaming, caching, and cost tracking.
 Author-email: John <johnnichev@gmail.com>
 License-Expression: LGPL-3.0-or-later
@@ -52,23 +52,27 @@ Dynamic: license-file
 [![PyPI version](https://badge.fury.io/py/selectools.svg)](https://badge.fury.io/py/selectools)
 [![Documentation](https://img.shields.io/badge/docs-GitHub%20Pages-blue)](https://johnnichev.github.io/selectools)
 [![License: LGPL v3](https://img.shields.io/badge/License-LGPL_v3-blue.svg)](https://www.gnu.org/licenses/lgpl-3.0)
-[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
+[![Python 3.13+](https://img.shields.io/badge/python-3.13+-blue.svg)](https://www.python.org/downloads/)
 
 **Production-ready AI agents with tool calling, RAG, and hybrid search.** Connect LLMs to your Python functions, embed and search your documents with vector + keyword fusion, stream responses in real time, and dynamically manage tools at runtime. Works with OpenAI, Anthropic, Gemini, and Ollama. Tracks costs automatically.
 
-## What's New in v0.16.0
+## What's New in v0.16.6
 
-**Memory & Persistence** — Five new features for durable conversation state:
+**Gemini 3.x thought_signature crash fix** — `thought_signature` from Gemini 3.x is opaque binary (protobuf/hash), not UTF-8 text. The previous code crashed with `UnicodeDecodeError` on non-UTF-8 bytes. Now uses base64 for lossless binary round-trip across all code paths.
 
-- **Persistent Sessions** — `SessionStore` protocol with 3 backends (JSON file, SQLite, Redis). Auto-save/load via `AgentConfig(session_store=store, session_id="user-123")`.
-- **Summarize-on-Trim** — LLM-generated summaries of trimmed messages, injected as system context. No more silent context loss.
-- **Entity Memory** — Auto-extract named entities (person, org, project) across turns with LRU-pruned registry and system prompt injection.
-- **Knowledge Graph** — Relationship triple extraction with in-memory and SQLite storage. Query-relevant triples auto-injected into prompts.
-- **Cross-Session Knowledge** — Daily logs + persistent facts with auto-registered `remember` tool. Give your agent durable memory across conversations.
-- **182 new tests** (total: 1462 with v0.16.3 refactoring)
+- **1642 tests** — 2 new regression tests for non-UTF-8 binary thought_signature round-trip
 
 > Full changelog: [CHANGELOG.md](https://github.com/johnnichev/selectools/blob/main/CHANGELOG.md)
 
+<details>
+<summary><strong>v0.16.x highlights</strong></summary>
+
+- **v0.16.5**: Design Patterns & Code Quality — terminal actions, async observers, Gemini 3.x thought signatures, agent decomposition, hooks deprecated
+- **v0.16.4**: Parallel execution safety — coherence + screening in parallel, guardrail immutability, streaming usage tracking
+- **v0.16.0**: Memory & Persistence — persistent sessions (3 backends), summarize-on-trim, entity memory, knowledge graph
+
+</details>
+
 <details>
 <summary><strong>v0.15.x highlights</strong></summary>
 
@@ -80,7 +84,7 @@ Dynamic: license-file
 <summary><strong>v0.14.x highlights</strong></summary>
 
 - **v0.14.1**: Critical streaming fix — 13 bugs fixed across all providers; 141 new tests (total: 1100)
-- **v0.14.0**: AgentObserver Protocol (15 events), 145 models with March 2026 pricing, OpenAI `max_completion_tokens` auto-detection, 11 bug fixes
+- **v0.14.0**: AgentObserver Protocol (25 events), 145 models with March 2026 pricing, OpenAI `max_completion_tokens` auto-detection, 11 bug fixes
 
 </details>
 
@@ -109,7 +113,7 @@ Dynamic: license-file
 | **Entity Memory** | LLM-based entity extraction with deduplication, LRU pruning, and system prompt injection. |
 | **Knowledge Graph** | Relationship triple extraction with in-memory and SQLite storage and keyword-based querying. |
 | **Cross-Session Knowledge** | Daily logs + persistent facts with auto-registered `remember` tool. |
-| **AgentObserver Protocol** | 19-event lifecycle observer with `run_id`/`call_id` correlation. Built-in `LoggingObserver` for structured JSON logs. |
+| **AgentObserver Protocol** | 25-event lifecycle observer with `run_id`/`call_id` correlation. Built-in `LoggingObserver` for structured JSON logs. |
 | **Production Hardened** | Retries with backoff, per-tool timeouts, iteration caps, cost warnings, observability hooks + observers. |
 | **Library-First** | Not a framework. No magic globals, no hidden state. Use as much or as little as you need. |
 
@@ -133,9 +137,9 @@ Dynamic: license-file
 - **Entity Memory**: LLM-based named entity extraction and tracking
 - **Knowledge Graph**: Triple extraction with in-memory and SQLite storage
 - **Cross-Session Knowledge**: Daily logs + persistent memory with `remember` tool
-- **37 Examples**: RAG, hybrid search, streaming, structured output, traces, batch, policy, observer, guardrails, audit, sessions, entity memory, knowledge graph, and more
+- **38 Examples**: RAG, hybrid search, streaming, structured output, traces, batch, policy, observer, guardrails, audit, sessions, entity memory, knowledge graph, and more
 - **AgentObserver Protocol**: 25 lifecycle events with `run_id` correlation, `LoggingObserver`, OTel export
-- **1462 Tests**: Unit, integration, regression, and E2E with real API calls
+- **1642 Tests**: Unit, integration, regression, and E2E with real API calls
 
 ## Install
 
@@ -457,7 +461,7 @@ agent = Agent(
 )
 ```
 
-15 lifecycle events: run, LLM, tool, iteration, batch, policy, structured output, fallback, retry, memory trim. See `observer.py` for full reference.
+25 lifecycle events: run, LLM, tool, iteration, batch, policy, structured output, fallback, retry, memory trim, guardrail, coherence, screening, session, entity, KG. See `observer.py` for full reference.
 
 ### E2E Streaming & Parallel Execution
 
@@ -627,7 +631,7 @@ Examples are numbered by difficulty. Start from 01 and work your way up.
 |---|---|---|---|
 | 01 | `01_hello_world.py` | First agent, `@tool`, `ask()` | No |
 | 02 | `02_search_weather.py` | ToolRegistry, multiple tools | No |
-| 03 | `03_toolbox.py` | 22 pre-built tools (file, data, text, datetime) | No |
+| 03 | `03_toolbox.py` | 24 pre-built tools (file, data, text, datetime, web) | No |
 | 04 | `04_conversation_memory.py` | Multi-turn memory | Yes |
 | 05 | `05_cost_tracking.py` | Token counting, cost warnings | Yes |
 | 06 | `06_async_agent.py` | `arun()`, concurrent agents, FastAPI | Yes |

{selectools-0.16.4 → selectools-0.16.6}/README.md

@@ -3,23 +3,27 @@
 [![PyPI version](https://badge.fury.io/py/selectools.svg)](https://badge.fury.io/py/selectools)
 [![Documentation](https://img.shields.io/badge/docs-GitHub%20Pages-blue)](https://johnnichev.github.io/selectools)
 [![License: LGPL v3](https://img.shields.io/badge/License-LGPL_v3-blue.svg)](https://www.gnu.org/licenses/lgpl-3.0)
-[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
+[![Python 3.13+](https://img.shields.io/badge/python-3.13+-blue.svg)](https://www.python.org/downloads/)
 
 **Production-ready AI agents with tool calling, RAG, and hybrid search.** Connect LLMs to your Python functions, embed and search your documents with vector + keyword fusion, stream responses in real time, and dynamically manage tools at runtime. Works with OpenAI, Anthropic, Gemini, and Ollama. Tracks costs automatically.
 
-## What's New in v0.16.0
+## What's New in v0.16.6
 
-**Memory & Persistence** — Five new features for durable conversation state:
+**Gemini 3.x thought_signature crash fix** — `thought_signature` from Gemini 3.x is opaque binary (protobuf/hash), not UTF-8 text. The previous code crashed with `UnicodeDecodeError` on non-UTF-8 bytes. Now uses base64 for lossless binary round-trip across all code paths.
 
-- **Persistent Sessions** — `SessionStore` protocol with 3 backends (JSON file, SQLite, Redis). Auto-save/load via `AgentConfig(session_store=store, session_id="user-123")`.
-- **Summarize-on-Trim** — LLM-generated summaries of trimmed messages, injected as system context. No more silent context loss.
-- **Entity Memory** — Auto-extract named entities (person, org, project) across turns with LRU-pruned registry and system prompt injection.
-- **Knowledge Graph** — Relationship triple extraction with in-memory and SQLite storage. Query-relevant triples auto-injected into prompts.
-- **Cross-Session Knowledge** — Daily logs + persistent facts with auto-registered `remember` tool. Give your agent durable memory across conversations.
-- **182 new tests** (total: 1462 with v0.16.3 refactoring)
+- **1642 tests** — 2 new regression tests for non-UTF-8 binary thought_signature round-trip
 
 > Full changelog: [CHANGELOG.md](https://github.com/johnnichev/selectools/blob/main/CHANGELOG.md)
 
+<details>
+<summary><strong>v0.16.x highlights</strong></summary>
+
+- **v0.16.5**: Design Patterns & Code Quality — terminal actions, async observers, Gemini 3.x thought signatures, agent decomposition, hooks deprecated
+- **v0.16.4**: Parallel execution safety — coherence + screening in parallel, guardrail immutability, streaming usage tracking
+- **v0.16.0**: Memory & Persistence — persistent sessions (3 backends), summarize-on-trim, entity memory, knowledge graph
+
+</details>
+
 <details>
 <summary><strong>v0.15.x highlights</strong></summary>
 
@@ -31,7 +35,7 @@
 <summary><strong>v0.14.x highlights</strong></summary>
 
 - **v0.14.1**: Critical streaming fix — 13 bugs fixed across all providers; 141 new tests (total: 1100)
-- **v0.14.0**: AgentObserver Protocol (15 events), 145 models with March 2026 pricing, OpenAI `max_completion_tokens` auto-detection, 11 bug fixes
+- **v0.14.0**: AgentObserver Protocol (25 events), 145 models with March 2026 pricing, OpenAI `max_completion_tokens` auto-detection, 11 bug fixes
 
 </details>
 
@@ -60,7 +64,7 @@
 | **Entity Memory** | LLM-based entity extraction with deduplication, LRU pruning, and system prompt injection. |
 | **Knowledge Graph** | Relationship triple extraction with in-memory and SQLite storage and keyword-based querying. |
 | **Cross-Session Knowledge** | Daily logs + persistent facts with auto-registered `remember` tool. |
-| **AgentObserver Protocol** | 19-event lifecycle observer with `run_id`/`call_id` correlation. Built-in `LoggingObserver` for structured JSON logs. |
+| **AgentObserver Protocol** | 25-event lifecycle observer with `run_id`/`call_id` correlation. Built-in `LoggingObserver` for structured JSON logs. |
 | **Production Hardened** | Retries with backoff, per-tool timeouts, iteration caps, cost warnings, observability hooks + observers. |
 | **Library-First** | Not a framework. No magic globals, no hidden state. Use as much or as little as you need. |
 
@@ -84,9 +88,9 @@
 - **Entity Memory**: LLM-based named entity extraction and tracking
 - **Knowledge Graph**: Triple extraction with in-memory and SQLite storage
 - **Cross-Session Knowledge**: Daily logs + persistent memory with `remember` tool
-- **37 Examples**: RAG, hybrid search, streaming, structured output, traces, batch, policy, observer, guardrails, audit, sessions, entity memory, knowledge graph, and more
+- **38 Examples**: RAG, hybrid search, streaming, structured output, traces, batch, policy, observer, guardrails, audit, sessions, entity memory, knowledge graph, and more
 - **AgentObserver Protocol**: 25 lifecycle events with `run_id` correlation, `LoggingObserver`, OTel export
-- **1462 Tests**: Unit, integration, regression, and E2E with real API calls
+- **1642 Tests**: Unit, integration, regression, and E2E with real API calls
 
 ## Install
 
@@ -408,7 +412,7 @@ agent = Agent(
 )
 ```
 
-15 lifecycle events: run, LLM, tool, iteration, batch, policy, structured output, fallback, retry, memory trim. See `observer.py` for full reference.
+25 lifecycle events: run, LLM, tool, iteration, batch, policy, structured output, fallback, retry, memory trim, guardrail, coherence, screening, session, entity, KG. See `observer.py` for full reference.
 
 ### E2E Streaming & Parallel Execution
 
@@ -578,7 +582,7 @@ Examples are numbered by difficulty. Start from 01 and work your way up.
 |---|---|---|---|
 | 01 | `01_hello_world.py` | First agent, `@tool`, `ask()` | No |
 | 02 | `02_search_weather.py` | ToolRegistry, multiple tools | No |
-| 03 | `03_toolbox.py` | 22 pre-built tools (file, data, text, datetime) | No |
+| 03 | `03_toolbox.py` | 24 pre-built tools (file, data, text, datetime, web) | No |
 | 04 | `04_conversation_memory.py` | Multi-turn memory | Yes |
 | 05 | `05_cost_tracking.py` | Token counting, cost warnings | Yes |
 | 06 | `06_async_agent.py` | `arun()`, concurrent agents, FastAPI | Yes |

{selectools-0.16.4 → selectools-0.16.6}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "selectools"
-version = "0.16.4"
+version = "0.16.6"
 description = "Production-ready AI agents with tool calling, structured output, execution traces, and RAG. Provider-agnostic (OpenAI, Anthropic, Gemini, Ollama) with fallback chains, batch processing, tool policies, streaming, caching, and cost tracking."
 readme = "README.md"
 requires-python = ">=3.9"
@@ -96,7 +96,7 @@ use_parentheses = true
 ensure_newline_before_comments = true
 
 [tool.mypy]
-python_version = "3.9"
+python_version = "3.13"
 warn_return_any = true
 warn_unused_configs = true
 disallow_untyped_defs = true
@@ -108,6 +108,16 @@ exclude = [
     "dist/",
 ]
 
+[[tool.mypy.overrides]]
+module = [
+    "selectools.agent._tool_executor",
+    "selectools.agent._provider_caller",
+    "selectools.agent._lifecycle",
+    "selectools.agent._memory_manager",
+    "selectools.providers._openai_compat",
+]
+disable_error_code = ["attr-defined"]
+
 [tool.bandit]
 exclude_dirs = ["tests", "examples", "scripts"]
 skips = ["B101", "B601", "B602"]  # Skip assert_used, shell, and subprocess checks

{selectools-0.16.4 → selectools-0.16.6}/src/selectools/__init__.py

@@ -1,6 +1,6 @@
 """Public exports for the selectools package."""
 
-__version__ = "0.16.4"
+__version__ = "0.16.6"
 
 # Import submodules (lazy loading for optional dependencies)
 from . import embeddings, guardrails, models, rag, toolbox
@@ -39,8 +39,18 @@ from .knowledge_graph import (
     TripleStore,
 )
 from .memory import ConversationMemory
-from .models import ALL_MODELS, MODELS_BY_ID, Anthropic, Cohere, Gemini, ModelInfo, Ollama, OpenAI
-from .observer import AgentObserver, LoggingObserver
+from .models import (
+    ALL_MODELS,
+    MODELS_BY_ID,
+    Anthropic,
+    Cohere,
+    Gemini,
+    ModelInfo,
+    ModelType,
+    Ollama,
+    OpenAI,
+)
+from .observer import AgentObserver, AsyncAgentObserver, LoggingObserver
 from .parser import ToolCallParser
 from .policy import PolicyDecision, PolicyResult, ToolPolicy
 from .pricing import PRICING, calculate_cost, calculate_embedding_cost, get_model_pricing
@@ -60,7 +70,7 @@ from .sessions import (
 )
 from .structured import ResponseFormat
 from .tools import Tool, ToolParameter, ToolRegistry, tool
-from .trace import AgentTrace, TraceStep
+from .trace import AgentTrace, StepType, TraceStep
 from .types import AgentResult, Message, Role, ToolCall
 from .usage import AgentUsage, UsageStats
 
@@ -104,6 +114,7 @@ __all__ = [
     # Model Registry
     "models",
     "ModelInfo",
+    "ModelType",
     "ALL_MODELS",
     "MODELS_BY_ID",
     "OpenAI",
@@ -124,8 +135,10 @@ __all__ = [
     "ResponseFormat",
     # Observability
     "AgentObserver",
+    "AsyncAgentObserver",
     "LoggingObserver",
     "AgentTrace",
+    "StepType",
     "TraceStep",
     # Guardrails
     "guardrails",

selectools-0.16.6/src/selectools/agent/_lifecycle.py

@@ -0,0 +1,141 @@
+"""Mixin providing observer notification and fallback wiring methods for the Agent class."""
+
+from __future__ import annotations
+
+import asyncio
+import threading
+from typing import TYPE_CHECKING, Any, Optional, cast
+
+if TYPE_CHECKING:
+    from ..memory import ConversationMemory
+
+
+class _LifecycleMixin:
+    """Mixin that provides observer lifecycle methods for the Agent class.
+
+    All methods access ``self.*`` attributes (config, provider, etc.)
+    which are expected to be provided by the Agent class that inherits
+    from this mixin.
+    """
+
+    def _notify_observers(self, method: str, *args: Any) -> None:
+        """Call *method* on every registered observer, swallowing errors."""
+        for obs in self.config.observers:
+            try:
+                getattr(obs, method)(*args)
+            except Exception:  # noqa: BLE001 # nosec B110
+                pass
+
+    async def _anotify_observers(self, method: str, *args: Any) -> None:
+        """Call async ``a_{method}`` on every AsyncAgentObserver, swallowing errors.
+
+        - ``blocking=True`` observers: awaited inline (sequential).
+        - ``blocking=False`` observers: dispatched via ``asyncio.ensure_future``.
+        """
+        from ..observer import AsyncAgentObserver
+
+        async_method = f"a_{method}"
+        for obs in self.config.observers:
+            if not isinstance(obs, AsyncAgentObserver):
+                continue
+            handler = getattr(obs, async_method, None)
+            if handler is None:
+                continue
+            try:
+                if obs.blocking:
+                    await handler(*args)
+                else:
+                    asyncio.ensure_future(handler(*args))
+            except Exception:  # noqa: BLE001 # nosec B110
+                pass
+
+    def _truncate_tool_result(self, result: Optional[str]) -> Optional[str]:
+        """Truncate tool result text for trace storage."""
+        if result is None:
+            return None
+        limit = self.config.trace_tool_result_chars
+        if limit is None:
+            return result
+        return result[:limit]
+
+    _fallback_run_id: threading.local = threading.local()
+    _lock_type: type = type(threading.Lock())
+
+    def _wire_fallback_observer(self, run_id: Optional[str]) -> None:
+        """If the provider is a FallbackProvider, wire its on_fallback to observers.
+
+        Thread-safe: uses a lock + refcount so multiple concurrent ``run()``
+        calls (e.g. from ``batch()``) share a single callback on the provider
+        while each thread's ``run_id`` is carried via a thread-local.
+        The lock persists on the provider to avoid races from delete-then-recreate.
+        """
+        if not run_id or not self.config.observers:
+            return
+        provider = self.provider
+        if not hasattr(provider, "on_fallback"):
+            return
+
+        _LifecycleMixin._fallback_run_id.value = run_id
+
+        raw_lock = getattr(provider, "_fb_wire_lock", None)
+        if not isinstance(raw_lock, _LifecycleMixin._lock_type):
+            raw_lock = threading.Lock()
+            provider._fb_wire_lock = raw_lock  # type: ignore[attr-defined]
+        lock = cast(threading.Lock, raw_lock)
+
+        agent_ref = self
+
+        with lock:
+            refcount: int = getattr(provider, "_fb_wire_refcount", 0)
+            if refcount == 0:
+                provider._fb_original_on_fallback = provider.on_fallback  # type: ignore[attr-defined]
+                user_cb = provider.on_fallback
+
+                def _observer_fallback(
+                    failed: str,
+                    next_p: str,
+                    exc: Exception,
+                ) -> None:
+                    rid = getattr(_LifecycleMixin._fallback_run_id, "value", "")
+                    agent_ref._notify_observers(
+                        "on_provider_fallback",
+                        rid,
+                        failed,
+                        next_p,
+                        exc,
+                    )
+                    if user_cb:
+                        try:
+                            user_cb(failed, next_p, exc)
+                        except Exception:  # nosec B110
+                            pass
+
+                provider.on_fallback = _observer_fallback  # type: ignore[attr-defined]
+
+            provider._fb_wire_refcount = refcount + 1  # type: ignore[attr-defined]
+
+    def _unwire_fallback_observer(self) -> None:
+        """Restore FallbackProvider's original on_fallback callback (thread-safe).
+
+        The lock is kept on the provider (never deleted) to prevent races when
+        concurrent threads overlap wire / unwire calls.
+        """
+        provider = self.provider
+        raw_lock = getattr(provider, "_fb_wire_lock", None)
+        if not isinstance(raw_lock, _LifecycleMixin._lock_type):
+            return
+        lock = cast(threading.Lock, raw_lock)
+
+        with lock:
+            refcount: int = getattr(provider, "_fb_wire_refcount", 0) - 1
+            if refcount < 0:
+                refcount = 0
+            provider._fb_wire_refcount = refcount  # type: ignore[attr-defined]
+            if refcount == 0:
+                original = getattr(provider, "_fb_original_on_fallback", None)
+                provider.on_fallback = original  # type: ignore[attr-defined]
+                if hasattr(provider, "_fb_original_on_fallback"):
+                    try:
+                        delattr(provider, "_fb_original_on_fallback")
+                    except Exception:  # nosec B110
+                        pass

selectools-0.16.6/src/selectools/agent/_memory_manager.py

@@ -0,0 +1,146 @@
+"""Mixin providing memory management methods for the Agent class."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, List, Optional
+
+from ..types import Message, Role
+
+if TYPE_CHECKING:
+    from ..memory import ConversationMemory
+
+
+class _MemoryManagerMixin:
+    """Mixin that provides memory management methods for the Agent class.
+
+    All methods access ``self.*`` attributes (config, provider, memory,
+    _history, _notify_observers, etc.) which are expected to be provided
+    by the Agent class that inherits from this mixin.
+    """
+
+    def _memory_add(self, msg: Message, run_id: str) -> None:
+        """Add message to memory and notify observers if trimming occurred."""
+        if not self.memory:
+            return
+        before = len(self.memory)
+        self.memory.add(msg)
+        after = len(self.memory)
+        removed = (before + 1) - after
+        if removed > 0:
+            self._notify_observers(
+                "on_memory_trim",
+                run_id,
+                removed,
+                after,
+                "enforce_limits",
+            )
+            self._maybe_summarize_trim(run_id)
+
+    def _memory_add_many(self, msgs: List[Message], run_id: str) -> None:
+        """Add multiple messages to memory and notify observers if trimming occurred."""
+        if not self.memory or not msgs:
+            return
+        before = len(self.memory)
+        self.memory.add_many(msgs)
+        after = len(self.memory)
+        removed = (before + len(msgs)) - after
+        if removed > 0:
+            self._notify_observers(
+                "on_memory_trim",
+                run_id,
+                removed,
+                after,
+                "enforce_limits",
+            )
+            self._maybe_summarize_trim(run_id)
+
+    def _maybe_summarize_trim(self, run_id: str) -> None:
+        """Generate a summary of trimmed messages if summarize_on_trim is enabled."""
+        if not self.config.summarize_on_trim or not self.memory:
+            return
+        trimmed = self.memory._last_trimmed
+        if not trimmed:
+            return
+        try:
+            provider = self.config.summarize_provider or self.provider
+            model = self.config.summarize_model or self.config.model
+            text_parts = []
+            for m in trimmed:
+                prefix = m.role.value.upper()
+                text_parts.append(f"{prefix}: {m.content or ''}")
+            trimmed_text = "\n".join(text_parts)
+
+            prompt_msg = Message(
+                role=Role.USER,
+                content=(
+                    "Summarize the following conversation excerpt in 2-3 sentences. "
+                    "Focus on key facts, decisions, and context that would be useful "
+                    "for continuing the conversation:\n\n" + trimmed_text
+                ),
+            )
+            result = provider.complete(
+                model=model,
+                system_prompt="You are a concise summarizer.",
+                messages=[prompt_msg],
+                max_tokens=self.config.summarize_max_tokens,
+            )
+            # Provider returns (Message, UsageStats) tuple
+            summary_msg = result[0] if isinstance(result, tuple) else result
+            summary_text = summary_msg.content or ""
+            if summary_text:
+                existing = self.memory.summary
+                if existing:
+                    self.memory.summary = existing + " " + summary_text
+                else:
+                    self.memory.summary = summary_text
+                self._notify_observers("on_memory_summarize", run_id, self.memory.summary)
+        except Exception:  # nosec B110
+            pass  # never crash the agent for a summarization failure
+
+    def _session_save(self, run_id: str) -> None:
+        """Auto-save memory to session store if configured."""
+        store = self.config.session_store
+        sid = self.config.session_id
+        if not store or not sid or not self.memory:
+            return
+        try:
+            store.save(sid, self.memory)
+            self._notify_observers("on_session_save", run_id, sid, len(self.memory))
+        except Exception:  # nosec B110
+            pass  # never crash the agent for a persistence failure
+
+    def _extract_entities(self, run_id: str) -> None:
+        """Extract entities from recent messages if entity_memory is configured."""
+        em = self.config.entity_memory
+        if not em:
+            return
+        try:
+            recent = self._history[-em._relevance_window :]
+            entities = em.extract_entities(recent, model=self.config.model)
+            if entities:
+                em.update(entities)
+                self._notify_observers(
+                    "on_entity_extraction",
+                    run_id,
+                    len(entities),
+                )
+        except Exception:  # nosec B110
+            pass  # never crash the agent for entity extraction failure
+
+    def _extract_kg_triples(self, run_id: str) -> None:
+        """Extract relationship triples from recent messages if knowledge_graph is configured."""
+        kg = self.config.knowledge_graph
+        if not kg:
+            return
+        try:
+            recent = self._history[-kg._relevance_window :]
+            triples = kg.extract_triples(recent, model=self.config.model)
+            if triples:
+                kg.store.add_many(triples)
+                self._notify_observers(
+                    "on_kg_extraction",
+                    run_id,
+                    len(triples),
+                )
+        except Exception:  # nosec B110
+            pass  # never crash the agent for KG extraction failure