veris-ai 1.3.0__py3-none-any.whl → 1.4.0__py3-none-any.whl

veris_ai/README.md

@@ -0,0 +1,75 @@
+# Veris AI Module Architecture
+
+This module contains the core implementation of the Veris AI Python SDK. Each component focuses on a specific aspect of tool mocking, tracing, and MCP integration.
+
+## Quick Reference
+
+**Purpose**: Core SDK implementation with modular architecture  
+**Entry Point**: [`__init__.py`](__init__.py) handles lazy imports and public API exports  
+**Source of Truth**: Individual module files contain implementation details
+
+## Module Overview
+
+**Semantic Tag**: `core-modules`
+
+| Module | Purpose | Key Classes/Functions | Lines |
+|--------|---------|----------------------|-------|
+| [`tool_mock.py`](tool_mock.py) | Function mocking & FastAPI MCP | `VerisSDK`, `@mock`, `@stub` | 327 |
+| [`braintrust_tracing.py`](braintrust_tracing.py) | Dual tracing instrumentation | `instrument()` | 283 |
+| [`utils.py`](utils.py) | Type utilities & JSON schema | `extract_json_schema()` | 272 |
+| [`logging.py`](logging.py) | Logging configuration | `setup_logging()` | 116 |
+| [`models.py`](models.py) | Data models | Type definitions | 12 |
+| [`jaeger_interface/`](jaeger_interface/) | Jaeger Query API wrapper | `JaegerClient` | See module README |
+
+## Core Workflows
+
+**Semantic Tag**: `implementation-flows`
+
+### 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`
+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`
+2. **Function Execution**: Original function runs normally
+3. **Post-execution Logging**: Response sent to `/api/v2/log_tool_response`
+
+**Implementation**: [`tool_mock.py:250-300`](tool_mock.py)
+
+### Tracing Flow
+1. **Dual Setup**: Braintrust + OpenTelemetry instrumentation  
+2. **Session Tagging**: Bearer tokens → session IDs
+3. **Span Attribution**: All operations tagged with `veris.session_id`
+
+**Implementation**: [`braintrust_tracing.py:50-150`](braintrust_tracing.py)
+
+## Configuration
+
+**Semantic Tag**: `module-config`
+
+Environment variables are processed in [`tool_mock.py`](tool_mock.py):
+
+- `VERIS_ENDPOINT_URL`: Mock server endpoint
+- `VERIS_MOCK_TIMEOUT`: Request timeout (default: 90s)  
+- `ENV`: Set to `"simulation"` for mock mode
+- `VERIS_SERVICE_NAME`: Tracing service identifier
+- `VERIS_OTLP_ENDPOINT`: OpenTelemetry collector endpoint
+
+## Development Notes
+
+**Semantic Tag**: `development-patterns`
+
+- **Lazy Imports**: [`__init__.py`](__init__.py) minimizes startup dependencies
+- **Type Safety**: Extensive use of Pydantic models and type hints
+- **Error Handling**: Comprehensive exception handling with timeouts
+- **Testing**: Module-specific tests in [`../tests/`](../tests/)
+
+**Architecture Principle**: Each module is self-contained with minimal cross-dependencies, enabling selective imports and reduced memory footprint.
+
+---
+
+**Parent Documentation**: See [main README](../../README.md) for installation and usage patterns.

veris_ai/jaeger_interface/README.md

@@ -1,137 +1,101 @@
 # Jaeger Interface
 
-This sub-package ships a **thin synchronous wrapper** around the
-[Jaeger Query Service](https://www.jaegertracing.io/docs/) HTTP API so
-that you can **search for and retrieve traces** directly from Python
-with minimal boilerplate. It also provides **client-side span filtering**
-capabilities for more granular control over the returned data.
+Typed Python wrapper for the Jaeger Query Service HTTP API with client-side span filtering capabilities.
 
-> The client relies on `requests` (already included in the SDK's
-> dependencies) and uses *pydantic* for full type-safety.
+## Quick Reference
 
----
+**Purpose**: Search and retrieve traces from Jaeger with minimal boilerplate  
+**Core Component**: [`JaegerClient`](client.py) class with `search()` and `get_trace()` methods  
+**Dependencies**: Uses `requests` and `pydantic` (included in base SDK)  
+**Compatibility**: Jaeger v1.x REST endpoints, OpenSearch storage backends
 
 ## Installation
 
-`veris-ai` already lists both `requests` and `pydantic` as hard
-requirements, so **no additional dependencies are required**.
+**Semantic Tag**: `jaeger-setup`
 
+No additional dependencies required - included with base `veris-ai` package:
 ```bash
 pip install veris-ai
 ```
 
 ---
 
-## Quick-start
+## Basic Usage
+
+**Semantic Tag**: `jaeger-client-usage`
 
 ```python
 from veris_ai.jaeger_interface import JaegerClient
-import json
-from veris_ai.jaeger_interface.models import Trace
-# Replace with the URL of your Jaeger Query Service instance
+
 client = JaegerClient("http://localhost:16686")
 
