veris-ai 1.2.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/__init__.py

@@ -5,9 +5,9 @@ from typing import Any
 __version__ = "0.1.0"
 
 # Import lightweight modules that only use base dependencies
-from .tool_mock import veris
 from .jaeger_interface import JaegerClient
 from .models import ResponseExpectation
+from .tool_mock import veris
 
 # Lazy import for modules with heavy dependencies
 _instrument = None
@@ -34,9 +34,4 @@ def instrument(*args: Any, **kwargs: Any) -> Any:  # noqa: ANN401
     return _instrument(*args, **kwargs)
 
 
-__all__ = [
-    "veris",
-    "JaegerClient",
-    "instrument",
-    "ResponseExpectation"
-]
+__all__ = ["veris", "JaegerClient", "instrument", "ResponseExpectation"]

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/jaeger_interface/client.py

@@ -5,12 +5,12 @@ This implementation keeps dependencies minimal while providing fully-typed
 """
 
 import json
-from typing import Any, Dict, List, Optional, Self
+import types
+from typing import Any, Self
 
 import requests
 
-from .models import GetTraceResponse, SearchResponse, Span, Tag, Trace
-
+from .models import GetTraceResponse, SearchResponse, Span, Trace
 
 __all__ = ["JaegerClient"]
 
@@ -60,30 +60,27 @@ class JaegerClient:  # noqa: D101
         session.headers.update(self._headers)
         return session, True
 
-    def _span_matches_tags(self, span: Span, span_tags: Dict[str, Any]) -> bool:
+    def _span_matches_tags(self, span: Span, span_tags: dict[str, Any]) -> bool:
         """Check if a span matches any of the provided tags (OR logic)."""
         if not span.tags or not span_tags:
             return False
-        
+
         # Convert span tags to a dict for easier lookup
         span_tag_dict = {tag.key: tag.value for tag in span.tags}
-        
+
         # OR logic: return True if ANY tag matches
-        for key, value in span_tags.items():
-            if span_tag_dict.get(key) == value:
-                return True
-        
-        return False
+        return any(span_tag_dict.get(key) == value for key, value in span_tags.items())
 
     def _filter_spans(
         self,
-        traces: List[Trace],
-        span_tags: Optional[Dict[str, Any]],
-        span_operations: Optional[List[str]] = None
-    ) -> List[Trace]:
-        """
-        Filter spans within traces based on span_tags (OR logic) and/or span_operations (OR logic).
-        If both are provided, a span must match at least one tag AND at least one operation.
+        traces: list[Trace],
+        span_tags: dict[str, Any] | None,
+        span_operations: list[str] | None = None,
+    ) -> list[Trace]:
+        """Filter spans within traces based on span_tags and/or span_operations.
+
+        Uses OR logic within each filter type. If both are provided, a span must
+        match at least one tag AND at least one operation.
         """
         if not span_tags and not span_operations:
             return traces
@@ -109,7 +106,7 @@ class JaegerClient:  # noqa: D101
                     traceID=trace.traceID,
                     spans=filtered_spans,
                     process=trace.process,
-                    warnings=trace.warnings
+                    warnings=trace.warnings,
                 )
                 filtered_traces.append(filtered_trace)
 
@@ -119,16 +116,16 @@ class JaegerClient:  # noqa: D101
     # Public API
     # ---------------------------------------------------------------------
 
-    def search(
+    def search(  # noqa: PLR0913
         self,
-        service: Optional[str] = None,
+        service: str | None = None,
         *,
-        limit: Optional[int] = None,
-        tags: Optional[Dict[str, Any]] = None,
-        operation: Optional[str] = None,
-        span_tags: Optional[Dict[str, Any]] = None,
-        span_operations: Optional[List[str]] = None,
-        **kwargs: Any
+        limit: int | None = None,
+        tags: dict[str, Any] | None = None,
+        operation: str | None = None,
+        span_tags: dict[str, Any] | None = None,
+        span_operations: list[str] | None = None,
+        **kwargs: Any,  # noqa: ANN401
     ) -> SearchResponse:  # noqa: D401
         """Search traces using the *v1* ``/api/traces`` endpoint with optional span filtering.
 
@@ -137,9 +134,11 @@ class JaegerClient:  # noqa: D101
             limit: Maximum number of traces to return.
             tags: Dictionary of tag filters for trace-level filtering (AND-combined).
             operation: Operation name to search for.
-            span_tags: Dictionary of tag filters for span-level filtering (OR-combined AND-combined with span_operations).
+            span_tags: Dictionary of tag filters for span-level filtering.
+                      Uses OR logic. Combined with span_operations using AND.
                       Applied client-side after retrieving traces.
-            span_operations: List of operation names to search for (OR-combined AND-combined with span_tags).
+            span_operations: List of operation names to search for.
+                            Uses OR logic. Combined with span_tags using AND.
             **kwargs: Additional parameters to pass to the Jaeger API.
 
         Returns:
@@ -147,24 +146,24 @@ class JaegerClient:  # noqa: D101
             with spans filtered according to span_tags if provided.
         """
         # Build params for the Jaeger API (excluding span_tags)
-        params: Dict[str, Any] = {}
-        
+        params: dict[str, Any] = {}
+
         if service is not None:
             params["service"] = service
-        
+
         if limit is not None:
             params["limit"] = limit
-        
+
         if operation is not None:
             params["operation"] = operation
-        
+
         if tags:
             # Convert tags to JSON string as expected by Jaeger API
             params["tags"] = json.dumps(tags)
-        
+
         # Add any additional parameters
         params.update(kwargs)
-        
+
         session, should_close = self._make_session()
         try:
             url = f"{self._base_url}/api/traces"
@@ -174,18 +173,22 @@ class JaegerClient:  # noqa: D101
         finally:
             if should_close:
                 session.close()
-        
+
         # Parse the response
         search_response = SearchResponse.model_validate(data)  # type: ignore[arg-type]
-        
+
         # Apply span-level filtering if span_tags is provided
-        if span_tags or span_operations and search_response.data and isinstance(search_response.data, list):
+        if (
+            (span_tags or span_operations)
+            and search_response.data
+            and isinstance(search_response.data, list)
+        ):
             filtered_traces = self._filter_spans(search_response.data, span_tags, span_operations)
             search_response.data = filtered_traces
             # Update the total to reflect filtered results
             if search_response.total is not None:
                 search_response.total = len(filtered_traces)
-        
+
         return search_response
 
     def get_trace(self, trace_id: str) -> GetTraceResponse:  # noqa: D401
@@ -225,7 +228,7 @@ class JaegerClient:  # noqa: D101
         self,
         exc_type: type[BaseException] | None,
         exc: BaseException | None,
-        tb: Any | None,
+        tb: types.TracebackType | None,
     ) -> None:
         """Exit the context manager."""
         # Only close if we created the session

veris_ai/jaeger_interface/models.py

@@ -1,9 +1,8 @@
 from __future__ import annotations
 
-import json
 from typing import Any
 
-from pydantic import BaseModel, Field, ConfigDict
+from pydantic import BaseModel, ConfigDict, Field
 
 __all__ = [
     "Tag",

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/models.py

@@ -5,7 +5,7 @@ from enum import Enum
 
 class ResponseExpectation(str, Enum):
     """Expected response behavior for tool mocking."""
-    
+
     AUTO = "auto"
     REQUIRED = "required"
-    NONE = "none"
+    NONE = "none"