veris-ai 1.3.0__tar.gz → 1.4.0__tar.gz

veris_ai-1.4.0/.cursor/rules/documentation-management.mdc

@@ -0,0 +1,80 @@
+---
+description: Ensure READMEs function as both a human-friendly guide and an LLM semantic router, while designating source code as the sole source of truth. This document also defines LLM workflows that continuously evolve documentation in response to actual usage patterns.
+alwaysApply: false
+---
+
+# Documentation Handling Guidelines
+
+### Dual‑Use Overview
+
+* **Humans**: READMEs must be narrative‑driven, intuitive, and structured for readability, with inline cross‑links to related READMEs or code modules for deeper context.
+* **LLM Agents**: Treat these same READMEs as semantic routers. Use linked references and tags within the document to locate the most relevant code, tests, and workflows — never treat the README as the ultimate logic source.
+* **Shared Goal**: Documentation must actively fight codebase complexity. Instead of growing endlessly, it should simplify, subtract redundancy, and delegate details to lower‑level READMEs in the hierarchy.
+
+---
+
+### When to Update Documentation
+
+Trigger updates upon significant changes including:
+
+* Major features, refactors, or architectural/schematic changes
+* Workflow updates or dependencies added/removed
+* Changes affecting user interactions or onboarding
+
+**Heuristic**: If the change alters how a human would interact or mentally model the system — or how the LLM navigates it — it calls for a README update.
+
+Updates should simplify where possible: remove outdated or redundant content, and delegate specifics via cross‑links (e.g., *See [Auth Module README](./auth/README.md) for details on authentication flows*).
+
+---
+
+### LLM‑Driven Continuous Documentation
+
+1. **End‑of‑session reflection**: At task completion, the LLM should summarize the work and, if needed, update the README with clarifications or new links to relevant modules.
+2. **Parallel instance memory**: Maintain awareness of session context across LLM instances to keep documentation aligned with ongoing workflows.
+3. **LLM as thought partner**: Propose not only wording edits but also simplifications and delegation opportunities — e.g., linking to an existing module README rather than duplicating logic.
+4. **Complexity management**: Treat every update as a chance to prune. The README should remain a high‑level, navigable entry point, not a catch‑all.
+
+---
+
+### Structure & Format
+
+Each meaningful workspace or module must include a `README.md` designed to operate like a **hub page** in an IDE‑backed website:
+
+* **Quick Reference**: Purpose, setup, usage, and high‑level architecture.
+* **Linked Context**: Cross‑links to deeper READMEs, design docs, or code directories.
+* **Semantic Anchors**: Inline cues (e.g., tags, headings, links) that help the LLM map concepts to code without requiring redundant prose.
+
+> Example:
+> *“For transaction processing, see [Transactions README](./transactions/README.md). For error handling logic, see [Error Handling README](./errors/README.md).”*
+
+The human and LLM share the same document: humans follow the narrative, while the LLM uses references and anchors to navigate the codebase semantically.
+
+---
+
+### Workflow Roles
+
+#### LLM Responsibilities
+
+* Detect README drift by comparing live code to described behavior.
+* Perform updates with an emphasis on pruning duplication and linking to existing READMEs.
+* Use end‑of‑session summaries to suggest or implement simplifications.
+* Ensure docs remain aligned with code without ballooning in size.
+
+#### Human Responsibilities
+
+* Review LLM‑driven updates for clarity, accuracy, and usability.
+* Refactor prose when needed to keep explanations intuitive.
+* Validate that cross‑links resolve correctly and are helpful for navigation.
+
+---
+
+### Key Principles
+
+| Principle                  | Description                                                               |
+| -------------------------- | ------------------------------------------------------------------------- |
+| **Code is truth**          | Source code is definitive; README is a semantic guide, not the authority. |
+| **Documentation evolves**  | Updates happen with real usage, not on a fixed schedule.                  |
+| **Simplicity over sprawl** | Fight complexity by pruning, delegating, and cross‑linking.               |
+| **One README, two roles**  | The same README serves both humans and LLMs through cross‑referencing.    |
+| **Real‑world grounding**   | Updates reflect actual changes in workflows and architecture.             |
+| **Human validation**       | LLM edits require human review to ensure usability and accuracy.          |

{veris_ai-1.3.0 → veris_ai-1.4.0}/.github/workflows/test.yml

@@ -5,6 +5,7 @@ on:
     branches: [ main ]
   pull_request:
     branches: [ main ]
+  workflow_dispatch:
 
 jobs:
   test:

{veris_ai-1.3.0 → veris_ai-1.4.0}/CLAUDE.md

@@ -5,10 +5,12 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 ## Project Overview
 
 This is the Veris AI Python SDK - a package that provides simulation capabilities through decorator-based function mocking and FastAPI MCP (Model Context Protocol) integration. The core functionality revolves around:
