jev-recipes 0.0.4 → 0.2.0

package/recipes/tool-fit/README.md

@@ -0,0 +1,49 @@
+# Check a tool fit
+
+Can the capabilities explicitly described in tool perform task? Do not assume capabilities that are not described. Capability fit is separate from permission to invoke the tool.
+
+```ts
+import { toolFit } from 'jev-recipes/tool-fit';
+
+const result = await toolFit({
+  task: 'Read the current incident status.',
+  tool: 'Status reader: retrieves active incidents. It cannot create or modify incidents.',
+});
+
+console.log(result.status, result.verdict);
+```
+
+## Input
+
+| Field           | Accepts                                      |
+| --------------- | -------------------------------------------- |
+| `task`          | Non-empty text                               |
+| `tool`          | 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                                                                    |
+| -------------- | -------------------------------------------------------------------------- |
+| `fits`         | The described capabilities can perform the requested task.                 |
+| `does_not_fit` | The described capabilities do not cover the task or explicitly exclude it. |
+| `unclear`      | The capability description lacks facts needed to decide.                   |
+
+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 capability description. It does not discover tools, validate credentials, or grant permission.
+
+## Example input
+
+[demo.json](demo.json) contains editable input and a hand-authored response. After installing `jev-recipes`, `npx jev-recipes demo tool-fit` shows the result offline. The fixture is an illustration, not an accuracy measurement. `npx jev-recipes describe tool-fit` shows the input and result schemas.

package/recipes/tool-fit/demo.json

@@ -0,0 +1,25 @@
+{
+  "input": {
+    "task": "Read the current incident status.",
+    "tool": "Status reader: retrieves active incidents. It cannot create or modify incidents."
+  },
+  "response": {
+    "model": "demo-fixture",
+    "usage": {
+      "input_tokens": 0,
+      "output_tokens": 0
+    },
+    "answers": {
+      "decision": {
+        "type": "choice",
+        "choice": "fits",
+        "confidence": 0.96,
+        "probabilities": {
+          "fits": 1,
+          "does_not_fit": 0,
+          "unclear": 0
+        }
+      }
+    }
+  }
+}

package/recipes/topic-shift/README.md

@@ -0,0 +1,50 @@
+# Detect a topic shift
+
+Does message stay with currentTopic, introduce a different topic, or contain both? A new detail within the same subject is not automatically a new topic.
+
+```ts
+import { topicShift } from 'jev-recipes/topic-shift';
+
+const result = await topicShift({
+  currentTopic: 'Resetting a password.',
+  message: 'Also, where can I download my invoices?',
+});
+
+console.log(result.status, result.verdict);
+```
+
+## Input
+
+| Field           | Accepts                                      |
+| --------------- | -------------------------------------------- |
+| `currentTopic`  | 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                                                                 |
+| ------------ | ----------------------------------------------------------------------- |
+| `same_topic` | The message remains within the current subject.                         |
+| `new_topic`  | The message moves to a different subject.                               |
+| `mixed`      | The message substantively addresses both the current and a new subject. |
+| `unclear`    | The subject relationship 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
+
+Compares one message with a supplied topic. It does not generate topic labels or split conversation threads.
+
+## Example input
+
+[demo.json](demo.json) contains editable input and a hand-authored response. After installing `jev-recipes`, `npx jev-recipes demo topic-shift` shows the result offline. The fixture is an illustration, not an accuracy measurement. `npx jev-recipes describe topic-shift` shows the input and result schemas.

package/recipes/topic-shift/demo.json

@@ -0,0 +1,26 @@
+{
+  "input": {
+    "currentTopic": "Resetting a password.",
+    "message": "Also, where can I download my invoices?"
+  },
+  "response": {
+    "model": "demo-fixture",
+    "usage": {
+      "input_tokens": 0,
+      "output_tokens": 0
+    },
+    "answers": {
+      "decision": {
+        "type": "choice",
+        "choice": "new_topic",
+        "confidence": 0.96,
+        "probabilities": {
+          "same_topic": 0,
+          "new_topic": 1,
+          "mixed": 0,
+          "unclear": 0
+        }
+      }
+    }
+  }
+}

