@larc-iu/plaid-client 0.2.0-alpha.2 → 0.2.0-alpha.21

package/src/roles.js

@@ -25,6 +25,23 @@ export const PLAID_NAMESPACE = 'plaid';
 export const ROLE_KEY = 'role';
 
 /** The fixed role inventory. */
+/**
+ * Layer config key naming the metadata keys a token born of a SPLIT inherits
+ * from the token it came from. Plaid honors it without knowing what the keys
+ * mean; see the manual's `Metadata Preserved Across a Split`. An app declares
+ * it so that a split in ANY app, including one that has never heard of these
+ * keys, does not silently drop them.
+ */
+export const PRESERVE_ON_SPLIT_KEY = 'preserveOnSplit';
+
+/**
+ * Layer config key (true): a space typed inside a token of the text's words
+ * splits it, the token going on the half sharing more letters with it.
+ * Declared on a word layer another app shares, it holds for the whole text.
+ * See the manual's `Changing a text's body`.
+ */
+export const SPLIT_ON_SPACE_KEY = 'splitOnSpace';
+
 export const ROLES = Object.freeze({
   BASELINE: 'baseline',
   SENTENCE: 'sentence',

package/src/serviceSchema.js

@@ -16,16 +16,21 @@
  *
  *   {
  *     schemaVersion: 1,
- *     tasks: ["tokenize"],              // controlled vocab; REPLACES tok:/asr: id prefixes
+ *     tasks: ["tokenize"],              // controlled vocab (TASKS)
  *     summary: "## markdown …",         // rich human description
  *     parameters: [                     // ordered; rendered into a form
  *       { key, label, type, description?, default?, required?,
  *         options?: [{value, label}],   // enum / multiselect
- *         min?, max?, step?,            // number
- *         placeholder?, multiline? }    // string
+ *         min?, max?, step?, slider?,   // number (slider: drag, don't type)
+ *         placeholder?, multiline?,     // string
+ *         scope? }                      // field: 'Sentence' | 'Word' | 'Morpheme'
  *     ]
  *   }
  *
+ * A `field` parameter names one of the project's annotation fields at its
+ * `scope`. A UI that knows the project offers those fields to choose from; to
+ * everything here, and to a UI that does not, it is a string.
+ *
  * A parameter's `key` is a string VALUE, so it passes over the wire verbatim;
  * the UI sends `{ [param.key]: value }` in the request data. Declare each `key`
  * in your service's own convention (Python: snake_case; JS: camelCase) and read
@@ -43,38 +48,59 @@
  * without an explicit `overwrite` parameter. See the manual, "Provenance".
  */
 export const TASKS = Object.freeze({
-  TOKENIZE: 'tokenize',
-  PARSE: 'parse',
-  TRANSCRIBE: 'transcribe',
+  TOKENIZE: "tokenize",
+  PARSE: "parse",
+  TRANSCRIBE: "transcribe",
   /** Create vocab links for unlinked tokens. */
-  LINK_VOCAB: 'link-vocab',
+  LINK_VOCAB: "link-vocab",
   /** Propose an interlinear analysis (morpheme segmentation + glosses) for words. */
-  ANALYZE: 'analyze',
-});
-
-/**
- * Legacy id-prefix → task map, for services that have not yet migrated to a
- * declared `tasks` array. Drop once all services advertise `tasks`.
- */
-const LEGACY_TASK_PREFIXES = Object.freeze({
-  [TASKS.TOKENIZE]: 'tok:',
-  [TASKS.TRANSCRIBE]: 'asr:',
+  ANALYZE: "analyze",
+  /**
+   * Draft a meaning representation graph over the sentences of a document,
+   * for correction by hand. The request names a `scope` ('document' or
+   * 'sentence'), a `sentence` number when the scope is one sentence, and
+   * `overwrite`. See plaid-umr's drafting services.
+   *
+   * Apart from `analyze` on purpose. A task is the CONTRACT a spot offers a
+   * service against, and these two share almost none of it: an analyze
+   * request names the three token layers plus the language and metalanguage,
+   * and writes morphemes and glosses. Both claimed `analyze` for
+   * a while, so every app offering an analyze spot offered the other app's
+   * services, which could not answer the request they would have been given.
+   */
+  DRAFT_GRAPH: "draft-graph",
+  /** Propose a free translation for each sentence. */
+  TRANSLATE: "translate",
+  /**
+   * Propose time-aligned speech regions for a recording.
+   *
+   * The odd one out: a detect-speech service RETURNS its regions and writes
+   * nothing, because a time-aligned segment is a stretch of the baseline and
+   * cannot exist without text. The response carries
+   * `{segments: [{timeBegin, timeEnd, speaker?}]}` (seconds), and the app
+   * holds them as proposals until a person types into one.
+   */
+  DETECT_SPEECH: "detect-speech",
+  /** A conversational assistant over a project (chat turns; see plaid-agent). */
+  ASSIST: "assist",
+  /**
+   * Score one document's annotation against another document's of the same
+   * text (two annotators' copies), writing a report on the scored document's
+   * metadata and never an annotation. The request names the other document
+   * as `against`. See plaid-umr's AnCast service.
+   */
+  COMPARE: "compare",
 });
 
 /**
- * Does `service` serve `task`? Prefers the declared `extras.tasks` array; falls
- * back to the legacy id-prefix convention for un-migrated services.
+ * Does `service` serve `task`, as its declared `extras.tasks` says?
  * @param {{serviceId?: string, extras?: {tasks?: string[]}}} service
  * @param {string} task one of TASKS
  * @returns {boolean}
  */
 export function servesTask(service, task) {
   const declared = service?.extras?.tasks;
-  if (Array.isArray(declared) && declared.length) {
-    return declared.includes(task);
-  }
-  const prefix = LEGACY_TASK_PREFIXES[task];
-  return !!prefix && typeof service?.serviceId === 'string' && service.serviceId.startsWith(prefix);
+  return Array.isArray(declared) && declared.includes(task);
 }
 
 /**
@@ -104,7 +130,7 @@ export function getParamSchema(service) {
  * @returns {string}
  */
 export function getServiceSummary(service) {
-  return service?.extras?.summary || service?.description || '';
+  return service?.extras?.summary || service?.description || "";
 }
 
 /** Valid option values for an enum/multiselect param. */
@@ -119,20 +145,25 @@ function optionValues(param) {
  */
 function defaultForParam(param) {
   const opts = optionValues(param);
-  if (param.type === 'enum') {
-    if (param.default != null && opts.includes(param.default)) return param.default;
-    return opts[0] ?? '';
+  if (param.type === "enum") {
+    if (param.default != null && opts.includes(param.default))
+      return param.default;
+    return opts[0] ?? "";
   }
-  if (param.type === 'multiselect') {
+  if (param.type === "multiselect") {
     const arr = Array.isArray(param.default) ? param.default : [];
     return opts.length ? arr.filter((x) => opts.includes(x)) : arr;
   }
-  if (param.default !== undefined && param.default !== null) return param.default;
+  if (param.default !== undefined && param.default !== null)
+    return param.default;
   switch (param.type) {
-    case 'number': return typeof param.min === 'number' ? param.min : 0;
-    case 'boolean': return false;
-    case 'string':
-    default: return '';
+    case "number":
+      return typeof param.min === "number" ? param.min : 0;
+    case "boolean":
+      return false;
+    case "string":
+    default:
+      return "";
   }
 }
 
@@ -169,43 +200,48 @@ export function coerceParamValues(schema, raw) {
     if (v === undefined) v = defaultForParam(param);
 
     switch (param.type) {
-      case 'number': {
+      case "number": {
         // Blank / nullish counts as "missing" → the param's default (matches the
         // Python client, where float('') raises and falls back to the default).
         let n;
-        if (v === '' || v == null || (typeof v === 'string' && v.trim() === '')) {
+        if (
+          v === "" ||
+          v == null ||
+          (typeof v === "string" && v.trim() === "")
+        ) {
           n = defaultForParam(param);
         } else {
-          n = typeof v === 'number' ? v : Number(v);
+          n = typeof v === "number" ? v : Number(v);
           if (Number.isNaN(n)) n = defaultForParam(param);
         }
-        if (typeof param.min === 'number') n = Math.max(param.min, n);
-        if (typeof param.max === 'number') n = Math.min(param.max, n);
+        if (typeof param.min === "number") n = Math.max(param.min, n);
+        if (typeof param.max === "number") n = Math.min(param.max, n);
         v = n;
         break;
       }
-      case 'boolean':
-        v = v === true || v === 'true';
+      case "boolean":
+        v = v === true || v === "true";
         break;
-      case 'enum': {
+      case "enum": {
         const opts = optionValues(param);
         if (opts.length && !opts.includes(v)) v = defaultForParam(param);
         break;
       }
-      case 'multiselect': {
+      case "multiselect": {
         const opts = optionValues(param);
-        const arr = Array.isArray(v) ? v : (v == null || v === '' ? [] : [v]);
+        const arr = Array.isArray(v) ? v : v == null || v === "" ? [] : [v];
         v = opts.length ? arr.filter((x) => opts.includes(x)) : arr;
         break;
       }
-      case 'string':
+      case "string":
       default:
-        v = v == null ? '' : String(v);
+        v = v == null ? "" : String(v);
         break;
     }
 
     if (param.required) {
-      const empty = v === '' || v == null || (Array.isArray(v) && v.length === 0);
+      const empty =
+        v === "" || v == null || (Array.isArray(v) && v.length === 0);
       if (empty) errors[k] = `${param.label || k} is required`;
     }
     values[k] = v;