agentcassette 0.1.0__tar.gz

agentcassette-0.1.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,38 @@
+---
+name: Bug report
+about: Something isn't working correctly
+labels: bug
+---
+
+## Description
+
+A clear description of the bug.
+
+## Reproduction
+
+```python
+import agentcassette
+from agentcassette import record, replay
+
+call_model = agentcassette.intercept(call_model, kind="llm")
+
+# What you did:
+with record("cassette.json"):
+    ...
+
+# What you expected:
+
+# What you got:
+```
+
+## Environment
+
+- agentcassette version:
+- Python version:
+- OS:
+
+## Traceback
+
+```
+Paste the full traceback here, if any.
+```

agentcassette-0.1.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,28 @@
+---
+name: Feature request
+about: Suggest a new capability or behavior
+labels: enhancement
+---
+
+## What problem does this solve?
+
+Describe the use case, not the solution. What can't you do today?
+
+## Proposed solution
+
+If you have a concrete idea, describe it here. Include example code if helpful:
+
+```python
+import agentcassette
+
+# What the new behavior would look like:
+```
+
+## Alternatives considered
+
+Any other approaches you've thought about?
+
+## Notes
+
+- Does this require a new dependency? (It shouldn't — agentcassette has zero dependencies by design.)
+- Does it keep cassettes provider-agnostic and human-readable JSON?

agentcassette-0.1.0/.github/dependabot.yml

@@ -0,0 +1,30 @@
+version: 2
+updates:
+  # Keep GitHub Actions up to date
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+    commit-message:
+      prefix: "ci"
+    labels:
+      - "dependencies"
+      - "ci"
+
+  # pip: only dev dependencies (agentcassette has no runtime dependencies)
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+    commit-message:
+      prefix: "chore"
+    labels:
+      - "dependencies"
+    ignore:
+      # Only update patch versions for dev tools automatically
+      - dependency-name: "pytest"
+        update-types: ["version-update:semver-major"]
+      - dependency-name: "hatch"
+        update-types: ["version-update:semver-major"]

agentcassette-0.1.0/.github/pull_request_template.md

@@ -0,0 +1,23 @@
+## Summary
+
+What does this PR do? Reference any related issues: `Fixes #123`
+
+## Changes
+
+- 
+- 
+
+## Testing
+
+- [ ] New tests added (or existing tests updated) for all changed behavior
+- [ ] `pytest tests/ -v` passes locally
+- [ ] No third-party imports introduced (zero-dependency contract)
+- [ ] Tested on Python 3.9 (lowest supported version)
+
+## Cassette compatibility (if applicable)
+
+If this PR changes the cassette format, describe the change and how existing cassettes are handled (bump `CASSETTE_VERSION` if the format is not backward compatible).
+
+## Notes for reviewers
+
+Anything that needs extra attention or context?

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

@@ -0,0 +1,78 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    name: Python ${{ matrix.python-version }} / ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
+        os: [ubuntu-latest, macos-latest, windows-latest]
+
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install package (no dependencies to install)
+        run: pip install -e ".[dev]"
+
+      - name: Run tests
+        run: pytest tests/ -v --tb=short
+
+      - name: Verify zero runtime dependencies
+        shell: bash  # heredoc below is bash syntax; Windows defaults to pwsh
+        run: |
+          # agentcassette must ship with zero dependencies.
+          # This step fails the build if any non-stdlib import is introduced.
+          python - <<'EOF'
+          import sys, pathlib, ast
+
+          # sys.stdlib_module_names is Python 3.10+. On 3.9 the rest of the
+          # matrix provides coverage, so skip this static check there.
+          if not hasattr(sys, "stdlib_module_names"):
+              print("Skipping static import check on Python < 3.10")
+              sys.exit(0)
+
+          src = pathlib.Path("src/agentcassette")
+          stdlib_modules = set(sys.stdlib_module_names)
+
+          third_party = []
+          for py_file in src.rglob("*.py"):
+              tree = ast.parse(py_file.read_text())
+              for node in ast.walk(tree):
+                  if isinstance(node, ast.Import):
+                      names = [alias.name for alias in node.names]
+                  elif isinstance(node, ast.ImportFrom):
+                      # Relative imports (level > 0) are always intra-package.
+                      if node.level:
+                          continue
+                      names = [node.module or ""]
+                  else:
+                      continue
+                  for name in names:
+                      top = name.split(".")[0]
+                      if top and top not in stdlib_modules and top != "agentcassette":
+                          third_party.append(f"{py_file}: {top}")
+
+          if third_party:
+              print("FAIL: third-party imports detected:")
+              for item in third_party:
+                  print(f"  {item}")
+              sys.exit(1)
+          print("OK: zero third-party dependencies confirmed")
+          EOF

agentcassette-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,136 @@
+name: Publish to PyPI
+
+# Triggers on a pushed version tag: v0.1.0, v1.2.3, etc.
+# Requires PyPI Trusted Publishing configured at:
+# https://pypi.org/manage/project/agentcassette/settings/publishing/
+# No API token or secret needed — OIDC handles authentication.
+#
+# Actions are pinned to full commit SHAs to satisfy the repo's
+# "require actions to be pinned to a full-length commit SHA" policy.
+
+on:
+  push:
+    tags:
+      - "v[0-9]+.[0-9]+.[0-9]+"
+      - "v[0-9]+.[0-9]+.[0-9]+[ab][0-9]+"   # alpha/beta: v1.0.0a1, v1.0.0b2
+
+jobs:
+  # ── 1. Run the full test suite before publishing ──────────────────────────
+  test:
+    name: Test before publish
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
+        with:
+          python-version: "3.12"
+      - run: pip install -e ".[dev]"
+      - run: pytest tests/ -v --tb=short
+
+  # ── 2. Build the distribution ─────────────────────────────────────────────
+  build:
+    name: Build distribution
+    needs: test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
+        with:
+          python-version: "3.12"
+
+      - name: Install hatch
+        run: pip install hatch
+
+      - name: Verify version tag matches pyproject.toml
+        run: |
+          TAG="${GITHUB_REF#refs/tags/v}"
+          PKG=$(python -c "import tomllib; d=tomllib.load(open('pyproject.toml','rb')); print(d['project']['version'])")
+          if [ "$TAG" != "$PKG" ]; then
+            echo "Tag $TAG does not match package version $PKG"
+            exit 1
+          fi
+          echo "Version match confirmed: $TAG"
+
+      - name: Build sdist and wheel
+        run: hatch build
+
+      - name: Upload distribution artifacts
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: dist
+          path: dist/
+
+  # ── 3. Publish to PyPI via Trusted Publishing (OIDC) ─────────────────────
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/agentcassette/
+    permissions:
+      id-token: write  # Required for OIDC trusted publishing
+
+    steps:
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
+        with:
+          python-version: "3.12"
+
+      - name: Download distribution artifacts
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: dist
+          path: dist/
+
+      # Trusted Publishing via OIDC, done manually with twine so no third-party
+      # GitHub Action is required (the org restricts which actions may run).
+      # Mirrors the official PyPI manual OIDC flow:
+      # https://docs.pypi.org/trusted-publishers/using-a-publisher/
+      - name: Publish to PyPI (OIDC trusted publishing)
+        run: |
+          set -euo pipefail
+          python -m pip install --upgrade twine
+
+          # 1. Obtain a GitHub OIDC token scoped to PyPI.
+          oidc_token=$(curl -sS \
+            -H "Authorization: bearer ${ACTIONS_ID_TOKEN_REQUEST_TOKEN}" \
+            "${ACTIONS_ID_TOKEN_REQUEST_URL}&audience=pypi" \
+            | python -c "import sys, json; print(json.load(sys.stdin)['value'])")
+
+          # 2. Exchange it for a short-lived PyPI API token.
+          api_token=$(curl -sS -X POST https://pypi.org/_/oidc/mint-token \
+            -d "{\"token\": \"${oidc_token}\"}" \
+            | python -c "import sys, json; print(json.load(sys.stdin)['token'])")
+
+          # 3. Upload the distributions (--skip-existing makes re-runs safe).
+          twine upload --skip-existing --username __token__ --password "${api_token}" dist/*
+
+  # ── 4. Create GitHub Release with changelog excerpt ───────────────────────
+  release:
+    name: Create GitHub Release
+    needs: publish
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+
+      - name: Download distribution artifacts
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: dist
+          path: dist/
+
+      - name: Create GitHub Release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          TAG="${GITHUB_REF#refs/tags/}"
+          VERSION="${TAG#v}"
+          # Extract the changelog block for this version (between its header and the next)
+          awk "/^## \[$VERSION\]/{flag=1; next} /^## \[/{flag=0} flag" CHANGELOG.md > notes.md
+          # Create the release, or (re)attach assets if it already exists.
+          gh release create "$TAG" dist/* --title "$TAG" --notes-file notes.md \
+            || gh release upload "$TAG" dist/* --clobber

agentcassette-0.1.0/.gitignore

@@ -0,0 +1,50 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+*.egg
+*.egg-info/
+dist/
+build/
+.eggs/
+pip-wheel-metadata/
+share/python-wheels/
+
+# Virtual environments
+.venv/
+venv/
+env/
+ENV/
+
+# Testing
+.pytest_cache/
+.coverage
+.coverage.*
+coverage.xml
+htmlcov/
+.tox/
+.nox/
+
+# Type checking
+.mypy_cache/
+.dmypy.json
+.pytype/
+.pyre/
+
+# Build tools
+.hatch/
+*.tar.gz
+*.whl
+
+# Editors
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+.DS_Store
+Thumbs.db
+
+# Project-specific
+*.log

agentcassette-0.1.0/CHANGELOG.md

@@ -0,0 +1,26 @@
+# Changelog
+
+All notable changes to agentcassette are documented here.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-06-30
+
+### Added
+- `intercept()` — wrap a callable so it can be recorded and replayed; transparent pass-through outside a session. Supports both sync functions and `async def` coroutine functions
+- `record()` — context manager that tapes every intercepted call to a JSON cassette (written on clean exit only)
+- `replay()` — context manager that serves recorded results without running the real functions
+- Strict replay (`strict=True`) raising `DivergenceError` on any name/argument mismatch; best-effort mode collects divergences on the player
+- `Cassette` — load/save, `num_steps`, `total_input_tokens`, `total_output_tokens`, `total_tokens`, `duration_ms`, and `redact()` for scrubbing secrets
+- Record-time redaction via `record(..., redact=[...])`
+- `diff_cassettes()` / `CassetteDiff` — `new_calls`, `dropped_calls`, `changed_calls`, token deltas, and `identical`
+- Token accounting that prefers exact provider usage blocks (OpenAI/Anthropic) and falls back to a deterministic character heuristic
+- Exception hierarchy under `AgentCassetteError`: `CassetteNotFound`, `ReplayExhausted`, `DivergenceError`
+- Zero external dependencies — pure Python stdlib (3.9+)
+- 44 unit tests covering sync/async record/replay, divergence, cassette inspection, diffing, token accounting, and error handling
+
+[Unreleased]: https://github.com/aenealabs/agentcassette/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/aenealabs/agentcassette/releases/tag/v0.1.0

agentcassette-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,31 @@
+# Code of Conduct
+
+## Our Pledge
+
+We as contributors and maintainers pledge to make participation in agentcassette a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment:
+
+- Using welcoming and inclusive language
+- Being respectful of differing viewpoints and experiences
+- Gracefully accepting constructive criticism
+- Focusing on what is best for the community
+- Showing empathy towards other community members
+
+Examples of unacceptable behavior:
+
+- The use of sexualized language or imagery
+- Trolling, insulting/derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information without explicit permission
+- Other conduct which could reasonably be considered inappropriate in a professional setting
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by opening a GitHub issue or contacting the maintainers directly. All complaints will be reviewed and investigated and will result in a response deemed necessary and appropriate to the circumstances.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org/), version 2.1.

agentcassette-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,70 @@
+# Contributing to agentcassette
+
+Thank you for taking the time to contribute.
+
+## Ground rules
+
+- **Zero external dependencies.** agentcassette must remain pure Python stdlib. PRs that introduce any third-party import will not be merged.
+- **Python 3.9+.** All code must run on Python 3.9 through the latest stable release.
+- **Tests required.** Every new feature or bug fix must include a corresponding test. The CI matrix runs on 3 operating systems × 5 Python versions — please run tests locally before opening a PR.
+- **Keep it focused.** agentcassette does one thing: record and replay agent runs deterministically. Feature requests outside that scope belong in a separate package.
+
+## Setting up a development environment
+
+```bash
+git clone https://github.com/aenealabs/agentcassette
+cd agentcassette
+python -m venv .venv
+source .venv/bin/activate        # Windows: .venv\Scripts\activate
+pip install -e ".[dev]"
+```
+
+## Running tests
+
+```bash
+pytest tests/ -v
+```
+
+To run against a specific Python version, use `hatch`:
+
+```bash
+pip install hatch
+hatch run test
+```
+
+## Architecture
+
+agentcassette is small and layered — read the modules in this order:
+
+1. `src/agentcassette/_errors.py` — the exception hierarchy.
+2. `src/agentcassette/_tokens.py` — token accounting (exact usage blocks, else heuristic).
+3. `src/agentcassette/_cassette.py` — the on-disk JSON format, load/save/redact, JSON coercion.
+4. `src/agentcassette/_session.py` — the thread-local session, `intercept()` seam, `Recorder`, `Player`, and the `record`/`replay` context managers.
+5. `src/agentcassette/_diff.py` — cassette comparison.
+6. `src/agentcassette/__init__.py` — the public surface.
+
+## Adding a feature
+
+1. Implement it in the appropriate `_*.py` module.
+2. Export it from `__init__.py` (and add to `__all__`) if it is public.
+3. Add tests under `tests/` covering the new behavior, including edge cases.
+4. Update `README.md` and `CHANGELOG.md`.
+
+## Submitting a pull request
+
+1. Fork the repository and create a branch: `git checkout -b fix/my-fix` or `feat/my-feature`.
+2. Make your changes and add tests.
+3. Run `pytest tests/ -v` — all tests must pass.
+4. Open a pull request against `main` with a clear description of what changed and why.
+
+## Reporting bugs
+
+Open an issue using the **Bug report** template. Include the Python version, OS, a minimal agent/callable, and the full traceback.
+
+## Suggesting features
+
+Open an issue using the **Feature request** template. Explain the use case, not just the solution.
+
+## Code style
+
+agentcassette uses no formatter or linter by choice to keep contributor setup minimal. Please follow the style of the surrounding code: 4-space indentation, descriptive variable names, module-level docstrings on every file.

agentcassette-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 LaVon Rutledge
+
+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.