tracereplay 0.1.0__tar.gz

tracereplay-0.1.0/.gitattributes

@@ -0,0 +1,10 @@
+# Enforce LF line endings across all platforms (Windows, Linux, macOS)
+* text=auto eol=lf
+
+*.py text eol=lf
+*.toml text eol=lf
+*.md text eol=lf
+*.yml text eol=lf
+*.yaml text eol=lf
+*.json text eol=lf
+

tracereplay-0.1.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,90 @@
+name: Bug report
+description: Report a bug or unexpected behaviour in TraceReplay.
+title: "[BUG] "
+labels:
+  - bug
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for reporting a bug. Please remove API keys, tokens,
+        passwords, and private prompts from all information you share.
+
+  - type: input
+    id: version
+    attributes:
+      label: TraceReplay version
+      placeholder: "0.1.0 or commit hash"
+    validations:
+      required: true
+
+  - type: input
+    id: python-version
+    attributes:
+      label: Python version
+      placeholder: "Python 3.12"
+    validations:
+      required: true
+
+  - type: dropdown
+    id: component
+    attributes:
+      label: Affected component
+      options:
+        - Recording
+        - Replay engine
+        - Request matching
+        - Tool calls
+        - Fixture storage
+        - pytest integration
+        - Provider integration
+        - Documentation
+        - Other
+    validations:
+      required: true
+
+  - type: textarea
+    id: description
+    attributes:
+      label: Bug description
+      description: Explain what happened.
+    validations:
+      required: true
+
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: Steps to reproduce
+      placeholder: |
+        1. Configure TraceReplay...
+        2. Record an interaction...
+        3. Run replay...
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behaviour
+    validations:
+      required: true
+
+  - type: textarea
+    id: actual
+    attributes:
+      label: Actual behaviour
+    validations:
+      required: true
+
+  - type: textarea
+    id: logs
+    attributes:
+      label: Error messages or logs
+      description: Remove all secrets and sensitive data before posting.
+      render: shell
+
+  - type: textarea
+    id: environment
+    attributes:
+      label: Additional environment information
+      placeholder: Operating system, provider, configuration, etc.

tracereplay-0.1.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,10 @@
+blank_issues_enabled: false
+
+contact_links:
+  - name: Security vulnerability
+    url: https://github.com/rakshithkumar608/TraceReplay/security/advisories/new
+    about: Report security vulnerabilities privately.
+
+  - name: Questions and discussions
+    url: https://github.com/rakshithkumar608/TraceReplay/discussions
+    about: Ask questions or discuss ideas with the community.

