jev-recipes 0.0.1 → 0.0.4

package/CHANGELOG.md

@@ -2,9 +2,14 @@
 
 ## Unreleased
 
-### Added
+- Add independent `answerability`, `clarify`, and `handoff` recipes with Zod schemas, inferred types, documentation, and offline fixtures.
+- Add recipe-owned metadata, a searchable catalog, and CLI `describe` with JSON schemas and example input.
+- Add `demo all` and a support-assistant example that composes six recipes, accepts an application draft callback, and verifies claims against selected evidence.
+- Extend package exports and release checks without adding dependencies.
 
-- Initial 0.0.1 foundation with route, rerank, and verify recipes.
+## 0.0.1
+
+- Initial foundation with route, rerank, and verify recipes.
 - TypeScript library with Zod schemas and inferred types.
 - CLI with offline demos, editable example input, and live Jev calls.
 - Build, formatting, and package checks for manual npm releases.

package/README.md

@@ -1,159 +1,149 @@
-# jev recipes
+# jev-recipes
 
-Small, composable recipes for [Jev](https://docs.typesafe.ai/introduction/coding-agents): choose a handler, rank useful passages, and check claims against evidence.
+[![npm version](https://img.shields.io/npm/v/jev-recipes?logo=npm)](https://www.npmjs.com/package/jev-recipes)
 
-**Version 0.0.1.** A TypeScript library and a small command-line runner. Each recipe owns its implementation, Zod schemas, example, and documentation. Public data types are inferred from those schemas.
+Small TypeScript recipes for the decisions inside an AI application. Use [Jev](https://docs.typesafe.ai/introduction/coding-agents) to choose a handler, select useful evidence, check an answer, or decide when to ask for help.
 
-| Recipe                               | Input                          | Result                                     |
-| ------------------------------------ | ------------------------------ | ------------------------------------------ |
-| [`route`](recipes/route/README.md)   | A request and named handlers   | A selected handler or a review decision    |
-| [`rerank`](recipes/rerank/README.md) | A query and candidate passages | Relevant passages, ordered by relevance    |
-| [`verify`](recipes/verify/README.md) | Claims paired with evidence    | A verdict and review status for each claim |
+Each recipe is a function you can use on its own. Your application supplies the context and acts on the result.
 
-## Try it locally
+## Recipes
 
-Requires Node.js 22.9 or newer. From this repository:
+| Recipe                                             | What it does                                       |
+| -------------------------------------------------- | -------------------------------------------------- |
+| [`route`](recipes/route/README.md)                 | Chooses a handler for a request.                   |
+| [`rerank`](recipes/rerank/README.md)               | Selects and orders relevant passages.              |
+| [`verify`](recipes/verify/README.md)               | Checks claims against supplied evidence.           |
+| [`answerability`](recipes/answerability/README.md) | Checks whether the evidence can answer a question. |
+| [`clarify`](recipes/clarify/README.md)             | Finds missing or ambiguous information.            |
+| [`handoff`](recipes/handoff/README.md)             | Checks your rules for involving a human.           |
 
-```sh
-npm ci
-npm run build
-npm run jev -- list
-npm run jev -- demo rerank
-```
+Each recipe has its own usage guide, input and result schemas, and runnable demo.
+
+## Use in an app
 
-All three demos work without a key. Each recipe's `README.md` explains its API and limits; `demo.json` supplies executable example input and a saved response for the CLI. The demos run the recipe's validation and decision handling without calling Jev or measuring model accuracy.
+Requires Node.js 22.9 or newer.
 
 ```sh
-npm run jev -- demo route
-npm run jev -- demo verify
+npm install jev-recipes
 ```
 
-## Run your own input
+Set `TYPESAFE_API_KEY` in your server's environment, then call a recipe:
 
-Copy `.env.example` to `.env`, then set `TYPESAFE_API_KEY` from your TypeSafe account. Keep the key out of source control.
+```ts
+import { rerank } from 'jev-recipes/rerank';
 
-```sh
-cp .env.example .env
-node dist/cli/index.js example rerank > input.json
+const result = await rerank({
+  query: 'How do I reset my password?',
+  items: [
+    { id: 'billing', text: 'Invoices appear on the Billing page.' },
+    { id: 'reset', text: 'Select Forgot password to receive a reset link.' },
+  ],
+  topK: 1,
+});
+
+if (result.status === 'ready') {
+  console.log(result.items);
+}
 ```
 
-Edit `input.json` with your query and passages, then run:
+You can also import recipes from `jev-recipes`. Every recipe accepts an optional second argument with `client`, `model`, and `signal`. Use `createClient` to configure the official TypeSafe SDK's timeouts and retries.
 
-```sh
-npm run jev -- run rerank input.json
-```
+Live calls send the supplied input to TypeSafe and use API quota. Keep your API key on the server.
+
+## Try the demos
 
-Use `-` in place of the filename to read JSON from stdin. The `npm run jev` script loads `.env`; direct `jev-recipes` or `node` invocations use the process environment unless you explicitly load an env file. Use the direct command when piping JSON so npm's script banner is not included:
+From this repository:
 
 ```sh
-node --env-file-if-exists=.env dist/cli/index.js run rerank input.json
+npm ci
+npm run build
+npm run jev -- demo all
 ```
 
-Live runs send the recipe's input to TypeSafe and consume API quota. Jev performs inference remotely; the recipe's filtering and review rules run in your process. This project does not store inputs or add telemetry.
+Demos use saved responses and need no API key. They show how each recipe handles a decision; they do not measure model accuracy. To run one, replace `all` with its name.
 
-## Use from an app
+The repository may contain additions that are not yet in the [published npm package](https://www.npmjs.com/package/jev-recipes). Use this checkout to try all the recipes shown here.
 
-The package exposes the same functions used by the command-line runner. In this checkout, package self-references work after `npm run build`:
+## Find a recipe
 
-```ts
-import { rerank } from 'jev-recipes';
+Developers and coding agents can inspect the catalog without calling Jev:
 
-const result = await rerank({
-  query: 'How do I reset my password?',
-  items: [
-    { id: 'billing', text: 'Invoices appear on the Billing page.' },
-    { id: 'reset', text: 'Select Forgot password to receive a reset link.' },
-  ],
-  topK: 1,
-});
-
-console.log(result.status, result.items);
+```sh
+npm run jev -- list
+npm run jev -- list evidence --category retrieval
+npm run jev -- describe answerability
 ```
 
-Individual recipe imports are also available:
+`list` searches names, descriptions, categories, and tags. `describe` returns the recipe's limits, JSON input and result schemas, and example input.
+
+The same catalog is available in TypeScript:
 
 ```ts
-import { route } from 'jev-recipes/route';
-import { verify } from 'jev-recipes/verify';
+import { listRecipes, describeRecipe } from 'jev-recipes/catalog';
+
+const recipes = listRecipes({ category: 'retrieval' });
+const specification = describeRecipe('answerability');
 ```
 
-For another local project, run `npm pack` here and install the resulting `.tgz` file there. That exercises the same package contents npm will distribute. See [RELEASING.md](RELEASING.md) for the commands. This README does not assume the package is published on npm yet.
+The library returns metadata and schemas. The command-line description also includes example input. Zod validates runtime inputs, including rules such as unique IDs that JSON Schema does not fully express.
 
-### Client configuration
+## Run your own input
 
-The default client reads `TYPESAFE_API_KEY` and uses `jev-latest`. You can reuse a client and supply a model or cancellation signal per call:
+Add `TYPESAFE_API_KEY` to a local `.env` file. See [.env.example](.env.example) for the format.
 
-```ts
-import { createClient, route } from 'jev-recipes';
-
-const client = createClient({ timeout: 15_000, retry: { maxRetries: 1 } });
-const result = await route(
-  {
-    request: 'I was charged twice.',
-    routes: {
-      billing: 'Invoices, payments, subscriptions, and refunds',
-      technical: 'Errors, outages, and broken integrations',
-    },
-    minConfidence: 0.8,
-  },
-  { client, signal: AbortSignal.timeout(20_000) },
-);
+Create an input file, edit it, then run the recipe:
+
+```sh
+node dist/cli/index.js example rerank > input.json
+npm run jev -- run rerank input.json
 ```
 
-Transport, authentication, retries, and timeouts use the official `@typesafe-ai/sdk`. The shared client disables SDK logging by default. API keys belong on the server, never in browser code. The SDK timeout applies per attempt; a cancellation signal can bound the complete operation. Pass a supported model ID through `{ model: '...' }` to pin evaluations when comparing versions.
+The `npm run jev` command loads `.env`. Use `-` instead of a filename to read from stdin. For scripts that need JSON without npm's command banner:
 
-## Behavior to know
+```sh
+node --env-file-if-exists=.env dist/cli/index.js run rerank input.json
+```
 
-- `ready` means a configured threshold passed. It does not mean the model is certainly correct or that an action was executed.
-- A review outcome is a successful evaluation, not a technical error. `verify` attaches a status to each check; a ready verdict can still be `contradicted` or `unsupported`.
-- Zod 4 validates inputs and model responses. Invalid input, missing credentials, provider failures, and malformed answers throw. The CLI writes an error to stderr and exits with code 1.
-- Confidence is distinct from a choice's probability. Reranking uses independent yes/no relevance values, which do not sum to 1.
-- Threshold defaults are illustrative. Evaluate on your own labeled examples before relying on them.
-- These functions return decisions only. They do not execute handlers, modify documents, search the web, or establish whether a source is true.
-- Inputs are not silently truncated. Batch limits are documented per recipe; provider context limits can require smaller batches.
+## Connect the recipes
 
-## Project layout
+The [support assistant example](examples/support/README.md) combines all six:
 
 ```text
-recipes/
-  route/
-  rerank/
-  verify/
-    index.ts          Recipe implementation
-    schema.ts         Input/result schemas and z.infer types
-    demo.json         Example input and an offline response fixture
-    README.md         Usage and limits
-src/
-  client.ts           Thin adapter over the official SDK
-  answers.ts          Validate model responses
-  schema.ts           Shared Zod schemas and inferred types
-  index.ts            Public exports
-cli/
-  index.ts            Arguments, files, stdin, and output
-  recipes.ts          Explicit recipe registration
-  schema.ts           Command and demo validation
+handoff → clarify → route → rerank → answerability → draft an answer → verify
 ```
 
-Recipes depend on `src/`, never on one another or on the CLI. The CLI calls the public recipe functions. There is no application server, database, or background process.
-
-## Development
+It stops when the request needs a person, clarification, better evidence, or review. The draft step is a callback you can connect to your existing generation code.
 
 ```sh
-npm run format
-npm run ci
-npm run pack:check
+npm run example:support
 ```
 
-`npm run ci` checks formatting, type-checks the source, makes a clean build, and runs the offline demos. GitHub runs the same checks on Node 22 and 24. The demos show request and result shapes; live model accuracy has not been measured for this initial release.
+This runs offline with a saved draft and saved decisions. Add `-- --live` to call Jev for the decisions using your `.env` key. The draft stays fixed in both modes.
+
+## Read the result before acting
+
+- `ready` means a decision passed its threshold. Check the recipe's outcome too: a ready assessment can still find missing information or an unsupported claim.
+- Use `canProceed`, `canAnswer`, `decision`, or `allSupported` as described in each recipe's guide.
+- `review` is a valid outcome. Invalid inputs, malformed model responses, and provider errors throw; the command-line runner reports them on stderr and exits with code 1.
+- Confidence does not guarantee correctness. Choose thresholds for your use case.
+- Recipes assess the evidence and rules you supply. They return decisions; your application handles actions and permissions.
 
-See [CONTRIBUTING.md](CONTRIBUTING.md) for adding a recipe. Version 0.0.1 is the foundation: recipe installation into other projects, a user-data evaluation runner, and an MCP server are not included yet.
+## Contribute
 
-## Distribution
+Each recipe owns its implementation, Zod 4 schemas, inferred types, metadata, demo, and documentation. Recipes share a small client layer and stay independent of one another.
+
+```text
+recipes/<name>/    Individual recipes
+src/              Shared client, response validation, schemas, and exports
+catalog/          Recipe registration and discovery
+cli/              Command-line runner
+examples/         Workflows that combine recipes
+```
 
-`npm run build` compiles the TypeScript into ESM JavaScript and `.d.ts` declarations under `dist/`. `npm pack` creates a `.tgz` containing that output, the recipe demos and documentation, the changelog, and the license. npm installs the TypeSafe SDK and Zod as runtime dependencies. Consumers do not run a build.
+See [CONTRIBUTING.md](CONTRIBUTING.md) to add a recipe.
 
-Use [RELEASING.md](RELEASING.md) to inspect the archive, try it in a separate project, run live evaluations, and publish version 0.0.1. Publishing is manual.
+`npm run build` compiles the TypeScript into JavaScript modules and type declarations. `npm pack` creates the installable archive. See [RELEASING.md](RELEASING.md) for packaging and publishing, and [CHANGELOG.md](CHANGELOG.md) for changes.
 
 ## License
 
-MIT. Independent community project; Jev and TypeSafe are products of TypeSafe AI.
+[MIT](LICENSE). Independent community project. Jev and TypeSafe are products of TypeSafe AI.

package/dist/catalog/index.d.ts

@@ -0,0 +1,211 @@
+import { z } from 'zod';
+import type { RecipeFilters, RecipeName } from './schema.js';
+export declare function listRecipes(filters?: RecipeFilters): {
+    id: "route" | "answerability" | "rerank" | "verify" | "clarify" | "handoff";
+    title: string;
+    description: string;
+    category: "retrieval" | "conversation" | "workflow";
+    tags: string[];
+    limitations: string[];
+}[];
+export declare function describeRecipe(name: RecipeName): {
+    inputSchema: z.core.ZodStandardJSONSchemaPayload<z.ZodObject<{
+        request: z.ZodString;
+        routes: z.ZodRecord<z.ZodString, z.ZodString>;
+        minConfidence: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip> | z.ZodObject<{
+        query: z.ZodString;
+        items: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            text: z.ZodString;
+        }, z.core.$strip>>;
+        topK: z.ZodOptional<z.ZodNumber>;
+        minRelevance: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip> | z.ZodObject<{
+        claims: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            claim: z.ZodString;
+            evidence: z.ZodString;
+        }, z.core.$strip>>;
+        minConfidence: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip> | z.ZodObject<{
+        question: z.ZodString;
+        evidence: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            text: z.ZodString;
+        }, z.core.$strip>>;
+        minConfidence: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip> | z.ZodObject<{
+        request: z.ZodString;
+        context: z.ZodOptional<z.ZodString>;
+        requirements: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            description: z.ZodString;
+        }, z.core.$strip>>;
+        minConfidence: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip> | z.ZodObject<{
+        request: z.ZodString;
+        context: z.ZodOptional<z.ZodString>;
+        rules: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            description: z.ZodString;
+        }, z.core.$strip>>;
+        minConfidence: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+    resultSchema: z.core.ZodStandardJSONSchemaPayload<z.ZodObject<{
+        model: z.ZodString;
+        usage: z.ZodObject<{
+            input_tokens: z.ZodNumber;
+            output_tokens: z.ZodNumber;
+        }, z.core.$strip>;
+        status: z.ZodEnum<{
+            ready: "ready";
+            review: "review";
+        }>;
+        route: z.ZodNullable<z.ZodString>;
+        suggestedRoute: z.ZodNullable<z.ZodString>;
+        confidence: z.ZodNumber;
+        probabilities: z.ZodRecord<z.ZodString, z.ZodNumber>;
+    }, z.core.$strip> | z.ZodObject<{
+        model: z.ZodString;
+        usage: z.ZodObject<{
+            input_tokens: z.ZodNumber;
+            output_tokens: z.ZodNumber;
+        }, z.core.$strip>;
+        status: z.ZodEnum<{
+            ready: "ready";
+            review: "review";
+        }>;
+        items: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            text: z.ZodString;
+            relevance: z.ZodNumber;
+        }, z.core.$strip>>;
+        evaluated: z.ZodNumber;
+    }, z.core.$strip> | z.ZodObject<{
+        model: z.ZodString;
+        usage: z.ZodObject<{
+            input_tokens: z.ZodNumber;
+            output_tokens: z.ZodNumber;
+        }, z.core.$strip>;
+        checks: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            status: z.ZodEnum<{
+                ready: "ready";
+                review: "review";
+            }>;
+            verdict: z.ZodEnum<{
+                supported: "supported";
+                contradicted: "contradicted";
+                unsupported: "unsupported";
+            }>;
+            confidence: z.ZodNumber;
+            probabilities: z.ZodRecord<z.ZodEnum<{
+                supported: "supported";
+                contradicted: "contradicted";
+                unsupported: "unsupported";
+            }>, z.ZodNumber>;
+        }, z.core.$strip>>;
+        allSupported: z.ZodBoolean;
+    }, z.core.$strip> | z.ZodObject<{
+        model: z.ZodString;
+        usage: z.ZodObject<{
+            input_tokens: z.ZodNumber;
+            output_tokens: z.ZodNumber;
+        }, z.core.$strip>;
+        status: z.ZodEnum<{
+            ready: "ready";
+            review: "review";
+        }>;
+        verdict: z.ZodEnum<{
+            sufficient: "sufficient";
+            partial: "partial";
+            insufficient: "insufficient";
+            conflicting: "conflicting";
+        }>;
+        canAnswer: z.ZodBoolean;
+        confidence: z.ZodNumber;
+        probabilities: z.ZodRecord<z.ZodEnum<{
+            sufficient: "sufficient";
+            partial: "partial";
+            insufficient: "insufficient";
+            conflicting: "conflicting";
+        }>, z.ZodNumber>;
+    }, z.core.$strip> | z.ZodObject<{
+        model: z.ZodString;
+        usage: z.ZodObject<{
+            input_tokens: z.ZodNumber;
+            output_tokens: z.ZodNumber;
+        }, z.core.$strip>;
+        status: z.ZodEnum<{
+            ready: "ready";
+            review: "review";
+        }>;
+        canProceed: z.ZodBoolean;
+        missing: z.ZodArray<z.ZodString>;
+        ambiguous: z.ZodArray<z.ZodString>;
+        checks: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            status: z.ZodEnum<{
+                ready: "ready";
+                review: "review";
+            }>;
+            verdict: z.ZodEnum<{
+                present: "present";
+                missing: "missing";
+                ambiguous: "ambiguous";
+            }>;
+            confidence: z.ZodNumber;
+            probabilities: z.ZodRecord<z.ZodEnum<{
+                present: "present";
+                missing: "missing";
+                ambiguous: "ambiguous";
+            }>, z.ZodNumber>;
+        }, z.core.$strip>>;
+    }, z.core.$strip> | z.ZodObject<{
+        model: z.ZodString;
+        usage: z.ZodObject<{
+            input_tokens: z.ZodNumber;
+            output_tokens: z.ZodNumber;
+        }, z.core.$strip>;
+        status: z.ZodEnum<{
+            ready: "ready";
+            review: "review";
+        }>;
+        decision: z.ZodEnum<{
+            review: "review";
+            human: "human";
+            continue: "continue";
+        }>;
+        matchedRules: z.ZodArray<z.ZodString>;
+        uncertainRules: z.ZodArray<z.ZodString>;
+        checks: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            status: z.ZodEnum<{
+                ready: "ready";
+                review: "review";
+            }>;
+            verdict: z.ZodEnum<{
+                matches: "matches";
+                does_not_match: "does_not_match";
+                unclear: "unclear";
+            }>;
+            confidence: z.ZodNumber;
+            probabilities: z.ZodRecord<z.ZodEnum<{
+                matches: "matches";
+                does_not_match: "does_not_match";
+                unclear: "unclear";
+            }>, z.ZodNumber>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    id: string;
+    title: string;
+    description: string;
+    category: "retrieval" | "conversation" | "workflow";
+    tags: string[];
+    limitations: string[];
+};
+export { recipeFiltersSchema, recipeNameSchema } from './schema.js';
+export { recipeCategorySchema, recipeMetadataSchema } from '../src/schema.js';
+export type { RecipeFilters, RecipeName } from './schema.js';
+export type { RecipeCategory, RecipeMetadata } from '../src/schema.js';

package/dist/catalog/index.js

@@ -0,0 +1,31 @@
+import { z } from 'zod';
+import { recipeMetadataSchema } from '../src/schema.js';
+import { recipes } from './recipes.js';
+import { recipeFiltersSchema, recipeNameSchema } from './schema.js';
+export function listRecipes(filters = {}) {
+    const { query, category } = recipeFiltersSchema.parse(filters);
+    const searchTerms = query?.toLowerCase().trim().split(/\s+/) ?? [];
+    return Object.entries(recipes)
+        .map(([id, recipe]) => ({
+        ...recipeMetadataSchema.parse(recipe.metadata),
+        id: recipeNameSchema.parse(id),
+    }))
+        .filter((recipe) => category === undefined || recipe.category === category)
+        .filter((recipe) => matchesSearch(recipe, searchTerms));
+}
+export function describeRecipe(name) {
+    const recipe = recipes[recipeNameSchema.parse(name)];
+    return {
+        ...recipeMetadataSchema.parse(recipe.metadata),
+        inputSchema: z.toJSONSchema(recipe.inputSchema, { io: 'input' }),
+        resultSchema: z.toJSONSchema(recipe.resultSchema),
+    };
+}
+function matchesSearch(recipe, terms) {
+    const text = [recipe.id, recipe.title, recipe.description, recipe.category, ...recipe.tags]
+        .join(' ')
+        .toLowerCase();
+    return terms.every((term) => text.includes(term));
+}
+export { recipeFiltersSchema, recipeNameSchema } from './schema.js';
+export { recipeCategorySchema, recipeMetadataSchema } from '../src/schema.js';