jev-recipes 0.0.4 → 0.2.0

package/recipes/document-role/README.md

@@ -0,0 +1,51 @@
+# Identify document purpose
+
+What is the primary purpose of document? Judge the actual content rather than a title alone. Choose unclear if several purposes are equally central.
+
+```ts
+import { documentRole } from 'jev-recipes/document-role';
+
+const result = await documentRole({
+  document:
+    'New in this release: workspace exports now include archived reports. Fixed an invoice download error.',
+});
+
+console.log(result.status, result.verdict);
+```
+
+## Input
+
+| Field           | Accepts                                      |
+| --------------- | -------------------------------------------- |
+| `document`      | 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                                                        |
+| ----------------- | -------------------------------------------------------------- |
+| `policy`          | Defines rules, permissions, requirements, or allowed behavior. |
+| `tutorial`        | Teaches a task through a guided sequence.                      |
+| `reference`       | Describes interfaces, features, or facts for lookup.           |
+| `troubleshooting` | Helps diagnose or resolve a described problem.                 |
+| `release_note`    | Describes changes in a release or update.                      |
+| `other`           | Has a clear purpose outside the listed roles.                  |
+| `unclear`         | The primary role cannot be established.                        |
+
+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
+
+Returns one primary role from the supplied text. It does not read files, split mixed documents, or create an index.
+
+## Example input
+
+[demo.json](demo.json) contains editable input and a hand-authored response. After installing `jev-recipes`, `npx jev-recipes demo document-role` shows the result offline. The fixture is an illustration, not an accuracy measurement. `npx jev-recipes describe document-role` shows the input and result schemas.

package/recipes/document-role/demo.json

@@ -0,0 +1,28 @@
+{
+  "input": {
+    "document": "New in this release: workspace exports now include archived reports. Fixed an invoice download error."
+  },
+  "response": {
+    "model": "demo-fixture",
+    "usage": {
+      "input_tokens": 0,
+      "output_tokens": 0
+    },
+    "answers": {
+      "decision": {
+        "type": "choice",
+        "choice": "release_note",
+        "confidence": 0.96,
+        "probabilities": {
+          "policy": 0,
+          "tutorial": 0,
+          "reference": 0,
+          "troubleshooting": 0,
+          "release_note": 1,
+          "other": 0,
+          "unclear": 0
+        }
+      }
+    }
+  }
+}

package/recipes/draft-compare/README.md

@@ -0,0 +1,54 @@
+# Compare two drafts
+
+Which draft better satisfies request under rubric? Evaluate only the supplied criteria. Treat presentation order as irrelevant and allow a tie or neither.
+
+```ts
+import { draftCompare } from 'jev-recipes/draft-compare';
+
+const result = await draftCompare({
+  request: 'Explain how to reset a password.',
+  firstDraft: 'Select Forgot password on the sign-in page.',
+  secondDraft: 'Contact billing to download an invoice.',
+  rubric: 'Prefer a direct answer to the requested task.',
+});
+
+console.log(result.status, result.verdict);
+```
+
+## Input
+
+| Field           | Accepts                                      |
+| --------------- | -------------------------------------------- |
+| `request`       | Non-empty text                               |
+| `firstDraft`    | Non-empty text                               |
+| `secondDraft`   | Non-empty text                               |
+| `rubric`        | 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                                                                       |
+| --------- | ----------------------------------------------------------------------------- |
+| `first`   | Only the first draft is suitable, or it clearly better satisfies the rubric.  |
+| `second`  | Only the second draft is suitable, or it clearly better satisfies the rubric. |
+| `tie`     | Both drafts are suitable and neither is meaningfully better under the rubric. |
+| `neither` | Neither draft satisfies the request and rubric.                               |
+| `unclear` | There is insufficient information to make the comparison.                     |
+
+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
+
+Makes a relative judgment against your rubric. A preferred draft can still contain unsupported facts.
+
+## Example input
+
+[demo.json](demo.json) contains editable input and a hand-authored response. After installing `jev-recipes`, `npx jev-recipes demo draft-compare` shows the result offline. The fixture is an illustration, not an accuracy measurement. `npx jev-recipes describe draft-compare` shows the input and result schemas.

package/recipes/draft-compare/demo.json

