chuk-tool-processor 0.1.0__py3-none-any.whl

chuk_tool_processor-0.1.0.dist-info/METADATA

@@ -0,0 +1,293 @@
+Metadata-Version: 2.4
+Name: chuk-tool-processor
+Version: 0.1.0
+Summary: Add your description here
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: pydantic>=2.11.3
+
+# CHUK Tool Processor
+
+A robust framework for detecting, executing, and managing tool calls in LLM responses.
+
+## Overview
+
+The CHUK Tool Processor is a Python library designed to handle the execution of tools referenced in the output of Large Language Models (LLMs). It provides a flexible and extensible architecture for:
+
+1. **Parsing tool calls** from different formats (JSON, XML, function calls)
+2. **Executing tools** with proper isolation and error handling
+3. **Managing tool executions** with retry logic, caching, and rate limiting
+4. **Monitoring tool usage** with comprehensive logging
+
+## Features
+
+- **Multiple Parser Support**: Extract tool calls from JSON, XML, or OpenAI-style function call formats
+- **Flexible Execution Strategies**: Choose between in-process or subprocess execution for different isolation needs
+- **Namespace Support**: Organize tools in logical namespaces
+- **Concurrency Control**: Set limits on parallel tool executions
+- **Validation**: Type validation for tool arguments and results
+- **Caching**: Cache tool results to improve performance for repeated calls
+- **Rate Limiting**: Prevent overloading external services with configurable rate limits
+- **Retry Logic**: Automatically retry transient failures with exponential backoff
+- **Structured Logging**: Comprehensive logging system for debugging and monitoring
+- **Plugin Discovery**: Dynamically discover and load plugins from packages
+
+## 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 .
+
+# Or with uv
+uv pip install -e .
+```
+
+## Quick Start
+
+### Registering Tools
+
+```python
+from chuk_tool_processor.registry import register_tool
+
+@register_tool(name="calculator", namespace="math")
+class CalculatorTool:
+    def execute(self, operation: str, a: float, b: float):
+        if operation == "add":
+            return a + b
+        elif operation == "multiply":
+            return a * b
+        # ... other operations
+```
+
+### Processing Tool Calls
+
+```python
+import asyncio
+from chuk_tool_processor.core.processor import ToolProcessor
+
+async def main():
+    # Create a processor with default settings
+    processor = ToolProcessor()
+    
+    # Process text with potential tool calls
+    llm_response = """
+    To calculate that, I'll use the calculator tool.
+    
+    {
+      "function_call": {
+        "name": "calculator",
+        "arguments": {"operation": "multiply", "a": 123.45, "b": 67.89}
+      }
+    }
+    """
+    
+    results = await processor.process_text(llm_response)
+    
+    # Handle results
+    for result in results:
+        print(f"Tool: {result.tool}")
+        print(f"Result: {result.result}")
+        print(f"Error: {result.error}")
+        print(f"Duration: {(result.end_time - result.start_time).total_seconds()}s")
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+## Advanced Usage
+
+### Using Decorators for Tool Configuration
+
+```python
+from chuk_tool_processor.registry import register_tool
+from chuk_tool_processor.utils.validation import with_validation
+from chuk_tool_processor.execution.wrappers.retry import retryable
+from chuk_tool_processor.execution.wrappers.caching import cacheable
+from chuk_tool_processor.execution.wrappers.rate_limiting import rate_limited
+from typing import Dict, Any, Optional
+
+@register_tool(name="weather", namespace="data")
+@retryable(max_retries=3)
+@cacheable(ttl=3600)  # Cache for 1 hour
+@rate_limited(limit=100, period=60.0)  # 100 requests per minute
+@with_validation
+class WeatherTool:
+    def execute(self, location: str, units: str = "metric") -> Dict[str, Any]:
+        # Implementation that calls a weather API
+        return {
+            "temperature": 22.5,
+            "conditions": "Partly Cloudy",
+            "humidity": 65
+        }
+```
+
+### Using Validated Tool Base Class
+
+```python
+from chuk_tool_processor.utils.validation import ValidatedTool
+from chuk_tool_processor.registry import register_tool
+from pydantic import BaseModel
+from typing import Optional
+
+@register_tool(namespace="data")
+class WeatherTool(ValidatedTool):
+    class Arguments(BaseModel):
+        location: str
+        units: str = "metric"  # Default to metric
+    
+    class Result(BaseModel):
+        temperature: float
+        conditions: str
+        humidity: Optional[int] = None
+    
+    def _execute(self, location: str, units: str = "metric"):
+        # Implementation
+        return {
+            "temperature": 22.5,
+            "conditions": "Sunny",
+            "humidity": 65
+        }
+```
+
+### Custom Execution Strategy
+
+```python
+from chuk_tool_processor.registry.providers.memory import InMemoryToolRegistry
+from chuk_tool_processor.execution.tool_executor import ToolExecutor
+from chuk_tool_processor.execution.inprocess_strategy import InProcessStrategy
+
+# Create registry and register tools
+registry = InMemoryToolRegistry()
+registry.register_tool(MyTool(), name="my_tool")
+
+# Create executor with custom strategy
+executor = ToolExecutor(
+    registry,
+    strategy=InProcessStrategy(
+        registry,
+        default_timeout=5.0,
+        max_concurrency=10
+    )
+)
+
+# Execute tool calls
+results = await executor.execute([call1, call2])
+```
+
+### Custom Parser Plugins
+
+```python
+from chuk_tool_processor.models.tool_call import ToolCall
+from chuk_tool_processor.plugins.discovery import plugin_registry
+import re
+from typing import List
+
+# Create a custom parser for a bracket syntax
+class BracketToolParser:
+    """Parser for [tool:name arg1=val1 arg2="val2"] syntax"""
+    
+    def try_parse(self, raw: str) -> List[ToolCall]:
+        calls = []
+        # Regex to match [tool:name arg1=val1 arg2="val2"]
+        pattern = r"\[tool:([^\s\]]+)([^\]]*)\]"
+        matches = re.finditer(pattern, raw)
+        
+        for match in matches:
+            tool_name = match.group(1)
+            args_str = match.group(2).strip()
+            
+            # Parse arguments
+            args = {}
+            if args_str:
+                # Match key=value pairs, handling quoted values
+                args_pattern = r'([^\s=]+)=(?:([^\s"]+)|"([^"]*)")'
+                for arg_match in re.finditer(args_pattern, args_str):
+                    key = arg_match.group(1)
+                    # Either group 2 (unquoted) or group 3 (quoted)
+                    value = arg_match.group(2) if arg_match.group(2) else arg_match.group(3)
+                    args[key] = value
+            
+            calls.append(ToolCall(tool=tool_name, arguments=args))
+        
+        return calls
+
+# Register plugin manually
+plugin_registry.register_plugin("parser", "BracketToolParser", BracketToolParser())
+```
+
+### Structured Logging
+
+```python
+from chuk_tool_processor.utils.logging import get_logger, log_context_span
+
+logger = get_logger("my_module")
+
+# Create a context span for timing operations
+with log_context_span("operation_name", {"extra": "context"}):
+    logger.info("Starting operation")
+    # Do something
+    logger.info("Operation completed")
+```
+
+## Architecture
+
+The tool processor has several key components organized into a modular structure:
+
+1. **Registry**: Stores tool implementations and metadata
+   - `registry/interface.py`: Defines the registry interface
+   - `registry/providers/memory.py`: In-memory implementation
+   - `registry/providers/redis.py`: Redis-backed implementation
+
+2. **Models**: Core data structures
+   - `models/tool_call.py`: Represents a tool call from an LLM
+   - `models/tool_result.py`: Represents the result of a tool execution
+
+3. **Execution**: Tool execution strategies and wrappers
+   - `execution/tool_executor.py`: Main executor interface
+   - `execution/inprocess_strategy.py`: Same-process execution
+   - `execution/subprocess_strategy.py`: Isolated process execution
+   - `execution/wrappers/`: Enhanced executors (caching, retries, etc.)
+
+4. **Plugins**: Extensible plugin system
+   - `plugins/discovery.py`: Plugin discovery mechanism
+   - `plugins/parsers/`: Parser plugins for different formats
+
+5. **Utils**: Shared utilities
+   - `utils/logging.py`: Structured logging system
+   - `utils/validation.py`: Argument and result validation
+
+6. **Core**: Central components
+   - `core/processor.py`: Main processor for handling tool calls
+   - `core/exceptions.py`: Exception hierarchy
+
+## Examples
+
+The repository includes several example scripts:
+
+- `examples/tool_registry_example.py`: Demonstrates tool registration and usage
+- `examples/plugin_example.py`: Shows how to create and use custom plugins
+- `examples/tool_calling_example_usage.py`: Basic example demonstrating tool execution
+
+Run examples with:
+
+```bash
+# Registry example
+uv run examples/tool_registry_example.py
+
+# Plugin example
+uv run examples/plugin_example.py
+
+# Tool execution example
+uv run examples/tool_calling_example_usage.py
+
+# Enable debug logging
+LOGLEVEL=DEBUG uv run examples/tool_calling_example_usage.py
+```
+
+## License
+
+This project is licensed under the MIT License - see the LICENSE file for details.

