@kindgi/sdk 0.1.4-rc.4 → 0.1.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kindgi/sdk",
-  "version": "0.1.4-rc.4",
+  "version": "0.1.4",
   "description": "@kindgi/sdk — the authoring SDK for Kindgi™. Facade over the individual @kindgi/* packages + @kindgi/client. Unifies pack authoring (defineTool / defineCheck / defineAgent / defineFlow) and client callsites (createClient) behind three sub-paths: /define, /client, /types. Re-export facade; zero behavior.",
   "license": "Apache-2.0",
   "repository": {
@@ -55,15 +55,15 @@
     "README.md"
   ],
   "dependencies": {
-    "@kindgi/agents": "0.1.4-rc.4",
-    "@kindgi/client": "0.1.4-rc.4",
-    "@kindgi/crypto": "0.1.4-rc.4",
-    "@kindgi/flow": "0.1.4-rc.4",
-    "@kindgi/guardrails": "0.1.4-rc.4",
-    "@kindgi/handler-runtime": "0.1.4-rc.4",
-    "@kindgi/schema": "0.1.4-rc.4",
-    "@kindgi/tools": "0.1.4-rc.4",
-    "@kindgi/types": "0.1.4-rc.4"
+    "@kindgi/agents": "0.1.4",
+    "@kindgi/client": "0.1.4",
+    "@kindgi/crypto": "0.1.4",
+    "@kindgi/flow": "0.1.4",
+    "@kindgi/guardrails": "0.1.4",
+    "@kindgi/handler-runtime": "0.1.4",
+    "@kindgi/schema": "0.1.4",
+    "@kindgi/tools": "0.1.4",
+    "@kindgi/types": "0.1.4"
   },
   "peerDependencies": {
     "zod": "^4.0.0"

package/skills/kindgi-authoring-agents/SKILL.md

@@ -12,7 +12,7 @@ description: >
   kindgi-authoring-guardrails.
 type: core
 library: "@kindgi/sdk"
-version: "0.4.2"
+version: "0.4.4"
 sdk_version: "0.0.0"
 pack_languages: [node]
 sources:
@@ -63,7 +63,7 @@ const defined = defineAgent({
   description:
     'Drafts appellate briefs from a case file. Cites precedents; escalates novel legal questions.',
   instructions:
-    'You are drafting a brief in {{ jurisdiction }}. The user provides the case facts; you produce a Section IV argument citing at least two precedents. Use `acme.verify-citation` on every cite before including it. Refuse to fabricate citations — always call the tool.',
+    'You are drafting a brief in {{ jurisdiction }}. The user provides the case facts; you produce a Section IV argument citing at least two precedents. Check every cite with the verify-citation tool before including it. Refuse to fabricate citations — always call the tool.',
   capabilities: [{ needs: [{ feature: 'tool-use' as const }] }],
   tools: [
     { id: 'acme.verify-citation', version: '^0.1.0' },
@@ -96,7 +96,11 @@ export default defined.value;
   `conversation.*`). Rendered with `strictVariables: true` — unresolved
   references fail loudly at invoke time. Frame instructions like a
   competent employee brief: what the agent does, what tools to prefer,
-  what to refuse, what quality bar to hit.
+  what to refuse, what quality bar to hit. Name a tool by what it does
+  ("the verify-citation tool"), never by its dotted id: the model sees
+  ids in its provider's form (`acme__verify-citation` for Anthropic and
+  OpenAI-compatible models), and `acme.verify-citation` in the
+  instructions can make it call a name it wasn't given.
 - **`capabilities`** — declares the resource kinds the agent needs at
   runtime. `{feature: 'tool-use'}` is standard for tool-calling
   agents. The router picks the concrete LLM provider at turn time.
@@ -121,10 +125,10 @@ export default defined.value;
   capability-based selection when the preferred provider is
   unregistered or filtered out.
 - **`preferredModel`** — optional soft hint at the model level: set to
-  a `ModelInfo.name` (e.g. `'gemini-2.5-pro'`), the router prefers
+  a `ModelInfo.name` (e.g. `'gemini-3.8-flash'`), the router prefers
   `(provider, model)` tuples whose model matches. To require a model
   rather than prefer it, add a hard requirement to the capability:
-  `capabilities: [{ needs: [{ feature: 'tool-use' }, { models: { allow: ['gemini-2.5-pro'] } }] }]`.
+  `capabilities: [{ needs: [{ feature: 'tool-use' }, { models: { allow: ['gemini-3.8-flash'] } }] }]`.
 - **`conversationPolicy`** — optional. Absent = each turn loads the
   conversation's full history and no HITL gates apply. `historyLimit`
   caps how many prior messages are loaded; `hitl` configures approval

package/skills/kindgi-authoring-providers/SKILL.md

@@ -5,8 +5,9 @@ description: >
   can actually call a real model. Covers four paths — hosted via
   Anthropic native adapter, Gemini on Vertex AI (Google Application
   Default Credentials, no API key), hosted via the OpenAI-compat adapter
-  (works with OpenAI + Groq + Together + Fireworks + OpenRouter +
-  Ollama + vLLM + any other OpenAI-compatible endpoint), and local
+  (works with OpenAI, Groq, self-hosted vLLM and Ollama, and any other
+  OpenAI-compatible endpoint, a hosted gateway such as OpenRouter
+  included), and local
   via the in-process ONNX adapter — plus the credential flow (in
   `kindgi dev` the key lives in the project's env files — `.env`, then
   `.env.local` — added by hand or with `kindgi secrets set`'s no-echo
@@ -22,7 +23,7 @@ description: >
   kindgi-getting-started.
 type: core
 library: "@kindgi/sdk"
-version: "0.9.4"
+version: "0.9.8"
 sdk_version: "0.0.0"
 pack_languages: [node, python]
 sources:
@@ -106,7 +107,11 @@ yours.
 ## Path A — Hosted, native Anthropic
 
 Best fidelity to Anthropic's API (prompt caching, latest models, tool
-use, structured output). Requires an `ANTHROPIC_API_KEY`.
+use). Requires an `ANTHROPIC_API_KEY`.
+
+A model's `structured-output` feature is a routing label: the model can
+follow a JSON schema natively, but Kindgi's typed outputs use instructions,
+then parse, check against the schema and repair, on every provider.
 
 **Step 1 — set the key:**
 ```sh
@@ -123,9 +128,18 @@ credential on argv.
 
 **Step 2 — register it, from the preset:**
 ```sh
-kindgi providers register --preset=anthropic                          # Opus 5.5, Sonnet 5.5, Haiku 4.5
-kindgi providers register --preset=anthropic --models=claude-haiku-4-5  # just one
+kindgi providers register --preset=anthropic                          # Opus 5.5, Sonnet 5.5 (default), Haiku 5.5, Haiku 4.5
+kindgi providers register --preset=anthropic --models=claude-sonnet-5-5  # just one
 ```
+Don't pin `claude-haiku-4-5`: Anthropic retires it on or after 2026-10-15,
+and a turn routed to it then fails; `claude-haiku-5-5` replaces it. Each
+preset names a default model (`metadata.defaultModel`, marked `(default)`
+when it registers), which an agent with no preference gets. A preset
+registered before 0.1.4 has none: unregister it and register it again.
+The Claude 5.5 and GPT-6 models take no `temperature` (`"sampling": false`:
+the call goes without it, with a `sampling-unsupported` warning), and a
+model's `thinking` says how it thinks; thinking counts against
+`maxOutputTokens` and bills as output.
 The preset carries the models, context windows, output limits and current
 prices (`kindgi providers presets` lists the presets and when their prices
 were checked); `--max-output-tokens=<n>` sets another output limit. In a pack it refuses until the key is in the pack's env files —
@@ -139,8 +153,8 @@ needs under `kindgi dev`:
 ```ts
 // in kindgi.config.ts
 providers: [
-  { preset: 'anthropic', models: ['claude-haiku-4-5'] },   // key ANTHROPIC_API_KEY, from the env files
-  { preset: 'gemini', project: 'acme-gcp', models: ['gemini-2.5-flash'] },
+  { preset: 'anthropic', models: ['claude-sonnet-5-5'] },  // key ANTHROPIC_API_KEY, from the env files
+  { preset: 'gemini', project: 'acme-gcp', models: ['gemini-3.8-flash'] },
   { spec: { /* the provider.json body below */ } },
 ],
 ```
@@ -148,7 +162,7 @@ providers: [
 # in pyproject.toml: one table per provider, same keys
 [[tool.kindgi.providers]]
 preset = "anthropic"
-models = ["claude-haiku-4-5"]
+models = ["claude-sonnet-5-5"]
 ```
 - A preset entry takes `models`, `project`, `secret` (the key's name, in place
   of the preset's) and `maxOutputTokens`, spelled the same in `pyproject.toml`;
@@ -167,7 +181,7 @@ models = ["claude-haiku-4-5"]
   providers with `kindgi providers register`.
 
 **Step 2 (by hand) — write `provider.json`** at the pack root. One connection,
-three models — matches how the Anthropic SDK actually works (the API
+two models — matches how the Anthropic SDK actually works (the API
 key is per-vendor; the model is per-call):
 ```json
 {
@@ -194,16 +208,6 @@ key is per-vendor; the model is per-call):
           "completionUsdPer1kTokens": 0.01
         },
         "description": "Balanced performance/cost."
-      },
-      {
-        "name": "claude-haiku-4-5",
-        "contextWindow": 200000,
-        "features": ["tool-use"],
-        "cost": {
-          "promptUsdPer1kTokens": 0.001,
-          "completionUsdPer1kTokens": 0.005
-        },
-        "description": "Fastest and cheapest — routing, classification, simple calls."
       }
     ],
     "description": "Anthropic Claude via native adapter."
@@ -241,7 +245,14 @@ capability requirement (see "How the router picks…" below).
 
 Nothing to switch off: `dev-echo` is a fallback, so the new provider
 answers every agent it satisfies. A turn that still lands on dev-echo
-carries a `fallback-provider` warning — see mistake 9.
+carries the `fallback-provider` and `dev-echo-not-a-model` warnings — see
+mistake 9.
+
+**The other one-key presets** work the same way, with their own key:
+`--preset=openai` (`OPENAI_API_KEY`), `--preset=gemini-api` (`GEMINI_API_KEY`,
+a Google AI Studio key; `gemini` is Vertex AI), `--preset=groq`
+(`GROQ_API_KEY`) and `--preset=openrouter` (`OPENROUTER_API_KEY`).
+`kindgi providers presets` lists them with their models.
 
 ## Path B — Hosted via OpenAI-compat
 
@@ -254,9 +265,9 @@ Works with **any** OpenAI-compatible endpoint. Same adapter, different
 | Groq | `https://api.groq.com/openai/v1` |
 | Together | `https://api.together.xyz/v1` |
 | Fireworks | `https://api.fireworks.ai/inference/v1` |
-| OpenRouter | `https://openrouter.ai/api/v1` |
 | DeepSeek | `https://api.deepseek.com/v1` |
 | LiteLLM proxy | `http://localhost:4000/v1` |
+| OpenRouter (a hosted gateway) | `https://openrouter.ai/api/v1` |
 
 The connection carries the `baseURL` (in `adapter_config`);
 each endpoint is a separate provider row because each has its own API
@@ -478,24 +489,16 @@ outside Google Cloud: put a service-account key (its JSON) in a secret
     "region": "global",
     "models": [
       {
-        "name": "gemini-2.5-pro",
+        "name": "gemini-3.8-flash",
         "contextWindow": 1048576,
-        "features": ["tool-use"],
+        "features": ["tool-use", "structured-output", "long-context"],
         "maxOutputTokens": 65536,
-        "cost": {
-          "promptUsdPer1kTokens": 0.00125,
-          "completionUsdPer1kTokens": 0.01,
-          "longContext": {
-            "thresholdTokens": 200000,
-            "promptUsdPer1kTokens": 0.0025,
-            "completionUsdPer1kTokens": 0.015
-          }
-        }
+        "cost": { "promptUsdPer1kTokens": 0.00075, "completionUsdPer1kTokens": 0.00375 }
       },
       {
-        "name": "gemini-2.5-flash",
+        "name": "gemini-3.5-flash-lite",
         "contextWindow": 1048576,
-        "features": ["tool-use"],
+        "features": ["tool-use", "structured-output", "long-context"],
         "maxOutputTokens": 65536,
         "cost": { "promptUsdPer1kTokens": 0.0003, "completionUsdPer1kTokens": 0.0025 }
       }
@@ -510,11 +513,17 @@ outside Google Cloud: put a service-account key (its JSON) in a secret
 - `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.
+  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.
-  `longContext` switches the whole call to the higher rates past the
-  threshold; `cachedPromptMultiplier` (default 0.25) prices cached
+  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.
 
 **Step 3 — register and check:**
@@ -546,8 +555,10 @@ tenant policy), then sorts survivors in this order:
    declares `prefer: [{feature: 'thinking', weight: 3}, ...]`, tuples
    with matching model features (or provider attributes) get higher
    scores. Sorted by summed score, descending.
-3. **Deterministic lexical tiebreak.** When scores tie, tuples sort by
-   `(providerId, modelName)` alphabetically — replay-safe and stable.
+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
@@ -696,8 +707,9 @@ defineAgent({
    does nothing. Pin the model with a `models: { allow: [...] }`
    requirement instead.
 
-9. **Replies still come from dev-echo** (`Tool responded: …`; the turn's
-   result has a `fallback-provider` warning). dev-echo is a fallback: it
+9. **Replies still come from dev-echo** (`⚠ dev-echo isn't a real model: …`
+   then `Tool responded: …`; the turn's result has the `fallback-provider`
+   and `dev-echo-not-a-model` warnings). dev-echo is a fallback: it
    answers only when no registered provider satisfies the agent. So your
    provider doesn't — check its models' `features` against the agent's
    `capabilities.needs` (mistake 2), a `models` / `providers` allow-list

package/skills/kindgi-python-authoring-agents/SKILL.md

@@ -15,7 +15,7 @@ description: >
   model by kindgi-authoring-providers.
 type: core
 library: "kindgi (Python)"
-version: "0.1.1"
+version: "0.1.4"
 sdk_version: "0.0.0"
 pack_languages: [python]
 sources:
@@ -77,7 +77,7 @@ brief_writer = Agent(
     instructions=(
         "You are drafting a brief in {{ jurisdiction }}. The user provides the case "
         "facts; you produce a Section IV argument citing at least two precedents. "
-        "Call acme.verify-citation on every cite before using it. Never invent one."
+        "Check every cite with the verify-citation tool before using it. Never invent one."
     ),
     capabilities=[{"needs": [{"feature": "tool-use"}]}],
     tools=[verify_citation, fetch_precedent],      # Tool objects — or {"id", "version"} refs
@@ -111,7 +111,11 @@ brief_writer = Agent(
   `parameters` or the runtime's own variables (`today`, `now`,
   `agent.*`, `conversation.*`), rendered strictly: an unknown variable
   fails the turn. Write it as a brief for a capable colleague: what to
-  do, which tools to prefer, what to refuse, the quality bar.
+  do, which tools to prefer, what to refuse, the quality bar. Name a
+  tool by what it does ("the verify-citation tool"), never by its dotted
+  id: the model sees ids in its provider's form (`acme__verify-citation`
+  for Anthropic and OpenAI-compatible models), and `acme.verify-citation`
+  in the instructions can make it call a name it wasn't given.
 - **`capabilities`** — what the model must support, e.g.
   `[{"needs": [{"feature": "tool-use"}]}]`. The turn routes its first
   capability to pick a provider and model; none declared fails the turn.
@@ -128,9 +132,9 @@ brief_writer = Agent(
   instructions.
 - **`preferred_provider`** / **`preferred_model`** — soft hints: the
   router prefers that provider id (e.g. `"anthropic"`) and/or model name
-  (e.g. `"claude-haiku-4-5"`) when they satisfy the capabilities. To
+  (e.g. `"claude-sonnet-5-5"`) when they satisfy the capabilities. To
   *require* a model, put it in the capability:
-  `{"needs": [{"feature": "tool-use"}, {"models": {"allow": ["claude-haiku-4-5"]}}]}`.
+  `{"needs": [{"feature": "tool-use"}, {"models": {"allow": ["claude-sonnet-5-5"]}}]}`.
 - **`conversation_policy`** — `{"historyLimit": n}` caps the prior
   messages loaded; `hitl` configures approval gates. Absent = the full
   history, no gates. A tenant's `hitl` policy can tighten the gates
@@ -161,8 +165,9 @@ brief_writer = Agent(
 Agents run on a registered model provider; the router picks one whose
 models satisfy `capabilities`. `kindgi dev` gives a new pack `dev-echo`,
 a **fallback** that answers only while no other provider fits — it
-calls the first tool and replies "Tool responded: …", and the turn
-carries a `fallback-provider` warning. Register a real model and it
+calls the first tool and replies "⚠ dev-echo isn't a real model: …"
+then "Tool responded: …", and the turn carries the `fallback-provider` and
+`dev-echo-not-a-model` warnings. Register a real model and it
 takes over: see `kindgi-authoring-providers`
 (`kindgi providers register --preset=anthropic`).
 

package/skills/kindgi-python-authoring-guardrails/SKILL.md

@@ -14,7 +14,7 @@ description: >
   kindgi-python-authoring-tools.
 type: core
 library: "kindgi (Python)"
-version: "0.1.2"
+version: "0.1.3"
 sdk_version: "0.0.0"
 pack_languages: [python]
 sources:
@@ -51,7 +51,7 @@ from kindgi import CheckResult, RunTrace, guardrail
 
 
 class Config(BaseModel):
-    min_lookups: int = Field(1, alias="minLookups", ge=0)
+    min_lookups: int = Field(default=1, alias="minLookups", ge=0)
 
 
 @guardrail(

package/skills/kindgi-python-getting-started/SKILL.md

@@ -14,7 +14,7 @@ description: >
   kindgi-python-authoring-agents; models by kindgi-authoring-providers.
 type: core
 library: "kindgi (Python)"
-version: "0.1.6"
+version: "0.1.7"
 sdk_version: "0.0.0"
 pack_languages: [python]
 sources:
@@ -123,9 +123,12 @@ uv run kindgi runs start --agent=my-pack.echo-agent --input='{"userMessage":"Ada
 ```
 
 The answer comes from `dev-echo`, a **fallback** provider a new pack
-gets: no model, no key — it calls the first tool and replies "Tool
-responded: …", and the turn carries a `fallback-provider` warning. For
-a real model, put the key in `.env` and register a provider:
+gets: no model, no key — it calls the first tool and replies "⚠
+dev-echo isn't a real model: …" then "Tool responded: …", and the turn
+carries the `fallback-provider` and `dev-echo-not-a-model` warnings. For a
+real model, put an LLM provider's key in `.env` and register its preset
+(Anthropic below; `kindgi providers presets` lists OpenAI, Gemini, Groq and
+OpenRouter too):
 
 ```sh
 uv run kindgi secrets set ANTHROPIC_API_KEY --env=local --scope=tenant   # no-echo prompt