@kindgi/sdk 0.1.4-rc.3 → 0.1.4-rc.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kindgi/sdk",
-  "version": "0.1.4-rc.3",
+  "version": "0.1.4-rc.5",
   "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.3",
-    "@kindgi/client": "0.1.4-rc.3",
-    "@kindgi/crypto": "0.1.4-rc.3",
-    "@kindgi/flow": "0.1.4-rc.3",
-    "@kindgi/guardrails": "0.1.4-rc.3",
-    "@kindgi/handler-runtime": "0.1.4-rc.3",
-    "@kindgi/schema": "0.1.4-rc.3",
-    "@kindgi/tools": "0.1.4-rc.3",
-    "@kindgi/types": "0.1.4-rc.3"
+    "@kindgi/agents": "0.1.4-rc.5",
+    "@kindgi/client": "0.1.4-rc.5",
+    "@kindgi/crypto": "0.1.4-rc.5",
+    "@kindgi/flow": "0.1.4-rc.5",
+    "@kindgi/guardrails": "0.1.4-rc.5",
+    "@kindgi/handler-runtime": "0.1.4-rc.5",
+    "@kindgi/schema": "0.1.4-rc.5",
+    "@kindgi/tools": "0.1.4-rc.5",
+    "@kindgi/types": "0.1.4-rc.5"
   },
   "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.3"
 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.

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

@@ -22,7 +22,7 @@ description: >
   kindgi-getting-started.
 type: core
 library: "@kindgi/sdk"
-version: "0.9.3"
+version: "0.9.5"
 sdk_version: "0.0.0"
 pack_languages: [node, python]
 sources:
@@ -241,7 +241,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
 
@@ -305,15 +312,23 @@ kindgi secrets set GROQ_API_KEY --env=local --scope=tenant
 
 **Steps 3–5** same as Path A.
 
-## Path C — Local via in-process ONNX
+## 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** ([Local via Ollama](#local-via-ollama-via-path-b)).
 
 > ⚠️ **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 local dev, smoke tests, and CI
