veris-ai 1.0.0__py3-none-any.whl → 1.2.0__py3-none-any.whl

veris_ai/utils.py

@@ -1,5 +1,10 @@
+import sys
+import types
+import typing
 from contextlib import suppress
-from typing import Any, Union, get_args, get_origin
+from typing import Any, ForwardRef, Literal, NotRequired, Required, Union, get_args, get_origin
+
+from pydantic import BaseModel
 
 
 def convert_to_type(value: object, target_type: type) -> object:
@@ -15,6 +20,7 @@ def convert_to_type(value: object, target_type: type) -> object:
         list: _convert_list,
         dict: _convert_dict,
         Union: _convert_union,
+        types.UnionType: _convert_union,  # Handle Python 3.10+ union syntax (str | int)
     }
 
     # Use appropriate converter based on origin
@@ -69,3 +75,197 @@ def _convert_simple_type(value: object, target_type: type) -> object:
             return target_type(**value)
 
     return target_type(value)
+
+
+def _resolve_forward_ref(ref: ForwardRef, module_context: types.ModuleType | None = None) -> Any:  # noqa: ANN401
+    """Resolve a ForwardRef to its actual type."""
+    if not isinstance(ref, ForwardRef):
+        return ref
+
+    # Try to evaluate the forward reference
+    try:
+        # Get the module's namespace for evaluation
+        namespace = dict(vars(module_context)) if module_context else {}
+
+        # Add common typing imports to namespace
+        namespace.update(
+            {
+                "Union": Union,
+                "Any": Any,
+                "Literal": Literal,
+                "Required": Required,
+                "NotRequired": NotRequired,
+                "List": list,
+                "Dict": dict,
+                "Optional": typing.Optional,
+                "Iterable": typing.Iterable,
+                "str": str,
+                "int": int,
+                "float": float,
+                "bool": bool,
+            },
+        )
+
+        # Try to import from the same module to resolve local references
+        if module_context and hasattr(module_context, "__name__"):
+            with suppress(Exception):
+                # Import all from the module to get access to local types
+                exec(f"from {module_context.__name__} import *", namespace)  # noqa: S102
+
+        # Get the forward reference string
+        ref_string = ref.__forward_arg__ if hasattr(ref, "__forward_arg__") else str(ref)
+
+        # Try to evaluate the forward reference string
+        return eval(ref_string, namespace, namespace)  # noqa: S307
+    except Exception:
+        # If we can't resolve it, return the ref itself
+        return ref
+
+
+def _unwrap_required(field_type: Any) -> tuple[Any, bool]:  # noqa: ANN401
+    """Unwrap Required/NotRequired and return the inner type and whether it's required."""
+    origin = get_origin(field_type)
+
+    # Check if it's Required or NotRequired
+    if origin is Required:
+        args = get_args(field_type)
+        return args[0] if args else field_type, True
+    if origin is NotRequired:
+        args = get_args(field_type)
+        return args[0] if args else field_type, False
+
+    # Default to required for TypedDict fields
+    return field_type, True
+
+
+def extract_json_schema(target_type: Any) -> dict:  # noqa: PLR0911, PLR0912, C901, ANN401
+    """Extract the JSON schema from a type or pydantic model.
+
+    Args:
+        target_type: The type or pydantic model to extract the JSON schema from.
+
+    Returns:
+        A dictionary representing the JSON schema.
+
+    Example:
+        >>> extract_json_schema(int)
+        {"type": "integer"}
+
+        >>> extract_json_schema(list[int])
+        {"type": "array", "items": {"type": "integer"}}
+
+        >>> extract_json_schema(list[User])
+        {"type": "array", "items": {"type": "object", "properties": {...}}}
+    """
+    # Handle Pydantic BaseModel instances or classes
+    if isinstance(target_type, type) and issubclass(target_type, BaseModel):
+        return target_type.model_json_schema()
+    if isinstance(target_type, BaseModel):
+        return target_type.model_json_schema()
+
+    # Handle TypedDict
+    if (
+        isinstance(target_type, type)
+        and hasattr(target_type, "__annotations__")
+        and hasattr(target_type, "__total__")
+    ):
+        # This is a TypedDict
+        properties = {}
+        required = []
+
+        # Get the module context for resolving forward references
+        module = sys.modules.get(target_type.__module__)
+
+        for field_name, field_type_annotation in target_type.__annotations__.items():
+            # Resolve forward references if present
+            resolved_type = field_type_annotation
+            if isinstance(resolved_type, ForwardRef):
+                resolved_type = _resolve_forward_ref(resolved_type, module)
+
+            # Unwrap Required/NotRequired
+            unwrapped_type, is_required = _unwrap_required(resolved_type)
+
+            # Extract schema for the unwrapped type
+            properties[field_name] = extract_json_schema(unwrapped_type)
+
+            # Add to required list if necessary
+            if is_required and getattr(target_type, "__total__", True):
+                required.append(field_name)
+
+        schema = {"type": "object", "properties": properties}
+        if required:
+            schema["required"] = required
+        return schema
+
+    # Handle built-in types
+    type_mapping = {
+        str: {"type": "string"},
+        int: {"type": "integer"},
+        float: {"type": "number"},
+        bool: {"type": "boolean"},
+        type(None): {"type": "null"},
+        Any: {},  # Empty schema for Any type
+    }
+
+    if target_type in type_mapping:
+        return type_mapping[target_type]
+
+    # Handle generic types
+    origin = get_origin(target_type)
+
+    # Handle bare collection types
+    if target_type is list:
+        return {"type": "array"}
+    if target_type is dict:
+        return {"type": "object"}
+    if target_type is tuple:
+        return {"type": "array"}
+
+    # Handle Literal types
+    if origin is Literal:
+        values = get_args(target_type)
+        if len(values) == 1:
+            # Single literal value - use const
+            return {"const": values[0]}
+        # Multiple literal values - use enum
+        return {"enum": list(values)}
+
+    if origin is list:
+        args = get_args(target_type)
+        if args:
+            return {"type": "array", "items": extract_json_schema(args[0])}
+        return {"type": "array"}
+
+    if origin is dict:
+        args = get_args(target_type)
+        if len(args) == 2:  # noqa: PLR2004
+            # For typed dicts like dict[str, int]
+            return {
+                "type": "object",
+                "additionalProperties": extract_json_schema(args[1]),
+            }
+        return {"type": "object"}
+
+    if origin is Union:
+        args = get_args(target_type)
+        # Handle Optional types (Union[T, None])
+        if len(args) == 2 and type(None) in args:  # noqa: PLR2004
+            non_none_type = args[0] if args[1] is type(None) else args[1]
+            schema = extract_json_schema(non_none_type)
+            return {"anyOf": [schema, {"type": "null"}]}
+        # Handle general Union types
+        return {"anyOf": [extract_json_schema(arg) for arg in args]}
+
+    if origin is tuple:
+        args = get_args(target_type)
+        if args:
+            return {
+                "type": "array",
+                "prefixItems": [extract_json_schema(arg) for arg in args],
+                "minItems": len(args),
+                "maxItems": len(args),
+            }
+        return {"type": "array"}
+
+    # Default case for unknown types
+    return {"type": "object"}

