jev-recipes 0.0.4 → 0.2.0

package/recipes/reference-resolve/README.md

@@ -0,0 +1,54 @@
+# Resolve a reference
+
+Which supplied candidate does reference refer to in message and context? Resolve only this reference. Do not invent an entity or break a genuine tie.
+
+```ts
+import { referenceResolve } from 'jev-recipes/reference-resolve';
+
+const result = await referenceResolve({
+  message: 'Please cancel the hardware order, not my subscription.',
+  reference: 'the hardware order',
+  candidates: [
+    {
+      id: 'order',
+      text: 'A pending hardware order.',
+    },
+    {
+      id: 'subscription',
+      text: 'An active monthly storage subscription.',
+    },
+  ],
+});
+
+console.log(result.status, result.selection);
+```
+
+## Input
+
+| Field           | Accepts                                      |
+| --------------- | -------------------------------------------- |
+| `message`       | Non-empty text                               |
+| `reference`     | Non-empty text                               |
+| `candidates`    | 1 to 50 `{ id, text }` items with unique IDs |
+| `context`       | Optional non-empty text                      |
+| `minConfidence` | Optional number from 0 to 1; defaults to 0.8 |
+
+See [shared options and behavior](../README.md#shared-options-and-behavior) for client configuration, validation, and errors.
+
+## Result
+
+`verdict` is `matched`, `none`, or `ambiguous`. A confident match returns the original item ID in `selection`. A low-confidence match keeps that ID only in `suggestedSelection`. `none` returns a null selection and can be `ready`; `ambiguous` always requires review. Probabilities are grouped under `candidates` by your original IDs, plus `none` and `ambiguous`.
+
+Results include model and token usage. Decisions below `minConfidence` require review. Inspect the outcome as well as the status.
+
+## Reuse and calls
+
+Uses the shared candidate-selection helper. This folder owns its selection question and input schema. A live invocation makes one logical Jev request; SDK retries can add transport attempts.
+
+## Limits
+
+Resolves a supplied reference among candidates. It does not extract references, verify identity, or authorize changes.
+
+## Example input
+
+[demo.json](demo.json) contains editable input and a hand-authored response. After installing `jev-recipes`, `npx jev-recipes demo reference-resolve` shows the result offline. The fixture is an illustration, not an accuracy measurement. `npx jev-recipes describe reference-resolve` shows the input and result schemas.

package/recipes/reference-resolve/demo.json

@@ -0,0 +1,36 @@
+{
+  "input": {
+    "message": "Please cancel the hardware order, not my subscription.",
+    "reference": "the hardware order",
+    "candidates": [
+      {
+        "id": "order",
+        "text": "A pending hardware order."
+      },
+      {
+        "id": "subscription",
+        "text": "An active monthly storage subscription."
+      }
+    ]
+  },
+  "response": {
+    "model": "demo-fixture",
+    "usage": {
+      "input_tokens": 0,
+      "output_tokens": 0
+    },
+    "answers": {
+      "decision": {
+        "type": "choice",
+        "choice": "candidate_0",
+        "confidence": 0.96,
+        "probabilities": {
+          "candidate_0": 1,
+          "candidate_1": 0,
+          "none": 0,
+          "ambiguous": 0
+        }
+      }
+    }
+  }
+}

package/recipes/repeated-attempt/README.md

@@ -0,0 +1,50 @@
+# Compare attempted approaches
+
+Does proposedAttempt use essentially the same approach as previousAttempt for objective? Rewording the same query without a material strategy change counts as the same approach.
+
+```ts
+import { repeatedAttempt } from 'jev-recipes/repeated-attempt';
+
+const result = await repeatedAttempt({
+  objective: 'Find reset documentation.',
+  previousAttempt: 'Search the help center for password reset.',
+  proposedAttempt: 'Search the same help center for reset password.',
+});
+
+console.log(result.status, result.verdict);
+```
+
+## Input
+
+| Field             | Accepts                                      |
+| ----------------- | -------------------------------------------- |
+| `objective`       | Non-empty text                               |
+| `previousAttempt` | Non-empty text                               |
+| `proposedAttempt` | Non-empty text                               |
+| `minConfidence`   | Optional number from 0 to 1; defaults to 0.8 |
+
+See [shared options and behavior](../README.md#shared-options-and-behavior) for client configuration, validation, and errors.
+
+## Result
+
+| Verdict              | Meaning                                                                    |
+| -------------------- | -------------------------------------------------------------------------- |
+| `same_approach`      | The proposed attempt repeats the material method and relevant assumptions. |
+| `different_approach` | The proposed attempt changes a material method, source, or assumption.     |
+| `unclear`            | The attempts are not described precisely enough to compare.                |
+
+The result includes `verdict`, `confidence`, and all choice `probabilities`. `unclear` always requires review, even at high confidence. Other verdicts can be ready, including negative assessments.
+
+Results include model and token usage. Decisions below `minConfidence` require review. Inspect the outcome as well as the status.
+
+## Reuse and calls
+
+Uses the shared choice helper for the Jev call and response parsing. This folder owns its question, verdict criteria, and review policy. A live invocation makes one logical Jev request; SDK retries can add transport attempts.
+
+## Limits
+
+Compares two attempts only. Counting repeats, deciding whether a retry is justified, and stopping loops belong in application code.
+
+## Example input
+
+[demo.json](demo.json) contains editable input and a hand-authored response. After installing `jev-recipes`, `npx jev-recipes demo repeated-attempt` shows the result offline. The fixture is an illustration, not an accuracy measurement. `npx jev-recipes describe repeated-attempt` shows the input and result schemas.

package/recipes/repeated-attempt/demo.json

@@ -0,0 +1,26 @@
+{
+  "input": {
+    "objective": "Find reset documentation.",
+    "previousAttempt": "Search the help center for password reset.",
+    "proposedAttempt": "Search the same help center for reset password."
+  },
+  "response": {
+    "model": "demo-fixture",
+    "usage": {
+      "input_tokens": 0,
+      "output_tokens": 0
+    },
+    "answers": {
+      "decision": {
+        "type": "choice",
+        "choice": "same_approach",
+        "confidence": 0.96,
+        "probabilities": {
+          "same_approach": 1,
+          "different_approach": 0,
+          "unclear": 0
+        }
+      }
+    }
+  }
+}

package/recipes/reply-template-match/README.md

@@ -0,0 +1,52 @@
+# Select a reply template
+
+Which supplied approved template applies to request and context? Match any stated template conditions and do not select a template that promises unsupported actions.
+
+```ts
+import { replyTemplateMatch } from 'jev-recipes/reply-template-match';
+
+const result = await replyTemplateMatch({
+  request: 'How do I reset my password?',
+  templates: [
+    {
+      id: 'reset',
+      text: 'For password reset requests: Select Forgot password on the sign-in page.',
+    },
+    {
+      id: 'invoice',
+      text: 'For invoice requests: Open Billing and select Download invoice.',
+    },
+  ],
+});
+
+console.log(result.status, result.selection);
+```
+
+## Input
+
+| Field           | Accepts                                      |
+| --------------- | -------------------------------------------- |
+| `request`       | Non-empty text                               |
+| `templates`     | 1 to 50 `{ id, text }` items with unique IDs |
+| `context`       | Optional non-empty text                      |
+| `minConfidence` | Optional number from 0 to 1; defaults to 0.8 |
+
+See [shared options and behavior](../README.md#shared-options-and-behavior) for client configuration, validation, and errors.
+
+## Result
+
+`verdict` is `matched`, `none`, or `ambiguous`. A confident match returns the original item ID in `selection`. A low-confidence match keeps that ID only in `suggestedSelection`. `none` returns a null selection and can be `ready`; `ambiguous` always requires review. Probabilities are grouped under `candidates` by your original IDs, plus `none` and `ambiguous`.
+
+Results include model and token usage. Decisions below `minConfidence` require review. Inspect the outcome as well as the status.
+
+## Reuse and calls
+
+Uses the shared candidate-selection helper. This folder owns its selection question and input schema. A live invocation makes one logical Jev request; SDK retries can add transport attempts.
+
+## Limits
+
+Selects a supplied template. It does not fill placeholders, approve its content, personalize it, or send a response.
+
+## Example input
+
+[demo.json](demo.json) contains editable input and a hand-authored response. After installing `jev-recipes`, `npx jev-recipes demo reply-template-match` shows the result offline. The fixture is an illustration, not an accuracy measurement. `npx jev-recipes describe reply-template-match` shows the input and result schemas.

package/recipes/reply-template-match/demo.json

@@ -0,0 +1,35 @@
+{
+  "input": {
+    "request": "How do I reset my password?",
+    "templates": [
+      {
+        "id": "reset",
+        "text": "For password reset requests: Select Forgot password on the sign-in page."
+      },
+      {
+        "id": "invoice",
+        "text": "For invoice requests: Open Billing and select Download invoice."
+      }
+    ]
+  },
+  "response": {
+    "model": "demo-fixture",
+    "usage": {
+      "input_tokens": 0,
+      "output_tokens": 0
+    },
+    "answers": {
+      "decision": {
+        "type": "choice",
+        "choice": "candidate_0",
+        "confidence": 0.96,
+        "probabilities": {
+          "candidate_0": 1,
+          "candidate_1": 0,
+          "none": 0,
+          "ambiguous": 0
+        }
+      }
+    }
+  }
+}

package/recipes/rerank/README.md

@@ -1,6 +1,6 @@
-# Rerank
+# Rerank evidence
 
-Rank supplied passages by how directly they help answer a query. This function does not retrieve documents or write an answer.
+Select supplied passages by how directly they help answer a query, then order them by relevance.
 
 ```ts
 import { rerank } from 'jev-recipes/rerank';
@@ -8,18 +8,48 @@ import { rerank } from 'jev-recipes/rerank';
 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.' },
+    {
+      id: 'billing',
+      text: 'Invoices appear on the Billing page.',
+    },
+    {
+      id: 'reset',
+      text: 'Select Forgot password to receive a reset link.',
+    },
   ],
-  topK: 5,
-  minRelevance: 0.5,
+  topK: 1,
 });
+
+console.log(result.items);
 ```
 
-Supply 1 to 100 items with unique, non-empty IDs and non-empty text. `topK` defaults to `5` and must be an integer from 1 to 100. `minRelevance` defaults to `0.5` and must be between 0 and 1.
+## Input
+
+| Field          | Accepts                                                                    |
+| -------------- | -------------------------------------------------------------------------- |
+| `query`        | Non-empty text describing the information needed                           |
+| `items`        | 1 to 100 `{ id, text }` items with unique non-empty IDs and non-empty text |
+| `topK`         | Optional integer from 1 to 100; defaults to 5                              |
+| `minRelevance` | Optional number from 0 to 1; defaults to 0.5                               |
+
+See [shared options and behavior](../README.md#shared-options-and-behavior) for client configuration, validation, and errors. Types are inferred from this folder's Zod 4 schemas.
+
+## Result
+
+`items` contains passages at or above `minRelevance`, ordered from highest relevance to lowest and limited to `topK`. Each item keeps its ID and text and adds `relevance`. Equal values preserve input order. The input array is not changed.
+
+`status` is `ready` when at least one passage qualifies, otherwise `review`. `evaluated` reports the number of supplied items. Relevance comes from independent yes/no questions, so values do not sum to 1 and have no separate confidence field.
+
+The result includes model and token usage. Inspect the outcome as well as its review status.
+
+## Reuse and calls
+
+Uses shared input preparation, instruction handling, the SDK client, and yes/no answer parsing. This folder owns the relevance question, filtering, and ordering. All item questions are sent in one request. A live invocation makes one logical Jev request; SDK retries can add transport attempts.
+
+## Limits
 
-One Jev call asks an independent yes/no relevance question for every item. The returned relevance values do not sum to 1 and have no separate confidence field. Results at or above the threshold are sorted, then limited to `topK`. Equal scores keep the original order. IDs and text are preserved, and the input array is not changed.
+Relevance does not establish that a passage is true or sufficient to answer the entire query. Use answerability to assess the selected evidence. This recipe does not retrieve documents or generate an answer.
 
-An empty selection returns `status: "review"`. `ready` means some candidates passed the relevance threshold; it does not establish that they completely answer the query. The result also includes the number evaluated, model, and token usage. Large passages may require fewer items to fit the provider's context limit.
+## Example input
 
-Try `npm run jev -- demo rerank` for the offline [`demo.json`](demo.json) fixture. Use `node dist/cli/index.js example rerank` to print editable input. Live retrieval quality and cost improvements have not been measured.
+[demo.json](demo.json) contains editable input and a hand-authored response. After installing `jev-recipes`, `npx jev-recipes demo rerank` shows an offline illustration, not an accuracy measurement. Use `npx jev-recipes describe rerank` to inspect the input and result schemas.

package/recipes/resolution-check/README.md

@@ -0,0 +1,49 @@
+# Check reported resolution
+
+Does message establish that the customer reports issue as resolved? Courtesy or thanks without a resolution statement is not enough. Assess the reported state, not the actual system state.
+
+```ts
+import { resolutionCheck } from 'jev-recipes/resolution-check';
+
+const result = await resolutionCheck({
+  issue: 'The customer cannot sign in.',
+  message: 'The reset worked. I can sign in now.',
+});
+
+console.log(result.status, result.verdict);
+```
+
+## Input
+
+| Field           | Accepts                                      |
+| --------------- | -------------------------------------------- |
+| `issue`         | Non-empty text                               |
+| `message`       | Non-empty text                               |
+| `context`       | Optional non-empty text                      |
+| `minConfidence` | Optional number from 0 to 1; defaults to 0.8 |
+
+See [shared options and behavior](../README.md#shared-options-and-behavior) for client configuration, validation, and errors.
+
+## Result
+
+| Verdict      | Meaning                                                                             |
+| ------------ | ----------------------------------------------------------------------------------- |
+| `resolved`   | The customer clearly reports this issue is solved or the desired outcome now works. |
+| `unresolved` | The customer clearly reports this issue persists or the attempted fix failed.       |
+| `unclear`    | The message does not establish whether this issue is resolved.                      |
+
+The result includes `verdict`, `confidence`, and all choice `probabilities`. `unclear` always requires review, even at high confidence. Other verdicts can be ready, including negative assessments.
+
+Results include model and token usage. Decisions below `minConfidence` require review. Inspect the outcome as well as the status.
+
+## Reuse and calls
+
+Uses the shared choice helper for the Jev call and response parsing. This folder owns its question, verdict criteria, and review policy. A live invocation makes one logical Jev request; SDK retries can add transport attempts.
+
+## Limits
+
+Interprets the customer report. It does not verify the system state, close a ticket, or treat courtesy alone as resolution.
+
+## Example input
+
+[demo.json](demo.json) contains editable input and a hand-authored response. After installing `jev-recipes`, `npx jev-recipes demo resolution-check` shows the result offline. The fixture is an illustration, not an accuracy measurement. `npx jev-recipes describe resolution-check` shows the input and result schemas.

package/recipes/resolution-check/demo.json

@@ -0,0 +1,25 @@
+{
+  "input": {
+    "issue": "The customer cannot sign in.",
+    "message": "The reset worked. I can sign in now."
+  },
+  "response": {
+    "model": "demo-fixture",
+    "usage": {
+      "input_tokens": 0,
+      "output_tokens": 0
+    },
+    "answers": {
+      "decision": {
+        "type": "choice",
+        "choice": "resolved",
+        "confidence": 0.96,
+        "probabilities": {
+          "resolved": 1,
+          "unresolved": 0,
+          "unclear": 0
+        }
+      }
+    }
+  }
+}

package/recipes/response-needed/README.md

@@ -0,0 +1,48 @@
+# Check whether a reply is needed
+
+Does message require a substantive reply in context? A question, request, correction needing follow-through, or unresolved issue requires a reply. A simple closing acknowledgment does not.
+
+```ts
+import { responseNeeded } from 'jev-recipes/response-needed';
+
+const result = await responseNeeded({
+  message: 'Thanks, that solved it!',
+  context: 'The assistant provided password reset instructions.',
+});
+
+console.log(result.status, result.verdict);
+```
+
+## Input
+
+| Field           | Accepts                                      |
+| --------------- | -------------------------------------------- |
+| `message`       | Non-empty text                               |
+| `context`       | Optional non-empty text                      |
+| `minConfidence` | Optional number from 0 to 1; defaults to 0.8 |
+
+See [shared options and behavior](../README.md#shared-options-and-behavior) for client configuration, validation, and errors.
+
+## Result
+
+| Verdict           | Meaning                                                                        |
+| ----------------- | ------------------------------------------------------------------------------ |
+| `reply_needed`    | The message requests or requires substantive follow-through.                   |
+| `no_reply_needed` | The message closes or acknowledges the exchange without an unresolved request. |
+| `unclear`         | The supplied context does not establish whether a response is expected.        |
+
+The result includes `verdict`, `confidence`, and all choice `probabilities`. `unclear` always requires review, even at high confidence. Other verdicts can be ready, including negative assessments.
+
+Results include model and token usage. Decisions below `minConfidence` require review. Inspect the outcome as well as the status.
+
+## Reuse and calls
+
+Uses the shared choice helper for the Jev call and response parsing. This folder owns its question, verdict criteria, and review policy. A live invocation makes one logical Jev request; SDK retries can add transport attempts.
+
+## Limits
+
+Assesses conversational need. Channel-specific response obligations and customer service policies remain application rules.
+
+## Example input
+
+[demo.json](demo.json) contains editable input and a hand-authored response. After installing `jev-recipes`, `npx jev-recipes demo response-needed` shows the result offline. The fixture is an illustration, not an accuracy measurement. `npx jev-recipes describe response-needed` shows the input and result schemas.

package/recipes/response-needed/demo.json

@@ -0,0 +1,25 @@
+{
+  "input": {
+    "message": "Thanks, that solved it!",
+    "context": "The assistant provided password reset instructions."
+  },
+  "response": {
+    "model": "demo-fixture",
+    "usage": {
+      "input_tokens": 0,
+      "output_tokens": 0
+    },
+    "answers": {
+      "decision": {
+        "type": "choice",
+        "choice": "no_reply_needed",
+        "confidence": 0.96,
+        "probabilities": {
+          "reply_needed": 0,
+          "no_reply_needed": 1,
+          "unclear": 0
+        }
+      }
+    }
+  }
+}

package/recipes/result-outcome/README.md

@@ -0,0 +1,49 @@
+# Interpret a reported tool outcome
+
+What outcome does result report for task? Judge only what the response claims. A success status for transport alone does not establish completion of the requested task.
+
+```ts
+import { resultOutcome } from 'jev-recipes/result-outcome';
+
+const result = await resultOutcome({
+  task: 'Export the customer report.',
+  result: 'The export could not be created because the account lacks export access.',
+});
+
+console.log(result.status, result.verdict);
+```
+
+## Input
+
+| Field           | Accepts                                      |
+| --------------- | -------------------------------------------- |
+| `task`          | Non-empty text                               |
+| `result`        | Non-empty text                               |
+| `minConfidence` | Optional number from 0 to 1; defaults to 0.8 |
+
+See [shared options and behavior](../README.md#shared-options-and-behavior) for client configuration, validation, and errors.
+
+## Result
+
+| Verdict           | Meaning                                                                              |
+| ----------------- | ------------------------------------------------------------------------------------ |
+| `success`         | The response explicitly reports the full requested task completed.                   |
+| `partial_success` | The response reports some requested work completed and some unfinished.              |
+| `failure`         | The response explicitly reports the requested work failed or could not be performed. |
+| `unclear`         | The response does not establish a task outcome.                                      |
+
+The result includes `verdict`, `confidence`, and all choice `probabilities`. `unclear` always requires review, even at high confidence. Other verdicts can be ready, including negative assessments.
+
+Results include model and token usage. Decisions below `minConfidence` require review. Inspect the outcome as well as the status.
+
+## Reuse and calls
+
+Uses the shared choice helper for the Jev call and response parsing. This folder owns its question, verdict criteria, and review policy. A live invocation makes one logical Jev request; SDK retries can add transport attempts.
+
+## Limits
+
+Interprets a report; it does not independently confirm an external action occurred. Prefer structured result fields when available.
+
+## Example input
+
+[demo.json](demo.json) contains editable input and a hand-authored response. After installing `jev-recipes`, `npx jev-recipes demo result-outcome` shows the result offline. The fixture is an illustration, not an accuracy measurement. `npx jev-recipes describe result-outcome` shows the input and result schemas.

package/recipes/result-outcome/demo.json

@@ -0,0 +1,26 @@
+{
+  "input": {
+    "task": "Export the customer report.",
+    "result": "The export could not be created because the account lacks export access."
+  },
+  "response": {
+    "model": "demo-fixture",
+    "usage": {
+      "input_tokens": 0,
+      "output_tokens": 0
+    },
+    "answers": {
+      "decision": {
+        "type": "choice",
+        "choice": "failure",
+        "confidence": 0.96,
+        "probabilities": {
+          "success": 0,
+          "partial_success": 0,
+          "failure": 1,
+          "unclear": 0
+        }
+      }
+    }
+  }
+}

package/recipes/result-usefulness/README.md

@@ -0,0 +1,49 @@
+# Check tool result usefulness
+
+Does result provide information useful for task? A response can be technically successful but contain no substantive information or information about a different task.
+
+```ts
+import { resultUsefulness } from 'jev-recipes/result-usefulness';
+
+const result = await resultUsefulness({
+  task: 'Find password reset instructions.',
+  result: 'Search completed successfully. No matching documents were found.',
+});
+
+console.log(result.status, result.verdict);
+```
+
+## Input
+
+| Field           | Accepts                                      |
+| --------------- | -------------------------------------------- |
+| `task`          | Non-empty text                               |
+| `result`        | Non-empty text                               |
+| `minConfidence` | Optional number from 0 to 1; defaults to 0.8 |
+
+See [shared options and behavior](../README.md#shared-options-and-behavior) for client configuration, validation, and errors.
+
+## Result
+
+| Verdict                 | Meaning                                                                           |
+| ----------------------- | --------------------------------------------------------------------------------- |
+| `useful`                | The response contains substantive information useful for the task.                |
+| `no_useful_information` | The response reports no results, an inability to help, or only empty boilerplate. |
+| `irrelevant`            | The response contains substantive information about a different task or subject.  |
+| `unclear`               | The response cannot be interpreted well enough to assess usefulness.              |
+
+The result includes `verdict`, `confidence`, and all choice `probabilities`. `unclear` always requires review, even at high confidence. Other verdicts can be ready, including negative assessments.
+
+Results include model and token usage. Decisions below `minConfidence` require review. Inspect the outcome as well as the status.
+
+## Reuse and calls
+
+Uses the shared choice helper for the Jev call and response parsing. This folder owns its question, verdict criteria, and review policy. A live invocation makes one logical Jev request; SDK retries can add transport attempts.
+
+## Limits
+
+Assesses response content, not transport success or source truth. Handle empty bodies and status codes in code.
+
+## Example input
+
+[demo.json](demo.json) contains editable input and a hand-authored response. After installing `jev-recipes`, `npx jev-recipes demo result-usefulness` shows the result offline. The fixture is an illustration, not an accuracy measurement. `npx jev-recipes describe result-usefulness` shows the input and result schemas.

package/recipes/result-usefulness/demo.json

@@ -0,0 +1,26 @@
+{
+  "input": {
+    "task": "Find password reset instructions.",
+    "result": "Search completed successfully. No matching documents were found."
+  },
+  "response": {
+    "model": "demo-fixture",
+    "usage": {
+      "input_tokens": 0,
+      "output_tokens": 0
+    },
+    "answers": {
+      "decision": {
+        "type": "choice",
+        "choice": "no_useful_information",
+        "confidence": 0.96,
+        "probabilities": {
+          "useful": 0,
+          "no_useful_information": 1,
+          "irrelevant": 0,
+          "unclear": 0
+        }
+      }
+    }
+  }
+}