jev-recipes 0.0.4 → 0.2.0

package/recipes/memory-relation/README.md

@@ -0,0 +1,52 @@
+# Compare a new fact with memory
+
+How does newFact relate to existingMemory? Choose updates only when a change or replacement is explicitly established, not merely because newFact was supplied later.
+
+```ts
+import { memoryRelation } from 'jev-recipes/memory-relation';
+
+const result = await memoryRelation({
+  existingMemory: 'The project uses npm.',
+  newFact: 'We have switched this project from npm to pnpm.',
+});
+
+console.log(result.status, result.verdict);
+```
+
+## Input
+
+| Field            | Accepts                                      |
+| ---------------- | -------------------------------------------- |
+| `existingMemory` | Non-empty text                               |
+| `newFact`        | 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                                                                              |
+| ------------- | ------------------------------------------------------------------------------------ |
+| `repeats`     | The new fact restates the existing meaning without a material addition.              |
+| `supplements` | The new fact adds compatible information while the existing memory still applies.    |
+| `updates`     | The new fact explicitly changes or replaces the existing fact within the same scope. |
+| `conflicts`   | The facts are incompatible within the same scope without an established replacement. |
+| `unrelated`   | The facts concern unrelated subjects or scopes.                                      |
+| `unclear`     | Their 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 two supplied facts. It does not select a memory to overwrite or resolve conflicts by timestamp alone.
+
+## Example input
+
+[demo.json](demo.json) contains editable input and a hand-authored response. After installing `jev-recipes`, `npx jev-recipes demo memory-relation` shows the result offline. The fixture is an illustration, not an accuracy measurement. `npx jev-recipes describe memory-relation` shows the input and result schemas.

package/recipes/memory-relation/demo.json

@@ -0,0 +1,28 @@
+{
+  "input": {
+    "existingMemory": "The project uses npm.",
+    "newFact": "We have switched this project from npm to pnpm."
+  },
+  "response": {
+    "model": "demo-fixture",
+    "usage": {
+      "input_tokens": 0,
+      "output_tokens": 0
+    },
+    "answers": {
+      "decision": {
+        "type": "choice",
+        "choice": "updates",
+        "confidence": 0.96,
+        "probabilities": {
+          "repeats": 0,
+          "supplements": 0,
+          "updates": 1,
+          "conflicts": 0,
+          "unrelated": 0,
+          "unclear": 0
+        }
+      }
+    }
+  }
+}

package/recipes/memory-scope/README.md

@@ -0,0 +1,50 @@
+# Identify memory scope
+
+What is the narrowest explicitly supported scope of fact in context? Do not generalize a one-off instruction into a lasting user preference.
+
+```ts
+import { memoryScope } from 'jev-recipes/memory-scope';
+
+const result = await memoryScope({
+  fact: 'Use two-space indentation in this repository.',
+  context: 'The user is describing the conventions for the billing service repository.',
+});
+
+console.log(result.status, result.verdict);
+```
+
+## Input
+
+| Field           | Accepts                                      |
+| --------------- | -------------------------------------------- |
+| `fact`          | 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                                                                   |
+| --------- | ------------------------------------------------------------------------- |
+| `user`    | The fact explicitly applies to the user across projects or tasks.         |
+| `project` | The fact applies to the identified project across its tasks.              |
+| `task`    | The fact applies to the current task only.                                |
+| `session` | The fact applies to this conversation session across its immediate tasks. |
+| `unclear` | The intended scope 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
+
+Identifies semantic scope. It does not identify a storage tenant, establish consent, or persist a memory.
+
+## Example input
+
+[demo.json](demo.json) contains editable input and a hand-authored response. After installing `jev-recipes`, `npx jev-recipes demo memory-scope` shows the result offline. The fixture is an illustration, not an accuracy measurement. `npx jev-recipes describe memory-scope` shows the input and result schemas.

package/recipes/memory-scope/demo.json

@@ -0,0 +1,27 @@
+{
+  "input": {
+    "fact": "Use two-space indentation in this repository.",
+    "context": "The user is describing the conventions for the billing service repository."
+  },
+  "response": {
+    "model": "demo-fixture",
+    "usage": {
+      "input_tokens": 0,
+      "output_tokens": 0
+    },
+    "answers": {
+      "decision": {
+        "type": "choice",
+        "choice": "project",
+        "confidence": 0.96,
+        "probabilities": {
+          "user": 0,
+          "project": 1,
+          "task": 0,
+          "session": 0,
+          "unclear": 0
+        }
+      }
+    }
+  }
+}

