chuk-tool-processor 0.1.6__py3-none-any.whl → 0.1.7__py3-none-any.whl

chuk_tool_processor-0.1.7.dist-info/METADATA

@@ -0,0 +1,401 @@
+Metadata-Version: 2.4
+Name: chuk-tool-processor
+Version: 0.1.7
+Summary: Add your description here
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: chuk-mcp>=0.1.12
+Requires-Dist: dotenv>=0.9.9
+Requires-Dist: openai>=1.76.0
+Requires-Dist: pydantic>=2.11.3
+Requires-Dist: uuid>=1.30
+
+# CHUK Tool Processor
+
+An async-native framework for registering, discovering, and executing tools referenced in LLM responses.
+
+## Quick Start
+
+### Installation
+
+```bash
+# Clone the repository
+git clone https://github.com/your-org/chuk-tool-processor.git
+cd chuk-tool-processor
+
+# Install with pip
+pip install -e .
+```
+
+### Basic Usage
+
+```python
+import asyncio
+from chuk_tool_processor.registry import register_tool, initialize
+from chuk_tool_processor.models.tool_call import ToolCall
+from chuk_tool_processor.execution.strategies.inprocess_strategy import InProcessStrategy
+from chuk_tool_processor.execution.tool_executor import ToolExecutor
+
+# Register a simple tool
+@register_tool(name="calculator", description="Perform basic calculations")
+class CalculatorTool:
+    async def execute(self, operation: str, x: float, y: float) -> dict:
+        if operation == "add":
+            result = x + y
+        elif operation == "multiply":
+            result = x * y
+        else:
+            raise ValueError(f"Unknown operation: {operation}")
+            
+        return {
+            "operation": operation,
+            "x": x,
+            "y": y,
+            "result": result
+        }
+
+# Setup and execute tools
+async def main():
+    # Initialize registry
+    await initialize()
+    
+    # Get the default registry
+    from chuk_tool_processor.registry import get_default_registry
+    registry = await get_default_registry()
+    
+    # Create execution strategy and executor
+    strategy = InProcessStrategy(registry)
+    executor = ToolExecutor(registry=registry, strategy=strategy)
+    
+    # Create a tool call
+    call = ToolCall(
+        tool="calculator",
+        arguments={
+            "operation": "multiply",
+            "x": 5,
+            "y": 7
+        }
+    )
+    
+    # Execute tool
+    results = await executor.execute([call])
+    
+    # Display result
+    result = results[0]
+    if not result.error:
+        print(f"Result: {result.result}")
+    else:
+        print(f"Error: {result.error}")
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+## Core Features
+
+### Async-Native Architecture
+
+The entire framework is built with native `async/await` support, allowing for:
+- Non-blocking execution of tools
+- True concurrency with controlled parallelism
+- Task-local context tracking across async boundaries
+
+### Tool Registry
+
+Tools are registered in a central registry with optional namespaces:
+
+```python
+# Register with default parameters
+@register_tool()
+class SimpleGreeter:
+    async def execute(self, name: str) -> str:
+        return f"Hello, {name}!"
+
+# Register with custom name and namespace
+@register_tool(name="weather", namespace="api", description="Get weather info")
+class WeatherTool:
+    async def execute(self, location: str, units: str = "metric") -> dict:
+        # Implementation...
+        return {"temperature": 23.5, "conditions": "Sunny"}
+```
+
+Initialize and access the registry:
+
+```python
+# Initialize registry (required at startup)
+await initialize()
+
+# Get registry
+registry = await get_default_registry()
+
+# Look up a tool
+tool = await registry.get_tool("weather", namespace="api")
+
+# List registered tools
+tools = await registry.list_tools()
+
+# Get tool metadata
+metadata = await registry.get_metadata("weather", namespace="api")
+```
+
+### Execution Strategies
+
+Two execution strategies are provided:
+
+#### 1. InProcessStrategy
+
+Executes tools in the same process with optional concurrency control:
+
+```python
+from chuk_tool_processor.execution.strategies.inprocess_strategy import InProcessStrategy
+
+strategy = InProcessStrategy(
+    registry,
+    default_timeout=10.0,     # Timeout for tool execution
+    max_concurrency=5         # Maximum concurrent executions
+)
+```
+
+#### 2. SubprocessStrategy
+
+Executes tools in separate processes for true isolation:
+
+```python
+from chuk_tool_processor.execution.strategies.subprocess_strategy import SubprocessStrategy
+
+strategy = SubprocessStrategy(
+    registry,
+    max_workers=4,            # Maximum worker processes
+    default_timeout=30.0      # Timeout for tool execution
+)
+```
+
+### Execution Wrappers
+
+Enhance tool execution with optional wrappers:
+
+#### Retry Logic
+
+```python
+from chuk_tool_processor.execution.wrappers.retry import RetryConfig, RetryableToolExecutor
+
+# Use as a wrapper
+retry_executor = RetryableToolExecutor(
+    executor=base_executor,
+    default_config=RetryConfig(
+        max_retries=3,
+        base_delay=0.5,
+        jitter=True
+    )
+)
+
+# Or as a decorator
+from chuk_tool_processor.execution.wrappers.retry import retryable
+
+@retryable(max_retries=3, base_delay=0.5)
+@register_tool(name="flaky_api")
+class FlakyApiTool:
+    async def execute(self, query: str) -> dict:
+        # Implementation with potential failures
+        pass
+```
+
+#### Caching
+
+```python
+from chuk_tool_processor.execution.wrappers.caching import InMemoryCache, CachingToolExecutor
+
+# Use as a wrapper
+cache = InMemoryCache(default_ttl=60)  # 60 second TTL
+cache_executor = CachingToolExecutor(
+    executor=base_executor,
+    cache=cache
+)
+
+# Or as a decorator
+from chuk_tool_processor.execution.wrappers.caching import cacheable
+
+@cacheable(ttl=300)  # Cache for 5 minutes
+@register_tool(name="expensive_operation")
+class ExpensiveOperationTool:
+    async def execute(self, input_value: int) -> dict:
+        # Expensive computation
+        pass
+```
+
+#### Rate Limiting
+
+```python
+from chuk_tool_processor.execution.wrappers.rate_limiting import RateLimiter, RateLimitedToolExecutor
+
+# Use as a wrapper
+limiter = RateLimiter(global_limit=100, global_period=60.0)  # 100 requests per minute
+rate_limited_executor = RateLimitedToolExecutor(
+    executor=base_executor,
+    limiter=limiter
+)
+
+# Or as a decorator
+from chuk_tool_processor.execution.wrappers.rate_limiting import rate_limited
+
+@rate_limited(limit=5, period=60.0)  # 5 requests per minute
+@register_tool(name="external_api")
+class ExternalApiTool:
+    async def execute(self, query: str) -> dict:
+        # Call to rate-limited external API
+        pass
+```
+
+### Streaming Tool Support
+
+Tools can stream results incrementally:
+
+```python
+from chuk_tool_processor.models.streaming_tool import StreamingTool
+from pydantic import BaseModel, Field
+from typing import AsyncIterator
+
+@register_tool(name="counter")
+class CounterTool(StreamingTool):
+    """Stream incremental counts."""
+    
+    class Arguments(BaseModel):
+        start: int = Field(1, description="Starting value")
+        end: int = Field(10, description="Ending value")
+        delay: float = Field(0.5, description="Delay between items")
+    
+    class Result(BaseModel):
+        value: int
+        timestamp: str
+    
+    async def _stream_execute(self, start: int, end: int, delay: float) -> AsyncIterator[Result]:
+        """Stream each count with a delay."""
+        from datetime import datetime
+        
+        for i in range(start, end + 1):
+            await asyncio.sleep(delay)
+            yield self.Result(
+                value=i,
+                timestamp=datetime.now().isoformat()
+            )
+
+# Stream results
+async for result in executor.stream_execute([tool_call]):
+    print(f"Received: {result.result.value}")
+```
+
+### Comprehensive Error Handling
+
+Errors are captured in the result objects rather than raising exceptions:
+
+```python
+# Execute tool calls
+results = await executor.execute([call1, call2, call3])
+
+for result in results:
+    if result.error:
+        print(f"Tool {result.tool} failed: {result.error}")
+        print(f"Duration: {(result.end_time - result.start_time).total_seconds()}s")
+    else:
+        print(f"Tool {result.tool} succeeded: {result.result}")
+```
+
+### Validation
+
+Validate tool arguments and results:
+
+```python
+from pydantic import BaseModel
+from chuk_tool_processor.models.validated_tool import ValidatedTool
+
+@register_tool(name="validate_data", namespace="utils")
+class ValidatedDataTool(ValidatedTool):
+    class Arguments(BaseModel):
+        username: str
+        age: int
+        email: str
+    
+    class Result(BaseModel):
+        is_valid: bool
+        errors: list[str] = []
+    
+    async def _execute(self, username: str, age: int, email: str) -> Result:
+        errors = []
+        
+        if len(username) < 3:
+            errors.append("Username too short")
+        
+        if age < 18:
+            errors.append("Must be 18 or older")
+            
+        if "@" not in email:
+            errors.append("Invalid email")
+            
+        return self.Result(
+            is_valid=len(errors) == 0,
+            errors=errors
+        )
+```
+
+## Processing LLM Responses
+
+The `ToolProcessor` helps extract and execute tool calls from LLM responses:
+
+```python
+from chuk_tool_processor.core.processor import ToolProcessor
+
+# Create processor
+processor = ToolProcessor()
+await processor.initialize()
+
+# Process text with tool calls
+llm_output = """
+I'll help calculate that for you.
+
+<tool name="calculator" args='{"operation": "multiply", "x": 5, "y": 7}'/>
+
+The result should be 35.
+"""
+
+# Extract and execute tool calls
+results = await processor.process_text(llm_output)
+
+# Process results
+for result in results:
+    print(f"Tool: {result.tool}")
+    print(f"Result: {result.result}")
+    print(f"Error: {result.error}")
+```
+
+The processor supports various formats:
+
+```python
+# XML format
+<tool name="calculator" args='{"operation": "add", "x": 5, "y": 3}'/>
+
+# OpenAI function call format
+{
+  "function_call": {
+    "name": "calculator",
+    "arguments": "{\"operation\": \"add\", \"x\": 5, \"y\": 3}"
+  }
+}
+
+# JSON format
+{
+  "tool_calls": [
+    {
+      "id": "call_123",
+      "type": "function",
+      "function": {
+        "name": "calculator",
+        "arguments": "{\"operation\": \"add\", \"x\": 5, \"y\": 3}"
+      }
+    }
+  ]
+}
+```
+
+## License
+
+This project is licensed under the MIT License - see the LICENSE file for details.

chuk_tool_processor-0.1.7.dist-info/RECORD

@@ -0,0 +1,58 @@
+chuk_tool_processor/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+chuk_tool_processor/core/__init__.py,sha256=slM7pZna88tyZrF3KtN22ApYyCqGNt5Yscv-knsLOOA,38
+chuk_tool_processor/core/exceptions.py,sha256=h4zL1jpCY1Ud1wT8xDeMxZ8GR8ttmkObcv36peUHJEA,1571
+chuk_tool_processor/core/processor.py,sha256=ttEYZTQHctXXiUP8gxAMCCSjbRvyOHojQe_UJezJYRs,18369
+chuk_tool_processor/execution/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+chuk_tool_processor/execution/tool_executor.py,sha256=NSzmvqGMMyKuVapJAmPr-YtNgGhZI3fcAxhilyGG5kY,12174
+chuk_tool_processor/execution/strategies/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+chuk_tool_processor/execution/strategies/inprocess_strategy.py,sha256=7Vx8zZ10DSK73tfinahAHElprctIJ1f4WKaR8lJf_Jk,21710
+chuk_tool_processor/execution/strategies/subprocess_strategy.py,sha256=6ByvqHhZ5fenrV7yPNRUHeid-htTiVu05Gn0n6ImXg4,20477
+chuk_tool_processor/execution/wrappers/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+chuk_tool_processor/execution/wrappers/caching.py,sha256=1pSyouYT4H7AGkNcK_7wWAIT1d4AKnHJlKBODPO8tZw,20416
+chuk_tool_processor/execution/wrappers/rate_limiting.py,sha256=CBBsI1VLosjo8dZXLeJ3IaclGvy9VdjGyqgunY089KQ,9231
+chuk_tool_processor/execution/wrappers/retry.py,sha256=oK6g0Ey8zbAubOgOvDbTFyvP1bVCI53knjXgfd_b3dw,10350
+chuk_tool_processor/logging/__init__.py,sha256=Uux0QnL6Xcd4vNjtt54rNei3yvxUZ-sOuAahlcPAez0,3382
+chuk_tool_processor/logging/context.py,sha256=8wLE6yoDxush7rGu_wTzVCautqq-Jq_0R9SBxLOjpwI,8520
+chuk_tool_processor/logging/formatter.py,sha256=RhlV6NqBYRBOtytDY49c9Y1J4l02ZjNXIgVRn03tfSQ,3061
+chuk_tool_processor/logging/helpers.py,sha256=c1mS1sb_rh4bKG0hisyvT7l7cirQfXPSyWeBqmqALRw,5941
+chuk_tool_processor/logging/metrics.py,sha256=s59Au8q0eqGGtJMDqmJBZhbJHh4BWGE1CzT0iI8lRS8,3624
+chuk_tool_processor/mcp/__init__.py,sha256=vR9HHxLpXlKTIIwJJRr3QTmZegcdedR1YKyb46j6FIM,689
+chuk_tool_processor/mcp/mcp_tool.py,sha256=BcFsW0iVXUpE0o-h3u2hYX-88EmfV80nMUoZPyZs_IY,3242
+chuk_tool_processor/mcp/register_mcp_tools.py,sha256=0q73gafC1d0ei_gqNidcUeY7NUg13UZdjhVOKEFcD5o,3642
+chuk_tool_processor/mcp/setup_mcp_sse.py,sha256=FmXyOG9DuH2pzr1TLTFRFLlW23YkFG8rzSdpybtPCJg,2865
+chuk_tool_processor/mcp/setup_mcp_stdio.py,sha256=P9qSgmxoNQbsOlGp83DlLLpN9BsG__MhlRsxFplNP3M,2753
+chuk_tool_processor/mcp/stream_manager.py,sha256=mrmlG54P_xLbDYz_rBjdu-OPMnbi916dgyJg7BrIbjM,12798
+chuk_tool_processor/mcp/transport/__init__.py,sha256=7QQqeSKVKv0N9GcyJuYF0R4FDZeooii5RjggvFFg5GY,296
+chuk_tool_processor/mcp/transport/base_transport.py,sha256=1E29LjWw5vLQrPUDF_9TJt63P5dxAAN7n6E_KiZbGUY,3427
+chuk_tool_processor/mcp/transport/sse_transport.py,sha256=bryH9DOWOn5qr6LsimTriukDC4ix2kuRq6bUv9qOV20,7645
+chuk_tool_processor/mcp/transport/stdio_transport.py,sha256=lFXL7p8ca4z_J0RBL8UCHrQ1UH7C2-LbC0tZhpya4V4,7763
+chuk_tool_processor/models/__init__.py,sha256=TC__rdVa0lQsmJHM_hbLDPRgToa_pQT_UxRcPZk6iVw,40
+chuk_tool_processor/models/execution_strategy.py,sha256=UVW35YIeMY2B3mpIKZD2rAkyOPayI6ckOOUALyf0YiQ,2115
+chuk_tool_processor/models/streaming_tool.py,sha256=0v2PSPTgZ5TS_PpVdohvVhh99fPwPQM_R_z4RU0mlLM,3541
+chuk_tool_processor/models/tool_call.py,sha256=t3QOQVzUaNRBea_n5fsrCgK4_ILiZlT8LvF7UwaZU84,1748
+chuk_tool_processor/models/tool_export_mixin.py,sha256=U9NJvn9fqH3pW50ozdDAHlA0fQSnjUt-lYhEoW_leZU,998
+chuk_tool_processor/models/tool_result.py,sha256=-8LdlaE9Ajfb1t-UyN9lW0XB2abQWALD7j8PZc-txhQ,5029
+chuk_tool_processor/models/validated_tool.py,sha256=LYc9-IBCiQmoMUotyByinRQQ-jfrC6g6tflMtSf9MUg,5908
+chuk_tool_processor/plugins/__init__.py,sha256=QO_ipvlsWG-rbaqGzj6-YtD7zi7Lx26hw-Cqha4MuWc,48
+chuk_tool_processor/plugins/discovery.py,sha256=kHRpOrcRnHiviKHCCdQN04cpSUqbifAZdSbU81Wc0fA,7112
+chuk_tool_processor/plugins/parsers/__init__.py,sha256=07waNfAGuytn-Dntx2IxjhgSkM9F40TBYNUXC8G4VVo,49
+chuk_tool_processor/plugins/parsers/base.py,sha256=r-15AZUmlGwWC3EQHRxiqPgivNv-mro6aTKqOwhuAtg,752
+chuk_tool_processor/plugins/parsers/function_call_tool.py,sha256=kaUTMhIpDP4jZa_CJZiGchIoszK3AboZM2BJOXzPJmg,3198
+chuk_tool_processor/plugins/parsers/json_tool.py,sha256=jljG7jR9070oHSTFqcrXbtFjYorw1cb4ZpwfrsLgFSE,1556
+chuk_tool_processor/plugins/parsers/openai_tool.py,sha256=O33DyXN0Llqv7AHygE9sVQkbSDVNIOcNqqa1CaZF6vo,2849
+chuk_tool_processor/plugins/parsers/xml_tool.py,sha256=V-JSWWy1ncXwX6-Of45zaLEGXryjKMTDEgTmEl6-XlY,3186
+chuk_tool_processor/registry/__init__.py,sha256=PBv5QyzHmUJEjgFQW1zgcUmppa5xUTjXTLVsYoVnDQI,2036
+chuk_tool_processor/registry/auto_register.py,sha256=wanaibx9CNsI1et0v2I25xzi5I_w8YaSlvW05ENEpIU,7252
+chuk_tool_processor/registry/decorators.py,sha256=qFK-z7wd53BY7rEbqqWMrWQXbP4UaTLVTCQRI2iUhHI,5035
+chuk_tool_processor/registry/interface.py,sha256=dqThCnHd2KCgX8j96j_hZxF2rigGClrI-hRc5n_nv2M,3467
+chuk_tool_processor/registry/metadata.py,sha256=lR9FO__lhPr-ax7PhFk8Se1bJdN_48rabiN7qegx4Ns,4582
+chuk_tool_processor/registry/provider.py,sha256=YUCGCFARNxnzV2Dm72Ur4DOrDs_ZYDtCzd6OBBzlis8,5162
+chuk_tool_processor/registry/tool_export.py,sha256=FEdMsfZ3uhiOjoDHqcnSwNehAN7Z5mgi4nI1UKu2hgs,7569
+chuk_tool_processor/registry/providers/__init__.py,sha256=eigwG_So11j7WbDGSWaKd3KwVen3Rap-aNQCSWA6T4k,2705
+chuk_tool_processor/registry/providers/memory.py,sha256=LlpPUU9E7S8Se6Q3VyKxLwpNm82SvmP8GLUmI8MkHxQ,5188
+chuk_tool_processor/utils/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+chuk_tool_processor/utils/validation.py,sha256=fiTSsHq7zx-kyd755GaFCvPCa-EVasSpg0A1liNHkxU,4138
+chuk_tool_processor-0.1.7.dist-info/METADATA,sha256=vqD7WCOAdv5CWGyQv0Hyp3oxWKGDkslRby84vVdCvLw,10165
+chuk_tool_processor-0.1.7.dist-info/WHEEL,sha256=DnLRTWE75wApRYVsjgc6wsVswC54sMSJhAEd4xhDpBk,91
+chuk_tool_processor-0.1.7.dist-info/top_level.txt,sha256=7lTsnuRx4cOW4U2sNJWNxl4ZTt_J1ndkjTbj3pHPY5M,20
+chuk_tool_processor-0.1.7.dist-info/RECORD,,

{chuk_tool_processor-0.1.6.dist-info → chuk_tool_processor-0.1.7.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (80.3.1)
+Generator: setuptools (80.4.0)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

chuk_tool_processor/plugins/parsers/json_tool_plugin.py

@@ -1,38 +0,0 @@
-# chuk_tool_processor/parsers/json_tool.py
-"""JSON *tool_calls* parser plugin (drop-in).
-
-Accepts raw‐string or dict input where the top-level object includes a
-``tool_calls`` array – an early OpenAI Chat Completions schema.
-"""
-from __future__ import annotations
-
-import json
-from typing import Any, List
-from pydantic import ValidationError
-
-# imports
-from .base import ParserPlugin
-from chuk_tool_processor.models.tool_call import ToolCall
-
-class JsonToolPlugin(ParserPlugin):
-    """Extracts ``tool_calls`` array from a JSON response."""
-
-    def try_parse(self, raw: str | Any) -> List[ToolCall]:
-        try:
-            data = json.loads(raw) if isinstance(raw, str) else raw
-        except json.JSONDecodeError:
-            return []
-
-        if not isinstance(data, dict):
-            return []
-
-        calls = data.get("tool_calls", [])
-        out: List[ToolCall] = []
-
-        for c in calls:
-            try:
-                out.append(ToolCall(**c))
-            except ValidationError:
-                continue
-        return out
-

chuk_tool_processor/plugins/parsers/openai_tool_plugin.py

@@ -1,76 +0,0 @@
-# chuk_tool_processor/parsers/openai_tool_plugin.py
-"""
-Parser for OpenAI Chat-Completions responses that contain a `tool_calls` array.
-"""
-
-from __future__ import annotations
-
-import json
-from typing import Any, List
-
-from pydantic import ValidationError
-
-from .base import ParserPlugin
-from chuk_tool_processor.models.tool_call import ToolCall
-
-
-class OpenAIToolPlugin(ParserPlugin):
-    """
-    Understands responses that look like:
-
-    {
-        "tool_calls": [
-            {
-                "id": "call_abc",
-                "type": "function",
-                "function": {
-                    "name": "weather",
-                    "arguments": "{\"location\": \"New York\"}"
-                }
-            },
-            …
-        ]
-    }
-    """
-
-    def try_parse(self, raw: str | Any) -> List[ToolCall]:
-        # ------------------------------------------------------------------ #
-        # Parse the incoming JSON (string or already-dict)
-        # ------------------------------------------------------------------ #
-        try:
-            data = json.loads(raw) if isinstance(raw, str) else raw
-        except (TypeError, json.JSONDecodeError):
-            return []
-
-        if not isinstance(data, dict) or "tool_calls" not in data:
-            return []
-
-        # ------------------------------------------------------------------ #
-        # Convert each entry into a ToolCall
-        # ------------------------------------------------------------------ #
-        calls: List[ToolCall] = []
-        for tc in data["tool_calls"]:
-            fn = tc.get("function", {})
-            name = fn.get("name")
-            args = fn.get("arguments", {})
-
-            if not isinstance(name, str) or not name:
-                continue
-
-            # arguments come back as a JSON-encoded string – decode if needed
-            if isinstance(args, str):
-                try:
-                    args = json.loads(args)
-                except json.JSONDecodeError:
-                    args = {}
-
-            if not isinstance(args, dict):
-                args = {}
-
-            try:
-                # `tool` must match the **registry key** (e.g. "weather")
-                calls.append(ToolCall(tool=name, arguments=args))
-            except ValidationError:
-                continue  # skip malformed entries
-
-        return calls