@@ -0,0 +1,29 @@
+{
+  "input": {
+    "request": "Explain how to reset a password.",
+    "firstDraft": "Select Forgot password on the sign-in page.",
+    "secondDraft": "Contact billing to download an invoice.",
+    "rubric": "Prefer a direct answer to the requested task."
+  },
+  "response": {
+    "model": "demo-fixture",
+    "usage": {
+      "input_tokens": 0,
+      "output_tokens": 0
+    },
+    "answers": {
+      "decision": {
+        "type": "choice",
+        "choice": "first",
+        "confidence": 0.96,
+        "probabilities": {
+          "first": 1,
+          "second": 0,
+          "tie": 0,
+          "neither": 0,
+          "unclear": 0
+        }
+      }
+    }
+  }
+}

package/recipes/evidence-conflict/README.md

@@ -0,0 +1,51 @@
+# Compare evidence for conflicts
+
+Do firstPassage and secondPassage give incompatible evidence relevant to question under the same conditions? Different scopes are not automatically contradictions.
+
+```ts
+import { evidenceConflict } from 'jev-recipes/evidence-conflict';
+
+const result = await evidenceConflict({
+  question: 'Can guests export reports?',
+  firstPassage: 'Guests can export reports.',
+  secondPassage: 'Guests cannot export reports.',
+});
+
+console.log(result.status, result.verdict);
+```
+
+## Input
+
+| Field           | Accepts                                      |
+| --------------- | -------------------------------------------- |
+| `firstPassage`  | Non-empty text                               |
+| `secondPassage` | Non-empty text                               |
+| `question`      | 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                                                                            |
+| ----------------- | ---------------------------------------------------------------------------------- |
+| `compatible`      | The passages address the same scope and can both be true.                          |
+| `conflicting`     | The passages address the same scope and make incompatible claims.                  |
+| `different_scope` | The apparent comparison concerns different subjects, circumstances, or conditions. |
+| `unclear`         | The scope or meaning cannot be resolved from the supplied evidence.                |
+
+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
+
+Does not decide which source is authoritative. Exact numbers, timestamps, and version ordering should be compared in code.
+
+## Example input
+
+[demo.json](demo.json) contains editable input and a hand-authored response. After installing `jev-recipes`, `npx jev-recipes demo evidence-conflict` shows the result offline. The fixture is an illustration, not an accuracy measurement. `npx jev-recipes describe evidence-conflict` shows the input and result schemas.

package/recipes/evidence-conflict/demo.json

@@ -0,0 +1,27 @@
+{
+  "input": {
+    "question": "Can guests export reports?",
+    "firstPassage": "Guests can export reports.",
+    "secondPassage": "Guests cannot export reports."
+  },
+  "response": {
+    "model": "demo-fixture",
+    "usage": {
+      "input_tokens": 0,
+      "output_tokens": 0
+    },
+    "answers": {
+      "decision": {
+        "type": "choice",
+        "choice": "conflicting",
+        "confidence": 0.96,
+        "probabilities": {
+          "compatible": 0,
+          "conflicting": 1,
+          "different_scope": 0,
+          "unclear": 0
+        }
+      }
+    }
+  }
+}

package/recipes/evidence-novelty/README.md

@@ -0,0 +1,56 @@
+# Check new evidence
+
+Does passage add material information relevant to question beyond existingEvidence? New information may conflict with existing evidence; novelty alone is not correctness.
+
+```ts
+import { evidenceNovelty } from 'jev-recipes/evidence-novelty';
+
+const result = await evidenceNovelty({
+  question: 'How do I reset my password and when does the link expire?',
+  passage: 'Reset links expire after 30 minutes.',
+  existingEvidence: [
+    {
+      id: 'steps',
+      text: 'Select Forgot password to receive a reset link.',
+    },
+  ],
+});
+
+console.log(result.status, result.verdict);
+```
+
+## Input
+
+| Field              | Accepts                                      |
+| ------------------ | -------------------------------------------- |
+| `passage`          | Non-empty text                               |
+| `existingEvidence` | 1 to 50 `{ id, text }` items with unique IDs |
+| `question`         | 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                                                                           |
+| --------------------- | --------------------------------------------------------------------------------- |
+| `adds_information`    | The passage adds a material relevant fact or distinction not already represented. |
+| `repeats_information` | It only repeats information already represented.                                  |
+| `irrelevant`          | It contributes no information relevant to the question.                           |
+| `unclear`             | Its contribution cannot be determined from the supplied material.                 |
+
+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 novelty within the supplied set. It does not establish correctness or decide when retrieval must stop.
+
+## Example input
+
+[demo.json](demo.json) contains editable input and a hand-authored response. After installing `jev-recipes`, `npx jev-recipes demo evidence-novelty` shows the result offline. The fixture is an illustration, not an accuracy measurement. `npx jev-recipes describe evidence-novelty` shows the input and result schemas.

