buildai-cli 0.3.87__tar.gz → 0.3.89__tar.gz

{buildai_cli-0.3.87 → buildai_cli-0.3.89}/.gitignore

@@ -21,6 +21,8 @@ dist/
 !apps/buildai-openai-ingest/frontend/dist/
 !apps/buildai-openai-ingest/frontend/dist/index.html
 !apps/buildai-openai-ingest/frontend/dist/mac-mini.png
+# Vendored BuildSpec engine — commit its built dist; node_modules stays ignored.
+!tools/buildspec/dist/
 build/
 .pytest_cache/
 .mypy_cache/
@@ -106,6 +108,9 @@ recording-cache/
 /datasets/250k-hour-dataset/build/**/out/
 /datasets/imu-on-head-frames-2026-04-25/*
 !/datasets/imu-on-head-frames-2026-04-25/README.md
+!/datasets/golden-ego-exo/build/
+!/datasets/golden-ego-exo/build/**
+/datasets/golden-ego-exo/build/**/out/
 /datasets/dataset-*.json
 /datasets/**/__pycache__/
 /datasets/**/frames/

buildai_cli-0.3.89/AGENTS.md

@@ -0,0 +1,44 @@
+# BuildAI CLI — Typer CLI with standalone (API-backed) and workspace (DB-direct) modes.
+
+## Read first
+
+- [../../AGENTS.md](../../AGENTS.md)
+- Docs site Engineering section (`make docs`)
+- Docs site Operations > Database roles (`make docs`)
+
+## Rules
+
+**Two planes.**
+
+| Mode | Install | Auth | DB access |
+|------|---------|------|-----------|
+| Standalone (`buildai`) | `uv tool install buildai-cli` | API key / JWT | Through API |
+| Workspace (`uv run buildai`) | Repo-local editable install | IAM / password | Direct via `db`, through profile-keyed local broker |
+
+**DB guards.** `db` subcommands require workspace install + gcloud IAM. Inspection/migration uses a profile-keyed `alloydb-auth-proxy` broker with state in `~/.buildai/db-brokers` (shared across worktrees). Use `buildai db broker status|ensure|stop` for local transport.
+
+**Writes.** Require `--write`. Production migrations prompt for confirmation.
+
+**Targeting.** Worktree app/runtime targeting comes from explicit env vars and the repo Makefile, not a saved CLI context layer. `buildai db --env` selects `production`, `staging`, or `dev`.
+
+**Staging.** Private-IP only. Start `buildai db --env staging tunnel`, then pass `--all-proxy socks5://127.0.0.1:1080` for queries.
+
+**Workers.** Call the API through the SDK; do not import `core/` or access the database directly from worker shells.
+
+## Verify
+
+```bash
+buildai auth whoami
+uv run buildai ingest deploy plan --scope active
+buildai db broker status
+buildai db schema tables
+buildai db query "SELECT count(*) FROM core.clips"
+buildai db --env staging tunnel   # in one terminal; query with --all-proxy in another
+```
+
+## Don't
+
+- Run `db --write` without `--write`.
+- Query staging without an IAP/VPN/SOCKS route and `--all-proxy`.
+- Assume a saved CLI context picks the worktree's DB lane — use env vars and Makefile.
+- Deploy ingest fleet changes from an unclear branch or dirty checkout.

buildai_cli-0.3.89/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

{buildai_cli-0.3.87 → buildai_cli-0.3.89}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: buildai-cli
-Version: 0.3.87
+Version: 0.3.89
 Summary: Build AI CLI (Typer)
 Requires-Python: >=3.11
 Requires-Dist: httpx>=0.27.0

buildai_cli-0.3.89/cli/commands/ego_frame_search.py

