jev-recipes 0.0.4 → 0.2.0

package/recipes/certainty-match/README.md

@@ -0,0 +1,49 @@
+# Check certainty wording
+
+Does the certainty expressed in draft match assessment? Treat assessment as the supplied evidence assessment and do not independently re-evaluate its truth.
+
+```ts
+import { certaintyMatch } from 'jev-recipes/certainty-match';
+
+const result = await certaintyMatch({
+  draft: 'The outage was definitely caused by the deploy.',
+  assessment: 'The deploy is one possible cause; the cause has not been established.',
+});
+
+console.log(result.status, result.verdict);
+```
+
+## Input
+
+| Field           | Accepts                                      |
+| --------------- | -------------------------------------------- |
+| `draft`         | Non-empty text                               |
+| `assessment`    | 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                                                                       |
+| ------------- | ----------------------------------------------------------------------------- |
+| `overstated`  | The draft expresses stronger certainty than the assessment supports.          |
+| `appropriate` | The draft expresses a degree of certainty consistent with the assessment.     |
+| `understated` | The draft expresses materially weaker certainty than the assessment supports. |
+| `unclear`     | The certainty levels cannot be compared from the supplied wording.            |
+
+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 wording with a supplied assessment. It does not calibrate probabilities or establish the assessment itself.
+
+## Example input
+
+[demo.json](demo.json) contains editable input and a hand-authored response. After installing `jev-recipes`, `npx jev-recipes demo certainty-match` shows the result offline. The fixture is an illustration, not an accuracy measurement. `npx jev-recipes describe certainty-match` shows the input and result schemas.

package/recipes/certainty-match/demo.json

@@ -0,0 +1,26 @@
+{
+  "input": {
+    "draft": "The outage was definitely caused by the deploy.",
+    "assessment": "The deploy is one possible cause; the cause has not been established."
+  },
+  "response": {
+    "model": "demo-fixture",
+    "usage": {
+      "input_tokens": 0,
+      "output_tokens": 0
+    },
+    "answers": {
+      "decision": {
+        "type": "choice",
+        "choice": "overstated",
+        "confidence": 0.96,
+        "probabilities": {
+          "overstated": 1,
+          "appropriate": 0,
+          "understated": 0,
+          "unclear": 0
+        }
+      }
+    }
+  }
+}

package/recipes/change-meaning/README.md

@@ -0,0 +1,49 @@
+# Assess a text revision
+
+Does the revision from before to after change material meaning, conditions, or obligations? Rephrasing that preserves the same meaning is editorial only.
+
+```ts
+import { changeMeaning } from 'jev-recipes/change-meaning';
+
+const result = await changeMeaning({
+  before: 'Guests may export reports.',
+  after: 'Only workspace owners may export reports.',
+});
+
+console.log(result.status, result.verdict);
+```
+
+## Input
+
+| Field           | Accepts                                      |
+| --------------- | -------------------------------------------- |
+| `before`        | Non-empty text                               |
+| `after`         | 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                                                                                               |
+| ----------------- | ----------------------------------------------------------------------------------------------------- |
+| `meaning_changed` | The revision changes a material fact, condition, instruction, or implication.                         |
+| `editorial_only`  | The revision preserves material meaning and changes only wording or presentation, or makes no change. |
+| `unclear`         | The material effect cannot be determined from the supplied text.                                      |
+
+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 supplied passages. It does not parse a repository diff or perform exact numeric and date comparisons.
+
+## Example input
+
+[demo.json](demo.json) contains editable input and a hand-authored response. After installing `jev-recipes`, `npx jev-recipes demo change-meaning` shows the result offline. The fixture is an illustration, not an accuracy measurement. `npx jev-recipes describe change-meaning` shows the input and result schemas.

package/recipes/change-meaning/demo.json

@@ -0,0 +1,25 @@
+{
+  "input": {
+    "before": "Guests may export reports.",
+    "after": "Only workspace owners may export reports."
+  },
+  "response": {
+    "model": "demo-fixture",
+    "usage": {
+      "input_tokens": 0,
+      "output_tokens": 0
+    },
+    "answers": {
+      "decision": {
+        "type": "choice",
+        "choice": "meaning_changed",
+        "confidence": 0.96,
+        "probabilities": {
+          "meaning_changed": 1,
+          "editorial_only": 0,
+          "unclear": 0
+        }
+      }
+    }
+  }
+}

package/recipes/citation-match/README.md