package/recipes/memory-value/README.md

@@ -0,0 +1,50 @@
+# Assess a candidate memory
+
+How useful is fact for future work under purpose? Distinguish lasting relevance from a current-task detail. Use the supplied purpose rather than assuming every personal fact is worth retaining.
+
+```ts
+import { memoryValue } from 'jev-recipes/memory-value';
+
+const result = await memoryValue({
+  fact: 'The user prefers short, direct support replies.',
+  purpose: 'Help the user draft customer support replies across sessions.',
+});
+
+console.log(result.status, result.verdict);
+```
+
+## Input
+
+| Field           | Accepts                                      |
+| --------------- | -------------------------------------------- |
+| `fact`          | Non-empty text                               |
+| `purpose`       | 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                                                                       |
+| --------------- | ----------------------------------------------------------------------------- |
+| `ongoing_value` | The fact has a clear recurring use for the supplied purpose beyond this task. |
+| `task_only`     | The fact helps the current task but has no established recurring use.         |
+| `incidental`    | The fact has no clear use for the supplied purpose.                           |
+| `unclear`       | Its future usefulness 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
+
+Assesses usefulness only. Storage consent, sensitive-data policy, retention, and deletion must be enforced separately.
+
+## Example input
+
+[demo.json](demo.json) contains editable input and a hand-authored response. After installing `jev-recipes`, `npx jev-recipes demo memory-value` shows the result offline. The fixture is an illustration, not an accuracy measurement. `npx jev-recipes describe memory-value` shows the input and result schemas.

package/recipes/memory-value/demo.json

@@ -0,0 +1,26 @@
+{
+  "input": {
+    "fact": "The user prefers short, direct support replies.",
+    "purpose": "Help the user draft customer support replies across sessions."
+  },
+  "response": {
+    "model": "demo-fixture",
+    "usage": {
+      "input_tokens": 0,
+      "output_tokens": 0
+    },
+    "answers": {
+      "decision": {
+        "type": "choice",
+        "choice": "ongoing_value",
+        "confidence": 0.96,
+        "probabilities": {
+          "ongoing_value": 1,
+          "task_only": 0,
+          "incidental": 0,
+          "unclear": 0
+        }
+      }
+    }
+  }
+}

package/recipes/passage-duplicate/README.md

@@ -0,0 +1,49 @@
+# Compare passages for duplication
+
+How much material information do firstPassage and secondPassage share? Different wording can express the same information. Shared subject matter alone does not make a duplicate.
+
+```ts
+import { passageDuplicate } from 'jev-recipes/passage-duplicate';
+
+const result = await passageDuplicate({
+  firstPassage: 'Select Forgot password to receive a reset email.',
+  secondPassage: 'Use Forgot password and we will email a reset link.',
+});
+
+console.log(result.status, result.verdict);
+```
+
+## Input
+
+| Field           | Accepts                                      |
+| --------------- | -------------------------------------------- |
+| `firstPassage`  | Non-empty text                               |
+| `secondPassage` | 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                                                                   |
+| ------------- | ------------------------------------------------------------------------- |
+| `duplicate`   | Both passages convey substantially the same material information.         |
+| `overlapping` | They share material information but at least one adds meaningful details. |
+| `distinct`    | They convey materially different information.                             |
+| `unclear`     | The meaning cannot be compared reliably.                                  |
+
+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 a supplied pair. It does not search a corpus, cluster documents, or remove content.
+
+## Example input
+
+[demo.json](demo.json) contains editable input and a hand-authored response. After installing `jev-recipes`, `npx jev-recipes demo passage-duplicate` shows the result offline. The fixture is an illustration, not an accuracy measurement. `npx jev-recipes describe passage-duplicate` shows the input and result schemas.

package/recipes/passage-duplicate/demo.json

@@ -0,0 +1,26 @@
+{
+  "input": {
+    "firstPassage": "Select Forgot password to receive a reset email.",
+    "secondPassage": "Use Forgot password and we will email a reset link."
+  },
+  "response": {
+    "model": "demo-fixture",
+    "usage": {
+      "input_tokens": 0,
+      "output_tokens": 0
+    },
+    "answers": {
+      "decision": {
+        "type": "choice",
+        "choice": "duplicate",
+        "confidence": 0.96,
+        "probabilities": {
+          "duplicate": 1,
+          "overlapping": 0,
+          "distinct": 0,
+          "unclear": 0
+        }
+      }
+    }
+  }
+}

