jev-recipes 0.0.4 → 0.2.0

package/recipes/retrieval-needed/README.md

@@ -0,0 +1,48 @@
+# Check whether retrieval is needed
+
+Does request require facts beyond context? A request to transform or summarize supplied material does not need outside facts unless the request explicitly asks for them.
+
+```ts
+import { retrievalNeeded } from 'jev-recipes/retrieval-needed';
+
+const result = await retrievalNeeded({
+  request: 'Summarize this policy in one sentence.',
+  context: 'Customers may cancel their subscription from Account settings.',
+});
+
+console.log(result.status, result.verdict);
+```
+
+## Input
+
+| Field           | Accepts                                      |
+| --------------- | -------------------------------------------- |
+| `request`       | Non-empty text                               |
+| `context`       | 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`      | Answering the request requires information missing from the supplied context. |
+| `unnecessary` | The requested work can be completed using only the supplied context.          |
+| `unclear`     | The request is too ambiguous to establish its information needs.              |
+
+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 information needs without searching. A no-retrieval decision does not establish source truth.
+
+## Example input
+
+[demo.json](demo.json) contains editable input and a hand-authored response. After installing `jev-recipes`, `npx jev-recipes demo retrieval-needed` shows the result offline. The fixture is an illustration, not an accuracy measurement. `npx jev-recipes describe retrieval-needed` shows the input and result schemas.

package/recipes/retrieval-needed/demo.json

@@ -0,0 +1,25 @@
+{
+  "input": {
+    "request": "Summarize this policy in one sentence.",
+    "context": "Customers may cancel their subscription from Account settings."
+  },
+  "response": {
+    "model": "demo-fixture",
+    "usage": {
+      "input_tokens": 0,
+      "output_tokens": 0
+    },
+    "answers": {
+      "decision": {
+        "type": "choice",
+        "choice": "unnecessary",
+        "confidence": 0.96,
+        "probabilities": {
+          "needed": 0,
+          "unnecessary": 1,
+          "unclear": 0
+        }
+      }
+    }
+  }
+}

package/recipes/route/README.md

@@ -1,6 +1,6 @@
-# Route
+# Route a request
 
-Choose a handler for a request. This function returns a decision and never executes the handler.
+Choose a handler from the routes you supply. The recipe returns the selection; your application runs the handler.
 
 ```ts
 import { route } from 'jev-recipes/route';
@@ -11,14 +11,37 @@ const result = await route({
     billing: 'Payments, invoices, subscriptions, and refunds',
     technical: 'Errors, outages, and broken integrations',
   },
-  minConfidence: 0.8,
 });
+
+console.log(result.route);
 ```
 
-Provide 1 to 254 route names and non-empty descriptions. The recipe adds a reserved `__review__` option for ambiguous requests or requests with no suitable handler. Do not use that name for your own route.
+## Input
+
+| Field           | Accepts                                                                   |
+| --------------- | ------------------------------------------------------------------------- |
+| `request`       | Non-empty text describing the request                                     |
+| `routes`        | 1 to 254 non-empty route names and descriptions; `__review__` is reserved |
+| `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. Types are inferred from this folder's Zod 4 schemas.
+
+## Result
+
+A confident selection returns `status: "ready"` and the route name in `route`. A low-confidence result or the reserved `__review__` choice returns `status: "review"` and a null `route`.
+
+`suggestedRoute` preserves a low-confidence suggestion. It is null when no route is selected. `confidence` and `probabilities` describe the model decision, including the `__review__` option.
+
+The result includes model and token usage. Inspect the outcome as well as its review status.
+
+## Reuse and calls
+
+Uses the shared choice helper. This folder owns the routing question, route criteria, and review policy. A live invocation makes one logical Jev request; SDK retries can add transport attempts.
+
+## Limits
 
-`minConfidence` defaults to `0.8`. At or above the threshold, a non-review selection returns `status: "ready"` and `route`. Below the threshold, or when Jev selects `__review__`, `route` is null and `status` is `review`. `suggestedRoute` preserves a low-confidence model suggestion for inspection; it is not an accepted decision.
+Routes with overlapping descriptions can be difficult to distinguish. Describe their responsibilities clearly. Routing does not execute handlers or establish permission to act.
 
-Results include confidence, the complete choice probability distribution (including `__review__`), model, and token usage. Describe overlapping routes carefully. Confidence does not guarantee correctness.
+## Example input
 
-Try `npm run jev -- demo route` for the offline [`demo.json`](demo.json) fixture. Use `node dist/cli/index.js example route` to print editable input for a live run. Live routing accuracy has not been measured.
+[demo.json](demo.json) contains editable input and a hand-authored response. After installing `jev-recipes`, `npx jev-recipes demo route` shows an offline illustration, not an accuracy measurement. Use `npx jev-recipes describe route` to inspect the input and result schemas.

