jev-recipes 0.6.1 → 0.7.0

package/README.md

@@ -11,7 +11,7 @@
 
 <!-- BEGIN GENERATED: summary -->
 
-236 focused recipes for JavaScript and TypeScript. Route messages, check evidence, and label model responses with a function call.
+243 focused recipes for JavaScript and TypeScript. Route messages, check evidence, and label model responses with a function call.
 
 <!-- END GENERATED: summary -->
 
@@ -117,16 +117,20 @@ The TypeSafe SDK handles API calls and typed answers. Recipes add the instructio
 
 ## Find your recipe
 
-| Your task                                              | Start with                                                                                                   |
-| ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------ |
-| Send a request to the right team                       | [`route`](https://github.com/agencyenterprise/jev-recipes/blob/main/recipes/route/README.md)                 |
-| Find useful passages                                   | [`rerank`](https://github.com/agencyenterprise/jev-recipes/blob/main/recipes/rerank/README.md)               |
-| Check whether the evidence is enough to answer         | [`answerability`](https://github.com/agencyenterprise/jev-recipes/blob/main/recipes/answerability/README.md) |
-| Check claims against supplied evidence                 | [`verify`](https://github.com/agencyenterprise/jev-recipes/blob/main/recipes/verify/README.md)               |
-| Find missing or ambiguous requirements                 | [`clarify`](https://github.com/agencyenterprise/jev-recipes/blob/main/recipes/clarify/README.md)             |
-| Label a response's stance toward a claim               | [`claim-stance`](https://github.com/agencyenterprise/jev-recipes/blob/main/recipes/claim-stance/README.md)   |
-| Choose a move from available game actions              | [`choose-action`](https://github.com/agencyenterprise/jev-recipes/blob/main/recipes/choose-action/README.md) |
-| Choose a checkers move from your board and legal moves | [`checkers-move`](https://github.com/agencyenterprise/jev-recipes/blob/main/recipes/checkers-move/README.md) |
+| Your task                                              | Start with                                                                                                       |
+| ------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------- |
+| Send a request to the right team                       | [`route`](https://github.com/agencyenterprise/jev-recipes/blob/main/recipes/route/README.md)                     |
+| Find useful passages                                   | [`rerank`](https://github.com/agencyenterprise/jev-recipes/blob/main/recipes/rerank/README.md)                   |
+| Check whether the evidence is enough to answer         | [`answerability`](https://github.com/agencyenterprise/jev-recipes/blob/main/recipes/answerability/README.md)     |
+| Check claims against supplied evidence                 | [`verify`](https://github.com/agencyenterprise/jev-recipes/blob/main/recipes/verify/README.md)                   |
+| Find missing or ambiguous requirements                 | [`clarify`](https://github.com/agencyenterprise/jev-recipes/blob/main/recipes/clarify/README.md)                 |
+| Label a response's stance toward a claim               | [`claim-stance`](https://github.com/agencyenterprise/jev-recipes/blob/main/recipes/claim-stance/README.md)       |
+| Choose a move from available game actions              | [`choose-action`](https://github.com/agencyenterprise/jev-recipes/blob/main/recipes/choose-action/README.md)     |
+| Choose a checkers move from your board and legal moves | [`checkers-move`](https://github.com/agencyenterprise/jev-recipes/blob/main/recipes/checkers-move/README.md)     |
+| Allow, ask, or deny an agent's tool call               | [`tool-call-gate`](https://github.com/agencyenterprise/jev-recipes/blob/main/recipes/tool-call-gate/README.md)   |
+| Check an agent's "done" against evidence               | [`completion-gate`](https://github.com/agencyenterprise/jev-recipes/blob/main/recipes/completion-gate/README.md) |
+| Pick a model tier and effort per request               | [`model-route`](https://github.com/agencyenterprise/jev-recipes/blob/main/recipes/model-route/README.md)         |
+| Route a backlog of messages in a few calls             | [`route-many`](https://github.com/agencyenterprise/jev-recipes/blob/main/recipes/route-many/README.md)           |
 
 Search, inspect inputs, and try saved results without a key:
 
@@ -140,6 +144,8 @@ npx jev-recipes demo answerability
 
 For games, use [game-action](https://github.com/agencyenterprise/jev-recipes/blob/main/recipes/game-action/README.md) with your existing JSON state and actions. It returns the original selected action, preserving your game IDs. [checkers-move](https://github.com/agencyenterprise/jev-recipes/blob/main/recipes/checkers-move/README.md) accepts a structured checkers board and legal moves; the [checkers example](https://github.com/agencyenterprise/jev-recipes/blob/main/examples/checkers/README.md) shows how to run its visual demo locally.
 
+For agent harnesses, browse [Agent harness](https://github.com/agencyenterprise/jev-recipes/blob/main/recipes/README.md#agent-harness) for the decisions inside an agent loop: `tool-call-gate` before a tool runs, `model-route` per turn, `context-prune` before compaction, `wake-gate` for paused agents, `diff-hazards` before a commit, and `completion-gate` before accepting a result. Search with `npx jev-recipes list harness`.
+
 For psychology, browse [Psychology & behavior](https://github.com/agencyenterprise/jev-recipes/blob/main/recipes/README.md#psychology--behavior) for gain/loss framing, causal explanations, stated motivation, and related wording annotations. Search with `npx jev-recipes list psychology`.
 
 For music, browse [Music & sound](https://github.com/agencyenterprise/jev-recipes/blob/main/recipes/README.md#music--sound) for generation-loop decisions such as `next-note` and `phrase-complete`, listener steering such as `listener-request-kind`, and instrument or music-software tooling. Pass musical state as text or JSON. Search with `npx jev-recipes list music`.
@@ -179,6 +185,46 @@ Batch recipes expose their own summaries, such as `verify.allSupported` and its
 
 Pass `{ client, model, signal }` as the optional second argument to configure a call. [Shared behavior and limits](https://github.com/agencyenterprise/jev-recipes/blob/main/recipes/README.md#shared-options-and-behavior) covers configuration, input limits, and uncertainty.
 
+## Batch many inputs
+
+A Jev request evaluates every question in parallel, so several inputs that share the same decision can travel together. `route-many` routes up to 500 requests in batches of 20 by default, making one call per batch instead of one per request:
+
+```js
+import { routeMany } from 'jev-recipes/route-many';
+
+const result = await routeMany({
+  requests: tickets.map((ticket) => ({ id: ticket.id, text: ticket.body })),
+  routes: { billing: 'Payments and refunds', technical: 'Errors and outages' },
+  batchSize: 20,
+});
+
+for (const item of result.items) {
+  if (item.status === 'ready') assign(item.id, item.route);
+  else queueForReview(item.id, item.suggestedRoute);
+}
+console.log(`${result.requestsMade} calls for ${result.requestCount} tickets`);
+```
+
+Accuracy can drop as batches grow. Measure on your own labeled data and tune `batchSize`; the [eval harness](https://github.com/agencyenterprise/jev-recipes/blob/main/CONTRIBUTING.md#model-evaluation) reports calibration per threshold.
+
+## Use a local or alternative decision model
+
+Recipes talk to any server that implements the TypeSafe `systemOne` wire format. Point the SDK client at it with `baseURL`, or set `TYPESAFE_BASE_URL` in the environment, and pass the client to any recipe:
+
+```js
+import { createClient } from 'jev-recipes';
+import { route } from 'jev-recipes/route';
+
+const client = createClient({
+  baseURL: 'http://localhost:11434', // a self-hosted, TypeSafe-compatible server
+  apiKey: 'local',
+});
+
+const result = await route({ request, routes }, { client, model: 'my-local-model' });
+```
+
+The `model` option selects a model name on that server. Recipes validate every response against the same schemas, so a server that returns malformed probabilities fails loudly rather than silently. The tooling tests exercise this path against a local HTTP server.
+
 ## Verification and scope
 
 The [CI workflow](https://github.com/agencyenterprise/jev-recipes/actions/workflows/ci.yml) runs on Node.js 22 and 24. `make ci` checks types, formatting, generated-file consistency, recipe test coverage, tooling, and the installable package.

package/dist/catalog/generated/details/completion-gate.json

@@ -0,0 +1,110 @@
+{
+  "inputSchema": {
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "type": "object",
+    "properties": {
+      "task": { "type": "string" },
+      "report": { "type": "string" },
+      "evidence": { "type": "string" },
+      "minConfidence": { "type": "number", "minimum": 0, "maximum": 1 }
+    },
+    "required": ["task", "report"]
+  },
+  "resultSchema": {
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "type": "object",
+    "properties": {
+      "model": { "type": "string" },
+      "usage": {
+        "type": "object",
+        "properties": {
+          "input_tokens": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 },
+          "output_tokens": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }
+        },
+        "required": ["input_tokens", "output_tokens"],
+        "additionalProperties": false
+      },
+      "status": { "type": "string", "enum": ["ready", "review"] },
+      "verdict": { "type": "string", "enum": ["complete", "incomplete", "unverified", "unclear"] },
+      "confidence": { "type": "number", "minimum": 0, "maximum": 1 },
+      "probabilities": {
+        "type": "object",
+        "propertyNames": {
+          "type": "string",
+          "enum": ["complete", "incomplete", "unverified", "unclear"]
+        },
+        "additionalProperties": { "type": "number", "minimum": 0, "maximum": 1 },
+        "required": ["complete", "incomplete", "unverified", "unclear"]
+      },
+      "signals": {
+        "type": "object",
+        "properties": {
+          "claimsWithoutEvidence": {
+            "type": "object",
+            "properties": {
+              "status": { "type": "string", "enum": ["ready", "review"] },
+              "verdict": { "type": "string", "enum": ["present", "absent"] },
+              "probability": { "type": "number", "minimum": 0, "maximum": 1 },
+              "confidence": { "type": "number", "minimum": 0, "maximum": 1 }
+            },
+            "required": ["status", "verdict", "probability", "confidence"],
+            "additionalProperties": false
+          },
+          "scopeNarrowed": {
+            "type": "object",
+            "properties": {
+              "status": { "type": "string", "enum": ["ready", "review"] },
+              "verdict": { "type": "string", "enum": ["present", "absent"] },
+              "probability": { "type": "number", "minimum": 0, "maximum": 1 },
+              "confidence": { "type": "number", "minimum": 0, "maximum": 1 }
+            },
+            "required": ["status", "verdict", "probability", "confidence"],
+            "additionalProperties": false
+          },
+          "openQuestions": {
+            "type": "object",
+            "properties": {
+              "status": { "type": "string", "enum": ["ready", "review"] },
+              "verdict": { "type": "string", "enum": ["present", "absent"] },
+              "probability": { "type": "number", "minimum": 0, "maximum": 1 },
+              "confidence": { "type": "number", "minimum": 0, "maximum": 1 }
+            },
+            "required": ["status", "verdict", "probability", "confidence"],
+            "additionalProperties": false
+          },
+          "unresolvedErrors": {
+            "type": "object",
+            "properties": {
+              "status": { "type": "string", "enum": ["ready", "review"] },
+              "verdict": { "type": "string", "enum": ["present", "absent"] },
+              "probability": { "type": "number", "minimum": 0, "maximum": 1 },
+              "confidence": { "type": "number", "minimum": 0, "maximum": 1 }
+            },
+            "required": ["status", "verdict", "probability", "confidence"],
+            "additionalProperties": false
+          }
+        },
+        "required": ["claimsWithoutEvidence", "scopeNarrowed", "openQuestions", "unresolvedErrors"],
+        "additionalProperties": false
+      },
+      "detected": {
+        "type": "array",
+        "items": {
+          "type": "string",
+          "enum": ["claimsWithoutEvidence", "scopeNarrowed", "openQuestions", "unresolvedErrors"]
+        }
+      }
+    },
+    "required": [
+      "model",
+      "usage",
+      "status",
+      "verdict",
+      "confidence",
+      "probabilities",
+      "signals",
+      "detected"
+    ],
+    "additionalProperties": false
+  }
+}

package/dist/catalog/generated/details/context-prune.json

@@ -0,0 +1,59 @@
+{
+  "inputSchema": {
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "type": "object",
+    "properties": {
+      "objective": { "type": "string" },
+      "items": {
+        "minItems": 1,
+        "maxItems": 50,
+        "type": "array",
+        "items": {
+          "type": "object",
+          "properties": { "id": { "type": "string" }, "text": { "type": "string" } },
+          "required": ["id", "text"]
+        }
+      },
+      "recent": { "type": "string" },
+      "minConfidence": { "type": "number", "minimum": 0, "maximum": 1 }
+    },
+    "required": ["objective", "items"]
+  },
+  "resultSchema": {
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "type": "object",
+    "properties": {
+      "model": { "type": "string" },
+      "usage": {
+        "type": "object",
+        "properties": {
+          "input_tokens": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 },
+          "output_tokens": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }
+        },
+        "required": ["input_tokens", "output_tokens"],
+        "additionalProperties": false
+      },
+      "status": { "type": "string", "enum": ["ready", "review"] },
+      "items": {
+        "type": "array",
+        "items": {
+          "type": "object",
+          "properties": {
+            "id": { "type": "string" },
+            "status": { "type": "string", "enum": ["ready", "review"] },
+            "verdict": { "type": "string", "enum": ["keep", "drop"] },
+            "probability": { "type": "number", "minimum": 0, "maximum": 1 },
+            "confidence": { "type": "number", "minimum": 0, "maximum": 1 }
+          },
+          "required": ["id", "status", "verdict", "probability", "confidence"],
+          "additionalProperties": false
+        }
+      },
+      "keep": { "type": "array", "items": { "type": "string" } },
+      "drop": { "type": "array", "items": { "type": "string" } },
+      "evaluated": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }
+    },
+    "required": ["model", "usage", "status", "items", "keep", "drop", "evaluated"],
+    "additionalProperties": false
+  }
+}

package/dist/catalog/generated/details/diff-hazards.json

@@ -0,0 +1,112 @@
+{
+  "inputSchema": {
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "type": "object",
+    "properties": {
+      "diff": { "type": "string" },
+      "context": { "type": "string" },
+      "minConfidence": { "type": "number", "minimum": 0, "maximum": 1 }
+    },
+    "required": ["diff"]
+  },
+  "resultSchema": {
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "type": "object",
+    "properties": {
+      "model": { "type": "string" },
+      "usage": {
+        "type": "object",
+        "properties": {
+          "input_tokens": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 },
+          "output_tokens": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }
+        },
+        "required": ["input_tokens", "output_tokens"],
+        "additionalProperties": false
+      },
+      "status": { "type": "string", "enum": ["ready", "review"] },
+      "detected": {
+        "type": "array",
+        "items": {
+          "type": "string",
+          "enum": [
+            "secretLeak",
+            "destructiveCommand",
+            "debugLeftover",
+            "testsWeakened",
+            "dependencyChange"
+          ]
+        }
+      },
+      "labels": {
+        "type": "object",
+        "properties": {
+          "secretLeak": {
+            "type": "object",
+            "properties": {
+              "status": { "type": "string", "enum": ["ready", "review"] },
+              "verdict": { "type": "string", "enum": ["present", "absent"] },
+              "probability": { "type": "number", "minimum": 0, "maximum": 1 },
+              "confidence": { "type": "number", "minimum": 0, "maximum": 1 }
+            },
+            "required": ["status", "verdict", "probability", "confidence"],
+            "additionalProperties": false
+          },
+          "destructiveCommand": {
+            "type": "object",
+            "properties": {
+              "status": { "type": "string", "enum": ["ready", "review"] },
+              "verdict": { "type": "string", "enum": ["present", "absent"] },
+              "probability": { "type": "number", "minimum": 0, "maximum": 1 },
+              "confidence": { "type": "number", "minimum": 0, "maximum": 1 }
+            },
+            "required": ["status", "verdict", "probability", "confidence"],
+            "additionalProperties": false
+          },
+          "debugLeftover": {
+            "type": "object",
+            "properties": {
+              "status": { "type": "string", "enum": ["ready", "review"] },
+              "verdict": { "type": "string", "enum": ["present", "absent"] },
+              "probability": { "type": "number", "minimum": 0, "maximum": 1 },
+              "confidence": { "type": "number", "minimum": 0, "maximum": 1 }
+            },
+            "required": ["status", "verdict", "probability", "confidence"],
+            "additionalProperties": false
+          },
+          "testsWeakened": {
+            "type": "object",
+            "properties": {
+              "status": { "type": "string", "enum": ["ready", "review"] },
+              "verdict": { "type": "string", "enum": ["present", "absent"] },
+              "probability": { "type": "number", "minimum": 0, "maximum": 1 },
+              "confidence": { "type": "number", "minimum": 0, "maximum": 1 }
+            },
+            "required": ["status", "verdict", "probability", "confidence"],
+            "additionalProperties": false
+          },
+          "dependencyChange": {
+            "type": "object",
+            "properties": {
+              "status": { "type": "string", "enum": ["ready", "review"] },
+              "verdict": { "type": "string", "enum": ["present", "absent"] },
+              "probability": { "type": "number", "minimum": 0, "maximum": 1 },
+              "confidence": { "type": "number", "minimum": 0, "maximum": 1 }
+            },
+            "required": ["status", "verdict", "probability", "confidence"],
+            "additionalProperties": false
+          }
+        },
+        "required": [
+          "secretLeak",
+          "destructiveCommand",
+          "debugLeftover",
+          "testsWeakened",
+          "dependencyChange"
+        ],
+        "additionalProperties": false
+      }
+    },
+    "required": ["model", "usage", "status", "detected", "labels"],
+    "additionalProperties": false
+  }
+}

package/dist/catalog/generated/details/model-route.json

@@ -0,0 +1,82 @@
+{
+  "inputSchema": {
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "type": "object",
+    "properties": {
+      "request": { "type": "string" },
+      "models": {
+        "minItems": 1,
+        "maxItems": 50,
+        "type": "array",
+        "items": {
+          "type": "object",
+          "properties": { "id": { "type": "string" }, "text": { "type": "string" } },
+          "required": ["id", "text"]
+        }
+      },
+      "context": { "type": "string" },
+      "minConfidence": { "type": "number", "minimum": 0, "maximum": 1 }
+    },
+    "required": ["request", "models"]
+  },
+  "resultSchema": {
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "type": "object",
+    "properties": {
+      "model": { "type": "string" },
+      "usage": {
+        "type": "object",
+        "properties": {
+          "input_tokens": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 },
+          "output_tokens": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }
+        },
+        "required": ["input_tokens", "output_tokens"],
+        "additionalProperties": false
+      },
+      "status": { "type": "string", "enum": ["ready", "review"] },
+      "verdict": { "type": "string", "enum": ["matched", "none", "ambiguous"] },
+      "selection": { "type": ["string", "null"] },
+      "suggestedSelection": { "type": ["string", "null"] },
+      "confidence": { "type": "number", "minimum": 0, "maximum": 1 },
+      "probabilities": {
+        "type": "object",
+        "properties": {
+          "candidates": {
+            "type": "object",
+            "propertyNames": { "type": "string" },
+            "additionalProperties": { "type": "number", "minimum": 0, "maximum": 1 }
+          },
+          "none": { "type": "number", "minimum": 0, "maximum": 1 },
+          "ambiguous": { "type": "number", "minimum": 0, "maximum": 1 }
+        },
+        "required": ["candidates", "none", "ambiguous"],
+        "additionalProperties": false
+      },
+      "effort": { "type": "string", "enum": ["low", "medium", "high"] },
+      "effortLevel": { "type": "integer", "minimum": 0, "maximum": 2 },
+      "effortScore": { "type": "number", "minimum": 0, "maximum": 2 },
+      "effortConfidence": { "type": "number", "minimum": 0, "maximum": 1 },
+      "effortProbabilities": {
+        "type": "object",
+        "propertyNames": { "type": "string" },
+        "additionalProperties": { "type": "number", "minimum": 0, "maximum": 1 }
+      }
+    },
+    "required": [
+      "model",
+      "usage",
+      "status",
+      "verdict",
+      "selection",
+      "suggestedSelection",
+      "confidence",
+      "probabilities",
+      "effort",
+      "effortLevel",
+      "effortScore",
+      "effortConfidence",
+      "effortProbabilities"
+    ],
+    "additionalProperties": false
+  }
+}

package/dist/catalog/generated/details/route-many.json

@@ -0,0 +1,68 @@
+{
+  "inputSchema": {
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "type": "object",
+    "properties": {
+      "requests": {
+        "minItems": 1,
+        "maxItems": 500,
+        "type": "array",
+        "items": {
+          "type": "object",
+          "properties": { "id": { "type": "string" }, "text": { "type": "string" } },
+          "required": ["id", "text"]
+        }
+      },
+      "routes": {
+        "type": "object",
+        "propertyNames": { "type": "string" },
+        "additionalProperties": { "type": "string" }
+      },
+      "batchSize": { "type": "integer", "minimum": 1, "maximum": 50 },
+      "minConfidence": { "type": "number", "minimum": 0, "maximum": 1 }
+    },
+    "required": ["requests", "routes"]
+  },
+  "resultSchema": {
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "type": "object",
+    "properties": {
+      "model": { "type": "string" },
+      "usage": {
+        "type": "object",
+        "properties": {
+          "input_tokens": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 },
+          "output_tokens": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }
+        },
+        "required": ["input_tokens", "output_tokens"],
+        "additionalProperties": false
+      },
+      "status": { "type": "string", "enum": ["ready", "review"] },
+      "items": {
+        "type": "array",
+        "items": {
+          "type": "object",
+          "properties": {
+            "id": { "type": "string" },
+            "status": { "type": "string", "enum": ["ready", "review"] },
+            "route": { "type": ["string", "null"] },
+            "suggestedRoute": { "type": ["string", "null"] },
+            "confidence": { "type": "number", "minimum": 0, "maximum": 1 },
+            "probabilities": {
+              "type": "object",
+              "propertyNames": { "type": "string" },
+              "additionalProperties": { "type": "number", "minimum": 0, "maximum": 1 }
+            }
+          },
+          "required": ["id", "status", "route", "suggestedRoute", "confidence", "probabilities"],
+          "additionalProperties": false
+        }
+      },
+      "routed": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 },
+      "requestCount": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 },
+      "requestsMade": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }
+    },
+    "required": ["model", "usage", "status", "items", "routed", "requestCount", "requestsMade"],
+    "additionalProperties": false
+  }
+}