veris-ai 1.8.2__py3-none-any.whl → 1.9.0__py3-none-any.whl

veris_ai/__init__.py

@@ -6,42 +6,31 @@ __version__ = "0.1.0"
 
 # Import lightweight modules that only use base dependencies
 from .jaeger_interface import JaegerClient
-from .models import ResponseExpectation
+from .models import ResponseExpectation, ToolCallOptions
 from .observability import init_observability, instrument_fastapi_app
 from .tool_mock import veris
 
 # Lazy import for modules with heavy dependencies
-_veris_runner = None
+_Runner = None
 _VerisConfig = None
 
 
-def veris_runner(*args: Any, **kwargs: Any) -> Any:  # noqa: ANN401
-    """Lazy loader for the veris_runner function from agents_wrapper.
-
-    This function wraps OpenAI agents Runner.run to intercept tool calls
-    through the Veris SDK's mocking infrastructure.
-
-    This function requires the 'agents' extra dependencies:
-    pip install veris-ai[agents]
-    """
-    global _veris_runner  # noqa: PLW0603
-    if _veris_runner is None:
-        try:
-            from .agents_wrapper import veris_runner as _veris_runner_impl  # noqa: PLC0415
-
-            _veris_runner = _veris_runner_impl
-        except ImportError as e:
-            error_msg = (
-                "The 'veris_runner' function requires additional dependencies. "
-                "Please install them with: pip install veris-ai[agents]"
-            )
-            raise ImportError(error_msg) from e
-    return _veris_runner(*args, **kwargs)
-
-
 def __getattr__(name: str) -> Any:  # noqa: ANN401
-    """Lazy load VerisConfig class."""
-    global _VerisConfig  # noqa: PLW0603
+    """Lazy load Runner and VerisConfig classes."""
+    global _Runner, _VerisConfig  # noqa: PLW0603
+    if name == "Runner":
+        if _Runner is None:
+            try:
+                from .agents_wrapper import Runner as _Runner_impl  # noqa: PLC0415
+
+                _Runner = _Runner_impl
+            except ImportError as e:
+                error_msg = (
+                    "The 'Runner' class requires additional dependencies. "
+                    "Please install them with: pip install veris-ai[agents]"
+                )
+                raise ImportError(error_msg) from e
+        return _Runner
     if name == "VerisConfig":
         if _VerisConfig is None:
             try:
@@ -63,8 +52,9 @@ __all__ = [
     "veris",
     "JaegerClient",
     "ResponseExpectation",
+    "ToolCallOptions",
     "init_observability",
     "instrument_fastapi_app",
-    "veris_runner",
+    "Runner",
     "VerisConfig",
 ]

veris_ai/agents_wrapper.py

@@ -4,11 +4,12 @@ import logging
 from collections.abc import Callable
 from typing import Any
 
-from agents import RunContextWrapper, RunResult, Runner
+from agents import RunContextWrapper, RunResult, Runner as OpenAIRunner
 from pydantic import BaseModel
 
 from veris_ai import veris
 from veris_ai.tool_mock import mock_tool_call
+from veris_ai.models import ToolCallOptions
 
 logger = logging.getLogger(__name__)
 
