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

veris_ai/README.md

@@ -14,9 +14,10 @@ This module contains the core implementation of the Veris AI Python SDK. Each co
 
 | Module | Purpose | Key Classes/Functions | Lines |
 |--------|---------|----------------------|-------|
-| [`tool_mock.py`](tool_mock.py) | Function mocking & FastAPI MCP | `VerisSDK`, `@mock`, `@stub` | 327 |
-| [`utils.py`](utils.py) | Type utilities & JSON schema | `extract_json_schema()` | 272 |
-| [`logging.py`](logging.py) | Logging configuration | `setup_logging()` | 116 |
+| [`tool_mock.py`](tool_mock.py) | Function mocking & FastAPI MCP | `VerisSDK`, `@mock`, `@stub`, `@spy` | 327 |
+| [`utils.py`](utils.py) | Type utilities & JSON schema | `extract_json_schema()`, `convert_to_type()` | 272 |
+| [`api_client.py`](api_client.py) | Centralized API client | `SimulatorAPIClient` | 62 |
+| [`logging.py`](logging.py) | Tool call/response logging | `log_tool_call()`, `log_tool_response()` | 116 |
 | [`models.py`](models.py) | Data models | Type definitions | 12 |
 | [`jaeger_interface/`](jaeger_interface/) | Jaeger Query API wrapper | `JaegerClient` | See module README |
 
@@ -26,16 +27,16 @@ This module contains the core implementation of the Veris AI Python SDK. Each co
 
 ### Mock Flow
 1. **Decoration**: `@veris.mock()` captures function metadata
-2. **Environment Check**: `ENV=simulation` determines behavior  
-3. **API Call**: POST to `{VERIS_ENDPOINT_URL}/api/v2/tool_mock`
+2. **Session Check**: Presence of session ID determines behavior  
+3. **API Call**: POST to VERIS API endpoint `/v2/tool_mock` (auto-configured)
 4. **Type Conversion**: Response converted using `extract_json_schema()`
 
 **Implementation**: [`tool_mock.py:200-250`](tool_mock.py)
 
 ### Spy Flow  
-1. **Pre-execution Logging**: Call details sent to `/api/v2/log_tool_call`
+1. **Pre-execution Logging**: Call details sent to `/v2/simulations/{session_id}/log_tool_call`
 2. **Function Execution**: Original function runs normally
-3. **Post-execution Logging**: Response sent to `/api/v2/log_tool_response`
+3. **Post-execution Logging**: Response sent to `/v2/simulations/{session_id}/log_tool_response`
 
 **Implementation**: [`tool_mock.py:250-300`](tool_mock.py)
 
@@ -44,11 +45,11 @@ This module contains the core implementation of the Veris AI Python SDK. Each co
 
 **Semantic Tag**: `module-config`
 
-Environment variables are processed in [`tool_mock.py`](tool_mock.py):
+Environment variables are processed in [`api_client.py`](api_client.py):
 
-- `VERIS_ENDPOINT_URL`: Mock server endpoint
-- `VERIS_MOCK_TIMEOUT`: Request timeout (default: 90s)  
-- `ENV`: Set to `"simulation"` for mock mode
+- `VERIS_API_KEY`: API authentication key (optional, but recommended)
+- `VERIS_MOCK_TIMEOUT`: Request timeout (default: 90s)
+- `VERIS_API_URL`: Override default API endpoint (rarely needed - defaults to production)
 
 ### Observability (OTLP / Logfire)
 

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

@@ -1,14 +1,16 @@
 """OpenAI Agents wrapper for automatic tool mocking via Veris SDK."""
 
+import json
 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 +18,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 +28,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 +40,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 +74,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 +87,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,
