@kindgi/sdk 0.1.4 → 0.1.5-rc.0

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

@@ -0,0 +1,199 @@
+---
+name: kindgi-scala-authoring-guardrails
+description: >
+  Covers writing guardrails (safety checks on an agent's turn) for a Kindgi
+  pack in Scala (`kindgi-pack-scala`, `com.kindgi.pack.scaladsl`):
+  `Guardrail[Config](id)` as a `val` of an object named like its file, a
+  `(config, trace)` check returning a `CheckResult` (or a Future of one with
+  `checkAsync`), `RunTrace`, config case classes and the values a check runs
+  with, actions (halt / retry / escalate / log-only / compensate), severity
+  and scope, munit tests with `evaluate`, and wiring a guardrail onto an
+  agent. Load this whenever you are authoring or editing code in a Scala
+  pack's guardrails packages (a pack whose `kindgi.config.json` says
+  `"language": "scala"`), defining a check, or wiring a guardrail onto an
+  agent. Scala agents are covered by kindgi-scala-authoring-agents, Scala
+  tools by kindgi-scala-authoring-tools.
+type: core
+library: "kindgi-pack-scala"
+version: "0.1.0"
+sdk_version: "0.0.0"
+pack_languages: [scala]
+sources:
+  - sdks/scala/README.md
+  - sdks/scala/kindgi-pack-scala/src/main/scala/com/kindgi/pack/scaladsl/Guardrail.scala
+  - sdks/java/kindgi-pack/src/main/java/com/kindgi/pack/RunTrace.java
+---
+
+# Authoring Kindgi guardrails in Scala
+
+> **Running `kindgi`:** the pack pins its CLI (`"cli"` in
+> `kindgi.config.json`), and `./kindgiw` runs that version, so every
+> `kindgi <command>` below runs as `./kindgiw <command>`.
+>
+> Scala support is in preview: tested and supported, but the API may still
+> change in 0.1.6 without the usual deprecation period.
+
+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
+fails). In a Scala pack it is a `val` of type `Guardrail[C]` in an object
+named like its file, in a `guardrails` package. For an agent turn, the
+runtime evaluates every guardrail the agent lists once, on the final answer,
+before it is stored.
+
+Ask what the rule should catch before writing one. The sample
+`response-not-empty` guardrail is a demonstration, not a template.
+
+## A guardrail
+
+```scala
+// src/main/scala/acme/guardrails/Citations.scala
+package acme.guardrails
+
+import com.kindgi.pack.scaladsl._
+import jakarta.validation.constraints.Min
+import scala.jdk.CollectionConverters._
+
+/** acme.no-fabricated-quotes: an answer that quotes case law looked the citations up. */
+object Citations {
+  final case class Config(@Min(value = 0) minLookups: Int = 1)
+
+  val noFabricatedQuotes: Guardrail[Config] = Guardrail[Config]("acme.no-fabricated-quotes")
+    .name("No fabricated quotations")
+    .onViolation("halt")
+    .severity("critical")
+    // What the check runs with, keyed as on the wire.
+    .set("config", Map("minLookups" -> 2))
+    .check { (config, trace) =>
+      val lookups = trace.toolCalls.asScala.count {
+        case call: java.util.Map[_, _] => call.get("toolName") == "acme.verify-citation"
+        case _                         => false
+      }
+      if (lookups >= config.minLookups) CheckResult.pass
+      else CheckResult.fail(s"Only $lookups citation lookups (need ${config.minLookups}+).")
+    }
+}
+```
+
+- **The check** is `(config, trace) => CheckResult`: `CheckResult.pass` or
+  `CheckResult.fail(reason)`. A failed result's reason is what the violation
+  reports, so make it say what was wrong. `checkAsync` takes a
+  `(config, trace) => Future[CheckResult]`.
+- **`trace`** is a `RunTrace` (kindgi-pack's), with Java collections:
+  - `output`: the final answer's text (`null` when there's none: wrap it in
+    `Option`);
+  - `userInput`;
+  - `toolCalls`: each a map with `toolId`, `toolName` (the tool's dotted
+    id), `arguments`;
+  - `toolResults`: each with `toolCallId`, `output`;
+  - `modelCalls`;
+  - `mode`: `runtime` or `ci`;
+  - `runId`, `tenantId`;
+  - `raw`: the trace as sent.
+- **`Guardrail[Config](id)`** takes the config's case class. Its schema is
+  derived as a tool input's is, and a parameter's default is the value when
+  none is given. `Guardrail.json(id).configSchema(Map(…))` gives a schema
+  instead; the config is then a `Map[String, Any]`.
+- **`set("config", Map(…))`** holds the values the check runs with, keyed as
+  on the wire. They go into the index, and the service checks them against
+  the schema before every evaluation. Without them the check runs with `{}`
+  and the defaults. So give every parameter a default: a required one with
+  no value fails every evaluation (`input-validation-failed`).
+- An exception thrown from the check fails the evaluation (`handler-throw`).
+  For a rule that isn't met, return `CheckResult.fail(…)`.
+- A check gets no model and no provider: it can't call an LLM. Keep it a
+  pure function of the trace (fast, deterministic, free).
+
+## `Guardrail[Config](id)`
+
+- **`id`:** `<pack-id>.<guardrail-name>`, kebab-case. Name the rule as a
+  positive assertion: `no-fabricated-quotes`, `response-not-empty`.
+- **`onViolation(action)`:** `halt`, `retry`, `escalate`, `log-only` or
+  `compensate`. For one that needs settings, pass the whole object instead,
+  with `action(Map("on-violation" -> "retry", "retry" -> Map("maxAttempts" -> 2)))`.
+  The same goes for `escalateTo` and `compensateWith` (a tool id). The
+  builder refuses a check with neither.
+  - In an agent turn, a failed `halt` guardrail fails the turn
+    (`guardrail-violation`), and the answer is not stored.
+  - Any other action reports the failure in the turn result's `violations`,
+    and the turn completes.
+  - In 0.1 the runtime acts only on `halt`: `retry`, `escalate` and
+    `compensate` are recorded on the violation, with no second attempt,
+    escalation or compensating call.
+- **`severity`:** `info`, `warn`, `error` (default) or `critical`. It's
+  independent of the action: dashboards group by severity, and execution
+  follows the action.
+- **`set("scope", Map("when" -> "runtime-only"))`:** when the guardrail
+  applies: `always`, `ci-only` or `runtime-only`, narrowed by `agents`,
+  `flows` and `tenants` lists.
+- **`name`:** a display name. **`checkId`:** defaults to the id.
+- **`kind`:** `zero-llm`, the default: a check over the trace, which is what
+  a pack writes.
+- `set("sandbox" | "limits" | "network", …)` are recorded in the index.
+
+## Testing
+
+`evaluate` runs the check with the config as given, with no schema check
+and no defaults. An async check is awaited.
+
+```scala
+// src/test/scala/acme/CitationsSuite.scala
+package acme
+
+import acme.guardrails.Citations
+import com.kindgi.pack.RunTrace
+import java.util.{List => JList, Map => JMap}
+
+class CitationsSuite extends munit.FunSuite {
+  test("no lookups fails") {
+    val trace = new RunTrace(JMap.of("output", "As held in Smith v. Jones…"))
+    assert(!Citations.noFabricatedQuotes.evaluate(Citations.Config(1), trace).passed)
+  }
+
+  test("enough lookups pass") {
+    val lookup = JMap.of("toolName", "acme.verify-citation", "arguments", JMap.of())
+    val trace = new RunTrace(JMap.of("toolCalls", JList.of(lookup, lookup)))
+    assert(Citations.noFabricatedQuotes.evaluate(Citations.Config(2), trace).passed)
+  }
+}
+```
+
+`new RunTrace(map)` takes the trace as the runtime sends it: a Java map,
+camelCase keys included.
+
+## Wiring onto an agent
+
+```scala
+Agent("acme.brief-writer")
+  // …
+  .guardrail(Citations.noFabricatedQuotes)
+```
+
+Pass the `Guardrail`, or its id (`.guardrail("acme.no-fabricated-quotes")`).
+`kindgi dev` registers the pack's guardrails. An agent that names an id with
+no registered guardrail fails the turn before the model is called
+(`Agent "…" references guardrails not in the registry: <id>`).
+
+## Common mistakes
+
+1. **A config parameter with no default and no value.** Without
+   `set("config", …)`, the check runs with `{}`. Give the parameter a
+   default, or the guardrail its values.
+2. **`set("config", …)` keyed by Scala names that differ from the wire.**
+   It's keyed by the case class's Jackson names.
+3. **No `onViolation` or `action`.** The builder refuses the check.
+4. **Expecting another attempt.** `halt` stops the turn, and in 0.1 `retry`
+   doesn't run the turn again: it's only recorded.
+5. **Calling a model from the check.** That isn't available: keep checks
+   pure.
+6. **Throwing for a broken rule.** Return `CheckResult.fail(…)`. An
+   exception is an evaluation error, not a violation.
+7. **`trace.output.length` without a null check.** `output` is `null` when
+   the turn produced no text: `Option(trace.output).getOrElse("")`.
+8. **A guardrail as a `def` or a `lazy val`.** It's a file error: make it a
+   `val`.
+
+## When the framework itself is the problem
+
+If the bug is in Kindgi, kindgi-pack or the Scala layer (a trace field
+missing, a misleading error) and not in the check, load
+`kindgi-framework-feedback` and file it with `./kindgiw feedback write`.