-> runners that 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.
+> 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
@@ -385,7 +400,8 @@ 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 every `kindgi dev` boot script.
+return almost instantly, so put it in the script that boots your
+from-source runtime.
 
 Multi-model providers: prepare each model separately.
 ```sh
@@ -687,8 +703,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.0"
+version: "0.1.3"
 sdk_version: "0.0.0"
 pack_languages: [python]
 sources:
@@ -25,9 +25,11 @@ sources:
 
 # Authoring Kindgi agents in Python
 
-> **Running `kindgi`:** a Python pack has no Node project, so the
-> `kindgi` CLI is the one on `PATH`. Python commands run in the pack's
-> environment: `uv run …` (or `.venv/bin/python …`).
+> **Running `kindgi`:** the CLI is `kindgi-cli` from PyPI, pinned in the
+> pack's dev group, so every `kindgi <command>` below runs as
+> `uv run kindgi <command>` (Poetry: `poetry run kindgi <command>`). Python
+> commands run in the pack's environment the same way: `uv run …` (or
+> `.venv/bin/python …`).
 
 An **agent** is a versioned, model-driven orchestrator: instructions (a
 prompt template), the tools it may call, the capabilities its model
@@ -75,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
@@ -109,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.
@@ -159,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-flows/SKILL.md

@@ -16,7 +16,7 @@ description: >
   kindgi-python-authoring-agents.
 type: core
 library: "kindgi (Python)"
-version: "0.1.1"
+version: "0.1.2"
 sdk_version: "0.0.0"
 pack_languages: [python]
 sources:
@@ -27,9 +27,11 @@ sources:
 
 # Authoring Kindgi flows in Python
 
-> **Running `kindgi`:** a Python pack has no Node project, so the
-> `kindgi` CLI is the one on `PATH`. Python commands run in the pack's
-> environment: `uv run …` (or `.venv/bin/python …`).
+> **Running `kindgi`:** the CLI is `kindgi-cli` from PyPI, pinned in the
+> pack's dev group, so every `kindgi <command>` below runs as
+> `uv run kindgi <command>` (Poetry: `poetry run kindgi <command>`). Python
+> commands run in the pack's environment the same way: `uv run …` (or
+> `.venv/bin/python …`).
 
 A **flow** is a versioned, durable graph of steps: tools (your code) and
 agents (a model's judgment), joined by edges that can carry conditions.

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.1"
+version: "0.1.3"
 sdk_version: "0.0.0"
 pack_languages: [python]
 sources:
@@ -25,9 +25,11 @@ sources:
 
 # Authoring Kindgi guardrails in Python
 
-> **Running `kindgi`:** a Python pack has no Node project, so the
-> `kindgi` CLI is the one on `PATH`. Python commands run in the pack's
-> environment: `uv run …` (or `.venv/bin/python …`).
+> **Running `kindgi`:** the CLI is `kindgi-cli` from PyPI, pinned in the
+> pack's dev group, so every `kindgi <command>` below runs as
+> `uv run kindgi <command>` (Poetry: `poetry run kindgi <command>`). Python
+> commands run in the pack's environment the same way: `uv run …` (or
+> `.venv/bin/python …`).
 
 A **guardrail** is a rule an agent's turn must satisfy: a **check** (a
 function over the turn's trace) plus an **action** (what happens when it
@@ -49,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-authoring-tools/SKILL.md

@@ -14,7 +14,7 @@ description: >
   kindgi-python-getting-started.
 type: core
 library: "kindgi (Python)"
-version: "0.1.1"
+version: "0.1.2"
 sdk_version: "0.0.0"
 pack_languages: [python]
 sources:
@@ -25,9 +25,11 @@ sources:
 
 # Authoring Kindgi tools in Python
 
-> **Running `kindgi`:** a Python pack has no Node project, so the
-> `kindgi` CLI is the one on `PATH`. Python commands run in the pack's
-> environment: `uv run …` (or `.venv/bin/python …`).
+> **Running `kindgi`:** the CLI is `kindgi-cli` from PyPI, pinned in the
+> pack's dev group, so every `kindgi <command>` below runs as
+> `uv run kindgi <command>` (Poetry: `poetry run kindgi <command>`). Python
+> commands run in the pack's environment the same way: `uv run …` (or
+> `.venv/bin/python …`).
 
 A **tool** is a unit of work an agent (or a flow step) calls: typed
 input, typed output, your code in between. In a Python pack it is a

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.5"
+version: "0.1.7"
 sdk_version: "0.0.0"
 pack_languages: [python]
 sources:
@@ -25,9 +25,11 @@ sources:
 
 # Getting started with Kindgi in Python
 
-> **Running `kindgi`:** a Python pack has no Node project, so the
-> `kindgi` CLI (a Node 22.12+ program) is the one on `PATH`. Python
-> commands run in the pack's environment: `uv run …`.
+> **Running `kindgi`:** the CLI is `kindgi-cli` from PyPI (the Kindgi CLI
+> with its own Node, so no Node install), pinned in the pack's dev group.
+> Every `kindgi <command>` below runs as `uv run kindgi <command>` (Poetry:
+> `poetry run kindgi <command>`). Python commands run in the pack's
+> environment the same way: `uv run …`.
 
 ## What a pack is
 
@@ -52,11 +54,11 @@ primitive; `test_*.py`, `*_test.py` and `conftest.py` are skipped.
 ## Scaffold a new pack
 
 ```sh
-kindgi init my-pack --template=python
+uvx --from "kindgi-cli>=0.1,<0.2" kindgi init my-pack --template=python
 cd my-pack
-uv sync            # .venv with the kindgi package
+uv sync            # .venv with the kindgi package and the kindgi CLI
 uv run pytest
-kindgi dev         # boots Kindgi locally and runs this pack, reloading on save
+uv run kindgi dev  # boots Kindgi locally and runs this pack, reloading on save
 ```
 
 `kindgi dev` needs Postgres: it starts one in Docker unless
@@ -70,9 +72,10 @@ kindgi dev         # boots Kindgi locally and runs this pack, reloading on save
 In the app's directory (where its `pyproject.toml` is):
 
 ```sh
-kindgi init            # --pack-id=<id> if the app's name doesn't make one
+uv add --dev "kindgi-cli>=0.1,<0.2"   # the CLI (Poetry: poetry add --group dev …)
+uv run kindgi init     # --pack-id=<id> if the app's name doesn't make one
 uv sync                # or what it prints for Poetry / pip
-kindgi dev
+uv run kindgi dev
 ```
 
 `kindgi init` edits the app's `pyproject.toml` in place — your layout and
@@ -116,17 +119,20 @@ The `[tool.kindgi]` keys are the ones `kindgi.config.ts` takes —
 With `kindgi dev` running, from another terminal in the pack directory:
 
 ```sh
-kindgi runs start --agent=my-pack.echo-agent --input='{"userMessage":"Ada"}'
+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
-kindgi secrets set ANTHROPIC_API_KEY --env=local --scope=tenant   # no-echo prompt
-kindgi providers register --preset=anthropic
+uv run kindgi secrets set ANTHROPIC_API_KEY --env=local --scope=tenant   # no-echo prompt
+uv run kindgi providers register --preset=anthropic
 ```
 
 It takes over at the next turn. That registration is in this project's dev