PyPI - local2 - Versions diffs - 0.2.1__tar.gz → 0.2.2__tar.gz - Mend

local2 0.2.1tar.gz → 0.2.2tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (4862) hide show

local2-0.2.2/.claude/plan_participant_base.html ADDED Viewed

@@ -0,0 +1,287 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<title>Plan — Participant base class + participation contract</title>
+<style>
+  body { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; max-width: 960px; margin: 40px auto; padding: 0 24px; background: #0f0f0f; color: #e0e0e0; line-height: 1.6; }
+  h1 { color: #7eb8f7; border-bottom: 1px solid #333; padding-bottom: 12px; }
+  h2 { color: #a0cfff; margin-top: 40px; }
+  h3 { color: #c8d8f0; margin-top: 24px; }
+  h4 { color: #aab8cc; margin-top: 16px; margin-bottom: 4px; }
+  code { background: #1a1a2e; padding: 2px 6px; border-radius: 4px; font-family: "SF Mono", "Fira Code", monospace; font-size: 0.88em; color: #a8d8a8; }
+  pre { background: #1a1a2e; padding: 16px; border-radius: 8px; overflow-x: auto; border-left: 3px solid #3a5a8a; }
+  pre code { background: none; padding: 0; color: #c8e8c8; }
+  table { width: 100%; border-collapse: collapse; margin: 16px 0; }
+  th { background: #1a2a3a; padding: 8px 12px; text-align: left; color: #a0cfff; border-bottom: 1px solid #2a4a7a; }
+  td { padding: 8px 12px; border-bottom: 1px solid #1e1e2e; vertical-align: top; }
+  ul li { margin: 4px 0; }
+  .decision { background: #1a1500; border-left: 3px solid #b8960a; padding: 10px 16px; border-radius: 0 6px 6px 0; margin: 12px 0; }
+  .decision strong { color: #e8c040; }
+  .note { background: #0d1a0d; border-left: 3px solid #4a8a4a; padding: 10px 16px; border-radius: 0 6px 6px 0; margin: 12px 0; }
+  .new { color: #7ec87e; }
+  .modified { color: #e8c87e; }
+  .deleted { color: #e87e7e; text-decoration: line-through; }
+  .file { font-family: "SF Mono", monospace; font-size: 0.85em; color: #a8d8a8; }
+  .arch-box { background: #0d1a2e; border: 1px solid #2a4a6a; border-radius: 8px; padding: 20px; font-family: monospace; font-size: 0.85em; line-height: 1.8; color: #b0c8e8; white-space: pre; overflow-x: auto; }
+</style>
+</head>
+<body>
+<h1>Plan — <code>Participant</code> base class + participation contract</h1>
+<p><em>Introduce a common Participant ABC above BaseAgent and BaseTool. Add BaseService for lightweight bus participants. Formalize the participation contract: every participant owns a config yaml with an id: field.</em></p>
+<h2>Motivation</h2>
+<p>Agents, tools, and services all live on the bus, but they share no common base. <code>AGENT_ID</code> and <code>TOOL_ID</code> are hardcoded class constants rather than config values. Services (CompactionService, RewardService) use <code>AGENT_ID</code> even though they are not agents. There is no stated contract for what it means to participate in LoCAL2.</p>
+<h2>Participation Contract</h2>
+<p>Every participant must:</p>
+<ol>
+  <li>Have a config yaml (under <code>config/</code> and <code>src/local/defaults/</code>)</li>
+  <li>Declare <code>CONFIG_NAME</code> — the key passed to <code>get_config()</code></li>
+  <li>Set <code>id:</code> in that yaml — the identity used as <code>sender_id</code> on all bus messages</li>
+</ol>
+<p>If <code>id:</code> is absent, <code>self.id</code> returns <code>"[set id in yaml]"</code> — no startup failure, visible in logs and UI.</p>
+<h2>New Class Hierarchy</h2>
+<div class="arch-box">
+Participant (ABC)                   ← new
+  CONFIG_NAME: ClassVar[str]        ← abstract; each subclass names its yaml
+  @property id → str                ← reads id: from config; placeholder if absent
+  ├── BaseAgent(Participant)        ← gains CONFIG_NAME requirement; AGENT_ID removed
+  │     ├── GeneratorAgent          CONFIG_NAME = "generator"
+  │     ├── CriticAgent             CONFIG_NAME = "critic"
+  │     └── MemoryAgent             CONFIG_NAME = "memory"
+  │
+  ├── BaseTool(Participant)         ← gains CONFIG_NAME requirement; TOOL_ID removed
+  │     ├── WebSearchTool           CONFIG_NAME = "web_search"
+  │     ├── WebFetchTool            CONFIG_NAME = "web_fetch"
+  │     ├── SearchMemoryTool        CONFIG_NAME = "search_memory"
+  │     ├── DateTimeTool            CONFIG_NAME = "datetime"
+  │     ├── LocationTool            CONFIG_NAME = "location"
+  │     ├── SemanticScholarTool     CONFIG_NAME = "semantic_scholar"
+  │     └── SearchLibraryTool       CONFIG_NAME = "documents"
+  │
+  └── BaseService(Participant)      ← new; lightweight subscribe loop
+        ├── CompactionService       CONFIG_NAME = "compaction"
+        └── RewardService           CONFIG_NAME = "reward"
+</div>
+<h2>Participant ABC</h2>
+<p>File: <span class="file">src/local/participants/participant.py</span> <span class="new">(new)</span></p>
+<pre><code>"""Participant — root base class for all LoCAL2 bus participants."""
+from __future__ import annotations
+from abc import ABC, abstractmethod
+from typing import ClassVar
+from local.config_loader import get_config
+_UNSET = "[set id in yaml]"
+class Participant(ABC):
+    """Root base for every LoCAL2 bus participant.
+    Contract:
+      - Declare CONFIG_NAME pointing to the participant's own yaml
+      - Set id: in that yaml
+    """
+    CONFIG_NAME: ClassVar[str]
+    @property
+    def id(self) -> str:
+        cfg = get_config(self.CONFIG_NAME) or {}
+        return cfg.get("id") or _UNSET
+</code></pre>
+<div class="note">
+  <code>get_config()</code> is already cached by ConfigManager — reading it on every property access is cheap. No need to store in <code>__init__</code>.
+</div>
+<h2>BaseService (new)</h2>
+<p>File: <span class="file">src/local/participants/base_service.py</span> <span class="new">(new)</span></p>
+<p>CompactionService and RewardService share the same pattern: subscribe to one or more subjects, loop receiving envelopes, publish back. BaseService captures that skeleton.</p>
+<pre><code>"""BaseService — lightweight bus participant with a subscribe loop."""
+from __future__ import annotations
+import logging
+from abc import abstractmethod
+from local.participants.participant import Participant
+logger = logging.getLogger(__name__)
+class BaseService(Participant):
+    """Participant with a simple subscribe-and-dispatch run loop.
+    Subclasses implement _handle(envelope).
+    """
+    def run(self) -> None:
+        logger.info("%s ready", self.id)
+        while True:
+            try:
+                envelope = self._sub.receive()
+            except Exception as exc:
+                logger.error("%s: receive error: %s", self.id, exc)
+                continue
+            try:
+                self._handle(envelope)
+            except Exception as exc:
+                logger.error("%s: handler error: %s", self.id, exc, exc_info=True)
+    @abstractmethod
+    def _handle(self, envelope) -> None: ...
+</code></pre>
+<h2>BaseAgent changes</h2>
+<p>File: <span class="file">src/local/agents/base_agent.py</span> <span class="modified">(modified)</span></p>
+<ul>
+  <li>Inherit from <code>Participant</code> instead of <code>ABC</code></li>
+  <li>Remove <code>AGENT_ID: ClassVar[str]</code> — replaced by <code>Participant.id</code></li>
+  <li>All <code>self.AGENT_ID</code> references → <code>self.id</code></li>
+</ul>
+<h2>BaseTool changes</h2>
+<p>File: <span class="file">src/local/tools/base_tool.py</span> <span class="modified">(modified)</span></p>
+<ul>
+  <li>Inherit from <code>Participant</code> instead of <code>ABC</code></li>
+  <li>Remove <code>TOOL_ID: ClassVar[str]</code> — replaced by <code>Participant.id</code></li>
+  <li>All <code>self.TOOL_ID</code> references → <code>self.id</code></li>
+  <li><code>CONFIG_NAME</code> already declared — no change needed there</li>
+</ul>
+<h2>CompactionService changes</h2>
+<p>File: <span class="file">src/local/services/compaction_service.py</span> <span class="modified">(modified)</span></p>
+<ul>
+  <li>Inherit from <code>BaseService</code></li>
+  <li>Remove <code>AGENT_ID = "compaction_service"</code></li>
+  <li>Add <code>CONFIG_NAME = "compaction"</code></li>
+  <li>Move subscribe loop boilerplate to <code>BaseService.run()</code>; rename <code>_check</code> → <code>_handle</code></li>
+  <li>All <code>self.AGENT_ID</code> → <code>self.id</code></li>
+</ul>
+<h2>RewardService changes</h2>
+<p>File: <span class="file">src/local/services/reward_service.py</span> <span class="modified">(modified)</span></p>
+<ul>
+  <li>Inherit from <code>BaseService</code></li>
+  <li>Remove any hardcoded ID constant</li>
+  <li>Add <code>CONFIG_NAME = "reward"</code></li>
+  <li>Move subscribe loop to <code>BaseService.run()</code> if not already compatible</li>
+</ul>
+<h2>Per-participant CONFIG_NAME additions</h2>
+<table>
+  <tr><th>Participant</th><th>CONFIG_NAME</th><th>Change</th></tr>
+  <tr><td>GeneratorAgent</td><td><code>"generator"</code></td><td class="modified">add CONFIG_NAME class var; remove AGENT_ID</td></tr>
+  <tr><td>CriticAgent</td><td><code>"critic"</code></td><td class="modified">add CONFIG_NAME class var; remove AGENT_ID</td></tr>
+  <tr><td>MemoryAgent</td><td><code>"memory"</code></td><td class="modified">add CONFIG_NAME class var; remove AGENT_ID</td></tr>
+  <tr><td>WebSearchTool</td><td><code>"web_search"</code></td><td class="modified">already has CONFIG_NAME; remove TOOL_ID</td></tr>
+  <tr><td>WebFetchTool</td><td><code>"web_fetch"</code></td><td class="modified">already has CONFIG_NAME; remove TOOL_ID</td></tr>
+  <tr><td>SearchMemoryTool</td><td><code>"search_memory"</code></td><td class="modified">already has CONFIG_NAME; remove TOOL_ID</td></tr>
+  <tr><td>DateTimeTool</td><td><code>"datetime"</code></td><td class="modified">add CONFIG_NAME; new yaml required</td></tr>
+  <tr><td>LocationTool</td><td><code>"location"</code></td><td class="modified">already has CONFIG_NAME; remove TOOL_ID</td></tr>
+  <tr><td>SemanticScholarTool</td><td><code>"semantic_scholar"</code></td><td class="modified">already has CONFIG_NAME; remove TOOL_ID</td></tr>
+  <tr><td>SearchLibraryTool</td><td><code>"documents"</code></td><td class="modified">already has CONFIG_NAME; remove TOOL_ID</td></tr>
+  <tr><td>CompactionService</td><td><code>"compaction"</code></td><td class="new">new CONFIG_NAME; new yaml required</td></tr>
+  <tr><td>RewardService</td><td><code>"reward"</code></td><td class="new">new CONFIG_NAME; new yaml required</td></tr>
+</table>
+<h2>New and Updated Config Files</h2>
+<h4>New yamls (both config/ and src/local/defaults/)</h4>
+<pre><code># config/datetime.yaml
+id: datetime_tool
+# config/compaction.yaml
+id: compaction_service
+# config/reward.yaml
+id: reward_service
+</code></pre>
+<h4>id: added to all existing yamls</h4>
+<table>
+  <tr><th>File</th><th>id: value</th></tr>
+  <tr><td>generator.yaml</td><td>generator</td></tr>
+  <tr><td>critic.yaml</td><td>critic</td></tr>
+  <tr><td>memory.yaml</td><td>memory_agent</td></tr>
+  <tr><td>web_search.yaml</td><td>web_search_tool</td></tr>
+  <tr><td>web_fetch.yaml</td><td>web_fetch_tool</td></tr>
+  <tr><td>search_memory.yaml</td><td>search_memory_tool</td></tr>
+  <tr><td>location.yaml</td><td>location_tool</td></tr>
+  <tr><td>semantic_scholar.yaml</td><td>semantic_scholar_tool</td></tr>
+  <tr><td>documents.yaml</td><td>search_library_tool</td></tr>
+</table>
+<h2>Module structure</h2>
+<p>New directory <span class="file">src/local/participants/</span> houses the base classes shared across agents, tools, and services:</p>
+<pre><code>src/local/participants/
+  __init__.py
+  participant.py      ← Participant ABC
+  base_service.py     ← BaseService
+</code></pre>
+<p>BaseAgent stays in <code>src/local/agents/</code>. BaseTool stays in <code>src/local/tools/</code>. Both import from <code>local.participants</code>.</p>
+<h2>GeneratorAgent special case</h2>
+<p>GeneratorAgent has both a participant <code>id</code> (from generator.yaml) and an <code>instance_id</code> (from system.yaml, used for peer identification in distributed mode). These remain distinct — <code>self.id</code> identifies the participant type; <code>self._instance_id</code> identifies the specific running instance.</p>
+<h2>File Map</h2>
+<table>
+  <tr><th>File</th><th>Change</th></tr>
+  <tr><td><code>src/local/participants/__init__.py</code></td><td class="new">new module</td></tr>
+  <tr><td><code>src/local/participants/participant.py</code></td><td class="new">Participant ABC</td></tr>
+  <tr><td><code>src/local/participants/base_service.py</code></td><td class="new">BaseService</td></tr>
+  <tr><td><code>src/local/agents/base_agent.py</code></td><td class="modified">inherit Participant; remove AGENT_ID; self.id</td></tr>
+  <tr><td><code>src/local/tools/base_tool.py</code></td><td class="modified">inherit Participant; remove TOOL_ID; self.id</td></tr>
+  <tr><td><code>src/local/agents/generator_agent.py</code></td><td class="modified">add CONFIG_NAME; remove AGENT_ID</td></tr>
+  <tr><td><code>src/local/agents/critic_agent.py</code></td><td class="modified">add CONFIG_NAME; remove AGENT_ID</td></tr>
+  <tr><td><code>src/local/agents/memory_agent.py</code></td><td class="modified">add CONFIG_NAME; remove AGENT_ID</td></tr>
+  <tr><td><code>src/local/tools/datetime_tool.py</code></td><td class="modified">add CONFIG_NAME</td></tr>
+  <tr><td><code>src/local/tools/*.py</code> (6 remaining tools)</td><td class="modified">remove TOOL_ID</td></tr>
+  <tr><td><code>src/local/services/compaction_service.py</code></td><td class="modified">inherit BaseService; add CONFIG_NAME; remove AGENT_ID</td></tr>
+  <tr><td><code>src/local/services/reward_service.py</code></td><td class="modified">inherit BaseService; add CONFIG_NAME; remove hardcoded id</td></tr>
+  <tr><td><code>config/generator.yaml</code> + defaults</td><td class="modified">add id: generator</td></tr>
+  <tr><td><code>config/critic.yaml</code> + defaults</td><td class="modified">add id: critic</td></tr>
+  <tr><td><code>config/memory.yaml</code> + defaults</td><td class="modified">add id: memory_agent</td></tr>
+  <tr><td><code>config/web_search.yaml</code> + defaults</td><td class="modified">add id: web_search_tool</td></tr>
+  <tr><td><code>config/web_fetch.yaml</code> + defaults</td><td class="modified">add id: web_fetch_tool</td></tr>
+  <tr><td><code>config/search_memory.yaml</code> + defaults</td><td class="modified">add id: search_memory_tool</td></tr>
+  <tr><td><code>config/location.yaml</code> + defaults</td><td class="modified">add id: location_tool</td></tr>
+  <tr><td><code>config/semantic_scholar.yaml</code> + defaults</td><td class="modified">add id: semantic_scholar_tool</td></tr>
+  <tr><td><code>config/documents.yaml</code> + defaults</td><td class="modified">add id: search_library_tool</td></tr>
+  <tr><td><code>config/datetime.yaml</code> + defaults</td><td class="new">id: datetime_tool</td></tr>
+  <tr><td><code>config/compaction.yaml</code> + defaults</td><td class="new">id: compaction_service</td></tr>
+  <tr><td><code>config/reward.yaml</code> + defaults</td><td class="new">id: reward_service</td></tr>
+</table>
+<h2>Test Impact</h2>
+<p>Any test that instantiates a participant and accesses <code>AGENT_ID</code> or <code>TOOL_ID</code> directly will need updating. Tests that check <code>sender_id</code> on published envelopes will continue to work — the value is unchanged, just the source moves from class constant to config.</p>
+<h2>Acceptance Criteria</h2>
+<ul>
+  <li>All participants expose <code>self.id</code>; no <code>AGENT_ID</code> or <code>TOOL_ID</code> class constants remain</li>
+  <li>Every participant has a config yaml with <code>id:</code></li>
+  <li>Removing <code>id:</code> from a yaml produces <code>"[set id in yaml]"</code> in logs and bus messages — no exception</li>
+  <li>CompactionService and RewardService extend <code>BaseService</code></li>
+  <li>All existing tests pass</li>
+</ul>
+</body>
+</html>

local2-0.2.2/.claude/plan_tool_dispatcher.html ADDED Viewed

@@ -0,0 +1,252 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<title>Plan — ToolDispatcher extraction</title>
+<style>
+  body { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; max-width: 960px; margin: 40px auto; padding: 0 24px; background: #0f0f0f; color: #e0e0e0; line-height: 1.6; }
+  h1 { color: #7eb8f7; border-bottom: 1px solid #333; padding-bottom: 12px; }
+  h2 { color: #a0cfff; margin-top: 40px; }
+  h3 { color: #c8d8f0; margin-top: 24px; }
+  h4 { color: #aab8cc; margin-top: 16px; margin-bottom: 4px; }
+  code { background: #1a1a2e; padding: 2px 6px; border-radius: 4px; font-family: "SF Mono", "Fira Code", monospace; font-size: 0.88em; color: #a8d8a8; }
+  pre { background: #1a1a2e; padding: 16px; border-radius: 8px; overflow-x: auto; border-left: 3px solid #3a5a8a; }
+  pre code { background: none; padding: 0; color: #c8e8c8; }
+  table { width: 100%; border-collapse: collapse; margin: 16px 0; }
+  th { background: #1a2a3a; padding: 8px 12px; text-align: left; color: #a0cfff; border-bottom: 1px solid #2a4a7a; }
+  td { padding: 8px 12px; border-bottom: 1px solid #1e1e2e; vertical-align: top; }
+  ul li { margin: 4px 0; }
+  .decision { background: #1a1500; border-left: 3px solid #b8960a; padding: 10px 16px; border-radius: 0 6px 6px 0; margin: 12px 0; }
+  .decision strong { color: #e8c040; }
+  .note { background: #0d1a0d; border-left: 3px solid #4a8a4a; padding: 10px 16px; border-radius: 0 6px 6px 0; margin: 12px 0; }
+  .new { color: #7ec87e; }
+  .modified { color: #e8c87e; }
+  .file { font-family: "SF Mono", monospace; font-size: 0.85em; color: #a8d8a8; }
+  .arch-box { background: #0d1a2e; border: 1px solid #2a4a6a; border-radius: 8px; padding: 20px; font-family: monospace; font-size: 0.85em; line-height: 1.8; color: #b0c8e8; white-space: pre; overflow-x: auto; }
+</style>
+</head>
+<body>
+<h1>Plan — ToolDispatcher extraction</h1>
+<p><em>Extract _execute_tool and _normalize_tool_name from GeneratorAgent into a dedicated ToolDispatcher helper. State transitions stay in the generator.</em></p>
+<h2>Motivation</h2>
+<p>GeneratorAgent._execute_tool() owns bus I/O mechanics that have nothing to do with generation: opening a short-lived subscriber, publishing a tool request, polling for a matching correlation_id, handling timeout. This is reusable bus plumbing. _normalize_tool_name() is similarly a tool-registry concern.</p>
+<p>Both belong in a dedicated helper, injected into the generator the same way CompactionService was.</p>
+<h2>What ToolDispatcher is</h2>
+<div class="decision">
+  <strong>ToolDispatcher is a synchronous Participant.</strong> It has its own <code>ZmqPublisher</code>, <code>CONFIG_NAME</code>, and <code>self.id</code>. It is a bus participant in spirit — it owns a bus connection and has a single clear responsibility — but has no event-driven run loop. It is called synchronously by the generator mid-generation turn. This is consistent with the architectural invariant that tool calls are synchronous within a generation turn.
+</div>
+<h2>Responsibility Split</h2>
+<table>
+  <tr><th>Concern</th><th>Owner</th><th>Why</th></tr>
+  <tr><td>Bus I/O: open subscriber, publish request, poll, close subscriber</td><td>ToolDispatcher</td><td>Generic bus plumbing, reusable, testable in isolation</td></tr>
+  <tr><td>Name normalization: map hallucinated names to registered schema names</td><td>ToolDispatcher</td><td>Tool-registry logic, not generation logic</td></tr>
+  <tr><td>State transitions: DISPATCH_TOOL, AWAIT_RESULT, TOOL_RESULT, TOOL_TIMEOUT</td><td>GeneratorAgent</td><td>Generator state machine; transitions must stay co-located with the machine they describe</td></tr>
+  <tr><td>Tool schema registry: maintain, register, expose</td><td>GeneratorAgent (unchanged)</td><td>Registry is used for status publishing and schema re-broadcast — broader than tool dispatch</td></tr>
+</table>
+<h2>ToolDispatcher API</h2>
+<p>File: <span class="file">src/local/tools/tool_dispatcher.py</span></p>
+<pre><code>class ToolDispatcher:
+    """Bus I/O helper for synchronous tool call dispatch.
+    Owned by GeneratorAgent. Uses the generator's publisher to send
+    tool.request.* and opens a short-lived subscriber to receive
+    tool.result.*. State transitions are the caller's responsibility.
+    """
+    CONFIG_NAME = "tool_dispatcher"
+    def __init__(self, tool_timeout: float) -> None:
+        self._tool_timeout = tool_timeout
+        self._pub = ZmqPublisher(PROXY_FRONTEND_ADDR, bind=False)
+    def execute(
+        self,
+        name: str,
+        args: dict,
+        correlation_id: str,
+        schemas: list,
+    ) -> tuple[str, bool]:
+        """Dispatch a tool call and block for the result.
+        Opens a ZmqSubscriber for tool.result.<name> BEFORE publishing
+        tool.request.<name> to avoid a race between publish and subscribe.
+        Polls until correlation_id matches or tool_timeout expires.
+        Args:
+            name: Tool function name; normalized via _normalize() first.
+            args: Tool arguments dict from the model's tool call.
+            correlation_id: Used to match the response envelope.
+            schemas: Current tool schema list; used for name normalization.
+        Returns:
+            (result, timed_out): result is the tool output string;
+            timed_out is True if no matching response arrived in time.
+        """
+        name = self._normalize(name, schemas)
+        req_subject = f"tool.request.{name}"
+        res_subject = f"tool.result.{name}"
+        result_sub = ZmqSubscriber(PROXY_BACKEND_ADDR, subscriptions=[res_subject])
+        try:
+            self._pub.publish(MessageEnvelope.create(
+                message_type="tool_request",
+                subject=req_subject,
+                sender_id=self.id,
+                payload={"tool": name, "args": args},
+                correlation_id=correlation_id,
+            ))
+            deadline = time.monotonic() + self._tool_timeout
+            while time.monotonic() < deadline:
+                remaining_ms = max(1, int((deadline - time.monotonic()) * 1000))
+                msg = result_sub.receive_with_timeout(remaining_ms)
+                if msg is None:
+                    break
+                if msg.correlation_id == correlation_id:
+                    return msg.payload.get("result", ""), False
+        finally:
+            result_sub.close()
+        return f"[tool timeout: {name!r} did not respond within {self._tool_timeout}s]", True
+    def _normalize(self, name: str, schemas: list) -> str:
+        registered = {s.get("function", {}).get("name") for s in schemas}
+        if name in registered:
+            return name
+        name_lower = name.lower()
+        for rname in registered:
+            if rname in name_lower or name_lower in rname:
+                logger.warning("ToolDispatcher: normalizing tool name %r → %r", name, rname)
+                return rname
+        return name
+</code></pre>
+<div class="note">
+  <code>sender_id</code> on the tool request: currently hardcoded as <code>"generator"</code> inside <code>_execute_tool</code> via <code>self._make_envelope</code>. The full implementation passes the generator's <code>self.id</code> to <code>execute()</code> as a parameter so ToolDispatcher doesn't reach into generator state.
+</div>
+<h2>GeneratorAgent changes</h2>
+<h3>__init__</h3>
+<p>Accept injected ToolDispatcher (constructed in run.py with <code>tool_timeout</code> from config):</p>
+<pre><code>def __init__(
+    self,
+    model: str | None = None,
+    temperature: float | None = None,
+    conversation_service=None,
+    compaction_service=None,
+    tool_dispatcher=None,           # ← add
+) -> None:
+    ...
+    self._tool_dispatcher = tool_dispatcher or ToolDispatcher(self._tool_timeout)
+</code></pre>
+<div class="note">
+  Fallback construction in <code>__init__</code> keeps tests that instantiate GeneratorAgent directly working without wiring up run.py.
+</div>
+<h3>_generate() — state transitions move out of _execute_tool, stay in _generate()</h3>
+<pre><code># before (inside for tc in tool_calls loop):
+self._do_transition(GeneratorAction.DISPATCH_TOOL)
+result = self._execute_tool(name, args, correlation_id)
+# after:
+self._do_transition(GeneratorAction.DISPATCH_TOOL)
+self._do_transition(GeneratorAction.AWAIT_RESULT)
+result, timed_out = self._tool_dispatcher.execute(
+    name, args, correlation_id, self._tool_schemas
+)
+if timed_out:
+    self._do_transition(GeneratorAction.TOOL_TIMEOUT)
+else:
+    self._do_transition(GeneratorAction.TOOL_RESULT)
+</code></pre>
+<h3>Methods removed</h3>
+<ul>
+  <li><code>_execute_tool()</code> — replaced by <code>self._tool_dispatcher.execute()</code></li>
+  <li><code>_normalize_tool_name()</code> — moved to <code>ToolDispatcher._normalize()</code></li>
+</ul>
+<h3>Imports removed</h3>
+<ul>
+  <li><code>PROXY_BACKEND_ADDR</code> from bus_config (used only by _execute_tool)</li>
+  <li><code>ZmqSubscriber</code> (used only by _execute_tool)</li>
+</ul>
+<h2>run.py change</h2>
+<pre><code>from local.tools.tool_dispatcher import ToolDispatcher
+_gen_cfg = get_config("generator") or {}
+shared_tool_dispatcher = ToolDispatcher(
+    tool_timeout=_gen_cfg.get("tool_timeout", 20),
+)
+# Pass into generator:
+gen_thread = threading.Thread(
+    target=_start_generator, args=(args.model,),
+    kwargs={
+        "conversation_service": shared_conv,
+        "compaction_service": shared_compaction,
+        "tool_dispatcher": shared_tool_dispatcher,
+    },
+    ...
+)
+</code></pre>
+<h2>Transition sequence — before and after</h2>
+<div class="arch-box">Before (all in _execute_tool):
+  _generate() calls:  DISPATCH_TOOL
+  _execute_tool():    open subscriber
+                      AWAIT_RESULT
+                      publish tool.request.*
+                      poll ...
+                      TOOL_RESULT  (or TOOL_TIMEOUT)
+                      close subscriber
+After (transitions in _generate, I/O in ToolDispatcher):
+  _generate():        DISPATCH_TOOL
+                      AWAIT_RESULT
+  tool_dispatcher.execute():
+                      open subscriber
+                      publish tool.request.*
+                      poll ...
+                      close subscriber
+                      return (result, timed_out)
+  _generate():        TOOL_RESULT  (or TOOL_TIMEOUT)
+</div>
+<div class="note">
+  The state machine sees the same transition sequence. The only change is that AWAIT_RESULT now fires before the subscriber opens rather than after. This is safe — AWAIT_RESULT is a visibility signal, not a coordination mechanism. The race-condition protection is subscribe-before-publish, which ToolDispatcher preserves internally.
+</div>
+<h2>File Map</h2>
+<table>
+  <tr><th>File</th><th>Change</th></tr>
+  <tr><td><code>src/local/tools/tool_dispatcher.py</code></td><td class="new">new — bus I/O + name normalization</td></tr>
+  <tr><td><code>src/local/agents/generator_agent.py</code></td><td class="modified">inject tool_dispatcher; remove _execute_tool + _normalize_tool_name; transitions moved inline in _generate()</td></tr>
+  <tr><td><code>src/local/run.py</code></td><td class="modified">construct ToolDispatcher; inject into generator</td></tr>
+  <tr><td><code>config/tool_dispatcher.yaml</code></td><td class="new">id: tool_dispatcher</td></tr>
+  <tr><td><code>src/local/defaults/tool_dispatcher.yaml</code></td><td class="new">id: tool_dispatcher</td></tr>
+</table>
+<h2>Acceptance Criteria</h2>
+<ul>
+  <li>Generator state machine sees the same DISPATCH_TOOL → AWAIT_RESULT → TOOL_RESULT/TIMEOUT sequence</li>
+  <li>Tool calls still execute with correct correlation_id matching</li>
+  <li>Tool timeout still returns an error string and logs a warning</li>
+  <li>Hallucinated tool names are still normalized before dispatch</li>
+  <li><code>_execute_tool</code> and <code>_normalize_tool_name</code> no longer exist in GeneratorAgent</li>
+  <li>All existing tests pass</li>
+</ul>
+</body>
+</html>

local2 0.2.1__tar.gz → 0.2.2__tar.gz

local2 0.2.1tar.gz → 0.2.2tar.gz