-# --- 1. Search traces --------------------------------------------------
-resp = client.search(
+# Search traces with filtering
+traces = client.search(
     service="veris-agent",
     limit=10,
-    # operation="CustomSpanData",
-    tags={"veris.session_id":"088b5aaf-84bd-4768-9a62-5e981222a9f2"},
-    span_tags={"bt.metadata.model":"gpt-4.1-2025-04-14"}
+    tags={"veris.session_id": "session-123"},
+    span_tags={"http.status_code": 500}
 )
 
-# save to json
-with open("resp.json", "w") as f:
-    f.write(resp.model_dump_json(indent=2))
-
-# Guard clause
-if not resp or not resp.data:
-    print("No data found")
-    exit(1)
-
-# Print trace ids
-for trace in resp.data:
-    if isinstance(trace, Trace):
-        print("TRACE ID:", trace.traceID, len(trace.spans), "spans")
-
-# --- 2. Retrieve a specific trace -------------------------------------
-if isinstance(resp.data, list):
-    trace_id = resp.data[0].traceID
-else:
-    trace_id = resp.data.traceID
-
-detailed = client.get_trace(trace_id)
-# save detailed to json
-with open("detailed.json", "w") as f:
-    f.write(detailed.model_dump_json(indent=2))
+# Retrieve specific trace
+if traces.data:
+    detailed = client.get_trace(traces.data[0].traceID)
 ```
 
+**Data Models**: See [`models.py`](models.py) for `Trace`, `Span`, and response type definitions.
+
 ---
 
 ## API Reference
 
-### `JaegerClient`
-
-| Method | Description |
-| -------- | ----------- |
-| `search(service, *, limit=None, tags=None, operation=None, span_tags=None, **kwargs) -> SearchResponse` | Search for traces with optional span-level filtering. |
-| `get_trace(trace_id: str) -> GetTraceResponse` | Fetch a single trace by ID (wrapper around `/api/traces/{id}`). |
-
-### `search()` Parameters
-
-The `search()` method now uses a flattened parameter structure:
+**Semantic Tag**: `jaeger-api-methods`
 
-| Parameter | Type | Description |
-| --------- | ---- | ----------- |
-| `service` | `str` | Service name to search for. Optional - if not provided, searches across all services. |
-| `limit` | `int` | Maximum number of traces to return. |
-| `tags` | `Dict[str, Any]` | Trace-level tag filters (AND logic). A trace must have a span matching ALL tags. |
-| `operation` | `str` | Filter by operation name. |
-| `span_tags` | `Dict[str, Any]` | Span-level tag filters (OR logic). Returns only spans matching ANY of these tags. | 
-| `span_operations` | `List[str]` | Span-level operation name filters (OR logic). Returns only spans matching ANY of these operations. |
-| `**kwargs` | `Any` | Additional parameters passed directly to Jaeger API. |
+### Core Methods
 
-### Filter Logic
+| Method | Purpose | Returns |
+|--------|---------|---------|
+| `search(service, **filters)` | Search traces with optional filtering | `SearchResponse` |
+| `get_trace(trace_id)` | Retrieve single trace by ID | `GetTraceResponse` |
 
-The interface provides two levels of filtering:
+**Implementation**: See [`client.py`](client.py) for method signatures and error handling.
 
-1. **Trace-level filtering** (`tags` parameter):
-   - Sent directly to Jaeger API
-   - Uses AND logic: all tag key-value pairs must match on a single span
-   - Efficient server-side filtering
+### Filtering Strategy
 
-2. **Span-level filtering** (`span_tags` parameter):
-   - Applied client-side after retrieving traces
-   - Uses OR logic: spans matching ANY of the provided tags are included
-   - Traces with no matching spans are excluded from results
-   - Useful for finding spans with specific characteristics across different traces
-
-### Example: Combining Filters
+**Semantic Tag**: `filtering-logic`
 
 ```python
-# Find traces in service that have errors, then filter to show only 
-# spans with specific HTTP status codes or database errors
+# Server-side filtering (efficient)
+traces = client.search(
+    service="my-service",
+    tags={"error": "true"},  # AND logic: trace must match ALL tags
+    operation="specific_op"
+)
+
+# Client-side filtering (granular)  
 traces = client.search(
-    service="my-api",
-    tags={"error": "true"},  # Trace must contain an error
-    span_tags={
-        "http.status_code": 500,
-        "http.status_code": 503,
-        "db.error": "connection_timeout"
-    }  # Show only spans with these specific errors
+    service="my-service",
+    span_tags={"http.status_code": [500, 503]},  # OR logic: ANY span match
+    span_operations=["db_query", "api_call"]
 )
 ```
 
+**Filter Types**:
+- **`tags`**: Trace-level filters (server-side, AND logic)
+- **`span_tags`**: Span-level filters (client-side, OR logic)  
+- **`span_operations`**: Operation name filters (client-side, OR logic)
+
 ---
 
-## Compatibility
+## Architecture
 
-The implementation targets **Jaeger v1.x** REST endpoints. For clusters
-backed by **OpenSearch** storage the same endpoints apply. Should you
-need API v3 support feel free to open an issue or contribution—thanks!
+**Semantic Tag**: `jaeger-architecture`
 
----
+- **Client Implementation**: [`client.py`](client.py) - HTTP requests to Jaeger API
+- **Data Models**: [`models.py`](models.py) - Pydantic models for type safety  
+- **Compatibility**: Jaeger v1.x REST endpoints, OpenSearch backends
 
-## License
+**Design Principle**: Thin wrapper maintaining Jaeger's native API structure while adding client-side span filtering capabilities.
+
+---
 
-This package is released under the **MIT license**.
+**Parent Documentation**: See [module README](../README.md) for integration with other SDK components.

veris_ai/logging.py

@@ -0,0 +1,116 @@
+"""Logging utilities for VERIS tool calls and responses."""
+
+import json
+import logging
+import os
+from typing import Any
+
+import httpx
+
+logger = logging.getLogger(__name__)
+
+
+async def log_tool_call_async(
+    session_id: str,
+    function_name: str,
+    parameters: dict[str, Any],
+    docstring: str,
+) -> None:
+    """Log tool call asynchronously to the VERIS logging endpoint."""
+    base_url = os.getenv("VERIS_ENDPOINT_URL")
+    if not base_url:
+        logger.warning("VERIS_ENDPOINT_URL not set, skipping tool call logging")
+        return
+
+    endpoint = f"{base_url}/api/v2/simulations/{session_id}/log_tool_call"
+    payload = {
+        "function_name": function_name,
+        "parameters": parameters,
+        "docstring": docstring,
+    }
+
+    timeout = float(os.getenv("VERIS_MOCK_TIMEOUT", "90.0"))
+
+    try:
+        async with httpx.AsyncClient(timeout=timeout) as client:
+            response = await client.post(endpoint, json=payload)
+            response.raise_for_status()
+            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_call_sync(
+    session_id: str,
+    function_name: str,
+    parameters: dict[str, Any],
+    docstring: str,
+) -> None:
+    """Log tool call synchronously to the VERIS logging endpoint."""
+    base_url = os.getenv("VERIS_ENDPOINT_URL")
+    if not base_url:
+        logger.warning("VERIS_ENDPOINT_URL not set, skipping tool call logging")
+        return
+
+    endpoint = f"{base_url}/api/v2/simulations/{session_id}/log_tool_call"
+    payload = {
+        "function_name": function_name,
+        "parameters": parameters,
+        "docstring": docstring,
+    }
+
+    timeout = float(os.getenv("VERIS_MOCK_TIMEOUT", "90.0"))
+
+    try:
+        with httpx.Client(timeout=timeout) as client:
+            response = client.post(endpoint, json=payload)
+            response.raise_for_status()
+            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}")
+
+
+async def log_tool_response_async(session_id: str, response: object) -> None:
+    """Log tool response asynchronously to the VERIS logging endpoint."""
+    base_url = os.getenv("VERIS_ENDPOINT_URL")
+    if not base_url:
+        logger.warning("VERIS_ENDPOINT_URL not set, skipping tool response logging")
+        return
+
+    endpoint = f"{base_url}/api/v2/simulations/{session_id}/log_tool_response"
+    payload = {
+        "response": json.dumps(response, default=str),
+    }
+
+    timeout = float(os.getenv("VERIS_MOCK_TIMEOUT", "90.0"))
+
+    try:
+        async with httpx.AsyncClient(timeout=timeout) as client:
+            http_response = await client.post(endpoint, json=payload)
+            http_response.raise_for_status()
+            logger.debug("Tool response logged")
+    except Exception as e:
+        logger.warning(f"Failed to log tool response: {e}")
+
+
+def log_tool_response_sync(session_id: str, response: object) -> None:
+    """Log tool response synchronously to the VERIS logging endpoint."""
+    base_url = os.getenv("VERIS_ENDPOINT_URL")
+    if not base_url:
+        logger.warning("VERIS_ENDPOINT_URL not set, skipping tool response logging")
+        return
+
+    endpoint = f"{base_url}/api/v2/simulations/{session_id}/log_tool_response"
+    payload = {
+        "response": json.dumps(response, default=str),
+    }
+
+    timeout = float(os.getenv("VERIS_MOCK_TIMEOUT", "90.0"))
+
+    try:
+        with httpx.Client(timeout=timeout) as client:
+            http_response = client.post(endpoint, json=payload)
+            http_response.raise_for_status()
+            logger.debug("Tool response logged")
+    except Exception as e:
+        logger.warning(f"Failed to log tool response: {e}")

veris_ai/tool_mock.py

@@ -15,6 +15,12 @@ from typing import (
 
 import httpx
 
+from veris_ai.logging import (
+    log_tool_call_async,
+    log_tool_call_sync,
+    log_tool_response_async,
+    log_tool_response_sync,
+)
 from veris_ai.models import ResponseExpectation
 from veris_ai.utils import convert_to_type, extract_json_schema
 
@@ -94,7 +100,7 @@ class VerisSDK:
 
     def mock(  # noqa: C901, PLR0915
         self,
-        mode: Literal["tool", "function"] = "tool",
+        mode: Literal["tool", "function", "spy"] = "tool",
         expects_response: bool | None = None,
         cache_response: bool | None = None,
     ) -> Callable:
@@ -165,10 +171,40 @@ class VerisSDK:
                 if not self.session_id:
                     # If not in simulation mode, execute the original function
                     return await func(*args, **kwargs)
-                endpoint = os.getenv("VERIS_MOCK_ENDPOINT_URL")
-                if not endpoint:
-                    error_msg = "VERIS_MOCK_ENDPOINT_URL environment variable is not set"
+
+                # Handle spy mode - execute original function and log
+                if mode == "spy":
+                    logger.info(f"Spying on function: {func.__name__}")
+
+                    # Log the tool call
+                    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)
+
+                    await log_tool_call_async(
+                        session_id=self.session_id,
+                        function_name=func.__name__,
+                        parameters=bound_args.arguments,
+                        docstring=inspect.getdoc(func) or "",
+                    )
+
+                    # Execute the original function
+                    result = await func(*args, **kwargs)
+
+                    # Log the response
+                    await log_tool_response_async(session_id=self.session_id, response=result)
+
+                    return result
+
+                # Regular mock mode
+                base_url = os.getenv("VERIS_ENDPOINT_URL")
+                if not base_url:
+                    error_msg = "VERIS_ENDPOINT_URL environment variable is not set"
                     raise ValueError(error_msg)
+                endpoint = f"{base_url.rstrip('/')}/api/v2/tool_mock"
                 # Default timeout of 30 seconds
                 timeout = float(os.getenv("VERIS_MOCK_TIMEOUT", "90.0"))
 
@@ -197,10 +233,40 @@ class VerisSDK:
                 if not self.session_id:
                     # If not in simulation mode, execute the original function
                     return func(*args, **kwargs)
-                endpoint = os.getenv("VERIS_MOCK_ENDPOINT_URL")
-                if not endpoint:
-                    error_msg = "VERIS_MOCK_ENDPOINT_URL environment variable is not set"
+
+                # Handle spy mode - execute original function and log
+                if mode == "spy":
+                    logger.info(f"Spying on function: {func.__name__}")
+
+                    # Log the tool call
+                    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)
+
+                    log_tool_call_sync(
+                        session_id=self.session_id,
+                        function_name=func.__name__,
+                        parameters=bound_args.arguments,
+                        docstring=inspect.getdoc(func) or "",
+                    )
+
+                    # Execute the original function
+                    result = func(*args, **kwargs)
+
+                    # Log the response
+                    log_tool_response_sync(session_id=self.session_id, response=result)
+
+                    return result
+
+                # Regular mock mode
+                base_url = os.getenv("VERIS_ENDPOINT_URL")
+                if not base_url:
+                    error_msg = "VERIS_ENDPOINT_URL environment variable is not set"
                     raise ValueError(error_msg)
+                endpoint = f"{base_url.rstrip('/')}/api/v2/tool_mock"
                 # Default timeout of 30 seconds
                 timeout = float(os.getenv("VERIS_MOCK_TIMEOUT", "90.0"))
 
@@ -240,7 +306,7 @@ class VerisSDK:
                 if not self.session_id:
                     # If not in simulation mode, execute the original function
                     return await func(*args, **kwargs)
-                logger.info(f"Simulating function: {func.__name__}")
+                logger.info(f"Stubbing function: {func.__name__}")
                 return return_value
 
             @wraps(func)
@@ -248,7 +314,7 @@ class VerisSDK:
                 if not self.session_id:
                     # If not in simulation mode, execute the original function
                     return func(*args, **kwargs)
-                logger.info(f"Simulating function: {func.__name__}")
+                logger.info(f"Stubbing function: {func.__name__}")
                 return return_value
 
             # Return the appropriate wrapper based on whether the function is async

veris_ai/utils.py

@@ -74,6 +74,9 @@ def _convert_simple_type(value: object, target_type: type) -> object:
         with suppress(TypeError):
             return target_type(**value)
 
+    if target_type is types.NoneType:
+        return None
+
     return target_type(value)
 
 

veris_ai-1.4.0.dist-info/METADATA

@@ -0,0 +1,223 @@
+Metadata-Version: 2.4
+Name: veris-ai
+Version: 1.4.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
+Author-email: Mehdi Jamei <mehdi@veris.ai>
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.24.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: requests>=2.31.0
+Provides-Extra: dev
+Requires-Dist: black>=23.7.0; extra == 'dev'
+Requires-Dist: mypy>=1.5.1; extra == 'dev'
+Requires-Dist: openai-agents>=0.0.1; extra == 'dev'
+Requires-Dist: pre-commit>=3.3.3; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21.1; extra == 'dev'
+Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
+Requires-Dist: pytest>=7.4.0; extra == 'dev'
+Requires-Dist: ruff>=0.11.4; extra == 'dev'
+Provides-Extra: fastapi
+Requires-Dist: fastapi; extra == 'fastapi'
+Requires-Dist: fastapi-mcp; extra == 'fastapi'
+Provides-Extra: instrument
+Requires-Dist: braintrust; extra == 'instrument'
+Requires-Dist: opentelemetry-api; extra == 'instrument'
+Requires-Dist: opentelemetry-exporter-otlp; extra == 'instrument'
+Requires-Dist: opentelemetry-exporter-otlp-proto-common; extra == 'instrument'
+Requires-Dist: opentelemetry-exporter-otlp-proto-grpc; extra == 'instrument'
+Requires-Dist: opentelemetry-exporter-otlp-proto-http; extra == 'instrument'
+Requires-Dist: opentelemetry-sdk; extra == 'instrument'
+Requires-Dist: wrapt; extra == 'instrument'
+Description-Content-Type: text/markdown
+
+# Veris AI Python SDK
+
+A Python package for Veris AI tools with simulation capabilities and FastAPI MCP (Model Context Protocol) integration.
+
+## Quick Reference
+
+**Purpose**: Tool mocking, tracing, and FastAPI MCP integration for AI agent development  
+**Core Components**: [`tool_mock`](#function-mocking) • [`jaeger_interface`](#jaeger-trace-interface) • [`braintrust_tracing`](#tracing-integration) • [`fastapi_mcp`](#fastapi-mcp-integration)  
+**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
+
+## Installation
+
+```bash
+# Base package
+uv add veris-ai
+
+# With optional extras
+uv add "veris-ai[dev,fastapi,instrument]"
+```
+
+**Installation Profiles**:
+- `dev`: Development tools (ruff, pytest, mypy) 
+- `fastapi`: FastAPI MCP integration
+- `instrument`: Braintrust/OpenTelemetry tracing
+
+## Import Patterns
+
+**Semantic Tag**: `import-patterns`
+
+```python
+# Core imports (base dependencies only)
+from veris_ai import veris, JaegerClient
+
+# Optional features (require extras)
+from veris_ai import braintrust_tracing  # Requires [instrument]
+```
+
+**Complete Import Strategies**: See [`examples/README.md`](examples/README.md) for five different import approaches, conditional features, and integration patterns.
+
+## Configuration
+
+**Semantic Tag**: `environment-config`
+
+| Variable | Purpose | Default |
+|----------|---------|---------|
+| `VERIS_ENDPOINT_URL` | Mock server endpoint | *Required* |
+| `VERIS_MOCK_TIMEOUT` | Request timeout (seconds) | `90.0` |
+| `ENV` | Set to `"simulation"` for mock mode | Production |
+| `VERIS_SERVICE_NAME` | Tracing service name | Auto-detected |
+| `VERIS_OTLP_ENDPOINT` | OpenTelemetry collector | *Required for tracing* |
+
+**Configuration Details**: See [`src/veris_ai/tool_mock.py`](src/veris_ai/tool_mock.py) for environment handling logic.
+
+## Tracing Integration
+
+**Semantic Tag**: `distributed-tracing`
+
+Parallel tracing to Braintrust and Jaeger/OpenTelemetry for monitoring and evaluation.
+
+```python
+from veris_ai import braintrust_tracing
+
+# Enable dual tracing
+braintrust_tracing.instrument(service_name="my-service", otlp_endpoint="http://localhost:4317")
+```
+
+**Session Management**: Automatic session ID extraction from bearer tokens. Manual session control via `veris.set_session_id()` and `veris.clear_session_id()`.
+
+**Implementation Details**: See [`src/veris_ai/braintrust_tracing.py`](src/veris_ai/braintrust_tracing.py) for instrumentation logic.
+
+## Function Mocking
+
+**Semantic Tag**: `tool-mocking`
+
+### Core Decorators
+
+```python
+from veris_ai import veris
+
+# Mock mode: Returns simulated responses in ENV=simulation
+@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
+@veris.mock(mode="spy")
+async def monitored_function(data: str) -> dict:
+    return process_data(data)
+
+# Stub mode: 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.
+
+**Implementation**: See [`src/veris_ai/tool_mock.py`](src/veris_ai/tool_mock.py) for decorator logic and API integration.
+
+## FastAPI MCP Integration
+
+**Semantic Tag**: `fastapi-mcp`
+
+Expose FastAPI endpoints as MCP tools for AI agent consumption.
+
+```python
+from fastapi import FastAPI
+from veris_ai import veris
+
+app = FastAPI()
+
+# Enable MCP integration
+veris.set_fastapi_mcp(
+    fastapi=app,
+    name="My API Server",
+    include_operations=["get_users", "create_user"],
+    exclude_tags=["internal"]
+)
+```
+
+**Key Features**:
+- **Automatic schema conversion**: FastAPI OpenAPI → MCP tool definitions
+- **Session management**: Bearer token → session ID mapping
+- **Filtering**: Include/exclude operations and tags
+- **Authentication**: OAuth2 integration
+
+**Configuration Reference**: See function signature in [`src/veris_ai/tool_mock.py`](src/veris_ai/tool_mock.py) for all `set_fastapi_mcp()` parameters.
+
+## Utility Functions
+
+**Semantic Tag**: `json-schema-utils`
+
+```python
+from veris_ai.utils import extract_json_schema
+
+# Schema extraction from types
+user_schema = extract_json_schema(User)  # Pydantic models
+list_schema = extract_json_schema(List[str])  # Generics
+```
+
+**Supported Types**: Built-in types, generics (List, Dict, Union), Pydantic models, TypedDict, forward references.
+
+**Implementation**: See [`src/veris_ai/utils.py`](src/veris_ai/utils.py) for type conversion logic.
+
+## Development
+
+**Semantic Tag**: `development-setup`
+
+**Requirements**: Python 3.11+, `uv` package manager
+
+```bash
+# Install with dev dependencies
+uv add "veris-ai[dev]"
+
+# Quality checks
+ruff check --fix .    # Lint and format
+pytest --cov=veris_ai # Test with coverage
+```
+
+**Testing & Architecture**: See [`tests/README.md`](tests/README.md) for test structure, fixtures, and coverage strategies. See [`src/veris_ai/README.md`](src/veris_ai/README.md) for module architecture and implementation flows.
+
+## Module Architecture
+
+**Semantic Tag**: `module-architecture`
+
+**Core Modules**: `tool_mock` (mocking), `jaeger_interface` (trace queries), `braintrust_tracing` (dual tracing), `utils` (schema conversion)
+
+**Complete Architecture**: See [`src/veris_ai/README.md`](src/veris_ai/README.md) for module overview, implementation flows, and configuration details. 
+
+## Jaeger Trace Interface
+
+**Semantic Tag**: `jaeger-query-api`
+
+```python
+from veris_ai.jaeger_interface import JaegerClient
+
+client = JaegerClient("http://localhost:16686")
+traces = client.search(service="veris-agent", tags={"error": "true"})
+```
+
+**Complete Guide**: See [`src/veris_ai/jaeger_interface/README.md`](src/veris_ai/jaeger_interface/README.md) for API reference, filtering strategies, and architecture details.
+
+---
+
+**License**: MIT License - see [LICENSE](LICENSE) file for details. 

veris_ai-1.4.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+veris_ai/README.md,sha256=q0Qn6gu85HWU189SmyOygY_mkNj0l10wlAVy9kj4udo,3120
+veris_ai/__init__.py,sha256=Vp5yf9ZRchw0mmPwrRuNebI5cb2NGwpJGfr41l86q1U,1177
+veris_ai/braintrust_tracing.py,sha256=0i-HR6IuK3-Q5ujMjT1FojxESRZLgqEvJ44bfJfDHaw,11938
+veris_ai/logging.py,sha256=2855E8s_k6yTnzFK10EQR4WQngQk3VuWFPJW-MYiw3k,3837
+veris_ai/models.py,sha256=6HINPxNFCakCVPcyEbUswWkXwb2K4lF0A8g8EvTMal4,213
+veris_ai/tool_mock.py,sha256=9rb4c8OZEg6hGmyJlmgFSmbBDa7L6_XzadvtVrGy9xs,13198
+veris_ai/utils.py,sha256=aqFFNuNiBehil6874nOHtU7G_bWHbFpVuubcz2AIx6I,9267
+veris_ai/jaeger_interface/README.md,sha256=kd9rKcE5xf3EyNaiHu0tjn-0oES9sfaK6Ih-OhhTyCM,2821
+veris_ai/jaeger_interface/__init__.py,sha256=d873a0zq3eUYU2Y77MtdjCwIARjAsAP7WDqGXDMWpYs,1158
+veris_ai/jaeger_interface/client.py,sha256=yJrh86wRR0Dk3Gq12DId99WogcMIVbL0QQFqVSevvlE,8772
+veris_ai/jaeger_interface/models.py,sha256=e64VV6IvOEFuzRUgvDAMQFyOZMRb56I-PUPZLBZ3rX0,1864
+veris_ai-1.4.0.dist-info/METADATA,sha256=yq1IbvlQ7qME6BdFz3tQ9-b0x9Oblcu2OJNUGS3iNVE,7702
+veris_ai-1.4.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+veris_ai-1.4.0.dist-info/licenses/LICENSE,sha256=2g4i20atAgtD5einaKzhQrIB-JrPhyQgD3bC0wkHcCI,1065
+veris_ai-1.4.0.dist-info/RECORD,,

veris_ai-1.3.0.dist-info/METADATA

@@ -1,457 +0,0 @@
-Metadata-Version: 2.4
-Name: veris-ai
-Version: 1.3.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
-Author-email: Mehdi Jamei <mehdi@veris.ai>
-License-Expression: MIT
-License-File: LICENSE
-Requires-Python: >=3.11
-Requires-Dist: httpx>=0.24.0
-Requires-Dist: pydantic>=2.0.0
-Requires-Dist: requests>=2.31.0
-Provides-Extra: dev
-Requires-Dist: black>=23.7.0; extra == 'dev'
-Requires-Dist: mypy>=1.5.1; extra == 'dev'
-Requires-Dist: openai-agents>=0.0.1; extra == 'dev'
-Requires-Dist: pre-commit>=3.3.3; extra == 'dev'
-Requires-Dist: pytest-asyncio>=0.21.1; extra == 'dev'
-Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
-Requires-Dist: pytest>=7.4.0; extra == 'dev'
-Requires-Dist: ruff>=0.11.4; extra == 'dev'
-Provides-Extra: fastapi
-Requires-Dist: fastapi; extra == 'fastapi'
-Requires-Dist: fastapi-mcp; extra == 'fastapi'
-Provides-Extra: instrument
-Requires-Dist: braintrust; extra == 'instrument'
-Requires-Dist: opentelemetry-api; extra == 'instrument'
-Requires-Dist: opentelemetry-exporter-otlp; extra == 'instrument'
-Requires-Dist: opentelemetry-exporter-otlp-proto-common; extra == 'instrument'
-Requires-Dist: opentelemetry-exporter-otlp-proto-grpc; extra == 'instrument'
-Requires-Dist: opentelemetry-exporter-otlp-proto-http; extra == 'instrument'
-Requires-Dist: opentelemetry-sdk; extra == 'instrument'
-Requires-Dist: wrapt; extra == 'instrument'
-Description-Content-Type: text/markdown
-
-# Veris AI Python SDK
-
-A Python package for Veris AI tools with simulation capabilities and FastAPI MCP (Model Context Protocol) integration.
-
-## Installation
-
-You can install the package using `uv`:
-
-```bash
-# Install the 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 tracing/instrumentation support
-uv add "veris-ai[instrument]"
-```
-
-## Import Options
-
-The SDK supports flexible import patterns to minimize dependencies:
-
-### Default Imports (Base Dependencies Only)
-
-```python
-# These imports only require base dependencies (httpx, pydantic, requests)
-from veris_ai import veris, JaegerClient
-```
-
-### Optional Imports (Require Extra Dependencies)
-
-```python
-# The instrument function requires the 'instrument' extra
-# Install with: pip install veris-ai[instrument] or uv add "veris-ai[instrument]"
-from veris_ai import instrument  # Lazy-loaded, will error if deps missing
-```
-
-### Direct Submodule Imports
-
-For maximum control over dependencies, you can import directly from submodules:
-
-```python
-# Import only what you need
-from veris_ai.tool_mock import veris
-from veris_ai.jaeger_interface import JaegerClient
-from veris_ai.braintrust_tracing import instrument  # Requires [instrument] extra
-```
-
-## Environment Setup
-
-The package requires the following environment variables:
-
-```bash
-# Required: URL for the mock endpoint
-VERIS_MOCK_ENDPOINT_URL=http://your-mock-endpoint.com
-
-# Optional: Timeout in seconds (default: 30.0)
-VERIS_MOCK_TIMEOUT=30.0
-
-# Optional: Set to "simulation" to enable mock mode
-ENV=simulation
-```
-
-## Tracing Integration
-
-The SDK provides seamless integration with Braintrust and Jaeger/OpenTelemetry for distributed tracing.
-
-### Setting up Tracing
-
-```python
-from veris_ai import instrument
-
-# Initialize tracing instrumentation
-instrument(
-    service_name="my-service",  # or via VERIS_SERVICE_NAME env var
-    otlp_endpoint="http://localhost:4317"  # or via VERIS_OTLP_ENDPOINT env var
-)
-```
-
-### Session ID Tracking
-
-When using the SDK with FastAPI MCP integration, session IDs are automatically embedded in all traces:
-
-1. **Automatic Session Extraction**: When a request includes an Authorization header with a bearer token, the token is automatically used as the session ID.
-
-2. **Trace Attribution**: All spans created during a request will include the `veris.session_id` attribute, allowing you to:
-   - Filter traces by session in Jaeger
-   - Correlate all operations within a single user session
-   - Debug issues specific to a particular session
-
-3. **Example**:
-   ```python
-   # FastAPI app with MCP integration
-   from fastapi import FastAPI
-   from veris_ai import veris, instrument
-   
-   app = FastAPI()
-   
-   # Set up tracing
-   instrument()
-   
-   # Set up FastAPI MCP with session handling
-   veris.set_fastapi_mcp(
-       fastapi=app,
-       name="My API Server"
-   )
-   
-   # Now all traces will automatically include session IDs from bearer tokens
-   ```
-
-4. **Manual Session Management**: You can also manually set session IDs:
-   ```python
-   veris.set_session_id("custom-session-123")
-   # All subsequent operations will be tagged with this session ID
-   veris.clear_session_id()  # Clear when done
-   ```
-
-The session ID tracking works seamlessly with both the mock decorators and the tracing system, providing end-to-end visibility of user sessions across your application.
-
-## Python Version
-
-This project requires Python 3.11 or higher. We use [pyenv](https://github.com/pyenv/pyenv) for Python version management.
-
-To set up the correct Python version:
-
-```bash
-# Install Python 3.11.0 using pyenv
-pyenv install 3.11.0
-
-# Set the local Python version for this project
-pyenv local 3.11.0
-```
-
-## Usage
-
-```python
-from veris_ai import veris
-
-@veris.mock()
-async def your_function(param1: str, param2: int) -> dict:
-    """
-    Your function documentation here.
-    
-    Args:
-        param1: Description of param1
-        param2: Description of param2
-        
-    Returns:
-        A dictionary containing the results
-    """
-    # Your implementation here
-    return {"result": "actual implementation"}
-```
-
-When `ENV=simulation` is set, the decorator will:
-1. Capture the function signature, type hints, and docstring
-2. Send this information to the mock endpoint
-3. Convert the mock response to the expected return type
-4. Return the mock result
-
-When not in simulation mode, the original function will be executed normally.
-
-### Stub Decorator
-
-For simple test scenarios where you want to return a fixed value in simulation mode, use the `@veris.stub()` decorator:
-
-```python
-from veris_ai import veris
-
-@veris.stub(return_value={"status": "success", "data": [1, 2, 3]})
-async def get_data() -> dict:
-    """Get some data from external service."""
-    # This implementation is only called in production mode
-    return await fetch_from_api()
-
-# In simulation mode: always returns {"status": "success", "data": [1, 2, 3]}
-# In production mode: calls fetch_from_api()
-```
-
-The stub decorator is useful for:
-- Quick prototyping with fixed responses
-- Testing with predictable data
-- Bypassing external dependencies in development
-
-## FastAPI MCP Integration
-
-The SDK provides integration with FastAPI applications through the Model Context Protocol (MCP). This allows your FastAPI endpoints to be exposed as MCP tools that can be used by AI agents.
-
-```python
-from fastapi import FastAPI
-from veris_ai import veris
-
-app = FastAPI()
-
-# Set up FastAPI MCP with automatic session handling
-veris.set_fastapi_mcp(
-    fastapi=app,
-    name="My API Server",
-    description="My FastAPI application exposed as MCP tools",
-    describe_all_responses=True,
-    include_operations=["get_users", "create_user"],
-    exclude_tags=["internal"]
-)
-
-# The MCP server is now available at veris.fastapi_mcp
-mcp_server = veris.fastapi_mcp
-```
-
-### Configuration Options
-
-The `set_fastapi_mcp()` method accepts the following parameters:
-
-- **fastapi** (required): Your FastAPI application instance
-- **name**: Custom name for the MCP server (defaults to app.title)
-- **description**: Custom description (defaults to app.description)
-- **describe_all_responses**: Whether to include all response schemas in tool descriptions
-- **describe_full_response_schema**: Whether to include full JSON schema for responses
-- **http_client**: Optional custom httpx.AsyncClient instance
-- **include_operations**: List of operation IDs to include as MCP tools
-- **exclude_operations**: List of operation IDs to exclude (can't use with include_operations)
-- **include_tags**: List of tags to include as MCP tools
-- **exclude_tags**: List of tags to exclude (can't use with include_tags)
-- **auth_config**: Optional FastAPI MCP AuthConfig for custom authentication
-
-### Session Management
-
-The SDK automatically handles session management through OAuth2 authentication:
-- Session IDs are extracted from bearer tokens
-- Context is maintained across API calls
-- Sessions can be managed programmatically:
-
-```python
-# Get current session ID
-session_id = veris.session_id
-
-# Set a new session ID
-veris.set_session_id("new-session-123")
-
-# Clear the session
-veris.clear_session_id()
-```
-
-## Braintrust & Jaeger Tracing
-
-The SDK includes a non-invasive instrumentation helper for sending traces to both Braintrust and a Jaeger-compatible OpenTelemetry (OTEL) collector simultaneously. This allows you to leverage Braintrust's powerful monitoring and evaluation tools while also storing and visualizing traces in your own Jaeger instance.
-
-### Usage
-
-To enable parallel tracing, simply import the `braintrust_tracing` module and call the `instrument()` function at the beginning of your application's lifecycle.
-
-```python
-from veris_ai import braintrust_tracing
-
-# Enable Braintrust and Jaeger tracing
-braintrust_tracing.instrument()
-```
-
-### Configuration
-
-The `instrument()` function is configured through environment variables:
-
--   **`VERIS_SERVICE_NAME`** (required): The name of your service as it will appear in Jaeger.
--   **`VERIS_OTLP_ENDPOINT`** (required): The gRPC endpoint of your Jaeger OTLP collector (e.g., `http://host.docker.internal:4317`).
-
-When initialized, the SDK automatically patches the `agents` library to send traces to both systems without any further code changes required.
-
-## Utility Functions
-
-### extract_json_schema
-
-The SDK provides a utility function to extract JSON schemas from Python types and Pydantic models:
-
-```python
-from veris_ai.utils import extract_json_schema
-from pydantic import BaseModel
-from typing import List, Optional
-
-# Extract schema from built-in types
-int_schema = extract_json_schema(int)
-# {"type": "integer"}
-
-list_schema = extract_json_schema(List[str])
-# {"type": "array", "items": {"type": "string"}}
-
-# Extract schema from Pydantic models
-class User(BaseModel):
-    name: str
-    age: int
-    email: Optional[str] = None
-
-user_schema = extract_json_schema(User)
-# Returns full JSON schema with properties, required fields, etc.
-
-# Extract schema from TypedDict
-from typing import TypedDict
-
-class Config(TypedDict):
-    host: str
-    port: int
-    debug: bool
-
-config_schema = extract_json_schema(Config)
-# {"type": "object", "properties": {...}, "required": ["host", "port", "debug"]}
-```
-
-This function supports:
-- Built-in types (str, int, float, bool, None)
-- Generic types (List, Dict, Union, Optional, Literal)
-- Pydantic models
-- TypedDict classes
-- Forward references and complex nested types
-
-## Project Structure
-
-```
-src/veris_ai/
-├── __init__.py        # Main entry point, exports the veris instance
-├── tool_mock.py       # VerisSDK class with @veris.mock() decorator
-└── utils.py           # Type conversion and JSON schema utilities
-
-tests/
-├── conftest.py        # Pytest fixtures
-├── test_tool_mock.py  # Tests for VerisSDK functionality
-└── test_utils.py      # Tests for type conversion and schema extraction
-```
-
-## Development
-
-This project uses `pyproject.toml` for dependency management and `uv` for package installation.
-
-### Development Dependencies
-
-To install the package with development dependencies:
-
-```bash
-uv add "veris-ai[dev]"
-```
-
-This will install the following development tools:
-- **Ruff**: Fast Python linter
-- **pytest**: Testing framework
-- **pytest-asyncio**: Async support for pytest
-- **pytest-cov**: Coverage reporting for pytest
-- **black**: Code formatter
-- **mypy**: Static type checker
-- **pre-commit**: Git hooks for code quality
-
-### Code Quality
-
-This project uses [Ruff](https://github.com/charliermarsh/ruff) for linting and code quality checks. Ruff is a fast Python linter written in Rust.
-
-To run Ruff:
-
-```bash
-# Lint code
-ruff check .
-
-# Auto-fix linting issues
-ruff check --fix .
-
-# Format code
-ruff format .
-
-# Check formatting only
-ruff format --check .
-```
-
-The Ruff configuration is defined in `pyproject.toml` under the `[tool.ruff]` section.
-
-### Running Tests
-
-```bash
-# Run all tests with coverage
-pytest tests/ --cov=veris_ai --cov-report=xml --cov-report=term-missing
-
-# Run specific test file
-pytest tests/test_tool_mock.py
-
-# Run tests with verbose output
-pytest -v tests/
-```
-
-### Type Checking
-
-```bash
-# Run static type checking
-mypy src/veris_ai tests
-```
-
-## License
-
-This project is licensed under the MIT License - see the LICENSE file for details. 
-
-## Jaeger Trace Interface
-
-A lightweight, fully-typed wrapper around the Jaeger **Query Service** HTTP API lives under `veris_ai.jaeger_interface`.
-It allows you to **search and retrieve traces** from both Jaeger's default storage back-ends as well as **OpenSearch**, with additional **client-side span filtering** capabilities.
-
-```python
-from veris_ai.jaeger_interface import JaegerClient
-
-client = JaegerClient("http://localhost:16686")
-
-# Search with trace-level filters (server-side)
-traces = client.search(service="veris-agent", limit=2, tags={"error": "true"})
-
-# Search with span-level filters (client-side, OR logic)
-filtered = client.search(
-    service="veris-agent", 
-    limit=10,
-    span_tags={"http.status_code": 500, "db.error": "timeout"}
-)
-
-first_trace = client.get_trace(traces.data[0].traceID)
-```
-
-See `src/veris_ai/jaeger_interface/README.md` for a complete walkthrough and API reference. 

veris_ai-1.3.0.dist-info/RECORD

@@ -1,13 +0,0 @@
-veris_ai/__init__.py,sha256=Vp5yf9ZRchw0mmPwrRuNebI5cb2NGwpJGfr41l86q1U,1177
-veris_ai/braintrust_tracing.py,sha256=0i-HR6IuK3-Q5ujMjT1FojxESRZLgqEvJ44bfJfDHaw,11938
-veris_ai/models.py,sha256=6HINPxNFCakCVPcyEbUswWkXwb2K4lF0A8g8EvTMal4,213
-veris_ai/tool_mock.py,sha256=U4xjINEZbtjutb_Vtr_So1ENNrU9kDROSyNUU5RL1Jc,10610
-veris_ai/utils.py,sha256=3R2J9ko5t1UATiF1R6Hox9IPbtUz59EHsMDFg1-i7sk,9208
-veris_ai/jaeger_interface/README.md,sha256=te5z3MWLqd2ECVV-a0MImBwTKRgQuuSuDB3bwIIsHi0,4437
-veris_ai/jaeger_interface/__init__.py,sha256=d873a0zq3eUYU2Y77MtdjCwIARjAsAP7WDqGXDMWpYs,1158
-veris_ai/jaeger_interface/client.py,sha256=yJrh86wRR0Dk3Gq12DId99WogcMIVbL0QQFqVSevvlE,8772
-veris_ai/jaeger_interface/models.py,sha256=e64VV6IvOEFuzRUgvDAMQFyOZMRb56I-PUPZLBZ3rX0,1864
-veris_ai-1.3.0.dist-info/METADATA,sha256=FD5DuzpYTZKjDmsPOb897HIMdOzS4l1UNTKh_68d29Y,13832
-veris_ai-1.3.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-veris_ai-1.3.0.dist-info/licenses/LICENSE,sha256=2g4i20atAgtD5einaKzhQrIB-JrPhyQgD3bC0wkHcCI,1065
-veris_ai-1.3.0.dist-info/RECORD,,