@kindgi/cli 0.0.0-bootstrap.0 → 0.1.0

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

@@ -0,0 +1,205 @@
+---
+name: kindgi-python-authoring-agents
+description: >
+  Covers writing agents for a Kindgi pack in Python (the `kindgi`
+  package): declaring an `Agent(...)` at module level, wiring tools
+  (Tool objects or {id, version} refs) and guardrails, capabilities and
+  model choice (preferred_provider / preferred_model), conversation
+  policy, turn budgets, prompt template parameters, typed output from a
+  pydantic model, and tool-error retries. Load this whenever you are
+  authoring or editing code inside a Python pack's agents/ directory
+  (a pack whose config is `[tool.kindgi]` in pyproject.toml), defining
+  an agent, or when the user asks to add, modify or refactor one.
+  Python tools are covered by kindgi-python-authoring-tools, Python
+  guardrails by kindgi-python-authoring-guardrails, connecting a real
+  model by kindgi-authoring-providers.
+type: core
+library: "kindgi (Python)"
+version: "0.1.0"
+sdk_version: "0.1.0"
+pack_languages: [python]
+sources:
+  - sdks/python/src/kindgi/pack/define.py
+  - sdks/python/src/kindgi/pack/index.py
+---
+
+# 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 …`).
+
+An **agent** is a versioned, model-driven orchestrator: instructions (a
+prompt template), the tools it may call, the capabilities its model
+needs, guardrails that gate its answer, and an optional conversation
+policy. In a Python pack it is **data**: an `Agent(...)` assigned at
+module level in a file under `agents/`. The model runs in the Kindgi
+runtime, not in your Python process; your Python code runs only inside
+the agent's tools and guardrail checks.
+
+## Ask before building
+
+"Add an agent" is a conversation opener, not a ticket. Before writing a
+file, ask:
+
+- **What should the agent do?** The purpose drives everything else.
+- **Which tools does it need?** New ones, or existing ones?
+- **Multi-turn or one-shot?** History changes the shape.
+- **Any rules it must respect?** Those become guardrails.
+
+The pack's sample agent proves the runtime works end to end. It is not
+the shape to imitate unless the user asks for that.
+
+## An agent
+
+```python
+# agents/brief_writer.py
+from pydantic import BaseModel
+
+from kindgi import Agent
+
+from ..guardrails.citations import no_fabricated_quotes
+from ..tools.citations import fetch_precedent, verify_citation
+
+
+class Brief(BaseModel):
+    argument: str
+    citations: list[str]
+
+
+brief_writer = Agent(
+    id="acme.brief-writer",
+    version="0.1.0",
+    name="Brief Writer",
+    description="Drafts appellate briefs from a case file; cites precedents.",
+    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."
+    ),
+    capabilities=[{"needs": [{"feature": "tool-use"}]}],
+    tools=[verify_citation, fetch_precedent],      # Tool objects — or {"id", "version"} refs
+    guardrails=[no_fabricated_quotes],             # Guardrail objects — or ids
+    parameters=[{"name": "jurisdiction", "type": "string", "required": True}],
+    conversation_policy={"historyLimit": 20},
+    budget={"maxSteps": 8, "maxCostUsd": 0.5, "maxWallMs": 60_000},
+    output=Brief,                                  # typed answer (optional)
+)
+```
+
+- Import tools and guardrails with **relative imports** — every file in
+  the pack is imported as part of one package rooted at the pack.
+- **Dict-valued fields keep the wire's camelCase keys**: `maxSteps`,
+  `maxCostUsd`, `maxWallMs`, `historyLimit`, `maxRetries`, `retryOn`.
+  Only the `Agent` keyword arguments themselves are snake_case.
+- A file may define several agents; each must be assigned at module
+  level (an agent built inside a function is invisible to the indexer).
+- `Agent(...)` checks the id (non-empty) and the version (an exact
+  semver) where it is written. Everything else is checked when Kindgi
+  reads the pack: `uv run python -m kindgi.pack index --pack-dir .`
+  shows what it sees, and `kindgi dev` reports a problem with its file.
+
+## Field by field
+
+- **`id`** — `<pack-id>.<agent-name>`, kebab-case, dot-namespaced.
+- **`version`** — exact semver. Conversations pin the version they
+  started on.
+- **`name`**, **`description`**, **`tags`** — for people and listings.
+- **`instructions`** — a LiquidJS template. `{{ variable }}` comes from
+  `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.
+- **`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.
+- **`tools`** — `Tool` objects (pinned to that tool's version, or the
+  pack's) or `{"id": "acme.x", "version": "^0.1.0"}` refs, where
+  `version` is a semver **range**; the highest active matching version
+  is picked at turn start. A bare string is rejected. Empty = a
+  chat-only agent.
+- **`guardrails`** — `Guardrail` objects or ids. Evaluated once per
+  turn on the final answer, before it is stored. An id with no
+  registered guardrail fails the turn (`unresolved-guardrail`).
+- **`parameters`** — inputs the caller supplies per run
+  (`{"name", "type", "required"}`); they fill `{{ … }}` in the
+  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
+  *require* a model, put it in the capability:
+  `{"needs": [{"feature": "tool-use"}, {"models": {"allow": ["claude-haiku-4-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
+  (shorter timeout, higher reviewer role, stricter per tool), never
+  loosen them.
+- **`budget`** — per turn: `maxSteps` (model calls, default 8),
+  `maxCostUsd`, `maxWallMs` (default 120 000). Steps or cost exceeded
+  fails the turn (`budget-exceeded`); out of wall time aborts it. Leave
+  room for real models: a turn with tool calls can take tens of seconds.
+- **`output`** — a typed answer: a pydantic model class (or any type
+  pydantic understands, or a JSON Schema dict), or the full
+  `{"schema", "name", "maxRepairs"}` object. The final answer must be
+  JSON matching it; a wrong one goes back to the model with the problems
+  (`maxRepairs`, default 1), then the turn fails
+  (`output-schema-violation`). The parsed answer is the turn result's
+  `output` — a dict on the wire (with `kindgi.client`:
+  `Brief.model_validate(run.output["output"])`), and in a flow
+  `nodeOutputs.<step>.output.<field>`.
+- **`tool_errors`** — `{"maxRetries": 1, "retryOn": [...]}`: a failed
+  tool call goes back to the model as the call's result so it can fix
+  the call. Default kinds are `invalid-arguments` and `unknown-tool`
+  (nothing ran); add `tool-error` only when retrying the tool is safe.
+  Each retry costs a step.
+- **`retrieval`** — memory retrieval declarations; usually `[]`.
+
+## Which model answers
+
+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
+takes over: see `kindgi-authoring-providers`
+(`kindgi providers register --preset=anthropic`).
+
+## Iterating
+
+Save the file; `kindgi dev` re-indexes and the next run uses it. No
+version bump, no restart. Bump `version` when you break what callers
+rely on (a removed parameter, an incompatible output), not on every
+save.
+
+Run an agent from another terminal in the pack directory:
+
+```sh
+kindgi runs start --agent=acme.brief-writer --input='{"userMessage":"…"}'
+```
+
+or from Python with `kindgi.client` (`Kindgi().runs.start(agent=…, input=…)`).
+
+## Common mistakes
+
+1. **Building an agent without asking what it should do.** Copying the
+   sample's shape answers the wrong question.
+2. **`tools=["acme.x"]`.** A tool is a `Tool` object or an
+   `{"id", "version"}` ref; a bare string fails the index.
+3. **snake_case inside the dicts.** `budget={"max_steps": 4}` is not a
+   budget; the keys are `maxSteps`, `historyLimit`, `maxRetries`, ….
+4. **An unregistered guardrail id.** Pass the `Guardrail` object you
+   import, or make sure the id is one the tenant has.
+5. **`{{ variable }}` not in `parameters`.** The turn fails when the
+   instructions render.
+6. **No `capabilities`.** The turn can't pick a model.
+7. **Defining the agent inside a function or under `if __name__`.** Only
+   module-level primitives are collected.
+8. **A tight `maxWallMs` with a real model.** 15 s aborts real turns
+   under load; 60 s is a safer start.
+
+## When the framework itself is the problem
+
+If the bug is in Kindgi or the `kindgi` package itself (the index
+dropping a field, a misleading error, the router picking the wrong
+model) and not in the pack's code, load `kindgi-framework-feedback` and
+file it with `kindgi feedback write`.

package/dist/sdk-skills/kindgi-python-authoring-flows/SKILL.md

@@ -0,0 +1,322 @@
+---
+name: kindgi-python-authoring-flows
+description: >
+  Covers writing flows for a Kindgi pack in Python (the `kindgi`
+  package): declaring a `Flow(...)` at module level, tool and agent
+  steps (Tool and Agent objects as refs), edges and `when` conditions,
+  branches that join again, inputMapping from runInput / nodeOutputs,
+  typed agent output in a flow, the flow's declared output, loops
+  (foreach / while) and fanout, per-edge retry and timeout, and running
+  a flow (kindgi runs start --flow, in the background, as a dry run) and
+  reading its journal. Load this whenever you are authoring or editing
+  code inside a Python pack's flows/ directory (a pack whose config is
+  `[tool.kindgi]` in pyproject.toml), defining a flow, or when the user
+  asks to add, change or debug one. Python tools are covered by
+  kindgi-python-authoring-tools, Python agents by
+  kindgi-python-authoring-agents.
+type: core
+library: "kindgi (Python)"
+version: "0.1.0"
+sdk_version: "0.1.0"
+pack_languages: [python]
+sources:
+  - sdks/python/src/kindgi/pack/define.py
+  - sdks/python/src/kindgi/pack/index.py
+  - packages/specs/schemas/flow.schema.json
+---
+
+# 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 …`).
+
+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.
+It is **data**, not code: a `Flow(...)` at module level in
+`flows/<name>.py`. The runtime runs it step by step, journals every
+step, and can resume a run that was interrupted. A run pins the flow
+version it started on.
+
+Use a flow when the order of the work is known: parse, then classify,
+then branch, then write. Use a single agent when the model should decide
+the order.
+
+## Ask before building
+
+- **What goes in, and what comes out?** The run input's shape and the
+  output the caller reads. They become `runInput.*` paths and `output`.
+- **Which steps are code, which are judgment?** Deterministic work
+  (parse, rank, look up, write) is a tool; judgment (classify, draft,
+  summarize) is an agent with a typed `output`.
+- **Where does it branch?** Every branch needs a condition, and the
+  steps after a branch must cope with the branch that didn't run.
+- **What does it change outside Kindgi?** Know which tools write: a dry
+  run stops before them (see "Running a flow").
+
+## A flow
+
+```python
+# flows/triage_ticket.py
+from kindgi import Flow
+
+from ..agents.ticket_classifier import ticket_classifier
+from ..tools.tickets import draft_reply, lookup_invoice, parse_ticket
+
+IS_BILLING = {
+    "op": "eq",
+    "left": {"path": "nodeOutputs.classify.output.category"},
+    "right": {"literal": "billing"},
+}
+
+triage_ticket = Flow(
+    id="acme.triage-ticket",
+    version="0.1.0",
+    name="Triage a support ticket",
+    description="Parses a ticket, classifies it, looks up billing when needed, drafts a reply.",
+    nodes=[
+        {
+            "id": "parse",
+            "kind": "tool",
+            "ref": parse_ticket,
+            "inputMapping": {"ticket": {"path": "runInput.ticket"}},
+        },
+        {
+            "id": "classify",
+            "kind": "agent",
+            "ref": ticket_classifier,  # an Agent with output=
+            "inputMapping": {"text": {"path": "nodeOutputs.parse.text"}},
+            "config": {"parameters": {"product": "acme-cloud"}},
+        },
+        {
+            "id": "billing",
+            "kind": "tool",
+            "ref": lookup_invoice,
+            "inputMapping": {"customer_id": {"path": "runInput.ticket.customer_id"}},
+        },
+        {
+            "id": "reply",
+            "kind": "tool",
+            "ref": draft_reply,
+            "inputMapping": {
+                "category": {"path": "nodeOutputs.classify.output.category"},
+                "invoice": {"path": "nodeOutputs.billing.invoice"},  # absent when billing didn't run
+            },
+        },
+    ],
+    edges=[
+        {"id": "e0", "from": "$start", "to": "parse"},
+        {"id": "e1", "from": "parse", "to": "classify"},
+        {"id": "e2", "from": "classify", "to": "billing", "when": IS_BILLING},
+        {"id": "e3", "from": "classify", "to": "reply", "when": {"op": "not", "child": IS_BILLING}},
+        {"id": "e4", "from": "billing", "to": "reply"},
+        {"id": "e5", "from": "reply", "to": "$end"},
+    ],
+    output={
+        "mapping": {
+            "category": {"path": "nodeOutputs.classify.output.category"},
+            "reply": {"path": "nodeOutputs.reply.text"},
+        },
+        "schema": {
+            "type": "object",
+            "properties": {"category": {"type": "string"}, "reply": {"type": "string"}},
+            "required": ["category", "reply"],
+        },
+    },
+)
+```
+
+- **Refs** are the `Tool` / `Agent` (or `Flow`) objects, imported
+  relatively from the pack's own modules — anywhere in the flow, loop
+  bodies and fanout branches included. A primitive from another pack is
+  its id string. Ids are plain strings; no casts.
+- **The dicts are the wire shape**, so their keys are camelCase
+  (`inputMapping`, `loopKind`, `maxIterations`); `Flow`'s own keywords
+  are snake_case (`max_parallelism`).
+- **Where it's checked:** `Flow(...)` checks the id when the module
+  loads. The indexer checks the rest against `flow.schema.json` —
+  version, node and edge shapes, `$start` / `$end` — and `kindgi dev`
+  reports a mistake as a file error that says what and where
+  (`flow 'acme.triage-ticket' is invalid at /nodes/0: must NOT have
+  additional properties ('input_mapping')`), while the pack's other
+  primitives keep serving. That a ref's tool or agent
+  exists is checked when a run starts (see "Running a flow").
+
+## Nodes
+
+- **`"kind": "tool"`** runs the tool `ref`. The tool's input is what the
+  node's `inputMapping` builds, else the output of the node's single
+  upstream node (the run input after `$start`). It is validated against
+  the tool's input schema, so a mismatch fails the step with
+  `input-validation-failed`. The node's output is the tool's return
+  value, as JSON (field aliases, if the model has any).
+- **`"kind": "agent"`** runs one turn of the agent `ref` as a child run
+  of the flow run. The agent gets the node's input in two ways:
+  - as **structured input**: `{{ input.text }}` in its instructions;
+  - as its user message (the input as JSON).
+
+  `"config": {"parameters": {…}}` fills the agent's `parameters`
+  (string, number or boolean values). `"config": {"version": "1.2.0"}`
+  pins an agent version; without it the latest active version runs.
+
+  The node's output:
+  - `output` is the agent's typed answer (its `output=` model);
+  - `text` is the answer as text;
+  - `runId` and `conversationId` belong to the child run.
+
+  Read a field as `nodeOutputs.<node>.output.<field>`. An answer that
+  doesn't fit the agent's `output`, after its repairs, fails the step
+  with `output-schema-violation`. An approval inside the agent's turn
+  parks the flow until it's decided.
+- **`"kind": "loop"`** repeats a body: `"loopKind": "foreach"` once per
+  element of `iterateOver` (`concurrency` up to 32 in parallel), or
+  `"loopKind": "while"` until `exitCondition`.
+  - The body (`"body": {"nodes": [...], "edges": [...]}`) has its own
+    nodes and edges, with `$loop-start` / `$loop-end`; the element is
+    the body's input.
+  - `maxIterations` and `outputSchema` are required.
+  - The loop's output is `finalOutput`, plus `outputs` with
+    `"collectAllIterations": True`.
+  - Node ids must be unique across the whole flow, bodies included.
+- **`"kind": "fanout"`** runs several handlers on the same input at
+  once, each a branch (`branchId`, `handler` — a `Tool` or an id —
+  and `outputSchema`). `convergence` decides the result: `all-succeed`,
+  `any-succeed` (the first success wins), or `settle-all` (wait for
+  every branch and report each).
+- **`"kind": "subgraph"`** (a sub-flow) is part of the flow schema, but a
+  run refuses it today (`flow-unbound`). Inline the steps instead.
+
+## Edges and conditions
+
+An edge goes from a node (or `$start`) to a node (or `$end`). Without
+`when` it fires when its source completes; with `when` it fires only if
+the condition is true. Conditions are dicts:
+
+| Operator | Shape |
+|---|---|
+| `eq` `ne` `lt` `lte` `gt` `gte` | `{"op", "left", "right"}` |
+| `in` `notIn` | `{"op", "value", "set"}` |
+| `exists` `notExists` `truthy` `falsy` | `{"op", "value"}` |
+| `and` `or` | `{"op", "children": [...]}` |
+| `not` | `{"op", "child"}` |
+
+Each operand is `{"literal": …}` or `{"path": …}`. A comparison whose
+path doesn't resolve is **false**, `ne` included. So to branch on "not
+billing", write `not` around the `eq` (as above), not `ne`. A condition
+used twice is easiest as a module-level constant (`IS_BILLING`).
+
+**Joining branches.** A node with several incoming edges runs once every
+one of them is decided and at least one fired. In the example, `reply`
+runs after `billing` on the billing branch, and straight after
+`classify` otherwise. A node none of whose incoming edges fired is
+skipped, and so is everything only it leads to.
+
+**Edge policy** (`"policy"` on the edge into a node with a single
+incoming edge):
+- `"retry": {"maxAttempts", "delayMs"?, "backoff"?, "maxDelayMs"?}`: up
+  to 10 attempts in all;
+- `"timeoutMs"`: a step that takes longer fails with `reason: timeout`;
+- `"concurrencyKey"`: at most one such step at a time in the tenant;
+- `"priority"`: −100 to 100.
+
+A node with several incoming edges ignores them.
+
+## Inputs and the output
+
+`inputMapping` maps each key to a `{"literal": …}` or a `{"path": …}`.
+Its keys are the tool's input **as it travels**: a pydantic field's name,
+or its alias if it has one (a `customer_id` field is the key
+`customer_id`; with `alias="customerId"`, it's `customerId`). Paths are
+dot-separated, with no array indexing, rooted at:
+- `runInput.…`: the input the run was started with;
+- `nodeOutputs.<nodeId>.…`: a step's output. For an agent step, add
+  `.output.<field>` to read its typed answer;
+- `state.…`: values written by the runtime's own handlers. Pack tools
+  don't write it, so use `nodeOutputs`.
+
+A path that doesn't resolve leaves its key out. A step after a branch
+that didn't run gets no `invoice` key at all, rather than `None`. Give
+that field a default in the tool's input model
+(`invoice: Invoice | None = None`).
+
+`output` is what the run returns: a `mapping` resolved when the run
+finishes, checked against `schema` if you give one. A run whose output
+doesn't match fails. Without `output`, the run returns the output of the
+step that reached `$end`.
+
+## Running a flow
+
+From another terminal in the pack directory, while `kindgi dev` runs:
+
+```sh
+kindgi runs start --flow=acme.triage-ticket --input='{"ticket":{"customer_id":"c-1","body":"Charged twice"}}'
+kindgi runs start --flow=acme.triage-ticket --input=@ticket.json --no-wait   # the run id now; it finishes in the background
+kindgi runs start --flow=acme.triage-ticket --input=@ticket.json --dry-run   # stops before a tool that may write
+kindgi runs get <run-id>        # status, output, failureMessage
+kindgi runs journal <run-id>    # every step.started / step.completed / edge.evaluated
+kindgi runs stream <run-id>     # follow a running one
+kindgi runs cancel <run-id>
+```
+
+Or from Python, with `kindgi.client`:
+`Kindgi().runs.start(flow="acme.triage-ticket", input={...})`.
+
+- **A refusal before the run exists:** `422 flow-unbound` names the
+  nodes a run can't bind: a tool or agent id the tenant doesn't have, or
+  a sub-flow. Fix the ids; nothing ran.
+- **A failed step fails the run**, and `failureMessage` says which step
+  and why. Retry it on its edge with `policy.retry` only if running the
+  step twice is safe.
+- **`--no-wait`** is how an application starts runs
+  (`options={"wait": False}`). It answers with the run id at once; poll
+  the run or follow its stream.
+- **`--dry-run`** runs a tool only if it's declared read-only:
+  `@tool(..., mutating=False)` (or `http_tool(..., mutating=False)`),
+  and no `writes`, `deletes`, `spawns-run`, `emits-event` or
+  `external-side-effect` effect. The first other tool stops the run with
+  `dry-run-effectful-tool`, and everything before it really ran. That's
+  useful for checking the wiring without the writes.
+
+## Iterating on a flow
+
+Save the file and `kindgi dev` re-indexes; the next run uses the new
+definition, with no restart. A run already in flight keeps the version it
+started on. Bump `version` when callers' contract changes (the input or
+the output), not on every save.
+
+## Common mistakes
+
+1. **Building a flow without asking what goes in and comes out.** The
+   pack's `echo_flow` proves the runtime works. It isn't a template for
+   the user's flow.
+2. **`ne` on a path that may be missing, to mean "otherwise".** A missing
+   path makes every comparison false, so neither branch fires and
+   everything after is skipped. Use `not` around the positive condition.
+3. **Reading an agent step's answer at `nodeOutputs.<step>.<field>`.**
+   The typed answer is under `.output`: `nodeOutputs.<step>.output.<field>`.
+   An agent without `output=` has only `text`.
+4. **A required input field fed by a branch that may not run.** The key
+   is omitted, the tool's input check fails, and so does the step. Give
+   the field a default.
+5. **`inputMapping` keys in the wrong spelling.** They're the input's
+   wire names (field names, or aliases): `customerId` doesn't fill a
+   `customer_id` field that has no alias.
+6. **snake_case keys inside the dicts** (`input_mapping`,
+   `max_iterations`). The indexer refuses them, naming the key; the
+   dicts are camelCase.
+7. **A sub-flow node.** A run refuses it (`flow-unbound`) until
+   sub-flows are supported.
+8. **Duplicate node ids inside a loop body.** Ids are unique across the
+   whole flow, bodies included.
+9. **`mutating=False` on a tool that writes.** A dry run then runs it for
+   real, and an agent's tool approval gate (when it falls back on
+   `mutating`) won't ask before it.
+10. **A read-only tool without `mutating=False`.** A dry run stops at it,
+    and an agent's tool approval gate asks before it on first use.
+
+## When the framework itself is the problem
+
+If the bug is in Kindgi or the `kindgi` package (a step's output missing
+a field, a condition that evaluates wrongly, a misleading error) and not
+in the pack's code, load `kindgi-framework-feedback` and file it with
+`kindgi feedback write`.