package/recipes/troubleshooting-fit/README.md

@@ -0,0 +1,49 @@
+# Check troubleshooting applicability
+
+Does procedure address symptoms under the described circumstances? Match the procedure's stated purpose and prerequisites, without inventing a diagnosis.
+
+```ts
+import { troubleshootingFit } from 'jev-recipes/troubleshooting-fit';
+
+const result = await troubleshootingFit({
+  symptoms: 'The customer forgot their password and cannot sign in.',
+  procedure: 'For forgotten passwords, use Forgot password on the sign-in page.',
+});
+
+console.log(result.status, result.verdict);
+```
+
+## Input
+
+| Field           | Accepts                                      |
+| --------------- | -------------------------------------------- |
+| `symptoms`      | Non-empty text                               |
+| `procedure`     | 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                                                                           |
+| ------------ | --------------------------------------------------------------------------------- |
+| `applicable` | The procedure covers the described symptoms and its stated prerequisites are met. |
+| `unsuitable` | The procedure concerns different symptoms or incompatible prerequisites.          |
+| `unclear`    | The symptoms or prerequisites are insufficiently specified.                       |
+
+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 procedure; it does not diagnose a root cause, generate steps, or execute them.
+
+## Example input
+
+[demo.json](demo.json) contains editable input and a hand-authored response. After installing `jev-recipes`, `npx jev-recipes demo troubleshooting-fit` shows the result offline. The fixture is an illustration, not an accuracy measurement. `npx jev-recipes describe troubleshooting-fit` shows the input and result schemas.

package/recipes/troubleshooting-fit/demo.json

@@ -0,0 +1,25 @@
+{
+  "input": {
+    "symptoms": "The customer forgot their password and cannot sign in.",
+    "procedure": "For forgotten passwords, use Forgot password on the sign-in page."
+  },
+  "response": {
+    "model": "demo-fixture",
+    "usage": {
+      "input_tokens": 0,
+      "output_tokens": 0
+    },
+    "answers": {
+      "decision": {
+        "type": "choice",
+        "choice": "applicable",
+        "confidence": 0.96,
+        "probabilities": {
+          "applicable": 1,
+          "unsuitable": 0,
+          "unclear": 0
+        }
+      }
+    }
+  }
+}

package/recipes/turn-intent/README.md

