sanity-plugin-jev-fields 0.1.1 → 0.2.0

package/README.md

@@ -8,16 +8,16 @@ next to it for you to query, and can warn or block publishing.
 
 The questions are answered by [TypeSafe's Jev](https://typesafe.ai), a decision model that
 answers a question with a probability instead of writing text, through
-[Vercel AI Gateway](https://vercel.com/ai-gateway). Each question is a signal, shown as a chip
-under the field it judges; click it for the details. There are three kinds:
+[Vercel AI Gateway](https://vercel.com/ai-gateway). Each question shows as a chip under the field
+it judges; click it for the details. There are three kinds:
 
 - `noul`: a yes/no question, answered with the probability that the answer is yes
 - `score`: a position on an ordered scale you define
 - `choice`: one option from a named set, with a probability for each option
 
-Signals re-evaluate shortly after the field is edited. Opening a document never writes to it.
+Questions are re-evaluated shortly after the field is edited. Opening a document never writes to it.
 
-<img src="https://raw.githubusercontent.com/frederikvonsperling/sanity-plugin-jev-fields/main/docs/images/readable.png" width="612" alt="A Body field in Sanity Studio with three signal chips under it: Readable 90%, Evidence 1.5/3 and Tone Casual. The Readable details are open: a High badge, 90% likely to read easily, a nearly full green bar, and the hint &quot;Short sentences, plain words, clear structure&quot;.">
+<img src="https://raw.githubusercontent.com/frederikvonsperling/sanity-plugin-jev-fields/main/docs/images/readable.png" width="612" alt="A Body field in Sanity Studio with three question chips under it: Readable 90%, Evidence 1.5/3 and Tone Casual. The Readable details are open: a High badge, 90% likely to read easily, a nearly full green bar, and the hint &quot;Short sentences, plain words, clear structure&quot;.">
 
 ## Install
 
@@ -38,7 +38,7 @@ Requires Sanity Studio 6. Its peer dependencies, `react` and `react-dom` 19.2 or
 
 ## Usage
 
-Add the plugin, and wrap your schema types with `withJevAnswers` so every signal gets a field to
+Add the plugin, and wrap your schema types with `withJevAnswers` so every question gets a field to
 store its answer in:
 
 ```ts
@@ -53,7 +53,7 @@ export default defineConfig({
 })
 ```
 
-Then attach signals to any field with `options.jev`:
+Then attach questions to any field with `options.jev`:
 
 ```ts
 import {defineArrayMember, defineField} from 'sanity'
@@ -94,11 +94,11 @@ defineField({
 })
 ```
 
-A signal reads only the field it is attached to. Portable Text, slugs and nested objects are
+A question reads only the field it is attached to. Portable Text, slugs and nested objects are
 flattened to plain text. Each key (`readable`, `evidence`, `tone`) becomes the name of a field
 next to it that stores the answer; `withJevAnswers` adds those fields and stops with an error if a
 name is already taken. A `score` takes 2 to 10 criteria and a `choice` 2 to 255 options; see
-[Signal options](#signal-options) for the rest.
+[Question options](#question-options) for the rest.
 
 <img src="https://raw.githubusercontent.com/frederikvonsperling/sanity-plugin-jev-fields/main/docs/images/tone.png" width="612" alt="A Title field with a Tone Casual chip under it. The Tone details are open: bars for Formal 3%, Casual 97% and Playful 0%, the meaning &quot;Conversational and relaxed&quot;, and the note &quot;Out of date: the field changed since this was evaluated.&quot;">
 
@@ -106,16 +106,16 @@ When a field changes, its answers are marked out of date until they are evaluate
 
 ## Rules
 
-Give a signal a `warn` or `require` rule to act on its answer: `warn` shows a warning on the
+Give a question a `warn` or `require` rule to act on its answer: `warn` shows a warning on the
 attached field, `require` an error that blocks publishing.
 
 ```ts
 options: {
   jev: {
-    readable: noul({...signal, warn: {atLeast: 0.6}}), // probability, 0–1
-    evidence: score({...signal, require: {atLeast: 2}}), // position on the scale
-    risk: score({...signal, colors: 'reverse', warn: {atMost: 1}}), // lower is better
-    tone: choice({...signal, warn: {oneOf: ['formal', 'casual']}}),
+    readable: noul({...question, warn: {atLeast: 0.6}}), // probability, 0–1
+    evidence: score({...question, require: {atLeast: 2}}), // position on the scale
+    risk: score({...question, colors: 'reverse', warn: {atMost: 1}}), // lower is better
+    tone: choice({...question, warn: {oneOf: ['formal', 'casual']}}),
   },
 }
 ```
@@ -123,14 +123,14 @@ options: {
 `noul` and `score` rules take `atLeast`, `atMost` or both. `choice` rules take `oneOf`, the options
 the answer must be one of.
 
-Rules judge the stored answer, so they say nothing until a signal has been evaluated, and an
+Rules judge the stored answer, so they say nothing until a question has been evaluated, and an
 answer that is out of date is still judged as it is.
 
 ## What Jev is good at
 
 Jev judges meaning in text: tone, clarity, whether claims are backed up. It reads only text, so
 images and other media in a field are ignored. It is not built for counting or arithmetic: ask
-"Is this under 150 words?" in a validation rule instead. Test signals on content in your own
+"Is this under 150 words?" in a validation rule instead. Test questions on content in your own
 languages before relying on them. A field's text may be up to about 32k tokens; the Studio warns
 when a field gets close.
 
@@ -210,24 +210,24 @@ and config problems are meant for schema authors.
 
 Passed to `jev({...})`. All are optional.
 
-| Option       | Default                                    | Description                                                                                                                     |
-| ------------ | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------- |
-| `transport`  |                                            | `(request, {signal}) => Promise<Response>`. Sends requests yourself, e.g. through your own server. See [API key](#api-key).     |
-| `apiKey`     |                                            | AI Gateway key. Bundled into the Studio's JavaScript; prefer the Jev tool or `transport`.                                       |
-| `endpoint`   | `https://ai-gateway.vercel.sh/v1/evaluate` | Where requests go. Ignored when `transport` is set.                                                                             |
-| `model`      | `typesafe-ai/jev`                          | Decision model to call.                                                                                                         |
-| `debounceMs` | `500`                                      | Delay after the last edit before re-evaluating, in milliseconds.                                                                |
-| `tool`       | `true`                                     | Adds the Jev tool for setting, testing and removing the stored key.                                                             |
-| `tags`       | `['feature:jev-fields']`                   | AI Gateway reporting tags, for cost attribution. Each request also gets a tag for its signal, e.g. `jev.noul:article.readable`. |
+| Option       | Default                                    | Description                                                                                                                       |
+| ------------ | ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------- |
+| `transport`  |                                            | `(request, {signal}) => Promise<Response>`. Sends requests yourself, e.g. through your own server. See [API key](#api-key).       |
+| `apiKey`     |                                            | AI Gateway key. Bundled into the Studio's JavaScript; prefer the Jev tool or `transport`.                                         |
+| `endpoint`   | `https://ai-gateway.vercel.sh/v1/evaluate` | Where requests go. Ignored when `transport` is set.                                                                               |
+| `model`      | `typesafe-ai/jev`                          | Decision model to call.                                                                                                           |
+| `debounceMs` | `500`                                      | Delay after the last edit before re-evaluating, in milliseconds.                                                                  |
+| `tool`       | `true`                                     | Adds the Jev tool for setting, testing and removing the stored key.                                                               |
+| `tags`       | `['feature:jev-fields']`                   | AI Gateway reporting tags, for cost attribution. Each request also gets a tag for its question, e.g. `jev.noul:article.readable`. |
 
-### Signal options
+### Question options
 
-Every signal takes:
+Every question takes:
 
 | Option         | Description                                                                         |
 | -------------- | ----------------------------------------------------------------------------------- |
 | `instructions` | Required. The question Jev answers about the attached field.                        |
-| `title`        | Chip and detail heading. Defaults to the signal's key: `readable` → "Readable".     |
+| `title`        | Chip and detail heading. Defaults to the question's key: `readable` → "Readable".   |
 | `warn`         | Shows a warning on the field when the answer breaks this rule. See [Rules](#rules). |
 | `require`      | Blocks publishing when the answer breaks this rule.                                 |
 

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import { SchemaTypeDefinition } from "sanity";
 import "react";
 /** @public */
-type JevQuestion = {
+type GatewayQuestion = {
   type: 'boolean';
   instructions: string;
   criteria: {
@@ -18,7 +18,7 @@ type JevQuestion = {
   criteria: Record<string, string>;
 };
 /** @public */
-type JevAnswer = {
+type GatewayAnswer = {
   type: 'boolean';
   probability: number;
 } | {
@@ -41,7 +41,7 @@ interface JevRequest {
   model: string;
   state: string | Record<string, string>;
   questions: {
-    q: JevQuestion;
+    q: GatewayQuestion;
   };
   providerOptions: {
     gateway: {
@@ -78,12 +78,12 @@ interface JevPluginConfig {
   tool?: boolean;
   /**
    * AI Gateway reporting tags, for cost attribution. Defaults to `['feature:jev-fields']`.
-   * Each request also gets a per-signal tag, e.g. `jev.noul:article.readable`.
+   * Each request also gets a per-question tag, e.g. `jev.noul:article.readable`.
    */
   tags?: string[];
 }
 /** @public */
-interface ChoiceSignal extends SignalBase {
+interface ChoiceQuestion extends QuestionBase {
   type: 'choice';
   /** Two to 255 options: option name → what it means. */
   criteria: Record<string, string>;
@@ -97,7 +97,7 @@ interface ChoiceRule {
   oneOf: string[];
 }
 /** One option from a named set. @public */
-export declare const choice: (signal: Omit<ChoiceSignal, "type">) => ChoiceSignal;
+export declare const choice: (question: Omit<ChoiceQuestion, "type">) => ChoiceQuestion;
 interface ChoiceProbability {
   _key: string;
   _type?: 'jev.choiceProbability';
@@ -113,7 +113,7 @@ interface ChoiceValue extends EvaluatedValue {
   probabilities?: ChoiceProbability[];
 }
 /** @public */
-interface NoulSignal extends SignalBase {
+interface NoulQuestion extends QuestionBase {
   type: 'noul';
   /** What a "yes" means. Shown when the probability is 50% or higher. */
   true: string;
@@ -126,8 +126,8 @@ interface NoulSignal extends SignalBase {
   /** Block publishing when the probability is outside these bounds (0–1). */
   require?: RangeRule;
 }
-/** A yes/no signal: the chip shows the probability that the answer is yes. @public */
-export declare const noul: (signal: Omit<NoulSignal, "type">) => NoulSignal;
+/** A yes/no question: the chip shows the probability that the answer is yes. @public */
+export declare const noul: (question: Omit<NoulQuestion, "type">) => NoulQuestion;
 /** @public */
 interface NoulValue extends EvaluatedValue {
   _type?: 'jev.noul';
@@ -135,7 +135,7 @@ interface NoulValue extends EvaluatedValue {
   probability?: number;
 }
 /** @public */
-interface ScoreSignal extends SignalBase {
+interface ScoreQuestion extends QuestionBase {
   type: 'score';
   /**
    * Two to ten criteria, lowest first. Text before a colon becomes the short label,
@@ -154,7 +154,7 @@ interface ScoreSignal extends SignalBase {
   require?: RangeRule;
 }
 /** A position on an ordered scale. @public */
-export declare const score: (signal: Omit<ScoreSignal, "type">) => ScoreSignal;
+export declare const score: (question: Omit<ScoreQuestion, "type">) => ScoreQuestion;
 /** @public */
 interface ScoreValue extends EvaluatedValue {
   _type?: 'jev.score';
@@ -167,8 +167,8 @@ interface ScoreValue extends EvaluatedValue {
   /** The model's confidence in this score (0–1). */
   confidence?: number;
 }
-interface SignalBase {
-  /** Chip and detail heading. Defaults to the signal's key, e.g. `readable` → "Readable". */
+interface QuestionBase {
+  /** Chip and detail heading. Defaults to the question's key, e.g. `readable` → "Readable". */
   title?: string;
   /** The question Jev answers about the attached field. */
   instructions: string;
@@ -186,11 +186,11 @@ interface RangeRule {
   atMost?: number;
 }
 /** @public */
-type JevSignal = NoulSignal | ScoreSignal | ChoiceSignal;
-/** Signals attached to a field, keyed by the name of the field that stores each answer. */
-type JevSignals = Record<string, JevSignal>;
+type JevQuestion = NoulQuestion | ScoreQuestion | ChoiceQuestion;
+/** Questions attached to a field, keyed by the name of the field that stores each answer. */
+type JevQuestions = Record<string, JevQuestion>;
 /**
- * Adds a field that stores each signal's answer next to every field with `options.jev`.
+ * Adds a field that stores each question's answer next to every field with `options.jev`.
  * Plugins can't see the Studio's own schema types, so wrap them in `sanity.config`:
  *
  * ```ts
@@ -209,7 +209,7 @@ export declare const JEV_NAMESPACE: "jev";
 declare const resources: {
   readonly 'strip.label': "Jev";
   readonly 'strip.set-up': "Set up Jev";
-  readonly 'strip.evaluate-all': "Evaluate all signals now";
+  readonly 'strip.evaluate-all': "Evaluate all questions now";
   readonly 'chip.empty': "–";
   readonly 'chip.error': "Error";
   readonly 'chip.out-of-date': "Out of date";
@@ -239,7 +239,7 @@ declare const resources: {
   readonly 'key-dialog.saving': "Saving…";
   readonly 'key-dialog.save-failed': "Could not save the key: {{error}}";
   readonly 'tool.title': "Jev";
-  readonly 'tool.intro': "Jev signals are answered by TypeSafe’s Jev model through Vercel AI Gateway.";
+  readonly 'tool.intro': "Jev questions are answered by TypeSafe’s Jev model through Vercel AI Gateway.";
   readonly 'tool.key.heading': "AI Gateway API key";
   readonly 'tool.key.status.config': "From plugin config";
   readonly 'tool.key.status.checking': "Checking";
@@ -250,11 +250,11 @@ declare const resources: {
   readonly 'tool.key.ends-with': "Key ending in <Code>{{last4}}</Code>";
   readonly 'tool.key.changed': "Last changed {{date}}";
   readonly 'tool.key.checking': "Checking for a stored key…";
-  readonly 'tool.key.none': "No key is stored, so Jev signals cannot evaluate yet.";
+  readonly 'tool.key.none': "No key is stored, so Jev questions can’t be evaluated yet.";
   readonly 'tool.key.set': "Set key";
   readonly 'tool.key.change': "Change key";
   readonly 'tool.key.remove': "Remove key";
-  readonly 'tool.key.remove-confirm': "Remove the key? Jev signals stop evaluating until a new one is set.";
+  readonly 'tool.key.remove-confirm': "Remove the key? Jev questions stop being evaluated until a new one is set.";
   readonly 'tool.key.remove-cancel': "Cancel";
   readonly 'tool.key.remove-confirm-button': "Remove";
   readonly 'tool.key.remove-failed': "Could not remove the key: {{error}}";
@@ -268,16 +268,16 @@ declare const resources: {
 type JevTranslationKey = keyof typeof resources;
 declare module 'sanity' {
   interface BaseSchemaTypeOptions {
-    /** Jev signals shown on this field, keyed by the name of the field storing each answer. */
-    jev?: JevSignals;
+    /** Jev questions shown on this field, keyed by the name of the field storing each answer. */
+    jev?: JevQuestions;
   }
 }
 /**
- * Jev signals for Sanity Studio: yes/no, score and choice questions attached to a field with
+ * Jev questions for Sanity Studio: yes/no, score and choice questions attached to a field with
  * `options.jev`, answered by TypeSafe's Jev model through Vercel AI Gateway. Pair it with
  * `withJevAnswers(schemaTypes)` in `schema.types`.
  * @public
  */
 export declare const jev: import("sanity").Plugin<void | JevPluginConfig>;
-export type { ChoiceRule, ChoiceSignal, ChoiceValue, JevAnswer, JevPluginConfig, JevQuestion, JevRequest, JevSignal, JevSignals, JevTranslationKey, JevTransport, NoulSignal, NoulValue, RangeRule, ScoreSignal, ScoreValue };
+export type { ChoiceQuestion, ChoiceRule, ChoiceValue, GatewayAnswer, GatewayQuestion, JevPluginConfig, JevQuestion, JevQuestions, JevRequest, JevTranslationKey, JevTransport, NoulQuestion, NoulValue, RangeRule, ScoreQuestion, ScoreValue };
 //# sourceMappingURL=index.d.ts.map