@kindgi/cli 0.2.0 → 0.3.0-rc.0

package/dist/sdk-skills/kindgi-authoring-providers/path-c-onnx.md

@@ -0,0 +1,97 @@
+# Path C — Local via in-process ONNX (runtime from source only)
+
+> ⚠️ **Not in the runtime image, so not under `kindgi dev`.** The adapter
+> runs ONNX through `onnxruntime-node`, which ships glibc binaries only,
+> and the Kindgi runtime image is Alpine (musl): the adapter can't load
+> there (`Error loading shared library ld-linux-…`). `kindgi dev` runs
+> that image, so this path fails under it. It works only when the
+> runtime itself runs from source on macOS or a glibc Linux. **For a
+> local model under `kindgi dev`, use Ollama** (`path-b-openai-compat.md`).
+
+> ⚠️ **Dev-only.** The in-process ONNX adapter writes weights to
+> `~/.cache/huggingface/hub/` — a per-machine cache with no production
+> recipe (no volume-mount recipe, no image-bake pattern, no offline
+> mode, no SHA pinning). Good for smoke tests and CI runners that run
+> the runtime from source and keep the same disk between runs. **Do not
+> ship packs that rely on this adapter to production.** Use hosted
+> providers (Path A) or Ollama (Path B) instead.
+
+No API key. No network. Bundled with the framework — the adapter ships
+`smollm2-360m` by default (~273 MB weights, cached at
+`~/.cache/huggingface/hub/models--HuggingFaceTB--SmolLM2-360M-Instruct/`
+after `kindgi adapters prepare`).
+
+**Not for reasoning-heavy agents.** SmolLM 360M is fine for smoke
+tests, canary agents, dev/CI. Real work needs a hosted model or a
+larger local model via Ollama (Path B).
+
+**`provider.json`** (single-model):
+```json
+{
+  "metadata": {
+    "id": "local-onnx",
+    "region": "in-process",
+    "models": [
+      {
+        "name": "smollm2-360m",
+        "contextWindow": 2048,
+        "features": ["tool-use"],
+        "cost": {
+          "promptUsdPer1kTokens": 0,
+          "completionUsdPer1kTokens": 0
+        }
+      }
+    ],
+    "description": "Local ONNX smollm2-360m — dev + smoke tests."
+  },
+  "adapter_id": "@kindgi/adapter-model-in-process"
+}
+```
+
+Multi-model variant — the in-process adapter loads each pipeline lazily,
+so listing several models keeps memory low until they're actually
+invoked:
+
+```json
+{
+  "metadata": {
+    "id": "local-onnx",
+    "region": "in-process",
+    "models": [
+      { "name": "smollm2-135m", "contextWindow": 2048, "features": [],
+        "cost": { "promptUsdPer1kTokens": 0, "completionUsdPer1kTokens": 0 } },
+      { "name": "smollm2-360m", "contextWindow": 2048, "features": ["tool-use"],
+        "cost": { "promptUsdPer1kTokens": 0, "completionUsdPer1kTokens": 0 } },
+      { "name": "qwen3-0.6b", "contextWindow": 32768, "features": ["tool-use", "long-context"],
+        "cost": { "promptUsdPer1kTokens": 0, "completionUsdPer1kTokens": 0 } }
+    ]
+  },
+  "adapter_id": "@kindgi/adapter-model-in-process"
+}
+```
+
+No `secret_ref` needed. Register + **prepare** + run:
+```sh
+kindgi providers register --spec=@provider.json
+kindgi adapters prepare @kindgi/adapter-model-in-process --model=smollm2-360m
+kindgi runs start --agent=<agent-id> --input='{...}'
+```
+
+**Always `prepare` before `runs start`.** It downloads the ONNX weights
+(~273 MB for smollm2-360m, ~30s on a typical connection) and streams
+per-file progress. Skipping it works — the first model call downloads
+lazily — but that stalls a request path on a multi-hundred-MB
+fetch with no observability, which is bad in dev and unacceptable in
+production. Skip only for scripted teardown where the model is already
+cached (`~/.cache/huggingface/hub/models--HuggingFaceTB--SmolLM2-360M-Instruct/`).
+
+`prepare` is idempotent: subsequent invocations are cache hits and
+return almost instantly, so put it in the script that boots your
+from-source runtime.
+
+Multi-model providers: prepare each model separately.
+```sh
+kindgi adapters prepare @kindgi/adapter-model-in-process --model=smollm2-135m
+kindgi adapters prepare @kindgi/adapter-model-in-process --model=smollm2-360m
+kindgi adapters prepare @kindgi/adapter-model-in-process --model=qwen3-0.6b
+```

package/dist/sdk-skills/kindgi-authoring-providers/path-d-vertex.md

