veris-ai 0.2.1__tar.gz → 1.0.0__tar.gz

{veris_ai-0.2.1 → veris_ai-1.0.0}/.github/workflows/release.yml

@@ -21,7 +21,7 @@ jobs:
       - name: Install dependencies
         run: |
           curl -LsSf https://astral.sh/uv/install.sh | sh
-          uv sync
+          uv sync --all-extras
           uv pip install python-semantic-release
 
       - name: Configure Git

{veris_ai-0.2.1 → veris_ai-1.0.0}/.github/workflows/test.yml

@@ -2,9 +2,9 @@ name: Tests
 
 on:
   push:
-    branches: [ master ]
+    branches: [ main ]
   pull_request:
-    branches: [ master ]
+    branches: [ main ]
 
 jobs:
   test:
@@ -27,8 +27,7 @@ jobs:
 
     - name: Install dependencies
       run: |
-        uv venv
-        uv pip install -e .[dev]
+        uv sync --all-extras
 
     - name: Run code quality checks with Ruff
       run: |

veris_ai-1.0.0/CLAUDE.md

@@ -0,0 +1,181 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## 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
+- `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
+
+## Development Commands
+
+This project uses `uv` as the package manager and follows modern Python tooling practices.
+
+### Setup
+```bash
+# Install with development dependencies
+uv add "veris-ai[dev]"
+
+# Install with FastAPI MCP integration
+uv add "veris-ai[fastapi]"
+
+# Set Python version (requires 3.11+)
+pyenv local 3.11.0
+```
+
+### Code Quality (Primary: Ruff)
+```bash
+# Lint code
+ruff check .
+
+# Auto-fix linting issues
+ruff check --fix .
+
+# Format code  
+ruff format .
+
+# Check formatting only
+ruff format --check .
+```
+
+### Type Checking
+```bash
+# Run static type checking
+mypy src/veris_ai tests
+```
+
+### Testing
+```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/
+```
+
+### Building
+```bash
+# Build package distributions
+uv build
+```
+
+## Code Architecture
+
+### Core Components
+
+**VerisSDK Class** (`src/veris_ai/tool_mock.py:27`)
+- Main SDK class that provides `@veris.mock()` decorator functionality
+- Environment detection: Uses `ENV` environment variable to determine simulation vs production mode
+- HTTP communication with mock endpoints via `httpx`
+- Context extraction for session management via context variables
+- Delegates type conversion to the utils module
+
+**API Surface** (`src/veris_ai/__init__.py:5`)
+- Exports single `veris` instance for public use
+- Clean, minimal API design
+
+**Type Conversion Utilities** (`src/veris_ai/utils.py:1`)
+- `convert_to_type()` function handles sophisticated type conversion from mock responses
+- Supports primitives, lists, dictionaries, unions, and custom types
+- Modular design with separate conversion functions for each type category
+- Uses Python's typing system for runtime type checking
+
+**FastAPI MCP Integration** (`src/veris_ai/models.py:1`)
+- `FastApiMCPParams` Pydantic model for configuring FastAPI MCP server integration
+- Comprehensive configuration options including:
+  - Custom server naming and descriptions
+  - HTTP client configuration (base URL, headers, timeout)
+  - Operation filtering (include/exclude by operation ID or tag)
+  - Response schema documentation controls
+  - Authentication configuration
+
+### Environment Configuration
+
+Required environment variables:
+- `VERIS_MOCK_ENDPOINT_URL`: Mock 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
+
+### Type System
+
+The SDK handles sophisticated type conversion from mock responses:
+- Type conversion is handled by the `convert_to_type()` function in `src/veris_ai/utils.py`
+- Supports primitives, lists, dictionaries, unions, and custom types
+- Modular design with separate handlers for different type categories
+- Uses Python's typing system for runtime type checking
+
+## Testing Strategy
+
+**Test Structure**:
+- `tests/conftest.py:1`: Pytest fixtures for environment mocking and context objects
+- `tests/test_tool_mock.py:1`: Unit tests for the VerisSDK class and mock decorator functionality
+- `tests/test_utils.py:1`: Comprehensive tests for type conversion utilities
+
+**Key Test Fixtures**:
+- `mock_context`: Provides mock context with session ID
+- `simulation_env`: Sets up simulation environment variables  
+- `production_env`: Sets up production environment variables
+
+**Test Coverage Areas**:
+- Environment-based behavior switching
+- HTTP client interactions and error handling
+- Type conversion scenarios (parametrized tests)
+- Configuration validation
+
+## Code Quality Standards
+
+**Ruff Configuration** (80+ rules enabled):
+- Line length: 100 characters
+- Target: Python 3.11+
+- Google-style docstring convention
+- Comprehensive rule set covering style, bugs, security, and complexity
+- Relaxed rules for test files (allows more flexibility in tests)
+
+**Development Tools**:
+- **Ruff**: Primary linter and formatter (replaces flake8, black, isort)
+- **MyPy**: Static type checking
+- **Pytest**: Testing with async support and coverage
+- **Pre-commit**: Git hooks for code quality
+
+## CI/CD Pipeline
+
+**Testing Workflow** (`.github/workflows/test.yml`):
+- Runs on Python 3.11, 3.12, 3.13
+- Code quality checks (Ruff lint/format)
+- Type checking (MyPy)  
+- Unit tests with coverage
+
+**Release Workflow** (`.github/workflows/release.yml`):
+- Manual trigger for releases
+- Semantic versioning with conventional commits
+- Automated PyPI publishing
+- Uses `uv build` for package building
+
+## Key Implementation Details
+
+- **Decorator Pattern**: Functions are wrapped to intercept calls in simulation mode
+- **Session Management**: Extracts session ID from context for request correlation
+- **Error Handling**: Comprehensive HTTP and type conversion error handling
+- **Async Support**: Built with async/await pattern throughout
+- **Type Safety**: Full type hints and runtime type conversion validation
+- **Modular Architecture**: Type conversion logic separated into utils module for better maintainability
+
+### FastAPI MCP Integration
+
+The `set_fastapi_mcp()` method provides:
+- **Automatic Session Handling**: OAuth2-based session ID extraction from bearer tokens
+- **Context Management**: Session IDs are stored in context variables for cross-request correlation
+- **Auth Config Merging**: User-provided auth configs are merged with internal session handling
+- **MCP Server Access**: Configured server available via `veris.fastapi_mcp` property
+
+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

{veris_ai-0.2.1 → veris_ai-1.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: veris-ai
-Version: 0.2.1
+Version: 1.0.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
@@ -17,11 +17,14 @@ 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'
 Description-Content-Type: text/markdown
 
 # Veris AI Python SDK
 
-A Python package for Veris AI tools with simulation capabilities.
+A Python package for Veris AI tools with simulation capabilities and FastAPI MCP (Model Context Protocol) integration.
 
 ## Installation
 
@@ -33,6 +36,9 @@ uv add veris-ai
 
 # Install with development dependencies
 uv add "veris-ai[dev]"
+
+# Install with FastAPI MCP integration
+uv add "veris-ai[fastapi]"
 ```
 
 ## Environment Setup
