blitz-cli 0.13.0__tar.gz → 0.15.0__tar.gz

{blitz_cli-0.13.0 → blitz_cli-0.15.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: blitz-cli
-Version: 0.13.0
+Version: 0.15.0
 Summary: Developer CLI for Blitz locker-room: spec-driven playbooks, a codebase/huddle ontology graph with an MCP tool, and the composable watcher/trainer/graph containers.
 License: MIT
 License-File: LICENSE
@@ -75,6 +75,37 @@ Tasks whose text says "optional manual" are skipped and left unchecked. The
 Ollama endpoint comes from `--ollama-url` or `OLLAMA_HOST`; the model from
 `--model` or `BLITZ_EXECUTE_MODEL`.
 
+### Collection over the ingest endpoint
+
+`blitz model execute --collect` records every generation attempt as DPO
+training data. By default it writes straight to the activity SQLite database
+(`BLITZ_ACTIVITY_DB_PATH`, else `data/activity.db`). With `BLITZ_COLLECT_ENDPOINT` set,
+the same writes go over HTTP JSON to a collect ingest server instead, so the
+collector needs no filesystem access to the database:
+
+```bash
+# on the locker-room node (default port 1739, binds all interfaces, no auth):
+BLITZ_ACTIVITY_DB_PATH=data/activity.db blitz locker-room collect-serve
+
+# on the collecting machine:
+BLITZ_COLLECT_ENDPOINT=http://locker-room-host:1739 blitz model execute --collect
+```
+
+Each attempt is acknowledged by the endpoint before the next model call
+starts. If the endpoint is unreachable when the run starts, the run fails
+fast, same as an unwritable database. If it fails mid-run, the run keeps
+going: undelivered payloads are buffered to `collect-buffer.jsonl` in the run
+directory and the final output names the file. Deliver them later with
+
+```bash
+blitz model collect flush .blitz/execute/runs/<stamp>/collect-buffer.jsonl
+```
+
+Flushing is idempotent (the server deduplicates attempts on their
+run/task/sample/attempt identity), so re-running a flush, or flushing rows the
+server already received, never duplicates data. `pairs extract/export/stats`
+read the database directly, unaffected by the endpoint.
+
 ## Locker-room: ontology graph, watcher, trainer, MCP
 
 The locker-room is a **context node**: a set of containers that ingest, build,
@@ -110,9 +141,9 @@ diff links it to the code it touches (`Feature -TOUCHES-> File/Symbol`), so an
 agent can walk a spec out to the full lineage of code it implements, and back.
 
 The `mcp` role serves this: point an agent's MCP config at
-`http://<node>:8848/sse` (tools `list_repos`, `get_repo`, `list_huddles`,
+`http://<node>:1738/sse` (tools `list_repos`, `get_repo`, `list_huddles`,
 `get_huddle`, `get_playbooks`, `get_lineage`, `impact_of`, `get_file`,
-`get_symbol`, `neighbors`), or open `http://<node>:8848/graph` in a browser.
+`get_symbol`, `neighbors`), or open `http://<node>:1738/graph` in a browser.
 
 ### Training (optional)
 
@@ -120,7 +151,7 @@ The `mcp` role serves this: point an agent's MCP config at
 
 `blitz locker-room train` runs an on-demand QLoRA fine-tune of the watcher corpus
 in the trainer container (needs a GPU); adapters land in `./train-out`. Override
-the base model with `BASE_MODEL_HF` or `blitz locker-room init --base-model`.
+the base model with `BLITZ_BASE_MODEL_HF` or `blitz locker-room init --base-model`.
 
 ## Activity: replay a coding-agent session
 

{blitz_cli-0.13.0 → blitz_cli-0.15.0}/README.md

@@ -56,6 +56,37 @@ Tasks whose text says "optional manual" are skipped and left unchecked. The
 Ollama endpoint comes from `--ollama-url` or `OLLAMA_HOST`; the model from
 `--model` or `BLITZ_EXECUTE_MODEL`.
 
+### Collection over the ingest endpoint
+
+`blitz model execute --collect` records every generation attempt as DPO
+training data. By default it writes straight to the activity SQLite database
+(`BLITZ_ACTIVITY_DB_PATH`, else `data/activity.db`). With `BLITZ_COLLECT_ENDPOINT` set,
+the same writes go over HTTP JSON to a collect ingest server instead, so the
+collector needs no filesystem access to the database:
+
+```bash
+# on the locker-room node (default port 1739, binds all interfaces, no auth):
+BLITZ_ACTIVITY_DB_PATH=data/activity.db blitz locker-room collect-serve
+
+# on the collecting machine:
+BLITZ_COLLECT_ENDPOINT=http://locker-room-host:1739 blitz model execute --collect
+```
+
+Each attempt is acknowledged by the endpoint before the next model call
+starts. If the endpoint is unreachable when the run starts, the run fails
+fast, same as an unwritable database. If it fails mid-run, the run keeps
+going: undelivered payloads are buffered to `collect-buffer.jsonl` in the run
+directory and the final output names the file. Deliver them later with
+
+```bash
+blitz model collect flush .blitz/execute/runs/<stamp>/collect-buffer.jsonl
+```
+
+Flushing is idempotent (the server deduplicates attempts on their
+run/task/sample/attempt identity), so re-running a flush, or flushing rows the
+server already received, never duplicates data. `pairs extract/export/stats`
+read the database directly, unaffected by the endpoint.
+
 ## Locker-room: ontology graph, watcher, trainer, MCP
 
 The locker-room is a **context node**: a set of containers that ingest, build,
@@ -91,9 +122,9 @@ diff links it to the code it touches (`Feature -TOUCHES-> File/Symbol`), so an
 agent can walk a spec out to the full lineage of code it implements, and back.
 
 The `mcp` role serves this: point an agent's MCP config at
-`http://<node>:8848/sse` (tools `list_repos`, `get_repo`, `list_huddles`,
+`http://<node>:1738/sse` (tools `list_repos`, `get_repo`, `list_huddles`,
 `get_huddle`, `get_playbooks`, `get_lineage`, `impact_of`, `get_file`,
-`get_symbol`, `neighbors`), or open `http://<node>:8848/graph` in a browser.
+`get_symbol`, `neighbors`), or open `http://<node>:1738/graph` in a browser.
 
 ### Training (optional)
 
@@ -101,7 +132,7 @@ The `mcp` role serves this: point an agent's MCP config at
 
 `blitz locker-room train` runs an on-demand QLoRA fine-tune of the watcher corpus
 in the trainer container (needs a GPU); adapters land in `./train-out`. Override
-the base model with `BASE_MODEL_HF` or `blitz locker-room init --base-model`.
+the base model with `BLITZ_BASE_MODEL_HF` or `blitz locker-room init --base-model`.
 
 ## Activity: replay a coding-agent session
 

{blitz_cli-0.13.0 → blitz_cli-0.15.0}/blitz_cli/__init__.py

@@ -30,4 +30,4 @@ Commands:
 
 __all__ = ["__version__"]
 
-__version__ = "0.12.0"
+__version__ = "0.15.0"

{blitz_cli-0.13.0 → blitz_cli-0.15.0}/blitz_cli/_collect.py

@@ -4,7 +4,7 @@
 `CollectStore` owns four tables (`collect_runs`, `collect_attempts`,
 `dpo_pairs`, `sft_queue`) in the same locker-room activity database that
 `_corpus.py`'s `TurnStore` writes its transcript corpus to (default
-`data/activity.db`, env override `ACTIVITY_DB_PATH`, WAL journal). Like
+`data/activity.db`, env override `BLITZ_ACTIVITY_DB_PATH`, WAL journal). Like
 `TurnStore`, it is the one writer of its tables and creates its schema on
 first connect.
 