@@ -16,6 +17,7 @@ logger = logging.getLogger(__name__)
 def _wrap(
     include_tools: list[str] | None = None,
     exclude_tools: list[str] | None = None,
+    tool_options: dict[str, ToolCallOptions] | None = None,
 ) -> Callable:
     """Private wrapper for OpenAI agents Runner to intercept tool calls through Veris SDK.
 
@@ -25,6 +27,7 @@ def _wrap(
     Args:
         include_tools: Optional list of tool names to intercept (only these if provided)
         exclude_tools: Optional list of tool names to NOT intercept (these run normally)
+        tool_options: Optional per-tool configuration for mocking behavior
 
     Returns:
         A wrapped Runner.run function
@@ -36,6 +39,8 @@ def _wrap(
     if include_tools and exclude_tools:
         msg = "Cannot specify both include_tools and exclude_tools"
         raise ValueError(msg)
+    if not tool_options:
+        tool_options = {}
 
     def wrapped_run_func(run_func: Callable) -> Callable:
         """Inner wrapper that takes the actual Runner.run function."""
@@ -68,7 +73,7 @@ def _wrap(
                             original_on_invoke = tool.on_invoke_tool
 
                             def make_wrapped_on_invoke_tool(
-                                tool_id: int, orig_invoke: Callable
+                                tool_id: int, orig_invoke: Callable, tool_name_inner: str
                             ) -> Callable:
                                 """Create a wrapped on_invoke_tool with proper closure."""
 
@@ -81,7 +86,10 @@ def _wrap(
                                     if the_func and session_id:
                                         # mock_tool_call is synchronous, don't await it
                                         return mock_tool_call(
-                                            the_func, session_id, parameters, None
+                                            the_func,
+                                            session_id,
+                                            parameters,
+                                            tool_options.get(tool_name_inner),
                                         )
                                     # Fall back to original if we couldn't extract the function
                                     return await orig_invoke(ctx, parameters)
@@ -89,7 +97,7 @@ def _wrap(
                                 return wrapped_on_invoke_tool
 
                             tool.on_invoke_tool = make_wrapped_on_invoke_tool(
-                                id(tool), original_on_invoke
+                                id(tool), original_on_invoke, tool_name
                             )
             return await run_func(starting_agent, input_text, **kwargs)
 
@@ -225,59 +233,78 @@ def _find_user_function_in_closure(closure: tuple) -> Callable | None:
 
 
 class VerisConfig(BaseModel):
-    """Configuration for the Veris SDK."""
+    """Configuration for the Veris SDK Runner.
+
+    Attributes:
+        include_tools: Optional list of tool names to intercept (only these if provided)
+        exclude_tools: Optional list of tool names to NOT intercept (these run normally)
+        tool_options: Optional per-tool configuration for mocking behavior
+    """
 
     include_tools: list[str] | None = None
     exclude_tools: list[str] | None = None
+    tool_options: dict[str, ToolCallOptions] | None = None
 
 
-def veris_runner(
-    starting_agent: Any,  # noqa: ANN401
-    input_text: str,
-    veris_config: VerisConfig | None = None,
-    **kwargs: Any,  # noqa: ANN401
-) -> RunResult:  # noqa: ANN401
-    """Veris-wrapped version of OpenAI agents Runner.run.
-
-    This function wraps the OpenAI agents Runner.run to intercept tool calls
-    and route them through the Veris SDK's mocking infrastructure. It can be
-    used as a drop-in replacement for Runner.run with an additional veris_config parameter.
+class Runner(OpenAIRunner):
+    """Veris-enhanced Runner that extends OpenAI's Runner with tool interception.
 
-    Args:
-        starting_agent: The OpenAI agent to run
-        input_text: The input text to process
-        veris_config: Optional configuration for Veris SDK tool interception
-        **kwargs: Additional arguments to pass to Runner.run
-
-    Returns:
-        The result from Runner.run
+    This class extends the OpenAI agents Runner to intercept tool calls
+    and route them through the Veris SDK's mocking infrastructure.
 
     Example:
         ```python
-        from veris_ai import veris_runner, VerisConfig
+        from veris_ai import Runner, VerisConfig
         from agents import Agent, FunctionTool
 
         # Define your agent with tools
         agent = Agent(...)
 
-        # Use veris_runner instead of Runner.run
-        result = await veris_runner(agent, "Process this input")
+        # Use Veris Runner instead of OpenAI Runner
+        result = await Runner.run(agent, "Process this input")
 
-        # Or with specific tool configuration
+        # Or with configuration
         config = VerisConfig(include_tools=["calculator", "search"])
-        result = await veris_runner(agent, "Calculate 2+2", veris_config=config)
+        result = await Runner.run(agent, "Calculate 2+2", veris_config=config)
         ```
     """
 
