buro 0.0.1__tar.gz

buro-0.0.1/.gitignore

@@ -0,0 +1,9 @@
+.venv/
+__pycache__/
+*.py[cod]
+*.pyo
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+.ruff_cache/

buro-0.0.1/Makefile

@@ -0,0 +1,7 @@
+.PHONY: mutation-check
+
+mutation-check:
+	@if [ -z "$(FILE)" ]; then \
+		echo "Usage: make mutation-check FILE=<source-file>"; exit 3; \
+	fi
+	@uv run python scripts/mutation_check.py "$(FILE)"

buro-0.0.1/PKG-INFO

@@ -0,0 +1,81 @@
+Metadata-Version: 2.4
+Name: buro
+Version: 0.0.1
+Summary: Experiment tracker and lab journal made for humans — and sexy human-agent interaction for AI research
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: lz4>=4.3
+Requires-Dist: pathspec>=0.12
+Requires-Dist: psutil>=6.0
+Requires-Dist: typer>=0.12
+Provides-Extra: dev
+Requires-Dist: mutmut<3,>=2.5; extra == 'dev'
+Requires-Dist: numpy>=1.26; extra == 'dev'
+Requires-Dist: pillow>=10.0; extra == 'dev'
+Requires-Dist: psycopg2-binary>=2.9; extra == 'dev'
+Requires-Dist: pytest>=8.3; extra == 'dev'
+Requires-Dist: respx>=0.22; extra == 'dev'
+Provides-Extra: gpu
+Requires-Dist: pynvml>=12.0; extra == 'gpu'
+Description-Content-Type: text/markdown
+
+# buro
+
+An experiment tracker and lab journal made for humans — and for sexy human ⇄ agent
+interaction in AI research. Log your runs, metrics, and media to a
+[Buro](https://github.com/dunnolab/buro) server.
+
+## Install
+
+```bash
+pip install buro
+```
+
+## Quickstart
+
+```python
+import buro
+
+run = buro.init(project="my-project")        # or "team-slug/my-project"
+for step in range(100):
+    buro.log({"loss": 1.0 / (step + 1), "acc": step / 100}, step=step)
+buro.finish()
+```
+
+`init(project=...)` resolves the project against the server and auto-creates it
+if it doesn't exist. `project` is a slug ref: `"slug"` (personal) or
+`"team-slug/slug"` (team).
+
+## Authenticate
+
+Log in once on your machine:
+
+```bash
+buro login --api-url https://<your-buro-server>
+buro whoami
+```
+
+The SDK resolves credentials in this order:
+
+1. `buro.setup(api_key=..., api_url=...)` in code
+2. `BURO_API_KEY` / `BURO_API_URL` environment variables
+3. `~/.buro/credentials` (written by `buro login`)
+
+On a cluster or in CI, the env-var path is usually easiest:
+
+```bash
+export BURO_API_KEY=buro_key_...
+export BURO_API_URL=https://<your-buro-server>
+```
+
+## Log media
+
+```python
+buro.log({"sample": buro.Image("path/to/image.png")})   # numpy array or PIL image also work
+# also available: buro.Audio, buro.Video
+```
+
+## Docs
+
+- `wandb` API compatibility: [`docs/wandb-compatibility.md`](docs/wandb-compatibility.md)
+- Release/publishing process: [`docs/publishing.md`](docs/publishing.md)

buro-0.0.1/README.md

@@ -0,0 +1,60 @@
+# buro
+
+An experiment tracker and lab journal made for humans — and for sexy human ⇄ agent
+interaction in AI research. Log your runs, metrics, and media to a
+[Buro](https://github.com/dunnolab/buro) server.
+
+## Install
+
+```bash
+pip install buro
+```
+
+## Quickstart
+
+```python
+import buro
+
+run = buro.init(project="my-project")        # or "team-slug/my-project"
+for step in range(100):
+    buro.log({"loss": 1.0 / (step + 1), "acc": step / 100}, step=step)
+buro.finish()
+```
+
+`init(project=...)` resolves the project against the server and auto-creates it
+if it doesn't exist. `project` is a slug ref: `"slug"` (personal) or
+`"team-slug/slug"` (team).
+
+## Authenticate
+
+Log in once on your machine:
+
+```bash
+buro login --api-url https://<your-buro-server>
+buro whoami
+```
+
+The SDK resolves credentials in this order:
+
+1. `buro.setup(api_key=..., api_url=...)` in code
+2. `BURO_API_KEY` / `BURO_API_URL` environment variables
+3. `~/.buro/credentials` (written by `buro login`)
+
+On a cluster or in CI, the env-var path is usually easiest:
+
+```bash
+export BURO_API_KEY=buro_key_...
+export BURO_API_URL=https://<your-buro-server>
+```
+
+## Log media
+
+```python
+buro.log({"sample": buro.Image("path/to/image.png")})   # numpy array or PIL image also work
+# also available: buro.Audio, buro.Video
+```
+
+## Docs
+
+- `wandb` API compatibility: [`docs/wandb-compatibility.md`](docs/wandb-compatibility.md)
+- Release/publishing process: [`docs/publishing.md`](docs/publishing.md)

buro-0.0.1/docs/publishing.md

@@ -0,0 +1,37 @@
+# Publishing the buro SDK to PyPI
+
+Releases are published by `.github/workflows/sdk-publish.yml` when a GitHub
+Release with a `sdk-v<version>` tag is published. Auth is PyPI Trusted
+Publishing (OIDC) — there are no secrets to manage.
+
+## Cut a release
+
+1. Bump the single version source on a branch and merge to `main`:
+   ```python
+   # sdk/src/buro/__init__.py
+   __version__ = "0.0.2"
+   ```
+   (`pyproject.toml` reads this automatically via hatchling — do not edit a
+   version there.)
+
+2. Create the GitHub Release from the merged commit:
+   ```bash
+   gh release create sdk-v0.0.2 --title "SDK 0.0.2" --notes "..."
+   ```
+
+The workflow then runs the unit tests, builds the sdist + wheel, asserts the
+tag matches the built version, runs `twine check`, and uploads to PyPI.
+
+## Guards (why a bad release won't reach PyPI)
+
+- The tag must be `sdk-v<version>` or the job is skipped (monorepo guard).
+- The tag's version must equal the built artifact version
+  (`scripts/check_release_version.py`) or the run fails before upload.
+- A version already on PyPI is rejected by PyPI — bump and re-tag.
+
+## One-time setup (already done)
+
+- **pypi.org pending publisher**: project `buro`, owner `dunnolab`, repo
+  `buro`, workflow `sdk-publish.yml`, environment `pypi`.
+- **GitHub repo Environment `pypi`** (optionally with a required reviewer to
+  gate each publish behind one approval click).

buro-0.0.1/docs/wandb-compatibility.md

@@ -0,0 +1,87 @@
+# wandb Compatibility Matrix
+
+`buro` accepts a subset of wandb's API surface so existing training scripts can switch with minimal edits. This document is the **source of truth** for how each surface behaves.
+
+## Level legend
+
+| Level | Meaning | User experience |
+|---|---|---|
+| **L0** | Identical — same signature, same effect | Silent |
+| **L1** | Equivalent semantics, impl details may differ | Silent |
+| **L2** | Param accepted; visual/extra effect dropped. No data loss | INFO once per (process, api, param) |
+| **L3** | Call works but some data dropped/truncated | WARNING every call |
+| **L4** | Unsupported; silent no-op would be dangerous | `NotImplementedError` |
+
+**Rule:** every wandb-shaped surface in `buro` MUST declare a level here. Undeclared = L4.
+
+## Matrix
+
+### `buro.Image` (vs `wandb.Image`)
+
+| Surface | Level | V1 behavior | Since |
+|---|---|---|---|
+| `Image(data)` — array / PIL / path | L0 | Identical | 0.1 |
+| `Image(caption=...)` | L0 | Sent to server and rendered in panel + modal | 0.2 |
+| `Image(file_type=...)` | L0 | Identical | 0.2 |
+| `Image(mode=...)` | L2 | Accepted, ignored. INFO once | 0.2 |
+| `Image(classes=...)` | L2 | Stored as sidecar JSONB on server, not rendered | 0.2 |
+| `Image(boxes=...)` | L2 | Stored as sidecar JSONB, not rendered | 0.2 |
+| `Image(masks=...)` | L2 | Stored as sidecar JSONB, not rendered | 0.2 |
+| `Image(grouping=...)` | L2 | Ignored | 0.2 |
+
+### `buro.log`
+
+| Surface | Level | V1 behavior | Since |
+|---|---|---|---|
+| `log({"k": Image(...)})` | L0 | Identical | 0.2 |
+| `log({"k": [Image, Image, ...]})` | L3 | Keeps first, WARN every call | 0.2 |
+
+### `buro.Run.fail()`
+
+`wandb` doesn't have a direct equivalent — failure is signaled via `wandb.finish(exit_code=N)` (non-zero exit_code → "failed" state).
+
+| Surface | Level | V1 behavior | Since |
+|---|---|---|---|
+| `run.fail()` | L1 | Attests `terminal_reason=user_failed` on the server. No wandb equivalent — use instead of `wandb.finish(exit_code=1)` for explicit failure | 0.2 |
+| `run.fail(reason)` | L1 | Reason string carried in `terminal_reason_detail.message` | 0.2 |
+| `wandb.finish(exit_code=N)` | L2 | Accepted, `exit_code` arg ignored. Users should migrate to `run.finish()` for success / `run.fail(reason)` for failure | 0.2 |
+
+### Run state / `terminal_reason`
+
+`wandb` exposes `wandb.Run.state` as a string property (`running`, `finished`, `failed`, `crashed`). `buro` does **not** currently expose `run.state` (undeclared = L4 = `NotImplementedError` on access).
+
+When/if we add `run.state` in the future, it will map our `terminal_reason` to wandb's shape:
+
+| buro state | wandb `run.state` |
+|---|---|
+| (live, no terminal_reason) | `"running"` |
+| `terminal_reason=user_finished` | `"finished"` |
+| `terminal_reason=user_failed` | `"failed"` |
+| `terminal_reason=exception_hooked` | `"failed"` (closest wandb equivalent for an SDK-caught exception) |
+| `terminal_reason=interrupted` | `"failed"` (no wandb equivalent for SIGINT/SIGTERM; closest signal is failure) |
+| `terminal_reason=unknown` | `"crashed"` (closest match; our model considers this the honest "we don't know" bucket) |
+
+In V1 the SDK installs `sys.excepthook`, `signal.SIGINT`/`SIGTERM` handlers, and an `atexit` log-drain hook. These do not shadow any wandb name — they're SDK-internal infrastructure that produces `terminal_reason` writes on the server. `wandb` has similar (and similar-named) hooks; the difference users will observe is that buro never invents a `crashed` label for runs that exit silently — those stay `terminal_reason=unknown` until the server's heartbeat timeout fires.
+
+### Unsupported (L4)
+
+| Surface | V1 behavior |
+|---|---|
+| `buro.Artifact` | `NotImplementedError` |
+| `buro.Table` | `NotImplementedError` |
+| `buro.Plotly` | `NotImplementedError` |
+| `buro.Html` | `NotImplementedError` |
+| `buro.Object3D` | `NotImplementedError` |
+| `buro.Molecule` | `NotImplementedError` |
+
+## Known V1 limits
+
+- **Quota over-count on failed media uploads.** If `POST /runs/{id}/media` succeeds but the subsequent S3 PUT fails, the quota counter stays incremented. No reconcile job. Failure rate expected low; revisit if it matters.
+- **No retry inside `_upload_media`.** A single transient S3 error logs WARNING and continues; the metric log call is not retried.
+- **No frontend renderer for `Audio` / `Video`.** SDK classes upload but no viewer V1.
+
+## Adding a new surface
+
+1. Add a row to the matrix above with declared level and behavior.
+2. If the level is L2 / L3 / L4: route through `buro._compat.emit_once` / `warn` / `unsupported`.
+3. Add tests to `sdk/tests/test_wandb_compat.py` matching the level's contract.

buro-0.0.1/examples/MANUAL_TESTING.md

@@ -0,0 +1,172 @@
+# Manual testing — Buro SDK credential profiles
+
+A runbook for exercising the SDK the way real users run it. The journey is
+always the same (create a project, log metrics, finish); what changes is **how
+credentials reach the SDK**. Resolution precedence is:
+
+> `buro.setup()` in code  >  `BURO_API_KEY` env var  >  `~/.buro/credentials` file
+
+Driver script: [`log_demo.py`](./log_demo.py). It hardcodes no key — it relies
+on whatever the environment provides, and prints which source it resolved so
+each profile is observable.
+
+---
+
+## One-time setup
+
+Each step says which directory to run it from — `npm run dev` blocks its
+terminal, so use a separate terminal per long-running process.
+
+```bash
+# 1. Backend stack — run from the REPO ROOT
+#    (--build picks up the device-auth migration + endpoints)
+cd /path/to/buro            # the repo root
+docker compose up -d --build
+
+# 2. Web frontend — run from the REPO ROOT, in its own terminal.
+#    Hosts /cli-auth and proxies /api -> :8000 on port 5173.
+#    Keep 5173 free; the device flow opens that exact URL.
+cd /path/to/buro/web
+npm install && npm run dev   # leave running
+
+# 3. Install the SDK so `buro` (CLI) and `import buro` (library) work.
+#    Run from the SDK directory (use a fresh venv if you prefer):
+cd /path/to/buro/sdk
+pip install -e .
+```
+
+> The example commands below assume you run them from the **repo root**
+> (so `python sdk/examples/log_demo.py ...` resolves). Adjust the path if
+> you `cd` elsewhere.
+
+Then create an account: open <http://localhost:5173> and sign up (registration
+is open in the compose stack).
+
+All profiles below assume the server is at `http://localhost:8000`.
+
+---
+
+## Profile A — Laptop, logged in (credentials file)
+
+The everyday dev flow: authorize once via the browser, then just run scripts.
+
+```bash
+buro login --api-url http://localhost:8000
+#   -> prints a code, opens http://localhost:5173/cli-auth?user_code=...
+#   -> approve in the browser
+#   -> terminal prints "Logged in as <you>"
+
+buro whoami                 # prints your email (reads ~/.buro/credentials)
+cat ~/.buro/credentials     # {"api_url": "...", "api_key": "buro_key_..."}  (mode 0600)
+
+python sdk/examples/log_demo.py --project cli-login-test
+```
+
+**Expect:** `Credential source : ~/.buro/credentials file`, then 40 logged
+steps. **Verify:** open <http://localhost:5173>, project `cli-login-test`, the
+run shows `loss`/`accuracy` charts.
+
+> Tip: grab the raw key for the next profiles — `cat ~/.buro/credentials`. You
+> can also mint a dedicated key in the web UI under account settings.
+
+---
+
+## Profile B — Cluster / CI job, env var only (no file)
+
+The unattended path: a remote box with no `buro login`, only an exported key.
+
+```bash
+# Simulate "no credentials file on this machine"
+mv ~/.buro/credentials ~/.buro/credentials.bak    # (restore later)
+
+export BURO_API_KEY=buro_key_...      # the raw key from Profile A
+export BURO_API_URL=http://localhost:8000
+
+python sdk/examples/log_demo.py --project cli-login-test --name cluster-run
+```
+
+**Expect:** `Credential source : BURO_API_KEY env var`; the run logs without any
+login. **Verify:** the `cluster-run` run appears in the UI.
+
+```bash
+# cleanup
+unset BURO_API_KEY BURO_API_URL
+mv ~/.buro/credentials.bak ~/.buro/credentials
+```
+
+---
+
+## Profile C — Explicit configuration in code (`buro.setup`)
+
+A user who configures the SDK in code (e.g. keys pulled from their job's own
+secret store). `setup()` wins over env and file.
+
+```bash
+# Pass the key explicitly; the script calls buro.setup(api_key=..., api_url=...)
+python sdk/examples/log_demo.py --project cli-login-test --name in-code \
+    --api-key buro_key_... --api-url http://localhost:8000
+```
+
+**Expect:** `Credential source : setup() in code (--api-key)`. **Verify:** the
+`in-code` run appears in the UI.
+
+---
+
+## Profile D — Precedence & negative paths
+
+**D1 — env overrides a stale file.** With BOTH a file and an env var present,
+the env var must win:
+
+```bash
+# (ensure ~/.buro/credentials exists from Profile A)
+export BURO_API_KEY=buro_key_...      # any valid key
+export BURO_API_URL=http://localhost:8000
+python sdk/examples/log_demo.py --project cli-login-test --name precedence
+# Expect: "Credential source : BURO_API_KEY env var" and api_url = the env one
+unset BURO_API_KEY BURO_API_URL
+```
+
+**D2 — setup() overrides env + file.** With a file present and an env var
+exported, ALSO pass `--api-key`: the printed source must be `setup() in code`.
+
+```bash
+export BURO_API_KEY=buro_key_SHOULD_BE_IGNORED
+python sdk/examples/log_demo.py --project cli-login-test \
+    --api-key buro_key_... --api-url http://localhost:8000
+# Expect: "Credential source : setup() in code (--api-key)"
+unset BURO_API_KEY
+```
+
+**D3 — no credentials anywhere → clean error, not a traceback.**
+
+```bash
+mv ~/.buro/credentials ~/.buro/credentials.bak 2>/dev/null
+env -u BURO_API_KEY -u BURO_API_URL python sdk/examples/log_demo.py --project x
+# Expect: "No API key found in any source." + the three options, exit code 1
+mv ~/.buro/credentials.bak ~/.buro/credentials 2>/dev/null
+```
+
+**D4 — logout clears the file.**
+
+```bash
+buro logout            # -> "Logged out."   (removes ~/.buro/credentials)
+buro whoami            # -> "Not logged in." exit 1
+```
+
+---
+
+## What "pass" looks like
+
+| Profile | Source line printed | Outcome |
+|---|---|---|
+| A | `~/.buro/credentials file` | run logged, visible in UI |
+| B | `BURO_API_KEY env var` | run logged, no login needed |
+| C | `setup() in code (--api-key)` | run logged |
+| D1 | `BURO_API_KEY env var` (file ignored) | env wins |
+| D2 | `setup() in code (--api-key)` | setup wins over env+file |
+| D3 | `none` | clean message, exit 1, no traceback |
+| D4 | — | logout removes file; whoami fails cleanly |
+
+> Note: `buro logout` clears the **local** file only; it does not revoke the key
+> server-side (out of scope by design). Keys do not expire; only the 10-minute
+> login *handshake* does.

buro-0.0.1/examples/log_demo.py

@@ -0,0 +1,110 @@
+#!/usr/bin/env python3
+"""End-user smoke for the Buro SDK: create a project and log to it.
+
+This is the script the manual-testing runbook (MANUAL_TESTING.md) drives
+across the credential environments a real user hits:
+
+  A. Laptop, logged in        -> creds resolved from ~/.buro/credentials
+  B. Cluster/CI, env var only  -> creds from BURO_API_KEY / BURO_API_URL
+  C. Explicit in code          -> pass --api-key/--api-url (calls buro.setup)
+  D. Precedence / negative     -> observe which source the resolver picks
+
+It intentionally hardcodes NO key. With --api-key it mimics a user who
+configures the SDK in code; without it, the SDK resolves credentials the
+same way it would in any real run: setup() > BURO_API_KEY env > ~/.buro file.
+
+Examples:
+    buro login --api-url http://localhost:8000          # profile A, once
+    python sdk/examples/log_demo.py --project cli-login-test
+
+    BURO_API_KEY=buro_key_... BURO_API_URL=http://localhost:8000 \\
+        python sdk/examples/log_demo.py --project cli-login-test   # profile B
+
+    python sdk/examples/log_demo.py --project p \\
+        --api-key buro_key_... --api-url http://localhost:8000      # profile C
+"""
+
+import argparse
+import math
+import os
+import random
+import time
+
+import buro
+from buro.credentials import load as load_credentials
+from buro.settings import resolve_api_key, resolve_api_url
+
+
+def _mask(key: str) -> str:
+    if not key:
+        return "<none>"
+    return f"{key[:12]}…{key[-4:]}" if len(key) > 20 else "<set>"
+
+
+def _credential_source(explicit_key: str | None) -> str:
+    """Mirror the resolver's precedence — for display only — so you can SEE
+    which credential environment is actually being exercised."""
+    if explicit_key:
+        return "setup() in code (--api-key)"
+    if os.environ.get("BURO_API_KEY"):
+        return "BURO_API_KEY env var"
+    if load_credentials().get("api_key"):
+        return "~/.buro/credentials file"
+    return "none"
+
+
+def main() -> int:
+    p = argparse.ArgumentParser(description="Buro SDK manual smoke")
+    p.add_argument("--project", default="cli-login-test",
+                   help="Project ref: 'slug' (personal) or 'team-slug/slug'.")
+    p.add_argument("--steps", type=int, default=40, help="Metric steps to log.")
+    p.add_argument("--name", default=None, help="Optional run name.")
+    p.add_argument("--delay", type=float, default=0.2, help="Seconds between steps.")
+    p.add_argument("--api-key", default=None,
+                   help="Profile C: configure the key in code via buro.setup().")
+    p.add_argument("--api-url", default=None,
+                   help="Server URL for buro.setup() (profile C) / override.")
+    args = p.parse_args()
+
+    # Profile C: explicit configuration in code. setup() wins over env + file.
+    if args.api_key or args.api_url:
+        buro.setup(api_key=args.api_key, api_url=args.api_url)
+
+    print(f"Credential source : {_credential_source(args.api_key)}")
+    print(f"Resolved api_url  : {resolve_api_url()}")
+    print(f"Resolved api_key  : {_mask(resolve_api_key())}")
+
+    if not resolve_api_key():
+        print(
+            "\nNo API key found in any source. Pick one:\n"
+            "  - run `buro login --api-url <server>`           (profile A), or\n"
+            "  - export BURO_API_KEY=buro_key_...              (profile B), or\n"
+            "  - pass --api-key buro_key_... --api-url <server> (profile C)."
+        )
+        return 1
+
+    print(f"\nLogging to project {args.project!r} ...")
+    try:
+        buro.init(project=args.project, name=args.name,
+                  config={"lr": 3e-4, "batch_size": 32, "optimizer": "adamw"})
+        try:
+            for step in range(args.steps):
+                loss = math.exp(-step / 12) + random.uniform(0, 0.05)
+                acc = min(0.99, 1 - math.exp(-step / 8) + random.uniform(-0.02, 0.02))
+                buro.log({"loss": loss, "accuracy": acc}, step=step)
+                print(f"  step {step:>3}  loss={loss:.4f}  acc={acc:.4f}")
+                time.sleep(args.delay)
+        finally:
+            buro.finish()
+    except Exception as e:  # noqa: BLE001 — surface a readable message for manual testing
+        print(f"\nFailed: {type(e).__name__}: {e}")
+        print("If this looks like auth: the key may be invalid/revoked, or the "
+              "server URL is wrong.")
+        return 1
+
+    print("\nDone. Open the web UI to see the run and its charts.")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

buro-0.0.1/pyproject.toml

@@ -0,0 +1,44 @@
+[project]
+name = "buro"
+dynamic = ["version"]
+description = "Experiment tracker and lab journal made for humans — and sexy human-agent interaction for AI research"
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+    "httpx>=0.27",
+    "lz4>=4.3",
+    "pathspec>=0.12",
+    "psutil>=6.0",
+    "typer>=0.12",
+]
+
+[project.scripts]
+buro = "buro.cli:main"
+
+[project.optional-dependencies]
+gpu = ["pynvml>=12.0"]
+dev = [
+    "pytest>=8.3",
+    "respx>=0.22",
+    "numpy>=1.26",
+    "pillow>=10.0",
+    "psycopg2-binary>=2.9",
+    "mutmut>=2.5,<3",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.version]
+path = "src/buro/__init__.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/buro"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.mutmut]
+paths_to_mutate = ["src/buro/"]
+tests_dir = ["tests/"]

