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

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
 
@@ -92,23 +98,16 @@ class VerisSDK:
             **params_dict,
         )
 
-    def mock(
+    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:
         """Decorator for mocking tool calls."""
 
-        def decorator(func: Callable) -> Callable:
+        def decorator(func: Callable) -> Callable:  # noqa: C901, PLR0915
             """Decorator for mocking tool calls."""
-            endpoint = os.getenv("VERIS_MOCK_ENDPOINT_URL")
-            if not endpoint:
-                error_msg = "VERIS_MOCK_ENDPOINT_URL environment variable is not set"
-                raise ValueError(error_msg)
-            # Default timeout of 30 seconds
-            timeout = float(os.getenv("VERIS_MOCK_TIMEOUT", "90.0"))
-            
             # Check if the original function is async
             is_async = inspect.iscoroutinefunction(func)
 
@@ -148,7 +147,7 @@ class VerisSDK:
                     response_expectation = ResponseExpectation.REQUIRED
                 else:
                     response_expectation = ResponseExpectation.AUTO
-                
+
                 payload = {
                     "session_id": self.session_id,
                     "response_expectation": response_expectation.value,
@@ -169,11 +168,46 @@ class VerisSDK:
                 **kwargs: dict[str, object],
             ) -> object:
                 # Check if we're in simulation mode
-                env_mode = os.getenv("ENV", "").lower()
-                if env_mode != "simulation":
+                if not self.session_id:
                     # If not in simulation mode, execute the original function
                     return await func(*args, **kwargs)
-                
+
+                # 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"))
+
                 logger.info(f"Simulating function: {func.__name__}")
                 payload, return_type_obj = create_mock_payload(*args, **kwargs)
 
@@ -196,11 +230,46 @@ class VerisSDK:
                 **kwargs: dict[str, object],
             ) -> object:
                 # Check if we're in simulation mode
-                env_mode = os.getenv("ENV", "").lower()
-                if env_mode != "simulation":
+                if not self.session_id:
                     # If not in simulation mode, execute the original function
                     return func(*args, **kwargs)
-                
+
+                # 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"))
+
                 logger.info(f"Simulating function: {func.__name__}")
                 payload, return_type_obj = create_mock_payload(*args, **kwargs)
 
@@ -228,26 +297,24 @@ class VerisSDK:
         def decorator(func: Callable) -> Callable:
             # Check if the original function is async
             is_async = inspect.iscoroutinefunction(func)
-            
+
             @wraps(func)
             async def async_wrapper(
                 *args: tuple[object, ...],
                 **kwargs: dict[str, object],
             ) -> object:
-                env_mode = os.getenv("ENV", "").lower()
-                if env_mode != "simulation":
+                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__}")
+                    return await func(*args, **kwargs)
+                logger.info(f"Stubbing function: {func.__name__}")
                 return return_value
-            
+
             @wraps(func)
             def sync_wrapper(*args: tuple[object, ...], **kwargs: dict[str, object]) -> object:
-                env_mode = os.getenv("ENV", "").lower()
-                if env_mode != "simulation":
+                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,,