3tears-agent-tools 0.14.0__py3-none-any.whl

3tears_agent_tools-0.14.0.dist-info/METADATA

@@ -0,0 +1,207 @@
+Metadata-Version: 2.4
+Name: 3tears-agent-tools
+Version: 0.14.0
+Summary: Tool framework for LLM agents -- routing, execution, and builtin tools
+Project-URL: Repository, https://github.com/pacepace/3tears
+Author: pace
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.14
+Requires-Dist: 3tears
+Requires-Dist: 3tears-agent-audit
+Requires-Dist: 3tears-agent-memory
+Requires-Dist: 3tears-langgraph
+Requires-Dist: 3tears-media-contracts
+Requires-Dist: 3tears-nats
+Requires-Dist: 3tears-observe
+Requires-Dist: httpx
+Requires-Dist: langchain-core
+Provides-Extra: all
+Requires-Dist: openpyxl; extra == 'all'
+Requires-Dist: pdf2image; extra == 'all'
+Requires-Dist: pillow; extra == 'all'
+Requires-Dist: pint; extra == 'all'
+Requires-Dist: pymupdf; extra == 'all'
+Requires-Dist: pytesseract; extra == 'all'
+Requires-Dist: python-docx; extra == 'all'
+Requires-Dist: simpleeval; extra == 'all'
+Requires-Dist: trafilatura; extra == 'all'
+Provides-Extra: calculator
+Requires-Dist: simpleeval; extra == 'calculator'
+Provides-Extra: document
+Requires-Dist: openpyxl; extra == 'document'
+Requires-Dist: pymupdf; extra == 'document'
+Requires-Dist: python-docx; extra == 'document'
+Provides-Extra: docx
+Requires-Dist: python-docx; extra == 'docx'
+Provides-Extra: fetch
+Requires-Dist: trafilatura; extra == 'fetch'
+Provides-Extra: ocr
+Requires-Dist: pdf2image; extra == 'ocr'
+Requires-Dist: pytesseract; extra == 'ocr'
+Provides-Extra: pdf
+Requires-Dist: pymupdf; extra == 'pdf'
+Provides-Extra: units
+Requires-Dist: pint; extra == 'units'
+Provides-Extra: vision
+Requires-Dist: pillow; extra == 'vision'
+Provides-Extra: xlsx
+Requires-Dist: openpyxl; extra == 'xlsx'
+Description-Content-Type: text/markdown
+
+# 3tears Agent Tools
+
+Tool framework for LLM agents. Provides tool routing, execution, context management, MCP integration, and a set of builtin tools.
+
+Part of the [3tears](https://github.com/pacepace/3tears) framework.
+
+## ToolServer baseline audit
+
+`ToolServer.handle_call` stamps every dispatch with a unified `AuditEvent` envelope (`event_type='tool.call'`) via `threetears.agent.audit.publish_audit`. The baseline emission fires in a `finally` block so success, failure (tool returned `success=False`), and error (tool raised) outcomes all produce a row. Identity axes carry from the active `ToolCallScope` (`actor_user_id`, `calling_agent_id`, `owner_agent_id`, `customer_id`, `correlation_id`); `resource_namespace_id` / `resource_namespace_type` stay `None` at the baseline layer since the tool resolves its target inside `execute`. Per-tool additive events (e.g. `workspace.fs_write`) still publish via `publish_audit` and ride alongside the baseline row under the same `correlation_id`. The `(correlation_id, event_type)` partial unique index on `platform_audit.audit_events` keeps them distinct. Emission is fire-and-forget: NATS publish failures log WARN and never taint the tool's response.
+
+## Tool-as-namespace emission
+
+Tool namespace materialization is platform-owned. `ToolServer.publish_registration` writes the `RegistrationManifest` (carrying `pod_id` + `tools` + the `owner_agent_id` / `customer_id` envelope fields), and a platform-side namespace emitter subscribes to `{ns}.tools.register` and upserts one `platform.namespaces` row of type `tool` per tool. This is the sole writer in the platform.
+
+Agent-spun ToolServers stamp `agent_id` + `customer_id` on the `RegistrationManifest` so the emitter lands rows with the right owner scope; platform-built-in pods (admin tool server, datasource tool pod) leave both `None` and the row lands with NULL owner columns (admitted under the widened `namespaces_row_scope_customer_ck` carve-out for `tool` type alongside `system` / `model`).
+
+The canonical `name` shape is `tools.<sanitized-mcp>.<sanitized-version>` (per `build_namespace_name`); `metadata` carries the pre-sanitized natural-identity fields `mcp_name` / `mcp_version` / `pod_id` so downstream pattern matching (platform access materializer agent.yaml `access.tools` patterns + registry authorizer canonical-name lookup) does not need to reverse the sanitization rules. Deterministic `uuid5` derived from `(mcp_name, version, owner_agent_id_hex)` keeps concurrent emitters race-safe via `ON CONFLICT (id) DO UPDATE`.
+
+The `ToolServer.register_tool` / `deregister_tool` helpers still emit through an injected `namespace_collection` for callers that wire one explicitly, but in production deployments the platform-side emitter is the source of truth and the in-process emission is redundant.
+
+## Installation
+
+```bash
+pip install 3tears-agent-tools
+
+# Optional extras for builtin tools
+pip install "3tears-agent-tools[calculator]"   # simpleeval
+pip install "3tears-agent-tools[units]"        # pint
+pip install "3tears-agent-tools[fetch]"        # trafilatura
+pip install "3tears-agent-tools[document]"     # PyMuPDF, python-docx, openpyxl
+pip install "3tears-agent-tools[all]"          # everything
+```
+
+## Components
+
+### ToolRouter
+
+Routes user messages to the appropriate tool using a lightweight LLM call. Includes recall-intent detection to avoid re-invoking tools when users ask about previous results.
+
+```python
+from threetears.agent.tools import ToolRouter, is_recall_intent
+
+# Quick check -- no LLM call needed
+if is_recall_intent("show me what the calculator said"):
+    # User wants to recall, not invoke
+
+# Full routing with LLM
+router = ToolRouter(chat_model)
+decision = await router.route(user_message, tool_descriptions)
+# decision.tool_name, decision.reasoning
+```
+
+### ToolExecutor
+
+Invokes a tool-LLM: sends the user message to a secondary model configured for a specific task.
+
+```python
+from threetears.agent.tools import ToolExecutor
+
+executor = ToolExecutor()
+result = await executor.invoke_with_tools(
+    chat_model=tool_model,
+    user_message="What is 42 * 17?",
+    tools=[calculator_tool],
+    tool_name="calculator",
+)
+# result.content, result.tool_calls
+```
+
+### ToolContextManager
+
+Tracks tool invocations and results across a conversation for recall support.
+
+```python
+from threetears.agent.tools import ToolContextManager
+
+ctx = ToolContextManager()
+await ctx.record_invocation("calculator", "42 * 17", "714")
+await ctx.get_recall_context("calculator")  # Returns formatted recall string
+```
+
+### McpClient
+
+MCP (Model Context Protocol) integration for connecting to external tool servers.
+
+```python
+from threetears.agent.tools import McpClient
+
+async with McpClient(server_config) as client:
+    tools = await client.list_tools()
+    result = await client.invoke_tool("tool_name", {"param": "value"})
+```
+
+### Builtin Tools
+
+Register all builtin tools at once:
+
+```python
+from threetears.agent.tools import register_builtins, ToolRegistry
+
+registry = ToolRegistry()
+register_builtins(registry)
+# Registers: calculator, unit_converter, dice_roller, date_time,
+#            random_number, web_fetch, text_transform, parse_document
+```
+
+### Todo Tools
+
+Todo list management behind a storage protocol:
+
+```python
+from threetears.agent.tools import TodoStorage, load_todo_tools_from_storage
+
+class MyTodoStorage(TodoStorage):
+    async def add(self, conv_id, user_id, title, list_name, msg_id) -> dict: ...
+    async def list_all(self, conv_id) -> list[dict]: ...
+    # ... other methods
+
+tools = load_todo_tools_from_storage(my_storage, snapshot_callback=on_snapshot)
+```
+
+### Protocols
+
+For media-related capabilities, implement these protocols:
+
+```python
+from threetears.agent.tools import (
+    ImageGenerationBackend,
+    MediaStorage,
+    VisionProvider,
+    TranscriptionProvider,
+)
+```
+
+### Document Parsing
+
+Parse PDF, DOCX, XLSX, and plain text with optional OCR:
+
+```python
+from threetears.agent.tools import parse_document, OcrConfig
+
+result = await parse_document(
+    file_bytes=data,
+    filename="report.pdf",
+    ocr_config=OcrConfig(enabled=True),
+)
+# result.sections -- list of DocumentSection with title, content, page numbers
+```

3tears_agent_tools-0.14.0.dist-info/RECORD

@@ -0,0 +1,66 @@
+threetears/agent/tools/__init__.py,sha256=z9TTY8-lAB201cGvlRyp2zBAqdWxMJ-qItu2U_g44vQ,10373
+threetears/agent/tools/_coercion.py,sha256=nXtjsmWP9vNJ4aI1GHwPe9kt__RfeFG5QkHgUIFECuE,3863
+threetears/agent/tools/aliases.py,sha256=lCYhlZJUXRlqUHTWBprwI1QpJVxWcPkvJm29MN0RU7U,10622
+threetears/agent/tools/base_tool.py,sha256=GgUQnTSTMMwcowWIjq46GlXWUwpHLNxeglBrBmd8HCs,8260
+threetears/agent/tools/bootstrap.py,sha256=1LIV7PfrcUcESJWiCUYMjBPruR6u9cd2l4cYEpn3FM4,11166
+threetears/agent/tools/bridge.py,sha256=el9iVwFymmCbY6N8aaupTMfSxRu5ZNWVKmFYbxfWbnc,4361
+threetears/agent/tools/call_scope.py,sha256=VauOPb4bGC_rRtd48fsy4zYXjFJiATzZ4JmdZ4UnRdc,8517
+threetears/agent/tools/chunker.py,sha256=0m8DHxAWxYEawEkhS5EDfOVKxGFyaqL60BMOg-OpVes,6793
+threetears/agent/tools/collections.py,sha256=4qKaEtitF8nXxcp4RYkCrT93fkH03qIx-0BhdzTwXR8,20669
+threetears/agent/tools/config.py,sha256=N2zQ1qDnDFtnRi59QJnK7neoKMXbbA9pbrh31Wv8oWU,3878
+threetears/agent/tools/consume.py,sha256=EocFDA7mCJfgAbU6caiOc2TuwDz0cJ21CU5rsfXD1lM,10132
+threetears/agent/tools/context.py,sha256=IV6NFfn4GI0nSZBQhaPrCyh-LzTSW8q2sSmmUoM_P40,34431
+threetears/agent/tools/context_envelope.py,sha256=6ksSLp2WIibAFpzrBiJFfpxpR62OM28qYL4au0ITuhc,9228
+threetears/agent/tools/deliver.py,sha256=13XBGLSyDKiaka1slXBLy7viJUWnMQw0CK0h1DBtd5M,8510
+threetears/agent/tools/document.py,sha256=eo-4tka10bF14ofixS2T8ReICW4l8WxkD7kZxRkvBHE,32425
+threetears/agent/tools/engagement.py,sha256=1Gvb3iMWVRqXrVArDvfNOO5bF1vE-XsUmZHAf4u59FI,6950
+threetears/agent/tools/engagement_resolver.py,sha256=MefjDsmivT8msOXC6wAbOjO7iqCoEz-JT7n29H-2PME,12422
+threetears/agent/tools/entities.py,sha256=zHVoyeXYLg_AP9hMN00JcPNbzHPdZMR-Y1uwPqKQJwQ,1788
+threetears/agent/tools/events.py,sha256=hfhWW2G-V5MkCzPyyy4LV1nSPBb1gRMpxKBhQTaKQ0c,3070
+threetears/agent/tools/executor.py,sha256=ZQyDlhA0TOt0xkv7ZI-f6VYV-_tB5uMhxJMeVhjzzpc,4405
+threetears/agent/tools/graph_nodes.py,sha256=7zAFLYuR3M-oVLAMpU3Z9FcVOrlan02m8NdjWCBGUFY,8538
+threetears/agent/tools/langchain_adapter.py,sha256=YRlPBex2HV1moYYAq8kDmMjLQkKhbuQp2fjl3v5bHoA,6228
+threetears/agent/tools/mcp.py,sha256=bMoqh4gwasiWV07UWM4PlawpLA8ciAAAK2lkJOvt2ng,4507
+threetears/agent/tools/object_resolver.py,sha256=vfIXsQCLHiC7l7edZ1o6a0jO91MOgqvonPw2LTLrRxk,10795
+threetears/agent/tools/produce.py,sha256=pe3C9taoh-FHh55uWIXKIjHPeP17d7m3kRcrj11QafU,8435
+threetears/agent/tools/protocols.py,sha256=HOWu74BuvRyWwHsYBYnSDy62SQXOpEhYgX8kYgJctL8,834
+threetears/agent/tools/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+threetears/agent/tools/registry.py,sha256=MuPn6UObIzqnaIzcwmnr3NB9RJuepfq4wzkyDmb3euU,2670
+threetears/agent/tools/report.py,sha256=9GnrdizPw07WqxZcU_uW7i9BNstsb9IPv-VgZI_InXQ,21136
+threetears/agent/tools/router.py,sha256=3rx_JU-WHZf8h0SHrA9TV2uZhZWfi_lnIKllM_JekSo,8054
+threetears/agent/tools/serve.py,sha256=pSi5Nr7qChGaGwwdcF-YThPgCmTor3NtcQAAL_-eJsI,9054
+threetears/agent/tools/server.py,sha256=HuQUbZ5xx5NB-dRIcSqqJNzPuy0KRkyv0IADNIqi9tU,96435
+threetears/agent/tools/strategy.py,sha256=-jVguOQDBzHfrhc0EsPhBmnqoDxEZZl1VpkNZhV90sE,14719
+threetears/agent/tools/todo.py,sha256=HiFuXw4niioYKq9Rtq1qJFest0miO6cTREIAElMuj84,10823
+threetears/agent/tools/tool_llm_dispatch.py,sha256=ZvbAPHtcxMoHUaB7RXnRF_qC_NkhuuF5_ZPb0dlktcY,8965
+threetears/agent/tools/types.py,sha256=wiaJpmY3fZQH7lkrAY8n8ncbr8cHQUKXr6nZDAqXT8Y,457
+threetears/agent/tools/utils.py,sha256=Ata2Tli2vflXtfArLuG-DzBTNRuc2ZprBkoowksZBds,295
+threetears/agent/tools/workflow.py,sha256=q7fVPxWlO0Istg6bjwuo2rIPq6-KSe9DND4GrVc-TSA,4699
+threetears/agent/tools/builtin/__init__.py,sha256=8zeSdSbnlS_CnTiHCZepkzRGUzKGkl_9fsi8Yhz_ggM,6230
+threetears/agent/tools/builtin/analyze_media.py,sha256=UXeUZp3PpxFvUVDR3_PWxEGWlrh_Q_-wdxxTfsaio4c,27556
+threetears/agent/tools/builtin/calculator.py,sha256=UoUiYD90vt2lM3IsVpeo_4WQplGHzWtQZ0C5BFeqlno,6567
+threetears/agent/tools/builtin/context_recall.py,sha256=sMMCzjVhW6LuSt8SzzyQ6pENaE--hIjchHUfZfDTN1k,6066
+threetears/agent/tools/builtin/current_date.py,sha256=Hl2aW_p2vS6rnFreu_lhUeYxqWwzZH2Zcd_EhdcNFo0,5735
+threetears/agent/tools/builtin/dictionary.py,sha256=P9KrTuhVUO6v3c3vWyou8CoJlCfwJRuzSQNIrMnZeGM,5628
+threetears/agent/tools/builtin/image_generation.py,sha256=pyZjVKPz-SHFH7ZCHfINHjNTj1I7e_LcXPRiEJhibbc,11397
+threetears/agent/tools/builtin/image_prep.py,sha256=qn3f-Ky7MNktVnXq_Lv3m9DcZLLQ18uDvjH8J6A4CIo,7013
+threetears/agent/tools/builtin/timezone_converter.py,sha256=ylTUSs5PHbz0Veea_X6CnXI3t95PW5eYyjxOZ5llrwQ,6444
+threetears/agent/tools/builtin/unit_converter.py,sha256=7aRGm0opsnFMHEE3OtZBWs18BOK8v7sECzDthBAraO0,4530
+threetears/agent/tools/builtin/web_fetch.py,sha256=hH8UEHirtB1nCcYYGvUFSS3h7SIJyxjoBMynCbw7wyY,7796
+threetears/agent/tools/builtin/web_search.py,sha256=BIN_6WWwOOMGSuwyU_wUXc6OMF-kA1qrZqn589ZacKg,4862
+threetears/agent/tools/migrations/__init__.py,sha256=_Hpb6V6jABgT_Vh3edu0C45tUjafcxFbl1_5MXdsCfg,3482
+threetears/agent/tools/migrations/v001_create_context_items_table.py,sha256=BeI3A-wWQblHBSl0s_ryPxgj6EYYb5TEWlEpeEZUFQk,1923
+threetears/agent/tools/migrations/v002_datetime_to_datetimetz.py,sha256=K-kj6H61fbB0SeyKnfiNw7SzXaZ4gVlleIU0YGtFh5U,5184
+threetears/agent/tools/migrations/v003_align_context_items_shape.py,sha256=IvC0zPQC-nZ8Rtp4OE6tvZk40rnuSh3m18anT-yXWGU,7188
+threetears/agent/tools/migrations/v004_tool_result_dedup_index.py,sha256=AoJ7Scy8PvOeHNoITwByB6QApbUZ_uBGcm_l2HEjd1w,2534
+threetears/agent/tools/platform_migrations/__init__.py,sha256=WsXVhpWPLEEyn1TICYhgNyMTm_lGMCN8BztLNWaapUM,2893
+threetears/agent/tools/platform_migrations/v001_add_tool_eligibility_columns.py,sha256=cRPfxB1A5RGCJjg5S9SFnK0YtjkQmHOV2jUjC7PTAFs,2384
+threetears/agent/tools/reports/__init__.py,sha256=myR_uloZkUSbVA-vJzJLrxc9wV9u1fgwPNZ0ZRZJq68,761
+threetears/agent/tools/reports/markdown_compiler.py,sha256=9evSspQ4pxSCVRxTVV2iudzBy8pH1BtFFQaisoZe4MQ,9352
+threetears/agent/tools/reports/mermaid_generator.py,sha256=rao_f423W90kcfQCs6nWmm1LQRwfKBYNxdtM4UyeS2Y,6803
+threetears/agent/tools/reports/pdf_renderer.py,sha256=7CltWlimHyavDtxnjD-rFPZONk9GBS2wGIlMvpOsZRA,4655
+threetears/agent/tools/reports/severity.py,sha256=cK5XRXTgo1M9M31Q7jqIOwJ0UJfz3dT-M3qv-VJkqCY,2614
+3tears_agent_tools-0.14.0.dist-info/METADATA,sha256=5mUBkjY1_h_coWqtl6s-en-j9m1CYN_OMNCpSrJ1IlU,8290
+3tears_agent_tools-0.14.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+3tears_agent_tools-0.14.0.dist-info/licenses/LICENSE,sha256=7GWEoEOcFJenZLt4LDzqH2K7QLxo_2m8rzG7Vv8VGXo,1066
+3tears_agent_tools-0.14.0.dist-info/RECORD,,

3tears_agent_tools-0.14.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

3tears_agent_tools-0.14.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mark Pace
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

threetears/agent/tools/__init__.py

@@ -0,0 +1,225 @@
+"""3tears agent-tools: tool registry, context management, and built-in tools."""
+
+from __future__ import annotations
+
+# Version derived from pyproject.toml so the metadata is the single
+# source of truth -- a future release that bumps pyproject without
+# updating ``__init__.py`` can't drift the runtime ``__version__``.
+# The except guard handles the rare case where the package isn't
+# installed via importlib.metadata (e.g. running directly from a
+# checked-out source tree without ``uv sync``); the fallback keeps
+# imports working but reports ``unknown`` rather than crashing.
+from importlib.metadata import PackageNotFoundError as _PackageNotFoundError
+from importlib.metadata import version as _version
+from typing import TYPE_CHECKING
+
+try:
+    __version__ = _version("3tears-agent-tools")
+except _PackageNotFoundError:  # pragma: no cover - dev fallback
+    __version__ = "unknown"
+
+# lazy public API (PEP 562). the package namespace no longer imports its
+# implementation modules eagerly: importing this package (or any of its
+# submodules) costs only this file, and each public attribute resolves
+# its defining module on first access. the TYPE_CHECKING block carries
+# the real imports so mypy and IDEs see the full statically-typed API;
+# the _LAZY map is the runtime equivalent. the three-way agreement
+# between __all__, _LAZY, and the TYPE_CHECKING block is pinned by the
+# package's lazy-surface consistency test.
+# decision record: docs/separate-concerns-decisions.md (hand-rolled
+# PEP 562 over lazy_loader -- zero added runtime deps, no stub drift).
+if TYPE_CHECKING:
+    from threetears.agent.tools.builtin import register_builtins
+    from threetears.agent.tools.builtin.analyze_media import AnalyzerConfig, create_analyze_media_tool
+    from threetears.agent.tools.builtin.image_generation import (
+        ImageGenerationContext,
+        ImageGenerationInput,
+        create_image_generation_tool,
+    )
+    from threetears.agent.tools.chunker import (
+        ChunkResult,
+        ChunkStrategy,
+        chunk_by_headers,
+        chunk_by_lines,
+        chunk_by_sections,
+        chunk_content,
+        register_chunk_strategy,
+    )
+    from threetears.agent.tools.collections import (
+        ContextItemCollection,
+        context_items_table,
+        migrate_context_items_schema,
+    )
+    from threetears.agent.tools.context import ToolContextManager
+    from threetears.agent.tools.document import (
+        DocumentResult,
+        DocumentSection,
+        OcrConfig,
+        ParseDocumentInput,
+        create_parse_document_tool,
+        detect_mime_from_filename,
+        parse_document,
+    )
+    from threetears.agent.tools.entities import ContextItemEntity
+    from threetears.agent.tools.events import TodosChangedEvent
+    from threetears.agent.tools.executor import ToolExecutionResult, ToolExecutor
+    from threetears.agent.tools.mcp import McpClient, McpTool, McpToolResult
+    from threetears.agent.tools.protocols import (
+        GeneratedImage,
+        ImageGenerationBackend,
+        MediaInfo,
+        MediaStorage,
+        TextProvider,
+        TranscriptionProvider,
+        VisionProvider,
+    )
+    from threetears.agent.tools.registry import ToolRegistry
+    from threetears.agent.tools.router import DEFAULT_ROUTING_PROMPT, ToolRouter, ToolRoutingDecision, is_recall_intent
+    from threetears.agent.tools.todo import TodoStorage, load_todo_tools as load_todo_tools_from_storage
+    from threetears.agent.tools.tool_llm_dispatch import (
+        InvokeToolLlmInput,
+        ToolLlmInvocation,
+        ToolLlmResolver,
+        load_tool_llm_dispatch,
+    )
+    from threetears.agent.tools.types import ChatModelFactory
+    from threetears.agent.tools.workflow import load_workflow_tools
+
+# public attribute -> (defining module, attribute name in that module)
+_LAZY: dict[str, tuple[str, str]] = {
+    "AnalyzerConfig": ("threetears.agent.tools.builtin.analyze_media", "AnalyzerConfig"),
+    "ChatModelFactory": ("threetears.agent.tools.types", "ChatModelFactory"),
+    "ChunkResult": ("threetears.agent.tools.chunker", "ChunkResult"),
+    "ChunkStrategy": ("threetears.agent.tools.chunker", "ChunkStrategy"),
+    "ContextItemCollection": ("threetears.agent.tools.collections", "ContextItemCollection"),
+    "ContextItemEntity": ("threetears.agent.tools.entities", "ContextItemEntity"),
+    "DEFAULT_ROUTING_PROMPT": ("threetears.agent.tools.router", "DEFAULT_ROUTING_PROMPT"),
+    "DocumentResult": ("threetears.agent.tools.document", "DocumentResult"),
+    "DocumentSection": ("threetears.agent.tools.document", "DocumentSection"),
+    "GeneratedImage": ("threetears.agent.tools.protocols", "GeneratedImage"),
+    "ImageGenerationBackend": ("threetears.agent.tools.protocols", "ImageGenerationBackend"),
+    "ImageGenerationContext": ("threetears.agent.tools.builtin.image_generation", "ImageGenerationContext"),
+    "ImageGenerationInput": ("threetears.agent.tools.builtin.image_generation", "ImageGenerationInput"),
+    "InvokeToolLlmInput": ("threetears.agent.tools.tool_llm_dispatch", "InvokeToolLlmInput"),
+    "McpClient": ("threetears.agent.tools.mcp", "McpClient"),
+    "McpTool": ("threetears.agent.tools.mcp", "McpTool"),
+    "McpToolResult": ("threetears.agent.tools.mcp", "McpToolResult"),
+    "MediaInfo": ("threetears.agent.tools.protocols", "MediaInfo"),
+    "MediaStorage": ("threetears.agent.tools.protocols", "MediaStorage"),
+    "OcrConfig": ("threetears.agent.tools.document", "OcrConfig"),
+    "ParseDocumentInput": ("threetears.agent.tools.document", "ParseDocumentInput"),
+    "TextProvider": ("threetears.agent.tools.protocols", "TextProvider"),
+    "TodoStorage": ("threetears.agent.tools.todo", "TodoStorage"),
+    "TodosChangedEvent": ("threetears.agent.tools.events", "TodosChangedEvent"),
+    "ToolContextManager": ("threetears.agent.tools.context", "ToolContextManager"),
+    "ToolExecutionResult": ("threetears.agent.tools.executor", "ToolExecutionResult"),
+    "ToolExecutor": ("threetears.agent.tools.executor", "ToolExecutor"),
+    "ToolLlmInvocation": ("threetears.agent.tools.tool_llm_dispatch", "ToolLlmInvocation"),
+    "ToolLlmResolver": ("threetears.agent.tools.tool_llm_dispatch", "ToolLlmResolver"),
+    "ToolRegistry": ("threetears.agent.tools.registry", "ToolRegistry"),
+    "ToolRouter": ("threetears.agent.tools.router", "ToolRouter"),
+    "ToolRoutingDecision": ("threetears.agent.tools.router", "ToolRoutingDecision"),
+    "TranscriptionProvider": ("threetears.agent.tools.protocols", "TranscriptionProvider"),
+    "VisionProvider": ("threetears.agent.tools.protocols", "VisionProvider"),
+    "chunk_by_headers": ("threetears.agent.tools.chunker", "chunk_by_headers"),
+    "chunk_by_lines": ("threetears.agent.tools.chunker", "chunk_by_lines"),
+    "chunk_by_sections": ("threetears.agent.tools.chunker", "chunk_by_sections"),
+    "chunk_content": ("threetears.agent.tools.chunker", "chunk_content"),
+    "context_items_table": ("threetears.agent.tools.collections", "context_items_table"),
+    "create_analyze_media_tool": ("threetears.agent.tools.builtin.analyze_media", "create_analyze_media_tool"),
+    "create_image_generation_tool": ("threetears.agent.tools.builtin.image_generation", "create_image_generation_tool"),
+    "create_parse_document_tool": ("threetears.agent.tools.document", "create_parse_document_tool"),
+    "detect_mime_from_filename": ("threetears.agent.tools.document", "detect_mime_from_filename"),
+    "is_recall_intent": ("threetears.agent.tools.router", "is_recall_intent"),
+    "load_todo_tools_from_storage": ("threetears.agent.tools.todo", "load_todo_tools"),
+    "load_tool_llm_dispatch": ("threetears.agent.tools.tool_llm_dispatch", "load_tool_llm_dispatch"),
+    "load_workflow_tools": ("threetears.agent.tools.workflow", "load_workflow_tools"),
+    "migrate_context_items_schema": ("threetears.agent.tools.collections", "migrate_context_items_schema"),
+    "parse_document": ("threetears.agent.tools.document", "parse_document"),
+    "register_builtins": ("threetears.agent.tools.builtin", "register_builtins"),
+    "register_chunk_strategy": ("threetears.agent.tools.chunker", "register_chunk_strategy"),
+}
+
+__all__ = [
+    "AnalyzerConfig",
+    "ChunkResult",
+    "ChunkStrategy",
+    "ChatModelFactory",
+    "ContextItemCollection",
+    "ContextItemEntity",
+    "context_items_table",
+    "migrate_context_items_schema",
+    "DEFAULT_ROUTING_PROMPT",
+    "DocumentResult",
+    "DocumentSection",
+    "GeneratedImage",
+    "ImageGenerationBackend",
+    "ImageGenerationContext",
+    "ImageGenerationInput",
+    "InvokeToolLlmInput",
+    "McpClient",
+    "McpTool",
+    "McpToolResult",
+    "MediaInfo",
+    "MediaStorage",
+    "OcrConfig",
+    "TextProvider",
+    "ParseDocumentInput",
+    "ToolContextManager",
+    "TodoStorage",
+    "TodosChangedEvent",
+    "ToolExecutionResult",
+    "ToolExecutor",
+    "ToolLlmInvocation",
+    "ToolLlmResolver",
+    "ToolRegistry",
+    "ToolRouter",
+    "ToolRoutingDecision",
+    "TranscriptionProvider",
+    "VisionProvider",
+    "chunk_by_headers",
+    "chunk_by_lines",
+    "chunk_by_sections",
+    "chunk_content",
+    "create_analyze_media_tool",
+    "create_image_generation_tool",
+    "create_parse_document_tool",
+    "detect_mime_from_filename",
+    "is_recall_intent",
+    "load_tool_llm_dispatch",
+    "load_todo_tools_from_storage",
+    "load_workflow_tools",
+    "parse_document",
+    "register_builtins",
+    "register_chunk_strategy",
+]
+
+
+def __getattr__(name: str) -> object:
+    """resolve a public attribute from its defining module on first access.
+
+    :param name: attribute name being resolved
+    :ptype name: str
+    :return: the resolved attribute (also cached in module globals so
+        ``__getattr__`` fires at most once per name)
+    :rtype: object
+    :raises AttributeError: when ``name`` is not part of the public API
+    """
+    entry = _LAZY.get(name)
+    if entry is None:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+    from importlib import import_module
+
+    module_name, attr = entry
+    value: object = getattr(import_module(module_name), attr)
+    globals()[name] = value
+    return value
+
+
+def __dir__() -> list[str]:
+    """include lazy attributes in ``dir()`` output.
+
+    :return: sorted union of materialized globals and lazy names
+    :rtype: list[str]
+    """
+    return sorted(set(globals()) | set(_LAZY))

threetears/agent/tools/_coercion.py

@@ -0,0 +1,102 @@
+"""input-value coercion helpers for TearsTool subclasses.
+
+LLMs routinely send loose values for object/array tool parameters:
+empty strings where a dict is expected, JSON-encoded strings where
+a dict/list is expected, arguments omitted entirely. this module
+provides pure functions that rewrite those loose values toward the
+declared JSON schema type before dispatch, so subclasses receive
+the native Python container they expect.
+
+the coercion engages only for fields whose declared type is
+``object`` or ``array``. every other field passes through
+untouched. explicit ``None`` is preserved as a "not provided"
+sentinel so required-field checks in subclasses still fire.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+__all__ = [
+    "coerce_value",
+    "normalize_kwargs",
+]
+
+
+def coerce_value(value: Any, declared_type: str | None) -> Any:
+    """coerce single MCP input value toward its declared JSON schema type.
+
+    handles two LLM mistakes: empty string supplied for complex type
+    (becomes empty container), and JSON-encoded string supplied where
+    native dict/list is expected (gets decoded). values already of
+    correct type, or values that cannot be safely coerced, pass
+    through unchanged.
+
+    :param value: raw value supplied by caller
+    :ptype value: Any
+    :param declared_type: JSON schema ``type`` for this parameter or None
+    :ptype declared_type: str | None
+    :return: value coerced to declared type when possible, else original
+    :rtype: Any
+    """
+    result = value
+    # only empty *strings* are treated as "give me the empty container" --
+    # literal 0, False, or empty tuple must pass through so type-strict
+    # subclasses still see the original value (and can reject it).
+    if declared_type == "object" and not isinstance(value, dict):
+        if value == "":
+            result = {}
+        elif isinstance(value, str):
+            try:
+                parsed = json.loads(value)
+            except TypeError, ValueError:
+                parsed = None
+            if isinstance(parsed, dict):
+                result = parsed
+    elif declared_type == "array" and not isinstance(value, list):
+        if value == "":
+            result = []
+        elif isinstance(value, str):
+            try:
+                parsed = json.loads(value)
+            except TypeError, ValueError:
+                parsed = None
+            if isinstance(parsed, list):
+                result = parsed
+    return result
+
+
+def normalize_kwargs(
+    kwargs: dict[str, Any],
+    input_schema: dict[str, Any],
+) -> dict[str, Any]:
+    """coerce loose LLM-supplied kwargs to match declared schema types.
+
+    inspects ``input_schema['properties']`` and rewrites entries in
+    kwargs whose declared type is ``object`` or ``array`` when the
+    supplied value is a wrong-shape loose container (empty string
+    or JSON-encoded string). values matching their declared type
+    are passed through untouched. keys not present in the schema
+    are passed through untouched. explicit ``None`` is preserved
+    so per-action required-field checks still function.
+
+    :param kwargs: raw tool input parameters as supplied by caller
+    :ptype kwargs: dict[str, Any]
+    :param input_schema: tool's JSON schema for input parameters
+    :ptype input_schema: dict[str, Any]
+    :return: parameters with wrong-type values coerced where possible
+    :rtype: dict[str, Any]
+    """
+    properties = input_schema.get("properties", {})
+    if not properties:
+        return dict(kwargs)
+    normalized: dict[str, Any] = {}
+    for key, value in kwargs.items():
+        prop = properties.get(key)
+        if prop is None or value is None:
+            normalized[key] = value
+            continue
+        declared_type = prop.get("type")
+        normalized[key] = coerce_value(value, declared_type)
+    return normalized