tracereplay-0.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,34 @@
+## Summary
+
+Describe what this pull request changes.
+
+## Related issue
+
+Closes #
+
+## Changes made
+
+- 
+- 
+- 
+
+## Type of change
+
+- [ ] Bug fix
+- [ ] New feature
+- [ ] Breaking change
+- [ ] Documentation update
+- [ ] Refactoring
+- [ ] Performance improvement
+- [ ] Tests
+
+## Testing
+
+- [ ] Existing tests pass.
+- [ ] New tests have been added where needed.
+- [ ] I tested the changes locally.
+
+Commands used:
+
+```bash
+# Add test commands here

tracereplay-0.1.0/.github/README1.md

@@ -0,0 +1,33 @@
+# GitHub Repository Configuration
+
+This directory contains GitHub repository automation and contribution templates.
+
+## Contents
+
+- `ISSUE_TEMPLATE/bug_report.yml`
+  - Standardized bug reports.
+
+- `ISSUE_TEMPLATE/feature_request.yml`
+  - Standardized feature requests.
+
+- `ISSUE_TEMPLATE/config.yml`
+  - Issue configuration and community links.
+
+- `PULL_REQUEST_TEMPLATE.md`
+  - Pull request checklist.
+
+- `dependabot.yml`
+  - Automated dependency update configuration.
+
+## Dependency updates
+
+Dependabot checks Python dependencies and GitHub Actions weekly.
+
+Python dependency updates will become useful once the project package
+configuration is added.
+
+## Continuous integration
+
+GitHub Actions CI will be configured after the initial Python SDK
+structure and `pyproject.toml` are created. This ensures CI runs
+actual project tests and checks.

tracereplay-0.1.0/.github/dependabot.yml

@@ -0,0 +1,20 @@
+
+
+version: 2
+
+updates:
+  - package-ecosystem: pip
+    directory: /
+    schedule:
+      interval: weekly
+    labels:
+      - dependencies
+      - python
+
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+    labels:
+      - dependencies
+      - ci

tracereplay-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,91 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint-and-typecheck:
+    name: Lint & Typecheck
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v7
+
+      - name: Set up Python 3.12
+        uses: actions/setup-python@v7
+        with:
+          python-version: "3.12"
+          cache: "pip"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Run Ruff Lint
+        run: ruff check .
+
+      - name: Run Ruff Format Check
+        run: ruff format --check .
+
+      - name: Run Mypy Typecheck
+        run: mypy src tests
+
+  test:
+    name: Test (Python ${{ matrix.python-version }} on ${{ matrix.os }})
+    needs: lint-and-typecheck
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v7
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v7
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: "pip"
+
+      - name: Install package & test dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Run Pytest
+        run: pytest -v --strict-markers
+
+  build-check:
+    name: Build & Package Check
+    needs: lint-and-typecheck
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v7
+
+      - name: Set up Python 3.12
+        uses: actions/setup-python@v7
+        with:
+          python-version: "3.12"
+
+      - name: Install build tools
+        run: |
+          python -m pip install --upgrade pip
+          pip install build twine
+
+      - name: Build package distributions
+        run: python -m build
+
+      - name: Check package metadata with twine
+        run: twine check dist/*

tracereplay-0.1.0/.gitignore

@@ -0,0 +1,44 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Distribution / packaging
+build/
+dist/
+*.egg-info/
+
+# Virtual Environments
+.venv/
+venv/
+env/
+ENV/
+
+# Testing, Linting & Type Checking caches
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# Staging & Scratch Directories (Protected staging area for phases)
+staging/
+staging_phase1/
+.staging/
+
+# Local Environment Variables & Secrets
+.env
+.env.local
+*.local
+
+# IDE & Editor files
+.vscode/
+.idea/
+*.swp
+*.swo
+
+
+# Local Assets & Scratch Directories
+assets/
+scratch/
+.tracereplay/

tracereplay-0.1.0/CHANGELOG.md

@@ -0,0 +1,65 @@
+# Changelog
+
+All notable changes to TraceReplay 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).
+
+---
+
+## [0.1.0] - 2026-11-05
+
+### Added
+
+#### Milestone 1: Core Foundation & Deterministic Replay Engine
+- **Core Domain Models:** High-performance immutable models (`SessionRecord`, `Interaction`, `RequestPayload`, `ResponsePayload`, `TokenUsage`, `ToolCallRecord`).
+- **Atomic JSON Storage Engine:** ACID-safe atomic JSON writes, schema validation, and path traversal protection.
+- **Deterministic Request Normalizer & Matcher:** Semantic whitespace normalizer, dictionary key sorting, parameter filtering, and unified diff output.
+- **Strict Zero-Live-Fallback Guarantee:** Replay mode strictly halts with `RequestMismatchError` or `LiveFallbackProhibitedError` on any discrepancy—guaranteeing zero silent cloud API bills.
+- **Automated PII & Secret Sanitizer:** Automatic redaction of sensitive credentials (`sk-...`, `gsk_...`, bearer tokens, authorization headers) before persisting fixtures.
+- **Universal Provider Interceptors:** Out-of-the-box adapters for OpenAI (`openai.OpenAI`), Groq (`groq.Groq`), Anthropic Claude (`anthropic.Anthropic`), Google Gemini (`google.genai`), DeepSeek, and local Ollama.
+- **Native Pytest Plugin:**
+  - Registered under Pytest `pytest11` entrypoint (`pytest_plugin.py`).
+  - `@pytest.mark.trace_replay` marker with custom fixture naming and parameterization support.
+  - Auto-injected fixtures: `tracereplay_session` and `tracereplay_patch`.
+  - Autonomous `AUTO` mode: Records missing fixtures on first run; deterministically replays on all subsequent runs.
+
+#### Milestone 2: Multi-Turn Agent & Complex Tool-Call Recording (Phase 8)
+- **`AgentTracker` Execution Graph:** Models complex agent workflows as stateful decision graphs (`User Input -> LLM Decision -> Tool Execution -> Tool Result -> Next Decision -> Final Answer`).
+- **Visual Graph Generator:** `AgentTracker.visualize_flow()` producing human-readable ASCII decision trees for debugging agent reasoning.
+- **`@record_tool` Interception Decorator:**
+  - Wraps synchronous and asynchronous local Python functions.
+  - Captures argument signatures and execution durations.
+  - **Replay Bypass:** In `REPLAY` mode, completely bypasses the real Python function and returns recorded fixture data deterministically.
+- **Sequential Tool Call Verification:** Strict index-based tool matching preventing out-of-order execution during agent reasoning loops.
+
+#### Milestone 2: Multi-Provider Expansion & Universal Model Switching (Phase 9)
+- **Official Mistral AI Adapter (`MistralAdapter`):**
+  - Dedicated adapter for modern `mistralai>=1.0.0` SDK (`Mistral` client).
+  - Intercepts synchronous `client.chat.complete` and asynchronous `client.chat.complete_async`.
+  - Normalizes Mistral messages, tool calls, and token usage statistics.
+  - Reconstructs native-compatible `MistralChatCompletionResponse` during deterministic replay.
+- **Generic OpenAI-Compatible Adapter (`GenericOpenAIAdapter`):**
+  - Universal adapter for self-hosted and local inference engines: Ollama (`:11434`), vLLM (`:8000`), LM Studio (`:1234`), and LocalAI (`:8080`).
+  - Ephemeral parameter sanitization stripping server-specific flags (`num_ctx`, `keep_alive`, `options`, `repetition_penalty`, `top_k`) ensuring environment-agnostic deterministic fixture hashing.
+- **Enhanced Anthropic Claude Adapter:**
+  - Full tool use roundtrip support (`tools`, `tool_choice`, `tool_use`, and `tool_result` content blocks).
+  - Reconstructs `AnthropicMessageResponse` populated with `AnthropicToolUseBlock` instances and `stop_reason="tool_use"`.
+- **Enhanced Google Gemini Adapter:**
+  - Function calling and tool definition extraction (`function_declarations`).
+  - Reconstructs `GeminiFunctionCall` within candidate parts and provides ergonomic `.function_calls` property.
+- **Universal Dynamic Provider Auto-Patcher:**
+  - Dynamic resolution for Mistral, Generic, Anthropic, Gemini, Groq, DeepSeek, and Ollama based on client types, base URL ports, and explicit hints.
+- **Cross-Provider Model Switching Suite:**
+  - Unit and integration tests demonstrating seamless runtime swapping across 5 distinct LLM providers with identical assertions and zero live fallback.
+
+#### Open-Source SDK Polish (Option A)
+- **GitHub Actions CI Matrix:** Multi-OS (Ubuntu, Windows) automated testing across Python `3.10`, `3.11`, `3.12`, and `3.13` with strict `ruff` linting, `mypy` strict type-checking, and `twine` packaging checks.
+- **Interactive Runnable Examples (`examples/`):**
+  - `01_quickstart_openai.py`: Hybrid real/simulated OpenAI recording and sub-5ms replay.
+  - `02_pytest_workflow/test_weather_bot.py`: Complete Pytest test suite.
+  - `03_autonomous_agent_tools.py`: Multi-turn autonomous agent with frozen local tool functions.
+  - `04_multi_provider.py`: Normalized cross-provider pipeline.
+  - `05_quickstart_groq.py`: Verified live Groq LPU inference recording and playback.
+  - `examples/README.md`: Quickstart cheat-sheet for running all examples.
+- **Production-Grade Documentation:** High-impact landing page in `README.md` with badges, value proposition, quickstarts, and security guidelines.

tracereplay-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,40 @@
+# Code of Conduct
+
+## Our commitment
+
+TraceReplay aims to provide a welcoming and respectful environment for everyone who participates in the project.
+
+We are committed to making participation free from harassment and discrimination, regardless of experience level, background, identity, or personal characteristics.
+
+## Expected behavior
+
+Examples of behavior that contributes to a positive environment include:
+
+- Being respectful and considerate.
+- Giving and receiving constructive feedback.
+- Explaining disagreements without personal attacks.
+- Respecting different viewpoints and experience levels.
+- Focusing criticism on ideas, code, and technical decisions.
+- Helping keep discussions clear and welcoming.
+
+## Unacceptable behavior
+
+Unacceptable behavior includes harassment, insults, intimidation, discriminatory language, deliberate disruption, personal attacks, and publishing another person's private information without permission.
+
+## Scope
+
+This code applies in project spaces, including Issues, Pull Requests, Discussions, and other project-related communication.
+
+## Reporting
+
+Report conduct that violates this policy to the project maintainers through the contact method listed in the repository profile. Please include relevant context and links where possible.
+
+Maintainers will review reports fairly and take appropriate action. Reports will be handled as privately as practical.
+
+## Enforcement
+
+Project maintainers may edit or remove inappropriate content, close discussions, or restrict participation when necessary. Maintainers are expected to apply these standards consistently.
+
+## Attribution
+
+This document is adapted from the Contributor Covenant framework. The project may adopt a specific Contributor Covenant version as its community grows.

tracereplay-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,81 @@
+# Contributing to TraceReplay
+
+Thank you for considering a contribution to TraceReplay.
+
+TraceReplay is an early-stage open-source project. The goal is to make testing LLM-powered applications more repeatable through recording, fixture storage, and replay.
+
+## Before you start
+
+1. Read the project [README](README.md).
+2. Check existing Issues and Pull Requests to avoid duplicate work.
+3. For a significant feature or architectural change, open an Issue first and discuss the proposed approach.
+4. Keep contributions focused. A small, well-tested change is easier to review.
+
+## Contribution areas
+
+Potential contribution areas include:
+
+- Core interaction models and configuration.
+- Fixture serialization, loading, and validation.
+- Recording and replay behavior.
+- Request matching.
+- Provider adapters.
+- Tool-call capture and replay.
+- pytest integration.
+- Documentation and examples.
+- Dashboard and platform work, when those components are opened for contribution.
+
+Do not claim support for a provider or API operation unless it has been implemented and tested.
+
+## Development principles
+
+- Local SDK use must not require a hosted TraceReplay account.
+- Replay mode must not silently call a live provider when a fixture is missing.
+- Errors should explain what failed and provide useful debugging context.
+- Avoid storing API keys, authorization headers, or other secrets.
+- Preserve provider-specific data when normalization would otherwise discard meaningful information.
+- Add tests for behavior changes and regression fixes.
+- Keep public APIs and documentation aligned.
+
+## Pull request process
+
+1. Create a branch for your change.
+2. Make the smallest coherent change that solves the issue.
+3. Add or update tests.
+4. Run the relevant test, lint, formatting, and type-check commands documented by the project.
+5. Update documentation when behavior or public APIs change.
+6. Open a Pull Request describing the problem, solution, and tests performed.
+7. Link the related Issue when applicable.
+
+Do not mark checks as passing unless you have run them successfully.
+
+## Commit messages
+
+Use clear, descriptive commit messages. A conventional format is recommended:
+
+- `feat: add fixture validation`
+- `fix: prevent live fallback during replay`
+- `docs: clarify provider setup`
+- `test: cover request matching`
+- `refactor: simplify interaction model`
+
+## Issues
+
+When opening a bug report, include:
+
+- TraceReplay version or commit.
+- Python version and operating system.
+- Minimal reproduction steps.
+- Expected behavior.
+- Actual behavior.
+- Relevant error output, with secrets and private data removed.
+
+For feature requests, explain the use case and the behavior you expect.
+
+## Security
+
+Never include API keys, tokens, customer data, private prompts, or unredacted production recordings in Issues, Pull Requests, or test fixtures. For vulnerabilities, follow [SECURITY.md](SECURITY.md).
+
+## Code of conduct
+
+By participating, you agree to follow the expectations in [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md).