@larc-iu/plaid-client 0.1.0-alpha.8 → 0.2.0-alpha.0

package/src/provenance.js

@@ -0,0 +1,123 @@
+/**
+ * Provenance: the cross-app convention for distinguishing machine-provided
+ * from human-labeled information, expressed as flat metadata keys on
+ * annotation entities (spans, relations, vocab links, optionally tokens).
+ * Flat scalar keys — the query engine matches flat metadata well, nested
+ * objects poorly.
+ *
+ * Three states (the PRESENCE of the `prov` key, not its value, is the
+ * discriminator; absent keys mean "human"):
+ *
+ *   human              — no prov keys; a person made it.
+ *   machine            — { prov: 'inferred', provSource: '<producer>' };
+ *                        an algorithm/service made it, no human has vouched.
+ *   verified           — same + { provConfirmed: true }; machine-made and a
+ *                        human confirmed (or edited) it. provSource stays so
+ *                        machine origin remains traceable.
+ *
+ * The write contract every machine writer must follow:
+ *   1. Machine writers may freely replace MACHINE (unverified) material.
+ *   2. Machine writers must never modify or delete human or verified
+ *      material unless explicitly told to overwrite (an explicit, per-run,
+ *      user-facing opt-in — for services, a declared boolean `overwrite`
+ *      parameter).
+ *   3. Any human edit of a machine annotation verifies it: the edit also
+ *      stamps { provConfirmed: true } (see verifyOnEdit).
+ *
+ * Producer naming: 'service:<serviceId>' for services (use serviceSource),
+ * 'rule:<name>' for built-in rule algorithms, app-specific ids like
+ * 'gloss:doc-frequency' or 'flex-import' otherwise.
+ *
+ * PREDICTION EXTRAS. A producer may also record how confident it was and
+ * what else it considered, in two reserved slots split along the
+ * queryability line:
+ *   - provProb: ONE flat number in [0, 1] — the producer's probability for
+ *     the value it chose. Flat scalars are what the query engine filters
+ *     and orders on, so "review the least-confident machine output first"
+ *     is an ordinary query. Omit it unless you can honestly produce a
+ *     probability (a raw logprob is NOT one — put it in provDetail).
+ *   - provDetail: ONE open map for everything else — top-k alternatives or
+ *     distributions, model name/version, raw scores. Deliberately nested
+ *     (not queryable); keep it small (top-k, not whole-vocabulary dumps).
+ * Both describe the machine's ORIGINAL prediction. They are kept after
+ * human edits (history is valuable), so a consumer must not present
+ * provProb as confidence in the CURRENT value once the entity is verified
+ * (provConfirmed is exactly the flag to check).
+ */
+
+/** The flat metadata keys of the provenance convention. */
+export const PROV = Object.freeze({
+  /** 'inferred' when produced by an algorithm/service; absent = human. */
+  key: 'prov',
+  /** Which producer, e.g. 'service:<id>', 'rule:precedent-or-unique'. */
+  sourceKey: 'provSource',
+  /** true once a human confirmed (or edited) the inferred value. */
+  confirmedKey: 'provConfirmed',
+  /** Producer's probability ([0,1]) for the chosen value. Flat = queryable. */
+  probKey: 'provProb',
+  /** Open map of producer extras (alternatives, model version, raw scores). */
+  detailKey: 'provDetail',
+  /** The (currently only) value of `prov`. Presence, not value, decides. */
+  INFERRED: 'inferred',
+});
+
+/** The three provenance states returned by provState. */
+export const PROV_STATES = Object.freeze({
+  HUMAN: 'human',
+  MACHINE: 'machine',
+  VERIFIED: 'verified',
+});
+
+/**
+ * The metadata fragment a machine writer merges into everything it creates.
+ * @param {string} source - producer id, e.g. serviceSource(serviceId)
+ * @param {Object} [extras] - optional prediction extras:
+ * @param {number} [extras.prob] - probability in [0,1] for the chosen value
+ *   (omit unless it honestly is one — raw scores go in detail)
+ * @param {Object} [extras.detail] - open map of producer extras (top-k
+ *   alternatives, model version, raw scores; keep it small)
+ */
+export const stampInferred = (source, { prob, detail } = {}) => ({
+  [PROV.key]: PROV.INFERRED,
+  [PROV.sourceKey]: source,
+  ...(prob !== undefined && prob !== null ? { [PROV.probKey]: prob } : {}),
+  ...(detail ? { [PROV.detailKey]: detail } : {}),
+});
+
+/**
+ * The fragment for machine-made material that is born verified (e.g. an
+ * import carrying upstream human approval, or a guess written only on
+ * explicit user confirmation). Takes the same optional prediction extras
+ * as stampInferred.
+ */
+export const confirmedInferred = (source, extras = {}) => ({
+  ...stampInferred(source, extras),
+  [PROV.confirmedKey]: true,
+});
+
+/**
+ * Classify an entity's metadata into one of PROV_STATES.
+ * @param {Object|null|undefined} metadata
+ * @returns {'human'|'machine'|'verified'}
+ */
+export const provState = (metadata) => {
+  if (!metadata || metadata[PROV.key] == null) return PROV_STATES.HUMAN;
+  return metadata[PROV.confirmedKey] ? PROV_STATES.VERIFIED : PROV_STATES.MACHINE;
+};
+
+/**
+ * Whether a machine writer must leave this entity alone (write-contract
+ * rule 2): true for human-made and human-verified material.
+ */
+export const isProtected = (metadata) => provState(metadata) !== PROV_STATES.MACHINE;
+
+/**
+ * The metadata fragment a HUMAN edit of this entity should merge in
+ * (write-contract rule 3): { provConfirmed: true } when the entity is
+ * machine-made and unverified, else null (nothing to do).
+ */
+export const verifyOnEdit = (metadata) =>
+  (provState(metadata) === PROV_STATES.MACHINE ? { [PROV.confirmedKey]: true } : null);
+
+/** Canonical provSource for a service: 'service:<serviceId>'. */
+export const serviceSource = (serviceId) => `service:${serviceId}`;

