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

{veris_ai-1.8.2 → veris_ai-1.10.0}/CLAUDE.md

@@ -6,11 +6,12 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 This is the Veris AI Python SDK - a package that provides simulation capabilities through decorator-based function mocking and FastAPI MCP (Model Context Protocol) integration. The core functionality revolves around:
 - `VerisSDK` class in `src/veris_ai/tool_mock.py:27` - enables environment-aware execution where functions can be mocked in simulation mode, spied on, or executed normally in production
-- Spy mode (`@veris.mock(mode="spy")`) - executes original functions while logging calls and responses to Redis via logging endpoints
+- `@veris.spy()` decorator - executes original functions while logging calls and responses via logging endpoints
 - `convert_to_type()` function in `src/veris_ai/utils.py:5` - handles sophisticated type conversion from mock responses
 - `FastApiMCPParams` model in `src/veris_ai/models.py:1` - provides configuration for integrating FastAPI applications with the Model Context Protocol
 - `set_fastapi_mcp()` method in `src/veris_ai/tool_mock.py:54` - configures FastAPI MCP server with automatic OAuth2-based session management
 - Logging utilities in `src/veris_ai/logging.py` - provide async and sync functions for logging tool calls and responses to VERIS endpoints
+- `SimulatorAPIClient` class in `src/veris_ai/api_client.py` - centralized client for making requests to VERIS simulation endpoints with automatic authentication
 
 ## Development Commands
 
@@ -18,12 +19,18 @@ This project uses `uv` as the package manager and follows modern Python tooling
 
 ### Setup
 ```bash
+# Install base package
+uv add veris-ai
+
 # Install with development dependencies
 uv add "veris-ai[dev]"
 
 # Install with FastAPI MCP integration
 uv add "veris-ai[fastapi]"
 
+# Install with all extras
+uv add "veris-ai[dev,fastapi,observability,agents]"
+
 # Set Python version (requires 3.11+)
 pyenv local 3.11.0
 ```
@@ -75,10 +82,12 @@ uv build
 - Main SDK class that provides decorator functionality:
   - `@veris.mock()`: Dynamic mocking that calls external endpoints for responses
   - `@veris.stub()`: Simple stubbing with fixed return values
-- Environment detection: Uses `ENV` environment variable to determine simulation vs production mode
+  - `@veris.spy()`: Logging decorator that executes original function and logs the call/response
+- Session-based activation: Uses session ID presence to determine mocking behavior
 - HTTP communication with mock endpoints via `httpx` (for mock decorator)
 - Context extraction for session management via context variables
 - Delegates type conversion to the utils module
+- Automatic API endpoint configuration with production defaults
 
 **API Surface** (`src/veris_ai/__init__.py:5`)
 - Exports single `veris` instance for public use
@@ -101,10 +110,18 @@ uv build
 
 ### Environment Configuration
 
-Required environment variables:
-- `VERIS_ENDPOINT_URL`: Base endpoint URL (required)
-- `VERIS_MOCK_TIMEOUT`: Request timeout in seconds (optional, default: 30.0)
-- `ENV`: Set to "simulation" to enable mocking, anything else runs original functions
+Environment variables:
+- `VERIS_API_KEY`: API authentication key for VERIS services (optional, but recommended for production)
+- `VERIS_MOCK_TIMEOUT`: Request timeout in seconds (optional, default: 90.0)
+
+**Note**: The SDK automatically connects to the production VERIS API endpoint (`https://simulation.api.veris.ai/`). Only override `VERIS_API_URL` if you need to use a custom endpoint (rarely needed).
+
+### Session-Based Activation
+
+The SDK activates mocking based on session ID presence:
+- **With session ID**: Routes calls to mock/simulator endpoint
+- **Without session ID**: Executes original function
+- Session IDs can be set manually via `veris.set_session_id()` or extracted automatically from OAuth2 tokens in FastAPI MCP integration
 
 ### Type System
 
@@ -123,8 +140,8 @@ The SDK handles sophisticated type conversion from mock responses:
 
 **Key Test Fixtures**:
 - `mock_context`: Provides mock context with session ID
-- `simulation_env`: Sets up simulation environment variables  
-- `production_env`: Sets up production environment variables
+- `simulation_env`: Sets up simulation mode with session ID  
+- `production_env`: Sets up production mode without session ID
 
 **Test Coverage Areas**:
 - Environment-based behavior switching
@@ -164,9 +181,14 @@ The SDK handles sophisticated type conversion from mock responses:
 ## Key Implementation Details
 
 - **Decorator Pattern**: Functions are wrapped to intercept calls in simulation mode
-  - `mock()`: Sends function metadata to external endpoint for dynamic responses
-  - `stub()`: Returns predetermined values without external calls
+  - `@veris.mock()`: Sends function metadata to external endpoint for dynamic responses
+  - `@veris.stub()`: Returns predetermined values without external calls
+  - `@veris.spy()`: Executes original function while logging calls and responses
 - **Session Management**: Extracts session ID from context for request correlation
+- **API Client**: Centralized `SimulatorAPIClient` handles all API communication
+  - Automatic endpoint configuration with production defaults
+  - Built-in authentication via `VERIS_API_KEY` header
+  - Configurable timeout with `VERIS_MOCK_TIMEOUT`
 - **Error Handling**: Comprehensive HTTP and type conversion error handling
 - **Async Support**: Built with async/await pattern throughout
 - **Type Safety**: Full type hints and runtime type conversion validation

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

@@ -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.8.2 → veris_ai-1.10.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
 
@@ -46,7 +48,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)
@@ -114,32 +115,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`
@@ -212,7 +342,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.10.0}/examples/README.md

@@ -63,9 +63,9 @@ if os.getenv("USE_FASTAPI") == "true":
 **Semantic Tag**: `integration-patterns`
 
 ### Decorator Usage
-- **Function Mocking**: `@veris.mock()` for simulation mode
-- **Spy Mode**: `@veris.spy()` for logging
-- **Stub Mode**: `@veris.stub(return_value={})` for fixed responses
+- **Mock Decorator**: `@veris.mock()` for simulation mode
+- **Spy Decorator**: `@veris.spy()` for logging calls and responses
+- **Stub Decorator**: `@veris.stub(return_value={})` for fixed responses
 
 ### Error Handling
 - **Graceful Import Failures**: Try/catch blocks for optional features
@@ -73,7 +73,8 @@ if os.getenv("USE_FASTAPI") == "true":
 - **Feature Detection**: Runtime capability checking
 
 ### Configuration Management  
-- **Environment Variables**: `VERIS_ENDPOINT_URL`, `ENV=simulation`
+- **Environment Variables**: `VERIS_API_KEY` for authentication, `VERIS_MOCK_TIMEOUT` for request timeout
+- **Session Management**: Use `veris.set_session_id()` to enable mocking
 - **Conditional Setup**: Feature flags for optional components
 - **Service Configuration**: Dynamic service naming and endpoints
 
@@ -86,13 +87,15 @@ if os.getenv("USE_FASTAPI") == "true":
 cd examples/
 python import_options.py
 
-# With specific environment setup
-ENV=simulation VERIS_ENDPOINT_URL=http://localhost:8000 python import_options.py
+# With API key for production
+VERIS_API_KEY=your-api-key python import_options.py
 
 # Testing with different feature flags
 ENABLE_TRACING=true USE_FASTAPI=true python import_options.py
 ```
 
+**Note**: To enable mocking in your code, call `veris.set_session_id("your-session-id")`.
+
 w### Observability Environment (optional)
 
 If you want traces exported while running examples, set the following before execution: