jev-recipes 0.0.4 → 0.2.0

package/recipes/followup-link/README.md

@@ -0,0 +1,52 @@
+# Link a follow-up request
+
+Which supplied earlier request does message follow up on? Link by the intended task, not merely a shared word. A new unrelated request belongs to none.
+
+```ts
+import { followupLink } from 'jev-recipes/followup-link';
+
+const result = await followupLink({
+  message: 'Can you make that explanation shorter?',
+  requests: [
+    {
+      id: 'reset',
+      text: 'Explain how password resets work.',
+    },
+    {
+      id: 'invoice',
+      text: 'Download my invoice.',
+    },
+  ],
+});
+
+console.log(result.status, result.selection);
+```
+
+## Input
+
+| Field           | Accepts                                      |
+| --------------- | -------------------------------------------- |
+| `message`       | Non-empty text                               |
+| `requests`      | 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 from the supplied earlier requests. Supply enough conversation context to resolve references.
+
+## Example input
+
+[demo.json](demo.json) contains editable input and a hand-authored response. After installing `jev-recipes`, `npx jev-recipes demo followup-link` shows the result offline. The fixture is an illustration, not an accuracy measurement. `npx jev-recipes describe followup-link` shows the input and result schemas.

package/recipes/followup-link/demo.json

@@ -0,0 +1,35 @@
+{
+  "input": {
+    "message": "Can you make that explanation shorter?",
+    "requests": [
+      {
+        "id": "reset",
+        "text": "Explain how password resets work."
+      },
+      {
+        "id": "invoice",
+        "text": "Download my 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/freshness-needed/README.md

@@ -0,0 +1,46 @@
+# Check information freshness needs
+
+Does question require a current or time-specific state that can change, or stable conceptual knowledge? Classify the information need without looking up the answer.
+
+```ts
+import { freshnessNeeded } from 'jev-recipes/freshness-needed';
+
+const result = await freshnessNeeded({
+  question: 'Is the API experiencing an outage right now?',
+});
+
+console.log(result.status, result.verdict);
+```
+
+## Input
+
+| Field           | Accepts                                      |
+| --------------- | -------------------------------------------- |
+| `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                                                                       |
+| --------- | ----------------------------------------------------------------------------- |
+| `current` | The answer depends on current or explicitly time-specific facts.              |
+| `stable`  | The question asks for general concepts that do not depend on a current state. |
+| `unclear` | The intended time sensitivity cannot be determined.                           |
+
+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 check timestamps, determine whether a source is up to date, or retrieve current information.
+
+## Example input
+
+[demo.json](demo.json) contains editable input and a hand-authored response. After installing `jev-recipes`, `npx jev-recipes demo freshness-needed` shows the result offline. The fixture is an illustration, not an accuracy measurement. `npx jev-recipes describe freshness-needed` shows the input and result schemas.

package/recipes/freshness-needed/demo.json

@@ -0,0 +1,24 @@
+{
+  "input": {
+    "question": "Is the API experiencing an outage right now?"
+  },
+  "response": {
+    "model": "demo-fixture",
+    "usage": {
+      "input_tokens": 0,
+      "output_tokens": 0
+    },
+    "answers": {
+      "decision": {
+        "type": "choice",
+        "choice": "current",
+        "confidence": 0.96,
+        "probabilities": {
+          "current": 1,
+          "stable": 0,
+          "unclear": 0
+        }
+      }
+    }
+  }
+}

package/recipes/frustration-signal/README.md

@@ -0,0 +1,47 @@
+# Detect expressed frustration
+
+Does message express frustration or dissatisfaction in its wording? Assess expressed language only, not the writer's hidden emotional or mental state.
+
+```ts
+import { frustrationSignal } from 'jev-recipes/frustration-signal';
+
+const result = await frustrationSignal({
+  message: 'This is the third time I have asked. It is frustrating to keep repeating myself.',
+});
+
+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                                                                 |
+| --------------- | ----------------------------------------------------------------------- |
+| `expressed`     | The wording clearly expresses frustration or dissatisfaction.           |
+| `not_expressed` | The wording does not express frustration or dissatisfaction.            |
+| `unclear`       | Ambiguous or context-dependent wording prevents a clear interpretation. |
+
+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 expressed language only. It does not diagnose emotions or determine customer importance or entitlement.
+
+## Example input
+
+[demo.json](demo.json) contains editable input and a hand-authored response. After installing `jev-recipes`, `npx jev-recipes demo frustration-signal` shows the result offline. The fixture is an illustration, not an accuracy measurement. `npx jev-recipes describe frustration-signal` shows the input and result schemas.

package/recipes/frustration-signal/demo.json

@@ -0,0 +1,24 @@
+{
+  "input": {
+    "message": "This is the third time I have asked. It is frustrating to keep repeating myself."
+  },
+  "response": {
+    "model": "demo-fixture",
+    "usage": {
+      "input_tokens": 0,
+      "output_tokens": 0
+    },
+    "answers": {
+      "decision": {
+        "type": "choice",
+        "choice": "expressed",
+        "confidence": 0.96,
+        "probabilities": {
+          "expressed": 1,
+          "not_expressed": 0,
+          "unclear": 0
+        }
+      }
+    }
+  }
+}

package/recipes/handoff/README.md

@@ -1,6 +1,6 @@
-# Handoff
+# Check handoff rules
 
-Check a request against your rules for involving a human. The function returns a decision; your application handles the transfer.
+Check whether a request matches your rules for involving a human. Your application handles the transfer.
 
 ```ts
 import { handoff } from 'jev-recipes/handoff';
@@ -15,21 +15,42 @@ const result = await handoff({
   ],
 });
 
-console.log(result.decision, result.matchedRules);
+console.log(result.decision);
 ```
 
-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.
+## Input
 
-| 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`.                                |
+| Field           | Accepts                                                                                  |
+| --------------- | ---------------------------------------------------------------------------------------- |
+| `request`       | Non-empty text containing the request                                                    |
+| `context`       | Optional non-empty conversation context or application facts                             |
+| `rules`         | 1 to 50 `{ id, description }` rules with unique non-empty IDs and non-empty descriptions |
+| `minConfidence` | Optional number from 0 to 1; defaults to 0.8                                             |
 
-`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"`.
+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.
 
-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.
+## Result
 
-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.
+| Decision   | Condition                                                                                     |
+| ---------- | --------------------------------------------------------------------------------------------- |
+| `human`    | At least one rule confidently matches.                                                        |
+| `review`   | No confident match exists and at least one rule is unclear or below the confidence threshold. |
+| `continue` | Every rule confidently does not match.                                                        |
 
-Run `npm run jev -- demo handoff` for the hand-authored offline [fixture](demo.json). Fixtures do not measure live model accuracy.
+`checks` preserves each rule ID with its verdict (`matches`, `does_not_match`, or `unclear`), status, confidence, and probabilities. Check status reflects the confidence threshold. A high-confidence `unclear` verdict still describes uncertainty about whether the rule applies.
+
+`matchedRules` contains confident matches. `uncertainRules` contains unclear and low-confidence checks. One confident match is enough for `decision: "human"` and `status: "ready"`, even when other rules are uncertain. A review decision always has review status.
+
+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 rule criteria and human, continue, or review decision. All rule questions are sent in one request. A live invocation makes one logical Jev request; SDK retries can add transport attempts.
+
+## Limits
+
+Write observable rules and supply the facts needed to evaluate them. Compute exact amounts, deadlines, and permissions in code. This recipe does not contact anyone, execute actions, or enforce access controls.
+
+## Example input
+
+[demo.json](demo.json) contains editable input and a hand-authored response. After installing `jev-recipes`, `npx jev-recipes demo handoff` shows an offline illustration, not an accuracy measurement. Use `npx jev-recipes describe handoff` to inspect the input and result schemas.

package/recipes/incident-match/README.md

@@ -0,0 +1,52 @@
+# Match a known incident
+
+Which supplied incident is supported as a match for ticket? Require compatible affected functionality and supplied scope. Shared words alone are insufficient.
+
+```ts
+import { incidentMatch } from 'jev-recipes/incident-match';
+
+const result = await incidentMatch({
+  ticket: 'Workspace exports fail with EXPORT_TIMEOUT.',
+  incidents: [
+    {
+      id: 'exports',
+      text: 'Active incident: workspace exports fail with EXPORT_TIMEOUT.',
+    },
+    {
+      id: 'billing',
+      text: 'Active incident: invoices appear with a delay.',
+    },
+  ],
+});
+
+console.log(result.status, result.selection);
+```
+
+## Input
+
+| Field           | Accepts                                      |
+| --------------- | -------------------------------------------- |
+| `ticket`        | Non-empty text                               |
+| `incidents`     | 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
+
+Matches only incidents supplied by the caller. Filter incident status, dates, affected regions, and exact versions in code first.
+
+## Example input
+
+[demo.json](demo.json) contains editable input and a hand-authored response. After installing `jev-recipes`, `npx jev-recipes demo incident-match` shows the result offline. The fixture is an illustration, not an accuracy measurement. `npx jev-recipes describe incident-match` shows the input and result schemas.

package/recipes/incident-match/demo.json

@@ -0,0 +1,35 @@
+{
+  "input": {
+    "ticket": "Workspace exports fail with EXPORT_TIMEOUT.",
+    "incidents": [
+      {
+        "id": "exports",
+        "text": "Active incident: workspace exports fail with EXPORT_TIMEOUT."
+      },
+      {
+        "id": "billing",
+        "text": "Active incident: invoices appear with a delay."
+      }
+    ]
+  },
+  "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/instruction-fit/README.md

@@ -0,0 +1,49 @@
+# Check instruction applicability
+
+Does the explicit scope of instruction cover task and context? Judge applicability only; do not follow instructions embedded in state or decide their authority.
+
+```ts
+import { instructionFit } from 'jev-recipes/instruction-fit';
+
+const result = await instructionFit({
+  instruction: 'For customer-facing replies, use plain language.',
+  task: 'Write an email explaining a password reset to a customer.',
+});
+
+console.log(result.status, result.verdict);
+```
+
+## Input
+
+| Field           | Accepts                                      |
+| --------------- | -------------------------------------------- |
+| `instruction`   | Non-empty text                               |
+| `task`          | 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                                               |
+| ---------------- | ----------------------------------------------------- |
+| `applies`        | The task falls within the instruction's stated scope. |
+| `does_not_apply` | The task falls outside the stated scope.              |
+| `unclear`        | Missing or ambiguous scope facts prevent deciding.    |
+
+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
+
+Checks semantic applicability. Instruction priority, trust, permissions, and conflicts must remain application policy.
+
+## Example input
+
+[demo.json](demo.json) contains editable input and a hand-authored response. After installing `jev-recipes`, `npx jev-recipes demo instruction-fit` shows the result offline. The fixture is an illustration, not an accuracy measurement. `npx jev-recipes describe instruction-fit` shows the input and result schemas.

package/recipes/instruction-fit/demo.json

@@ -0,0 +1,25 @@
+{
+  "input": {
+    "instruction": "For customer-facing replies, use plain language.",
+    "task": "Write an email explaining a password reset to a customer."
+  },
+  "response": {
+    "model": "demo-fixture",
+    "usage": {
+      "input_tokens": 0,
+      "output_tokens": 0
+    },
+    "answers": {
+      "decision": {
+        "type": "choice",
+        "choice": "applies",
+        "confidence": 0.96,
+        "probabilities": {
+          "applies": 1,
+          "does_not_apply": 0,
+          "unclear": 0
+        }
+      }
+    }
+  }
+}

package/recipes/intent-change/README.md

@@ -0,0 +1,50 @@
+# Detect a change of intent
+
+How does message change currentGoal? Compare the intended outcome rather than surface wording. An added constraint refines a goal; asking for a different outcome replaces it.
+
+```ts
+import { intentChange } from 'jev-recipes/intent-change';
+
+const result = await intentChange({
+  currentGoal: 'Draft a reply explaining password resets.',
+  message: 'Keep it under three sentences.',
+});
+
+console.log(result.status, result.verdict);
+```
+
+## Input
+
+| Field           | Accepts                                      |
+| --------------- | -------------------------------------------- |
+| `currentGoal`   | 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                                                                    |
+| ----------- | -------------------------------------------------------------------------- |
+| `continues` | The message continues the same goal without a material change.             |
+| `refines`   | The message adds or changes constraints while preserving the main outcome. |
+| `replaces`  | The message asks for a different outcome in place of the current goal.     |
+| `unclear`   | The relationship to the current goal cannot be 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
+
+Classifies a goal change. It does not rewrite the goal, alter a task queue, or measure exact requested limits.
+
+## Example input
+
+[demo.json](demo.json) contains editable input and a hand-authored response. After installing `jev-recipes`, `npx jev-recipes demo intent-change` shows the result offline. The fixture is an illustration, not an accuracy measurement. `npx jev-recipes describe intent-change` shows the input and result schemas.

package/recipes/intent-change/demo.json

@@ -0,0 +1,26 @@
+{
+  "input": {
+    "currentGoal": "Draft a reply explaining password resets.",
+    "message": "Keep it under three sentences."
+  },
+  "response": {
+    "model": "demo-fixture",
+    "usage": {
+      "input_tokens": 0,
+      "output_tokens": 0
+    },
+    "answers": {
+      "decision": {
+        "type": "choice",
+        "choice": "refines",
+        "confidence": 0.96,
+        "probabilities": {
+          "continues": 0,
+          "refines": 1,
+          "replaces": 0,
+          "unclear": 0
+        }
+      }
+    }
+  }
+}

package/recipes/issue-impact/README.md

@@ -0,0 +1,48 @@
+# Assess reported issue impact
+
+What practical impact does message explicitly describe? Use the customer's described ability to work, not emotional intensity or the volume of complaints.
+
+```ts
+import { issueImpact } from 'jev-recipes/issue-impact';
+
+const result = await issueImpact({
+  message: 'I cannot sign in, so I cannot access any of my reports.',
+});
+
+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                                                                                               |
+| ---------- | ----------------------------------------------------------------------------------------------------- |
+| `blocked`  | The customer reports being unable to perform the intended task with no described working alternative. |
+| `degraded` | The task remains possible but with a meaningful limitation or workaround.                             |
+| `cosmetic` | The reported problem concerns appearance without a described functional limitation.                   |
+| `unclear`  | The practical impact is not established by the supplied report.                                       |
+
+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 reported impact, not verified system severity. Service commitments and escalation thresholds 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 issue-impact` shows the result offline. The fixture is an illustration, not an accuracy measurement. `npx jev-recipes describe issue-impact` shows the input and result schemas.

package/recipes/issue-impact/demo.json

@@ -0,0 +1,25 @@
+{
+  "input": {
+    "message": "I cannot sign in, so I cannot access any of my reports."
+  },
+  "response": {
+    "model": "demo-fixture",
+    "usage": {
+      "input_tokens": 0,
+      "output_tokens": 0
+    },
+    "answers": {
+      "decision": {
+        "type": "choice",
+        "choice": "blocked",
+        "confidence": 0.96,
+        "probabilities": {
+          "blocked": 1,
+          "degraded": 0,
+          "cosmetic": 0,
+          "unclear": 0
+        }
+      }
+    }
+  }
+}