@@ -0,0 +1,51 @@
+# Match claims to citations
+
+Find passages that support a supplied claim. Each passage is checked independently against the entire claim.
+
+```ts
+import { citationMatch } from 'jev-recipes/citation-match';
+
+const result = await citationMatch({
+  claim: 'Reset links expire after 30 minutes.',
+  passages: [
+    {
+      id: 'reset',
+      text: 'Password reset links expire after 30 minutes.',
+    },
+    {
+      id: 'billing',
+      text: 'Invoices are available on the Billing page.',
+    },
+  ],
+});
+
+console.log(result.status, result.passageIds);
+```
+
+## Input
+
+| Field           | Accepts                                      |
+| --------------- | -------------------------------------------- |
+| `claim`         | Non-empty text                               |
+| `passages`      | 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
+
+`passageIds` contains every passage that independently supports the entire claim at or above the confidence threshold. `checks` preserves the verification result for each passage. If any passage qualifies, overall status is `ready`, even if other checks need review. With no qualifying passage, uncertainty produces `review`; otherwise a confident no-match returns `ready` with an empty list.
+
+Results include model and token usage. Decisions below `minConfidence` require review. Inspect the outcome as well as the status.
+
+## Reuse and calls
+
+Uses the public [`verify`](../verify/README.md) recipe once, with one claim/evidence pair per passage. It adds selection of confidently supported passage IDs. A live invocation makes one logical Jev request; SDK retries can add transport attempts. All item questions are sent in that request.
+
+## Limits
+
+Returns passages that independently support the entire claim. Joint support across several individually incomplete passages is not assessed.
+
+## Example input
+
+[demo.json](demo.json) contains editable input and a hand-authored response. After installing `jev-recipes`, `npx jev-recipes demo citation-match` shows the result offline. The fixture is an illustration, not an accuracy measurement. `npx jev-recipes describe citation-match` shows the input and result schemas.

package/recipes/citation-match/demo.json

@@ -0,0 +1,44 @@
+{
+  "input": {
+    "claim": "Reset links expire after 30 minutes.",
+    "passages": [
+      {
+        "id": "reset",
+        "text": "Password reset links expire after 30 minutes."
+      },
+      {
+        "id": "billing",
+        "text": "Invoices are available on the Billing page."
+      }
+    ]
+  },
+  "response": {
+    "model": "demo-fixture",
+    "usage": {
+      "input_tokens": 0,
+      "output_tokens": 0
+    },
+    "answers": {
+      "claim_0": {
+        "type": "choice",
+        "choice": "supported",
+        "confidence": 0.96,
+        "probabilities": {
+          "supported": 1,
+          "contradicted": 0,
+          "unsupported": 0
+        }
+      },
+      "claim_1": {
+        "type": "choice",
+        "choice": "unsupported",
+        "confidence": 0.96,
+        "probabilities": {
+          "supported": 0,
+          "contradicted": 0,
+          "unsupported": 1
+        }
+      }
+    }
+  }
+}

package/recipes/citation-needed/README.md

@@ -0,0 +1,49 @@
+# Check citation requirements
+
+Do citationRules require evidence for statement? Apply the supplied rules rather than an unstated citation policy.
+
+```ts
+import { citationNeeded } from 'jev-recipes/citation-needed';
+
+const result = await citationNeeded({
+  statement: 'Reset links expire after 30 minutes.',
+  citationRules:
+    'Cite documentation for claims about product behavior. Greetings need no citations.',
+});
+
+console.log(result.status, result.verdict);
+```
+
+## Input
+
+| Field           | Accepts                                      |
+| --------------- | -------------------------------------------- |
+| `statement`     | Non-empty text                               |
+| `citationRules` | 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                                                                                          |
+| ------------- | ------------------------------------------------------------------------------------------------ |
+| `needed`      | The statement falls within a category requiring citation under the supplied rules.               |
+| `unnecessary` | The supplied rules explicitly exempt this statement or clearly do not require a citation for it. |
+| `unclear`     | The rules or statement do not establish whether a citation is required.                          |
+
+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 a supplied citation policy; does not find sources or determine whether a statement is true.
+
+## Example input
+
+[demo.json](demo.json) contains editable input and a hand-authored response. After installing `jev-recipes`, `npx jev-recipes demo citation-needed` shows the result offline. The fixture is an illustration, not an accuracy measurement. `npx jev-recipes describe citation-needed` shows the input and result schemas.

package/recipes/citation-needed/demo.json