-    # Extract config values
-    include_tools = None
-    exclude_tools = None
-    if veris_config:
-        include_tools = veris_config.include_tools
-        exclude_tools = veris_config.exclude_tools
-
-    # Create the wrapped version of Runner.run with the config
-    wrapped_run = _wrap(include_tools=include_tools, exclude_tools=exclude_tools)(Runner.run)
-
-    # Execute the wrapped run function
-    return wrapped_run(starting_agent, input_text, **kwargs)
+    @classmethod
+    async def run(
+        cls,
+        starting_agent: Any,  # noqa: ANN401
+        input: Any,  # noqa: ANN401, A002
+        veris_config: VerisConfig | None = None,
+        **kwargs: Any,  # noqa: ANN401
+    ) -> RunResult:  # noqa: ANN401
+        """Run an agent with Veris tool interception.
+
+        This method overrides the OpenAI Runner.run to apply tool interception
+        based on the provided configuration.
+
+        Args:
+            starting_agent: The OpenAI agent to run
+            input: The input text/messages to process
+            veris_config: Optional configuration for tool interception
+            **kwargs: Additional arguments to pass to the base Runner.run
+
+        Returns:
+            The result from the agent execution
+        """
+        # Use provided config or create default
+        config = veris_config or VerisConfig()
+
+        # Validate configuration
+        if config.include_tools and config.exclude_tools:
+            msg = "Cannot specify both include_tools and exclude_tools"
+            raise ValueError(msg)
+
+        # Apply the wrapping logic
+        wrapped_run = _wrap(
+            include_tools=config.include_tools,
+            exclude_tools=config.exclude_tools,
+            tool_options=config.tool_options or {},
+        )(OpenAIRunner.run)
+
+        # Execute the wrapped run function
+        return await wrapped_run(starting_agent, input, **kwargs)

veris_ai/models.py

@@ -19,4 +19,4 @@ class ToolCallOptions(BaseModel):
 
     response_expectation: ResponseExpectation = ResponseExpectation.AUTO
     cache_response: bool = False
-    mode: Literal["tool", "function", "spy"] = "tool"
+    mode: Literal["tool", "function"] = "tool"