package/src/roles.js

@@ -0,0 +1,57 @@
+/**
+ * Shared layer-role vocabulary for cross-app interoperability.
+ *
+ * Apps that share a Plaid project agree on the *substrate* — the text and token
+ * layers — by tagging each shared layer with a ROLE under the reserved `plaid`
+ * config namespace (`config.plaid.role`, a scalar). Annotations stay private to
+ * each app under that app's own namespace. See the Plaid manual, "Layer
+ * Interoperability". The role inventory is small and fixed:
+ *
+ *   baseline        the primary text layer
+ *   sentence        sentence token layer
+ *   word            orthographic-word token layer (CoNLL-U "token")
+ *   syntactic-word  grammatical words below the word (CoNLL-U "word" / MWT splits)
+ *   morpheme        morpheme token layer
+ *   time-alignment  media-timeline token layer
+ *
+ * Only these values are understood across apps; an app may store any string but
+ * loses interoperability for unknown values.
+ */
+
+/** The reserved config namespace for cross-app conventions. */
+export const PLAID_NAMESPACE = 'plaid';
+
+/** The config key, under `plaid`, holding a layer's role. */
+export const ROLE_KEY = 'role';
+
+/** The fixed role inventory. */
+export const ROLES = Object.freeze({
+  BASELINE: 'baseline',
+  SENTENCE: 'sentence',
+  WORD: 'word',
+  SYNTACTIC_WORD: 'syntactic-word',
+  MORPHEME: 'morpheme',
+  TIME_ALIGNMENT: 'time-alignment',
+});
+
+/**
+ * The role recorded on a layer's `config`, or null if none.
+ * @param {object} [config] a layer's `config` object
+ * @returns {string|null}
+ */
+export function readRole(config) {
+  const v = config?.[PLAID_NAMESPACE]?.[ROLE_KEY];
+  return v == null ? null : v;
+}
+
+/**
+ * The first layer in `layers` carrying the given role, or null. The single
+ * "find a layer by its role" primitive — apps build their named finders
+ * (findWordTokenLayer, etc.) on top of this.
+ * @param {Array<{config?: object}>} [layers]
+ * @param {string} role
+ * @returns {object|null}
+ */
+export function findByRole(layers, role) {
+  return (layers || []).find(l => readRole(l?.config) === role) || null;
+}

package/src/serviceSchema.js