@@ -0,0 +1,569 @@
+"""Operator commands for the reusable ego frame-search embedding space."""
+
+from __future__ import annotations
+
+import asyncio
+from dataclasses import asdict, is_dataclass
+from uuid import UUID
+
+import typer
+
+from cli.context import get_cli_context
+from cli.ops_init import init_ops_context
+from cli.output import Format, format_option, render
+
+app = typer.Typer(no_args_is_help=True, help="Operate ego frame-search embeddings.")
+_SUBMITTED_BY = "00000000-0000-0000-0000-000000000000"
+
+
+@app.callback()
+def ego_frame_search_callback(
+    ctx: typer.Context,
+    env: str | None = typer.Option(
+        None,
+        "--env",
+        "-e",
+        help="Target environment. Defaults to APP_ENV, then production.",
+    ),
+    auth: str = typer.Option(None, "--auth", "-a", help="Auth method: iam or password."),
+    user: str = typer.Option(None, "--user", "-u", help="Override database user."),
+    profile: str | None = typer.Option(
+        None,
+        "--profile",
+        "-p",
+        help="Auth workflow profile. Use internal_admin for writes.",
+    ),
+    all_proxy: str | None = typer.Option(
+        None,
+        "--all-proxy",
+        help="Proxy URL passed to alloydb-auth-proxy for private-only DB lanes.",
+    ),
+    verbose: bool = typer.Option(False, "--verbose", "-v", help="Verbose logging."),
+) -> None:
+    """Capture DB-targeting flags; subcommands initialize ops context lazily."""
+    ctx.ensure_object(dict)
+    ctx.obj["cli_profile"] = profile
+    ctx.obj["_env"] = env
+    ctx.obj["_auth"] = auth
+    ctx.obj["_user"] = user
+    ctx.obj["_all_proxy"] = all_proxy
+    ctx.obj["_verbose"] = verbose
+    ctx.obj.setdefault("allow_write", False)
+    ctx.obj.setdefault("_ops_ready", False)
+
+
+def _settings_for_command(ctx: typer.Context, *, write: bool) -> object:
+    """Initialize the repo DB settings for one command."""
+    ctx.ensure_object(dict)
+    ctx.obj["allow_write"] = write
+    if "settings" in ctx.obj:
+        return ctx.obj["settings"]
+    return init_ops_context(ctx)
+
+
+def _require_internal_admin_for_write(ctx: typer.Context, *, write: bool) -> None:
+    """Require the explicit admin profile before direct DB writes."""
+    if not write:
+        return
+    profile = (ctx.obj or {}).get("cli_profile") or "engineers-dev"
+    if profile != "internal_admin":
+        raise typer.BadParameter("writes require --profile internal_admin")
+
+
+def _plain(value: object) -> object:
+    """Convert dataclass outputs into JSON/table-friendly dictionaries."""
+    if is_dataclass(value) and not isinstance(value, type):
+        return asdict(value)
+    if isinstance(value, list):
+        return [_plain(item) for item in value]
+    return value
+
+
+async def _resolve_space_id(dal_ctx: object, *, space_id: int | None, space_key: str | None) -> int:
+    """Resolve one space id from either numeric id or semantic key."""
+    from dal.embeddings import spaces as spaces_dal
+
+    if space_id is not None and space_key is not None:
+        raise typer.BadParameter("pass either --space-id or --space-key, not both")
+    if space_id is not None:
+        return space_id
+    if space_key is None:
+        space_key = "qwen.frame.global.ego.default"
+    space = await spaces_dal.get_by_space_key(dal_ctx, space_key)
+    return space.id
+
+
+@app.command("corpora")
+def corpora(
+    ctx: typer.Context,
+    format: Format = format_option(),
+) -> None:
+    """List registered ego frame-search corpora and route flags."""
+    settings = _settings_for_command(ctx, write=False)
+
+    async def run() -> None:
+        from dal.embeddings import ego_frame_search as ego_search_dal
+
+        async with get_cli_context(settings, profile=(ctx.obj or {}).get("cli_profile")) as (
+            _db,
+            dal_ctx,
+        ):
+            rows = await ego_search_dal.list_corpora(dal_ctx)
+        render(rows, format=format)
+
+    asyncio.run(run())
+
+
+@app.command("membership-program")
+def membership_program(
+    ctx: typer.Context,
+    corpus_key: str = typer.Option(..., "--corpus-key", help="Target corpus key."),
+    program_id: list[UUID] = typer.Option(..., "--program-id", help="Program id to include."),
+    run_id: str = typer.Option("manual", "--run-id", help="Membership materialization run id."),
+    limit: int | None = typer.Option(None, "--limit", min=1, help="Cap candidate clips."),
+    write: bool = typer.Option(False, "--write", help="Insert membership rows."),
+    format: Format = format_option(),
+) -> None:
+    """Dry-run or materialize corpus membership from program-source clips."""
+    _require_internal_admin_for_write(ctx, write=write)
+    settings = _settings_for_command(ctx, write=write)
+
+    async def run() -> None:
+        from dal.embeddings import ego_frame_search as ego_search_dal
+
+        async with get_cli_context(settings, profile=(ctx.obj or {}).get("cli_profile")) as (
+            _db,
+            dal_ctx,
+        ):
+            summary = await ego_search_dal.materialize_program_membership(
+                dal_ctx,
+                corpus_key=corpus_key,
+                program_ids=program_id,
+                membership_run_id=run_id,
+                limit=limit,
+                write=write,
+            )
+        render(_plain(summary), format=format)
+
+    asyncio.run(run())
+
+
+@app.command("membership-gigcamera")
+def membership_gigcamera(
+    ctx: typer.Context,
+    corpus_key: str = typer.Option("gigcamera", "--corpus-key", help="Target corpus key."),
+    run_id: str = typer.Option("manual", "--run-id", help="Membership materialization run id."),
+    limit: int | None = typer.Option(None, "--limit", min=1, help="Cap candidate clips."),
+    write: bool = typer.Option(False, "--write", help="Insert membership rows."),
+    format: Format = format_option(),
+) -> None:
+    """Dry-run or materialize non-duplicate GigCamera corpus membership."""
+    _require_internal_admin_for_write(ctx, write=write)
+    settings = _settings_for_command(ctx, write=write)
+
+    async def run() -> None:
+        from dal.embeddings import ego_frame_search as ego_search_dal
+
+        async with get_cli_context(settings, profile=(ctx.obj or {}).get("cli_profile")) as (
+            _db,
+            dal_ctx,
+        ):
+            summary = await ego_search_dal.materialize_gigcamera_membership(
+                dal_ctx,
+                corpus_key=corpus_key,
+                membership_run_id=run_id,
+                limit=limit,
+                write=write,
+            )
+        render(_plain(summary), format=format)
+
+    asyncio.run(run())
+
+
+@app.command("coverage")
+def coverage(
+    ctx: typer.Context,
+    corpus_key: str = typer.Option(..., "--corpus-key", help="Corpus key to inspect."),
+    space_id: int | None = typer.Option(None, "--space-id", help="Target embedding space id."),
+    space_key: str | None = typer.Option(
+        "qwen.frame.global.ego.default",
+        "--space-key",
+        help="Target embedding space key.",
+    ),
+    selection_kind: str = typer.Option("near_90s", "--selection-kind"),
+    refresh: bool = typer.Option(False, "--refresh", help="Upsert readiness counts."),
+    route_ready: bool = typer.Option(False, "--route-ready", help="Mark routing verified."),
+    smoke_passed: bool = typer.Option(False, "--smoke-passed", help="Mark smoke benchmark passed."),
+    write: bool = typer.Option(False, "--write", help="Apply readiness refresh."),
+    format: Format = format_option(),
+) -> None:
+    """Inspect or refresh corpus coverage/readiness for a target space."""
+    write_requested = write or refresh
+    _require_internal_admin_for_write(ctx, write=write_requested)
+    settings = _settings_for_command(ctx, write=write_requested)
+
+    async def run() -> None:
+        from dal.embeddings import ego_frame_search as ego_search_dal
+
+        async with get_cli_context(settings, profile=(ctx.obj or {}).get("cli_profile")) as (
+            _db,
+            dal_ctx,
+        ):
+            target_space_id = await _resolve_space_id(
+                dal_ctx,
+                space_id=space_id,
+                space_key=space_key,
+            )
+            if refresh:
+                summary = await ego_search_dal.refresh_corpus_readiness(
+                    dal_ctx,
+                    corpus_key=corpus_key,
+                    target_space_id=target_space_id,
+                    selection_kind=selection_kind,
+                    route_ready=route_ready,
+                    smoke_passed=smoke_passed,
+                )
+            else:
+                summary = await ego_search_dal.compute_corpus_coverage(
+                    dal_ctx,
+                    corpus_key=corpus_key,
+                    target_space_id=target_space_id,
+                    selection_kind=selection_kind,
+                )
+        render(_plain(summary), format=format)
+
+    asyncio.run(run())
+
+
+@app.command("missing-vectors")
+def missing_vectors(
+    ctx: typer.Context,
+    corpus_key: str = typer.Option(..., "--corpus-key", help="Corpus key to inspect."),
+    space_id: int | None = typer.Option(None, "--space-id", help="Target embedding space id."),
+    space_key: str | None = typer.Option("qwen.frame.global.ego.default", "--space-key"),
+    selection_kind: str = typer.Option("near_90s", "--selection-kind"),
+    format: Format = format_option(),
+) -> None:
+    """Count sampled corpus frames that still need embeddings."""
+    settings = _settings_for_command(ctx, write=False)
+
+    async def run() -> None:
+        from dal.embeddings import ego_frame_search as ego_search_dal
+
+        async with get_cli_context(settings, profile=(ctx.obj or {}).get("cli_profile")) as (
+            _db,
+            dal_ctx,
+        ):
+            target_space_id = await _resolve_space_id(
+                dal_ctx,
+                space_id=space_id,
+                space_key=space_key,
+            )
+            count = await ego_search_dal.count_missing_vectors(
+                dal_ctx,
+                corpus_key=corpus_key,
+                target_space_id=target_space_id,
+                selection_kind=selection_kind,
+            )
+        render(
+            {
+                "corpus_key": corpus_key,
+                "target_space_id": target_space_id,
+                "selection_kind": selection_kind,
+                "missing_vector_count": count,
+            },
+            format=format,
+        )
+
+    asyncio.run(run())
+
+
+@app.command("missing-demian-labels")
+def missing_demian_labels(
+    ctx: typer.Context,
+    corpus_key: str = typer.Option(..., "--corpus-key", help="Corpus key to inspect."),
+    selection_kind: str = typer.Option("near_90s", "--selection-kind"),
+    observation_kind: str = typer.Option("demian_frame_label_v1", "--observation-kind"),
+    format: Format = format_option(),
+) -> None:
+    """Count sampled corpus frames missing DeMiAn labels."""
+    settings = _settings_for_command(ctx, write=False)
+
+    async def run() -> None:
+        from dal.embeddings import ego_frame_search as ego_search_dal
+
+        async with get_cli_context(settings, profile=(ctx.obj or {}).get("cli_profile")) as (
+            _db,
+            dal_ctx,
+        ):
+            count = await ego_search_dal.count_missing_demian_labels(
+                dal_ctx,
+                corpus_key=corpus_key,
+                selection_kind=selection_kind,
+                observation_kind=observation_kind,
+            )
+        render(
+            {
+                "corpus_key": corpus_key,
+                "selection_kind": selection_kind,
+                "observation_kind": observation_kind,
+                "missing_demian_label_count": count,
+            },
+            format=format,
+        )
+
+    asyncio.run(run())
+
+
+@app.command("copy-plan")
+def copy_plan(
+    ctx: typer.Context,
+    source_space_id: int = typer.Option(..., "--source-space-id"),
+    target_space_id: int | None = typer.Option(None, "--target-space-id"),
+    target_space_key: str | None = typer.Option(
+        "qwen.frame.global.ego.default", "--target-space-key"
+    ),
+    selection_kind: str = typer.Option("near_90s", "--selection-kind"),
+    format: Format = format_option(),
+) -> None:
+    """Inspect how many legacy vectors can be copied safely."""
+    settings = _settings_for_command(ctx, write=False)
+
+    async def run() -> None:
+        from dal.embeddings import ego_frame_search as ego_search_dal
+
+        async with get_cli_context(settings, profile=(ctx.obj or {}).get("cli_profile")) as (
+            _db,
+            dal_ctx,
+        ):
+            resolved_target_space_id = await _resolve_space_id(
+                dal_ctx,
+                space_id=target_space_id,
+                space_key=target_space_key,
+            )
+            plan = await ego_search_dal.plan_vector_copy(
+                dal_ctx,
+                source_space_id=source_space_id,
+                target_space_id=resolved_target_space_id,
+                selection_kind=selection_kind,
+            )
+        render(_plain(plan), format=format)
+
+    asyncio.run(run())
+
+
+@app.command("copy-vectors")
+def copy_vectors(
+    ctx: typer.Context,
+    source_space_id: int = typer.Option(..., "--source-space-id"),
+    target_space_id: int | None = typer.Option(None, "--target-space-id"),
+    target_space_key: str | None = typer.Option(
+        "qwen.frame.global.ego.default", "--target-space-key"
+    ),
+    selection_kind: str = typer.Option("near_90s", "--selection-kind"),
+    run_id: str = typer.Option(..., "--run-id", help="Operator copy run id."),
+    limit: int | None = typer.Option(None, "--limit", min=1, help="Cap copied vectors."),
+    write: bool = typer.Option(False, "--write", help="Insert copied vector rows."),
+    format: Format = format_option(),
+) -> None:
+    """Copy compatible legacy vectors without overwriting target rows."""
+    _require_internal_admin_for_write(ctx, write=write)
+    settings = _settings_for_command(ctx, write=write)
+
+    async def run() -> None:
+        from dal.embeddings import ego_frame_search as ego_search_dal
+        from dal.embeddings import spaces as spaces_dal
+
+        async with get_cli_context(settings, profile=(ctx.obj or {}).get("cli_profile")) as (
+            _db,
+            dal_ctx,
+        ):
+            resolved_target_space_id = await _resolve_space_id(
+                dal_ctx,
+                space_id=target_space_id,
+                space_key=target_space_key,
+            )
+            source_space = await spaces_dal.get(dal_ctx, source_space_id)
+            target_space = await spaces_dal.get(dal_ctx, resolved_target_space_id)
+            compatibility = ego_search_dal.compare_spaces(
+                source=source_space,
+                target=target_space,
+            )
+            if not compatibility.compatible:
+                raise typer.BadParameter("; ".join(compatibility.reasons))
+            plan = await ego_search_dal.plan_vector_copy(
+                dal_ctx,
+                source_space_id=source_space_id,
+                target_space_id=resolved_target_space_id,
+                selection_kind=selection_kind,
+            )
+            inserted = 0
+            if write:
+                inserted = await ego_search_dal.copy_compatible_vectors(
+                    dal_ctx,
+                    source_space_id=source_space_id,
+                    target_space_id=resolved_target_space_id,
+                    selection_kind=selection_kind,
+                    copy_run_id=run_id,
+                    limit=limit,
+                )
+        render(
+            {
+                "write": write,
+                "inserted": inserted,
+                "compatibility": _plain(compatibility),
+                "plan": _plain(plan),
+            },
+            format=format,
+        )
+
+    asyncio.run(run())
+
+
+@app.command("build-scann")
+def build_scann(
+    ctx: typer.Context,
+    space_id: int | None = typer.Option(None, "--space-id", help="Target embedding space id."),
+    space_key: str | None = typer.Option("qwen.frame.global.ego.default", "--space-key"),
+    strategy: str = typer.Option("balanced", "--strategy", help="speed, balanced, or quality."),
+    quantizer: str = typer.Option("SQ8", "--quantizer", help="SQ8, FLAT, or AH."),
+    write: bool = typer.Option(False, "--write", help="Create btree/ANALYZE/ScaNN."),
+    format: Format = format_option(),
+) -> None:
+    """Analyze a partition and create its ScaNN index after bulk load."""
+    _require_internal_admin_for_write(ctx, write=write)
+    settings = _settings_for_command(ctx, write=write)
+
+    async def run() -> None:
+        from dal.embeddings import indexes as index_dal
+
+        async with get_cli_context(settings, profile=(ctx.obj or {}).get("cli_profile")) as (
+            _db,
+            dal_ctx,
+        ):
+            target_space_id = await _resolve_space_id(
+                dal_ctx,
+                space_id=space_id,
+                space_key=space_key,
+            )
+            info = await index_dal.create_scann_index(
+                dal_ctx,
+                target_space_id,
+                strategy=strategy,  # type: ignore[arg-type]
+                quantizer=quantizer,  # type: ignore[arg-type]
+                dry_run=not write,
+            )
+        render(info, format=format)
+
+    asyncio.run(run())
+
+
+@app.command("queue-missing-embeddings")
+def queue_missing_embeddings(
+    ctx: typer.Context,
+    corpus_key: list[str] = typer.Option(..., "--corpus-key", help="Corpus key. Repeatable."),
+    space_id: int | None = typer.Option(None, "--space-id", help="Target embedding space id."),
+    space_key: str | None = typer.Option("qwen.frame.global.ego.default", "--space-key"),
+    selection_kind: str = typer.Option("near_90s", "--selection-kind"),
+    limit: int | None = typer.Option(None, "--limit", min=1, help="Cap selected sampled frames."),
+    idempotency_key: str = typer.Option(..., "--idempotency-key", help="Manifest idempotency key."),
+    cost_cap_usd: float | None = typer.Option(None, "--cost-cap-usd", min=0.0),
+    write: bool = typer.Option(False, "--write", help="Create the processing manifest."),
+    format: Format = format_option(),
+) -> None:
+    """Queue a capped missing-only embed_frames manifest from corpus membership."""
+    _require_internal_admin_for_write(ctx, write=write)
+    settings = _settings_for_command(ctx, write=write)
+
+    async def run() -> None:
+        from dal.processing import media_jobs
+
+        async with get_cli_context(settings, profile=(ctx.obj or {}).get("cli_profile")) as (
+            _db,
+            dal_ctx,
+        ):
+            target_space_id = await _resolve_space_id(
+                dal_ctx,
+                space_id=space_id,
+                space_key=space_key,
+            )
+            selection_spec = {
+                "kind": "by_corpus",
+                "corpus_keys": corpus_key,
+                "selection_kind": selection_kind,
+                "limit": limit,
+                "only_missing_vectors": True,
+            }
+            sink_overrides = {"embedding": {"space_id": target_space_id}}
+            resource_overrides = {"cost_cap_usd": cost_cap_usd} if cost_cap_usd is not None else {}
+            if write:
+                manifest = await media_jobs.queue_processor_job(
+                    dal_ctx,
+                    processor_ref=media_jobs.EMBED_FRAMES_PROCESSOR_REF,
+                    selection_spec=selection_spec,
+                    sink_overrides=sink_overrides,
+                    resource_overrides=resource_overrides,
+                    submitted_by_principal=_SUBMITTED_BY,
+                    idempotency_key=idempotency_key,
+                )
+            else:
+                manifest = {
+                    "dry_run": True,
+                    "processor_ref": media_jobs.EMBED_FRAMES_PROCESSOR_REF,
+                    "selection_spec": selection_spec,
+                    "sink_overrides": sink_overrides,
+                    "resource_overrides": resource_overrides,
+                }
+        render(manifest, format=format)
+
+    asyncio.run(run())
+
+
+@app.command("queue-missing-sampled-frames")
+def queue_missing_sampled_frames(
+    ctx: typer.Context,
+    corpus_key: list[str] = typer.Option(..., "--corpus-key", help="Corpus key. Repeatable."),
+    selection_kind: str = typer.Option("near_90s", "--selection-kind"),
+    limit: int | None = typer.Option(None, "--limit", min=1, help="Cap selected clips."),
+    idempotency_key: str = typer.Option(..., "--idempotency-key", help="Manifest idempotency key."),
+    write: bool = typer.Option(False, "--write", help="Create the processing manifest."),
+    format: Format = format_option(),
+) -> None:
+    """Queue extraction for corpus clips missing the sampled-frame anchor."""
+    _require_internal_admin_for_write(ctx, write=write)
+    settings = _settings_for_command(ctx, write=write)
+
+    async def run() -> None:
+        from dal.processing import media_jobs
+
+        async with get_cli_context(settings, profile=(ctx.obj or {}).get("cli_profile")) as (
+            _db,
+            dal_ctx,
+        ):
+            selection_spec = {
+                "kind": "by_corpus",
+                "corpus_keys": corpus_key,
+                "selection_kind": selection_kind,
+                "limit": limit,
+                "only_missing_sampled_frames": True,
+                "require_zero_frames": False,
+            }
+            if write:
+                manifest = await media_jobs.queue_processor_job(
+                    dal_ctx,
+                    processor_ref=media_jobs.EXTRACT_FRAMES_PROCESSOR_REF,
+                    selection_spec=selection_spec,
+                    sink_overrides=None,
+                    resource_overrides=None,
+                    submitted_by_principal=_SUBMITTED_BY,
+                    idempotency_key=idempotency_key,
+                )
+            else:
+                manifest = {
+                    "dry_run": True,
+                    "processor_ref": media_jobs.EXTRACT_FRAMES_PROCESSOR_REF,
+                    "selection_spec": selection_spec,
+                }
+        render(manifest, format=format)
+
+    asyncio.run(run())

