Qv SDK Update Models

SDK Update Models

Regenerate @qvac/sdk static model constants from the live P2P registry, then open a [mod] PR. Registry sync does not auto-update SDK constants — this skill is the deliberate regen + PR path.

When to use this skill

Use when:

• New/updated/removed models landed in the production registry and SDK constants are stale.
• Someone asks to "update models", "sync models.ts", or "run update-models".
• User invokes /qv-sdk-update-models.

Do NOT use when:

• Changing naming rules / companion detection / codegen logic (those are code changes; regen may be a follow-up, not the whole PR).
• Only needing a dry-run drift check — run bun run check-models directly.
• Releasing / changelog work — use qv-sdk-changelog after the [mod] PR merges.

Flags

Combine as needed: /qv-sdk-update-models --cascade, /qv-sdk-update-models --check-only.

Prerequisites

• Working directory is the qvac monorepo root (or resolve paths from it).
• Network access to the live registry (Hyperswarm / Hyperdrive).
• packages/sdk dependencies installed (bun install in that package if needed).
• Optional: QVAC_REGISTRY_CORE_KEY to target a non-default registry core.
• For --with-python / --cascade: packages/sdk-python/.venv with gen extras (python3 -m venv .venv && .venv/bin/pip install -e ".[gen,dev]").
• gh CLI for PR creation (same expectations as qv-sdk-pr-create).

Secrets: this skill only needs registry network access. It does not read GH_TOKEN / HF_TOKEN / NPM_TOKEN unless a chained skill does.

Safety rules

• Plan-then-apply. Print the planned commands and expected file set; wait for explicit user confirmation before regen, commit, push, or gh pr create.
• No silent git mutations. Do not git switch / checkout / stash / pull / merge / rebase without explicit user instruction.
• Fail-stop on unexpected dirty files, missing tools, or registry errors.
• Do not edit naming.ts, companion logic, schemas, or hand-written API code. If those need changes, stop and tell the user this skill is the wrong tool.
• Prefer draft=false / Ready for review org-branch PRs when the user wants baseline CI (same preference as qv-sdk-pr-create).

Expected file sets

SDK (always)

After a successful bun run update-models in packages/sdk/:

• packages/sdk/models/registry/models.ts
• packages/sdk/models/history/<short-sha>.txt (only when add/update/remove)
• packages/sdk/contract/models.json (via chained contract:export)
• Possibly other packages/sdk/contract/* if export rewrites them — include if git status shows them; do not invent diffs.

Provider (--with-provider / --cascade)

• packages/ai-sdk-provider/src/models/constants.ts
• packages/ai-sdk-provider/models/history/<short-sha>.txt (when delta exists)

Python (--with-python / --cascade)

• packages/sdk-python/src/tetherto/qvac_sdk/_generated/models_registry.py
• Other _generated/** files if generate.py rewrites them — include if dirty.

If git status shows files outside the active file set, STOP and ask.

Workflow

Step 0 — Parse flags and resolve ticket

1. Parse flags from the user message.
2. Ticket:
   • Prefer QVAC-\d+ / SDK-\d+ from branch name or user message.
   • If missing and --notask was passed → use [notask].
   • If missing and no --notask → ASK for a ticket (or confirm --notask).

Step 1 — Preflight (read-only)

From monorepo root:

1. git status -sb and git status --porcelain.
2. Allowed dirty paths before regen: none, or only files already in the expected file set from a prior interrupted run of this skill.
3. Confirm remotes (git remote -v) for later PR push (org remote preferred).
4. Print plan:

Plan:
  1. bun run check-models   (packages/sdk)
  2. bun run update-models  (packages/sdk)   [needs confirm]
  3. [optional] provider / python cascade
  4. commit feat[mod] …
  5. open PR via qv-sdk-pr-create
Ticket: …
Cascade: none | provider | python | both

5. If --check-only: run Step 2 only, report, stop.
6. Otherwise ask: "Proceed with regen?" — wait for yes.

Step 2 — Drift check

cd packages/sdk
bun run check-models

Capture Added / Updated / Removed names from the check output when present — useful if history later looks bogus.

Step 3 — Regenerate SDK

After user confirmation:

cd packages/sdk
bun run update-models

Then:

cd packages/sdk
bun run contract:check

contract:check must pass (update-models already ran export; this verifies).

Inspect git status. Confirm only the SDK expected file set is dirty.

Step 4 — Optional cascade

Provider

If --cascade or --with-provider:

cd packages/ai-sdk-provider
bun run update-models

Note: provider filters engines without OpenAI-shaped endpoints (e.g. VAD). A smaller delta than SDK is expected.

Python

If --cascade or --with-python:

cd packages/sdk-python
.venv/bin/python3 scripts/generate.py
.venv/bin/python3 scripts/generate.py --check

If .venv is missing, fail-stop with the venv setup command from Prerequisites. Do not invent alternate python binaries.

Step 5 — Build the Models section

Prefer the newest history file under packages/sdk/models/history/ whose timestamp= is from this run (or the file update-models just printed).

Parse sections:

• [added] → ### Added models
• [updated] → ### Updated models
• [removed] → ### Removed models

Bogus-history guard: if previous_count=0 and the [added] list is huge relative to a normal incremental sync (e.g. hundreds of names when check-models only reported a handful), do not paste the full history dump into the PR. Fall back to:

1. Names printed by check-models / update-models console output, or
2. Diff-derived constant names from git diff on export lines in models.ts

Delete empty subsections. Validator requires at least one of Added / Updated / Removed with a fenced code block.