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

chuk_tool_processor/registry/tool_export.py

@@ -0,0 +1,76 @@
+# chuk_tool_processor/registry/tool_export.py
+"""
+Helpers that expose all registered tools in various formats and
+translate an OpenAI `function.name` back to the matching tool.
+"""
+from __future__ import annotations
+
+from typing import Dict, List
+
+from .provider import ToolRegistryProvider
+
+# --------------------------------------------------------------------------- #
+# internal cache so tool-name lookup is O(1)
+# --------------------------------------------------------------------------- #
+_OPENAI_NAME_CACHE: dict[str, object] | None = None
+
+
+def _build_openai_name_cache() -> None:
+    """Populate the global reverse-lookup table once."""
+    global _OPENAI_NAME_CACHE
+    if _OPENAI_NAME_CACHE is not None:  # already built
+        return
+
+    _OPENAI_NAME_CACHE = {}
+    reg = ToolRegistryProvider.get_registry()
+
+    for ns, key in reg.list_tools():
+        tool = reg.get_tool(key, ns)
+
+        # ▸ registry key  -> tool
+        _OPENAI_NAME_CACHE[key] = tool
+
+        # ▸ class name    -> tool  (legacy)
+        _OPENAI_NAME_CACHE[tool.__class__.__name__] = tool
+
+        # ▸ OpenAI name   -> tool  (may differ from both above)
+        _OPENAI_NAME_CACHE[tool.to_openai()["function"]["name"]] = tool
+
+
+# --------------------------------------------------------------------------- #
+# public helpers
+# --------------------------------------------------------------------------- #
+def openai_functions() -> List[Dict]:
+    """
+    Return **all** registered tools in the exact schema the Chat-Completions
+    API expects in its ``tools=[ … ]`` parameter.
+
+    The ``function.name`` is always the *registry key* so that the round-trip
+    (export → model → parser) stays consistent even when the class name and
+    the registered key differ.
+    """
+    reg = ToolRegistryProvider.get_registry()
+    specs: list[dict] = []
+
+    for ns, key in reg.list_tools():
+        tool = reg.get_tool(key, ns)
+        spec = tool.to_openai()
+        spec["function"]["name"] = key  # ensure round-trip consistency
+        specs.append(spec)
+
+    # Ensure the cache is built the first time we export
+    _build_openai_name_cache()
+    return specs
+
+
+def tool_by_openai_name(name: str):
+    """
+    Map an OpenAI ``function.name`` back to the registered tool.
+
+    Raises ``KeyError`` if the name is unknown.
+    """
+    _build_openai_name_cache()
+    try:
+        return _OPENAI_NAME_CACHE[name]  # type: ignore[index]
+    except (KeyError, TypeError):
+        raise KeyError(f"No tool registered for OpenAI name {name!r}") from None

chuk_tool_processor/utils/validation.py

@@ -1,192 +1,121 @@
 # chuk_tool_processor/utils/validation.py
-from typing import Any, Dict, Optional, Type, get_type_hints, Union, List, Callable
-from pydantic import BaseModel, ValidationError, create_model
+"""
+Runtime helpers for validating tool inputs / outputs with Pydantic.
+
+Public API
+----------
+validate_arguments(tool_name, fn, args) -> dict
+validate_result(tool_name, fn, result)  -> Any
+@with_validation                        -> class decorator
+"""
+from __future__ import annotations
 import inspect
-from functools import wraps
+from functools import lru_cache, wraps
+from typing import Any, Callable, Dict, get_type_hints
+from pydantic import BaseModel, ValidationError, create_model, Extra
 
+# excpetion
 from chuk_tool_processor.core.exceptions import ToolValidationError
 
+__all__ = [
+    "validate_arguments",
+    "validate_result",
+    "with_validation",
+]
 
