jev-recipes 0.0.1 → 0.1.0

package/CHANGELOG.md

@@ -2,9 +2,21 @@
 
 ## Unreleased
 
-### Added
+- Unify recipe execution helpers, result validation, subject registration, and documentation across the catalog.
 
-- Initial 0.0.1 foundation with route, rerank, and verify recipes.
+- Expand the catalog to 66 focused recipes across answer quality, retrieval, conversation, tools, support, memory, and knowledge maintenance.
+- Add shared choice, candidate-selection, and item-check helpers; keep recipe criteria and schemas in their own folders.
+- Register every new recipe for root and subpath imports, discovery, CLI input examples, and offline demos.
+- Document the complete catalog, explicit internal reuse, and Cool projects that compose small decisions.
+
+- 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.
+
+## 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,158 @@
-# 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:
+[Browse all 66 recipes](recipes/README.md). Each handles a focused decision and has its own schemas, example, and usage guide.
 
-```sh
-npm ci
-npm run build
-npm run jev -- list
-npm run jev -- demo rerank
-```
+| Group                                                              | Recipes | Examples                                                |
+| ------------------------------------------------------------------ | ------- | ------------------------------------------------------- |
+| [Answer quality](recipes/README.md#answer-quality)                 | 10      | `answer-coverage`, `answer-relevance`, `citation-match` |
+| [Retrieval and evidence](recipes/README.md#retrieval-and-evidence) | 13      | `rerank`, `verify`, `answerability`                     |
+| [Conversation](recipes/README.md#conversation)                     | 11      | `clarify`, `turn-intent`, `followup-link`               |
+| [Tools and tasks](recipes/README.md#tools-and-tasks)               | 12      | `route`, `handoff`, `tool-fit`                          |
+| [Customer support](recipes/README.md#customer-support)             | 10      | `issue-impact`, `attempted-step`, `workaround-fit`      |
+| [Memory](recipes/README.md#memory)                                 | 5       | `memory-value`, `memory-scope`, `memory-relation`       |
+| [Knowledge maintenance](recipes/README.md#knowledge-maintenance)   | 5       | `document-role`, `audience-fit`, `change-meaning`       |
+
+## 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.
 
-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:
+## Try the demos
+
+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';
-
-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,
-});
+Developers and coding agents can inspect the catalog without calling Jev:
 
-console.log(result.status, result.items);
+```sh
+npm run jev -- list
+npm run jev -- list evidence --category retrieval
+npm run jev -- describe answer-coverage
 ```
 
-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('answer-coverage');
 ```
 
-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
+```
+
+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:
+
+```sh
+node --env-file-if-exists=.env dist/cli/index.js 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.
+## Read the result before acting
 
-## Behavior to know
+- `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.
+- Inspect `verdict`, `selection`, or the recipe's aggregate result such as `allAnswered` or `canProceed`. Each guide explains its output.
+- `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.
 
-- `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.
+## Contribute
 
-## Project layout
+Each recipe owns its implementation, Zod 4 schemas, inferred types, metadata, demo, and documentation. Recipes share small decision helpers. A recipe that reuses another names that dependency in its guide and catalog metadata. Larger workflows belong in examples.
 
 ```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
+recipes/<name>/    Individual recipes
+src/              Shared client, response validation, schemas, and exports
+catalog/          Recipe discovery and registrations grouped by subject
+cli/              Command-line runner
+examples/         Workflows that combine recipes
 ```
 
-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.
+See [CONTRIBUTING.md](CONTRIBUTING.md) to add a recipe.
 
-## Development
+`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.
 
-```sh
-npm run format
-npm run ci
-npm run pack:check
-```
+## Cool projects
 
-`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.
+Keep the recipes small and connect them in your application. These ideas show how a few decisions can support a larger project:
 
-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.
+| Project idea                                       | Recipes to combine                                                   | Your application supplies                                              |
+| -------------------------------------------------- | -------------------------------------------------------------------- | ---------------------------------------------------------------------- |
+| An assistant that answers every part of a question | `rerank`, `answerability`, `citation-match`, `answer-coverage`       | Document retrieval, a draft generator, and the question parts to check |
+| Support that remembers attempted fixes             | `attempted-step`, `troubleshooting-fit`, `workaround-fit`, `handoff` | Conversation history, approved procedures, and escalation rules        |
+| An agent that notices repeated attempts            | `result-usefulness`, `step-progress`, `repeated-attempt`             | Tool execution, attempt history, retry limits, and stop rules          |
+| A knowledge base that catches outdated answers     | `change-meaning`, `answer-invalidation`, `cache-match`               | Source change tracking, saved answers, and access and freshness checks |
+| Memory that respects the task's scope              | `preference-kind`, `memory-value`, `memory-scope`, `memory-relation` | Candidate facts, storage consent, and retention rules                  |
 
-## Distribution
+The [support assistant example](examples/support/README.md) is implemented in this repository. It stops when review or better information is needed and accepts your own draft callback:
 
-`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.
+```text
+handoff → clarify → route → rerank → answerability → draft an answer → verify
+```
+
+```sh
+npm run example:support
+```
 
-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.
+That command uses saved decisions and a saved draft. Add `-- --live` to use live Jev decisions with your `.env` key; the example still uses the saved draft. The other projects above are composition ideas, not additional bundled applications.
 
 ## 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.