veris-ai 1.8.2__tar.gz → 1.9.0__tar.gz

{veris_ai-1.8.2 → veris_ai-1.9.0}/PKG-INFO

@@ -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 → veris_ai-1.9.0}/README.md

@@ -5,7 +5,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
 
@@ -16,13 +16,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
 
@@ -33,10 +34,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
 
@@ -140,6 +142,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`
@@ -212,7 +315,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 → veris_ai-1.9.0}/examples/openai_agents_example.py

@@ -4,15 +4,17 @@ import asyncio
 import os
 import sys
 
-from veris_ai import veris, wrap
+from veris_ai import veris, Runner, VerisConfig
 
 # Ensure the openai-agents package is installed
 try:
-    from agents import Agent, Runner, function_tool
+    from agents import Agent, function_tool
 except ImportError:
     print("Please install the openai-agents package: pip install veris-ai[agents]")
     sys.exit(1)
 
+# Note: The Veris Runner extends OpenAI's Runner, providing a seamless upgrade path
+
 
 # Define some example tools
 @function_tool
@@ -42,9 +44,9 @@ def get_weather(location: str) -> str:
 
 
 async def example_basic_wrap() -> None:
-    """Basic example: Wrap all tools."""
+    """Basic example: Intercept all tools using Runner (recommended)."""
     print("\n" + "=" * 60)
-    print("Example 1: Basic Wrap - All Tools Intercepted")
+    print("Example 1: Basic - All Tools Intercepted (New Runner Class)")
     print("=" * 60)
 
     # Create an agent with tools
@@ -55,18 +57,15 @@ async def example_basic_wrap() -> None:
         instructions="You are a helpful assistant with various tools.",
     )
 
-    # Wrap the Runner.run method - all tools will be intercepted
-    wrapped_run = wrap(Runner.run)
-
-    # Use it like normal Runner.run
-    result = await wrapped_run(agent, "What's 10 + 5? Also search for Python tutorials.")
+    # Use the new Runner class (recommended approach)
+    result = await Runner.run(agent, "What's 10 + 5? Also search for Python tutorials.")
     print(f"Result: {result.output}")
 
 
 async def example_selective_wrap() -> None:
-    """Example with selective tool interception."""
+    """Example with selective tool interception using Runner with config."""
     print("\n" + "=" * 60)
-    print("Example 2: Selective Wrap - Only Specific Tools")
+    print("Example 2: Selective - Only Specific Tools (With Config)")
     print("=" * 60)
 
     agent = Agent(
@@ -76,13 +75,12 @@ async def example_selective_wrap() -> None:
         instructions="You are a helpful assistant.",
     )
 
-    # Only intercept calculator and search_web
-    wrapped_run = wrap(Runner.run, include_tools=["calculator", "search_web"])
-
     print("📝 Only 'calculator' and 'search_web' will be mocked via Veris")
     print("   'get_weather' will run normally")
 
-    result = await wrapped_run(agent, "Calculate 5+3 and check weather in NYC")
+    # Create configuration and use Runner.run
+    config = VerisConfig(include_tools=["calculator", "search_web"])
+    result = await Runner.run(agent, "Calculate 5+3 and check weather in NYC", veris_config=config)
     print(f"Result: {result.output}")
 
 
@@ -99,19 +97,20 @@ async def example_exclude_tools() -> None:
         instructions="You are a helpful assistant.",
     )
 
-    # Intercept everything EXCEPT get_weather
-    wrapped_run = wrap(Runner.run, exclude_tools=["get_weather"])
-
     print("📝 All tools EXCEPT 'get_weather' will be mocked via Veris")
 
-    result = await wrapped_run(agent, "Calculate 10*5 and check weather in London")
+    # Use Runner.run with exclude_tools config
+    config = VerisConfig(exclude_tools=["get_weather"])
+    result = await Runner.run(
+        agent, "Calculate 10*5 and check weather in London", veris_config=config
+    )
     print(f"Result: {result.output}")
 
 
-async def example_coroutine_wrap() -> None:
-    """Example wrapping a coroutine directly."""
+async def example_simple_calculation() -> None:
+    """Example with simple calculation tool."""
     print("\n" + "=" * 60)
-    print("Example 4: Direct Coroutine Wrap")
+    print("Example 4: Simple Calculation (Direct Runner.run)")
     print("=" * 60)
 
     agent = Agent(
@@ -121,8 +120,8 @@ async def example_coroutine_wrap() -> None:
         instructions="You are a helpful assistant.",
     )
 
-    # Wrap the coroutine directly
-    result = await wrap(Runner.run(agent, "What's 7 * 8?"))
+    # Use Runner.run directly (like OpenAI's Runner)
+    result = await Runner.run(agent, "What's 7 * 8?")
     print(f"Result: {result.output}")
 
 
@@ -131,6 +130,7 @@ async def main() -> None:
     print("\n🚀 VERIS SDK - OPENAI AGENTS WRAPPER EXAMPLES")
     print("\nThese examples demonstrate different ways to intercept tool calls")
     print("from OpenAI agents and route them through the Veris SDK.\n")
+    print("🆕 Using the Veris Runner class that extends OpenAI's Runner!\n")
 
     # Set up the environment
     # In production, these would be set as environment variables
@@ -153,7 +153,7 @@ async def main() -> None:
         await example_basic_wrap()
         await example_selective_wrap()
         await example_exclude_tools()
-        await example_coroutine_wrap()
+        await example_simple_calculation()
     except Exception as e:
         print(f"\n❌ Error: {e}")
         print("\nMake sure to:")
@@ -169,7 +169,14 @@ async def main() -> None:
     print("\nNext steps:")
     print("1. Set up your Veris endpoint")
     print("2. Configure your OpenAI API key")
-    print("3. Use wrap() to intercept tool calls in your agents")
+    print("3. Use the Runner class from veris_ai to intercept tool calls")
+    print("\n💡 Usage:")
+    print("   from veris_ai import Runner, VerisConfig")
+    print("   # Direct usage without config")
+    print("   result = await Runner.run(agent, 'your input')")
+    print("   # With configuration")
+    print("   config = VerisConfig(include_tools=['tool1'])")
+    print("   result = await Runner.run(agent, 'your input', veris_config=config)")
 
 
 if __name__ == "__main__":

{veris_ai-1.8.2 → veris_ai-1.9.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "veris-ai"
-version = "1.8.2"
+version = "1.9.0"
 description = "A Python package for Veris AI tools"
 readme = "README.md"
 requires-python = ">=3.11"

{veris_ai-1.8.2 → veris_ai-1.9.0}/src/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",
 ]