blitz-cli 0.3.0__tar.gz → 0.5.0__tar.gz

blitz_cli-0.5.0/PKG-INFO

@@ -0,0 +1,95 @@
+Metadata-Version: 2.4
+Name: blitz-cli
+Version: 0.5.0
+Summary: Developer CLI for Blitz: local-first tracing/init, codebase instrumentation scan, and scaffolds for both a QLoRA workflow trainer and a coding-agent session-to-fine-tuning-corpus watcher.
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.9
+Requires-Dist: rich>=13
+Requires-Dist: tomlkit>=0.12
+Description-Content-Type: text/markdown
+
+# blitz-cli
+
+Developer CLI for [Blitz](https://github.com/sparepartslabs/blitz-sdk-py). Pull a
+workflow's locally captured traces as a fine-tuning dataset, scaffold a
+self-contained, runnable QLoRA training container, and (optionally) release the
+trained adapter for Blitz to deploy and host.
+
+```bash
+pip install blitz-cli
+
+blitz scaffold -w mechanic-assistant -o ./train
+blitz config set -w mechanic-assistant --base <hf-model-id> --params-b <N> --seq-len <N>
+
+cd train
+make build && make train
+```
+
+`blitz scaffold` writes `./train` with `data/dataset.jsonl` and a `Dockerfile` +
+`train.py` + `Makefile`. Bring your own NVIDIA GPU. Both commands are fully
+local/offline — no project id or API key needed; the training config lives in
+a repo-root `blitz.toml`.
+
+This package is stdlib + the Blitz HTTP API, plus `rich` (for `blitz traces`'
+and `blitz activity`'s table/tree rendering) and `tomlkit` (for reading/writing
+`blitz.toml`). The heavy ML stack (torch / transformers / trl / peft) is
+pinned only in the *generated* project's `requirements.txt`, installed inside
+the training image.
+
+### Release: deploy to production
+
+Once a local training run has produced `./train/adapter`, `blitz release`
+registers the run with Blitz, uploads the adapter to S3, and triggers Blitz's
+own deploy pipeline (a vLLM-served endpoint with native multi-LoRA serving, so
+one base-model image is reused across releases), then reports the smoke test
+result. No Modal account, token, or dependency needed on your machine — Blitz
+owns the deploy, opaque to you:
+
+```bash
+export BLITZ_API_KEY=blz_...   # a read-scoped project key
+blitz release -w mechanic-assistant -p proj_abc
+```
+
+`--idle-timeout` controls how long the deployed container stays warm after
+its last request before scaling to zero — the lever for
+trading off cold-start latency against idle GPU cost.
+
+### Reading captured traces
+
+`blitz.init()` always writes spans to a local SQLite file (`.blitz/traces.db`
+by default — override with `BLITZ_LOCAL_DIR`, or a repo-root `blitz.toml`'s
+`[capture] local_dir`). Read them back with:
+
+```bash
+blitz traces list
+blitz traces show <trace_id>
+```
+
+No project id or API key needed.
+
+### Replaying coding-agent session activity
+
+`blitz activity` reads your local coding agent's own session transcripts
+(`~/.claude/projects`, unrelated to Blitz's captured traces above) for the
+current repo and replays each prompt you sent alongside the actions taken to
+resolve it (tool calls, sub-agents) and the final response:
+
+```bash
+blitz activity --list              # sessions for this repo, most recent first
+blitz activity                     # the most recent session's timeline
+blitz activity <session-id-prefix> # a specific session
+blitz activity --full               # untruncated prompts/responses/tool I/O in the terminal
+blitz activity --html report.html  # also write a self-contained HTML report
+```
+
+The terminal view is compact by default (truncated prompt/response/tool I/O)
+for a quick glance; pass `--full` for the untruncated text there too. The
+HTML report always includes each action's full tool input/output, collapsed
+per action so it stays scannable. Each turn also shows its raw token usage
+(input/output/cache tokens and model), and where a pre-edit backup was kept
+(`~/.claude/file-history`), an `Edit`/`Write` action shows a real diff of what
+changed — reconstructed from the action's own recorded input, so it reflects
+that turn's change even if the file has since drifted further.
+
+No project id or API key needed; this only reads local session data.

blitz_cli-0.5.0/README.md

@@ -0,0 +1,84 @@
+# blitz-cli
+
+Developer CLI for [Blitz](https://github.com/sparepartslabs/blitz-sdk-py). Pull a
+workflow's locally captured traces as a fine-tuning dataset, scaffold a
+self-contained, runnable QLoRA training container, and (optionally) release the
+trained adapter for Blitz to deploy and host.
+
+```bash
+pip install blitz-cli
+
+blitz scaffold -w mechanic-assistant -o ./train
+blitz config set -w mechanic-assistant --base <hf-model-id> --params-b <N> --seq-len <N>
+
+cd train
+make build && make train
+```
+
+`blitz scaffold` writes `./train` with `data/dataset.jsonl` and a `Dockerfile` +
+`train.py` + `Makefile`. Bring your own NVIDIA GPU. Both commands are fully
+local/offline — no project id or API key needed; the training config lives in
+a repo-root `blitz.toml`.
+
+This package is stdlib + the Blitz HTTP API, plus `rich` (for `blitz traces`'
+and `blitz activity`'s table/tree rendering) and `tomlkit` (for reading/writing
+`blitz.toml`). The heavy ML stack (torch / transformers / trl / peft) is
+pinned only in the *generated* project's `requirements.txt`, installed inside
+the training image.
+
+### Release: deploy to production
+
+Once a local training run has produced `./train/adapter`, `blitz release`
+registers the run with Blitz, uploads the adapter to S3, and triggers Blitz's
+own deploy pipeline (a vLLM-served endpoint with native multi-LoRA serving, so
+one base-model image is reused across releases), then reports the smoke test
+result. No Modal account, token, or dependency needed on your machine — Blitz
+owns the deploy, opaque to you:
+
+```bash
+export BLITZ_API_KEY=blz_...   # a read-scoped project key
+blitz release -w mechanic-assistant -p proj_abc
+```
+
+`--idle-timeout` controls how long the deployed container stays warm after
+its last request before scaling to zero — the lever for
+trading off cold-start latency against idle GPU cost.
+
+### Reading captured traces
+
+`blitz.init()` always writes spans to a local SQLite file (`.blitz/traces.db`
+by default — override with `BLITZ_LOCAL_DIR`, or a repo-root `blitz.toml`'s
+`[capture] local_dir`). Read them back with:
+
+```bash
+blitz traces list
+blitz traces show <trace_id>
+```
+
+No project id or API key needed.
+
+### Replaying coding-agent session activity
+
+`blitz activity` reads your local coding agent's own session transcripts
+(`~/.claude/projects`, unrelated to Blitz's captured traces above) for the
+current repo and replays each prompt you sent alongside the actions taken to
+resolve it (tool calls, sub-agents) and the final response:
+
+```bash
+blitz activity --list              # sessions for this repo, most recent first
+blitz activity                     # the most recent session's timeline
+blitz activity <session-id-prefix> # a specific session
+blitz activity --full               # untruncated prompts/responses/tool I/O in the terminal
+blitz activity --html report.html  # also write a self-contained HTML report
+```
+
+The terminal view is compact by default (truncated prompt/response/tool I/O)
+for a quick glance; pass `--full` for the untruncated text there too. The
+HTML report always includes each action's full tool input/output, collapsed
+per action so it stays scannable. Each turn also shows its raw token usage
+(input/output/cache tokens and model), and where a pre-edit backup was kept
+(`~/.claude/file-history`), an `Edit`/`Write` action shows a real diff of what
+changed — reconstructed from the action's own recorded input, so it reflects
+that turn's change even if the file has since drifted further.
+
+No project id or API key needed; this only reads local session data.

blitz_cli-0.5.0/blitz_cli/__init__.py

@@ -0,0 +1,33 @@
+"""blitz-cli — instrument a codebase for Blitz and scaffold a QLoRA trainer.
+
+Commands:
+
+- ``blitz init`` — write a repo-root ``blitz.toml`` (project/local_dir/environment/
+  service_name) and stub the local trace store. Infers the project id from the git
+  remote. No endpoint or API key needed; traces are always captured locally.
+
+- ``blitz scan [path]`` — statically walk a codebase and report each AI/LLM
+  call's Blitz instrumentation posture (unsupported provider / no blitz.init() /
+  traced-but-unnamed / instrumented), with copy-paste fixes. Offline, no API key.
+
+- ``blitz traces list`` / ``blitz traces show <trace_id>`` — inspect captured
+  traces from the local SQLite store.
+
+- ``blitz activity [session] [--list] [--html report.html]`` — replay a
+  Claude Code session for this repo: each prompt you sent, the actions taken
+  to resolve it (tool calls, sub-agents), and the final response. Reads
+  ``~/.claude/projects`` directly; unrelated to Blitz's own captured traces.
+
+- ``blitz skill install`` — drop the Blitz Claude Code skills (``blitz-instrument``,
+  ``blitz-fix-teacher``) into the repo's ``.claude/skills`` so Claude can run the
+  instrumentation and teacher-hardening playbooks.
+
+- ``blitz scaffold -p <project> -w <workflow> -o ./train`` — download a
+  workflow's SFT dataset, then emit a self-contained, runnable training project
+  (Dockerfile + train.py). Authenticates with a read-scoped Blitz API key
+  (``BLITZ_API_KEY``).
+"""
+
+__all__ = ["__version__"]
+
+__version__ = "0.5.0"