@@ -0,0 +1,95 @@
+# Path D — Gemini on Vertex AI
+
+Gemini through Google Cloud's Vertex AI. No API key: the adapter uses
+**Google Application Default Credentials** — your `gcloud` login on a
+laptop, the attached service account on Cloud Run (and other Google Cloud
+runtimes). The same registration works in both.
+
+**Step 1 — credentials:**
+```sh
+gcloud auth application-default login     # once per laptop
+```
+The account (locally) or the service account (deployed) needs the
+**Vertex AI User** role (`roles/aiplatform.user`) in the project. Running
+outside Google Cloud: put a service-account key (its JSON) in a secret
+(`kindgi secrets set GEMINI_SA_KEY --env=local --scope=tenant`) and add
+`"secret_ref": { "envName": "local", "name": "GEMINI_SA_KEY" }`. A runtime
+with `KINDGI_TENANT_HOST_ACCESS=isolated` requires that key: it doesn't lend
+its own credentials to tenant configuration.
+
+**Step 2 — `provider.json`:**
+```json
+{
+  "metadata": {
+    "id": "gemini",
+    "region": "global",
+    "models": [
+      {
+        "name": "gemini-3.8-flash",
+        "contextWindow": 1048576,
+        "features": ["tool-use", "structured-output", "long-context"],
+        "maxOutputTokens": 65536,
+        "thinking": { "mode": "adaptive", "lowest": "low" },
+        "cost": { "promptUsdPer1kTokens": 0.00075, "completionUsdPer1kTokens": 0.00375 }
+      },
+      {
+        "name": "gemini-3.5-flash-lite",
+        "contextWindow": 1048576,
+        "features": ["tool-use", "structured-output", "long-context"],
+        "maxOutputTokens": 65536,
+        "thinking": { "mode": "adaptive", "lowest": "minimal" },
+        "cost": { "promptUsdPer1kTokens": 0.0003, "completionUsdPer1kTokens": 0.0025 }
+      }
+    ]
+  },
+  "adapter_id": "@kindgi/adapter-model-gemini",
+  "adapter_config": { "project": "<your-gcp-project-id>" }
+}
+```
+- `adapter_config.project` is required: the Google Cloud project Vertex
+  bills and authorises against.
+- `metadata.region` is the Vertex location: `global`, or a region such as
+  `us-central1` or `northamerica-northeast1` when data must stay in one
+  place. `unspecified` means `global`. Different locations are different
+  provider rows. Check that the location serves the model: Gemini 3.8 Flash
+  isn't served from `us-central1`.
+- Don't register `gemini-2.5-pro` or `gemini-2.5-flash`: Vertex AI retires
+  both on 2026-10-20.
+- Rates are per 1K tokens, from Google's published pricing; check them
+  before relying on budgets. Thinking tokens bill as output, and Gemini 3.8
+  Flash thinks by default. `gemini-3.8-flash`'s rates above are Google's
+  launch price, through 2026-12-31 ($0.0015 / $0.0075 from 2027-01-01).
+  `longContext` (`{ thresholdTokens, promptUsdPer1kTokens,
+  completionUsdPer1kTokens }` in a model's `cost`) switches the whole call
+  to the higher rates past the threshold; `cachedPromptMultiplier` (default 0.25) prices cached
+  prompt tokens.
+- `thinking` is how the model thinks, as the preset has it. `lowest` is
+  the least level it takes, which a judge's call asks for. `levels`
+  (optional) are the levels it takes besides `lowest`, least first; without
+  them it takes `low`, `medium` and `high` (plus `minimal` when `lowest` is
+  `minimal`, and none below `lowest` when that's `medium` or `high`).
+- To make a model think less, the agent sets `thinking` in its model
+  settings (`lowest`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`).
+  For calls that ask none, set the model's `thinking.default`:
+  `"thinking": { "mode": "adaptive", "lowest": "low", "default": "low" }`.
+  A `default` the model doesn't take is refused, naming the ones it takes.
+  A model without one thinks as Google sets. It needs runtime 0.3.0 or
+  later; an older one refuses a `thinking` with `default`.
+- `adapter_config.thinkingLevels` is no longer read. A new registration
+  with it is refused (`adapter_config.thinkingLevels isn't read here: its
+  setting is metadata.models[].thinking.default.`); a stored one builds,
+  thinking at Google's default, and `kindgi doctor` warns. Move each
+  `model=level` pair into that model's `thinking.default`, unregister the
+  provider and register it again.
+
+**Step 3 — register and check:**
+```sh
+kindgi providers register --spec=@provider.json
+kindgi providers list
+```
+Or skip step 2: `kindgi providers register --preset=gemini --project=<your-gcp-project-id>`
+registers both models above.
+Then pin it from an agent with `preferredProvider: 'gemini'` (and a model
+with `preferredModel`; in Python, `preferred_provider="gemini"` and
+`preferred_model=…`; in Java, `.set("preferredProvider", "gemini")`), or let
+the router pick by capability.

package/dist/sdk-skills/kindgi-authoring-providers/router.md

@@ -0,0 +1,113 @@
+# How the router picks between multiple providers + models
+
+## Contents
+
+- The order the router sorts (provider, model) tuples in
+- Practical rule: preferences rank, they never exclude
+- A/B testing a specific agent across models within one Anthropic registration
+- A/B testing across vendors
+
+When an agent turn fires, the router expands each registered provider
+into one entry per model (`metadata.models[]`), filters the resulting
+(provider, model) tuples against the agent's `capabilities.needs` (and
+tenant policy), then sorts survivors in this order:
+
+1. **Preferred provider / model.** Tuples matching the agent's
+   `preferredProvider` and `preferredModel` are promoted to the front.
+     - Both set → promote the exact tuple.
+     - Only `preferredModel` set → promote any provider exposing that model.
+     - Only `preferredProvider` set → promote every model of that provider.
+   `defineAgent` takes both (`preferredProvider`, `preferredModel`), and
+   so does a Python `Agent` (`preferred_provider=`, `preferred_model=`) and
+   a Java `Agent.define(…)` (`set("preferredProvider", …)`).
+2. **`capability.prefer[]` weights.** If the agent's capability
+   declares `prefer: [{feature: 'thinking', weight: 3}, ...]`, tuples
+   with matching model features (or provider attributes) get higher
+   scores. Sorted by summed score, descending.
+3. **Deterministic tiebreak.** When scores tie, tuples sort by provider
+   id, then the provider's `defaultModel` before its other models, then
+   model name — replay-safe and stable. A provider without a
+   `defaultModel` falls back to its first model by name.
+
+**Practical rule:** preferences are soft — they rank, they don't
+exclude. To guarantee which model runs, make it a hard requirement in
+the capability: `{ models: { allow: ['claude-sonnet-5-5'] } }` (and
+`{ providers: { allow: ['anthropic'] } }` to pin the connection). If no
+registered tuple satisfies it, the turn fails with
+`capability-routing-failed` instead of silently using another model.
+
+**A/B testing a specific agent across models within one Anthropic
+registration:**
+
+```ts
+// agents/weather-agent-sonnet/index.ts
+defineAgent({
+  id: 'my-pack.weather-agent-sonnet',
+  // …same name, instructions, tools, retrieval and guardrails as the opus variant
+  capabilities: [
+    { needs: [{ feature: 'tool-use' }, { models: { allow: ['claude-sonnet-5-5'] } }] },
+  ],
+  preferredProvider: 'anthropic',
+});
+
+// agents/weather-agent-opus/index.ts
+defineAgent({
+  id: 'my-pack.weather-agent-opus',
+  // …
+  capabilities: [
+    { needs: [{ feature: 'tool-use' }, { models: { allow: ['claude-opus-5-5'] } }] },
+  ],
+  preferredProvider: 'anthropic',
+});
+```
+
+The same pair in a Python pack (`kindgi.Agent`; module-level, one file each):
+
+```python
+# agents/weather_agent_sonnet.py
+weather_agent_sonnet = Agent(
+    id="my-pack.weather-agent-sonnet",
+    # …same version, name, instructions, tools and guardrails as the opus variant
+    capabilities=[
+        {"needs": [{"feature": "tool-use"}, {"models": {"allow": ["claude-sonnet-5-5"]}}]},
+    ],
+    preferred_provider="anthropic",
+)
+
+# agents/weather_agent_opus.py
+weather_agent_opus = Agent(
+    id="my-pack.weather-agent-opus",
+    # …
+    capabilities=[
+        {"needs": [{"feature": "tool-use"}, {"models": {"allow": ["claude-opus-5-5"]}}]},
+    ],
+    preferred_provider="anthropic",
+)
+```
+
+Both agents share the tool + instructions; only the pinned model
+differs. One Anthropic provider registration + one API key covers
+both. Register the provider once, then invoke each agent to compare
+outputs on the same inputs.
+
+**A/B testing across vendors:**
+
+```ts
+defineAgent({
+  id: 'my-pack.weather-agent-groq',
+  // …
+  capabilities: [
+    { needs: [{ feature: 'tool-use' }, { models: { allow: ['llama-3.3-70b-versatile'] } }] },
+  ],
+  preferredProvider: 'groq',
+});
+
+defineAgent({
+  id: 'my-pack.weather-agent-anthropic',
+  // …
+  capabilities: [
+    { needs: [{ feature: 'tool-use' }, { models: { allow: ['claude-sonnet-5-5'] } }] },
+  ],
+  preferredProvider: 'anthropic',
+});
+```