@@ -0,0 +1,25 @@
+{
+  "input": {
+    "statement": "Reset links expire after 30 minutes.",
+    "citationRules": "Cite documentation for claims about product behavior. Greetings need no citations."
+  },
+  "response": {
+    "model": "demo-fixture",
+    "usage": {
+      "input_tokens": 0,
+      "output_tokens": 0
+    },
+    "answers": {
+      "decision": {
+        "type": "choice",
+        "choice": "needed",
+        "confidence": 0.96,
+        "probabilities": {
+          "needed": 1,
+          "unnecessary": 0,
+          "unclear": 0
+        }
+      }
+    }
+  }
+}

package/recipes/clarify/README.md

@@ -1,6 +1,6 @@
-# Clarify
+# Check required information
 
-Check whether a request supplies the information your application needs. You define the requirements; the recipe identifies which ones are present, missing, or ambiguous.
+Identify which supplied requirements are present, missing, or ambiguous in a request and its context.
 
 ```ts
 import { clarify } from 'jev-recipes/clarify';
@@ -9,24 +9,53 @@ 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' },
+    {
+      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);
+console.log(result.canProceed);
 ```
 
-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.
+## Input
 
-- `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.
+| Field           | Accepts                                                                                  |
+| --------------- | ---------------------------------------------------------------------------------------- |
+| `request`       | Non-empty text containing the request                                                    |
+| `context`       | Optional non-empty conversation context or application facts                             |
+| `requirements`  | 1 to 50 `{ id, description }` items with unique non-empty IDs and non-empty descriptions |
+| `minConfidence` | Optional number from 0 to 1; defaults to 0.8                                             |
 
-`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.
+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.
 
-A `ready` result can still require clarification. Each check includes its verdict, confidence, and probabilities; the result also includes model and token usage.
+## Result
 