{veris_ai-1.8.2.dist-info → veris_ai-1.9.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: veris-ai
-Version: 1.8.2
+Version: 1.9.0
 Summary: A Python package for Veris AI tools
 Project-URL: Homepage, https://github.com/veris-ai/veris-python-sdk
 Project-URL: Bug Tracker, https://github.com/veris-ai/veris-python-sdk/issues
@@ -47,7 +47,7 @@ A Python package for Veris AI tools with simulation capabilities and FastAPI MCP
 ## Quick Reference
 
 **Purpose**: Tool mocking, tracing, and FastAPI MCP integration for AI agent development  
-**Core Components**: [`tool_mock`](#function-mocking) • [`api_client`](src/veris_ai/api_client.py) • [`observability`](#sdk-observability-helpers) • [`fastapi_mcp`](#fastapi-mcp-integration) • [`jaeger_interface`](#jaeger-trace-interface)  
+**Core Components**: [`tool_mock`](#function-mocking) • [`api_client`](src/veris_ai/api_client.py) • [`observability`](#sdk-observability-helpers) • [`agents_wrapper`](#openai-agents-integration) • [`fastapi_mcp`](#fastapi-mcp-integration) • [`jaeger_interface`](#jaeger-trace-interface)  
 **Deep Dive**: [`Module Architecture`](src/veris_ai/README.md) • [`Testing Guide`](tests/README.md) • [`Usage Examples`](examples/README.md)  
 **Source of Truth**: Implementation details in [`src/veris_ai/`](src/veris_ai/) source code
 
@@ -58,13 +58,14 @@ A Python package for Veris AI tools with simulation capabilities and FastAPI MCP
 uv add veris-ai
 
 # With optional extras
-uv add "veris-ai[dev,fastapi,instrument]"
+uv add "veris-ai[dev,fastapi,observability,agents]"
 ```
 
 **Installation Profiles**:
 - `dev`: Development tools (ruff, pytest, mypy) 
 - `fastapi`: FastAPI MCP integration
 - `observability`: OpenTelemetry tracing
+- `agents`: OpenAI agents integration
 
 ## Import Patterns
 
@@ -75,10 +76,11 @@ uv add "veris-ai[dev,fastapi,instrument]"
 from veris_ai import veris, JaegerClient
 
 # Optional features (require extras)
-from veris_ai import init_observability, instrument_fastapi_app  # Provided by SDK observability helpers
+from veris_ai import init_observability, instrument_fastapi_app  # Requires observability extras
+from veris_ai import Runner, VerisConfig  # Requires agents extras
 ```
 
-**Complete Import Strategies**: See [`examples/README.md`](examples/README.md) for five different import approaches, conditional features, and integration patterns.
+**Complete Import Strategies**: See [`examples/README.md`](examples/README.md) for different import approaches, conditional features, and integration patterns.
 
 ## Configuration
 
@@ -182,6 +184,107 @@ async def get_data() -> dict:
 
 **Implementation**: See [`src/veris_ai/tool_mock.py`](src/veris_ai/tool_mock.py) for decorator logic and API integration.
 
+## OpenAI Agents Integration
+
+**Semantic Tag**: `openai-agents`
+
+The SDK provides seamless integration with [OpenAI's agents library](https://github.com/openai/agents) through the `Runner` class, which extends OpenAI's Runner to intercept tool calls and route them through Veris's mocking infrastructure.
+
+### Installation
+
+```bash
+# Install with agents support
+uv add "veris-ai[agents]"
+```
+
+### Basic Usage
+
+```python
+from veris_ai import veris, Runner, VerisConfig
+from agents import Agent, function_tool
+
+# Define your tools
+@function_tool
+def calculator(x: int, y: int, operation: str = "add") -> int:
+    """Performs arithmetic operations."""
+    # ... implementation ...
+
+# Create an agent with tools
+agent = Agent(
+    name="Assistant",
+    model="gpt-4",
+    tools=[calculator],
+    instructions="You are a helpful assistant.",
+)
+
+# Use Veris Runner instead of OpenAI's Runner
+result = await Runner.run(agent, "Calculate 10 + 5")
+
+# Or with configuration
+config = VerisConfig(include_tools=["calculator"])
+result = await Runner.run(agent, "Calculate 10 + 5", veris_config=config)
+```
+
+### Selective Tool Interception
+
+Control which tools are intercepted using VerisConfig:
+
+```python
+from veris_ai import Runner, VerisConfig
+
+# Only intercept specific tools
+config = VerisConfig(include_tools=["calculator", "search_web"])
+result = await Runner.run(agent, "Process this", veris_config=config)
+
+# Or exclude specific tools from interception
+config = VerisConfig(exclude_tools=["get_weather"])
+result = await Runner.run(agent, "Check weather", veris_config=config)
+```
+
+### Advanced Tool Configuration
+
+Fine-tune individual tool behavior using `ToolCallOptions`:
+
+```python
+from veris_ai import Runner, VerisConfig, ResponseExpectation, ToolCallOptions
+
+# Configure specific tool behaviors
+config = VerisConfig(
+    tool_options={
+        "calculator": ToolCallOptions(
+            response_expectation=ResponseExpectation.REQUIRED,  # Always expect response
+            cache_response=True,  # Cache responses for identical calls
+            mode="tool"  # Use tool mode (default)
+        ),
+        "search_web": ToolCallOptions(
+            response_expectation=ResponseExpectation.NONE,  # Don't wait for response
+            cache_response=False,
+            mode="spy"  # Log calls but execute normally
+        )
+    }
+)
+
+result = await Runner.run(agent, "Calculate and search", veris_config=config)
+```
+
+**ToolCallOptions Parameters**:
+- `response_expectation`: Control response behavior
+  - `AUTO` (default): Automatically determine based on context
+  - `REQUIRED`: Always wait for mock response
+  - `NONE`: Don't wait for response
+- `cache_response`: Cache responses for identical tool calls
+- `mode`: Tool execution mode
+  - `"tool"` (default): Standard tool execution
+  - `"function"`: Function mode
+
+**Key Features**:
+- **Drop-in replacement**: Use `Runner` from veris_ai instead of OpenAI's Runner
+- **Extends OpenAI Runner**: Inherits all functionality while adding Veris capabilities
+- **Automatic session management**: Integrates with Veris session IDs
+- **Selective mocking**: Include or exclude specific tools from interception
+
+**Implementation**: See [`src/veris_ai/agents_wrapper.py`](src/veris_ai/agents_wrapper.py) for the integration logic and [`examples/openai_agents_example.py`](examples/openai_agents_example.py) for complete examples.
+
 ## FastAPI MCP Integration
 
 **Semantic Tag**: `fastapi-mcp`
@@ -254,7 +357,7 @@ pytest --cov=veris_ai # Test with coverage
 
 **Semantic Tag**: `module-architecture`
 
-**Core Modules**: `tool_mock` (mocking), `api_client` (centralized API), `jaeger_interface` (trace queries), `utils` (schema conversion)
+**Core Modules**: `tool_mock` (mocking), `api_client` (centralized API), `agents_wrapper` (OpenAI agents integration), `jaeger_interface` (trace queries), `utils` (schema conversion)
 
 **Complete Architecture**: See [`src/veris_ai/README.md`](src/veris_ai/README.md) for module overview, implementation flows, and configuration details. 
 

{veris_ai-1.8.2.dist-info → veris_ai-1.9.0.dist-info}/RECORD

@@ -1,9 +1,9 @@
 veris_ai/README.md,sha256=0EC-yWB8FtqAhtcE5Q204bS1JWJPIvfpp1bPDo6iwwc,3601
-veris_ai/__init__.py,sha256=mFEF2pHXOAXoXuBh9IOQgqpKGvzLOsy8b0vUpMRJggU,2260
-veris_ai/agents_wrapper.py,sha256=LmxPkOg3KLICgTrl0Bouy7enhyO4tF6_evq2cb8I_ig,10718
+veris_ai/__init__.py,sha256=enl_gEa6BQAjWvzCtsn_hFVJVVlJZ_dMsLL--E5W3nU,1907
+veris_ai/agents_wrapper.py,sha256=L4llszfyZkG4Xjo8OTeVfm-IIdESAcW51ukxceKc88U,11907
 veris_ai/api_client.py,sha256=Gu_ovqaW-hZ6yPee2GVconMeg_xOxlt7IKu0HJQNiD0,2192
 veris_ai/logging.py,sha256=ENduOHnc5UmzciTDZDJCZqUOXb5We-bdtwN9f9Qqwl0,1360
-veris_ai/models.py,sha256=TiQJuME2pGDE6EY5J8TYKNSeajaN2Xk9ISsLoIwgtgU,502
+veris_ai/models.py,sha256=xKeheSJQle2tBeJG1DsGJzMDwv24p5jECjX6RAa39n4,495
 veris_ai/observability.py,sha256=fDtWeUexfzaIQArE5YbWsja8Y-bcE_h0dXQWYbXbupY,4929
 veris_ai/tool_mock.py,sha256=L2p6Yg8S98floahDTrf6cnmDqC6Dq3YKA7Q6RRvv7BQ,10253
 veris_ai/utils.py,sha256=Ud4k2jKAJ6-nqSsFXIJWYrOmPGmvl5RSp36cQtgnMpg,9781
@@ -11,7 +11,7 @@ veris_ai/jaeger_interface/README.md,sha256=kd9rKcE5xf3EyNaiHu0tjn-0oES9sfaK6Ih-O
 veris_ai/jaeger_interface/__init__.py,sha256=KD7NSiMYRG_2uF6dOLKkGG5lNQe4K9ptEwucwMT4_aw,1128
 veris_ai/jaeger_interface/client.py,sha256=yJrh86wRR0Dk3Gq12DId99WogcMIVbL0QQFqVSevvlE,8772
 veris_ai/jaeger_interface/models.py,sha256=e64VV6IvOEFuzRUgvDAMQFyOZMRb56I-PUPZLBZ3rX0,1864
-veris_ai-1.8.2.dist-info/METADATA,sha256=Qw1UFcpv4cc7kpozLsUds6R8p5inAadVz0SSnYqwBQs,9924
-veris_ai-1.8.2.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-veris_ai-1.8.2.dist-info/licenses/LICENSE,sha256=2g4i20atAgtD5einaKzhQrIB-JrPhyQgD3bC0wkHcCI,1065
-veris_ai-1.8.2.dist-info/RECORD,,
+veris_ai-1.9.0.dist-info/METADATA,sha256=8c5TObTTfXNUiV0uTiTUu1sAZs7VOcrki1Q-00sGn_8,13495
+veris_ai-1.9.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+veris_ai-1.9.0.dist-info/licenses/LICENSE,sha256=2g4i20atAgtD5einaKzhQrIB-JrPhyQgD3bC0wkHcCI,1065
+veris_ai-1.9.0.dist-info/RECORD,,