package/recipes/preference-kind/README.md

@@ -0,0 +1,48 @@
+# Identify a stated preference
+
+Does statement express an ongoing preference, a factual assertion, or a temporary request? Do not treat a task-specific instruction as a lasting preference without evidence of scope.
+
+```ts
+import { preferenceKind } from 'jev-recipes/preference-kind';
+
+const result = await preferenceKind({
+  statement: 'For this reply, please use bullet points.',
+});
+
+console.log(result.status, result.verdict);
+```
+
+## Input
+
+| Field           | Accepts                                      |
+| --------------- | -------------------------------------------- |
+| `statement`     | 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                                                                                              |
+| ------------------- | ---------------------------------------------------------------------------------------------------- |
+| `preference`        | The statement expresses an ongoing choice or preferred way of working.                               |
+| `fact`              | The statement asserts information without expressing a preference or requesting an action.           |
+| `temporary_request` | The statement asks for something in the current situation without establishing a lasting preference. |
+| `unclear`           | The intended kind cannot be established.                                                             |
+
+The result includes `verdict`, `confidence`, and all choice `probabilities`. `unclear` always requires review, even at high confidence. Other verdicts can be ready, including negative assessments.
+
+Results include model and token usage. Decisions below `minConfidence` require review. Inspect the outcome as well as the status.
+
+## Reuse and calls
+
+Uses the shared choice helper for the Jev call and response parsing. This folder owns its question, verdict criteria, and review policy. A live invocation makes one logical Jev request; SDK retries can add transport attempts.
+
+## Limits
+
+Classifies a statement. It does not infer unexpressed preferences or grant permission to store personal information.
+
+## Example input
+
+[demo.json](demo.json) contains editable input and a hand-authored response. After installing `jev-recipes`, `npx jev-recipes demo preference-kind` shows the result offline. The fixture is an illustration, not an accuracy measurement. `npx jev-recipes describe preference-kind` shows the input and result schemas.

package/recipes/preference-kind/demo.json

@@ -0,0 +1,25 @@
+{
+  "input": {
+    "statement": "For this reply, please use bullet points."
+  },
+  "response": {
+    "model": "demo-fixture",
+    "usage": {
+      "input_tokens": 0,
+      "output_tokens": 0
+    },
+    "answers": {
+      "decision": {
+        "type": "choice",
+        "choice": "temporary_request",
+        "confidence": 0.96,
+        "probabilities": {
+          "preference": 0,
+          "fact": 0,
+          "temporary_request": 1,
+          "unclear": 0
+        }
+      }
+    }
+  }
+}

package/recipes/promise-check/README.md

@@ -0,0 +1,48 @@
+# Check reply commitments
+
+Does reply promise actions or outcomes beyond allowedCommitments? A conditional possibility is not a guarantee. Judge the whole reply; one unsupported promise is enough.
+
+```ts
+import { promiseCheck } from 'jev-recipes/promise-check';
+
+const result = await promiseCheck({
+  reply: 'Your refund is guaranteed.',
+  allowedCommitments: 'We may promise to review a refund request. We cannot promise approval.',
+});
+
+console.log(result.status, result.verdict);
+```
+
+## Input
+
+| Field                | Accepts                                      |
+| -------------------- | -------------------------------------------- |
+| `reply`              | Non-empty text                               |
+| `allowedCommitments` | 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                                                                                   |
+| -------------------- | ----------------------------------------------------------------------------------------- |
+| `within_commitments` | Every promise is permitted by the supplied commitments, or the reply contains no promise. |
+| `unsupported`        | At least one promise exceeds or contradicts the supplied commitments.                     |
+| `unclear`            | The wording or allowed commitments leave a promise 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
+
+Reviews expressed promises. It does not approve refunds, establish contractual obligations, or execute actions.
+
+## Example input
+
+[demo.json](demo.json) contains editable input and a hand-authored response. After installing `jev-recipes`, `npx jev-recipes demo promise-check` shows the result offline. The fixture is an illustration, not an accuracy measurement. `npx jev-recipes describe promise-check` shows the input and result schemas.

package/recipes/promise-check/demo.json

