backspin 0.5.1__tar.gz

backspin-0.5.1/.gitattributes

@@ -0,0 +1,4 @@
+# Normalize line endings across platforms
+* text=auto eol=lf
+*.png binary
+*.whl binary

backspin-0.5.1/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,26 @@
+---
+name: Bug report
+about: Something recorded / replayed / diffed wrong
+labels: bug
+---
+
+**What happened?** A clear description of the wrong behavior.
+
+**Minimal reproduction**
+
+```python
+# the smallest agent snippet that shows it
+```
+
+**The run file.** backspin is built so a bug report can be a `*.backspin.jsonl`
+file — attach it when you can (redact first if it contains sensitive content,
+see the README's redaction section). If not, include:
+
+- backspin version (`pip show backspin`)
+- Python version, OS
+- how the run was captured: `capture_openai` / `capture_anthropic` / proxy / TS SDK
+- provider and protocol (OpenAI-compatible / Anthropic Messages)
+
+**What did you expect?**
+
+**Anything else?** Tracebacks, warnings (`ReplayMismatchWarning`?), screenshots of the viewer.

backspin-0.5.1/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Questions & usage help
+    url: https://github.com/zaibuchihuoji/backspin/discussions
+    about: Ask how to record/replay/diff your agent — we'll answer.

backspin-0.5.1/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,19 @@
+---
+name: Feature request
+about: Suggest a capability for the recorder / replay / diff workflow
+labels: enhancement
+---
+
+**Your use case.** What are you trying to debug that backspin doesn't help with today?
+
+**Proposed solution.** What should it do? An API sketch is welcome:
+
+```python
+# e.g. rec.capture_x(...) / backspin some-command ...
+```
+
+**Alternatives you considered.** Cloud tools, manual logging, etc.
+
+**Does it fit the project's scope?** backspin stays local-first, file-based,
+and dependency-free at its core — features that need a server or an account
+belong elsewhere.

backspin-0.5.1/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,15 @@
+## What & why
+
+<!-- One or two sentences: what changes, and why a user would care. -->
+
+## Checklist
+
+- [ ] `pytest` green locally (including integration + performance suites)
+- [ ] `ruff check backspin/ tests/` clean
+- [ ] `mypy backspin/` clean
+- [ ] Behavior change has a test (run-format changes need a round-trip test)
+- [ ] `CHANGELOG.md` updated under an "Unreleased" heading
+- [ ] No new core dependencies (`backspin/` stays stdlib-only outside extras)
+
+<!-- If this touches the run file format: SCHEMA_VERSION bumped + load_run
+     still reads old files. -->

backspin-0.5.1/.github/dependabot.yml

@@ -0,0 +1,19 @@
+version: 2
+updates:
+  - package-ecosystem: pip
+    directory: "/"
+    schedule:
+      interval: weekly
+    groups:
+      python-dev-deps:
+        applies-to: version-updates
+        patterns:
+          - "*"
+  - package-ecosystem: npm
+    directory: "/sdks/typescript"
+    schedule:
+      interval: weekly
+  - package-ecosystem: github-actions
+    directory: "/"
+    schedule:
+      interval: monthly

backspin-0.5.1/.github/workflows/ci.yml

@@ -0,0 +1,82 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+      - run: pip install ruff
+      - run: ruff check backspin/ tests/
+
+  typecheck:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+      - run: pip install -e ".[dev]"
+      - run: mypy backspin/
+
+  test:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+        python: ["3.9", "3.10", "3.11", "3.12", "3.13"]
+        exclude:
+          - os: windows-latest
+            python: "3.9"
+          - os: windows-latest
+            python: "3.10"
+          - os: macos-latest
+            python: "3.9"
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 20
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+          cache: pip
+      - run: pip install -e ".[dev]"
+      # 3.9 skips the anthropic SDK (dropped 3.9), which drags total
+      # coverage below the normal gate; relax just that leg.
+      - run: >
+          pytest -q --cov=backspin --cov-report=xml --cov-report=term
+          ${{ matrix.python == '3.9' && '--cov-fail-under=60' || '' }}
+
+  typescript:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+      - working-directory: sdks/typescript
+        run: |
+          npm ci
+          npm test
+      # the published tarball must not ship tests and must typecheck clean
+      - working-directory: sdks/typescript
+        run: |
+          rm -rf dist
+          npm run build
+          test ! -d dist/test

backspin-0.5.1/.github/workflows/release.yml

@@ -0,0 +1,60 @@
+name: Release
+
+# Push a tag `vX.Y.Z` to publish. PyPI uses trusted publishing (no token):
+# configure the "backspin" project on pypi.org once —
+# Settings > Publishing > add GitHub publisher (repo: zaibuchihuoji/backspin,
+# workflow: release.yml, environment: pypi).
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  id-token: write  # PyPI trusted publishing (OIDC)
+
+jobs:
+  build-python:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+      - run: pip install -e ".[dev]" build
+      - run: ruff check backspin/ tests/
+      - run: mypy backspin/
+      - run: pytest -q
+      - run: python -m build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish-pypi:
+    needs: build-python
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+  build-typescript:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+      - working-directory: sdks/typescript
+        run: |
+          npm ci
+          npm test
+          npm run build
+      # npm publish stays manual until an NPM_TOKEN secret is configured:
+      #   npm publish --access public   (from sdks/typescript, on the tag)

backspin-0.5.1/.gitignore

@@ -0,0 +1,19 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+runs/
+*.backspin.jsonl
+node_modules/
+sdks/typescript/dist/
+.coverage
+coverage.xml
+.mimosa/
+.DS_Store

backspin-0.5.1/.pre-commit-config.yaml

@@ -0,0 +1,14 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.16.5
+    hooks:
+      - id: ruff
+        args: [--fix]
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: end-of-file-fixer
+      - id: trailing-whitespace
+      - id: check-json
+      - id: check-toml
+      - id: check-merge-conflict

backspin-0.5.1/CHANGELOG.md

@@ -0,0 +1,161 @@
+# Changelog
+
+All notable changes to backspin are documented here.
+
+## 0.5.1 — 2026-08-29
+
+Hardening release: engineering-quality fixes found in a full project audit.
+
+- **TS SDK: async tools recorded correctly** — `Recorder.tool()` now awaits
+  async functions, recording the resolved value (previously a Promise, which
+  serialized to `{}`) with the real duration; async rejections are recorded
+  with their error. A stream the consumer abandons mid-loop is now still
+  recorded (`finalize` runs in `finally`). `diffRuns` no longer falls back to
+  `"[object Object]"` for fingerprint-less events.
+- **TS SDK: redaction parity** — `redactStrings(transform)` / `mask(regex)`
+  mirror the Python API; `Recorder({ redact })` keeps secrets out of run
+  files while structural fields stay readable. npm packaging hardened
+  (`files`, `exports`, `engines`, `prepublishOnly`, SDK LICENSE/README,
+  tests excluded from the tarball). Version sync: Python and TS SDK both
+  0.5.1.
+- **Recorder survives disk failures** — a run file that becomes unwritable
+  (disk full, closed handle) stops recording with one `RuntimeWarning`
+  instead of raising into instrumented agent code (a stated ground rule).
+- **Stream context managers no longer swallow exceptions** — `__exit__` in
+  both OpenAI and Anthropic stream wrappers returned from a `finally`
+  block, which could discard in-flight exceptions; rewritten.
+- **Proxy hardening** — non-object JSON bodies return a clean 400 instead
+  of an unhandled 500 (both `/v1/chat/completions` and `/v1/messages`).
+- **Viewer API** — a well-formed but missing run name returns 404 instead
+  of a 500; corrupt runs still return 422.
+- **Viewer UI** — language toggle re-renders in place (no page reload),
+  `title` attributes and `<html lang>` localize, cards escape by default,
+  run list / timeline rows / tabs are keyboard-operable (roles, tabindex,
+  Enter/Space, Esc closes the inspector, focus rings).
+- **Tooling** — ruff (curated rule set) and mypy are clean across the
+  codebase and enforced in CI; fixed real findings (`share.py` missing
+  `Any` import, `replay.py` missing `Callable` import). pytest-cov wired
+  in. CI: lint + typecheck + test matrix (adds macOS and Python 3.13) +
+  a TypeScript job (tests + publish-shape check); release workflow builds
+  and publishes to PyPI via trusted publishing on `v*` tags.
+- **Community/meta** — SECURITY.md (incl. the recordings-contain-secrets
+  threat model), CODE_OF_CONDUCT.md, issue templates, PR checklist,
+  Dependabot, pre-commit config, README badges (CI/PyPI/license/ruff),
+  SPDX license expression, PyPI URLs; RELEASE.md rewritten as a generic
+  maintainer handbook.
+- Tests: Python 116 (was 107), TypeScript 10 (was 6).
+
+## 0.5.0 — 2026-08-29
+
+- **Agent-level what-if** — `branch_agent(fn, run, mutations)`: re-run the
+  actual agent function against a mutated cassette. Unlike `branch()`
+  (request-sequence replay), the full run shape — logs, tool calls, spans,
+  downstream requests — is regenerated for real, and `diff_runs` pins the
+  first divergence at the exact event where the mutation took effect.
+  `examples/what_if.py` demonstrates both levels.
+
+## 0.4.1 — 2026-08-29
+
+- **Viewer i18n** — the local viewer is now Chinese-first with an EN/中文
+  toggle in the header (choice persisted in localStorage); share files
+  inherit the same interface. README screenshots updated.
+- `share` also inlines the new `i18n.js` asset.
+
+## 0.4.0 — 2026-08-29
+
+Multi-provider release: Anthropic natively, TypeScript SDK, export/share/TUI.
+
+- **Anthropic native** — `rec.capture_anthropic(client)`: sync/async/
+  streaming capture of the Messages API (text + tool_use blocks), events
+  recorded with `provider="anthropic"` and usage normalized to
+  `prompt_tokens`/`completion_tokens` so costs/diffs work cross-provider.
+  `backspin proxy` gains a `/v1/messages` adapter (record + replay,
+  streaming included) — verified end-to-end against the real anthropic SDK.
+- **TypeScript SDK** (`sdks/typescript`, `@backspin/sdk`) — Recorder with
+  AsyncLocalStorage spans, `captureOpenAI` (sync/async/streaming),
+  `Cassette`/`stubClient` replay, `diffRuns`. Same `.backspin.jsonl` run
+  format — Python recordings replay in TypeScript and vice versa. 6 node:test
+  suites.
+- **Dataset export** — `backspin export <run> --format pairs|sft` turns
+  recordings into eval/fine-tune JSONL.
+- **Single-file sharing** — `backspin share <run>` bundles the run + the
+  whole viewer into one HTML file; opens in any browser, zero install.
+- **TUI** — `backspin tui`: keyboard-driven terminal viewer (runs → timeline
+  → step JSON), injectable IO, fully unit-tested.
+- Python suite: 104 tests; TypeScript suite: 6 tests.
+
+## 0.3.0 — 2026-08-29
+
+The "real debugger" release: what-if branching, zero-code proxy
+integration, structured spans, and costs.
+
+- **What-if branching** — `Cassette.mutate()` alters a recorded answer;
+  `backspin.replay.branch()` records the mutated replay as a new run
+  (`branch_of` metadata), rewriting downstream requests so mutations
+  propagate; `diff_runs(..., llm_only=True)` and
+  `backspin branch <file> --step N --content "..."` pinpoint where the
+  timelines split.
+- **`backspin proxy`** — OpenAI-compatible local proxy in two modes:
+  *record* (forward to upstream, capture everything, streaming included —
+  zero-code integration for any framework/language) and *replay* (serve a
+  recorded run back as an API, no network). Authorization headers are
+  forwarded but never recorded.
+- **Spans** — `with rec.span(name, meta=...)`: nested agent → tool →
+  sub-LLM structure. Events carry `span_id`/`depth`; async-safe via
+  contextvars (per-task stacks); exceptions recorded on the exit event;
+  span durations excluded from run totals to avoid double counting.
+- **Costs** — built-in per-1M-token price table (OpenAI, Claude, Gemini,
+  DeepSeek; exact-then-longest-prefix matching), `cost_usd` /
+  `cost_complete` in run totals, cost card in the viewer, `~$` in `show`.
+- **pytest plugin** — `backspin` fixture (pytest11 entry point) with
+  strict `assert_replays_identically()`: order-fallback replays are
+  failures, only fingerprint-exact replay passes.
+- **Viewer** — span tree indentation, cost card.
+- **Docs** — `docs/format-spec.md` (the run file specification with
+  versioning rules) and `docs/architecture.md`.
+- Internal: diff signatures understand span events; `_usage_of` fixes
+  streamed usage extraction; stream wrappers gain context-manager/close
+  passthrough.
+
+## 0.2.0 — 2026-08-29
+
+Hardening release: the record → replay → diff → view loop is now verified
+against the real OpenAI SDK and guarded by edge-case and performance tests.
+
+- **Real-SDK integration suite** — a local OpenAI-compatible HTTP/SSE mock
+  server runs the genuine `openai` SDK through sync, async, streaming
+  (tool-call deltas, `include_usage`), context-manager and error paths.
+  Found and fixed two real bugs:
+  - async resource detection (modern SDKs ship async methods that are not
+    coroutine functions — detection now uses the resource type name)
+  - streamed `usage` chunks were dropped in stream reconstruction
+- **Redaction API** — `Recorder(redact=...)` plus
+  `backspin.redaction.redact_strings` / `mask`. Structural fields (model,
+  tool name, fingerprint, durations) stay in clear; every other payload
+  value — including unknown custom keys — goes through the redactor.
+  Fingerprints are computed pre-redaction so replay matching is unaffected.
+- **Streaming wrappers** now pass through `close()`, the async/with context
+  manager protocols and positional args.
+- **Performance guards** — 20k-event record/load and 2×4000-event diff stay
+  in the seconds range.
+- **Edge-case suite** — unicode round-trips, concurrent recorders,
+  thread-safe single recorder, writes after close, circular references,
+  empty cassettes, corrupt run files over the viewer API, CLI `--json`.
+- **Packaging** — wheel verified to ship the viewer UI assets and
+  `py.typed`.
+
+## 0.1.0 — 2026-08-29
+
+Initial MVP.
+
+- `Recorder`: single-file JSONL run format (`.backspin.jsonl`), header +
+  ordered steps, error capture with tracebacks, custom events
+- OpenAI-shaped capture: sync / async / streaming, tool-call reconstruction
+- `@rec.tool` decorator (sync + async)
+- Deterministic replay: `Cassette`, `stub_client`, `patch_openai`
+  (fingerprint match, order fallback with warning)
+- `diff_runs`: step alignment by signature, first-divergence detection
+- CLI: `backspin ls / show / diff / ui`
+- Local viewer: FastAPI + zero-build vanilla JS (waterfall timeline, step
+  inspector, side-by-side diff)
+- `backspin.testing.FakeOpenAI` for keyless demos and tests

backspin-0.5.1/CODE_OF_CONDUCT.md

@@ -0,0 +1,65 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity and
+orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances
+  of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards
+of acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies
+when an individual is officially representing the community in public spaces.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement via a private
+message to the maintainers or via [GitHub's private vulnerability/advisory
+channel](https://github.com/zaibuchihuoji/backspin/security/advisories/new) if
+private. All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant](
+https://www.contributor-covenant.org), version 2.1, available at
+https://www.contributor-covenant.org/version/2/1/code_of_conduct.html.

backspin-0.5.1/CONTRIBUTING.md

@@ -0,0 +1,47 @@
+# Contributing to backspin
+
+Thanks for helping make agent debugging less painful.
+
+## Setup
+
+```bash
+git clone <your fork>
+cd backspin
+python -m venv .venv && source .venv/bin/activate  # Windows: .venv\Scripts\activate
+pip install -e ".[dev]"
+pytest
+ruff check backspin/ tests/   # must be clean
+mypy backspin/                # must be clean
+```
+
+`pytest` runs the full suite, including the real-SDK integration tests
+(they talk to a local OpenAI-compatible mock server — no network, no API
+key needed). `pip install pre-commit && pre-commit install` wires the same
+lint into your commits.
+
+## Ground rules
+
+- **Core stays dependency-free.** `backspin/` (except the `ui` extra)
+  must import nothing beyond the standard library. If you need a library,
+  it belongs in an extra or in the test suite.
+- **A recorder must never crash the agent.** Serialization problems degrade
+  to reprs; exceptions in recorded code are captured and re-raised. Keep it
+  that way.
+- **Every behavior change needs a test.** If it touches the run format,
+  add a round-trip test (record → `load_run` → assert).
+- **The run file format is a contract.** Bump `SCHEMA_VERSION` in
+  `runfile.py` and document the change in `CHANGELOG.md` if you must break
+  it — then keep `load_run` able to read old files.
+
+## Style
+
+- Type-hinted Python, `from __future__ import annotations`, 3.9+ compatible.
+- ASCII-only CLI output (Windows consoles); unicode is fine in file content.
+- Comments explain constraints, not mechanics.
+
+## Submitting
+
+1. Branch from `main`.
+2. `pytest` green, `ruff check` and `mypy` clean — CI enforces all three.
+3. Update `CHANGELOG.md` under an "Unreleased" heading.
+4. Open a PR describing the user-visible change (the template has the checklist).

backspin-0.5.1/LICENSE

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