-def validate_arguments(tool_name: str, tool_func: Callable, args: Dict[str, Any]) -> Dict[str, Any]:
-    """
-    Validate tool arguments against function signature.
-    
-    Args:
-        tool_name: Name of the tool for error reporting.
-        tool_func: Tool function to validate against.
-        args: Arguments to validate.
-        
-    Returns:
-        Validated arguments dict.
-        
-    Raises:
-        ToolValidationError: If validation fails.
-    """
+# --------------------------------------------------------------------------- #
+# helpers – create & cache ad-hoc pydantic models
+# --------------------------------------------------------------------------- #
+
+
+@lru_cache(maxsize=256)
+def _arg_model(tool_name: str, fn: Callable) -> type[BaseModel]:
+    """Return (and memoise) a pydantic model derived from *fn*'s signature."""
+    hints = get_type_hints(fn)
+    hints.pop("return", None)
+
+    sig = inspect.signature(fn)
+    fields: Dict[str, tuple[Any, Any]] = {}
+    for name, hint in hints.items():
+        param = sig.parameters[name]
+        default = param.default if param.default is not inspect.Parameter.empty else ...
+        fields[name] = (hint, default)
+
+    return create_model(
+        f"{tool_name}Args",
+        __config__=type(
+            "Cfg",
+            (),
+            {"extra": Extra.forbid},  # disallow unknown keys
+        ),
+        **fields,
+    )
+
+
+@lru_cache(maxsize=256)
+def _result_model(tool_name: str, fn: Callable) -> type[BaseModel] | None:
+    """Return a pydantic model for the annotated return type (or None)."""
+    return_hint = get_type_hints(fn).get("return")
+    if return_hint is None or return_hint is type(None):  # noqa: E721
+        return None
+
+    return create_model(
+        f"{tool_name}Result",
+        result=(return_hint, ...),
+    )
+
+
+# --------------------------------------------------------------------------- #
+# public validation helpers
+# --------------------------------------------------------------------------- #
+
+
+def validate_arguments(tool_name: str, fn: Callable, args: Dict[str, Any]) -> Dict[str, Any]:
     try:
-        # Get type hints from function
-        type_hints = get_type_hints(tool_func)
-        
-        # Remove return type hint if present
-        if 'return' in type_hints:
-            type_hints.pop('return')
-        
-        # Create dynamic Pydantic model for validation
-        field_definitions = {
-            name: (type_hint, ...) for name, type_hint in type_hints.items()
-        }
-        
-        # Add optional fields based on default values
-        sig = inspect.signature(tool_func)
-        for param_name, param in sig.parameters.items():
-            if param.default is not inspect.Parameter.empty:
-                if param_name in field_definitions:
-                    field_type, _ = field_definitions[param_name]
-                    field_definitions[param_name] = (field_type, param.default)
-        
-        # Create model
-        model = create_model(f"{tool_name}Args", **field_definitions)
-        
-        # Validate args
-        validated = model(**args)
-        return validated.dict()
-    
-    except ValidationError as e:
-        raise ToolValidationError(tool_name, e.errors())
-    except Exception as e:
-        raise ToolValidationError(tool_name, {"general": str(e)})
-
-
-def validate_result(tool_name: str, tool_func: Callable, result: Any) -> Any:
-    """
-    Validate tool result against function return type.
-    
-    Args:
-        tool_name: Name of the tool for error reporting.
-        tool_func: Tool function to validate against.
-        result: Result to validate.
-        
-    Returns:
-        Validated result.
-        
-    Raises:
-        ToolValidationError: If validation fails.
-    """
+        model = _arg_model(tool_name, fn)
+        return model(**args).dict()
+    except ValidationError as exc:
+        raise ToolValidationError(tool_name, exc.errors()) from exc
+
+
+def validate_result(tool_name: str, fn: Callable, result: Any) -> Any:
+    model = _result_model(tool_name, fn)
+    if model is None:  # no annotation ⇒ no validation
+        return result
     try:
-        # Get return type hint
-        type_hints = get_type_hints(tool_func)
-        return_type = type_hints.get('return')
-        
-        if return_type is None:
-            # No return type to validate against
-            return result
-        
-        # Create dynamic Pydantic model for validation
-        model = create_model(
-            f"{tool_name}Result",
-            result=(return_type, ...)
-        )
-        
-        # Validate result
-        validated = model(result=result)
-        return validated.result
-    
-    except ValidationError as e:
-        raise ToolValidationError(tool_name, e.errors())
-    except Exception as e:
-        raise ToolValidationError(tool_name, {"general": str(e)})
+        return model(result=result).result
+    except ValidationError as exc:
+        raise ToolValidationError(tool_name, exc.errors()) from exc
+
+
+# --------------------------------------------------------------------------- #
+# decorator for classic “imperative” tools
+# --------------------------------------------------------------------------- #
 
 
 def with_validation(cls):
     """
-    Class decorator to add type validation to tool classes.
-    
-    Example:
-        @with_validation
-        class MyTool:
-            def execute(self, x: int, y: str) -> float:
-                return float(x) + float(y)
+    Wrap *execute* / *_execute* so that their arguments & return values
+    are type-checked each call.
+
+    ```
+    @with_validation
+    class MyTool:
+        def execute(self, x: int, y: int) -> int:
+            return x + y
+    ```
     """