package/recipes/source-applicability/README.md

@@ -0,0 +1,48 @@
+# Check source applicability
+
+Does the scope described in passage apply to scenario? Distinguish applicable information from information about another product, environment, role, or condition.
+
+```ts
+import { sourceApplicability } from 'jev-recipes/source-applicability';
+
+const result = await sourceApplicability({
+  passage: 'Workspace owners can delete the workspace. These instructions are for owners only.',
+  scenario: 'A workspace guest wants to delete the workspace.',
+});
+
+console.log(result.status, result.verdict);
+```
+
+## Input
+
+| Field           | Accepts                                      |
+| --------------- | -------------------------------------------- |
+| `passage`       | Non-empty text                               |
+| `scenario`      | 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 passage explicitly covers or unambiguously applies to the scenario. |
+| `does_not_apply` | The passage is scoped to incompatible circumstances.                    |
+| `unclear`        | Required scope information is missing or ambiguous.                     |
+
+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 semantic scope. Enforce tenant, access, exact version, and region constraints 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 source-applicability` shows the result offline. The fixture is an illustration, not an accuracy measurement. `npx jev-recipes describe source-applicability` shows the input and result schemas.

package/recipes/source-applicability/demo.json

@@ -0,0 +1,25 @@
+{
+  "input": {
+    "passage": "Workspace owners can delete the workspace. These instructions are for owners only.",
+    "scenario": "A workspace guest wants to delete the workspace."
+  },
+  "response": {
+    "model": "demo-fixture",
+    "usage": {
+      "input_tokens": 0,
+      "output_tokens": 0
+    },
+    "answers": {
+      "decision": {
+        "type": "choice",
+        "choice": "does_not_apply",
+        "confidence": 0.96,
+        "probabilities": {
+          "applies": 0,
+          "does_not_apply": 1,
+          "unclear": 0
+        }
+      }
+    }
+  }
+}

package/recipes/step-complete/README.md

@@ -0,0 +1,48 @@
+# Check one completion condition
+
+Does evidence establish that condition has been met? A plan, attempted action, or unsupported assertion of completion is not enough unless the condition specifically concerns that report.
+
+```ts
+import { stepComplete } from 'jev-recipes/step-complete';
+
+const result = await stepComplete({
+  condition: 'The customer has received a reset email.',
+  evidence: 'A reset email was queued for delivery. Delivery has not been confirmed.',
+});
+
+console.log(result.status, result.verdict);
+```
+
+## Input
+
+| Field           | Accepts                                      |
+| --------------- | -------------------------------------------- |
+| `condition`     | Non-empty text                               |
+| `evidence`      | 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                                                             |
+| --------- | ------------------------------------------------------------------- |
+| `met`     | The evidence establishes the full condition is satisfied.           |
+| `unmet`   | The evidence establishes the condition is not fully satisfied.      |
+| `unclear` | The evidence does not establish whether the condition is satisfied. |
+
+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 supplied evidence for one condition. Use exact system state checks when the condition can be determined in code.
+
+## Example input
+
+[demo.json](demo.json) contains editable input and a hand-authored response. After installing `jev-recipes`, `npx jev-recipes demo step-complete` shows the result offline. The fixture is an illustration, not an accuracy measurement. `npx jev-recipes describe step-complete` shows the input and result schemas.

package/recipes/step-complete/demo.json

@@ -0,0 +1,25 @@
+{
+  "input": {
+    "condition": "The customer has received a reset email.",
+    "evidence": "A reset email was queued for delivery. Delivery has not been confirmed."
+  },
+  "response": {
+    "model": "demo-fixture",
+    "usage": {
+      "input_tokens": 0,
+      "output_tokens": 0
+    },
+    "answers": {
+      "decision": {
+        "type": "choice",
+        "choice": "unclear",
+        "confidence": 0.96,
+        "probabilities": {
+          "met": 0,
+          "unmet": 0,
+          "unclear": 1
+        }
+      }
+    }
+  }
+}

package/recipes/step-progress/README.md

@@ -0,0 +1,51 @@
+# Check step progress
+
+How does observation change progress toward objective relative to previousState? Base the decision on observed information or achieved conditions, not an unsupported claim of progress.
+
+```ts
+import { stepProgress } from 'jev-recipes/step-progress';
+
+const result = await stepProgress({
+  objective: 'Find the password reset documentation.',
+  previousState: 'No relevant page has been identified.',
+  observation: 'The search returned the official password reset guide.',
+});
+
+console.log(result.status, result.verdict);
+```
+
+## Input
+
+| Field           | Accepts                                      |
+| --------------- | -------------------------------------------- |
+| `objective`     | Non-empty text                               |
+| `previousState` | Non-empty text                               |
+| `observation`   | 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                                                                                        |
+| ------------- | ---------------------------------------------------------------------------------------------- |
+| `progress`    | The observation establishes a useful new fact or achieved condition toward the objective.      |
+| `no_progress` | The observation leaves the relevant state essentially unchanged.                               |
+| `setback`     | The observation establishes loss of previously achieved progress or a worsened relevant state. |
+| `unclear`     | The change in progress 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
+
+Compares one observation with a supplied prior state. It does not measure elapsed time or schedule the next step.
+
+## Example input
+
+[demo.json](demo.json) contains editable input and a hand-authored response. After installing `jev-recipes`, `npx jev-recipes demo step-progress` shows the result offline. The fixture is an illustration, not an accuracy measurement. `npx jev-recipes describe step-progress` shows the input and result schemas.

package/recipes/step-progress/demo.json

@@ -0,0 +1,27 @@
+{
+  "input": {
+    "objective": "Find the password reset documentation.",
+    "previousState": "No relevant page has been identified.",
+    "observation": "The search returned the official password reset guide."
+  },
+  "response": {
+    "model": "demo-fixture",
+    "usage": {
+      "input_tokens": 0,
+      "output_tokens": 0
+    },
+    "answers": {
+      "decision": {
+        "type": "choice",
+        "choice": "progress",
+        "confidence": 0.96,
+        "probabilities": {
+          "progress": 1,
+          "no_progress": 0,
+          "setback": 0,
+          "unclear": 0
+        }
+      }
+    }
+  }
+}

package/recipes/summary-coverage/README.md

@@ -0,0 +1,60 @@
+# Check summary coverage
+
+Check whether a summary preserves each supplied point.
+
+```ts
+import { summaryCoverage } from 'jev-recipes/summary-coverage';
+
+const result = await summaryCoverage({
+  summary: 'We agreed to keep the API unchanged.',
+  points: [
+    {
+      id: 'api',
+      text: 'Keep the public API unchanged.',
+    },
+    {
+      id: 'docs',
+      text: 'Update the installation instructions.',
+    },
+  ],
+});
+
+console.log(result.status, result.checks);
+```
+
+## Input
+
+| Field           | Accepts                                      |
+| --------------- | -------------------------------------------- |
+| `summary`       | Non-empty text                               |
+| `points`        | 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
+
+`checks` contains the original ID, verdict, status, confidence, and probabilities for each item. `allPreserved` is true only when every check is ready and has verdict `preserved`. Any uncertain check makes overall status `review`.
+
+| Verdict     | Meaning                                                                  |
+| ----------- | ------------------------------------------------------------------------ |
+| `preserved` | The full material meaning of this point is retained.                     |
+| `partial`   | Some meaning is retained but a material detail or constraint is missing. |
+| `missing`   | This point is absent or its meaning is reversed.                         |
+| `unclear`   | The summary is too ambiguous to establish coverage.                      |
+
+`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 item-check helper. This folder owns its question, verdict criteria, and aggregate decision. A live invocation makes one logical Jev request; SDK retries can add transport attempts. All item questions are sent in that request.
+
+## Limits
+
+Checks the points you supply. It does not select important points from a transcript or detect unrelated invented statements.
+
+## Example input
+
+[demo.json](demo.json) contains editable input and a hand-authored response. After installing `jev-recipes`, `npx jev-recipes demo summary-coverage` shows the result offline. The fixture is an illustration, not an accuracy measurement. `npx jev-recipes describe summary-coverage` shows the input and result schemas.

package/recipes/summary-coverage/demo.json

@@ -0,0 +1,46 @@
+{
+  "input": {
+    "summary": "We agreed to keep the API unchanged.",
+    "points": [
+      {
+        "id": "api",
+        "text": "Keep the public API unchanged."
+      },
+      {
+        "id": "docs",
+        "text": "Update the installation instructions."
+      }
+    ]
+  },
+  "response": {
+    "model": "demo-fixture",
+    "usage": {
+      "input_tokens": 0,
+      "output_tokens": 0
+    },
+    "answers": {
+      "check_0": {
+        "type": "choice",
+        "choice": "preserved",
+        "confidence": 0.96,
+        "probabilities": {
+          "preserved": 1,
+          "partial": 0,
+          "missing": 0,
+          "unclear": 0
+        }
+      },
+      "check_1": {
+        "type": "choice",
+        "choice": "missing",
+        "confidence": 0.96,
+        "probabilities": {
+          "preserved": 0,
+          "partial": 0,
+          "missing": 1,
+          "unclear": 0
+        }
+      }
+    }
+  }
+}

package/recipes/ticket-match/README.md

@@ -0,0 +1,50 @@
+# Compare support tickets
+
+Do firstTicket and secondTicket describe the same underlying reported issue? Similar symptoms alone establish relatedness, not identity. Use only supplied links between the reports.
+
+```ts
+import { ticketMatch } from 'jev-recipes/ticket-match';
+
+const result = await ticketMatch({
+  firstTicket: 'My workspace export fails with error EXPORT_TIMEOUT.',
+  secondTicket: 'Exports also time out with EXPORT_TIMEOUT in another workspace.',
+});
+
+console.log(result.status, result.verdict);
+```
+
+## Input
+
+| Field           | Accepts                                      |
+| --------------- | -------------------------------------------- |
+| `firstTicket`   | Non-empty text                               |
+| `secondTicket`  | 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                                                                            |
+| ------------ | ---------------------------------------------------------------------------------- |
+| `same_issue` | The reports contain enough shared identifying context to establish the same issue. |
+| `related`    | The reports share symptoms or a subject but do not establish the same issue.       |
+| `different`  | The reports describe materially different issues.                                  |
+| `unclear`    | The descriptions are insufficient to establish even their relationship.            |
+
+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 merge tickets or establish a shared root cause from similar symptoms alone. Compare exact 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 ticket-match` shows the result offline. The fixture is an illustration, not an accuracy measurement. `npx jev-recipes describe ticket-match` shows the input and result schemas.

package/recipes/ticket-match/demo.json

@@ -0,0 +1,26 @@
+{
+  "input": {
+    "firstTicket": "My workspace export fails with error EXPORT_TIMEOUT.",
+    "secondTicket": "Exports also time out with EXPORT_TIMEOUT in another workspace."
+  },
+  "response": {
+    "model": "demo-fixture",
+    "usage": {
+      "input_tokens": 0,
+      "output_tokens": 0
+    },
+    "answers": {
+      "decision": {
+        "type": "choice",
+        "choice": "related",
+        "confidence": 0.96,
+        "probabilities": {
+          "same_issue": 0,
+          "related": 1,
+          "different": 0,
+          "unclear": 0
+        }
+      }
+    }
+  }
+}

package/recipes/tone-check/README.md

@@ -0,0 +1,55 @@
+# Check writing criteria
+
+Check a draft against each supplied writing criterion.
+
+```ts
+import { toneCheck } from 'jev-recipes/tone-check';
+
+const result = await toneCheck({
+  draft: 'You caused this problem. Read the manual.',
+  criteria: [
+    {
+      id: 'blame',
+      text: 'Avoid blaming the customer.',
+    },
+  ],
+});
+
+console.log(result.status, result.checks);
+```
+
+## Input
+
+| Field           | Accepts                                      |
+| --------------- | -------------------------------------------- |
+| `draft`         | Non-empty text                               |
+| `criteria`      | 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
+
+`checks` contains the original ID, verdict, status, confidence, and probabilities for each item. `allPassed` is true only when every check is ready and has verdict `pass`. Any uncertain check makes overall status `review`.
+
+| Verdict   | Meaning                                              |
+| --------- | ---------------------------------------------------- |
+| `pass`    | The wording satisfies this criterion.                |
+| `fail`    | The wording violates this criterion.                 |
+| `unclear` | The criterion or wording is too ambiguous to assess. |
+
+`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 item-check helper. This folder owns its question, verdict criteria, and aggregate decision. A live invocation makes one logical Jev request; SDK retries can add transport attempts. All item questions are sent in that request.
+
+## Limits
+
+Checks supplied writing criteria. It does not rewrite text, determine factual accuracy, or check exact character counts.
+
+## Example input
+
+[demo.json](demo.json) contains editable input and a hand-authored response. After installing `jev-recipes`, `npx jev-recipes demo tone-check` shows the result offline. The fixture is an illustration, not an accuracy measurement. `npx jev-recipes describe tone-check` shows the input and result schemas.

package/recipes/tone-check/demo.json

@@ -0,0 +1,30 @@
+{
+  "input": {
+    "draft": "You caused this problem. Read the manual.",
+    "criteria": [
+      {
+        "id": "blame",
+        "text": "Avoid blaming the customer."
+      }
+    ]
+  },
+  "response": {
+    "model": "demo-fixture",
+    "usage": {
+      "input_tokens": 0,
+      "output_tokens": 0
+    },
+    "answers": {
+      "check_0": {
+        "type": "choice",
+        "choice": "fail",
+        "confidence": 0.96,
+        "probabilities": {
+          "pass": 0,
+          "fail": 1,
+          "unclear": 0
+        }
+      }
+    }
+  }
+}