buildai_cli-0.3.89/cli/commands/spec.py

@@ -0,0 +1,173 @@
+"""BuildSpec wrapper commands for the Build AI CLI."""
+
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+from pathlib import Path
+
+import typer
+
+from cli.console import error, info
+
+
+def _repo_root() -> Path | None:
+    """Return the current Build AI repo root when running from a checkout."""
+
+    current = Path(__file__).resolve()
+    for parent in current.parents:
+        if (parent / ".git").exists() and (parent / "buildspec").exists():
+            return parent
+    cwd = Path.cwd().resolve()
+    for parent in (cwd, *cwd.parents):
+        if (parent / ".git").exists() and (parent / "buildspec").exists():
+            return parent
+    return None
+
+
+def _candidate_commands(repo_root: Path | None) -> list[list[str]]:
+    """Return BuildSpec engine command candidates in preference order.
+
+    Order: an explicit ``BUILDSPEC_BIN`` override, then the engine vendored
+    in-repo at ``tools/buildspec/`` (the default for everyone after a plain
+    ``git pull``), then a sibling ``../buildspec`` dev clone, then a ``buildspec``
+    binary on PATH.
+    """
+
+    candidates: list[list[str]] = []
+    node = shutil.which("node")
+
+    env_bin = os.environ.get("BUILDSPEC_BIN")
+    if env_bin:
+        candidates.append([env_bin])
+
+    if repo_root is not None and node:
+        vendored = repo_root / "tools" / "buildspec" / "bin" / "buildspec.js"
+        if vendored.exists():
+            candidates.append([node, str(vendored)])
+
+        sibling = repo_root.parent / "buildspec" / "bin" / "buildspec.js"
+        if sibling.exists():
+            candidates.append([node, str(sibling)])
+
+    path_bin = shutil.which("buildspec")
+    if path_bin:
+        candidates.append([path_bin])
+
+    # De-duplicate while preserving order.
+    seen: set[tuple[str, ...]] = set()
+    unique: list[list[str]] = []
+    for cmd in candidates:
+        key = tuple(cmd)
+        if key not in seen:
+            seen.add(key)
+            unique.append(cmd)
+    return unique
+
+
+def _resolve_buildspec(repo_root: Path | None) -> list[str]:
+    for cmd in _candidate_commands(repo_root):
+        exe = cmd[0]
+        if Path(exe).exists() or shutil.which(exe):
+            return cmd
+    raise RuntimeError(
+        "BuildSpec engine not found. Set BUILDSPEC_BIN, install `buildspec`, "
+        "or clone build-ai-ego/buildspec next to the build-ai repo."
+    )
+
+
+CONTEXT_SETTINGS = {"allow_extra_args": True, "ignore_unknown_options": True}
+
+
+def run_buildspec(args: list[str]) -> int:
+    """Run BuildSpec in the repo root with the provided arguments."""
+
+    repo_root = _repo_root()
+    if repo_root is None:
+        raise RuntimeError("Run `buildai spec` from the Build AI repo checkout.")
+
+    command = _resolve_buildspec(repo_root)
+    env = os.environ.copy()
+    env.setdefault("BUILDSPEC_PROJECT_ROOT", str(repo_root))
+
+    result = subprocess.run([*command, *args], cwd=repo_root, env=env)
+    return result.returncode
+
+
+def doctor() -> int:
+    """Diagnose the BuildSpec engine integration: node, engine resolution,
+    project schema, and end-to-end change listing. Prints a report and returns
+    a non-zero exit code when anything is unhealthy."""
+
+    healthy = True
+    repo_root = _repo_root()
+    if repo_root is None:
+        error("Run `buildai spec doctor` from the Build AI repo checkout.")
+        return 1
+
+    node = shutil.which("node")
+    info(f"node: {node or 'NOT FOUND — install Node >= 20.19'}")
+    healthy = healthy and node is not None
+
+    try:
+        command = _resolve_buildspec(repo_root)
+        info(f"engine: {' '.join(command)}")
+    except RuntimeError as exc:
+        error(f"engine: NOT RESOLVED — {exc}")
+        return 1
+
+    vendored_dir = repo_root / "tools" / "buildspec"
+    if str(vendored_dir) in " ".join(command):
+        source = vendored_dir / "SOURCE"
+        if source.exists():
+            info("vendored: " + source.read_text(encoding="utf-8").strip().replace("\n", "; "))
+        if not (vendored_dir / "node_modules").exists():
+            error("vendored engine deps missing — run `make buildspec-setup`")
+            healthy = False
+
+    env = os.environ.copy()
+    env.setdefault("BUILDSPEC_PROJECT_ROOT", str(repo_root))
+
+    schema = subprocess.run(
+        [*command, "schema", "which", "build-ai-change"],
+        cwd=repo_root,
+        env=env,
+        capture_output=True,
+        text=True,
+    )
+    project = "Source: project" in (schema.stdout + schema.stderr)
+    info(f"schema build-ai-change: {'project ✓' if project else 'NOT project ✗'}")
+    healthy = healthy and project
+
+    listing = subprocess.run(
+        [*command, "list"], cwd=repo_root, env=env, capture_output=True, text=True
+    )
+    info(f"engine list: {'ok ✓' if listing.returncode == 0 else 'FAILED ✗'}")
+    healthy = healthy and listing.returncode == 0
+
+    info(f"buildai spec doctor: {'OK' if healthy else 'PROBLEMS'}")
+    return 0 if healthy else 1
+
+
+def spec_command(
+    ctx: typer.Context,
+    args: list[str] | None = typer.Argument(
+        None,
+        help="Arguments passed through to BuildSpec, e.g. `list --specs` or `validate <change> --strict`. Use `doctor` to diagnose the engine integration.",
+    ),
+) -> None:
+    """Run BuildSpec against this repo's `buildspec/` directory."""
+
+    forwarded = list(args or []) + list(ctx.args)
+    if forwarded and forwarded[0] == "doctor":
+        raise typer.Exit(code=doctor())
+    if not forwarded:
+        forwarded = ["--help"]
+    try:
+        code = run_buildspec(forwarded)
+    except RuntimeError as exc:
+        error(str(exc))
+        info("Try: BUILDSPEC_BIN=/path/to/buildspec buildai spec list")
+        raise typer.Exit(code=1) from exc
+    raise typer.Exit(code=code)

