clustertrace 0.5.0__tar.gz

clustertrace-0.5.0/.github/ISSUE_TEMPLATE/bug.yml

@@ -0,0 +1,45 @@
+name: Bug report
+description: Something doesn't work the way the README says it does.
+labels: ["bug"]
+body:
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: What happened?
+      description: Quick description of the broken behaviour and what you expected.
+      placeholder: "@clustertrace.trace on my async function logs duration=None instead of the actual ms."
+    validations:
+      required: true
+  - type: textarea
+    id: repro
+    attributes:
+      label: Minimal reproduction
+      description: A code snippet that triggers it. Include any flags / env vars (`CLUSTERTRACE_DB`, etc.).
+      render: python
+    validations:
+      required: true
+  - type: input
+    id: version
+    attributes:
+      label: clustertrace version
+      description: Output of `clustertrace --version`.
+      placeholder: "0.3.0"
+    validations:
+      required: true
+  - type: input
+    id: python
+    attributes:
+      label: Python version
+      placeholder: "3.12.4"
+    validations:
+      required: true
+  - type: input
+    id: os
+    attributes:
+      label: OS
+      placeholder: "macOS 14 / Ubuntu 22.04 / Windows 11"
+  - type: textarea
+    id: extras
+    attributes:
+      label: Anything else?
+      description: Logs, stack traces, full trace IDs, anything that helps narrow it down.

clustertrace-0.5.0/.github/ISSUE_TEMPLATE/feature.yml

@@ -0,0 +1,23 @@
+name: Feature request
+description: Propose a new feature or behaviour change.
+labels: ["enhancement"]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: What problem are you trying to solve?
+      description: The concrete situation that made you wish clustertrace did this. Skip "wouldn't it be cool if…".
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed shape of the fix
+      description: API sketch, screenshot, or rough mechanism. Doesn't need to be final.
+    validations:
+      required: true
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: What would you do instead today?
+      description: Workarounds, other tools that have it, why the workarounds aren't enough.

clustertrace-0.5.0/.github/ISSUE_TEMPLATE/good_first_issue_reorder_clustering.md