+                                            json.loads(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 +98,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 +234,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/observability.py

@@ -28,6 +28,12 @@ def init_observability() -> None:  # noqa: PLR0912
 
         logfire.configure(scrubbing=False)
         logfire.instrument_openai_agents()
+        try:
+            logfire.instrument_redis()
+        except Exception:
+            logger.warning("Failed to instrument redis")
+        logfire.instrument_mcp()
+
     except Exception as e:
         # Tracing is optional; continue without Traceloop
         msg = "Logfire not found: " + str(e)
@@ -96,25 +102,6 @@ def init_observability() -> None:  # noqa: PLR0912
         msg = "OpenTelemetry not found: " + str(e)
         raise RuntimeError(msg) from e
 
-    try:
-        from opentelemetry.instrumentation.httpx import (
-            HTTPXClientInstrumentor,  # type: ignore[import-not-found]
-        )
-
-        HTTPXClientInstrumentor().instrument(request_hook=_log_request_headers)
-    except Exception as e:
-        msg = "OpenTelemetry not found: " + str(e)
-        raise RuntimeError(msg) from e
-
-    # Optionally enable MCP-specific spans
-    try:
-        from opentelemetry.instrumentation.mcp import McpInstrumentor  # type: ignore[import-not-found]
-
-        McpInstrumentor().instrument()
-    except Exception as e:
-        msg = "OpenTelemetry not found: " + str(e)
-        raise RuntimeError(msg) from e
-
 
 def instrument_fastapi_app(app: FastAPI) -> None:
     """Instrument a FastAPI app so inbound HTTP requests continue W3C traces.
@@ -122,10 +109,6 @@ def instrument_fastapi_app(app: FastAPI) -> None:
     Safe to call even if the fastapi instrumentation package is not installed.
     """
 
-    try:
-        from opentelemetry.instrumentation.fastapi import FastAPIInstrumentor  # type: ignore[import-not-found]
+    import logfire
 
-        FastAPIInstrumentor.instrument_app(app)
-    except Exception as e:
-        msg = "OpenTelemetry not found: " + str(e)
-        raise RuntimeError(msg) from e
+    logfire.instrument_fastapi(app)

veris_ai/tool_mock.py

@@ -5,6 +5,7 @@ from collections.abc import Callable
 from contextlib import suppress
 from contextvars import ContextVar
 from functools import wraps
+import tenacity
 from typing import (
     Any,
     Literal,
@@ -13,10 +14,6 @@ from typing import (
 )
 
 
-from veris_ai.logging import (
-    log_tool_call,
-    log_tool_response,
-)
 from veris_ai.models import ResponseExpectation, ToolCallOptions
 from veris_ai.api_client import get_api_client
 from veris_ai.utils import convert_to_type, extract_json_schema, get_function_parameters
@@ -173,6 +170,9 @@ class VerisSDK:
                 """Async wrapper."""
                 session_id = _session_id_context.get()
                 if not session_id:
+                    logger.info(
+                        f"No session ID found, executing original function: {func.__name__}"
+                    )
                     return await func(*args, **kwargs)
                 parameters = get_function_parameters(func, args, kwargs)
                 return mock_tool_call(
@@ -190,6 +190,9 @@ class VerisSDK:
                 """Sync wrapper."""
                 session_id = _session_id_context.get()
                 if not session_id:
+                    logger.info(
+                        f"No session ID found, executing original function: {func.__name__}"
+                    )
                     return func(*args, **kwargs)
                 parameters = get_function_parameters(func, args, kwargs)
                 return mock_tool_call(
@@ -217,7 +220,9 @@ class VerisSDK:
                 **kwargs: Any,  # noqa: ANN401
             ) -> object:
                 if not self.session_id:
-                    # If not in simulation mode, execute the original function
+                    logger.info(
+                        f"No session ID found, executing original function: {func.__name__}"
+                    )
                     return await func(*args, **kwargs)
                 logger.info(f"Stubbing function: {func.__name__}")
                 return return_value
@@ -225,7 +230,9 @@ class VerisSDK:
             @wraps(func)
             def sync_wrapper(*args: tuple[object, ...], **kwargs: Any) -> object:  # noqa: ANN401
                 if not self.session_id:
-                    # If not in simulation mode, execute the original function
+                    logger.info(
+                        f"No session ID found, executing original function: {func.__name__}"
+                    )
                     return func(*args, **kwargs)
                 logger.info(f"Stubbing function: {func.__name__}")
                 return return_value
@@ -236,10 +243,15 @@ class VerisSDK:
         return decorator
 
 
+@tenacity.retry(
+    stop=tenacity.stop_after_attempt(3),
+    wait=tenacity.wait_exponential(multiplier=1, min=4, max=10),
+    reraise=True,
+)
 def mock_tool_call(
     func: Callable,
     session_id: str,
-    parameters: str,
+    parameters: dict[str, dict[str, str]],
     options: ToolCallOptions | None = None,
 ) -> object:
     """Mock tool call."""
@@ -262,7 +274,7 @@ def mock_tool_call(
         "cache_response": bool(options.cache_response),
         "tool_call": {
             "function_name": func.__name__,
-            "parameters": json.loads(parameters),
+            "parameters": parameters,
             "return_type": json.dumps(extract_json_schema(return_type_obj)),
             "docstring": docstring,
         },
@@ -278,4 +290,41 @@ def mock_tool_call(
     return convert_to_type(mock_result, return_type_obj)
 
 
+def log_tool_call(
+    session_id: str,
+    function_name: str,
+    parameters: dict[str, dict[str, str]],
+    docstring: str,
+) -> None:
+    """Log tool call synchronously to the VERIS logging endpoint."""
+    api_client = get_api_client()
+    endpoint = api_client.get_log_tool_call_endpoint(session_id)
+    payload = {
+        "function_name": function_name,
+        "parameters": parameters,
+        "docstring": docstring,
+    }
+    try:
+        api_client.post(endpoint, payload)
+        logger.debug(f"Tool call logged for {function_name}")
+    except Exception as e:
+        logger.warning(f"Failed to log tool call for {function_name}: {e}")
+
+
+def log_tool_response(session_id: str, response: Any) -> None:  # noqa: ANN401
+    """Log tool response synchronously to the VERIS logging endpoint."""
+    api_client = get_api_client()
+    endpoint = api_client.get_log_tool_response_endpoint(session_id)
+
+    payload = {
+        "response": json.dumps(response, default=str),
+    }
+
+    try:
+        api_client.post(endpoint, payload)
+        logger.debug("Tool response logged")
+    except Exception as e:
+        logger.warning(f"Failed to log tool response: {e}")
+
+
 veris = VerisSDK()

veris_ai/utils.py

@@ -1,10 +1,19 @@
 import inspect
-import json
 import sys
 import types
 import typing
 from contextlib import suppress
-from typing import Any, ForwardRef, Literal, NotRequired, Required, Union, get_args, get_origin
+from typing import (
+    Any,
+    ForwardRef,
+    Literal,
+    NotRequired,
+    Required,
+    Union,
+    get_args,
+    get_origin,
+    get_type_hints,
+)
 from collections.abc import Callable
 
 from pydantic import BaseModel
@@ -279,12 +288,18 @@ def extract_json_schema(target_type: Any) -> dict:  # noqa: PLR0911, PLR0912, C9
 
 def get_function_parameters(
     func: Callable, args: tuple[object, ...], kwargs: dict[str, object]
-) -> str:
+) -> dict[str, dict[str, str]]:
     """Get the parameters for a function."""
+    params_info = {}
     sig = inspect.signature(func)
     bound_args = sig.bind(*args, **kwargs)
     bound_args.apply_defaults()
     _ = bound_args.arguments.pop("ctx", None)
     _ = bound_args.arguments.pop("self", None)
     _ = bound_args.arguments.pop("cls", None)
-    return json.dumps(bound_args.arguments)
+    for param_name, param_value in bound_args.arguments.items():
+        params_info[param_name] = {
+            "value": str(param_value),
+            "type": str(get_type_hints(func).get(param_name, Any)),
+        }
+    return params_info

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: veris-ai
-Version: 1.8.2
+Version: 1.10.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
@@ -20,6 +20,7 @@ Requires-Dist: opentelemetry-instrumentation>=0.55b1
 Requires-Dist: opentelemetry-sdk>=1.34.1
 Requires-Dist: pydantic>=2.0.0
 Requires-Dist: requests>=2.31.0
+Requires-Dist: tenacity>=9.1.2
 Provides-Extra: agents
 Requires-Dist: openai-agents>=0.0.1; extra == 'agents'
 Provides-Extra: dev
@@ -47,7 +48,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 +59,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 +77,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
 
@@ -88,7 +91,6 @@ from veris_ai import init_observability, instrument_fastapi_app  # Provided by S
 |----------|---------|---------|
 | `VERIS_API_KEY` | API authentication key | None |
 | `VERIS_MOCK_TIMEOUT` | Request timeout (seconds) | `90.0` |
-| `ENV` | Set to `"simulation"` for mock mode | Production |
 
 **Advanced Configuration** (rarely needed):
 - `VERIS_API_URL`: Override default API endpoint (defaults to production)
@@ -156,32 +158,161 @@ End-to-end propagation with the simulator:
 
 **Semantic Tag**: `tool-mocking`
 
+### Session-Based Activation
+
+The SDK uses session-based activation to determine when to enable mocking. Choose one of these methods to set a session ID:
+
+**Option 1: Manual Setting**
+```python
+from veris_ai import veris
+
+# Explicitly set a session ID
+veris.set_session_id("your-session-id")
+
+# Now decorated functions will use mock responses
+result = await your_mocked_function()
+
+# Clear session to disable mocking
+veris.clear_session_id()
+```
+
+**Option 2: Automatic Extraction (FastAPI MCP)**
+```python
+# When using FastAPI MCP integration, session IDs are 
+# automatically extracted from OAuth2 bearer tokens
+veris.set_fastapi_mcp(...)
+# No manual session management needed
+```
+
+**How it works internally**: Regardless of which method you use, session IDs are stored in Python context variables (`contextvars`). This ensures proper isolation between concurrent requests and automatic propagation through the call stack.
+
 ### Core Decorators
 
 ```python
 from veris_ai import veris
 
-# Mock mode: Returns simulated responses in ENV=simulation
+# Mock decorator: Returns simulated responses when session ID is set
 @veris.mock()
 async def your_function(param1: str, param2: int) -> dict:
     """Function documentation for LLM context."""
     return {"result": "actual implementation"}
 
-# Spy mode: Executes function but logs calls/responses
+# Spy decorator: Executes function and logs calls/responses
 @veris.spy()
 async def monitored_function(data: str) -> dict:
     return process_data(data)
 
-# Stub mode: Returns fixed value in simulation
+# Stub decorator: Returns fixed value in simulation
 @veris.stub(return_value={"status": "success"})
 async def get_data() -> dict:
     return await fetch_from_api()
 ```
 
-**Behavior**: In simulation mode, decorators intercept calls to mock endpoints. In production, functions execute normally.
+**Behavior**: When a session ID is set, decorators activate their respective behaviors (mock responses, logging, or stubbed values). Without a session ID, functions execute normally.
 
 **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 +385,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.10.0.dist-info/RECORD

@@ -0,0 +1,16 @@
+veris_ai/README.md,sha256=Ht1abGu-2_O0ZHJoJC7eAfG5WhO2CstAuV3hXPq1yAs,3875
+veris_ai/__init__.py,sha256=enl_gEa6BQAjWvzCtsn_hFVJVVlJZ_dMsLL--E5W3nU,1907
+veris_ai/agents_wrapper.py,sha256=N-YZ0qvIEJ8rlFZAzVKg6eWKa7I_qIt-khlg_zL-qY8,11931
+veris_ai/api_client.py,sha256=Gu_ovqaW-hZ6yPee2GVconMeg_xOxlt7IKu0HJQNiD0,2192
+veris_ai/models.py,sha256=xKeheSJQle2tBeJG1DsGJzMDwv24p5jECjX6RAa39n4,495
+veris_ai/observability.py,sha256=eSIXmk6fpOAoWM-sDbsvzyUASh1ZwU6tRIPduy09RxY,4206
+veris_ai/tool_mock.py,sha256=rU_ZwYWYIfgiOojEjmi5BdBsNzP3RphLPmMG1pyYUVw,11954
+veris_ai/utils.py,sha256=hJetCiN8Bubhy0nqSoS1C2awN9cdkKuHM1v7YhtwtTs,10066
+veris_ai/jaeger_interface/README.md,sha256=kd9rKcE5xf3EyNaiHu0tjn-0oES9sfaK6Ih-OhhTyCM,2821
+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.10.0.dist-info/METADATA,sha256=SRkcA5PGLQ5eNcz-yCNuXMECuRypD6olI9fjbFff-qQ,14471
+veris_ai-1.10.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+veris_ai-1.10.0.dist-info/licenses/LICENSE,sha256=2g4i20atAgtD5einaKzhQrIB-JrPhyQgD3bC0wkHcCI,1065
+veris_ai-1.10.0.dist-info/RECORD,,

veris_ai/logging.py

@@ -1,46 +0,0 @@
-"""Logging utilities for VERIS tool calls and responses."""
-
-import json
-import logging
-from typing import Any
-
-from veris_ai.api_client import get_api_client
-
-logger = logging.getLogger(__name__)
-
-
-def log_tool_call(
-    session_id: str,
-    function_name: str,
-    parameters: str,
-    docstring: str,
-) -> None:
-    """Log tool call synchronously to the VERIS logging endpoint."""
-    api_client = get_api_client()
-    endpoint = api_client.get_log_tool_call_endpoint(session_id)
-    payload = {
-        "function_name": function_name,
-        "parameters": json.loads(parameters),
-        "docstring": docstring,
-    }
-    try:
-        api_client.post(endpoint, payload)
-        logger.debug(f"Tool call logged for {function_name}")
-    except Exception as e:
-        logger.warning(f"Failed to log tool call for {function_name}: {e}")
-
-
-def log_tool_response(session_id: str, response: Any) -> None:  # noqa: ANN401
-    """Log tool response synchronously to the VERIS logging endpoint."""
-    api_client = get_api_client()
-    endpoint = api_client.get_log_tool_response_endpoint(session_id)
-
-    payload = {
-        "response": json.dumps(response, default=str),
-    }
-
-    try:
-        api_client.post(endpoint, payload)
-        logger.debug("Tool response logged")
-    except Exception as e:
-        logger.warning(f"Failed to log tool response: {e}")

veris_ai-1.8.2.dist-info/RECORD

@@ -1,17 +0,0 @@
-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/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/observability.py,sha256=fDtWeUexfzaIQArE5YbWsja8Y-bcE_h0dXQWYbXbupY,4929
-veris_ai/tool_mock.py,sha256=L2p6Yg8S98floahDTrf6cnmDqC6Dq3YKA7Q6RRvv7BQ,10253
-veris_ai/utils.py,sha256=Ud4k2jKAJ6-nqSsFXIJWYrOmPGmvl5RSp36cQtgnMpg,9781
-veris_ai/jaeger_interface/README.md,sha256=kd9rKcE5xf3EyNaiHu0tjn-0oES9sfaK6Ih-OhhTyCM,2821
-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,,