@@ -0,0 +1,212 @@
+/**
+ * Service self-description: tasks, summary, and a parameter schema.
+ *
+ * The service framework's transport carries an opaque `extras` JSON map on every
+ * registered service (see services.js). This module standardizes what a service
+ * advertises in that map so apps can, at a fixed integration point (a "task"
+ * like tokenize / parse / transcribe):
+ *
+ *   1. SELECT one of several services that serve the task,
+ *   2. let the user SPECIFY arguments the service declares, and
+ *   3. show the user a service-provided SUMMARY.
+ *
+ * Shape of a service's `extras` (camelCase here; Python services author the
+ * snake_case equivalent and the client transform converts it — see the Plaid
+ * manual, "Describing a service"):
+ *
+ *   {
+ *     schemaVersion: 1,
+ *     tasks: ["tokenize"],              // controlled vocab; REPLACES tok:/asr: id prefixes
+ *     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
+ *     ]
+ *   }
+ *
+ * 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
+ * it back under that same key — request data is recased symmetrically, so a
+ * snake_case key round-trips unchanged to a JS UI and back.
+ */
+
+/**
+ * The controlled task vocabulary — the fixed integration-point goals.
+ *
+ * Whatever the task, a service should stamp everything it creates with the
+ * provenance convention (see ./provenance.js: stampInferred(serviceSource(id)))
+ * so UIs can distinguish machine output until a human verifies it, and should
+ * honor the write contract: never destroy human-made or verified material
+ * without an explicit `overwrite` parameter. See the manual, "Provenance".
+ */
+export const TASKS = Object.freeze({
+  TOKENIZE: 'tokenize',
+  PARSE: 'parse',
+  TRANSCRIBE: 'transcribe',
+  /** Create vocab links for unlinked tokens. */
+  LINK_VOCAB: 'link-vocab',
+});
+
+/**
+ * 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:',
+});
+
+/**
+ * Does `service` serve `task`? Prefers the declared `extras.tasks` array; falls
+ * back to the legacy id-prefix convention for un-migrated services.
+ * @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);
+}
+
+/**
+ * The discovered services that serve `task`.
+ * @param {Array} services result of client.messages.discoverServices()
+ * @param {string} task one of TASKS
+ * @returns {Array}
+ */
+export function filterServicesByTask(services, task) {
+  return (services || []).filter((s) => servesTask(s, task));
+}
+
+/**
+ * The parameter schema a service declares (ordered array), or [].
+ * @param {{extras?: {parameters?: Array}}} service
+ * @returns {Array}
+ */
+export function getParamSchema(service) {
+  const params = service?.extras?.parameters;
+  return Array.isArray(params) ? params : [];
+}
+
+/**
+ * A service's human summary: the rich `extras.summary`, else the short
+ * `description`, else ''.
+ * @param {{description?: string, extras?: {summary?: string}}} service
+ * @returns {string}
+ */
+export function getServiceSummary(service) {
+  return service?.extras?.summary || service?.description || '';
+}
+
+/** Valid option values for an enum/multiselect param. */
+function optionValues(param) {
+  return Array.isArray(param?.options) ? param.options.map((o) => o.value) : [];
+}
+
+/**
+ * A single parameter's default, honoring its declared `default` then falling
+ * back per type. For enum/multiselect the declared default is validated against
+ * `options` (an out-of-range declared default never escapes).
+ */
+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 === '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;
+  switch (param.type) {
+    case 'number': return typeof param.min === 'number' ? param.min : 0;
+    case 'boolean': return false;
+    case 'string':
+    default: return '';
+  }
+}
+
+/**
+ * Default values keyed by param key — the initial form state.
+ * @param {Array} schema getParamSchema(service)
+ * @returns {Object} { [key]: defaultValue }
+ */
+export function buildDefaultValues(schema) {
+  const out = {};
+  for (const param of schema || []) {
+    if (!param || !param.key) continue;
+    out[param.key] = defaultForParam(param);
+  }
+  return out;
+}
+
+/**
+ * Coerce/validate raw form values against the schema. Returns the cleaned
+ * values (keyed by param key, ready to merge into the request payload) plus any
+ * validation errors keyed by param key. Unknown keys in `raw` are dropped.
+ * @param {Array} schema getParamSchema(service)
+ * @param {Object} raw current form values
+ * @returns {{values: Object, errors: Object}}
+ */
+export function coerceParamValues(schema, raw) {
+  const values = {};
+  const errors = {};
+  const src = raw || {};
+  for (const param of schema || []) {
+    if (!param || !param.key) continue;
+    const k = param.key;
+    let v = src[k];
+    if (v === undefined) v = defaultForParam(param);
+
+    switch (param.type) {
+      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() === '')) {
+          n = defaultForParam(param);
+        } else {
+          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);
+        v = n;
+        break;
+      }
+      case 'boolean':
+        v = v === true || v === 'true';
+        break;
+      case 'enum': {
+        const opts = optionValues(param);
+        if (opts.length && !opts.includes(v)) v = defaultForParam(param);
+        break;
+      }
+      case 'multiselect': {
+        const opts = optionValues(param);
+        const arr = Array.isArray(v) ? v : (v == null || v === '' ? [] : [v]);
+        v = opts.length ? arr.filter((x) => opts.includes(x)) : arr;
+        break;
+      }
+      case 'string':
+      default:
+        v = v == null ? '' : String(v);
+        break;
+    }
+
+    if (param.required) {
+      const empty = v === '' || v == null || (Array.isArray(v) && v.length === 0);
+      if (empty) errors[k] = `${param.label || k} is required`;
+    }
+    values[k] = v;
+  }
+  return { values, errors };
+}