@@ -0,0 +1,52 @@
+# Identify a conversation turn
+
+What is the primary communicative purpose of message in context? For mixed messages choose the purpose that changes what the application should do next; choose unclear if none dominates.
+
+```ts
+import { turnIntent } from 'jev-recipes/turn-intent';
+
+const result = await turnIntent({
+  message: 'Actually, use the staging account, not production.',
+  context: 'The assistant is preparing a deployment.',
+});
+
+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                                                                     |
+| ---------------- | --------------------------------------------------------------------------- |
+| `request`        | The message asks for new work or information.                               |
+| `answer`         | The message supplies information requested earlier.                         |
+| `correction`     | The message corrects a prior fact or instruction.                           |
+| `cancellation`   | The message asks to stop or pause an existing task.                         |
+| `acknowledgment` | The message acknowledges prior content without requesting substantive work. |
+| `other`          | The purpose is clear but does not fit the listed purposes.                  |
+| `unclear`        | The primary purpose 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 the primary purpose only. It does not split a message into separate requests or execute instructions.
+
+## Example input
+
+[demo.json](demo.json) contains editable input and a hand-authored response. After installing `jev-recipes`, `npx jev-recipes demo turn-intent` shows the result offline. The fixture is an illustration, not an accuracy measurement. `npx jev-recipes describe turn-intent` shows the input and result schemas.

package/recipes/turn-intent/demo.json

@@ -0,0 +1,29 @@
+{
+  "input": {
+    "message": "Actually, use the staging account, not production.",
+    "context": "The assistant is preparing a deployment."
+  },
+  "response": {
+    "model": "demo-fixture",
+    "usage": {
+      "input_tokens": 0,
+      "output_tokens": 0
+    },
+    "answers": {
+      "decision": {
+        "type": "choice",
+        "choice": "correction",
+        "confidence": 0.96,
+        "probabilities": {
+          "request": 0,
+          "answer": 0,
+          "correction": 1,
+          "cancellation": 0,
+          "acknowledgment": 0,
+          "other": 0,
+          "unclear": 0
+        }
+      }
+    }
+  }
+}

package/recipes/urgency-signal/README.md

@@ -0,0 +1,47 @@
+# Detect an explicit urgency request
+
+Does message explicitly request urgent attention? Look for stated urgency, not inferred importance, customer tone, or an unstated interpretation of a date.
+
+```ts
+import { urgencySignal } from 'jev-recipes/urgency-signal';
+
+const result = await urgencySignal({
+  message: 'Please treat this as urgent; we need someone to look at it immediately.',
+});
+
+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 message explicitly asks for immediate, urgent, or expedited attention. |
+| `not_expressed` | The message does not explicitly ask for urgent attention.                  |
+| `unclear`       | The urgency language is too ambiguous to interpret.                        |
+
+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
+
+Detects an expressed urgency request. Compute deadline proximity and apply incident or service priority rules in code.
+
+## Example input
+
+[demo.json](demo.json) contains editable input and a hand-authored response. After installing `jev-recipes`, `npx jev-recipes demo urgency-signal` shows the result offline. The fixture is an illustration, not an accuracy measurement. `npx jev-recipes describe urgency-signal` shows the input and result schemas.

package/recipes/urgency-signal/demo.json

