jev-recipes 0.0.1 → 0.0.4

package/dist/src/schema.d.ts

@@ -34,6 +34,25 @@ export declare const recipeOptionsSchema: z.ZodObject<{
     model: z.ZodOptional<z.ZodString>;
     signal: z.ZodOptional<z.ZodInstanceOf<AbortSignal>>;
 }, z.core.$strip>;
+export declare const recipeCategorySchema: z.ZodEnum<{
+    retrieval: "retrieval";
+    conversation: "conversation";
+    workflow: "workflow";
+}>;
+export declare const recipeMetadataSchema: z.ZodObject<{
+    id: z.ZodString;
+    title: z.ZodString;
+    description: z.ZodString;
+    category: z.ZodEnum<{
+        retrieval: "retrieval";
+        conversation: "conversation";
+        workflow: "workflow";
+    }>;
+    tags: z.ZodArray<z.ZodString>;
+    limitations: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+export type RecipeMetadata = z.infer<typeof recipeMetadataSchema>;
+export type RecipeCategory = z.infer<typeof recipeCategorySchema>;
 export type DecisionClient = z.infer<typeof decisionClientSchema>;
 export type DecisionStatus = z.infer<typeof decisionStatusSchema>;
 export type RecipeOptions = z.infer<typeof recipeOptionsSchema>;

package/dist/src/schema.js

@@ -20,6 +20,15 @@ export const recipeOptionsSchema = z.object({
     model: nonEmptyText.optional(),
     signal: z.instanceof(AbortSignal).optional(),
 });
+export const recipeCategorySchema = z.enum(['retrieval', 'conversation', 'workflow']);
+export const recipeMetadataSchema = z.object({
+    id: nonEmptyText,
+    title: nonEmptyText,
+    description: nonEmptyText,
+    category: recipeCategorySchema,
+    tags: z.array(nonEmptyText),
+    limitations: z.array(nonEmptyText),
+});
 function hasDecisionMethod(client) {
     return (typeof client === 'object' &&
         client !== null &&

package/examples/support/README.md

@@ -0,0 +1,60 @@
+# Support assistant
+
+A complete decision flow using all six recipes. The workflow lives here so each recipe remains independently usable.
+
+From the repository, after `npm run build`:
+
+```sh
+npm run example:support
+```
+
+The default run uses hand-authored Jev responses and a saved draft from [demo.json](demo.json). It requires no API key and makes no model calls.
+
+To use live Jev decisions with the same saved draft:
+
+```sh
+npm run example:support -- --live
+```
+
+This loads `TYPESAFE_API_KEY` from `.env`, sends synthetic fixture inputs to TypeSafe, and makes up to six Jev requests with retries disabled. There is no generative model call. The output identifies the mode, outcome, and decisions made before stopping.
+
+After installing a packed or released package, you can run the compiled example directly:
+
+```sh
+node node_modules/jev-recipes/dist/examples/support/index.js
+node --env-file=.env node_modules/jev-recipes/dist/examples/support/index.js --live
+```
+
+## Follow the flow
+
+Read [workflow.ts](https://github.com/agencyenterprise/jev-recipes/blob/main/examples/support/workflow.ts) from top to bottom:
+
+1. `handoff` checks escalation rules first. A human request or uncertainty stops here.
+2. `clarify` checks the information needed to proceed.
+3. `route` selects the support handler. Its name is passed to the draft callback.
+4. `rerank` selects useful passages from evidence the application already retrieved.
+5. `answerability` checks whether those passages answer the question.
+6. Your `draftAnswer` callback creates claims with references to selected evidence IDs.
+7. `verify` checks each claim against the referenced original passages.
+8. The final answer joins only those checked claims after all are supported.
+
+The workflow rejects references to evidence that was not selected. The callback supplies IDs, never replacement evidence text. The final response contains no unchecked prose outside the supplied claims. Claim verification still does not establish source truth or guarantee that the answer covers every part of the question.
+
+## Adapt it
+
+Copy `workflow.ts` and `schema.ts` into your application. Replace their repository-relative imports with `jev-recipes` or individual recipe exports. The example schemas also use lower-level recipe schemas; either define your application's shapes locally or derive them from each exported input schema's `.shape`.
+
+Supply your own routes, requirements, handoff rules, and retrieved evidence. Replace the runner's saved-draft callback with your existing generation code, returning `{ claims: [{ id, claim, evidenceIds }] }`. The callback receives the original request, optional conversation context, selected route, and selected passages. You choose the model and framework.
+
+A caller can import the source workflow within this repository:
+
+```ts
+import { answerSupportRequest } from './workflow.js';
+
+const result = await answerSupportRequest(input, draftAnswer, { client });
+if (result.outcome === 'answered') console.log(result.answer);
+```
+
+The possible outcomes are `answered`, `human`, `review`, `clarification`, `no_evidence`, `cannot_answer`, and `unverified`. Stopped results identify the `stage`. Results include completed `decisions` for inspection. Only `answered` includes an answer; errors in inputs, draft references, model responses, or transport throw.
+
+This example does not retrieve documents, send responses, open tickets, or make account changes. Your application handles those actions and follows its own review policy. The example is not an accuracy benchmark.

package/examples/support/demo.json

@@ -0,0 +1,156 @@
+{
+  "input": {
+    "request": "How do I reset my password?",
+    "routes": {
+      "account": "Sign-in, passwords, and account access",
+      "billing": "Invoices, payments, and subscriptions"
+    },
+    "requirements": [
+      {
+        "id": "intent",
+        "description": "The customer identifies what they need help with."
+      }
+    ],
+    "handoffRules": [
+      {
+        "id": "requested-human",
+        "description": "The customer explicitly asks to speak with a human support representative."
+      }
+    ],
+    "evidence": [
+      {
+        "id": "password-reset",
+        "text": "Select Forgot password on the sign-in page to receive a password reset link."
+      },
+      {
+        "id": "invoices",
+        "text": "Download invoices from the Billing page."
+      }
+    ],
+    "topK": 1
+  },
+  "draft": {
+    "claims": [
+      {
+        "id": "reset-instructions",
+        "claim": "Select Forgot password on the sign-in page to receive a password reset link.",
+        "evidenceIds": ["password-reset"]
+      }
+    ]
+  },
+  "responses": {
+    "rule_0": {
+      "model": "demo-fixture",
+      "usage": {
+        "input_tokens": 0,
+        "output_tokens": 0
+      },
+      "answers": {
+        "rule_0": {
+          "type": "choice",
+          "choice": "does_not_match",
+          "confidence": 0.96,
+          "probabilities": {
+            "matches": 0.015,
+            "does_not_match": 0.97,
+            "unclear": 0.015
+          }
+        }
+      }
+    },
+    "requirement_0": {
+      "model": "demo-fixture",
+      "usage": {
+        "input_tokens": 0,
+        "output_tokens": 0
+      },
+      "answers": {
+        "requirement_0": {
+          "type": "choice",
+          "choice": "present",
+          "confidence": 0.96,
+          "probabilities": {
+            "present": 0.97,
+            "missing": 0.015,
+            "ambiguous": 0.015
+          }
+        }
+      }
+    },
+    "route": {
+      "model": "demo-fixture",
+      "usage": {
+        "input_tokens": 0,
+        "output_tokens": 0
+      },
+      "answers": {
+        "route": {
+          "type": "choice",
+          "choice": "account",
+          "confidence": 0.96,
+          "probabilities": {
+            "account": 0.97,
+            "billing": 0.015,
+            "__review__": 0.015
+          }
+        }
+      }
+    },
+    "item_0,item_1": {
+      "model": "demo-fixture",
+      "usage": {
+        "input_tokens": 0,
+        "output_tokens": 0
+      },
+      "answers": {
+        "item_0": {
+          "type": "noul",
+          "noul": 0.97
+        },
+        "item_1": {
+          "type": "noul",
+          "noul": 0.04
+        }
+      }
+    },
+    "answerability": {
+      "model": "demo-fixture",
+      "usage": {
+        "input_tokens": 0,
+        "output_tokens": 0
+      },
+      "answers": {
+        "answerability": {
+          "type": "choice",
+          "choice": "sufficient",
+          "confidence": 0.96,
+          "probabilities": {
+            "sufficient": 0.97,
+            "partial": 0.01,
+            "insufficient": 0.01,
+            "conflicting": 0.01
+          }
+        }
+      }
+    },
+    "claim_0": {
+      "model": "demo-fixture",
+      "usage": {
+        "input_tokens": 0,
+        "output_tokens": 0
+      },
+      "answers": {
+        "claim_0": {
+          "type": "choice",
+          "choice": "supported",
+          "confidence": 0.96,
+          "probabilities": {
+            "supported": 0.97,
+            "contradicted": 0.015,
+            "unsupported": 0.015
+          }
+        }
+      }
+    }
+  }
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "jev-recipes",
-  "version": "0.0.1",
-  "description": "Small, composable Jev recipes for routing, reranking, and checking evidence.",
+  "version": "0.0.4",
+  "description": "Small, composable Jev decisions for retrieval, conversations, and agent workflows.",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -31,7 +31,23 @@
       "types": "./dist/recipes/verify/index.d.ts",
       "import": "./dist/recipes/verify/index.js"
     },
-    "./package.json": "./package.json"
+    "./package.json": "./package.json",
+    "./answerability": {
+      "types": "./dist/recipes/answerability/index.d.ts",
+      "import": "./dist/recipes/answerability/index.js"
+    },
+    "./clarify": {
+      "types": "./dist/recipes/clarify/index.d.ts",
+      "import": "./dist/recipes/clarify/index.js"
+    },
+    "./handoff": {
+      "types": "./dist/recipes/handoff/index.d.ts",
+      "import": "./dist/recipes/handoff/index.js"
+    },
+    "./catalog": {
+      "types": "./dist/catalog/index.d.ts",
+      "import": "./dist/catalog/index.js"
+    }
   },
   "bin": {
     "jev-recipes": "dist/cli/index.js"
@@ -42,7 +58,9 @@
     "recipes/*/README.md",
     "README.md",
     "CHANGELOG.md",
-    "LICENSE"
+    "LICENSE",
+    "examples/support/demo.json",
+    "examples/support/README.md"
   ],
   "scripts": {
     "clean": "rimraf dist",
@@ -50,12 +68,13 @@
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "format": "prettier --write .",
     "format:check": "prettier --check .",
-    "demo": "node dist/cli/index.js demo route && node dist/cli/index.js demo rerank && node dist/cli/index.js demo verify",
+    "demo": "node dist/cli/index.js demo all",
     "jev": "node --env-file-if-exists=.env dist/cli/index.js",
-    "ci": "npm run format:check && npm run typecheck && npm run build && npm run demo",
+    "ci": "npm run format:check && npm run typecheck && npm run build && npm run demo && npm run example:support",
     "pack:check": "npm pack --dry-run",
     "prepack": "npm run build",
-    "prepublishOnly": "npm run ci"
+    "prepublishOnly": "npm run ci",
+    "example:support": "node --env-file-if-exists=.env dist/examples/support/index.js"
   },
   "dependencies": {
     "@typesafe-ai/sdk": "0.6.0",

package/recipes/answerability/README.md

@@ -0,0 +1,29 @@
+# Answerability
+
+Decide whether supplied evidence can answer an entire question before generating a response.
+
+```ts
+import { answerability } from 'jev-recipes/answerability';
+
+const result = await answerability({
+  question: 'How do I reset my password, and when does the link expire?',
+  evidence: [{ id: 'reset', text: 'Select Forgot password. Reset links expire after 30 minutes.' }],
+});
+
+if (result.canAnswer) console.log('Evidence is sufficient for drafting.');
+```
+
+Provide 1 to 50 passages with unique, non-empty IDs. Handle empty retrieval in your application before calling this recipe. `minConfidence` defaults to `0.8`.
+
+| Verdict        | Meaning                                                 |
+| -------------- | ------------------------------------------------------- |
+| `sufficient`   | Every material part of the question can be answered.    |
+| `partial`      | Some material parts can be answered, but others cannot. |
+| `insufficient` | No material part can be answered.                       |
+| `conflicting`  | Incompatible evidence prevents a consistent answer.     |
+
+`canAnswer` is true only for `sufficient` at or above the confidence threshold. `status: "ready"` means the assessment passed the threshold; it can still describe insufficient or conflicting evidence. Below the threshold, `status` is `review` and `canAnswer` is false.
+
+The result includes the verdict, confidence, all choice probabilities, model, and token usage. The recipe assesses only supplied evidence. It does not verify source truth, generate an answer, or guarantee that a later draft uses the evidence correctly. Use `verify` on that draft's claims.
+
+Run `npm run jev -- demo answerability` for the hand-authored offline [fixture](demo.json). Fixtures exercise decision handling; they do not measure accuracy. Calibrate thresholds with your own labeled examples.

package/recipes/answerability/demo.json

@@ -0,0 +1,31 @@
+{
+  "input": {
+    "question": "How do I reset my password, and when does the link expire?",
+    "evidence": [
+      {
+        "id": "reset",
+        "text": "Select Forgot password on the sign-in page. Reset links expire after 30 minutes."
+      }
+    ]
+  },
+  "response": {
+    "model": "demo-fixture",
+    "usage": {
+      "input_tokens": 0,
+      "output_tokens": 0
+    },
+    "answers": {
+      "answerability": {
+        "type": "choice",
+        "choice": "sufficient",
+        "confidence": 0.96,
+        "probabilities": {
+          "sufficient": 0.97,
+          "partial": 0.01,
+          "insufficient": 0.01,
+          "conflicting": 0.01
+        }
+      }
+    }
+  }
+}

package/recipes/clarify/README.md

@@ -0,0 +1,32 @@
+# Clarify
+
+Check whether a request supplies the information your application needs. You define the requirements; the recipe identifies which ones are present, missing, or ambiguous.
+
+```ts
+import { clarify } from 'jev-recipes/clarify';
+
+const result = await clarify({
+  request: 'Please cancel it.',
+  context: 'The customer has a storage subscription and a pending hardware order.',
+  requirements: [
+    { id: 'target', description: 'Which product or order should be changed' },
+    { id: 'action', description: 'What change the customer wants' },
+  ],
+});
+
+console.log(result.canProceed, result.missing, result.ambiguous);
+```
+
+Provide 1 to 50 requirements with unique, non-empty IDs. Optional `context` supplies conversation history or application facts. `minConfidence` defaults to `0.8` and applies independently to each check.
+
+- `present`: the required information is explicit or unambiguously implied.
+- `missing`: the required information is absent.
+- `ambiguous`: relevant information has multiple plausible meanings or conflicting values.
+
+`canProceed` is true only when every requirement is confidently present. `missing` and `ambiguous` contain confidently classified requirement IDs. Low-confidence checks remain in `checks` with `status: "review"`; they block proceeding even if both arrays are empty. Overall `status` is `review` when any check falls below the threshold.
+
+A `ready` result can still require clarification. Each check includes its verdict, confidence, and probabilities; the result also includes model and token usage.
+
+Your application maps requirement IDs to follow-up questions or asks its generative model to phrase them. This recipe neither discovers requirements nor generates questions. It does not validate identity, permissions, or exact field formats.
+
+Run `npm run jev -- demo clarify` for the hand-authored offline [fixture](demo.json). Evaluate your own requirements and thresholds on labeled examples before relying on them.

package/recipes/clarify/demo.json

@@ -0,0 +1,45 @@
+{
+  "input": {
+    "request": "Please cancel it.",
+    "context": "The customer has a monthly storage subscription and a pending hardware order.",
+    "requirements": [
+      {
+        "id": "target",
+        "description": "Which product or order should be changed"
+      },
+      {
+        "id": "action",
+        "description": "What change the customer wants"
+      }
+    ]
+  },
+  "response": {
+    "model": "demo-fixture",
+    "usage": {
+      "input_tokens": 0,
+      "output_tokens": 0
+    },
+    "answers": {
+      "requirement_0": {
+        "type": "choice",
+        "choice": "ambiguous",
+        "confidence": 0.96,
+        "probabilities": {
+          "present": 0.015,
+          "missing": 0.015,
+          "ambiguous": 0.97
+        }
+      },
+      "requirement_1": {
+        "type": "choice",
+        "choice": "present",
+        "confidence": 0.96,
+        "probabilities": {
+          "present": 0.97,
+          "missing": 0.015,
+          "ambiguous": 0.015
+        }
+      }
+    }
+  }
+}

package/recipes/handoff/README.md

@@ -0,0 +1,35 @@
+# Handoff
+
+Check a request against your rules for involving a human. The function returns a decision; your application handles the transfer.
+
+```ts
+import { handoff } from 'jev-recipes/handoff';
+
+const result = await handoff({
+  request: 'Please connect me with a person.',
+  rules: [
+    {
+      id: 'requested-human',
+      description: 'The customer explicitly asks to speak with a human support representative.',
+    },
+  ],
+});
+
+console.log(result.decision, result.matchedRules);
+```
+
+Provide 1 to 50 rules with unique, non-empty IDs. Optional `context` supplies conversation history or application facts. `minConfidence` defaults to `0.8` and applies independently to each check.
+
+| Decision   | Condition                                                               |
+| ---------- | ----------------------------------------------------------------------- |
+| `human`    | At least one rule confidently `matches`.                                |
+| `review`   | No confident match, and at least one `unclear` or low-confidence check. |
+| `continue` | Every rule confidently `does_not_match`.                                |
+
+`matchedRules` contains confident matches. `uncertainRules` contains unclear and low-confidence checks. A confident match is enough to return `human` with `status: "ready"`, even if other rules are uncertain. A `review` decision always has `status: "review"`.
+
+The result includes every rule's verdict, confidence, and probabilities, plus model and token usage. An `unclear` verdict can have high confidence: the model is confident that it cannot decide from the supplied facts.
+
+Write observable rules and provide the facts needed to evaluate them. Compute exact amounts, dates, permissions, and hard limits in code. This semantic check does not contact anyone, enforce authorization, or provide a security boundary.
+
+Run `npm run jev -- demo handoff` for the hand-authored offline [fixture](demo.json). Fixtures do not measure live model accuracy.

package/recipes/handoff/demo.json

@@ -0,0 +1,30 @@
+{
+  "input": {
+    "request": "Please connect me with a person.",
+    "rules": [
+      {
+        "id": "requested-human",
+        "description": "The customer explicitly asks to speak with a human support representative."
+      }
+    ]
+  },
+  "response": {
+    "model": "demo-fixture",
+    "usage": {
+      "input_tokens": 0,
+      "output_tokens": 0
+    },
+    "answers": {
+      "rule_0": {
+        "type": "choice",
+        "choice": "matches",
+        "confidence": 0.96,
+        "probabilities": {
+          "matches": 0.97,
+          "does_not_match": 0.015,
+          "unclear": 0.015
+        }
+      }
+    }
+  }
+}

package/dist/cli/recipes.d.ts

@@ -1,53 +0,0 @@
-import type { RecipeOptions } from '../src/schema.js';
-export declare const recipes: {
-    route: {
-        description: string;
-        run: (input: unknown, options?: RecipeOptions) => Promise<{
-            model: string;
-            usage: {
-                input_tokens: number;
-                output_tokens: number;
-            };
-            status: "ready" | "review";
-            route: string | null;
-            suggestedRoute: string | null;
-            confidence: number;
-            probabilities: Record<string, number>;
-        }>;
-    };
-    rerank: {
-        description: string;
-        run: (input: unknown, options?: RecipeOptions) => Promise<{
-            model: string;
-            usage: {
-                input_tokens: number;
-                output_tokens: number;
-            };
-            status: "ready" | "review";
-            items: {
-                id: string;
-                text: string;
-                relevance: number;
-            }[];
-            evaluated: number;
-        }>;
-    };
-    verify: {
-        description: string;
-        run: (input: unknown, options?: RecipeOptions) => Promise<{
-            model: string;
-            usage: {
-                input_tokens: number;
-                output_tokens: number;
-            };
-            checks: {
-                id: string;
-                status: "ready" | "review";
-                verdict: "supported" | "contradicted" | "unsupported";
-                confidence: number;
-                probabilities: Record<"supported" | "contradicted" | "unsupported", number>;
-            }[];
-            allSupported: boolean;
-        }>;
-    };
-};

package/dist/cli/recipes.js

@@ -1,20 +0,0 @@
-import { route } from '../recipes/route/index.js';
-import { routeInputSchema } from '../recipes/route/schema.js';
-import { rerank } from '../recipes/rerank/index.js';
-import { rerankInputSchema } from '../recipes/rerank/schema.js';
-import { verify } from '../recipes/verify/index.js';
-import { verifyInputSchema } from '../recipes/verify/schema.js';
-export const recipes = {
-    route: {
-        description: 'Choose a handler or request review.',
-        run: (input, options) => route(routeInputSchema.parse(input), options),
-    },
-    rerank: {
-        description: 'Rank passages by relevance to a query.',
-        run: (input, options) => rerank(rerankInputSchema.parse(input), options),
-    },
-    verify: {
-        description: 'Check claims against supplied evidence.',
-        run: (input, options) => verify(verifyInputSchema.parse(input), options),
-    },
-};