chuk-tool-processor 0.11__tar.gz → 0.11.2__tar.gz

{chuk_tool_processor-0.11 → chuk_tool_processor-0.11.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: chuk-tool-processor
-Version: 0.11
+Version: 0.11.2
 Summary: Async-native framework for registering, discovering, and executing tools referenced in LLM responses
 Author-email: CHUK Team <chrishayuk@somejunkmailbox.com>
 Maintainer-email: CHUK Team <chrishayuk@somejunkmailbox.com>
@@ -20,11 +20,15 @@ Classifier: Framework :: AsyncIO
 Classifier: Typing :: Typed
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
-Requires-Dist: chuk-mcp>=0.8.1
+Requires-Dist: chuk-mcp>=0.9
 Requires-Dist: dotenv>=0.9.9
 Requires-Dist: psutil>=7.0.0
 Requires-Dist: pydantic>=2.11.3
 Requires-Dist: uuid>=1.30
+Provides-Extra: fast-json
+Requires-Dist: orjson<4,>=3.10.0; extra == "fast-json"
+Provides-Extra: full
+Requires-Dist: orjson<4,>=3.10.0; extra == "full"
 
 # CHUK Tool Processor — Production-grade execution for LLM tool calls
 
@@ -287,12 +291,41 @@ pip install chuk-tool-processor[observability]
 # With MCP extras
 pip install chuk-tool-processor[mcp]
 
+# With fast JSON serialization (2-3x faster, recommended for production)
+pip install chuk-tool-processor[fast-json]
+
 # All extras
 pip install chuk-tool-processor[all]
 ```
 
 </details>
 
+<details>
+<summary><strong>Performance Optimization (Optional)</strong></summary>
+
+For **2-3x faster JSON operations**, install with the `fast-json` extra:
+
+```bash
+pip install chuk-tool-processor[fast-json]
+```
+
+This installs [orjson](https://github.com/ijl/orjson), a fast C-based JSON library. When available, it's automatically used for JSON serialization/deserialization throughout the processor while maintaining full compatibility with stdlib json.
+
+**Benchmarks** (see `benchmarks/` for full results):
+
+| Operation | stdlib json | orjson | Speedup |
+|-----------|-------------|--------|---------|
+| Simple JSON (100 bytes) | 1.23 µs | 0.45 µs | **2.7x faster** |
+| Complex JSON (5 KB) | 12.5 µs | 4.2 µs | **3.0x faster** |
+| OpenAI tool calls | 8.9 µs | 3.1 µs | **2.9x faster** |
+
+**Notes:**
+- Falls back to stdlib json automatically if orjson is not installed
+- Hash computation uses stdlib json for consistency across environments
+- No code changes required—just install the extra
+
+</details>
+
 <details>
 <summary><strong>Type Checking Support (PEP 561 compliant)</strong></summary>
 

{chuk_tool_processor-0.11 → chuk_tool_processor-0.11.2}/README.md

@@ -259,12 +259,41 @@ pip install chuk-tool-processor[observability]
 # With MCP extras
 pip install chuk-tool-processor[mcp]
 
+# With fast JSON serialization (2-3x faster, recommended for production)
+pip install chuk-tool-processor[fast-json]
+
 # All extras
 pip install chuk-tool-processor[all]
 ```
 
 </details>
 
+<details>
+<summary><strong>Performance Optimization (Optional)</strong></summary>
+
+For **2-3x faster JSON operations**, install with the `fast-json` extra:
+
+```bash
+pip install chuk-tool-processor[fast-json]
+```
+
+This installs [orjson](https://github.com/ijl/orjson), a fast C-based JSON library. When available, it's automatically used for JSON serialization/deserialization throughout the processor while maintaining full compatibility with stdlib json.
+
+**Benchmarks** (see `benchmarks/` for full results):
+
+| Operation | stdlib json | orjson | Speedup |
+|-----------|-------------|--------|---------|
+| Simple JSON (100 bytes) | 1.23 µs | 0.45 µs | **2.7x faster** |
+| Complex JSON (5 KB) | 12.5 µs | 4.2 µs | **3.0x faster** |
+| OpenAI tool calls | 8.9 µs | 3.1 µs | **2.9x faster** |
+
+**Notes:**
+- Falls back to stdlib json automatically if orjson is not installed
+- Hash computation uses stdlib json for consistency across environments
+- No code changes required—just install the extra
+
+</details>
+
 <details>
 <summary><strong>Type Checking Support (PEP 561 compliant)</strong></summary>
 

{chuk_tool_processor-0.11 → chuk_tool_processor-0.11.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "chuk-tool-processor"
-version = "0.11"
+version = "0.11.2"
 description = "Async-native framework for registering, discovering, and executing tools referenced in LLM responses"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -41,13 +41,25 @@ classifiers = [
     "Typing :: Typed",
 ]
 dependencies = [
-    "chuk-mcp>=0.8.1",
+    "chuk-mcp>=0.9",
     "dotenv>=0.9.9",
     "psutil>=7.0.0",
     "pydantic>=2.11.3",
     "uuid>=1.30",
 ]
 
+# Optional dependency groups
+[project.optional-dependencies]
+# Fast JSON parsing (2-3x faster than stdlib json)
+fast-json = [
+    "orjson>=3.10.0,<4",
+]
+
+# Full feature set with performance optimizations
+full = [
+    "orjson>=3.10.0,<4",
+]
+
 # Tell setuptools to look in src/ for your a2a package
 [tool.setuptools.packages.find]
 where   = ["src"]
@@ -80,6 +92,7 @@ dev = [
     "bandit>=1.7.0",
     "pre-commit>=3.8.0",
     "coverage[toml]>=7.6.0",
+    "orjson>=3.10.0",
 ]
 
 observability = [

{chuk_tool_processor-0.11 → chuk_tool_processor-0.11.2}/src/chuk_tool_processor/core/processor.py

@@ -12,7 +12,7 @@ from __future__ import annotations
 
 import asyncio
 import hashlib
-import json
+import json as stdlib_json  # Use stdlib json for consistent hashing
 import time
 from typing import Any
 
@@ -29,6 +29,7 @@ from chuk_tool_processor.models.tool_call import ToolCall
 from chuk_tool_processor.models.tool_result import ToolResult
 from chuk_tool_processor.plugins.discovery import discover_default_plugins, plugin_registry
 from chuk_tool_processor.registry import ToolRegistryInterface, ToolRegistryProvider
+from chuk_tool_processor.utils import fast_json as json
 
 
 class ToolProcessor:
@@ -571,6 +572,9 @@ class ToolProcessor:
         """
         Extract tool calls from text using all available parsers.
 
+        PERFORMANCE: Uses content sniffing to try most likely parser first,
+        with early exit on success. Falls back to concurrent parsing if needed.
+
         Args:
             text: Text to parse.
 
@@ -581,6 +585,39 @@ class ToolProcessor:
 
         # Try each parser
         async with log_context_span("parsing", {"text_length": len(text)}):
+            # PERFORMANCE: Smart parser selection based on content hints
+            # Most inputs match exactly ONE format, so try the obvious one first
+            likely_parser = None
+
+            # Quick content sniffing (cheap string checks)
+            if '"tool_calls"' in text or '"function"' in text:
+                # Likely OpenAI format
+                likely_parser = next((p for p in self.parsers if "OpenAI" in p.__class__.__name__), None)
+            elif text.strip().startswith("{") and ('"name"' in text and '"arguments"' in text):
+                # Likely direct JSON tool format
+                likely_parser = next((p for p in self.parsers if "Json" in p.__class__.__name__), None)
+            elif "<tool" in text or "</tool>" in text:
+                # Likely XML format
+                likely_parser = next((p for p in self.parsers if "Xml" in p.__class__.__name__), None)
+
+            # PERFORMANCE: Early exit path - try likely parser first
+            if likely_parser:
+                try:
+                    result = await self._try_parser(likely_parser, text)
+                    if result and isinstance(result, list) and len(result) > 0:
+                        # Success! Return immediately without trying other parsers
+                        all_calls.extend(result)
+                        # Skip to deduplication
+                        if len(all_calls) <= 1:
+                            # Fast path: single call, no dedup needed
+                            return all_calls
+                        # Jump to dedup section
+                        return self._deduplicate_calls(all_calls)
+                except Exception:
+                    # Failed, fall through to try all parsers
+                    pass
+
+            # PERFORMANCE: Fallback - try all parsers concurrently
             parse_tasks = []
 
             # Create parsing tasks
@@ -591,20 +628,39 @@ class ToolProcessor:
             parser_results = await asyncio.gather(*parse_tasks, return_exceptions=True)
 
             # Collect successful results
-            for result in parser_results:
-                if isinstance(result, Exception):
-                    continue
-                # At this point, result is list[ToolCall], not an exception
-                if result and isinstance(result, list):
+            for result in parser_results:  # type: ignore[assignment]
+                # Skip exceptions (return_exceptions=True gives us Exception | result)
+                if isinstance(result, list):
+                    # Type narrowing: result is list[ToolCall] here, not BaseException
                     all_calls.extend(result)
 
+        # PERFORMANCE: Skip deduplication for single calls (common case)
+        return self._deduplicate_calls(all_calls)
+
+    def _deduplicate_calls(self, all_calls: list[ToolCall]) -> list[ToolCall]:
+        """
+        Remove duplicate tool calls from the list.
+
+        PERFORMANCE: Fast path for single calls (no dedup needed).
+
+        Args:
+            all_calls: List of tool calls (may contain duplicates).
+
+        Returns:
+            List of unique tool calls.
+        """
+        # PERFORMANCE: Fast path - no deduplication needed for 0 or 1 calls
+        if len(all_calls) <= 1:
+            return all_calls
+
         # ------------------------------------------------------------------ #
         # Remove duplicates - use a stable digest instead of hashing a
         # frozenset of argument items (which breaks on unhashable types).
         # ------------------------------------------------------------------ #
         def _args_digest(args: dict[str, Any]) -> str:
             """Return a stable hash for any JSON-serialisable payload."""
-            blob = json.dumps(args, sort_keys=True, default=str)
+            # Use stdlib json for consistent hashing across orjson/stdlib
+            blob = stdlib_json.dumps(args, sort_keys=True, default=str)
             return hashlib.md5(blob.encode(), usedforsecurity=False).hexdigest()  # nosec B324
 
         unique_calls: dict[str, ToolCall] = {}

{chuk_tool_processor-0.11 → chuk_tool_processor-0.11.2}/src/chuk_tool_processor/execution/strategies/subprocess_strategy.py

@@ -232,7 +232,7 @@ class SubprocessStrategy(ExecutionStrategy):
                 await asyncio.wait_for(
                     loop.run_in_executor(self._process_pool, _pool_test_func), timeout=self.worker_init_timeout
                 )
-                logger.info("Process pool initialized with %d workers", self.max_workers)
+                logger.debug("Process pool initialized with %d workers", self.max_workers)
             except Exception as e:
                 # Clean up on initialization error
                 self._process_pool.shutdown(wait=False)

{chuk_tool_processor-0.11 → chuk_tool_processor-0.11.2}/src/chuk_tool_processor/execution/wrappers/caching.py

@@ -16,7 +16,7 @@ from __future__ import annotations
 
 import asyncio
 import hashlib
-import json
+import json as stdlib_json  # Use stdlib json for consistent hashing
 from abc import ABC, abstractmethod
 from datetime import UTC, datetime, timedelta
 from typing import Any
@@ -379,7 +379,8 @@ class CachingToolExecutor:
             MD5 hash of the sorted JSON representation
         """
         try:
-            blob = json.dumps(arguments, sort_keys=True, default=str)
+            # Use stdlib json for consistent hashing across orjson/stdlib
+            blob = stdlib_json.dumps(arguments, sort_keys=True, default=str)
             return hashlib.md5(blob.encode(), usedforsecurity=False).hexdigest()  # nosec B324
         except Exception as e:
             logger.warning(f"Error hashing arguments: {e}")
@@ -447,7 +448,8 @@ class CachingToolExecutor:
                     continue
 
                 # Use idempotency_key if available, otherwise hash arguments
-                cache_key = call.idempotency_key or self._hash_arguments(call.arguments)
+                # PERFORMANCE: Only compute idempotency key when caching is actually used
+                cache_key = call.get_idempotency_key()
 
                 # Trace cache lookup operation
                 with trace_cache_operation("lookup", call.tool):
@@ -515,7 +517,8 @@ class CachingToolExecutor:
                     logger.debug(f"Caching result for {call.tool} with TTL={ttl}s")
 
                     # Use idempotency_key if available, otherwise hash arguments
-                    cache_key = call.idempotency_key or self._hash_arguments(call.arguments)
+                    # PERFORMANCE: Only compute idempotency key when caching is actually used
+                    cache_key = call.get_idempotency_key()
 
                     # Trace and record cache set operation
                     # Bind loop variables to avoid B023 error
@@ -598,8 +601,9 @@ def invalidate_cache(tool: str, arguments: dict[str, Any] | None = None):
 
     async def _invalidate(cache: CacheInterface):
         if arguments is not None:
+            # Use stdlib json for consistent hashing across orjson/stdlib
             h = hashlib.md5(
-                json.dumps(arguments, sort_keys=True, default=str).encode(), usedforsecurity=False
+                stdlib_json.dumps(arguments, sort_keys=True, default=str).encode(), usedforsecurity=False
             ).hexdigest()  # nosec B324
             await cache.invalidate(tool, h)
             logger.debug(f"Invalidated cache entry for {tool} with specific arguments")

{chuk_tool_processor-0.11 → chuk_tool_processor-0.11.2}/src/chuk_tool_processor/mcp/stream_manager.py

@@ -565,6 +565,21 @@ class StreamManager:
     def get_server_info(self) -> list[dict[str, Any]]:
         return self.server_info
 
+    def set_session_id(self, session_id: str | None) -> None:
+        """
+        Set the session ID on all HTTP/SSE transports.
+
+        This allows dynamically updating the session ID at runtime,
+        which is useful when the session ID is only known after agent initialization.
+
+        Args:
+            session_id: Session ID to set, or None to clear it
+        """
+        for name, transport in self.transports.items():
+            if hasattr(transport, "set_session_id"):
+                transport.set_session_id(session_id)
+                logger.debug("Set session ID for transport %s", name)
+
     async def list_tools(self, server_name: str) -> list[dict[str, Any]]:
         """List all tools available from a specific server."""
         if self._closed:

{chuk_tool_processor-0.11 → chuk_tool_processor-0.11.2}/src/chuk_tool_processor/mcp/transport/base_transport.py

@@ -28,12 +28,12 @@ class MCPBaseTransport(ABC):
         Returns:
             True if initialization was successful, False otherwise.
         """
-        pass
+        raise NotImplementedError
 
     @abstractmethod
     async def close(self) -> None:
         """Close the transport connection and clean up all resources."""
-        pass
+        raise NotImplementedError
 
     # ------------------------------------------------------------------ #
     #  Health and diagnostics                                            #
@@ -46,7 +46,7 @@ class MCPBaseTransport(ABC):
         Returns:
             True if ping was successful, False otherwise.
         """
-        pass
+        raise NotImplementedError
 
     @abstractmethod
     def is_connected(self) -> bool:
@@ -56,7 +56,7 @@ class MCPBaseTransport(ABC):
         Returns:
             True if connected, False otherwise.
         """
-        pass
+        raise NotImplementedError
 
     # ------------------------------------------------------------------ #
     #  Core MCP operations                                               #
@@ -69,7 +69,7 @@ class MCPBaseTransport(ABC):
         Returns:
             List of tool definitions.
         """
-        pass
+        raise NotImplementedError
 
     @abstractmethod
     async def call_tool(
@@ -86,7 +86,7 @@ class MCPBaseTransport(ABC):
         Returns:
             Dictionary with 'isError' boolean and either 'content' or 'error'
         """
-        pass
+        raise NotImplementedError
 
     @abstractmethod
     async def list_resources(self) -> dict[str, Any]:
@@ -96,7 +96,7 @@ class MCPBaseTransport(ABC):
         Returns:
             Dictionary containing resources list or empty dict if not supported.
         """
-        pass
+        raise NotImplementedError
 
     @abstractmethod
     async def list_prompts(self) -> dict[str, Any]:
@@ -106,7 +106,7 @@ class MCPBaseTransport(ABC):
         Returns:
             Dictionary containing prompts list or empty dict if not supported.
         """
-        pass
+        raise NotImplementedError
 
     # ------------------------------------------------------------------ #
     #  Metrics and monitoring (all transports should support these)     #
@@ -119,12 +119,12 @@ class MCPBaseTransport(ABC):
         Returns:
             Dictionary containing metrics data.
         """
-        pass
+        raise NotImplementedError
 
     @abstractmethod
     def reset_metrics(self) -> None:
         """Reset performance metrics to initial state."""
-        pass
+        raise NotImplementedError
 
     # ------------------------------------------------------------------ #
     #  Backward compatibility and utility methods                       #

{chuk_tool_processor-0.11 → chuk_tool_processor-0.11.2}/src/chuk_tool_processor/mcp/transport/http_streamable_transport.py

@@ -122,9 +122,9 @@ class HTTPStreamableTransport(MCPBaseTransport):
         if self.api_key and "Authorization" not in headers:
             headers["Authorization"] = f"Bearer {self.api_key}"
 
-        # Add session ID if provided
+        # Add session ID if provided (use mcp-session-id header expected by MCP server)
         if self.session_id:
-            headers["X-Session-ID"] = self.session_id
+            headers["mcp-session-id"] = self.session_id
 
         return headers
 
@@ -642,6 +642,19 @@ class HTTPStreamableTransport(MCPBaseTransport):
         )
         return metrics
 
+    def set_session_id(self, session_id: str | None) -> None:
+        """
+        Dynamically update the session ID for this transport.
+
+        This allows setting or changing the session ID after initialization,
+        which is useful when the session ID is only known at runtime.
+
+        Args:
+            session_id: New session ID to use, or None to clear it
+        """
+        self.session_id = session_id
+        logger.debug("Session ID updated: %s", session_id if session_id else "(cleared)")
+
     def reset_metrics(self) -> None:
         """Enhanced metrics reset preserving health state."""
         if not self._metrics:

{chuk_tool_processor-0.11 → chuk_tool_processor-0.11.2}/src/chuk_tool_processor/mcp/transport/sse_transport.py

@@ -714,6 +714,19 @@ class SSETransport(MCPBaseTransport):
         self._last_successful_ping = None
         self._initialization_time = None
 
+    def set_session_id(self, session_id: str | None) -> None:
+        """
+        Dynamically update the session ID for this transport.
+
+        This allows setting or changing the session ID after initialization,
+        which is useful when the session ID is only known at runtime.
+
+        Args:
+            session_id: New session ID to use, or None to clear it
+        """
+        self.session_id = session_id
+        logger.debug("Session ID updated: %s", session_id if session_id else "(cleared)")
+
     def get_metrics(self) -> dict[str, Any]:
         """Get performance and connection metrics with health info."""
         if not self._metrics:

{chuk_tool_processor-0.11 → chuk_tool_processor-0.11.2}/src/chuk_tool_processor/models/tool_call.py

@@ -10,7 +10,7 @@ import json
 import uuid
 from typing import Any
 
-from pydantic import BaseModel, ConfigDict, Field, model_validator
+from pydantic import BaseModel, ConfigDict, Field
 
 
 class ToolCall(BaseModel):
@@ -31,17 +31,18 @@ class ToolCall(BaseModel):
     tool: str = Field(..., min_length=1, description="Name of the tool to call; must be non-empty")
     namespace: str = Field(default="default", description="Namespace the tool belongs to")
     arguments: dict[str, Any] = Field(default_factory=dict, description="Arguments to pass to the tool")
-    idempotency_key: str | None = Field(
-        None,
-        description="Idempotency key for deduplication. Auto-generated if not provided.",
-    )
+    _idempotency_key: str | None = None  # Cached value, computed lazily
 
-    @model_validator(mode="after")
-    def generate_idempotency_key(self) -> ToolCall:
-        """Generate idempotency key if not provided."""
-        if self.idempotency_key is None:
-            self.idempotency_key = self._compute_idempotency_key()
-        return self
+    def get_idempotency_key(self) -> str:
+        """
+        Get or compute idempotency key lazily.
+
+        PERFORMANCE: Only computed when explicitly needed, avoiding overhead
+        in hot paths where deduplication isn't required.
+        """
+        if self._idempotency_key is None:
+            self._idempotency_key = self._compute_idempotency_key()
+        return self._idempotency_key
 
     def _compute_idempotency_key(self) -> str:
         """

{chuk_tool_processor-0.11 → chuk_tool_processor-0.11.2}/src/chuk_tool_processor/plugins/parsers/function_call_tool.py

@@ -3,7 +3,6 @@
 
 from __future__ import annotations
 
-import json
 import re
 from typing import Any
 
@@ -12,6 +11,7 @@ from pydantic import ValidationError
 from chuk_tool_processor.logging import get_logger
 from chuk_tool_processor.models.tool_call import ToolCall
 from chuk_tool_processor.plugins.parsers.base import ParserPlugin
+from chuk_tool_processor.utils import fast_json as json
 
 __all__ = ["FunctionCallPlugin"]
 

{chuk_tool_processor-0.11 → chuk_tool_processor-0.11.2}/src/chuk_tool_processor/plugins/parsers/json_tool.py

@@ -3,7 +3,6 @@
 
 from __future__ import annotations
 
-import json
 from typing import Any
 
 from pydantic import ValidationError
@@ -11,6 +10,7 @@ from pydantic import ValidationError
 from chuk_tool_processor.logging import get_logger
 from chuk_tool_processor.models.tool_call import ToolCall
 from chuk_tool_processor.plugins.parsers.base import ParserPlugin
+from chuk_tool_processor.utils import fast_json as json
 
 __all__ = ["JsonToolPlugin"]
 

{chuk_tool_processor-0.11 → chuk_tool_processor-0.11.2}/src/chuk_tool_processor/plugins/parsers/openai_tool.py

@@ -3,7 +3,6 @@
 
 from __future__ import annotations
 
-import json
 from typing import Any
 
 from pydantic import ValidationError
@@ -11,6 +10,7 @@ from pydantic import ValidationError
 from chuk_tool_processor.logging import get_logger
 from chuk_tool_processor.models.tool_call import ToolCall
 from chuk_tool_processor.plugins.parsers.base import ParserPlugin
+from chuk_tool_processor.utils import fast_json as json
 
 __all__ = ["OpenAIToolPlugin"]
 

chuk_tool_processor-0.11.2/src/chuk_tool_processor/utils/fast_json.py

@@ -0,0 +1,157 @@
+# chuk_tool_processor/utils/fast_json.py
+"""
+Fast JSON encoding/decoding with automatic fallback.
+
+PERFORMANCE OPTIMIZED:
+- Uses orjson if available (2-3x faster than stdlib json)
+- Automatic fallback to stdlib json if orjson not installed
+- Compatible API for seamless integration
+"""
+
+import json as _stdlib_json
+import logging
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+# Try to import orjson for 2-3x faster JSON operations
+try:
+    import orjson as _orjson
+
+    HAS_ORJSON = True
+    logger.debug("orjson available - using fast JSON implementation")
+except ImportError:
+    HAS_ORJSON = False
+    logger.debug("orjson not available - using stdlib json")
+
+
+def dumps(obj: Any, **kwargs: Any) -> str:
+    """
+    Serialize obj to a JSON formatted string.
+
+    PERFORMANCE: Uses orjson if available (2-3x faster), falls back to stdlib json.
+
+    Args:
+        obj: Python object to serialize
+        **kwargs: Additional arguments (for stdlib json compatibility)
+
+    Returns:
+        JSON string
+
+    Note:
+        orjson returns bytes, we decode to str for compatibility with existing code.
+    """
+    if HAS_ORJSON:
+        # orjson.dumps returns bytes, decode to str for compatibility
+        # orjson is ~2-3x faster than stdlib json
+        try:
+            # orjson options for compatibility with stdlib json
+            # OPT_INDENT_2 for pretty printing if indent kwarg present
+            options = 0
+            if kwargs.get("indent"):
+                options |= _orjson.OPT_INDENT_2
+
+            return _orjson.dumps(obj, option=options).decode("utf-8")
+        except Exception as e:
+            # Fallback to stdlib json if orjson fails (e.g., unsupported types)
+            logger.debug(f"orjson failed, falling back to stdlib json: {e}")
+            return _stdlib_json.dumps(obj, **kwargs)
+    else:
+        # Use stdlib json
+        return _stdlib_json.dumps(obj, **kwargs)
+
+
+def loads(s: str | bytes) -> Any:
+    """
+    Deserialize s (a str, bytes or bytearray containing a JSON document) to a Python object.
+
+    PERFORMANCE: Uses orjson if available (2-3x faster), falls back to stdlib json.
+
+    Args:
+        s: JSON string or bytes to deserialize
+
+    Returns:
+        Python object
+    """
+    if HAS_ORJSON:
+        # orjson.loads accepts both str and bytes
+        try:
+            return _orjson.loads(s)
+        except Exception as e:
+            # Fallback to stdlib json if orjson fails
+            logger.debug(f"orjson failed, falling back to stdlib json: {e}")
+            if isinstance(s, bytes):
+                s = s.decode("utf-8")
+            return _stdlib_json.loads(s)
+    else:
+        # Use stdlib json
+        if isinstance(s, bytes):
+            s = s.decode("utf-8")
+        return _stdlib_json.loads(s)
+
+
+def dump(obj: Any, fp: Any, **kwargs: Any) -> None:
+    """
+    Serialize obj as a JSON formatted stream to fp (a .write()-supporting file-like object).
+
+    PERFORMANCE: Uses orjson if available, falls back to stdlib json.
+
+    Args:
+        obj: Python object to serialize
+        fp: File-like object with .write() method
+        **kwargs: Additional arguments (for stdlib json compatibility)
+    """
+    if HAS_ORJSON:
+        # orjson doesn't have dump(), so we use dumps() and write
+        try:
+            options = 0
+            if kwargs.get("indent"):
+                options |= _orjson.OPT_INDENT_2
+
+            json_bytes = _orjson.dumps(obj, option=options)
+            fp.write(json_bytes)
+        except Exception as e:
+            logger.debug(f"orjson failed, falling back to stdlib json: {e}")
+            _stdlib_json.dump(obj, fp, **kwargs)
+    else:
+        _stdlib_json.dump(obj, fp, **kwargs)
+
+
+def load(fp: Any) -> Any:
+    """
+    Deserialize fp (a .read()-supporting file-like object containing a JSON document) to a Python object.
+
+    PERFORMANCE: Uses orjson if available, falls back to stdlib json.
+
+    Args:
+        fp: File-like object with .read() method
+
+    Returns:
+        Python object
+    """
+    if HAS_ORJSON:
+        try:
+            content = fp.read()
+            return _orjson.loads(content)
+        except Exception as e:
+            logger.debug(f"orjson failed, falling back to stdlib json: {e}")
+            # Re-read if needed
+            if hasattr(fp, "seek"):
+                fp.seek(0)
+                content = fp.read()
+            if isinstance(content, bytes):
+                content = content.decode("utf-8")
+            return _stdlib_json.loads(content)
+    else:
+        return _stdlib_json.load(fp)
+
+
+# Export JSONDecodeError for compatibility
+if HAS_ORJSON:
+    # orjson uses the same JSONDecodeError from json module
+    from json import JSONDecodeError
+else:
+    from json import JSONDecodeError
+
+# Export flag for conditional behavior
+__all__ = ["dumps", "loads", "dump", "load", "HAS_ORJSON", "JSONDecodeError"]

{chuk_tool_processor-0.11 → chuk_tool_processor-0.11.2}/src/chuk_tool_processor.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: chuk-tool-processor
-Version: 0.11
+Version: 0.11.2
 Summary: Async-native framework for registering, discovering, and executing tools referenced in LLM responses
 Author-email: CHUK Team <chrishayuk@somejunkmailbox.com>
 Maintainer-email: CHUK Team <chrishayuk@somejunkmailbox.com>
@@ -20,11 +20,15 @@ Classifier: Framework :: AsyncIO
 Classifier: Typing :: Typed
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
-Requires-Dist: chuk-mcp>=0.8.1
+Requires-Dist: chuk-mcp>=0.9
 Requires-Dist: dotenv>=0.9.9
 Requires-Dist: psutil>=7.0.0
 Requires-Dist: pydantic>=2.11.3
 Requires-Dist: uuid>=1.30
+Provides-Extra: fast-json
+Requires-Dist: orjson<4,>=3.10.0; extra == "fast-json"
+Provides-Extra: full
+Requires-Dist: orjson<4,>=3.10.0; extra == "full"
 
 # CHUK Tool Processor — Production-grade execution for LLM tool calls
 
@@ -287,12 +291,41 @@ pip install chuk-tool-processor[observability]
 # With MCP extras
 pip install chuk-tool-processor[mcp]
 
+# With fast JSON serialization (2-3x faster, recommended for production)
+pip install chuk-tool-processor[fast-json]
+
 # All extras
 pip install chuk-tool-processor[all]
 ```
 
 </details>
 
+<details>
+<summary><strong>Performance Optimization (Optional)</strong></summary>
+
+For **2-3x faster JSON operations**, install with the `fast-json` extra:
+
+```bash
+pip install chuk-tool-processor[fast-json]
+```
+
+This installs [orjson](https://github.com/ijl/orjson), a fast C-based JSON library. When available, it's automatically used for JSON serialization/deserialization throughout the processor while maintaining full compatibility with stdlib json.
+
+**Benchmarks** (see `benchmarks/` for full results):
+
+| Operation | stdlib json | orjson | Speedup |
+|-----------|-------------|--------|---------|
+| Simple JSON (100 bytes) | 1.23 µs | 0.45 µs | **2.7x faster** |
+| Complex JSON (5 KB) | 12.5 µs | 4.2 µs | **3.0x faster** |
+| OpenAI tool calls | 8.9 µs | 3.1 µs | **2.9x faster** |
+
+**Notes:**
+- Falls back to stdlib json automatically if orjson is not installed
+- Hash computation uses stdlib json for consistency across environments
+- No code changes required—just install the extra
+
+</details>
+
 <details>
 <summary><strong>Type Checking Support (PEP 561 compliant)</strong></summary>
 

{chuk_tool_processor-0.11 → chuk_tool_processor-0.11.2}/src/chuk_tool_processor.egg-info/SOURCES.txt

@@ -69,4 +69,5 @@ src/chuk_tool_processor/registry/tool_export.py
 src/chuk_tool_processor/registry/providers/__init__.py
 src/chuk_tool_processor/registry/providers/memory.py
 src/chuk_tool_processor/utils/__init__.py
+src/chuk_tool_processor/utils/fast_json.py
 src/chuk_tool_processor/utils/validation.py

chuk_tool_processor-0.11.2/src/chuk_tool_processor.egg-info/requires.txt

@@ -0,0 +1,11 @@
+chuk-mcp>=0.9
+dotenv>=0.9.9
+psutil>=7.0.0
+pydantic>=2.11.3
+uuid>=1.30
+
+[fast-json]
+orjson<4,>=3.10.0
+
+[full]
+orjson<4,>=3.10.0

chuk_tool_processor-0.11/src/chuk_tool_processor.egg-info/requires.txt

@@ -1,5 +0,0 @@
-chuk-mcp>=0.8.1
-dotenv>=0.9.9
-psutil>=7.0.0
-pydantic>=2.11.3
-uuid>=1.30