@@ -95,10 +95,38 @@ CREATE TABLE IF NOT EXISTS sft_queue (
 """
 
 
+# Sentinel spec value for stub runs the ingest server creates when a write
+# references a run_id it has no row for (for example the server restarted onto
+# a fresh database mid-run). Flushes must survive server-side data loss, so
+# ingestion never rejects a write for an unknown run; the sentinel keeps
+# recovered runs visible in stats output.
+RECOVERED_SPEC = "__recovered__"
+
+# collect_runs metadata columns in insert order, shared by insert/ingest paths
+# and by the ingest server's payload validation (payload fields mirror these
+# column names 1:1; started_at/finished_at are server-owned).
+RUN_FIELDS = (
+    "run_id", "repo_path", "spec", "tasks_file", "model", "endpoint",
+    "temperature", "max_retries", "k",
+)
+
+# collect_attempts client-sent columns. attempt_id and created_at are
+# server-owned; env_failure/judge_* are judge-side and never client-sent.
+ATTEMPT_REQUIRED_FIELDS = (
+    "run_id", "task_id", "sample_index", "attempt_index",
+    "prompt_messages_json", "reply", "actions_json", "passed",
+)
+ATTEMPT_OPTIONAL_FIELDS = (
+    "error_detail", "guard_violation", "input_tokens", "output_tokens",
+)
+
+SFT_FIELDS = ("run_id", "task_id", "prompt_messages_json")
+
+
 def default_db_path() -> Path:
-    """The activity database path: ACTIVITY_DB_PATH env override, else the
+    """The activity database path: BLITZ_ACTIVITY_DB_PATH env override, else the
     conventional data/activity.db relative to the CWD (same idiom as _train.py)."""
-    return Path(os.environ.get("ACTIVITY_DB_PATH", "data/activity.db"))
+    return Path(os.environ.get("BLITZ_ACTIVITY_DB_PATH", "data/activity.db"))
 
 
 def _now_iso() -> str:
@@ -225,6 +253,104 @@ class CollectStore:
         finally:
             conn.close()
 
+    # -- Ingest-server write path ---------------------------------------
+    # These methods back the collect ingest endpoint (_collect_server.py).
+    # They differ from the insert_* methods above in two ways: every write
+    # is idempotent (retries, flush re-runs, and flush-after-partial-delivery
+    # are no-ops), and the server stamps its own timestamps. Payload shapes
+    # mirror the column names 1:1 (RUN_FIELDS / ATTEMPT_*_FIELDS / SFT_FIELDS).
+
+    def _ensure_run(self, conn: sqlite3.Connection, run_id: str) -> None:
+        """Auto-create a recovered stub run when run_id has no row, so writes
+        referencing a run the server never saw are accepted, never rejected.
+        The stub is marked with the RECOVERED_SPEC sentinel."""
+        conn.execute(
+            "INSERT OR IGNORE INTO collect_runs (run_id, repo_path, spec, "
+            "tasks_file, model, endpoint, temperature, max_retries, k, started_at) "
+            "VALUES (?, '', ?, '', '', '', 0.0, 0, 0, ?)",
+            (run_id, RECOVERED_SPEC, _now_iso()),
+        )
+
+    def ingest_run(self, payload: dict) -> bool:
+        """Idempotent run-open: INSERT OR IGNORE on the run_id primary key,
+        started_at stamped by this server. Returns True when the row was
+        created, False when the run_id already existed (no changes made)."""
+        conn = self._connect()
+        try:
+            cur = conn.execute(
+                "INSERT OR IGNORE INTO collect_runs (run_id, repo_path, spec, "
+                "tasks_file, model, endpoint, temperature, max_retries, k, "
+                "started_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)",
+                tuple(payload[f] for f in RUN_FIELDS) + (_now_iso(),),
+            )
+            conn.commit()
+            return bool(cur.rowcount)
+        finally:
+            conn.close()
+
+    def ingest_attempts(self, rows: list) -> tuple:
+        """Idempotent batch attempt ingestion in one transaction: INSERT OR
+        IGNORE on the natural key (run_id, task_id, sample_index,
+        attempt_index), created_at stamped by this server, unknown run_ids
+        recovered via a stub run. Returns (inserted, duplicates)."""
+        inserted = duplicates = 0
+        conn = self._connect()
+        try:
+            for row in rows:
+                self._ensure_run(conn, row["run_id"])
+                cur = conn.execute(
+                    "INSERT OR IGNORE INTO collect_attempts (run_id, task_id, "
+                    "sample_index, attempt_index, prompt_messages_json, reply, "
+                    "actions_json, passed, error_detail, guard_violation, "
+                    "input_tokens, output_tokens, created_at) "
+                    "VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)",
+                    tuple(row[f] for f in ATTEMPT_REQUIRED_FIELDS)
+                    + tuple(row.get(f) for f in ATTEMPT_OPTIONAL_FIELDS)
+                    + (_now_iso(),),
+                )
+                if cur.rowcount:
+                    inserted += 1
+                else:
+                    duplicates += 1
+            conn.commit()
+            return inserted, duplicates
+        finally:
+            conn.close()
+
+    def finish_run_if_open(self, run_id: str) -> None:
+        """Replay-safe finish: stamps finished_at only while it is NULL, so a
+        flushed or retried finish marker never moves an existing stamp.
+        Unknown run_ids get a recovered stub run first."""
+        conn = self._connect()
+        try:
+            self._ensure_run(conn, run_id)
+            conn.execute(
+                "UPDATE collect_runs SET finished_at = ? "
+                "WHERE run_id = ? AND finished_at IS NULL",
+                (_now_iso(), run_id),
+            )
+            conn.commit()
+        finally:
+            conn.close()
+
+    def ingest_sft(self, payload: dict) -> bool:
+        """Idempotent sft placeholder ingestion (UNIQUE(run_id, task_id)),
+        created_at stamped by this server, unknown run_ids recovered.
+        Returns True when a row was created, False when already present."""
+        conn = self._connect()
+        try:
+            self._ensure_run(conn, payload["run_id"])
+            cur = conn.execute(
+                "INSERT OR IGNORE INTO sft_queue "
+                "(run_id, task_id, prompt_messages_json, created_at) "
+                "VALUES (?, ?, ?, ?)",
+                tuple(payload[f] for f in SFT_FIELDS) + (_now_iso(),),
+            )
+            conn.commit()
+            return bool(cur.rowcount)
+        finally:
+            conn.close()
+
 
 def extract_pairs(store: CollectStore, run_id: Optional[str] = None) -> dict:
     """Materialize eligible DPO preference pairs from collected attempts.

blitz_cli-0.15.0/blitz_cli/_collect_http.py

@@ -0,0 +1,241 @@
+"""HTTP collection sink and buffer/flush tooling for the collect ingest
+endpoint (see _collect_server.py for the server side).
+
+`HttpCollectSink` is the BLITZ_COLLECT_ENDPOINT-selected counterpart of
+`_collect.CollectStore`: it exposes the same methods the execute loop calls
+(check_writable, insert_run, insert_attempt, finish_run,
+insert_sft_placeholder) but delivers each payload synchronously over HTTP, so
+an attempt is durable at the endpoint before the next model call starts.
+Stdlib only (urllib), per the repo's runtime dependency constraint.
+
+Failure semantics (contracts/client-sink.md): an unreachable endpoint at run
+start fails fast via check_writable (OSError, same failure class as an
+unwritable database). Once the run has started, the first delivery failure of
+any kind flips the sink into buffered mode: the failed payload and every
+subsequent one (attempts, sft placeholders, the finish marker) are appended as
+JSONL to <rundir>/collect-buffer.jsonl, the run never fails because of the
+sink, and buffer_notice() tells the user what was buffered and how to flush
+it. `blitz model collect flush <buffer-file>` replays the records in order;
+the server's idempotent writes make retries and re-flushes duplicate-free.
+"""
+
+from __future__ import annotations
+
+import json
+import urllib.error
+import urllib.request
+from pathlib import Path
+from typing import Callable, Optional
+
+BUFFER_FILENAME = "collect-buffer.jsonl"
+
+_TIMEOUT = 10  # seconds per request; a hung sink must not stall model calls long
+
+
+def post_json(endpoint: str, path: str, payload: dict, timeout: int = _TIMEOUT) -> dict:
+    """POST payload as JSON to endpoint+path and return the parsed JSON reply.
+    Raises OSError (URLError subclasses it) on connection failure or timeout
+    and urllib.error.HTTPError (also an OSError) on any non-2xx status."""
+    req = urllib.request.Request(
+        endpoint.rstrip("/") + path,
+        data=json.dumps(payload).encode(),
+        headers={"Content-Type": "application/json"},
+    )
+    with urllib.request.urlopen(req, timeout=timeout) as resp:
+        return json.load(resp)
+
+
+def _path_for(kind: str, payload: dict) -> str:
+    if kind == "run":
+        return "/v1/collect/runs"
+    if kind == "attempts":
+        return "/v1/collect/attempts"
+    if kind == "finish":
+        return f"/v1/collect/runs/{payload['run_id']}/finish"
+    if kind == "sft":
+        return "/v1/collect/sft"
+    raise ValueError(f"unknown buffer record kind {kind!r}")
+
+
+class HttpCollectSink:
+    """Collection sink that writes through the ingest endpoint instead of
+    opening the activity database. Duck-types CollectStore's writer surface;
+    selected by cli._cmd_execute when BLITZ_COLLECT_ENDPOINT is set."""
+
+    def __init__(self, endpoint: str, timeout: int = _TIMEOUT):
+        self.endpoint = endpoint.rstrip("/")
+        self._timeout = timeout
+        self._buffer_path: Optional[Path] = None
+        self._failed = False
+        self._first_error: Optional[str] = None
+        self._buffered_count = 0
+
+    # -- run-start reachability check (same failure class as an unwritable db)
+
+    def check_writable(self) -> None:
+        """GET /v1/health; raises OSError when the endpoint is unreachable or
+        unhealthy so the run fails fast before any task executes."""
+        try:
+            with urllib.request.urlopen(
+                self.endpoint + "/v1/health", timeout=self._timeout
+            ) as resp:
+                json.load(resp)
+        except OSError:
+            raise
+        except Exception as exc:  # non-JSON body etc.
+            raise OSError(f"collect endpoint health check failed: {exc}")
+
+    # -- execute-loop hooks (discovered with getattr; CollectStore has neither)
+
+    def bind_rundir(self, rundir: Path) -> None:
+        """Called by _execute.run once the run directory exists; the JSONL
+        buffer for undeliverable payloads lives there."""
+        self._buffer_path = Path(rundir) / BUFFER_FILENAME
+
+    def buffer_notice(self) -> Optional[str]:
+        """A user-facing message when payloads were buffered, else None."""
+        if not self._buffered_count:
+            return None
+        return (
+            f"collect: endpoint {self.endpoint} failed mid-run "
+            f"({self._first_error}); {self._buffered_count} payload(s) were "
+            f"buffered to {self._buffer_path}. The run itself is unaffected. "
+            f"Deliver them later with: blitz model collect flush {self._buffer_path}"
+        )
+
+    # -- delivery core
+
+    def _deliver(self, kind: str, payload: dict) -> None:
+        """Send one payload, or buffer it. After the first failure everything
+        goes to the buffer: this preserves delivery order in the file and
+        avoids paying a connection timeout on every remaining model call."""
+        if not self._failed:
+            try:
+                post_json(self.endpoint, _path_for(kind, payload), payload,
+                          timeout=self._timeout)
+                return
+            except Exception as exc:
+                self._failed = True
+                self._first_error = f"{type(exc).__name__}: {exc}"
+        self._buffer(kind, payload)
+
+    def _buffer(self, kind: str, payload: dict) -> None:
+        if self._buffer_path is None:
+            raise RuntimeError(
+                "HttpCollectSink cannot buffer before bind_rundir() is called"
+            )
+        self._buffer_path.parent.mkdir(parents=True, exist_ok=True)
+        with self._buffer_path.open("a", encoding="utf-8") as f:
+            f.write(json.dumps({"kind": kind, "payload": payload},
+                               ensure_ascii=False) + "\n")
+        self._buffered_count += 1
+
+    # -- CollectStore writer surface
+
+    def insert_run(
+        self,
+        run_id: str,
+        repo_path: str,
+        spec: str,
+        tasks_file: str,
+        model: str,
+        endpoint: str,
+        temperature: float,
+        max_retries: int,
+        k: int,
+    ) -> None:
+        self._deliver("run", {
+            "run_id": run_id, "repo_path": repo_path, "spec": spec,
+            "tasks_file": tasks_file, "model": model, "endpoint": endpoint,
+            "temperature": temperature, "max_retries": max_retries, "k": k,
+        })
+
+    def insert_attempt(
+        self,
+        run_id: str,
+        task_id: str,
+        sample_index: int,
+        attempt_index: int,
+        prompt_messages_json: str,
+        reply: str,
+        actions_json: str,
+        passed: int,
+        error_detail: Optional[str] = None,
+        guard_violation: Optional[str] = None,
+        input_tokens: Optional[int] = None,
+        output_tokens: Optional[int] = None,
+    ) -> int:
+        self._deliver("attempts", {"attempts": [{
+            "run_id": run_id, "task_id": task_id,
+            "sample_index": sample_index, "attempt_index": attempt_index,
+            "prompt_messages_json": prompt_messages_json, "reply": reply,
+            "actions_json": actions_json, "passed": passed,
+            "error_detail": error_detail, "guard_violation": guard_violation,
+            "input_tokens": input_tokens, "output_tokens": output_tokens,
+        }]})
+        # The direct store returns the autoincrement attempt_id; the execute
+        # loop ignores it, and over HTTP the id is server-side only.
+        return 0
+
+    def finish_run(self, run_id: str) -> None:
+        self._deliver("finish", {"run_id": run_id})
+
+    def insert_sft_placeholder(
+        self, run_id: str, task_id: str, prompt_messages_json: str
+    ) -> None:
+        self._deliver("sft", {
+            "run_id": run_id, "task_id": task_id,
+            "prompt_messages_json": prompt_messages_json,
+        })
+
+
+def flush_buffer(
+    buffer_path: Path,
+    endpoint: str,
+    print_fn: Callable = print,
+    timeout: int = _TIMEOUT,
+) -> int:
+    """Deliver every record of a collect buffer file, in file order, to the
+    ingest endpoint. Returns 0 on full delivery, 1 on the first failure (the
+    file is left intact either way; server-side idempotency makes re-runs and
+    partial overlaps duplicate-free). Reports delivered attempt counts."""
+    buffer_path = Path(buffer_path)
+    records = []
+    with buffer_path.open("r", encoding="utf-8") as f:
+        for n, line in enumerate(f, 1):
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                rec = json.loads(line)
+                kind, payload = rec["kind"], rec["payload"]
+                _path_for(kind, payload)  # validates the kind
+            except (ValueError, KeyError, TypeError) as exc:
+                print_fn(f"error: {buffer_path}:{n} is not a valid buffer record: {exc}")
+                return 1
+            records.append((n, kind, payload))
+
+    if not records:
+        print_fn(f"{buffer_path}: nothing to flush")
+        return 0
+
+    inserted = duplicates = 0
+    for n, kind, payload in records:
+        try:
+            reply = post_json(endpoint, _path_for(kind, payload), payload,
+                              timeout=timeout)
+        except Exception as exc:
+            print_fn(
+                f"error: delivery failed at {buffer_path}:{n} ({kind}): {exc}. "
+                "The buffer file is unchanged; re-run the flush once the "
+                "endpoint is reachable (idempotent, no duplicates)."
+            )
+            return 1
+        if kind == "attempts":
+            inserted += reply.get("inserted", 0)
+            duplicates += reply.get("duplicates", 0)
+    print_fn(
+        f"flushed {len(records)} record(s) from {buffer_path}: "
+        f"{inserted} attempt(s) inserted, {duplicates} duplicate(s) ignored"
+    )
+    return 0