veris_ai-1.2.0.dist-info/METADATA

@@ -0,0 +1,457 @@
+Metadata-Version: 2.4
+Name: veris-ai
+Version: 1.2.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.2.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+veris_ai/__init__.py,sha256=FkpF1jAEX9y5mZjICuxv0-uc_pTgWuCzK5D5fEQ-b8s,1195
+veris_ai/braintrust_tracing.py,sha256=0i-HR6IuK3-Q5ujMjT1FojxESRZLgqEvJ44bfJfDHaw,11938
+veris_ai/models.py,sha256=wj1avahszKrErFbWVar9xvFrp_pVkQUCaJUc_gFzu3k,216
+veris_ai/tool_mock.py,sha256=UO-6tYvfreLXfOxHFKFl-GJ1nI7bLoz93uuv_yBehWc,10507
+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=AU9qP_pzutwantcLiKaml5JW_AHrXHH7X-ALYVkbNZc,8777
+veris_ai/jaeger_interface/models.py,sha256=ZYL2vlJbObAiAowsashuAuT6tUV9HaEmGKuxLPi_ye8,1876
+veris_ai-1.2.0.dist-info/METADATA,sha256=ZmgJqKZUnL2G0ANQxX6SiYX2UK3HqeG7FjGgCttAQPM,13832
+veris_ai-1.2.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+veris_ai-1.2.0.dist-info/licenses/LICENSE,sha256=2g4i20atAgtD5einaKzhQrIB-JrPhyQgD3bC0wkHcCI,1065
+veris_ai-1.2.0.dist-info/RECORD,,