@@ -93,6 +99,78 @@ When `ENV=simulation` is set, the decorator will:
 
 When not in simulation mode, the original function will be executed normally.
 
+## 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()
+```
+
+## 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 utilities
+
+tests/
+├── conftest.py        # Pytest fixtures
+├── test_tool_mock.py  # Tests for VerisSDK functionality
+└── test_utils.py      # Tests for type conversion utilities
+```
+
 ## Development
 
 This project uses `pyproject.toml` for dependency management and `uv` for package installation.
@@ -121,16 +199,40 @@ This project uses [Ruff](https://github.com/charliermarsh/ruff) for linting and
 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 .
 ```
 
-To automatically fix issues:
+The Ruff configuration is defined in `pyproject.toml` under the `[tool.ruff]` section.
+
+### Running Tests
 
 ```bash
-ruff check --fix .
+# 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/
 ```
 
-The Ruff configuration is defined in `pyproject.toml` under the `[tool.ruff]` section.
+### Type Checking
+
+```bash
+# Run static type checking
+mypy src/veris_ai tests
+```
 
 ## License
 

veris_ai-1.0.0/README.md

@@ -0,0 +1,215 @@
+# 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]"
+```
+
+## 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
+```
+
+## 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.
+
+## 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()
+```
+
+## 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 utilities
+
+tests/
+├── conftest.py        # Pytest fixtures
+├── test_tool_mock.py  # Tests for VerisSDK functionality
+└── test_utils.py      # Tests for type conversion utilities
+```
+
+## 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. 

{veris_ai-0.2.1 → veris_ai-1.0.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "veris-ai"
-version = "0.2.1"
+version = "1.0.0"
 description = "A Python package for Veris AI tools"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -26,6 +26,10 @@ dev = [
     "mypy>=1.5.1",
     "pre-commit>=3.3.3",
 ]
+fastapi = [
+    "fastapi",
+    "fastapi_mcp",
+]
 
 [project.urls]
 "Homepage" = "https://github.com/veris-ai/veris-python-sdk"
@@ -118,7 +122,7 @@ convention = "google"
 
 [tool.semantic_release]
 version_variables = ["pyproject.toml:version"]
-branch = "master"
+branch = "main"
 changelog_file = "CHANGELOG.md"
 build_command = "uv build"
 dist_path = "dist/"