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

blitz_cli-0.3.0/.github/workflows/homebrew.yml

@@ -0,0 +1,54 @@
+name: Update Homebrew tap
+
+# On every release tag, point the sparepartslabs/homebrew-tap formula at the new
+# PyPI sdist. Runs alongside publish.yml (same v* trigger) and waits for the
+# sdist to appear on PyPI before reading its canonical URL + sha256.
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  bump:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Resolve version
+        id: v
+        run: echo "version=${GITHUB_REF_NAME#v}" >> "$GITHUB_OUTPUT"
+
+      - name: Fetch sdist url + sha256 from PyPI (wait for publish)
+        id: pypi
+        run: |
+          VERSION="${{ steps.v.outputs.version }}"
+          for i in $(seq 1 30); do
+            JSON=$(curl -fsSL "https://pypi.org/pypi/blitz-cli/${VERSION}/json" || true)
+            URL=$(printf '%s' "$JSON" | jq -r '.urls[]? | select(.packagetype=="sdist") | .url')
+            SHA=$(printf '%s' "$JSON" | jq -r '.urls[]? | select(.packagetype=="sdist") | .digests.sha256')
+            if [ -n "$URL" ] && [ "$URL" != "null" ]; then break; fi
+            echo "sdist for ${VERSION} not on PyPI yet, retrying ($i)..."
+            sleep 10
+          done
+          if [ -z "$URL" ] || [ "$URL" = "null" ]; then
+            echo "::error::blitz-cli ${VERSION} sdist not found on PyPI"; exit 1
+          fi
+          echo "url=$URL" >> "$GITHUB_OUTPUT"
+          echo "sha=$SHA" >> "$GITHUB_OUTPUT"
+
+      - name: Checkout tap
+        uses: actions/checkout@v4
+        with:
+          repository: sparepartslabs/homebrew-tap
+          token: ${{ secrets.HOMEBREW_TAP_TOKEN }}
+
+      - name: Update formula
+        run: |
+          F=Formula/blitz-cli.rb
+          sed -i -E "s#^  url \".*\"#  url \"${{ steps.pypi.outputs.url }}\"#" "$F"
+          sed -i -E "s#^  sha256 \".*\"#  sha256 \"${{ steps.pypi.outputs.sha }}\"#" "$F"
+          git config user.name  "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          if git diff --quiet; then
+            echo "formula already up to date"; exit 0
+          fi
+          git commit -am "blitz-cli ${{ steps.v.outputs.version }}"
+          git push

blitz_cli-0.3.0/LICENSE

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

{blitz_cli-0.1.0 → blitz_cli-0.3.0}/PKG-INFO

@@ -1,7 +1,9 @@
 Metadata-Version: 2.4
 Name: blitz-cli
-Version: 0.1.0
+Version: 0.3.0
 Summary: Developer CLI for Blitz: pull a workflow's training data + base-model recommendation and scaffold a runnable QLoRA training container.
+License: MIT
+License-File: LICENSE
 Requires-Python: >=3.9
 Description-Content-Type: text/markdown
 

blitz_cli-0.3.0/blitz_cli/__init__.py

@@ -0,0 +1,26 @@
+"""blitz-cli — onboard a codebase to Blitz and scaffold a QLoRA trainer.
+
+Commands:
+
+- ``blitz init -p <project>`` — write a repo-local ``.env`` (BLITZ_PROJECT /
+  BLITZ_ENDPOINT) and validate your ingest key.
+
+- ``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 verify [--wait]`` — confirm sample traces have landed in Blitz,
+  authenticated by the ingest key (``BLITZ_API_KEY``).
+
+- ``blitz skill install`` — drop the ``onboard-to-blitz`` Claude Code skill into
+  the repo's ``.claude/skills`` so Claude can run the onboarding playbook.
+
+- ``blitz scaffold -p <project> -w <workflow> -o ./train`` — download a
+  workflow's SFT dataset, held-out eval set, and base-model recommendation, then
+  emit a self-contained, runnable training project (Dockerfile + train.py +
+  eval.py). Authenticates with a read-scoped Blitz API key (``BLITZ_API_KEY``).
+"""
+
+__all__ = ["__version__"]
+
+__version__ = "0.3.0"

{blitz_cli-0.1.0 → blitz_cli-0.3.0}/blitz_cli/_client.py