-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.
+| Verdict     | Meaning                                                                     |
+| ----------- | --------------------------------------------------------------------------- |
+| `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. |
 
-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.
+`checks` preserves each requirement ID with its verdict, status, confidence, and probabilities. A check is ready when its confidence reaches `minConfidence`. Overall `status` is `review` if any check falls below the threshold.
+
+`canProceed` is true only when every check is ready and present. `missing` and `ambiguous` contain confidently classified requirement IDs. A confident ambiguity assessment can be ready while `canProceed` remains false. Low-confidence checks also block proceeding, even if both ID lists are empty.
+
+The result includes model and token usage. Inspect the outcome as well as its review status.
+
+## Reuse and calls
+
+Uses the shared item-check helper. This folder owns the requirement criteria, follow-up ID lists, and can-proceed decision. All requirement questions are sent in one request. A live invocation makes one logical Jev request; SDK retries can add transport attempts.
+
+## Limits
+
+Your application supplies the requirements and maps their IDs to follow-up questions. The recipe does not discover requirements, generate questions, validate identity, or enforce exact field formats.
+
+## Example input
+
+[demo.json](demo.json) contains editable input and a hand-authored response. After installing `jev-recipes`, `npx jev-recipes demo clarify` shows an offline illustration, not an accuracy measurement. Use `npx jev-recipes describe clarify` to inspect the input and result schemas.

package/recipes/confirmation-match/README.md

@@ -0,0 +1,49 @@
+# Interpret a confirmation
+
+Does response clearly agree to or reject this exact proposal? Do not treat politeness, acknowledgment, a question, or agreement to only part of the proposal as full agreement.
+
+```ts
+import { confirmationMatch } from 'jev-recipes/confirmation-match';
+
+const result = await confirmationMatch({
+  proposal: 'Cancel the storage subscription now.',
+  response: 'How much would I save?',
+});
+
+console.log(result.status, result.verdict);
+```
+
+## Input
+
+| Field           | Accepts                                      |
+| --------------- | -------------------------------------------- |
+| `proposal`      | Non-empty text                               |
+| `response`      | 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                                                                                |
+| --------- | -------------------------------------------------------------------------------------- |
+| `agrees`  | The response clearly agrees to this complete proposal.                                 |
+| `rejects` | The response clearly rejects this proposal.                                            |
+| `unclear` | The response is conditional, partial, ambiguous, unrelated, or only an acknowledgment. |
+
+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 language only. Approval identity, authority, scope, expiration, and action permissions remain application checks.
+
+## Example input
+
+[demo.json](demo.json) contains editable input and a hand-authored response. After installing `jev-recipes`, `npx jev-recipes demo confirmation-match` shows the result offline. The fixture is an illustration, not an accuracy measurement. `npx jev-recipes describe confirmation-match` shows the input and result schemas.

package/recipes/confirmation-match/demo.json

@@ -0,0 +1,25 @@
+{
+  "input": {
+    "proposal": "Cancel the storage subscription now.",
+    "response": "How much would I save?"
+  },
+  "response": {
+    "model": "demo-fixture",
+    "usage": {
+      "input_tokens": 0,
+      "output_tokens": 0
+    },
+    "answers": {
+      "decision": {
+        "type": "choice",
+        "choice": "unclear",
+        "confidence": 0.96,
+        "probabilities": {
+          "agrees": 0,
+          "rejects": 0,
+          "unclear": 1
+        }
+      }
+    }
+  }
+}

package/recipes/context-role/README.md

@@ -0,0 +1,49 @@
+# Identify a passage role
+
+What role does passage play in answering question? Classify its contribution without establishing whether its claims are true.
+
+```ts
+import { contextRole } from 'jev-recipes/context-role';
+
+const result = await contextRole({
+  question: 'How do I reset my password?',
+  passage: 'Passwords help protect access to accounts.',
+});
+
+console.log(result.status, result.verdict);
+```
+
+## Input
+
+| Field           | Accepts                                      |
+| --------------- | -------------------------------------------- |
+| `question`      | Non-empty text                               |
+| `passage`       | 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                                                                          |
+| ----------------- | -------------------------------------------------------------------------------- |
+| `direct_evidence` | The passage directly supplies information needed to answer the question.         |
+| `background`      | The passage helps interpret the topic but does not directly answer the question. |
+| `unrelated`       | The passage contributes neither an answer nor useful background.                 |
+| `unclear`         | Its relationship to the question 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
+
+Classifies a passage contribution. It does not rank sources or prove the answer is supported.
+
+## Example input
+
+[demo.json](demo.json) contains editable input and a hand-authored response. After installing `jev-recipes`, `npx jev-recipes demo context-role` shows the result offline. The fixture is an illustration, not an accuracy measurement. `npx jev-recipes describe context-role` shows the input and result schemas.

package/recipes/context-role/demo.json

@@ -0,0 +1,26 @@
+{
+  "input": {
+    "question": "How do I reset my password?",
+    "passage": "Passwords help protect access to accounts."
+  },
+  "response": {
+    "model": "demo-fixture",
+    "usage": {
+      "input_tokens": 0,
+      "output_tokens": 0
+    },
+    "answers": {
+      "decision": {
+        "type": "choice",
+        "choice": "background",
+        "confidence": 0.96,
+        "probabilities": {
+          "direct_evidence": 0,
+          "background": 1,
+          "unrelated": 0,
+          "unclear": 0
+        }
+      }
+    }
+  }
+}

package/recipes/correction-target/README.md

@@ -0,0 +1,52 @@
+# Locate a correction target
+
+Which supplied field or statement is message correcting? Identify the target, not the replacement value. Use ambiguous when the message corrects multiple targets without a single primary target.
+
+```ts
+import { correctionTarget } from 'jev-recipes/correction-target';
+
+const result = await correctionTarget({
+  message: 'The billing email is finance@example.com, not support@example.com.',
+  targets: [
+    {
+      id: 'billing-email',
+      text: 'Billing email: support@example.com',
+    },
+    {
+      id: 'shipping-city',
+      text: 'Shipping city: Portland',
+    },
+  ],
+});
+
+console.log(result.status, result.selection);
+```
+
+## Input
+
+| Field           | Accepts                                      |
+| --------------- | -------------------------------------------- |
+| `message`       | Non-empty text                               |
+| `targets`       | 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 one correction target. It does not extract a replacement value or update a record.
+
+## Example input
+
+[demo.json](demo.json) contains editable input and a hand-authored response. After installing `jev-recipes`, `npx jev-recipes demo correction-target` shows the result offline. The fixture is an illustration, not an accuracy measurement. `npx jev-recipes describe correction-target` shows the input and result schemas.

package/recipes/correction-target/demo.json

@@ -0,0 +1,35 @@
+{
+  "input": {
+    "message": "The billing email is finance@example.com, not support@example.com.",
+    "targets": [
+      {
+        "id": "billing-email",
+        "text": "Billing email: support@example.com"
+      },
+      {
+        "id": "shipping-city",
+        "text": "Shipping city: Portland"
+      }
+    ]
+  },
+  "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
+        }
+      }
+    }
+  }
+}