chuk_tool_processor-0.1.0.dist-info/RECORD

@@ -0,0 +1,37 @@
+chuk_tool_processor/__init__.py,sha256=a4pDi8hta4hjhijLGcv3vlWL8iu3F9EynkmB3si7-hg,33
+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=wRVFLHMWikanFb8Zo8Hdp1XDnBmxzVYaNdWYnCyKI44,10164
+chuk_tool_processor/execution/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+chuk_tool_processor/execution/tool_executor.py,sha256=e1EHE-744uJuB1XeZZF_6VT25Yg1RCd8XI3v8uOrOSo,1794
+chuk_tool_processor/execution/strategies/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+chuk_tool_processor/execution/strategies/inprocess_strategy.py,sha256=i0wsauDOij0w5VP2chmSx5EOPXsuPcDLM7bQ8-CYLIM,7305
+chuk_tool_processor/execution/strategies/subprocess_strategy.py,sha256=Ev3brLfKF6ylH0Ck20ahML9_miFq9vu33DeER2ntf2k,3792
+chuk_tool_processor/execution/wrappers/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+chuk_tool_processor/execution/wrappers/caching.py,sha256=dA2OULPQ9xCZj-r3ev5LtsCDFDPgoz8tr70YCX5A4Wg,7714
+chuk_tool_processor/execution/wrappers/rate_limiting.py,sha256=pFqD1vLzOtJzsWzpEI7J786gOAbdFY0gVeiO7ElBXbA,4991
+chuk_tool_processor/execution/wrappers/retry.py,sha256=tRIuT5iNAYUY3r9y3shouWCxJZB5VONkBC9qPBaaVdc,6386
+chuk_tool_processor/models/__init__.py,sha256=TC__rdVa0lQsmJHM_hbLDPRgToa_pQT_UxRcPZk6iVw,40
+chuk_tool_processor/models/execution_strategy.py,sha256=s4yGAlVn_tqzpaqQPTTociOWhu6fxQWsd9BxoMhb4yU,511
+chuk_tool_processor/models/tool_call.py,sha256=RZOnx2YczkJN6ym2PLiI4CRzP2qU_5hpMtHxMcFOxY4,298
+chuk_tool_processor/models/tool_result.py,sha256=fqHuRC8bLek1PAwyhLOoKjRCLhpSm-mhDgLpsItjZ60,1532
+chuk_tool_processor/plugins/__init__.py,sha256=QO_ipvlsWG-rbaqGzj6-YtD7zi7Lx26hw-Cqha4MuWc,48
+chuk_tool_processor/plugins/discovery.py,sha256=K0sncdDmswH2tS_k-siJYLfEHzwMlU4iQVPX5kb6SZU,6370
+chuk_tool_processor/plugins/parsers/__init__.py,sha256=QO_ipvlsWG-rbaqGzj6-YtD7zi7Lx26hw-Cqha4MuWc,48
+chuk_tool_processor/plugins/parsers/function_call_tool.py,sha256=h7hbw25j-H961Pe7VVM0tSoPyP0IaprETmtDKSB2Teg,3945
+chuk_tool_processor/plugins/parsers/json_tool.py,sha256=20maA7jyEe6NFY7Efg_HqKhBkIQ5JhuAIKNfvjytEds,573
+chuk_tool_processor/plugins/parsers/xml_tool.py,sha256=QhywgQFEfticAf6LOfMTgzHN37lgZBqLFGXzNqGK5v8,1255
+chuk_tool_processor/registry/__init__.py,sha256=mLV6J2e7dcPva7S2gE6X3G1OElTXO0iTMzDC6-jL1SI,647
+chuk_tool_processor/registry/decorators.py,sha256=WecmzWK2RliMO0xmWEifj7xBqACoGfm2rz1hxcgtkrI,1346
+chuk_tool_processor/registry/interface.py,sha256=40KFbMKzjnwf6iki9aeWBx5c3Dq3Tadr78y-Ko-IYsM,2299
+chuk_tool_processor/registry/metadata.py,sha256=zoSv8QnncqMtvEo7nj_pGKKQohw6maBVDiInXBoNaxY,1744
+chuk_tool_processor/registry/provider.py,sha256=lsolfDqKelvxEkZR_qbHPe9iDZFHobnk5sm_LvSTdTU,1318
+chuk_tool_processor/registry/providers/__init__.py,sha256=_0dg4YhyfAV0TXuR_i4ewXPU8fY7odFd1RJWCmHIXmk,1326
+chuk_tool_processor/registry/providers/memory.py,sha256=Re5B0PPRETJOUVz6_gwMEJDBmYQulTtqkfnZacgxC8s,5552
+chuk_tool_processor/utils/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+chuk_tool_processor/utils/logging.py,sha256=cr3N3EMr7EqLj6SW-N-i4LJTegodUDtl3BxGvZbc26Q,7846
+chuk_tool_processor/utils/validation.py,sha256=kincqcVrYl2XUU3BHwqPAcQa6L-Cx0Oees4L8qwOK54,5994
+chuk_tool_processor-0.1.0.dist-info/METADATA,sha256=SRLHsrpXRZeFHvWYu3XWtWOgKaoXG6l1g9VhjSBVskM,9221
+chuk_tool_processor-0.1.0.dist-info/WHEEL,sha256=SmOxYU7pzNKBqASvQJ7DjX3XGUF92lrGhMb3R6_iiqI,91
+chuk_tool_processor-0.1.0.dist-info/top_level.txt,sha256=7lTsnuRx4cOW4U2sNJWNxl4ZTt_J1ndkjTbj3pHPY5M,20
+chuk_tool_processor-0.1.0.dist-info/RECORD,,

chuk_tool_processor-0.1.0.dist-info/WHEEL

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

chuk_tool_processor-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+chuk_tool_processor