-    original_execute = cls.execute
-    
-    @wraps(original_execute)
-    def execute_with_validation(self, **kwargs):
-        # Get tool name
-        tool_name = getattr(cls, "__name__", repr(cls))
-        
-        # Validate arguments
-        validated_args = validate_arguments(tool_name, original_execute, kwargs)
-        
-        # Execute the tool
-        result = original_execute(self, **validated_args)
-        
-        # Validate result
-        return validate_result(tool_name, original_execute, result)
-    
-    cls.execute = execute_with_validation
-    return cls
 
+    # Which method did the user provide?
+    fn_name = "_execute" if hasattr(cls, "_execute") else "execute"
+    original = getattr(cls, fn_name)
 
-class ValidatedTool(BaseModel):
-    """
-    Base class for tools with built-in validation.
-    
-    Example:
-        class AddTool(ValidatedTool):
-            class Arguments(BaseModel):
-                x: int
-                y: int
-                
-            class Result(BaseModel):
-                sum: int
-                
-            def execute(self, x: int, y: int) -> Result:
-                return self.Result(sum=x + y)
-    """
-    class Arguments(BaseModel):
-        """Base arguments model to be overridden by subclasses."""
-        pass
-    
-    class Result(BaseModel):
-        """Base result model to be overridden by subclasses."""
-        pass
-    
-    def execute(self, **kwargs) -> Any:
-        """
-        Execute the tool with validated arguments.
-        
-        Args:
-            **kwargs: Arguments to validate against Arguments model.
-            
-        Returns:
-            Validated result according to Result model.
-            
-        Raises:
-            ToolValidationError: If validation fails.
-        """
-        try:
-            # Validate arguments
-            validated_args = self.Arguments(**kwargs)
-            
-            # Execute implementation
-            result = self._execute(**validated_args.dict())
-            
-            # Validate result if it's not already a Result instance
-            if not isinstance(result, self.Result):
-                result = self.Result(**result if isinstance(result, dict) else {"value": result})
-                
-            return result
-            
-        except ValidationError as e:
-            raise ToolValidationError(self.__class__.__name__, e.errors())
-    
-    def _execute(self, **kwargs) -> Any:
-        """
-        Implementation method to be overridden by subclasses.
-        
-        Args:
-            **kwargs: Validated arguments.
-            
-        Returns:
-            Result that will be validated against Result model.
-        """
-        raise NotImplementedError("Subclasses must implement _execute")
+    @wraps(original)
+    def _validated(self, **kwargs):
+        name = cls.__name__
+        kwargs = validate_arguments(name, original, kwargs)
+        res = original(self, **kwargs)
+        return validate_result(name, original, res)
+
+    setattr(cls, fn_name, _validated)
+    return cls

{chuk_tool_processor-0.1.0.dist-info → chuk_tool_processor-0.1.1.dist-info}/METADATA

@@ -1,10 +1,13 @@
 Metadata-Version: 2.4
 Name: chuk-tool-processor
-Version: 0.1.0
+Version: 0.1.1
 Summary: Add your description here
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
+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
 
