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.