package/recipes/evidence-novelty/demo.json

@@ -0,0 +1,32 @@
+{
+  "input": {
+    "question": "How do I reset my password and when does the link expire?",
+    "passage": "Reset links expire after 30 minutes.",
+    "existingEvidence": [
+      {
+        "id": "steps",
+        "text": "Select Forgot password to receive a reset link."
+      }
+    ]
+  },
+  "response": {
+    "model": "demo-fixture",
+    "usage": {
+      "input_tokens": 0,
+      "output_tokens": 0
+    },
+    "answers": {
+      "decision": {
+        "type": "choice",
+        "choice": "adds_information",
+        "confidence": 0.96,
+        "probabilities": {
+          "adds_information": 1,
+          "repeats_information": 0,
+          "irrelevant": 0,
+          "unclear": 0
+        }
+      }
+    }
+  }
+}

package/recipes/fact-stability/README.md

@@ -0,0 +1,47 @@
+# Assess fact stability
+
+Is fact about an enduring or historical attribute, or a state that is expected to change? Classify the kind of information, not whether this particular fact is currently true.
+
+```ts
+import { factStability } from 'jev-recipes/fact-stability';
+
+const result = await factStability({
+  fact: 'The API is currently experiencing an outage.',
+});
+
+console.log(result.status, result.verdict);
+```
+
+## Input
+
+| Field           | Accepts                                      |
+| --------------- | -------------------------------------------- |
+| `fact`          | 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                                                                                                              |
+| ------------ | -------------------------------------------------------------------------------------------------------------------- |
+| `stable`     | The fact describes a historical event, definition, or enduring attribute unlikely to change in the relevant context. |
+| `changeable` | The fact describes a current state, preference, configuration, or other information that can change.                 |
+| `unclear`    | The kind or relevant timescale is not established.                                                                   |
+
+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
+
+Does not establish truth, expiration times, or freshness. Refresh policies and timestamp comparisons belong in code.
+
+## Example input
+
+[demo.json](demo.json) contains editable input and a hand-authored response. After installing `jev-recipes`, `npx jev-recipes demo fact-stability` shows the result offline. The fixture is an illustration, not an accuracy measurement. `npx jev-recipes describe fact-stability` shows the input and result schemas.

package/recipes/fact-stability/demo.json

@@ -0,0 +1,24 @@
+{
+  "input": {
+    "fact": "The API is currently experiencing an outage."
+  },
+  "response": {
+    "model": "demo-fixture",
+    "usage": {
+      "input_tokens": 0,
+      "output_tokens": 0
+    },
+    "answers": {
+      "decision": {
+        "type": "choice",
+        "choice": "changeable",
+        "confidence": 0.96,
+        "probabilities": {
+          "stable": 0,
+          "changeable": 1,
+          "unclear": 0
+        }
+      }
+    }
+  }
+}

package/recipes/failure-kind/README.md

@@ -0,0 +1,52 @@
+# Classify a described failure
+
+Which supplied category best describes the observed failure? Classify the described failure rather than inventing an underlying cause.
+
+```ts
+import { failureKind } from 'jev-recipes/failure-kind';
+
+const result = await failureKind({
+  failure: 'The export was rejected because the report name is missing.',
+  categories: [
+    {
+      id: 'missing-input',
+      text: 'A required input was not supplied.',
+    },
+    {
+      id: 'temporary',
+      text: 'A temporary service interruption prevented the operation.',
+    },
+  ],
+});
+
+console.log(result.status, result.selection);
+```
+
+## Input
+
+| Field           | Accepts                                      |
+| --------------- | -------------------------------------------- |
+| `failure`       | Non-empty text                               |
+| `categories`    | 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
+
+Maps text to your categories. Use structured error codes first; this recipe does not diagnose a root cause or initiate retries.
+
+## Example input
+
+[demo.json](demo.json) contains editable input and a hand-authored response. After installing `jev-recipes`, `npx jev-recipes demo failure-kind` shows the result offline. The fixture is an illustration, not an accuracy measurement. `npx jev-recipes describe failure-kind` shows the input and result schemas.

package/recipes/failure-kind/demo.json