@@ -222,7 +225,7 @@ plugin_registry.register_plugin("parser", "BracketToolParser", BracketToolParser
 ### Structured Logging
 
 ```python
-from chuk_tool_processor.utils.logging import get_logger, log_context_span
+from chuk_tool_processor.logging import get_logger, log_context_span
 
 logger = get_logger("my_module")
 

chuk_tool_processor-0.1.1.dist-info/RECORD

@@ -0,0 +1,47 @@
+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=RbHNFYpzn7hhjBXwqPOdRvTGWky4z8tT7k672nwRE0s,10158
+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=zybG8PzIf7VbDfQfMg2TJ67-zxbArt1eEjczRLzZfrQ,5957
+chuk_tool_processor/execution/strategies/subprocess_strategy.py,sha256=Er8z7x94E7HmhFr9LtOvSBifL1eJ4l-12XampzkjBjU,3786
+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/logging/__init__.py,sha256=YslBwMTCgxboYwnT4w5qX0_BnA0MR62eI8NH9le9G38,1057
+chuk_tool_processor/logging/context.py,sha256=hQFWGeraHX3DM28JDSiIuhQqep6TBfo1uaLlRRlGMVU,1521
+chuk_tool_processor/logging/formatter.py,sha256=4pO-fLULkD3JPLjZOSiOZPGsjV3c4Ztr5ySda1RAvi4,1754
+chuk_tool_processor/logging/helpers.py,sha256=Fk32BuecWZdyrmv8U0lh4W0AdNx4-gKcCaWBdId_rlI,3569
+chuk_tool_processor/logging/metrics.py,sha256=ti_owuslT-x9cjcbP-_j7jivrlyY-Vb41mVhU-6W-2M,1537
+chuk_tool_processor/models/__init__.py,sha256=TC__rdVa0lQsmJHM_hbLDPRgToa_pQT_UxRcPZk6iVw,40
+chuk_tool_processor/models/execution_strategy.py,sha256=ZPHysmKNHqJmahTtUXAbt1ke09vxy7EhZcsrwTdla8o,508
+chuk_tool_processor/models/tool_call.py,sha256=RZOnx2YczkJN6ym2PLiI4CRzP2qU_5hpMtHxMcFOxY4,298
+chuk_tool_processor/models/tool_export_mixin.py,sha256=U9NJvn9fqH3pW50ozdDAHlA0fQSnjUt-lYhEoW_leZU,998
+chuk_tool_processor/models/tool_result.py,sha256=fqHuRC8bLek1PAwyhLOoKjRCLhpSm-mhDgLpsItjZ60,1532
+chuk_tool_processor/models/validated_tool.py,sha256=REXLfKYNpdvm7hH4tYUZq1-TxiD0784iZUffrucGN_o,5714
+chuk_tool_processor/plugins/__init__.py,sha256=QO_ipvlsWG-rbaqGzj6-YtD7zi7Lx26hw-Cqha4MuWc,48
+chuk_tool_processor/plugins/discovery.py,sha256=pyUQk18c9mNoruoa2eY8T-FhkpomPllnWiyRDVCaJNM,5299
+chuk_tool_processor/plugins/parsers/__init__.py,sha256=07waNfAGuytn-Dntx2IxjhgSkM9F40TBYNUXC8G4VVo,49
+chuk_tool_processor/plugins/parsers/base.py,sha256=VwN1sT03L5Ar37koDgT9El0MRdIJCwwNJMbN76GKB5E,564
+chuk_tool_processor/plugins/parsers/function_call_tool_plugin.py,sha256=rZt-fJ_dhVkRFR1OU86yZNq1R9AFvAiwjk6I3Hktc-A,2706
+chuk_tool_processor/plugins/parsers/json_tool_plugin.py,sha256=wllYEqCzgxmCYdcugelWYFNHTjMYgDsghI-cbh8Qudk,1050
+chuk_tool_processor/plugins/parsers/openai_tool_plugin.py,sha256=IyL6ZE03disNqkRYiyQZqJRV-vk99mLCZoKeLTwNYjQ,2347
+chuk_tool_processor/plugins/parsers/xml_tool.py,sha256=rWdm25TwuT8S7l7GrYOvd-gFiVr6oss5ncjhQZGQxqA,1304
+chuk_tool_processor/registry/__init__.py,sha256=kjNEM5dM7kEucfDjvgnww-QLrBrCzuDAuj9OBTizm5I,782
+chuk_tool_processor/registry/auto_register.py,sha256=moHYkfWsSUOs7uu7MbZj2v-ujUHPbGD4nXsQZ5Dk1hM,5119
+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=EG1K28nfRddq18UDrymKse_bMt3PAhLcQ3TRaG89Tq8,3869
+chuk_tool_processor/registry/tool_export.py,sha256=msGOszF9NtJEb4u0XhA0tz6EwkL3Uv_R7QAz0p2eJM8,2543
+chuk_tool_processor/registry/providers/__init__.py,sha256=_0dg4YhyfAV0TXuR_i4ewXPU8fY7odFd1RJWCmHIXmk,1326
+chuk_tool_processor/registry/providers/memory.py,sha256=29aI5uvykjDmn9ymIukEdUtmTC9SXOAsDu9hw36XF44,4474
+chuk_tool_processor/utils/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+chuk_tool_processor/utils/validation.py,sha256=7ezn_o-3IHDrzOD3j6ttsAn2s3zS-jIjeBTuqicrs6A,3775
+chuk_tool_processor-0.1.1.dist-info/METADATA,sha256=roW8za1Cw1IKO3ZkzzHYVFzAeFZM2-b8CWKCCwa6Ag0,9300
+chuk_tool_processor-0.1.1.dist-info/WHEEL,sha256=SmOxYU7pzNKBqASvQJ7DjX3XGUF92lrGhMb3R6_iiqI,91
+chuk_tool_processor-0.1.1.dist-info/top_level.txt,sha256=7lTsnuRx4cOW4U2sNJWNxl4ZTt_J1ndkjTbj3pHPY5M,20
+chuk_tool_processor-0.1.1.dist-info/RECORD,,

chuk_tool_processor/plugins/parsers/function_call_tool.py

@@ -1,105 +0,0 @@
-# chuk_tool_processor/plugins/function_call_tool.py
-import json
-import re
-from typing import List, Any, Dict
-from pydantic import ValidationError
-
-# imports
-from chuk_tool_processor.models.tool_call import ToolCall
-from chuk_tool_processor.utils.logging import get_logger
-
-# logger
-logger = get_logger("chuk_tool_processor.plugins.function_call_tool")
-
-class FunctionCallPlugin:
-    """
-    Parse OpenAI-style `function_call` payloads embedded in the LLM response.
-    
-    Supports two formats:
-    1. JSON object with function_call field:
-      {
-        "function_call": {
-          "name": "my_tool",
-          "arguments": '{"x":1,"y":"two"}'
-        }
-      }
-      
-    2. JSON object with function_call field and already parsed arguments:
-      {
-        "function_call": {
-          "name": "my_tool",
-          "arguments": {"x":1, "y":"two"}
-        }
-      }
-    """
-    def try_parse(self, raw: str) -> List[ToolCall]:
-        calls: List[ToolCall] = []
-        
-        # First, try to parse as a complete JSON object
-        try:
-            payload = json.loads(raw)
-            
-            # Check if this is a function call payload
-            if isinstance(payload, dict) and "function_call" in payload:
-                fc = payload.get("function_call")
-                if not isinstance(fc, dict):
-                    return []
-                
-                name = fc.get("name")
-                args = fc.get("arguments", {})
-                
-                # Arguments sometimes come back as a JSON-encoded string
-                if isinstance(args, str):
-                    try:
-                        args = json.loads(args)
-                    except json.JSONDecodeError:
-                        # Leave as empty dict if malformed but still create the call
-                        args = {}
-                
-                # Only proceed if we have a valid name
-                if not isinstance(name, str) or not name:
-                    return []
-                
-                try:
-                    call = ToolCall(tool=name, arguments=args if isinstance(args, Dict) else {})
-                    calls.append(call)
-                    logger.debug(f"Found function call to {name}")
-                except ValidationError:
-                    # invalid tool name or args shape
-                    logger.warning(f"Invalid function call: {name}")
-            
-            # Look for nested function calls
-            if not calls:
-                # Try to find function calls in nested objects
-                json_str = json.dumps(payload)
-                json_pattern = r'\{(?:[^{}]|(?:\{[^{}]*\}))*\}'
-                matches = re.finditer(json_pattern, json_str)
-                
-                for match in matches:
-                    # Skip if it's the complete string we already parsed
-                    json_substr = match.group(0)
-                    if json_substr == json_str:
-                        continue
-                        
-                    try:
-                        nested_payload = json.loads(json_substr)
-                        if isinstance(nested_payload, dict) and "function_call" in nested_payload:
-                            nested_calls = self.try_parse(json_substr)
-                            calls.extend(nested_calls)
-                    except json.JSONDecodeError:
-                        continue
-                
-        except json.JSONDecodeError:
-            # If it's not valid JSON, try to extract function calls using regex
-            json_pattern = r'\{(?:[^{}]|(?:\{[^{}]*\}))*\}'
-            matches = re.finditer(json_pattern, raw)
-            
-            for match in matches:
-                json_str = match.group(0)
-                try:
-                    nested_calls = self.try_parse(json_str)
-                    calls.extend(nested_calls)
-                except Exception:
-                    continue
-        
-        return calls

chuk_tool_processor/plugins/parsers/json_tool.py

@@ -1,17 +0,0 @@
-# chuk_tool_processor/plugins/json_tool.py
-import json
-from typing import List
-from pydantic import ValidationError
-
-# tool processor
-from chuk_tool_processor.models.tool_call import ToolCall
-
-class JsonToolPlugin:
-    """Parse JSON-encoded `tool_calls` field."""
-    def try_parse(self, raw: str) -> List[ToolCall]:
-        try:
-            data = json.loads(raw)
-            calls = data.get('tool_calls', []) if isinstance(data, dict) else []
-            return [ToolCall(**c) for c in calls]
-        except (json.JSONDecodeError, ValidationError):
-            return []