package/skills/kindgi-scala-authoring-tools/SKILL.md

@@ -0,0 +1,302 @@
+---
+name: kindgi-scala-authoring-tools
+description: >
+  Covers writing tools for a Kindgi pack in Scala (`kindgi-pack-scala`,
+  `com.kindgi.pack.scaladsl`): `Tool[Input, Output](id)` as a `val` of an
+  object named like its file, schemas from case classes (Option, defaults,
+  collections, Jakarta constraints) or `Tool.json` with maps, `handler` and
+  `handlerAsync` (a Future), `ToolContext` and cancellation, secrets
+  (`needsSpec`) and configuration, errors, `readOnly` and effects, munit
+  tests with `tool.call`, and wiring a tool onto an agent. Load this
+  whenever you are authoring or editing code in a Scala pack's tools
+  packages (a pack whose `kindgi.config.json` says `"language": "scala"`),
+  defining a tool, or wiring one onto an agent. Scala agents are covered by
+  kindgi-scala-authoring-agents, getting started by
+  kindgi-scala-getting-started.
+type: core
+library: "kindgi-pack-scala"
+version: "0.1.0"
+sdk_version: "0.0.0"
+pack_languages: [scala]
+sources:
+  - sdks/scala/README.md
+  - sdks/scala/kindgi-pack-scala/src/main/scala/com/kindgi/pack/scaladsl/Tool.scala
+  - sdks/java/kindgi-pack/README.md
+---
+
+# Authoring Kindgi tools in Scala
+
+> **Running `kindgi`:** the pack pins its CLI (`"cli"` in
+> `kindgi.config.json`), and `./kindgiw` runs that version, so every
+> `kindgi <command>` below runs as `./kindgiw <command>`. sbt is the one on
+> your `PATH`.
+>
+> Scala support is in preview: tested and supported, but the API may still
+> change in 0.1.6 without the usual deprecation period.
+
+A **tool** is a unit of work an agent (or a flow step) calls: typed input,
+typed output, your code in between. In a Scala pack it is a `val` of type
+`Tool[I, O]` in an object named like its file (`VerifyCitation.scala` holds
+`object VerifyCitation`), in a `tools` package
+(`src/main/scala/**/tools/**/*.scala`; in an app, `**/kindgi/tools/**`).
+Kindgi runs it in the pack's own JVM (the pack service) and calls it over
+HTTP. The model sees its id, description and input schema.
+
+Before writing one, establish what it should **do**: what it computes or
+fetches, what the caller provides, what it returns. "Add a tool" is a
+conversation opener. The pack's sample tools prove the runtime works; they
+are not the shape to copy unless the user asks.
+
+## A tool
+
+```scala
+// src/main/scala/acme/tools/VerifyCitation.scala
+package acme.tools
+
+import com.kindgi.pack.scaladsl._
+import jakarta.validation.constraints.{Pattern, Size}
+
+/** acme.verify-citation: checks a legal citation against the citator. */
+object VerifyCitation {
+  final case class Input(
+      @Size(min = 1) citation: String,
+      @Pattern(regexp = "^(US|UK|EU)$") jurisdiction: String)
+
+  final case class Output(found: Boolean, canonicalCite: Option[String])
+
+  val tool: Tool[Input, Output] = Tool[Input, Output]("acme.verify-citation")
+    .description("Verifies a legal citation against the citator; returns whether it resolves and its canonical form.")
+    .readOnly
+    .set("needsSpec", Map("secrets" -> Map("CITATOR_KEY" -> Map("type" -> "string", "minLength" -> 20))))
+    .handler((in, ctx) =>
+      verify(in, String.valueOf(ctx.secrets.get("CITATOR_KEY")), sys.env.getOrElse("CITATOR_URL", "")))
+
+  /** The tool's work, with what it reads from its context and the environment passed in: a test calls it. */
+  def verify(in: Input, key: String, citatorUrl: String): Output = {
+    val hit = Citator.lookup(citatorUrl, key, in.citation, in.jurisdiction)
+    Output(hit.isDefined, hit)
+  }
+}
+```
+
+```scala
+// src/main/scala/acme/tools/Citator.scala
+package acme.tools
+
+import java.net.URI
+import java.net.URLEncoder
+import java.net.http.{HttpClient, HttpRequest, HttpResponse}
+import java.nio.charset.StandardCharsets
+
+/** The citator's API: an object with no tools in it is a helper, not a primitive. */
+object Citator {
+  private val http = HttpClient.newHttpClient()
+
+  def lookup(baseUrl: String, key: String, citation: String, jurisdiction: String): Option[String] = {
+    val query = s"q=${URLEncoder.encode(citation, StandardCharsets.UTF_8)}&j=$jurisdiction"
+    val request = HttpRequest.newBuilder(URI.create(s"$baseUrl/lookup?$query"))
+      .header("Authorization", s"Bearer $key")
+      .build()
+    val response = http.send(request, HttpResponse.BodyHandlers.ofString())
+    if (response.statusCode() == 200) Some(response.body()) else None
+  }
+}
+```
+
+- **Where it lives:** a `val` of the object named like the file. The
+  indexer reads the object's vals, and only the primitives that object
+  defined. A tool defined as a `def` or a `lazy val` is a file error that
+  says to make it a `val`: the indexer can't read one without running it.
+  An object with no tools in it is a helper. So is a file with no object
+  (a case class, a trait).
+- **Id:** `<pack-id>.<tool-name>`, kebab-case, dot-namespaced.
+- **Description:** what it does and returns. The model reads it to decide
+  when to call the tool. It isn't enforced, so never leave it out.
+- **Version:** the pack's (`pack.version`), or `.version("1.2.0")` (an exact
+  semver).
+- **Schemas:** from the case classes `Tool[Input, Output]` names. A
+  parameter is a property, by its Jackson name
+  (`@JsonProperty("canonical_cite")` renames one). The input must be an
+  **object**: a model calls a tool with an object of arguments.
+
+  | In Scala | In the schema |
+  |---|---|
+  | `String`, `Int`/`Long`, `Double`/`BigDecimal`, `Boolean`; `BigInt` | `string`, `integer`, `number`, `boolean`; `integer` |
+  | `Option[T]` | not required; `null` allowed |
+  | a parameter's default (`greeting: String = "Hello"`) | `default`, not required; the service fills it in |
+  | `Seq[T]`, `List[T]`, `Vector[T]`; `Set[T]` | `array`; `array` with `uniqueItems` |
+  | `Map[String, T]` | `object` with `additionalProperties` |
+  | a Scala 3 simple enum (`enum Scale { case C, F }`) | `string`, `enum` of its case names |
+  | `@Size`, `@Min`, `@Max`, `@Pattern`, `@Email`, `@NotBlank`, `@Positive`, … | the matching keywords |
+
+  **In Scala 3, name a Java annotation's arguments:** `@Min(value = 0)`, not
+  `@Min(0)`. Scala 3 passes a positional argument to the wrong element.
+  When a type can't say it, `Tool.json(id).inputSchema(Map(…))` takes the
+  schema as Scala maps, and the handler gets a `Map[String, Any]`.
+- **Handler:** `(in, ctx) => output`. It may throw. It runs on a thread of
+  its own, so blocking I/O is fine. `handlerAsync((in, ctx) => future)`
+  returns a `Future[O]`, and the service awaits it.
+- **Validation:** before the handler runs, the input is checked against the
+  schema (its defaults filled in). Then what the handler returns is checked
+  against the output schema. A bad input comes back as
+  `input-validation-failed`, naming the field (a bad output as
+  `output-validation-failed`). The agent's `toolErrors` policy decides
+  whether the model gets to fix the call.
+
+## `ToolContext`
+
+- `ctx.tenantId`: the tenant the call is for. Key per-tenant state by it.
+- `ctx.runId`: the run (an agent turn or a flow step) the call belongs to.
+- `ctx.requestId`: this call, such as the model's tool-call id. Useful for
+  logs and idempotency keys.
+- `ctx.projectId`, `ctx.orgId`: the run's project, and its org (`null` when
+  it has none). The runtime sets them from the run, never from the input.
+  To check an id the input names, compare it with these.
+- `ctx.cancellation` fires when the call's deadline passes (120 s by
+  default) or the caller goes away. A blocking handler's thread is
+  interrupted too. A loop checks `ctx.cancellation.isCancelled`. A `Future`
+  has no way to stop, so stop the work behind it with
+  `ctx.cancellation.onCancel(() => …)`.
+- `ctx.secrets`: the secrets the tool declares (below), as a Java map.
+  Printing the context shows their names, never their values.
+- `ctx.env`, `ctx.config`: **reserved, empty today**.
+
+## Configuration and secrets
+
+A secret that belongs to the tenant, such as an API key a customer gives
+you, is declared with `set("needsSpec", …)` and read from `ctx.secrets`, as
+above. The runtime resolves every declared secret on every call, for the
+call's tenant, in its env (`KINDGI_ENV`; under `kindgi dev`, `local`: the
+pack's `.env` and `.env.local`). It checks each against its schema, and fails
+the call, naming the secret, when one is missing or doesn't match. Every
+declared secret is required.
+
+Everything else comes from the process environment: `sys.env("CITATOR_URL")`.
+Under `kindgi dev`, the pack service gets the pack's `.env` and `.env.local`,
+and restarts when they change. Nothing else from your shell reaches it
+except `PATH`, `HOME` and `TMPDIR`; `SBT_OPTS` reaches sbt only. Put a secret
+there by hand, or with `./kindgiw secrets set NAME --env=local --scope=tenant`
+(a no-echo prompt), and keep the env files out of git. A deployed service
+names the variables it needs in `kindgi.config.json`:
+`"env": {"required": ["DATABASE_URL"], "optional": ["SENTRY_DSN"]}`. Without
+a required one it isn't ready. `KINDGI_*` names are Kindgi's own and never
+reach pack code.
+
+## Errors and output
+
+- Throw for a failure, or fail the `Future`: the call fails with
+  `handler-throw` and the exception's message. In an agent turn, the model
+  sees the failure only when the agent's `toolErrors` policy includes
+  `tool-error`, so retrying must be safe for that tool.
+- What the handler logs goes to the pack service's output (`kindgi dev`
+  shows it as `[pack] …`), never into a result.
+
+## Other declarations
+
+**`readOnly`** declares a tool that changes nothing outside itself (a lookup,
+a search, a calculation): it's `mutating(false)`. A dry run
+(`./kindgiw runs start --dry-run`) runs it. Leave it off for anything that
+writes, sends, charges or deletes: such a tool stops a dry run. It's also
+the tool's approval default: an agent that turns approval gates on
+(`conversationPolicy.hitl`) asks before any tool that isn't read-only on its
+first use.
+
+`effect(kind, resource)` declares a side effect, such as
+`.effect("writes", "db:ledger")`. A dry run also stops at a tool with a
+`writes`, `deletes`, `spawns-run`, `emits-event` or `external-side-effect`
+effect. `set(field, value)` sets the index entry's other fields (`needs`,
+`needsSpec`, `sandbox`, `limits`, `network`), with Scala maps and lists. They
+are recorded for policy and review, so declare what the tool really does.
+
+There is no HTTP-tool form (TypeScript's `kind: 'http'`). A tool that calls
+an HTTP API is a handler with `java.net.http.HttpClient`, as above.
+
+## Testing
+
+`tool.call(input, ctx)` runs the handler with the input as given (no schema
+check). `ToolContext.forTest()` is a context with a test tenant and run and
+nothing else. A handler that reads the environment and calls a service is
+tested through the method it calls, with a stub server:
+
+```scala
+// src/test/scala/acme/VerifyCitationSuite.scala
+package acme
+
+import acme.tools.VerifyCitation
+import com.sun.net.httpserver.HttpServer
+import java.net.InetSocketAddress
+
+class VerifyCitationSuite extends munit.FunSuite {
+  test("an unknown citation is not found") {
+    val citator = HttpServer.create(new InetSocketAddress("127.0.0.1", 0), 0)
+    citator.createContext("/lookup", exchange => {
+      exchange.sendResponseHeaders(404, -1)
+      exchange.close()
+    })
+    citator.start()
+    try {
+      val url = s"http://127.0.0.1:${citator.getAddress.getPort}"
+      assert(!VerifyCitation.verify(VerifyCitation.Input("1 U.S. 1", "US"), "test-key", url).found)
+    } finally citator.stop(0)
+  }
+}
+```
+
+`sbt test` runs the tests (anything under `src/test/` is never indexed). To
+see the schemas Kindgi derives:
+
+```sh
+java -cp "$(sbt -batch -error 'export Runtime/fullClasspath')" com.kindgi.pack.Main index --pack-dir .
+```
+
+## Wiring the tool onto an agent
+
+Pass the `Tool`, which pins that tool's version:
+
+```scala
+Agent("acme.brief-writer")
+  // …
+  .tool(VerifyCitation.tool)
+```
+
+A tool of another pack is `.tool("other.lookup", "^1.0.0")`: its id and a
+semver **range**, and the highest active version matching it is picked at
+turn start. In a flow, `toolNode("verify", VerifyCitation.tool)` runs it.
+
+## Iterating
+
+Save the file. `kindgi dev` recompiles through sbt's server, and the next
+call runs the new code. A compile error is reported as `file:line:col`, and
+the last good code keeps serving. Bump the version when callers' contract
+changes (a removed field, a narrower type), not on every save.
+
+## Common mistakes
+
+1. **Copying the sample tool's shape without asking what the tool should do.**
+2. **A tool as a `def` or a `lazy val`.** It's a file error: make it a `val`.
+3. **An object not named like its file.** The indexer reads `Greet.scala`'s
+   `object Greet`, and a file without one is an error.
+4. **No description.** The model can't tell when to call the tool.
+5. **`@Min(0)` in Scala 3.** Name the argument: `@Min(value = 0)`.
+6. **A primitive inside a type parameter** (`Seq[Int]`, `Option[Long]`). On
+   the JVM it's `Object`, so the schema allows any JSON value there. Use a
+   case class (`Seq[Item]`), or say the schema with `Tool.json`.
+7. **Reading `ctx.env` or `ctx.config`, or an undeclared secret.** The first
+   two are empty, and `ctx.secrets` holds only what `needsSpec` declares.
+   Use `sys.env` for the rest.
+8. **A library the tool uses as `% Test` or `% Provided`.** It works under
+   `kindgi dev` and fails in the image, which ships the runtime classpath
+   only.
+9. **A read-only tool without `readOnly`.** A dry run stops at it, and an
+   approval gate asks before it on first use.
+10. **`readOnly` on a tool that writes.** A dry run then runs it for real.
+11. **A jackson-module-scala that doesn't match your app's
+    `jackson-databind` minor version.** It refuses to load: depend on the
+    matching one.
+
+## When the framework itself is the problem
+
+If the bug is in Kindgi, kindgi-pack or the Scala layer (a schema derived
+wrong, a misleading error, the pack service misbehaving) and not in the
+tool's code, load `kindgi-framework-feedback` and file it with
+`./kindgiw feedback write`.