{buildai_cli-0.3.87 → buildai_cli-0.3.89}/cli/main.py

@@ -20,6 +20,8 @@ from cli.commands.dev import app as dev_app
 from cli.commands.doctor import app as doctor_app
 from cli.commands.egoexo import app as egoexo_app
 from cli.commands.processing import app as processing_app
+from cli.commands.spec import CONTEXT_SETTINGS as SPEC_CONTEXT_SETTINGS
+from cli.commands.spec import spec_command
 from cli.console import error, info, set_verbose, success, warning
 
 
@@ -274,6 +276,7 @@ app.add_typer(dev_app, name="dev")
 app.add_typer(doctor_app, name="doctor")
 app.add_typer(egoexo_app, name="egoexo")
 app.add_typer(processing_app, name="processing")
+app.command("spec", context_settings=SPEC_CONTEXT_SETTINGS)(spec_command)
 
 
 def db_callback(
@@ -329,11 +332,13 @@ def _has_ingest_workspace() -> bool:
 
 if has_core():
     from cli.commands.db import app as db_app
+    from cli.commands.ego_frame_search import app as ego_frame_search_app
     from cli.commands.gigcamera import app as gigcamera_app
     from cli.commands.grid import app as grid_app
 
     db_app.callback()(db_callback)
     app.add_typer(db_app, name="db")
+    app.add_typer(ego_frame_search_app, name="ego-frame-search")
     app.add_typer(gigcamera_app, name="gigcamera")
     app.add_typer(grid_app, name="grid")
 

{buildai_cli-0.3.87 → buildai_cli-0.3.89}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "buildai-cli"
-version = "0.3.87"
+version = "0.3.89"
 description = "Build AI CLI (Typer)"
 requires-python = ">=3.11"
 dependencies = [

buildai_cli-0.3.87/AGENTS.md

@@ -1 +0,0 @@
-CLAUDE.md

buildai_cli-0.3.87/CLAUDE.md

@@ -1,47 +0,0 @@
-# BuildAI CLI
-
-Typer-based CLI with two modes: standalone (PyPI, API-backed) and workspace (repo-local, DB-direct).
-
-## Two Planes
-
-| Mode | Install | Auth | DB Access |
-|------|---------|------|-----------|
-| Standalone (`buildai`) | `uv tool install buildai-cli` | API key / JWT | Through API |
-| Workspace (`uv run buildai`) | Repo-local editable install | IAM / password | Direct via `db`, through the profile-keyed local broker |
-
-## Key Commands
-
-```bash
-buildai auth whoami                                  # API auth inspection
-uv run buildai ingest deploy plan --scope active     # Dry-run ingest fleet plan
-uv run buildai ingest deploy run --scope station:2   # Staged ingest rollout
-uv run buildai ingest fleet readiness --scope active # Host readiness gate
-buildai db query "SELECT count(*) FROM core.clips"   # DB-direct
-buildai db --env staging tunnel                      # IAP/SOCKS route for private staging DB
-buildai db --env staging --all-proxy socks5://127.0.0.1:1080 query "SELECT 1"  # staging query
-buildai db broker status                             # Active local DB broker state
-buildai db schema tables                             # Schema introspection
-buildai db schema describe core.clips                # Table details
-buildai db --write migrate all                       # Run migrations
-buildai db status                                    # Migration status
-```
-
-## Guards
-
-- `db` subcommands require workspace install + gcloud IAM.
-- `db` inspection/migration commands use a profile-keyed `alloydb-auth-proxy`
-  broker owned by the local machine, with state in `~/.buildai/db-brokers` so
-  all worktrees reuse the same listener; use `buildai db broker status|ensure|stop`
-  for that local transport.
-- Writes require `--write` flag.
-- Production migrations prompt for confirmation.
-- Worktree app/runtime targeting comes from explicit env vars and the repo Makefile, not a saved CLI context layer.
-- `buildai db --env` selects the explicit DB lane: `production`, `staging`, `dev`.
-- Staging is private-IP only. Start an IAP/VPN/SOCKS route first, then pass it
-  with `--all-proxy` so the local AlloyDB broker can reach the private address.
-  The standard route is `buildai db --env staging tunnel`.
-
-## Reference
-
-CLI mode guide: docs site Engineering section (run `make docs`)
-Database roles: docs site Operations section (run `make docs`)