@@ -0,0 +1,35 @@
+{
+  "input": {
+    "failure": "The export was rejected because the report name is missing.",
+    "categories": [
+      {
+        "id": "missing-input",
+        "text": "A required input was not supplied."
+      },
+      {
+        "id": "temporary",
+        "text": "A temporary service interruption prevented the operation."
+      }
+    ]
+  },
+  "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/feedback-kind/README.md

@@ -0,0 +1,51 @@
+# Classify customer feedback
+
+What is the primary kind of feedback in message? Prefer the explicit requested outcome over incidental tone. Choose unclear when several kinds are equally central.
+
+```ts
+import { feedbackKind } from 'jev-recipes/feedback-kind';
+
+const result = await feedbackKind({
+  message: 'Could you add CSV export to the activity page?',
+});
+
+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                                                                                          |
+| ----------------- | ------------------------------------------------------------------------------------------------ |
+| `bug_report`      | Reports existing functionality behaving incorrectly.                                             |
+| `feature_request` | Requests a new capability or changed behavior.                                                   |
+| `question`        | Asks for information or instructions.                                                            |
+| `praise`          | Primarily expresses positive feedback without another requested outcome.                         |
+| `complaint`       | Primarily expresses dissatisfaction without a specific bug report, feature request, or question. |
+| `other`           | The feedback has a clear purpose outside these categories.                                       |
+| `unclear`         | The primary kind cannot be established.                                                          |
+
+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
+
+Returns one primary category. It does not create a ticket, extract multiple issues, or set a priority.
+
+## Example input
+
+[demo.json](demo.json) contains editable input and a hand-authored response. After installing `jev-recipes`, `npx jev-recipes demo feedback-kind` shows the result offline. The fixture is an illustration, not an accuracy measurement. `npx jev-recipes describe feedback-kind` shows the input and result schemas.

package/recipes/feedback-kind/demo.json

@@ -0,0 +1,28 @@
+{
+  "input": {
+    "message": "Could you add CSV export to the activity page?"
+  },
+  "response": {
+    "model": "demo-fixture",
+    "usage": {
+      "input_tokens": 0,
+      "output_tokens": 0
+    },
+    "answers": {
+      "decision": {
+        "type": "choice",
+        "choice": "feature_request",
+        "confidence": 0.96,
+        "probabilities": {
+          "bug_report": 0,
+          "feature_request": 1,
+          "question": 0,
+          "praise": 0,
+          "complaint": 0,
+          "other": 0,
+          "unclear": 0
+        }
+      }
+    }
+  }
+}

package/recipes/field-select/README.md

@@ -0,0 +1,53 @@
+# Select a field value
+
+Which supplied candidate is the value of field in document? Select an existing candidate only. Do not calculate a value, invent one, or infer an unstated field.
+
+```ts
+import { fieldSelect } from 'jev-recipes/field-select';
+
+const result = await fieldSelect({
+  field: 'Invoice reference',
+  document: 'Invoice INV-2026-A. Purchase order PO-77.',
+  candidates: [
+    {
+      id: 'invoice',
+      text: 'INV-2026-A',
+    },
+    {
+      id: 'purchase-order',
+      text: 'PO-77',
+    },
+  ],
+});
+
+console.log(result.status, result.selection);
+```
+
+## Input
+
+| Field           | Accepts                                      |
+| --------------- | -------------------------------------------- |
+| `field`         | Non-empty text                               |
+| `document`      | Non-empty text                               |
+| `candidates`    | 1 to 50 `{ id, text }` items with unique IDs |
+| `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
+
+Chooses among caller-supplied candidates. Extract candidates with a parser or generator first; validate exact formats and identifiers in code.
+
+## Example input
+
+[demo.json](demo.json) contains editable input and a hand-authored response. After installing `jev-recipes`, `npx jev-recipes demo field-select` shows the result offline. The fixture is an illustration, not an accuracy measurement. `npx jev-recipes describe field-select` shows the input and result schemas.

package/recipes/field-select/demo.json

@@ -0,0 +1,36 @@
+{
+  "input": {
+    "field": "Invoice reference",
+    "document": "Invoice INV-2026-A. Purchase order PO-77.",
+    "candidates": [
+      {
+        "id": "invoice",
+        "text": "INV-2026-A"
+      },
+      {
+        "id": "purchase-order",
+        "text": "PO-77"
+      }
+    ]
+  },
+  "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
+        }
+      }
+    }
+  }
+}