vapviz 1.0.1__tar.gz

vapviz-1.0.1/.claude/launch.json

@@ -0,0 +1,11 @@
+{
+  "version": "0.0.1",
+  "configurations": [
+    {
+      "name": "vap-ui",
+      "runtimeExecutable": "cmd",
+      "runtimeArgs": ["/c", "cd ui && npm run dev"],
+      "port": 5173
+    }
+  ]
+}

vapviz-1.0.1/.dockerignore

@@ -0,0 +1,28 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+dist/
+build/
+.pytest_cache/
+
+# Node
+ui/node_modules/
+ui/dist/
+
+# Data / secrets
+*.db
+*.db-wal
+*.db-shm
+.env
+*.env
+
+# Dev artifacts
+.git/
+docs/screenshot.png
+take_screenshot.py
+
+# OS
+.DS_Store
+Thumbs.db

vapviz-1.0.1/.github/workflows/ci.yml

@@ -0,0 +1,111 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+# Cancel superseded runs on the same ref.
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: tests (py${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      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 }}
+          cache: pip
+          cache-dependency-path: pyproject.toml
+
+      - name: Install package + dev deps
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Run test suite
+        run: pytest -q
+
+  ui:
+    name: ui build
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: ui
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          cache: npm
+          cache-dependency-path: ui/package-lock.json
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Type-check and build
+        run: npm run build
+
+  package:
+    name: build & check package
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          cache: npm
+          cache-dependency-path: ui/package-lock.json
+
+      - name: Build the UI and stage it into the package
+        run: |
+          cd ui && npm ci && npm run build && cd ..
+          rm -rf vapviz/_static
+          cp -r ui/dist vapviz/_static
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Build sdist and wheel
+        run: |
+          python -m pip install --upgrade pip build twine
+          python -m build
+
+      - name: Verify the UI is bundled in the wheel
+        run: |
+          python - <<'PY'
+          import zipfile, glob
+          whl = glob.glob("dist/*.whl")[0]
+          names = zipfile.ZipFile(whl).namelist()
+          assert "vapviz/_static/index.html" in names, "UI not bundled in wheel"
+          print("OK: UI bundled in", whl)
+          PY
+
+      - name: Check distribution metadata
+        run: python -m twine check dist/*
+
+      - name: Upload distribution artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/*

vapviz-1.0.1/.github/workflows/release.yml

@@ -0,0 +1,78 @@
+name: Release
+
+# Publishes to PyPI when a version tag (e.g. v0.8.0) is pushed.
+#
+# Uses PyPI Trusted Publishing (OIDC) — no API token/secret required. One-time
+# setup on PyPI: Project → Settings → Publishing → add a GitHub publisher with
+#   owner: kochrisdev   repo: vapviz   workflow: release.yml   environment: pypi
+# See https://docs.pypi.org/trusted-publishers/
+
+on:
+  push:
+    tags: ["v*.*.*"]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: build distribution
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          cache: npm
+          cache-dependency-path: ui/package-lock.json
+
+      - name: Build the UI and stage it into the package
+        run: |
+          cd ui && npm ci && npm run build && cd ..
+          rm -rf vapviz/_static
+          cp -r ui/dist vapviz/_static
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Build sdist and wheel
+        run: |
+          python -m pip install --upgrade pip build twine
+          python -m build
+
+      - name: Check distribution metadata
+        run: python -m twine check dist/*
+
+      - name: Verify tag matches package version
+        run: |
+          TAG="${GITHUB_REF_NAME#v}"
+          PKG=$(ls dist/*.tar.gz | sed -E 's/.*-([0-9][^-]*)\.tar\.gz/\1/')
+          echo "tag=$TAG package=$PKG"
+          test "$TAG" = "$PKG"
+
+      - name: Upload distribution artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/*
+
+  publish:
+    name: publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write   # required for OIDC trusted publishing
+    steps:
+      - name: Download distribution artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

vapviz-1.0.1/.gitignore

@@ -0,0 +1,49 @@
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+.Python
+*.egg-info/
+dist/
+build/
+.venv/
+venv/
+env/
+.env
+*.egg
+
+# Node
+ui/node_modules/
+ui/dist/
+ui/.vite/
+
+# Bundled UI copied into the package at build time
+vapviz/_static/
+
+# Logs
+*.log
+/logs/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# Temp
+/C:/Temp/
+
+# Runtime data — local SQLite stores and server logs
+vapviz.db
+vapviz.db-shm
+vapviz.db-wal
+*.db
+*.db-shm
+*.db-wal
+.vap_server.out
+.vap_server.err

vapviz-1.0.1/CHANGELOG.md

@@ -0,0 +1,102 @@
+# Changelog
+
+All notable changes to vapviz are documented here. The format is based on
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+For the detailed per-release notes (APIs, fixes, internals), see the
+[Developer Reference changelog](docs/DEVELOPER_REFERENCE.md#changelog).
+
+## [Unreleased]
+
+_Nothing yet._
+
+## [1.0.1]
+
+### Changed
+- **Renamed the project to `vapviz`.** The PyPI name `vap` was already taken by an unrelated
+  project, so the distribution, the import package, and the CLI are all `vapviz` now:
+  `pip install vapviz`, `import vapviz`, `vapviz serve`. (The `Vap*` public class names — `VapEvent`,
+  `VapPydanticAI`, etc. — are unchanged.)
+
+## [1.0.0]
+
+First stable release. The public API now follows [Semantic Versioning](https://semver.org/) — see
+the [Versioning & Stability](README.md#versioning--stability) section for the tracked surface.
+
+### Added
+- The published wheel bundles the built React UI, so `pip install vapviz && vapviz serve` serves the full UI with no Node build (`vapviz serve` auto-detects the bundled UI; `--static-dir` still overrides).
+- Root `CHANGELOG.md` and a documented public-API stability policy.
+- Anthropic integration tests (`tests/test_anthropic_patch.py`), closing the last integration coverage gap (269 tests).
+
+### Changed
+- Promoted to `Development Status :: 5 - Production/Stable`.
+
+This release adds no new tracing/integration features beyond 0.15.0 — it marks the project as stable. The capability set: 7 framework integrations (Anthropic, OpenAI, LangChain, CrewAI, Pydantic AI, LlamaIndex, AutoGen), OpenTelemetry export, an analytics dashboard, cost/latency budgets with alerting, agent evals & scoring, run search & tagging, and trace replay.
+
+## [0.15.0]
+### Added
+- Trace replay / time-travel: a UI scrubber (`ReplayBar`) that replays a run event-by-event; the graph fills in node by node.
+
+## [0.14.0]
+### Added
+- Run search (`GET /search`) across run labels and node inputs/outputs, with `status` / `kind` / `tool` / `tag` filters.
+- Persistent per-run tags (`GET`/`PUT /runs/{id}/tags`, stored in SQLite); UI search box, tag chips, and inline tag editor.
+
+## [0.13.0]
+### Added
+- Agent evals & scoring: `eval_run(run, [checks…])` → `EvalResult` with built-in `max_cost` / `max_latency` / `max_tokens` / `no_errors` / `output_contains` plus `custom` and `judge` hooks; declarative `POST /runs/{id}/eval`.
+
+## [0.12.0]
+### Added
+- Cost & latency budgets: `Budget`, `check_budget()`, `enable_budget_alerts(budget, on_alert=…)`, and `GET /runs/{id}/budget`.
+
+## [0.11.0]
+### Added
+- AutoGen (AG2) integration: `VapAutoGen` traces `ConversableAgent` conversations (chat, agent turns, tool calls).
+
+## [0.10.0]
+### Added
+- LlamaIndex integration: `VapLlamaIndex` span handler traces query engines, retrievers, embeddings, and LLM calls.
+
+## [0.9.0]
+### Added
+- OpenTelemetry export: `enable_otel_export(...)` mirrors each run into OTLP spans (Jaeger / Grafana Tempo / Datadog).
+
+## [0.8.0]
+### Added
+- Pydantic AI integration: `VapPydanticAI` traces `Agent.run` / `run_sync` (model requests + tool calls).
+- PyPI-ready packaging (license, classifiers, URLs), MIT `LICENSE`, GitHub Actions CI + release workflows, and `CONTRIBUTING.md`.
+
+## [0.7.0]
+### Added
+- Analytics dashboard + `GET /metrics`: cross-run cost, tokens, success rate, per-model breakdown, and cost-over-time.
+
+## [0.6.0]
+### Added
+- CrewAI integration: `VapCrewAIListener` traces Crews, Tasks, Agent executions, Tool calls, and LLM round-trips.
+
+## [0.5.0]
+### Added
+- Run comparison (side-by-side diff) and export (JSON download + PNG capture).
+
+## [0.4.0]
+### Added
+- Token cost tracking: pricing table, `calculate_cost()`, per-node cost overlay, per-run totals.
+
+## [0.3.0]
+### Added
+- OpenAI SDK and LangChain / LangGraph integrations.
+
+## [0.2.0]
+### Added
+- Async tracer (`atrace` / `astep`), SQLite persistence, the `vapviz serve` CLI.
+
+## [0.1.0]
+### Added
+- Initial release: sync tracer, in-memory store, FastAPI + SSE server, ReactFlow UI, Anthropic SDK integration.
+
+[Unreleased]: https://github.com/kochrisdev/vapviz/compare/v1.0.1...HEAD
+[1.0.1]: https://github.com/kochrisdev/vapviz/releases/tag/v1.0.1
+[1.0.0]: https://github.com/kochrisdev/vapviz/releases/tag/v1.0.0
+[0.15.0]: https://github.com/kochrisdev/vapviz/releases/tag/v0.15.0

vapviz-1.0.1/CONTRIBUTING.md

@@ -0,0 +1,161 @@
+# Contributing to vapviz
+
+Thanks for your interest in improving vapviz! This guide covers how to set up a
+development environment, the checks your change needs to pass, and how to get a
+pull request merged.
+
+By participating, you agree that your contributions will be licensed under the
+project's [MIT License](LICENSE).
+
+---
+
+## Ways to contribute
+
+- **Report a bug** or **request a feature** — open an
+  [issue](https://github.com/kochrisdev/vapviz/issues). For bugs, include the vapviz
+  version, Python version, a minimal repro, and the expected vs. actual behaviour.
+- **Improve the docs** — fixes to `README.md` or anything under `docs/` are very
+  welcome and make great first contributions.
+- **Send a pull request** — see the workflow below. For anything non-trivial,
+  please open an issue first so we can agree on the approach before you build it.
+
+---
+
+## Development setup
+
+vapviz is a Python package (`vapviz/`) plus a Vite + React UI (`ui/`). You need
+**Python 3.11+** and **Node 20+**.
+
+```bash
+git clone https://github.com/kochrisdev/vapviz.git
+cd vapviz
+
+# Python — editable install with all integrations + test/dev tooling
+pip install -e ".[dev]"
+
+# UI
+cd ui && npm ci && cd ..
+```
+
+Run the whole thing locally (server + a demo agent, hot-reloading UI):
+
+```bash
+python run_dev.py            # server + demo on http://localhost:8001
+# in another terminal:
+cd ui && npm run dev         # UI dev server on http://localhost:5173
+```
+
+---
+
+## Checks your change must pass
+
+CI ([`.github/workflows/ci.yml`](.github/workflows/ci.yml)) runs these on every
+push and pull request to `main`. Run them locally before pushing:
+
+```bash
+# Python test suite — 269 tests; integration tests skip automatically
+# when their framework (crewai, pydantic-ai, langchain, …) isn't installed
+pytest -q
+
+# UI type-check + production build
+cd ui && npm run build && cd ..
+
+# Package builds cleanly and its metadata is valid
+python -m build
+python -m twine check dist/*
+```
+
+CI runs the test suite against Python 3.11, 3.12, and 3.13, so avoid
+version-specific APIs.
+
+---
+
+## Coding guidelines
+
+- **Match the surrounding code.** Mirror the existing naming, comment density,
+  and idioms in the file you're editing rather than introducing a new style.
+- **Type everything.** The package ships type hints (`Typing :: Typed`); keep new
+  Python code annotated and new TypeScript code free of `any` where practical.
+- **Tests are required for behaviour changes.** Add or update tests under
+  `tests/`. Keep them hermetic — no network calls or API keys. The integration
+  tests use each framework's built-in fakes (e.g. Pydantic AI's `TestModel`,
+  mocked SDK clients) and `pytest.importorskip` so the suite stays green even
+  when the optional dependency is absent.
+- **Keep tracing best-effort.** Instrumentation must never break the user's
+  agent — failures in a listener/patch should be swallowed, not raised.
+- **Update the docs.** If you change public behaviour, update the relevant file
+  in `docs/` (and `README.md` where it overlaps) in the same PR.
+
+Get oriented with the
+[Project Structure](README.md#project-structure) section and
+[`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md).
+
+### Adding a new framework integration
+
+Integrations live in `vapviz/integrations/` and follow one of two patterns
+(SDK monkey-patch, or event-bus/listener) described in the
+[Extension Guide](docs/ARCHITECTURE.md#extension-guide). When you add one:
+
+1. Implement it in `vapviz/integrations/<name>.py`, reusing `vapviz.calculate_cost`
+   for LLM cost and emitting standard `VapEvent`s so it works with the existing
+   store, server, and UI unchanged.
+2. Add an optional extra in `pyproject.toml` (and to the `all` / `dev` groups).
+3. Add `tests/test_<name>.py`, guarded with
+   `pytest.importorskip("<package>")` and using the framework's test doubles.
+4. Add an `examples/<name>_demo.py` and document it in `README.md`,
+   `docs/TUTORIAL.md`, `docs/ARCHITECTURE.md`, and `docs/DEVELOPER_REFERENCE.md`.
+
+---
+
+## Commit messages
+
+This repo uses [Conventional Commits](https://www.conventionalcommits.org/).
+Prefix the subject with the change type, e.g.:
+
+```
+feat(pydantic-ai): trace Pydantic AI agents
+fix(tests): reset _current_step ContextVar between tests
+docs: document the analytics dashboard
+ci: add GitHub Actions CI/release + PyPI release metadata
+```
+
+Common types: `feat`, `fix`, `docs`, `test`, `refactor`, `perf`, `ci`, `chore`.
+Keep the subject in the imperative mood and under ~72 characters; put detail and
+rationale in the body.
+
+---
+
+## Pull request workflow
+
+1. Fork the repo (or create a branch if you have write access) — don't commit
+   directly to `main`.
+2. Make your change with tests and docs updated.
+3. Run the [checks above](#checks-your-change-must-pass) locally.
+4. Open a PR against `main` with a clear description of **what** changed and
+   **why**. Link any related issue.
+5. Make sure CI is green — PRs are merged only when all jobs pass.
+
+Small, focused PRs are reviewed fastest. If a change is large, consider splitting
+it (e.g. one PR for the feature, one for docs).
+
+---
+
+## Releasing (maintainers)
+
+Releases are tag-driven and publish to PyPI via
+[Trusted Publishing](https://docs.pypi.org/trusted-publishers/) — no API tokens.
+
+1. Bump `version` in [`pyproject.toml`](pyproject.toml) and add a changelog entry
+   in [`docs/DEVELOPER_REFERENCE.md`](docs/DEVELOPER_REFERENCE.md#changelog).
+2. Commit, then tag and push:
+   ```bash
+   git tag v0.8.0 && git push origin v0.8.0
+   ```
+3. [`.github/workflows/release.yml`](.github/workflows/release.yml) builds the
+   distribution, verifies the tag matches the package version, and publishes to
+   PyPI. (Requires the one-time PyPI publisher configuration noted in that
+   workflow's header.)
+
+---
+
+Questions? Open an [issue](https://github.com/kochrisdev/vapviz/issues) — happy to help.

vapviz-1.0.1/Dockerfile

@@ -0,0 +1,40 @@
+# ── Stage 1: Build the React UI ───────────────────────────────────────────────
+FROM node:20-alpine AS ui-builder
+
+WORKDIR /app/ui
+COPY ui/package*.json ./
+RUN npm ci
+COPY ui/ .
+RUN npm run build          # output → /app/ui/dist
+
+
+# ── Stage 2: Python runtime ───────────────────────────────────────────────────
+FROM python:3.11-slim
+
+# System deps (SQLite is bundled with Python — no extra install needed)
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /app
+
+# Install Python package
+COPY pyproject.toml ./
+COPY vapviz/ ./vapviz/
+RUN pip install --no-cache-dir -e .
+
+# Copy built UI from stage 1
+COPY --from=ui-builder /app/ui/dist ./ui/dist
+
+# Data directory for SQLite persistence (mount a volume here)
+RUN mkdir -p /data
+
+EXPOSE 8001
+
+# Default: persist to /data/vapviz.db and serve the built UI.
+# Override CMD or set env vars at runtime to customise.
+CMD ["vapviz", "serve", \
+     "--host", "0.0.0.0", \
+     "--port", "8001", \
+     "--db", "/data/vapviz.db", \
+     "--static-dir", "ui/dist", \
+     "--log-level", "info"]

vapviz-1.0.1/LICENSE

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