QVAC-21691 feat[api]: full-fidelity Python SDK client

[lauripiisang]

🎯 What problem does this PR solve?

Ships the full-fidelity Python client for QVAC — the Python equivalent of
@qvac/sdk, so Python apps get the same capabilities and the same behaviour as
the TypeScript SDK, generated from the one contract.

Single PR by design: the SDK contract, the generated Python client, and the
worker behaviour it depends on are CI-coupled (any packages/sdk/contract
change re-runs the Python generator and must ship the regenerated client in the
same PR), so they can't be split cleanly. Supersedes #3208 — the
bare-rpc-python transport PoC is included here as the production transport.

🛠️ How does it solve it?

• Scoped, flat Python API: distribution tetherto-qvac-sdk, import
  tetherto.qvac_sdk (PEP 420 namespace — matches @qvac/sdk scoping, reserves
  the tetherto.* root, and leaves the bare qvac name free). The name is a
  proposal — open to change before publish; it's applied consistently across
  the code so a rename is a mechanical find-replace. Usage is flat:
  from tetherto.qvac_sdk import Client, load_model, completion, embed, translate, …
  (+ tetherto.qvac_sdk.models).
• Generated from the contract: pydantic models + typed async method stubs,
  model-type maps, error-code registries, and the pinned SDK version — all from
  packages/sdk/contract/**, guarded by generate.py --check.
• Behaviour lives in the worker (shared, not re-implemented): translate
  source-language detection and the completion tool loop (completionOrchestrate,
  a new duplex contract method) run worker-side; the Python client is thin glue.
  This removed a real drift (Python lingua vs JS @qvac/langdetect-text).
• Production transport: bare-rpc-python, all three call shapes, with
  worker-disconnect handling (pending calls fail fast instead of hanging).
• Distribution: a self-contained bundled wheel (zero-config Client()), or a
  thin wheel that resolves a version-pinned worker via
  python -m tetherto.qvac_sdk install-worker (recommended) or a version-matched
  npm install -g @qvac/sdk@<version>. The package version tracks @qvac/sdk
  (0.15.0).
• Docs & examples: packages/sdk-python/examples/ (one per major capability,
  mirroring packages/sdk/examples), a full README with a two-step first-run
  (install the package, then the worker), and a Python SDK page on the docs site.

🔌 API ([api])

from tetherto.qvac_sdk import Client, load_model, completion
from tetherto.qvac_sdk.models import LLAMA_3_2_1B_INST_Q4_0

async with Client() as client:
    t = client.transport
    model_id = await load_model(t, model_src=LLAMA_3_2_1B_INST_Q4_0)
    run = completion(t, model_id=model_id, history=[{"role": "user", "content": "hi"}])
    async for event in run.events:
        ...
    final = await run.final

The ergonomic wrappers and result types are statically typed on the flat
surface. Raw generated method stubs and models are re-exported flat for runtime
use and are also available fully-typed from tetherto.qvac_sdk.methods /
.schemas. New worker method completionOrchestrate is additive (nothing
removed) and is worker plumbing, not public client API (reachable at
tetherto.qvac_sdk._completion), matching the JS SDK.

✅ Testing

• Real-worker e2e runs in CI: on-pr-sdk-python-e2e.yml (label-gated,
  self-hosted GPU) builds the worker, installs the bare-rpc extra, and runs the
  full suite — completion (events / tools / the completionOrchestrate tool
  loop), embeddings, transcription, TTS, OCR, translate (worker-side autodetect),
  VLA, cancel, and worker-disconnect. The fast PR check
  (pr-checks-sdk-python) runs generate.py --check + black + ruff + mypy + the
  mocked unit tests.
• Cross-client conformance: a shared corpus
  (packages/sdk/e2e/conformance/cases.json) of 8 cases (completion, translate,
  embed, model load/unload, cancel, tts) — 8/8 on the Python runner and 8/8 on
  the JS runner against the built worker.
• Examples verified end-to-end against a real worker + real models (14 of 15;
  plugins.py is a fixture-only template for the low-level plugin API).
• VLA e2e (--filter vla) — 8/8 against real SmolVLA + pi05.
• SDK side: bun run build, contract:check, bun run test:unit, tsc, eslint.

📝 Follow-ups

• PyPI publish is not wired yet: the bare-rpc transport dependencies are
  git-only for now, and PyPI rejects direct git references in a package's required
  dependencies — so publishing waits on those landing on PyPI, after which
  bare-rpc folds into the base install. The distribution name /import root
  (tetherto-qvac-sdk / tetherto.qvac_sdk) is a proposal pending
  confirmation before publish.

[github-actions]

Review Status

Current Status: ✅ APPROVED
Approvals so far: Team Lead: 1, Member: 1

[github-actions]

License compliance — findings detected (warn-only)

Critical: 0 · High: 4 · Medium: 0

Dependency	License	Scope	Severity	Outcome
actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd	(none detected)	runtime	High	blocks
actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f	(none detected)	runtime	High	blocks
actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405	(none detected)	runtime	High	blocks
oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6	(none detected)	runtime	High	blocks

How to resolve a blocking finding:

• Remove or replace the disallowed dependency, or
• If the license is genuinely acceptable, run the compliance SKILL and record the decision in .github/license-allowlist.yml (CODEOWNERS-reviewed), or
• For a one-off, a maintainer can apply the license-override label (High findings only; Critical cannot be overridden).

Warn-only (shadow) mode — this check does not block merges yet.

Updated automatically by the canonical license compliance workflow.

NOTICE presence (advisory)

Missing NOTICE (advisory, does not block):

• ./packages/embed-llamacpp/benchmarks/server
• ./packages/embed-llamacpp/benchmarks/performance
• ./packages/ggml-coload-smoke
• ./packages/llm-llamacpp/benchmarks/server
• ./packages/llm-llamacpp/benchmarks/performance
• ./packages/fabric/test/integration
• ./packages/transcription-whispercpp/benchmarks/server
• ./packages/transcription-parakeet/benchmarks/server
• ./packages/sdk/e2e
• ./packages/vla-ggml/sim/server
• ./.github/actions/release-merge-guard
• ./docs/website

[arun-mani-j]

Looks good overall. Shared a few nits. I thought we would drop the Client style for the direction function usage like in JS. But fine with this too.