-- `VerisSDK` class in `src/veris_ai/tool_mock.py:27` - enables environment-aware execution where functions can be mocked in simulation mode or executed normally in production
+- `VerisSDK` class in `src/veris_ai/tool_mock.py:27` - enables environment-aware execution where functions can be mocked in simulation mode, spied on, or executed normally in production
+- Spy mode (`@veris.mock(mode="spy")`) - executes original functions while logging calls and responses to Redis via logging endpoints
 - `convert_to_type()` function in `src/veris_ai/utils.py:5` - handles sophisticated type conversion from mock responses
 - `FastApiMCPParams` model in `src/veris_ai/models.py:1` - provides configuration for integrating FastAPI applications with the Model Context Protocol
 - `set_fastapi_mcp()` method in `src/veris_ai/tool_mock.py:54` - configures FastAPI MCP server with automatic OAuth2-based session management
+- Logging utilities in `src/veris_ai/logging.py` - provide async and sync functions for logging tool calls and responses to VERIS endpoints
 
 ## Development Commands
 
@@ -100,7 +102,7 @@ uv build
 ### Environment Configuration
 
 Required environment variables:
-- `VERIS_MOCK_ENDPOINT_URL`: Mock endpoint URL (required)
+- `VERIS_ENDPOINT_URL`: Base endpoint URL (required)
 - `VERIS_MOCK_TIMEOUT`: Request timeout in seconds (optional, default: 30.0)
 - `ENV`: Set to "simulation" to enable mocking, anything else runs original functions
 
@@ -182,4 +184,80 @@ Key implementation aspects:
 - Creates internal OAuth2PasswordBearer scheme for token extraction
 - Dependency injection for automatic session context setting
 - Preserves user auth configurations while adding session management
-- SSE (Server-Sent Events) support for streaming responses
+- SSE (Server-Sent Events) support for streaming responses
+
+## Documentation Handling Guidelines
+
+### Dual‑Use Overview
+
+* **Humans**: READMEs must be narrative‑driven, intuitive, and structured for readability, with inline cross‑links to related READMEs or code modules for deeper context.
+* **LLM Agents**: Treat these same READMEs as semantic routers. Use linked references and tags within the document to locate the most relevant code, tests, and workflows — never treat the README as the ultimate logic source.
+* **Shared Goal**: Documentation must actively fight codebase complexity. Instead of growing endlessly, it should simplify, subtract redundancy, and delegate details to lower‑level READMEs in the hierarchy.
+
+---
+
+### When to Update Documentation
+
+Trigger updates upon significant changes including:
+
+* Major features, refactors, or architectural/schematic changes
+* Workflow updates or dependencies added/removed
+* Changes affecting user interactions or onboarding
+
+**Heuristic**: If the change alters how a human would interact or mentally model the system — or how the LLM navigates it — it calls for a README update.
+
+Updates should simplify where possible: remove outdated or redundant content, and delegate specifics via cross‑links (e.g., *See [Auth Module README](./auth/README.md) for details on authentication flows*).
+
+---
+
+### LLM‑Driven Continuous Documentation
+
+1. **End‑of‑session reflection**: At task completion, the LLM should summarize the work and, if needed, update the README with clarifications or new links to relevant modules.
+2. **Parallel instance memory**: Maintain awareness of session context across LLM instances to keep documentation aligned with ongoing workflows.
+3. **LLM as thought partner**: Propose not only wording edits but also simplifications and delegation opportunities — e.g., linking to an existing module README rather than duplicating logic.
+4. **Complexity management**: Treat every update as a chance to prune. The README should remain a high‑level, navigable entry point, not a catch‑all.
+
+---
+
+### Structure & Format
+
+Each meaningful workspace or module must include a `README.md` designed to operate like a **hub page** in an IDE‑backed website:
+
+* **Quick Reference**: Purpose, setup, usage, and high‑level architecture.
+* **Linked Context**: Cross‑links to deeper READMEs, design docs, or code directories.
+* **Semantic Anchors**: Inline cues (e.g., tags, headings, links) that help the LLM map concepts to code without requiring redundant prose.
+
+> Example:
+> *“For transaction processing, see [Transactions README](./transactions/README.md). For error handling logic, see [Error Handling README](./errors/README.md).”*
+
+The human and LLM share the same document: humans follow the narrative, while the LLM uses references and anchors to navigate the codebase semantically.
+
+---
+
+### Workflow Roles
+
+#### LLM Responsibilities
+
+* Detect README drift by comparing live code to described behavior.
+* Perform updates with an emphasis on pruning duplication and linking to existing READMEs.
+* Use end‑of‑session summaries to suggest or implement simplifications.
+* Ensure docs remain aligned with code without ballooning in size.
+
+#### Human Responsibilities
+
+* Review LLM‑driven updates for clarity, accuracy, and usability.
+* Refactor prose when needed to keep explanations intuitive.
+* Validate that cross‑links resolve correctly and are helpful for navigation.
+
+---
+
+### Key Principles
+
+| Principle                  | Description                                                               |
+| -------------------------- | ------------------------------------------------------------------------- |
+| **Code is truth**          | Source code is definitive; README is a semantic guide, not the authority. |
+| **Documentation evolves**  | Updates happen with real usage, not on a fixed schedule.                  |
+| **Simplicity over sprawl** | Fight complexity by pruning, delegating, and cross‑linking.               |
+| **One README, two roles**  | The same README serves both humans and LLMs through cross‑referencing.    |
+| **Real‑world grounding**   | Updates reflect actual changes in workflows and architecture.             |
+| **Human validation**       | LLM edits require human review to ensure usability and accuracy.          |

veris_ai-1.4.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,187 @@
+# 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.