@@ -0,0 +1,24 @@
+{
+  "input": {
+    "message": "Please treat this as urgent; we need someone to look at it immediately."
+  },
+  "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/verify/README.md

@@ -1,6 +1,6 @@
-# Verify
+# Verify claims
 
-Check whether each claim is supported by its paired evidence. The caller supplies both. This function does not browse, extract claims, validate sources, or guarantee factual truth.
+Check whether each supplied claim is supported by its paired evidence. Every pair is evaluated independently.
 
 ```ts
 import { verify } from 'jev-recipes/verify';
@@ -8,23 +8,47 @@ import { verify } from 'jev-recipes/verify';
 const result = await verify({
   claims: [
     {
-      id: 'refund-window',
-      claim: 'Refunds are available for 60 days.',
-      evidence: 'Refunds are available only within 30 days of purchase.',
+      id: 'guest-export',
+      claim: 'Guests can export reports.',
+      evidence: 'Only workspace owners can export reports. Guests cannot export.',
     },
   ],
-  minConfidence: 0.8,
 });
+
+console.log(result.checks);
 ```
 
-Supply 1 to 100 claims, each with a unique non-empty `id`, `claim`, and `evidence`. One Jev call evaluates all pairs. Every check returns:
+## Input
+
+| Field           | Accepts                                                                                                  |
+| --------------- | -------------------------------------------------------------------------------------------------------- |
+| `claims`        | 1 to 100 `{ id, claim, evidence }` items with unique non-empty IDs and non-empty claim and evidence 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. Types are inferred from this folder's Zod 4 schemas.
+
+## Result
+
+`checks` preserves each claim ID and returns its verdict, status, confidence, and choice probabilities.
+
+| Verdict        | Meaning                                                                        |
+| -------------- | ------------------------------------------------------------------------------ |
+| `supported`    | The paired evidence supports the entire claim.                                 |
+| `contradicted` | The paired evidence establishes something incompatible with the claim.         |
+| `unsupported`  | The paired evidence is insufficient to support or contradict the entire claim. |
+
+Each check is `ready` at or above `minConfidence`, otherwise `review`. A ready check can still be contradicted or unsupported. `allSupported` is true only when every check is ready and supported. Read individual check statuses; the result has no top-level 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 evidence criteria and the all-supported decision. All claim questions are sent in one request. The citation-match recipe calls this public function to select supporting passages. A live invocation makes one logical Jev request; SDK retries can add transport attempts.
 
-- `verdict`: `supported`, `contradicted`, or `unsupported`.
-- `status`: `ready` when confidence meets `minConfidence`, otherwise `review`.
-- `confidence` and the full probability distribution.
+## Limits
 
-`minConfidence` defaults to `0.8`. A ready result can be a confident contradiction; always read its verdict. `allSupported` is true only when every claim is both supported and ready. A review result retains the suggested verdict for inspection.
+Checks only supplied claim/evidence pairs. It does not extract claims, retrieve sources, establish source truth, or check whether an answer addresses every requested point. Exact arithmetic and date comparisons belong in code.
 
-Model and token usage appear on the overall result. Missing or malformed model answers fail the complete evaluation. Contradictory or incomplete evidence can still lead to mistakes; measure performance on your own examples. Quote matching and source retrieval are outside the 0.0.1 scope.
+## Example input
 
-Try `npm run jev -- demo verify` for the offline [`demo.json`](demo.json) fixture. Use `node dist/cli/index.js example verify` to print editable input. Live claim-checking 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 verify` shows an offline illustration, not an accuracy measurement. Use `npx jev-recipes describe verify` to inspect the input and result schemas.

package/recipes/workaround-fit/README.md

@@ -0,0 +1,50 @@
+# Check workaround fit
+
+Can workaround address issue without violating constraints? Check the stated prerequisites and restrictions. Do not assume permissions, tools, or capabilities not supplied.
+
+```ts
+import { workaroundFit } from 'jev-recipes/workaround-fit';
+
+const result = await workaroundFit({
+  issue: 'The desktop application cannot open a report.',
+  workaround: 'Open the report in the web application.',
+  constraints: 'The customer has web access and needs only to view the report.',
+});
+
+console.log(result.status, result.verdict);
+```
+
+## Input
+
+| Field           | Accepts                                      |
+| --------------- | -------------------------------------------- |
+| `issue`         | Non-empty text                               |
+| `workaround`    | Non-empty text                               |
+| `constraints`   | 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                                                                               |
+| ----------- | ------------------------------------------------------------------------------------- |
+| `fits`      | The described workaround addresses the issue and satisfies the stated constraints.    |
+| `conflicts` | The workaround contradicts a stated constraint or cannot address the described issue. |
+| `unclear`   | A needed prerequisite or effect 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
+
+Assesses described compatibility. It does not establish operational safety, execute a workaround, or grant access.
+
+## Example input
+
+[demo.json](demo.json) contains editable input and a hand-authored response. After installing `jev-recipes`, `npx jev-recipes demo workaround-fit` shows the result offline. The fixture is an illustration, not an accuracy measurement. `npx jev-recipes describe workaround-fit` shows the input and result schemas.

package/recipes/workaround-fit/demo.json

@@ -0,0 +1,26 @@
+{
+  "input": {
+    "issue": "The desktop application cannot open a report.",
+    "workaround": "Open the report in the web application.",
+    "constraints": "The customer has web access and needs only to view the report."
+  },
+  "response": {
+    "model": "demo-fixture",
+    "usage": {
+      "input_tokens": 0,
+      "output_tokens": 0
+    },
+    "answers": {
+      "decision": {
+        "type": "choice",
+        "choice": "fits",
+        "confidence": 0.96,
+        "probabilities": {
+          "fits": 1,
+          "conflicts": 0,
+          "unclear": 0
+        }
+      }
+    }
+  }
+}