jev-recipes 0.0.4 → 0.2.0

package/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 ## Unreleased
 
+- Document installed-package imports and CLI commands first; move repository setup into the contributor guide and rename the local CLI script to `jev-recipes`.
+
+- Add recipe tests under `tests/recipe/`, mocked Jev responses, recipe coverage reports and thresholds, and test checks in CI.
+
+- Unify recipe execution helpers, result validation, subject registration, and documentation across the catalog.
+
+- 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.

package/README.md

@@ -2,24 +2,11 @@
 
 [![npm version](https://img.shields.io/npm/v/jev-recipes?logo=npm)](https://www.npmjs.com/package/jev-recipes)
 
-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.
+66 small TypeScript recipes for AI applications. Choose a handler, select useful evidence, check an answer, or decide when to ask for help.
 
-Each recipe is a function you can use on its own. Your application supplies the context and acts on the result.
+Use `jev-recipes` through TypeScript imports or its included command-line tool. [Jev](https://docs.typesafe.ai/introduction/coding-agents) powers the live decisions. Your application supplies the context and acts on the result.
 
-## Recipes
-
-| 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.           |
-
-Each recipe has its own usage guide, input and result schemas, and runnable demo.
-
-## Use in an app
+## Install
 
 Requires Node.js 22.9 or newer.
 
@@ -27,6 +14,8 @@ Requires Node.js 22.9 or newer.
 npm install jev-recipes
 ```
 
+## Use a recipe
+
 Set `TYPESAFE_API_KEY` in your server's environment, then call a recipe:
 
 ```ts
@@ -50,28 +39,38 @@ You can also import recipes from `jev-recipes`. Every recipe accepts an optional
 
 Live calls send the supplied input to TypeSafe and use API quota. Keep your API key on the server.
 
-## Try the demos
+## Recipes
+
+[Browse all 66 recipes](https://github.com/agencyenterprise/jev-recipes/blob/main/recipes/README.md). Each handles a focused decision and has its own schemas, example, and usage guide.
 
-From this repository:
+| Group                                                                                                                        | Recipes | Examples                                                |
+| ---------------------------------------------------------------------------------------------------------------------------- | ------- | ------------------------------------------------------- |
+| [Answer quality](https://github.com/agencyenterprise/jev-recipes/blob/main/recipes/README.md#answer-quality)                 | 10      | `answer-coverage`, `answer-relevance`, `citation-match` |
+| [Retrieval and evidence](https://github.com/agencyenterprise/jev-recipes/blob/main/recipes/README.md#retrieval-and-evidence) | 13      | `rerank`, `verify`, `answerability`                     |
+| [Conversation](https://github.com/agencyenterprise/jev-recipes/blob/main/recipes/README.md#conversation)                     | 11      | `clarify`, `turn-intent`, `followup-link`               |
+| [Tools and tasks](https://github.com/agencyenterprise/jev-recipes/blob/main/recipes/README.md#tools-and-tasks)               | 12      | `route`, `handoff`, `tool-fit`                          |
+| [Customer support](https://github.com/agencyenterprise/jev-recipes/blob/main/recipes/README.md#customer-support)             | 10      | `issue-impact`, `attempted-step`, `workaround-fit`      |
+| [Memory](https://github.com/agencyenterprise/jev-recipes/blob/main/recipes/README.md#memory)                                 | 5       | `memory-value`, `memory-scope`, `memory-relation`       |
+| [Knowledge maintenance](https://github.com/agencyenterprise/jev-recipes/blob/main/recipes/README.md#knowledge-maintenance)   | 5       | `document-role`, `audience-fit`, `change-meaning`       |
+
+## Try a demo
+
+After installing the package, run its CLI from your app's directory:
 
 ```sh
-npm ci
-npm run build
-npm run jev -- demo all
+npx jev-recipes demo rerank
 ```
 
-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.
-
-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.
+Replace `rerank` with another recipe name, or use `all` to try every installed recipe. Demos use saved responses and need no API key. They show how recipes handle decisions; they do not measure model accuracy.
 
 ## Find a recipe
 
-Developers and coding agents can inspect the catalog without calling Jev:
+Use the CLI to browse the installed recipes without an API key:
 
 ```sh
-npm run jev -- list
-npm run jev -- list evidence --category retrieval
-npm run jev -- describe answerability
+npx jev-recipes list
+npx jev-recipes list evidence --category retrieval
+npx jev-recipes describe answer-coverage
 ```
 
 `list` searches names, descriptions, categories, and tags. `describe` returns the recipe's limits, JSON input and result schemas, and example input.
@@ -82,68 +81,58 @@ The same catalog is available in TypeScript:
 import { listRecipes, describeRecipe } from 'jev-recipes/catalog';
 
 const recipes = listRecipes({ category: 'retrieval' });
-const specification = describeRecipe('answerability');
+const specification = describeRecipe('answer-coverage');
 ```
 
 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.
 
 ## Run your own input
 
-Add `TYPESAFE_API_KEY` to a local `.env` file. See [.env.example](.env.example) for the format.
-
-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:
+Save an example input from the installed package:
 
 ```sh
-node --env-file-if-exists=.env dist/cli/index.js run rerank input.json
-```
-
-## Connect the recipes
-
-The [support assistant example](examples/support/README.md) combines all six:
-
-```text
-handoff → clarify → route → rerank → answerability → draft an answer → verify
+npx jev-recipes example rerank > input.json
 ```
 
-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.
+Edit `input.json`, then set your API key in the terminal and run the recipe:
 
 ```sh
-npm run example:support
+export TYPESAFE_API_KEY='your-api-key'
+npx jev-recipes run rerank input.json
 ```
 
-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.
+The CLI reads the key from its environment; it does not load `.env` files automatically. Live runs send your input to TypeSafe and use API quota. Commands return JSON. Use `-` instead of a filename to read from stdin.
 
 ## 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.
+- 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.
 
 ## Contribute
 
-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.
+See [CONTRIBUTING.md](https://github.com/agencyenterprise/jev-recipes/blob/main/CONTRIBUTING.md) for repository setup, tests, and adding recipes. See [CHANGELOG.md](https://github.com/agencyenterprise/jev-recipes/blob/main/CHANGELOG.md) for changes and [RELEASING.md](https://github.com/agencyenterprise/jev-recipes/blob/main/RELEASING.md) for publishing.
 
-```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
-```
+## Cool projects
+
+Keep the recipes small and connect them in your application. These ideas show how a few decisions can support a larger project:
+
+| 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                  |
 
-See [CONTRIBUTING.md](CONTRIBUTING.md) to add a recipe.
+The [support assistant example](https://github.com/agencyenterprise/jev-recipes/blob/main/examples/support/README.md) shows how to combine recipes with your own draft generator. It stops when review or better information is needed:
 
-`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.
+```text
+handoff → clarify → route → rerank → answerability → draft an answer → verify
+```
 
 ## License
 
-[MIT](LICENSE). Independent community project. Jev and TypeSafe are products of TypeSafe AI.
+[MIT](https://github.com/agencyenterprise/jev-recipes/blob/main/LICENSE). Independent community project. Jev and TypeSafe are products of TypeSafe AI.