veris-ai 1.17.1__tar.gz

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

@@ -0,0 +1,82 @@
+---
+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
+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.
+
+### 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 and exploration waypoints. Use linked references and tags to dynamically navigate through the documentation web, following trails of dependency and discovering emergent patterns — 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.
+5. **Recursive documentation weaving**: When creating or updating a README, treat it as the entry point to a documentation web. Draft the initial README, then follow every dependency thread—navigating to parent and child READMEs, creating missing pieces, and refining connections. Continue this cyclical exploration until the entire documentation network achieves seamless consistency, with each iteration strengthening the coherence of the whole system.
+
+---
+
+### 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 child READMEs and parent READMEs, design docs, or code directories.
+* **Visual Aids**: Use visual aids (e.g. mermaid diagrams) to as needed to help explain the codebase to humans.
+
+
+> 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 in the LLM 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.
+* Ensure docs remain aligned with code without ballooning in size.
+
+#### Human Responsibilities
+
+* Diligently read through *ALL* LLM‑driven documentation 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 documentation edits require thorough human driver review to ensure usability and accuracy.          |

veris_ai-1.17.1/.github/workflows/release.yml

@@ -0,0 +1,45 @@
+name: Release
+
+on:
+  workflow_dispatch:
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: '3.13'
+
+      - name: Install dependencies
+        run: |
+          curl -LsSf https://astral.sh/uv/install.sh | sh
+          uv sync --all-extras
+          uv pip install python-semantic-release
+
+      - name: Configure Git
+        run: |
+          git config --global user.name "GitHub Actions"
+          git config --global user.email "actions@github.com"
+
+      - name: Version and Upload Artifacts
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          uv run semantic-release version
+          uv run semantic-release publish
+
+      - name: Publish to PyPI if distribution is created
+        run: |
+          if [ -d "dist" ] && [ "$(ls -A dist)" ]; then
+            uv publish --token ${{ secrets.PYPI_API_TOKEN }}
+          else
+            echo "No distribution files found in dist directory. Skipping PyPI publish."
+          fi

veris_ai-1.17.1/.github/workflows/test.yml

@@ -0,0 +1,44 @@
+name: Tests
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+  workflow_dispatch:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v5
+      with:
+        python-version: ${{ matrix.python-version }}
+
+    - name: Install uv
+      run: |
+        curl -LsSf https://astral.sh/uv/install.sh | sh
+
+    - name: Install dependencies
+      run: |
+        uv sync --all-extras
+
+    - name: Run code quality checks with Ruff
+      run: |
+        uv run ruff check .
+        uv run ruff format --check .
+
+    - name: Run type checks with mypy
+      run: |
+        uv run mypy src/veris_ai
+
+    - name: Run tests with pytest
+      run: |
+        uv run pytest tests/ --cov=veris_ai --cov-report=xml --cov-report=term-missing

veris_ai-1.17.1/.gitignore

@@ -0,0 +1,132 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+.python-version
+
+# celery beat schedule file
+celerybeat-schedule
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# VS Code
+.vscode/
+
+# PyCharm
+.idea/
+
+# macOS
+.DS_Store
+
+# Windows
+Thumbs.db 
+
+.scratch/

veris_ai-1.17.1/.pre-commit-config.yaml

@@ -0,0 +1,24 @@
+repos:
+  - repo: local
+    hooks:
+      - id: ruff-check
+        name: Ruff lint
+        entry: uv run ruff check --fix .
+        language: system
+        pass_filenames: false
+        types: [python]
+
+      - id: ruff-format-check
+        name: Ruff format (check)
+        entry: uv run ruff format 
+        language: system
+        pass_filenames: false
+        types: [python]
+
+      - id: mypy
+        name: Mypy type check
+        entry: uv run mypy src/veris_ai
+        language: system
+        pass_filenames: false
+        types: [python]
+

veris_ai-1.17.1/CHANGELOG.md

@@ -0,0 +1,13 @@
+# CHANGELOG
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## v0.1.1 (2025-04-17)
+
+### Features
+
+- Updates to package for publishing ([#1](https://github.com/veris-ai/veris-python-sdk/pull/1),
+  [`c6f460e`](https://github.com/veris-ai/veris-python-sdk/commit/c6f460ea6e2f8472c120370a14f67f1d8c28626c))

veris_ai-1.17.1/CLAUDE.md

@@ -0,0 +1,285 @@
+# 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, spied on, or executed normally in production
+- `@veris.spy()` decorator - executes original functions while logging calls and responses 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
+- `SimulatorAPIClient` class in `src/veris_ai/api_client.py` - centralized client for making requests to VERIS simulation endpoints with automatic authentication
+
+## Development Commands
+
+This project uses `uv` as the package manager and follows modern Python tooling practices.
+
+### Setup
+```bash
+# Install base 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 all extras
+uv add "veris-ai[dev,fastapi,observability,agents]"
+
+# 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 decorator functionality:
+  - `@veris.mock()`: Dynamic mocking that calls external endpoints for responses
+  - `@veris.stub()`: Simple stubbing with fixed return values
+  - `@veris.spy()`: Logging decorator that executes original function and logs the call/response
+- Session-based activation: Uses session ID presence to determine mocking behavior
+- HTTP communication with mock endpoints via `httpx` (for mock decorator)
+- Context extraction for session management via context variables
+- Delegates type conversion to the utils module
+- Automatic API endpoint configuration with production defaults
+
+**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
+
+Environment variables:
+- `VERIS_API_KEY`: API authentication key for VERIS services (optional, but recommended for production)
+- `VERIS_MOCK_TIMEOUT`: Request timeout in seconds (optional, default: 90.0)
+
+**Note**: The SDK automatically connects to the production VERIS API endpoint (`https://simulation.api.veris.ai/`). Only override `VERIS_API_URL` if you need to use a custom endpoint (rarely needed).
+
+### Session-Based Activation
+
+The SDK activates mocking based on session ID presence:
+- **With session ID**: Routes calls to mock/simulator endpoint
+- **Without session ID**: Executes original function
+- Session IDs can be set manually via `veris.set_session_id()` or extracted automatically from OAuth2 tokens in FastAPI MCP integration
+
+### 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 mode with session ID  
+- `production_env`: Sets up production mode without session ID
+
+**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
+  - `@veris.mock()`: Sends function metadata to external endpoint for dynamic responses
+  - `@veris.stub()`: Returns predetermined values without external calls
+  - `@veris.spy()`: Executes original function while logging calls and responses
+- **Session Management**: Extracts session ID from context for request correlation
+- **API Client**: Centralized `SimulatorAPIClient` handles all API communication
+  - Automatic endpoint configuration with production defaults
+  - Built-in authentication via `VERIS_API_KEY` header
+  - Configurable timeout with `VERIS_MOCK_TIMEOUT`
+- **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
+
+## 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.17.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Veris AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.