@@ -26,8 +26,9 @@ class BlitzAPIError(RuntimeError):
 def _hint(status: int, detail: str) -> str:
     if status in (401, 403):
         return (
-            f"{detail} (HTTP {status}). Check BLITZ_API_KEY — it must be a "
-            "read-scoped key for this project (create one in the dashboard)."
+            f"{detail} (HTTP {status}). Check BLITZ_API_KEY — it must be a valid "
+            "key for this project (an ingest key for tracing/verify, a read key "
+            "for training data). Create one in the dashboard."
         )
     if status == 404:
         return (
@@ -71,6 +72,12 @@ class BlitzClient:
             except Exception:  # noqa: BLE001
                 pass
             raise BlitzAPIError(exc.code, _hint(exc.code, str(detail))) from None
+        except urllib.error.URLError as exc:
+            raise BlitzAPIError(
+                0,
+                f"could not reach the Blitz API at {self._base} ({exc.reason}). "
+                "Check BLITZ_ENDPOINT and your network.",
+            ) from None
 
     def _get_json(self, path: str, query: Optional[dict] = None) -> dict:
         req = urllib.request.Request(self._url(path, query), headers=self._headers)
@@ -136,3 +143,9 @@ class BlitzClient:
 
     def get_eval_run(self, run_id: str) -> dict:
         return self._get_json(self._p(f"/eval/runs/{run_id}"))
+
+    def ingest_status(self, workflow: Optional[str] = None) -> dict:
+        """Trace summary for `blitz verify`, authed by the ingest key. This is
+        the one read the ingest scope can do (path is not project-scoped; the
+        key resolves the project server-side)."""
+        return self._get_json("/blitz/v1/ingest-status", {"workflow": workflow})

blitz_cli-0.3.0/blitz_cli/_scan/__init__.py

@@ -0,0 +1,65 @@
+"""Codebase scan: find AI/LLM calls and report their Blitz instrumentation
+posture. Public surface: ``scan_path``, ``render_report``, ``dumps_json``."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Optional, Set
+
+from ._classify import classify
+from ._js import scan_js
+from ._models import ProjectSignals, ScanResult, Tier
+from ._python import scan_python
+from ._report import dumps_json, render_report
+from ._walk import iter_source_files
+
+__all__ = ["scan_path", "render_report", "dumps_json", "ScanResult", "Tier"]
+
+
+def scan_path(root: Path, langs: Optional[Set[str]] = None) -> ScanResult:
+    """Walk ``root``, detect LLM calls in each file, then classify every site
+    against tree-wide signals (whether the project calls ``blitz.init()``)."""
+    langs = langs or {"python", "js"}
+    root = root.resolve()
+    base = root if root.is_dir() else root.parent
+
+    result = ScanResult(root=str(root))
+    signals = ProjectSignals()
+
+    for path, lang in iter_source_files(root, langs):
+        try:
+            source = path.read_text(encoding="utf-8", errors="replace")
+        except OSError:
+            continue
+        rel = _relpath(path, base)
+        try:
+            scan = scan_python(path, source, rel) if lang == "python" else scan_js(
+                path, source, rel
+            )
+        except SyntaxError:
+            result.skipped.append(rel)
+            continue
+        signals.files_scanned += 1
+        if scan.has_init:
+            if lang == "python":
+                signals.has_python_init = True
+            else:
+                signals.has_js_init = True
+        result.sites.extend(scan.sites)
+
+    # Classification needs the tree-wide init signal, so it runs after the walk.
+    result.signals = signals
+    for site in result.sites:
+        classify(site, signals)
+
+    # Stable ordering: worst tier first, then path/line.
+    order = {Tier.UNSUPPORTED: 0, Tier.NO_INIT: 1, Tier.UNNAMED: 2, Tier.INSTRUMENTED: 3}
+    result.sites.sort(key=lambda s: (order.get(s.tier, 9), s.path, s.line))
+    return result
+
+
+def _relpath(path: Path, base: Path) -> str:
+    try:
+        return path.resolve().relative_to(base).as_posix()
+    except ValueError:
+        return path.as_posix()

blitz_cli-0.3.0/blitz_cli/_scan/_classify.py

@@ -0,0 +1,28 @@
+"""The 4-tier decision tree. Pure and language-agnostic: both detectors funnel
+their ``CallSite`` drafts through here once project-wide signals are known."""
+
+from __future__ import annotations
+
+from ._models import CallSite, Confidence, ProjectSignals, Provider, SUPPORTED, Tier
+
+
+def classify(site: CallSite, signals: ProjectSignals) -> None:
+    """Set ``site.tier`` (and adjust confidence) in place."""
+    if site.in_untraced:
+        # Intentional suppression (blitz-platform meta-calls). Not a miss; we
+        # still label it INSTRUMENTED-equivalent so it drops out of misses().
+        site.tier = Tier.INSTRUMENTED
+        return
+
+    if site.provider not in SUPPORTED:
+        site.tier = Tier.UNSUPPORTED
+    elif not signals.has_init(site.lang):
+        site.tier = Tier.NO_INIT
+    elif not site.in_named_workflow:
+        site.tier = Tier.UNNAMED
+        # A decorated caller further up the stack may already be tracing this
+        # helper at runtime — we can't see that lexically, so soften confidence.
+        if site.confidence is Confidence.HIGH:
+            site.confidence = Confidence.MEDIUM
+    else:
+        site.tier = Tier.INSTRUMENTED

blitz_cli-0.3.0/blitz_cli/_scan/_js.py

@@ -0,0 +1,98 @@
+"""JS/TS detector — honest regex heuristic.
+
+There's no stdlib JS parser and blitz-cli must stay dependency-free, so this is
+line-oriented ``re`` matching, not real parsing. Consequences, stated loudly:
+no scope resolution, no reliable client-var/decorator tracking, and — because a
+JS Blitz SDK's ``init`` can't be verified here — supported-provider JS calls are
+reported as NO_INIT at LOW confidence rather than pretending they're traced.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import List, Optional
+
+from ._models import CallSite, Confidence, FileScan, Provider
+
+# import specifier substring -> provider (used to know what a file touches)
+_IMPORT_PROVIDER = [
+    ("@anthropic-ai/sdk", Provider.ANTHROPIC),
+    ("@google/generative-ai", Provider.GEMINI),
+    ("@google/genai", Provider.GEMINI),
+    ("openai", Provider.OPENAI),
+    ("@langchain", Provider.LANGCHAIN),
+    ("langchain", Provider.LANGCHAIN),
+    ("litellm", Provider.LITELLM),
+    ("cohere-ai", Provider.COHERE),
+    ("@mistralai", Provider.MISTRAL),
+    ("@aws-sdk/client-bedrock", Provider.BEDROCK),
+    ("ollama", Provider.OLLAMA),
+    ("groq-sdk", Provider.GROQ),
+]
+
+# call-chain regex -> provider it identifies
+_CALL_PATTERNS = [
+    (re.compile(r"\.messages\.create\s*\("), Provider.ANTHROPIC),
+    (re.compile(r"\.messages\.stream\s*\("), Provider.ANTHROPIC),
+    (re.compile(r"\.chat\.completions\.create\s*\("), Provider.OPENAI),
+    (re.compile(r"\.responses\.create\s*\("), Provider.OPENAI),
+    (re.compile(r"\.generateContent\s*\("), Provider.GEMINI),
+    (re.compile(r"\.generateContentStream\s*\("), Provider.GEMINI),
+]
+
+_INIT_RE = re.compile(r"blitz\.init\s*\(")
+_WORKFLOW_RE = re.compile(r"blitz\.workflow\s*\(")
+
+
+def scan_js(path: Path, source: str, rel_path: str) -> FileScan:
+    lines = source.splitlines()
+    imported: List[Provider] = []
+    has_init = False
+    for ln in lines:
+        if _INIT_RE.search(ln):
+            has_init = True
+        for spec, prov in _IMPORT_PROVIDER:
+            if ("import" in ln or "require" in ln) and spec in ln and prov not in imported:
+                imported.append(prov)
+
+    sites: List[CallSite] = []
+    for i, ln in enumerate(lines, start=1):
+        for pat, prov in _CALL_PATTERNS:
+            m = pat.search(ln)
+            if not m:
+                continue
+            # Prefer a provider actually imported in this file; a bare
+            # `.responses.create` in a groq/azure file still reads as its shape.
+            provider = prov
+            sites.append(
+                CallSite(
+                    path=rel_path,
+                    line=i,
+                    provider=provider,
+                    lang="js",
+                    call_expr=m.group(0).rstrip("(").strip(),
+                    enclosing_func=_nearest_func(lines, i - 1),
+                    in_named_workflow=bool(_WORKFLOW_RE.search(ln)),
+                    in_untraced=False,
+                    confidence=Confidence.LOW,
+                )
+            )
+    return FileScan(sites=sites, has_init=has_init)
+
+
+_FUNC_RES = [
+    re.compile(r"function\s+([A-Za-z0-9_$]+)"),
+    re.compile(r"(?:const|let|var)\s+([A-Za-z0-9_$]+)\s*=\s*(?:async\s*)?\("),
+    re.compile(r"([A-Za-z0-9_$]+)\s*\([^)]*\)\s*\{"),
+]
+
+
+def _nearest_func(lines: List[str], idx: int) -> Optional[str]:
+    """Best-effort: the nearest preceding function-ish declaration name."""
+    for j in range(idx, max(-1, idx - 60), -1):
+        for rx in _FUNC_RES:
+            m = rx.search(lines[j])
+            if m:
+                return m.group(1)
+    return None

blitz_cli-0.3.0/blitz_cli/_scan/_models.py

@@ -0,0 +1,126 @@
+"""Data model for the codebase scan: providers, tiers, and per-call records.
+
+Everything here is stdlib-only (``dataclasses`` + ``enum``) so the whole scan
+subpackage stays dependency-free like the rest of blitz-cli. The detectors
+(``_python``/``_js``) emit ``CallSite`` drafts; ``_classify`` fills in ``tier``;
+``_report`` renders them.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Dict, List, Optional
+
+
+class Provider(str, Enum):
+    """Every LLM provider we can name. Only ``SUPPORTED`` ones are auto-traced
+    by ``blitz.init()``; the rest are invisible to Blitz today."""
+
+    OPENAI = "openai"
+    ANTHROPIC = "anthropic"
+    GEMINI = "gemini"
+    LANGCHAIN = "langchain"
+    PYDANTIC_AI = "pydantic-ai"
+    LITELLM = "litellm"
+    COHERE = "cohere"
+    MISTRAL = "mistral"
+    BEDROCK = "bedrock"
+    VERTEX = "vertex"
+    OLLAMA = "ollama"
+    GROQ = "groq"
+    UNKNOWN = "unknown"
+
+
+# Providers whose calls blitz traces after a single blitz.init().
+#   - openai / anthropic / gemini: directly auto-instrumented via OpenLLMetry.
+#   - pydantic-ai: a thin typed wrapper that always calls the official
+#     openai/anthropic/gemini SDKs at the exact methods OpenLLMetry patches
+#     (verified: the pinned anthropic instrumentor wraps beta.messages.AsyncMessages
+#     .create, which is what pydantic-ai's AnthropicModel calls). So it IS traced
+#     once init runs — the gate is init, not the framework. (Caveat: a pydantic-ai
+#     model over a non-supported provider, e.g. groq/mistral, would not be traced.)
+SUPPORTED = {
+    Provider.OPENAI,
+    Provider.ANTHROPIC,
+    Provider.GEMINI,
+    Provider.PYDANTIC_AI,
+}
+
+
+class Tier(str, Enum):
+    """Instrumentation posture of a single AI call, worst-first when reported."""
+
+    UNSUPPORTED = "unsupported"  # provider blitz can't auto-trace at all
+    NO_INIT = "no_init"  # supported, but the project never calls blitz.init()
+    UNNAMED = "unnamed"  # traced, but not under a named workflow()
+    INSTRUMENTED = "instrumented"  # supported + init + under a workflow()
+
+
+class Confidence(str, Enum):
+    HIGH = "high"  # python ast, lexical facts certain
+    MEDIUM = "medium"  # python ast, but the call-graph caveat may apply
+    LOW = "low"  # js/ts regex heuristic
+
+
+@dataclass
+class CallSite:
+    """One detected AI/LLM call and everything we know about how it's wrapped."""
+
+    path: str  # relative to the scan root, posix-style
+    line: int
+    provider: Provider
+    lang: str  # "python" | "js"
+    call_expr: str  # e.g. "client.messages.create"
+    enclosing_func: Optional[str] = None  # for the workflow-name suggestion
+    in_named_workflow: bool = False  # lexical `with blitz.workflow` OR decorator
+    in_untraced: bool = False  # inside `with _untraced():` — suppressed on purpose
+    confidence: Confidence = Confidence.HIGH
+    tier: Optional[Tier] = None  # filled by _classify
+
+
+@dataclass
+class ProjectSignals:
+    """Tree-wide facts that decide NO_INIT vs UNNAMED for the whole scan."""
+
+    has_python_init: bool = False  # `blitz.init(` resolved anywhere in the .py tree
+    has_js_init: bool = False  # best-effort; a JS SDK may not exist yet
+    files_scanned: int = 0
+
+    def has_init(self, lang: str) -> bool:
+        return self.has_python_init if lang == "python" else self.has_js_init
+
+
+@dataclass
+class FileScan:
+    """What a single-file detector returns before project-wide aggregation."""
+
+    sites: List[CallSite] = field(default_factory=list)
+    has_init: bool = False
+
+
+@dataclass
+class ScanResult:
+    root: str
+    signals: ProjectSignals = field(default_factory=ProjectSignals)
+    sites: List[CallSite] = field(default_factory=list)
+    skipped: List[str] = field(default_factory=list)  # files we couldn't parse
+
+    def misses(self) -> List[CallSite]:
+        """Sites a user should act on: anything not fully instrumented, minus the
+        intentionally-suppressed ``_untraced()`` calls."""
+        return [
+            s
+            for s in self.sites
+            if not s.in_untraced and s.tier is not Tier.INSTRUMENTED
+        ]
+
+    def by_tier(self) -> Dict[Tier, List[CallSite]]:
+        out: Dict[Tier, List[CallSite]] = {t: [] for t in Tier}
+        for s in self.sites:
+            if s.tier is not None:
+                out[s.tier].append(s)
+        return out
+
+    def untraced(self) -> List[CallSite]:
+        return [s for s in self.sites if s.in_untraced]