@@ -0,0 +1,25 @@
+{
+  "input": {
+    "reply": "Your refund is guaranteed.",
+    "allowedCommitments": "We may promise to review a refund request. We cannot promise approval."
+  },
+  "response": {
+    "model": "demo-fixture",
+    "usage": {
+      "input_tokens": 0,
+      "output_tokens": 0
+    },
+    "answers": {
+      "decision": {
+        "type": "choice",
+        "choice": "unsupported",
+        "confidence": 0.96,
+        "probabilities": {
+          "within_commitments": 0,
+          "unsupported": 1,
+          "unclear": 0
+        }
+      }
+    }
+  }
+}

package/recipes/query-equivalence/README.md

@@ -0,0 +1,50 @@
+# Compare question meaning
+
+Do firstQuestion and secondQuestion request the same information under the same stated conditions? Shared vocabulary or topic alone is not equivalence.
+
+```ts
+import { queryEquivalence } from 'jev-recipes/query-equivalence';
+
+const result = await queryEquivalence({
+  firstQuestion: 'How can I reset my password?',
+  secondQuestion: 'What should I do if I forgot my password?',
+});
+
+console.log(result.status, result.verdict);
+```
+
+## Input
+
+| Field            | Accepts                                      |
+| ---------------- | -------------------------------------------- |
+| `firstQuestion`  | Non-empty text                               |
+| `secondQuestion` | 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                                                                    |
+| ------------ | -------------------------------------------------------------------------- |
+| `equivalent` | Both questions request the same information with compatible conditions.    |
+| `related`    | They share a topic but differ in a material information need or condition. |
+| `different`  | They request different subjects or unrelated information.                  |
+| `unclear`    | The intended meanings 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 supplied questions. It does not rewrite them or establish that an existing answer is still valid.
+
+## Example input
+
+[demo.json](demo.json) contains editable input and a hand-authored response. After installing `jev-recipes`, `npx jev-recipes demo query-equivalence` shows the result offline. The fixture is an illustration, not an accuracy measurement. `npx jev-recipes describe query-equivalence` shows the input and result schemas.

package/recipes/query-equivalence/demo.json

@@ -0,0 +1,26 @@
+{
+  "input": {
+    "firstQuestion": "How can I reset my password?",
+    "secondQuestion": "What should I do if I forgot my password?"
+  },
+  "response": {
+    "model": "demo-fixture",
+    "usage": {
+      "input_tokens": 0,
+      "output_tokens": 0
+    },
+    "answers": {
+      "decision": {
+        "type": "choice",
+        "choice": "equivalent",
+        "confidence": 0.96,
+        "probabilities": {
+          "equivalent": 1,
+          "related": 0,
+          "different": 0,
+          "unclear": 0
+        }
+      }
+    }
+  }
+}

package/recipes/query-specificity/README.md

@@ -0,0 +1,47 @@
+# Check question specificity
+
+Does question, interpreted with context, identify a focused information need? A broad but clear request differs from an ambiguous reference or missing subject.
+
+```ts
+import { querySpecificity } from 'jev-recipes/query-specificity';
+
+const result = await querySpecificity({
+  question: 'Tell me everything about software.',
+});
+
+console.log(result.status, result.verdict);
+```
+
+## Input
+
+| Field           | Accepts                                      |
+| --------------- | -------------------------------------------- |
+| `question`      | 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                                                                                 |
+| ----------- | --------------------------------------------------------------------------------------- |
+| `specific`  | The subject and requested information are sufficiently clear and focused.               |
+| `too_broad` | The intended subject is clear but the request spans an open-ended range of information. |
+| `ambiguous` | The subject, reference, or intended information has multiple unresolved meanings.       |
+
+The result includes `verdict`, `confidence`, and all choice `probabilities`. `ambiguous` 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 focus only. Use clarify when the application has explicit required fields to check.
+
+## Example input
+
+[demo.json](demo.json) contains editable input and a hand-authored response. After installing `jev-recipes`, `npx jev-recipes demo query-specificity` shows the result offline. The fixture is an illustration, not an accuracy measurement. `npx jev-recipes describe query-specificity` shows the input and result schemas.

package/recipes/query-specificity/demo.json

@@ -0,0 +1,24 @@
+{
+  "input": {
+    "question": "Tell me everything about software."
+  },
+  "response": {
+    "model": "demo-fixture",
+    "usage": {
+      "input_tokens": 0,
+      "output_tokens": 0
+    },
+    "answers": {
+      "decision": {
+        "type": "choice",
+        "choice": "too_broad",
+        "confidence": 0.96,
+        "probabilities": {
+          "specific": 0,
+          "too_broad": 1,
+          "ambiguous": 0
+        }
+      }
+    }
+  }
+}