package/src/services.js

@@ -11,18 +11,34 @@
 import { transformRequest, transformResponse } from './transforms.js';
 
 /**
- * Discover the services currently connected to a project — a synchronous GET.
- * `timeout` is accepted for back-compat and ignored.
+ * Discover the services seen on a project — a synchronous GET. Returns every
+ * service ever registered on the project: currently connected ones carry
+ * `online: true`; previously-seen offline ones carry `online: false` plus a
+ * `lastSeenAt` stamp. Callers that need a service they can actually submit
+ * work to should filter on `online`.
  *
  * @param {Object} client - PlaidClient instance
  * @param {string} projectId - Project UUID
- * @param {number} [timeout] - Ignored
- * @returns {Promise<Array>} [{serviceId, serviceName, description, extras}]
+ * @returns {Promise<Array>} [{serviceId, serviceName, description, extras, online, lastSeenAt}]
  */
-export function discoverServices(client, projectId, timeout) {
+export function discoverServices(client, projectId) {
   return client._request('GET', `/api/v1/projects/${projectId}/services`);
 }
 
+/**
+ * Forget a previously-seen (offline) service: removes its row from the
+ * project's persistent registry. Maintainer-only; 409 if the service is
+ * currently connected (it would just re-register).
+ *
+ * @param {Object} client - PlaidClient instance
+ * @param {string} projectId - Project UUID
+ * @param {string} serviceId - Service ID to forget
+ * @returns {Promise<void>}
+ */
+export function discardService(client, projectId, serviceId) {
+  return client._request('DELETE', `/api/v1/projects/${projectId}/services/${encodeURIComponent(serviceId)}`);
+}
+
 /**
  * Register a service and handle incoming work requests.
  *

package/src/sse.js

@@ -75,6 +75,13 @@ export function createSSEConnection(client, projectId, onEvent, path) {
       });
 
       if (!response.ok) {
+        if (response.status === 409 && streamPath.includes('/services/')) {
+          // Service channel rejected: another live instance holds this
+          // service-id. The serve() reconnect timer will retry — once the
+          // other instance is gone (or its dead channel is reaped) the retry
+          // takes over.
+          console.warn('Service registration rejected (409): another instance of this service is already connected; will retry');
+        }
         throw new Error(`HTTP ${response.status} ${response.statusText}`);
       }
 

package/src/transforms.js

@@ -25,7 +25,7 @@ export function transformKeyFromCamel(key) {
 // are never re-cased or namespace-stripped — a label like `case-marker` used as
 // a map key survives intact. Everything else is API envelope and gets the
 // usual case conversion.
-const OPAQUE_KEYS = new Set(['metadata', 'config']);
+const OPAQUE_KEYS = new Set(['metadata', 'config', 'bindings']);
 
 /**
  * Recursively transform request object keys from camelCase to kebab-case.