buro-0.0.1/scripts/check_release_version.py

@@ -0,0 +1,73 @@
+#!/usr/bin/env python3
+"""Assert a GitHub Release tag matches the built buro distribution version.
+
+Usage:
+    check_release_version.py <tag> <dist_dir>
+
+<tag>       GitHub Release tag, expected form ``sdk-v<version>``.
+<dist_dir>  Directory of artifacts from ``uv build`` (one wheel + one sdist).
+
+Exits 0 when the tag's version equals the single version embedded in the
+distribution artifacts; prints a diagnostic and exits non-zero otherwise.
+The artifact filenames are the source of truth: this verifies what hatchling
+actually produced, independent of how the version was configured.
+"""
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+TAG_PREFIX = "sdk-v"
+SDIST_SUFFIX = ".tar.gz"
+
+
+def version_from_tag(tag: str) -> str:
+    """``sdk-v0.0.1`` -> ``0.0.1``. Raise ValueError on any other shape."""
+    if not tag.startswith(TAG_PREFIX):
+        raise ValueError(f"tag {tag!r} does not start with {TAG_PREFIX!r}")
+    version = tag[len(TAG_PREFIX):]
+    if not version:
+        raise ValueError(f"tag {tag!r} has an empty version after {TAG_PREFIX!r}")
+    return version
+
+
+def versions_from_dist(dist_dir: Path) -> set[str]:
+    """Parse the buro version out of every artifact filename in ``dist_dir``.
+
+    Wheel:  buro-<ver>-py3-none-any.whl   (version is the 2nd '-' field)
+    Sdist:  buro-<ver>.tar.gz             (strip 'buro-' prefix + '.tar.gz')
+    """
+    versions: set[str] = set()
+    for whl in dist_dir.glob("buro-*.whl"):
+        versions.add(whl.name.split("-")[1])
+    for sdist in dist_dir.glob(f"buro-*{SDIST_SUFFIX}"):
+        versions.add(sdist.name[len("buro-"):-len(SDIST_SUFFIX)])
+    if not versions:
+        raise ValueError(f"no buro artifacts found in {dist_dir}")
+    return versions
+
+
+def main(argv: list[str]) -> int:
+    if len(argv) != 2:
+        print("usage: check_release_version.py <tag> <dist_dir>", file=sys.stderr)
+        return 2
+    tag, dist_dir = argv
+    try:
+        expected = version_from_tag(tag)
+        built = versions_from_dist(Path(dist_dir))
+    except ValueError as exc:
+        print(f"::error::{exc}", file=sys.stderr)
+        return 1
+    if built != {expected}:
+        print(
+            f"::error::release tag {tag!r} -> version {expected!r} does not "
+            f"match built artifact version(s) {sorted(built)!r}",
+            file=sys.stderr,
+        )
+        return 1
+    print(f"OK: release tag {tag} matches built version {expected}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))