@@ -0,0 +1,42 @@
+---
+name: 'Wanted: tree-edit-distance clustering mode'
+about: Help wanted — better clustering for traces that differ by reorderings
+title: 'Add mode=''tree_edit'' to signature_for_spans (reorder + insertion tolerance)'
+labels: enhancement, help wanted, algorithm
+assignees: ''
+---
+
+## What
+
+Today clustertrace has two clustering modes:
+- `mode='ordered'` — exact-string equality on RLE-collapsed sequence
+- `mode='set'` — sorted unique pairs (collapses all reorderings)
+
+Both are extremes. We want a middle ground: a signature mode that tolerates small reorderings and insertions (e.g. one extra retry, two tool calls swapped) but still distinguishes structurally different paths.
+
+## Why
+
+Real agents are noisy. With `mode='ordered'` you get 100+ clusters from 1000 traces (one extra retry creates a new cluster). With `mode='set'` you collapse everything that has the same step inventory regardless of order — too coarse.
+
+Tree-edit-distance or Levenshtein on the step sequence would give a tunable threshold.
+
+## Design sketch
+
+```python
+def signature_for_spans(spans, mode='ordered', edit_distance_threshold=None):
+    if mode == 'tree_edit':
+        # Compute a normalized step sequence
+        # Bucket traces whose pairwise edit distance < threshold
+        ...
+```
+
+Storage implication: the canonical signature for a cluster becomes the "representative" sequence; non-canonical traces store a reference. This needs a `signature_canonical_id` column on traces (v4 migration).
+
+## Pointers
+
+- [`src/clustertrace/cluster.py`](../../src/clustertrace/cluster.py).
+- [Wagner-Fischer algorithm](https://en.wikipedia.org/wiki/Wagner%E2%80%93Fischer_algorithm) is the obvious starting point.
+- [Zhang-Shasha](https://epubs.siam.org/doi/10.1137/0218082) for the tree-edit-distance variant if you want hierarchical structure too.
+- This is real algorithmic work; not a 4-hour PR.
+
+Estimated effort: a weekend of focused work + a benchmark showing it's better than `mode='set'` on real data.

clustertrace-0.5.0/.github/ISSUE_TEMPLATE/good_first_issue_streaming_capture.md

@@ -0,0 +1,32 @@
+---
+name: 'Wanted: streaming chunk capture'
+about: Help wanted — capture streaming response chunks as they arrive
+title: 'Capture streaming response chunks instead of completion-only'
+labels: enhancement, help wanted
+assignees: ''
+---
+
+## What
+
+Today, when you call `messages.create(stream=True)` or `chat.completions.create(stream=True)`, clustertrace records the span on completion only and tags it with `streaming: true`. It does **not** capture the intermediate chunks.
+
+We want: chunk-by-chunk capture so debugging an agent that gets stuck mid-stream (or fails partway through) is possible.
+
+## Why
+
+Streaming is the default for most production agents. Without chunk capture, clustertrace is invisible to that workflow.
+
+## Design sketch
+
+- Wrap the returned stream/iterator in a `_StreamingResponseWrapper`.
+- On each `__next__`, append to an in-memory list on the wrapper.
+- On `__exit__` / `StopIteration`, write the accumulated chunks into `spans.output_json` as a list, plus a `chunks_received: N` attr.
+- Be careful with the OpenAI streaming context manager (`with client.chat.completions.create(stream=True) as stream:`) — needs `__enter__` / `__exit__` proxies.
+- Handle async streams (`async for chunk in stream`) too — `__aiter__` / `__anext__`.
+
+## Pointers
+
+- [`src/clustertrace/anthropic.py`](../../src/clustertrace/anthropic.py) `_WrappedMessages.create`.
+- [`src/clustertrace/openai.py`](../../src/clustertrace/openai.py) `_WrappedCompletions.create`.
+
+Estimated effort: 300 LOC + 200 LOC tests, a full day. The fiddly bits are sync vs async + context-manager vs iterator semantics.

clustertrace-0.5.0/.github/ISSUE_TEMPLATE/good_first_issue_wrap_bedrock.md

@@ -0,0 +1,27 @@
+---
+name: 'Wanted: native wrap_bedrock'
+about: Help wanted — native AWS Bedrock wrapper for non-Anthropic-SDK paths
+title: 'Add wrap_bedrock for the boto3 Bedrock runtime client'
+labels: enhancement, good first issue, help wanted
+assignees: ''
+---
+
+## What
+
+A native `clustertrace.wrap_bedrock(client)` that wraps `boto3.client("bedrock-runtime")` and logs `invoke_model` / `invoke_model_with_response_stream` calls.
+
+## Why
+
+Today, Bedrock works through `wrap_anthropic(AnthropicBedrock())` — but a lot of users hit Bedrock via the raw `boto3` client, which doesn't expose `.messages.create`. A native wrapper closes the gap and broadens addressable users meaningfully.
+
+## Pointers
+
+- Mirror the pattern in [`src/clustertrace/anthropic.py`](../../src/clustertrace/anthropic.py): `_record_*_span`, `_finish`, `_WrappedClient`.
+- Parse Bedrock's `body` (it's a JSON-encoded string) to extract the model, input, output, and usage.
+- Add `boto3` as an optional install extra: `clustertrace[bedrock]`.
+- Add a price entry in [`src/clustertrace/cost.py`](../../src/clustertrace/cost.py) for the Bedrock model IDs you support (`anthropic.claude-*-v2`, `meta.llama3-*`, etc.).
+- Write `tests/test_wrap_bedrock.py` against a `FakeBedrockClient` (no AWS credentials needed).
+
+[CONTRIBUTING.md](../../CONTRIBUTING.md) has the step-by-step recipe.
+
+Estimated effort: 250 LOC code + 150 LOC tests, half a day.

clustertrace-0.5.0/.github/ISSUE_TEMPLATE/good_first_issue_wrap_gemini.md

@@ -0,0 +1,30 @@
+---
+name: 'Wanted: native wrap_gemini'
+about: Help wanted — native Google Gemini wrapper
+title: 'Add wrap_gemini for google-genai SDK'
+labels: enhancement, good first issue, help wanted
+assignees: ''
+---
+
+## What
+
+`clustertrace.wrap_gemini(client)` wrapping the `google.genai.Client.models.generate_content` (and the streaming + async variants).
+
+## Why
+
+Gemini works through OpenTelemetry today, but a native wrapper:
+- captures fields the OTel auto-instrumentor doesn't (function-calling tool args, safety settings)
+- lands costs from the bundled pricing table without needing the OTel `gen_ai.*` attribute mapping
+- gives a more accurate `messages.create`-style span shape
+
+## Pointers
+
+- Mirror [`src/clustertrace/openai.py`](../../src/clustertrace/openai.py).
+- Watch out for sync vs async (`Client` vs `AsyncClient`).
+- Add `google-genai` as an extra: `clustertrace[gemini]`.
+- Add prices to [`src/clustertrace/cost.py`](../../src/clustertrace/cost.py) — `gemini-2.5-pro`, `gemini-2.5-flash`, etc.
+- Tests in `tests/test_wrap_gemini.py` against a `FakeGeminiClient`.
+
+[CONTRIBUTING.md](../../CONTRIBUTING.md) has the recipe.
+
+Estimated effort: 250 LOC code + 150 LOC tests, half a day.

clustertrace-0.5.0/.github/pull_request_template.md

@@ -0,0 +1,22 @@
+<!-- Thanks for sending a PR. Keep PRs small — one logical change per PR. -->
+
+## What this changes
+
+<!-- One or two sentences. -->
+
+## Why
+
+<!-- What problem does this solve? Link issue if relevant. -->
+
+## How
+
+<!-- Brief overview of the implementation choice and any trade-offs. -->
+
+## Checklist
+
+- [ ] `ruff check .` is clean
+- [ ] `pytest -q` is green
+- [ ] Added/updated tests for new behaviour
+- [ ] Updated README if the public API or pitch changed
+- [ ] If adding a new SDK wrapper, followed the steps in CONTRIBUTING.md
+- [ ] Appended a line to `STATUS.md`

clustertrace-0.5.0/.github/workflows/publish.yml

@@ -0,0 +1,66 @@
+name: publish to pypi
+
+# Triggers on any v* tag push. Uses PyPI's OIDC trusted-publisher flow —
+# no API tokens stored in the repo. Set up once at
+# https://pypi.org/manage/account/publishing/ with:
+#   owner=harrywinter06  repo=clustertrace
+#   workflow=publish.yml  environment=pypi  project=clustertrace
+
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build wheel + sdist
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v3
+        with:
+          enable-cache: false  # uv.lock is gitignored
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Build sdist + wheel
+        # `uv build` produces both without needing a venv or --system.
+        run: uv build
+
+      - name: Show artifacts
+        run: ls -la dist/
+
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    # Restrict OIDC to a named environment so a stolen token can't
+    # publish without an approval step on protected releases.
+    environment:
+      name: pypi
+      url: https://pypi.org/project/clustertrace/
+    permissions:
+      id-token: write  # required for OIDC
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        # No username/password — OIDC token is exchanged automatically.
+        # PyPI verifies the workflow filename + repo + environment match
+        # what you configured on the trusted-publisher page.

clustertrace-0.5.0/.github/workflows/release.yml

@@ -0,0 +1,65 @@
+name: github release
+
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: "Tag name (e.g. v0.5.0)"
+        required: true
+
+permissions:
+  contents: write  # required to create releases
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # need the full history for prev-tag lookup
+
+      - name: Extract release notes from CHANGELOG
+        id: notes
+        run: |
+          set -euo pipefail
+          if [ -n "${{ inputs.tag }}" ]; then
+            TAG="${{ inputs.tag }}"
+          else
+            TAG="${GITHUB_REF#refs/tags/}"
+          fi
+          VERSION="${TAG#v}"
+          echo "tag=$TAG" >> "$GITHUB_OUTPUT"
+          # Pull the section between "## [<version>]" and the next "## [" header.
+          NOTES=$(awk -v ver="$VERSION" '
+            /^## \[/ {
+              if (in_section) exit
+              if ($0 ~ "## \\["ver"\\]") { in_section=1; next }
+            }
+            in_section { print }
+          ' CHANGELOG.md)
+          if [ -z "$NOTES" ]; then
+            echo "no CHANGELOG section found for $VERSION; falling back to tag message"
+            NOTES=$(git tag -l --format="%(contents)" "$TAG")
+          fi
+          {
+            echo "notes<<EOF"
+            echo "$NOTES"
+            echo ""
+            echo "---"
+            echo ""
+            echo "Install: \`pip install clustertrace==$VERSION\`"
+            echo "Try: \`clustertrace demo\`"
+            echo "EOF"
+          } >> "$GITHUB_OUTPUT"
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          tag_name: ${{ steps.notes.outputs.tag || github.ref_name }}
+          name: ${{ steps.notes.outputs.tag || github.ref_name }}
+          body: ${{ steps.notes.outputs.notes }}
+          draft: false
+          prerelease: ${{ contains(github.ref_name, 'rc') || contains(github.ref_name, 'beta') || contains(github.ref_name, 'alpha') }}

clustertrace-0.5.0/.github/workflows/test.yml

@@ -0,0 +1,40 @@
+name: tests
+
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  test:
+    name: Python ${{ matrix.python }} on ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        python: ["3.11", "3.12", "3.13"]
+        os: [ubuntu-latest, macos-latest, windows-latest]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          enable-cache: false  # uv.lock is gitignored
+
+      - name: Set up Python ${{ matrix.python }}
+        run: uv python install ${{ matrix.python }}
+
+      - name: Create venv + install
+        # Use a venv (not --system) because the runner's host Python is
+        # externally managed (PEP 668) on Ubuntu/macOS.
+        run: |
+          uv venv --python ${{ matrix.python }}
+          uv pip install -e ".[anthropic,openai,dev]"
+
+      - name: Lint
+        run: uv run ruff check src tests examples
+
+      - name: Run tests
+        run: uv run pytest -q

clustertrace-0.5.0/.gitignore

@@ -0,0 +1,30 @@
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+.Python
+*.egg-info/
+.eggs/
+dist/
+build/
+.venv/
+venv/
+env/
+.env
+*.db
+*.db-journal
+*.db-wal
+*.db-shm
+.pytest_cache/
+.ruff_cache/
+.coverage
+.idea/
+.vscode/
+*.log
+.DS_Store
+Thumbs.db
+uv.lock
+demo-traces/
+
+# Internal strategy docs - not for public consumption
+_internal/

clustertrace-0.5.0/ARCHITECTURE.md

@@ -0,0 +1,105 @@
+# ARCHITECTURE
+
+This document explains the design choices in clustertrace. It's intentionally short — the codebase is small enough that you can read it end-to-end in an hour. Read this first.
+
+## Storage
+
+One SQLite file, WAL mode, schema versioned by a `schema_meta.version` row and a list of migration scripts in `storage._MIGRATIONS`. Adding a column or table = append a new script and bump `_SCHEMA_VERSION`. Migrations are applied in order, exactly once, by `_ensure_initialized` on first connect.
+
+There are five tables:
+
+| Table | Purpose |
+|---|---|
+| `traces` | one row per top-level trace (status, duration, signature, cost) |
+| `spans` | every span in every trace, parent-linked |
+| `trace_tags` | key/value tags filterable in the dashboard |
+| `trace_metrics` | numeric metrics from `clustertrace.metric()` for time-series charts |
+| `spans_fts` | FTS5 virtual table mirroring span name + I/O + error_message |
+
+The FTS5 table is kept in sync via three triggers (insert/update/delete on `spans`). When migration v3 runs on an existing DB, the table is backfilled inline.
+
+## Tracing
+
+`@clustertrace.trace` opens a span when the function is called and closes it on return or exception. Parent linkage uses `contextvars` — a `ContextVar` for `trace_id` and one for `span_id`. This is what makes async work without manual plumbing: `contextvars` propagate across `await` boundaries and `asyncio.gather`, so a span opened in a parent task is visible to spans opened in child tasks.
+
+The decorator distinguishes sync vs. async functions via `inspect.iscoroutinefunction(fn)` and dispatches to different code paths (`_sync_call_span` and `_AsyncCallSpan`) so that we never accidentally `await` a non-coroutine or block on a coroutine.
+
+## Signatures and clustering
+
+The differentiator. A trace's *signature* is the ordered sequence of `(normalized_name, status)` pairs from its non-root spans, with consecutive duplicates collapsed (RLE). Two traces with the same signature took the same execution path. Clustering by signature reveals the distinct ways an agent runs.
+
+Three design choices worth justifying:
+
+**Why exact-string equality, not fuzzy?** Trade-offs in v0.3:
+
+| Approach | Pros | Cons |
+|---|---|---|
+| Exact ordered + RLE | Cheap, deterministic, easy to explain | Reorderings split clusters |
+| Set-of-edges | Reorder-insensitive | Loses order information that's often diagnostic |
+| Tree-edit distance | Captures intuitive similarity | O(n²) per pair, expensive at scale |
+| Learned embeddings | Captures semantic similarity | Adds ML dep, opaque, harder to debug |
+
+For v0.3 we go with the simple approach. Reorder-insensitive clustering is a real gap and is on the v0.4 list. Fuzzy clustering on top of the exact signatures is straightforward to layer in later.
+
+**Why normalize LLM-call names by provider, not by model?** Because changing models is the most common thing an agent dev does, and we don't want every prompt-tuning iteration to fragment your clusters into N×(number of models) groups. The model is preserved in span attributes; clustering uses the provider prefix only.
+
+**Why collapse consecutive duplicates (RLE)?** Agents loop. "Fetched 3 papers" and "fetched 5 papers" are the same execution shape. RLE collapse keeps the cluster count manageable.
+
+The cost: RLE means "loop ran 3 times" and "loop ran 30 times" look identical. There's no flag to disable it yet; if you need to distinguish, the per-span data is still in the spans table.
+
+## OpenTelemetry ingestion
+
+`clustertrace.otel.ClustertraceSpanExporter` implements the OTel exporter protocol (`export`, `shutdown`, `force_flush`) and writes received spans directly into the SQLite store. The mapping:
+
+- OTel `trace_id` (16 bytes → 32 hex chars) → `traces.id`
+- OTel `span_id` (8 bytes → 16 hex chars) → `spans.id`
+- OTel `attributes` → `spans.attrs_json`
+- OTel `gen_ai.*` / `llm.*` attributes → mapped onto clustertrace's conventions so the cost module works
+- OTel `events` with `name=exception` → `spans.error_type` / `error_message`
+- OTel parent context → `spans.parent_id`
+
+Why ingestion, not export? The clustering page only works if all your traces live in one store. We let users keep their existing OTel instrumentation and route it to us.
+
+## Cost
+
+`clustertrace.cost.PRICING` is a dict keyed by model id mapping to `(input_per_million, output_per_million)` in USD. `estimate_span_cost(attrs)` looks up the model (exact match → date-suffix strip → longest-prefix match) and multiplies by the captured input/output token counts.
+
+`cost.backfill()` walks every `kind='llm_call'` span, computes its cost, writes it to `spans.cost_usd`, then rolls up per trace into `traces.cost_usd`. The dashboard surfaces these in the recent-traces list, the trace detail page, the snapshot HTML, and the header.
+
+Users can override or extend the pricing table at runtime via `$CLUSTERTRACE_PRICING_JSON='{"some-model": [2.0, 10.0]}'`.
+
+## Replay
+
+`clustertrace replay <trace_id> --entry module:function` imports the named entrypoint, reads the captured `args`/`kwargs` from the trace's root span input, and re-invokes the function. The new trace is tagged `replay_of=<original_id>` so the dashboard can pair them.
+
+Limitations are intentional:
+
+- The entrypoint module must be importable in the current Python env (you can't replay a trace from a different codebase without putting that code on the path).
+- Non-JSON-serializable args (file handles, sockets) don't round-trip.
+- Truncated root inputs (the `__truncated` marker) refuse to replay because the result wouldn't match the original.
+
+Replay-with-modified-prompt is the natural extension — same machinery, but with a stage that lets you edit the captured kwargs before the re-invocation. v0.4 target.
+
+## Wrappers
+
+`wrap_anthropic` and `wrap_openai` are explicit: you pass an instance, you get a wrapped instance back. No global monkey-patching, no import-time side effects. The wrapper detects sync vs. async by class name (`AsyncAnthropic`, `AsyncOpenAI`) and exposes `.messages.create` (Anthropic) or `.chat.completions.create` (OpenAI). Both providers' Bedrock and Vertex clients (`AnthropicBedrock`, `AnthropicVertex`) work through `wrap_anthropic` for free because they expose the same `.messages.create` interface.
+
+## Dashboard
+
+FastAPI + vanilla HTML + small inline JS. No build step, no framework. Static files served from `clustertrace/dashboard/static/`. Templates are Jinja2. The frontend uses `fetch()` for JSON endpoints and renders dynamically.
+
+| Page | Purpose |
+|---|---|
+| `/` | recent traces with status/tag/name-search filters and live polling |
+| `/clusters` | execution patterns, failure rates, common failure prefix |
+| `/search` | FTS5 search over span I/O and errors |
+| `/metrics` | per-metric aggregates and rolling-mean sparklines |
+| `/failures` | per-span error-rate bars + force-directed call graph |
+| `/trace/<id>` | Gantt timeline + expandable I/O + tags + metrics |
+
+## What's intentionally absent
+
+- **No auth.** Local-first means one user.
+- **No retention policy.** Delete `~/.clustertrace/traces.db` when you want to start fresh; export with `clustertrace export --all` first if you want a backup.
+- **No alerting.** Alerts belong with a production observability stack, not a debug tool.
+- **No streaming chunk capture.** We log on completion. Streaming sequences add complexity that doesn't justify itself for debugging.

clustertrace-0.5.0/CHANGELOG.md

@@ -0,0 +1,122 @@
+# Changelog
+
+All notable changes to clustertrace. Format roughly follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); semver applies.
+
+> **Renamed from `agentlog` to `clustertrace` in v0.5.0** — PyPI's name-similarity check rejected `agentlog` as too close to the existing `agentlogger` package. The new name lands the differentiator (clustering of traces) more directly anyway.
+
+## [0.5.0] — 2026-05-20
+
+### Breaking
+- **Package renamed `agentlog` → `clustertrace`.** Update your imports: `from agentlog import ...` → `from clustertrace import ...`. The decorator (`@clustertrace.trace`), wrappers (`clustertrace.wrap_anthropic`, `clustertrace.wrap_openai`), exporter (`ClustertraceSpanExporter`), and CLI (`clustertrace dashboard`, `clustertrace demo`) all use the new name.
+- **Environment variables renamed**: `AGENTLOG_DB` → `CLUSTERTRACE_DB`, `AGENTLOG_MAX_PAYLOAD_BYTES` → `CLUSTERTRACE_MAX_PAYLOAD_BYTES`, `AGENTLOG_PRICING_JSON` → `CLUSTERTRACE_PRICING_JSON`, `AGENTLOG_SAMPLE_RATE` → `CLUSTERTRACE_SAMPLE_RATE`.
+- **Default DB path** moved from `~/.agentlog/traces.db` to `~/.clustertrace/traces.db`. If you have existing traces, set `CLUSTERTRACE_DB=~/.agentlog/traces.db` or `mv ~/.agentlog ~/.clustertrace`.
+- **Export format header key** changed from `_agentlog_header` to `_clustertrace_header`. The bundled demo dataset was re-exported under the new key. Old export files will fail to import — re-export from the old version if you need them.
+
+### Why the rename
+PyPI's ultranormalization rejected `agentlog` as too similar to the existing `agentlogger` (0.1.2) package. Rather than fight the similarity check, we picked `clustertrace` — a name that lands the actual differentiator (structural clustering of traces) more clearly. PyPI confirmed `clustertrace` is free.
+
+### Same
+Everything functional from v0.4.2 is unchanged — same `@trace` decorator API, same dashboard pages, same clustering algorithm, same OpenTelemetry exporter, same wrappers, same 95-test suite (still 95/95 passing under the new name).
+
+## [0.4.2] — 2026-05-20
+
+### Fixed
+- **Windows cp1252 crash on `clustertrace demo`** — the CLI used Unicode arrows (`→`) and bullets (`·`) in its output, which crashed on a fresh Windows install where Python's stdout defaults to cp1252. Found in a first-5-minutes UX test. CLI output is now ASCII-only; regression test enforces this.
+
+### Added
+- **`publish.yml` workflow** — pushes a tag, builds the wheel + sdist, publishes to PyPI via OIDC trusted publisher (no API token stored). One-time setup at https://pypi.org/manage/account/publishing/ then `git push --tags` releases.
+- **`release.yml` workflow** — same trigger creates a GitHub Release with notes auto-extracted from the matching `CHANGELOG.md` section.
+- **`OUTREACH.md`** — researched, named-target list: 6 awesome-lists with categories, 9 AI infra bloggers/outlets with specific pitch angles, 9 Slack/Discord communities with channel names, named individuals worth engaging.
+- **README hero restructured** to match the patterns of higher-star competitors (Langfuse 27k, Phoenix 9.8k, Helicone 5.7k): centered banner image, tagline, badges row including PyPI; install command before features.
+
+### Improved
+- `LAUNCH.md` updated with researched data: 605-post Show HN survival study (1% survive 7 days on front page), 23,000-post timing analysis confirming weekday US morning slots, plus the contrarian Sunday-late-evening option. Specific times now grounded, not generic.
+
+## [0.4.1] — 2026-05-20
+
+Launch-readiness release. Code is stable from 0.4.0; new content + integration examples.
+
+### Added
+- `examples/langchain_example.py` — five-line OpenTelemetry path showing LangChain → clustertrace.
+- `examples/llamaindex_example.py` — same for LlamaIndex.
+- `examples/benchmark.py` — overhead-per-trace measurements; prints a Markdown table you can paste.
+- `docs/hero.svg` — inline-renderable hero image for the README (no external host).
+- `LAUNCH.md` — internal launch playbook with Show HN draft, Twitter thread, outreach templates.
+- Pinned `good first issue` templates for `wrap_bedrock`, `wrap_gemini`, streaming-chunk capture, and tree-edit-distance clustering.
+- "Overhead" section in the README with honest numbers and the sampling/skip escape hatches.
+
+## [0.4.0] — 2026-05-20
+
+### Performance
+- **Thread-local connection pool** — 200 concurrent async traces now finish in ~9s instead of ~55s (6× speedup). Previously each storage helper opened a fresh SQLite connection with PRAGMA setup; now the connection is reused within a thread.
+
+### Added
+- **`signature_for_spans(mode='set')`** — reorder-insensitive cluster signature. `A→B` and `B→A` collapse to one cluster. Dashboard `/clusters` page now has a mode toggle.
+- **Pagination on `/api/clusters`** — `limit` + `offset` parameters; "Load more" button on the page.
+- **Auto-cost** — `finish_span` now estimates and stores `cost_usd` automatically for any span with a known LLM model + token counts. `finish_trace` rolls up the per-span costs into the trace's `cost_usd`. No more manual `clustertrace backfill-cost`.
+- **`@trace(sample=0.1)` + `@trace(skip=True)`** — production-grade sampling. `skip=True` returns the original function unwrapped (zero overhead). `sample` accepts a float in (0, 1] or reads `$CLUSTERTRACE_SAMPLE_RATE`. Sampling is bypassed inside an active trace so child spans are always recorded.
+- **`clustertrace.flush()` + `atexit` hook** — orphan `running` traces from crashes/kills are cleaned up automatically on process exit.
+- **`clustertrace cleanup --stale-after 5m`** — explicit CLI for the same.
+- **`clustertrace vacuum --older-than 30d [--dry-run]`** — retention policy. `ON DELETE CASCADE` removes spans, tags, metrics; `VACUUM` reclaims disk space.
+- **Per-tag failure-prefix mining** — `failure_summary(group_by_tag='agent')` returns a separate longest-common-prefix per tag value. When you have multiple agents in the same DB, the global prefix is empty but the per-tag ones are diagnostic. The `/clusters` page shows them as labelled chip rows.
+- **Streaming-aware attrs** — when you call `messages.create(stream=True)` or `chat.completions.create(stream=True)`, the span's attrs include `streaming: true` so you can filter or cluster on it. (Full chunk-by-chunk capture is v0.5.)
+- **Versioned JSON exports** — `clustertrace export` emits a header line with `clustertrace_version` and `export_format_version`. `clustertrace import` refuses streams from a newer format than it supports.
+
+### Fixed
+- **OTel ingestion**: child-span errors now propagate to trace-level status. Previously OTel-ingested traces where a child errored but the root ended OK were silently classified as successful and excluded from the failure clusters.
+
+### Tests
+- 94 tests (was 75). New suite `tests/test_v04_features.py` covers connection pooling, auto-cost, set-mode clustering, sampling, per-tag prefix, streaming attrs, flush + cleanup, vacuum + duration parsing, versioned export.
+- 88% line coverage maintained. Pyright clean. Ruff clean.
+
+## [0.3.1] — 2026-05-20
+
+### Added
+- `clustertrace demo` command — zero-config trial: imports 60 bundled traces and launches the dashboard. No API key needed.
+- 60-trace `demo-traces.jsonl` bundled in the wheel (3 agent topologies, real failure clustering).
+- Empty-state guidance on the dashboard when there are no traces: `clustertrace demo`, instrument-your-code snippet, and OpenTelemetry one-liner.
+- `py.typed` marker so type checkers respect clustertrace's type hints.
+- GitHub Actions CI on push and PR — Python 3.11/3.12/3.13 × ubuntu/macOS/windows.
+- Issue and PR templates.
+- `CHANGELOG.md`, `SECURITY.md`.
+
+### Documentation
+- README hero ASCII cluster view + badges + comparison table + FAQ.
+- Install-from-git instructions for the pre-PyPI window.
+
+## [0.3.0] — 2026-05-20
+
+### Added
+- **OpenTelemetry exporter** (`clustertrace.otel.ClustertraceSpanExporter`) — any OTel-instrumented app pipes spans into clustertrace with one line. Maps `gen_ai.*` and `llm.*` attribute conventions.
+- **Cost tracking** — pricing table for Anthropic, OpenAI, Gemini with date-suffix stripping. `$CLUSTERTRACE_PRICING_JSON` override. Cached per span + rolled up per trace.
+- **Replay** — `clustertrace replay <id> --entry mod:fn` re-runs a trace with captured args. New trace tagged `replay_of=<original>`.
+- **FTS5 search** across span name + input + output + error_message. Supports phrases, OR, NEAR. `/search` page.
+- **`clustertrace.metric(name, value)`** — numeric metrics per trace, time-series sparkline charts on `/metrics`.
+- **JSONL export/import** — `clustertrace export [--all]` and `clustertrace import`.
+- **Self-contained HTML snapshots** — `clustertrace snapshot <id>` produces a single shareable file with no external assets.
+- Schema migration v3: `trace_metrics` table, `cost_usd` columns, `spans_fts` virtual table with sync triggers.
+- `ARCHITECTURE.md` (design choices and trade-offs), `CONTRIBUTING.md` (how to add an SDK wrapper).
+
+### Changed
+- README leads with the differentiator + cost + OTel + replay.
+
+## [0.2.0] — 2026-05-20
+
+### Added
+- **Trace clustering by structural signature** — RLE-collapsed sequence of `(name, status)` pairs. `/clusters` page.
+- **Longest common failure prefix** mining across failed traces.
+- `clustertrace.tag(key, value)` and `@trace(tags={...})` for filterable tags.
+- `wrap_openai` for sync + async OpenAI clients.
+- Filter UI on the recent-traces page (status, tag, name search) with live polling.
+- Per-field payload truncation (`CLUSTERTRACE_MAX_PAYLOAD_BYTES`, default 32 KB).
+- Real schema migration runner (`schema_meta.version` + ordered DDL list). v1 → v2 adds `trace_tags`, `traces.signature`.
+
+## [0.1.0] — 2026-05-20
+
+### Added
+- Initial release.
+- `@clustertrace.trace` decorator (sync + async), `clustertrace.span(...)`, `clustertrace.tool_call(...)`.
+- `wrap_anthropic` for sync + async Anthropic clients (works with `AnthropicBedrock` and `AnthropicVertex` via the shared `.messages.create` interface).
+- SQLite storage at `~/.clustertrace/traces.db`, `CLUSTERTRACE_DB` override, WAL mode.
+- FastAPI dashboard on port 7777: recent traces, trace timeline, failure-cluster visualization (per-span error rate + step-of-failure histogram + force-directed call graph).
+- 18 tests.