@larc-iu/plaid-client 0.2.0-alpha.3 → 0.2.0-alpha.32

package/src/requester.js

@@ -0,0 +1,74 @@
+// Who asked for a service run, named in what the run leaves behind.
+//
+// A plain service writes with its own token, so the History entry of a run
+// reads "by <operator> (via <token>)" and the person who pressed the button is
+// recorded nowhere. Core tells every service who asked (`requesterId` in the
+// request data), and every app's services put that person in the History
+// label and in what they store:
+//
+//   AnCast adjudication against lunch, requested by second
+//
+// This is the JS twin of `plaid_client.workflows.requester`, for a service
+// authored with `serve`. The wording and the stored key are the same.
+//
+// The name is the requester's display name, which any signed-in user may
+// read. When it cannot be read the id stands in for it, and with no requester
+// at all the label is left as it was and nothing is stored.
+
+/**
+ * The person who asked for one service run. Both fields are null when nobody
+ * asked.
+ * @typedef {object} Requester
+ * @property {string | null} id
+ * @property {string | null} name
+ * @property {(text: string) => string} label `"<text>, requested by <name>"`,
+ *   or `text` when nobody asked.
+ * @property {() => ({id: string, name: string | null} | null)} record
+ *   `{ id, name }` for a stored report, or null when nobody asked.
+ * @property {(detail?: Record<string, any>) => Record<string, any>} detail A
+ *   machine stamp's `provDetail` with `requestedBy: <id>` added.
+ */
+
+/** The key a run's stored record names its requester under. */
+export const REQUESTED_BY = /** @type {const} */ ("requestedBy");
+
+/**
+ * The person who asked for one run: `id` is their account (their email),
+ * `name` how they are shown. Both are null when nobody asked.
+ * @param {string | null} [id]
+ * @param {string | null} [name]
+ * @returns {Requester}
+ */
+export function makeRequester(id = null, name = null) {
+  return {
+    id,
+    name,
+    /** A History label with the requester named, or `text` when nobody asked. */
+    label: (text) => (name ? `${text}, requested by ${name}` : text),
+    /** `{ id, name }` for a stored report, or null when nobody asked. */
+    record: () => (id ? { id, name } : null),
+    /** A machine stamp's `provDetail` with the requester's id added. */
+    detail: (detail = {}) => ({ ...(detail || {}), ...(id ? { [REQUESTED_BY]: id } : {}) }),
+  };
+}
+
+/**
+ * The requester of one request, from the `requesterId` core put in its data,
+ * with their display name read through `client`.
+ * @param {{users: {get(id: string): Promise<any>}}} client - A PlaidClient (only `users.get` is used)
+ * @param {any} data - The request data a `serve` handler receives
+ * @returns {Promise<Requester>}
+ */
+export async function requesterOf(client, data) {
+  const id = data && typeof data === "object" ? data.requesterId || null : null;
+  if (!id) return makeRequester();
+  let name = null;
+  try {
+    name = (await client.users.get(id))?.displayName || null;
+  } catch (error) {
+    // The id is always there to fall back on, so a failed read costs the
+    // label nothing but the nicer name.
+    console.warn(`Could not read the requester ${id}: ${error?.message || error}`);
+  }
+  return makeRequester(id, name || id);
+}

package/src/roles.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Whether a project records research telemetry: `config.plaid.research.telemetry`
+ * is exactly true.
+ * @param {object} [config] a project's `config` object
+ * @returns {boolean}
+ */
+export function readResearchTelemetry(config?: object): boolean;
+/**
+ * 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?: object): string | null;
+/**
+ * The ignored-tokens rule on a word layer's `config` (see
+ * `IGNORED_TOKENS_KEY`), or null if none. The one reader of the key in JS.
+ * @param {object} [config] a token layer's `config` object
+ * @returns {{type: string, whitelist?: string[], blacklist?: string[]}|null}
+ */
+export function readIgnoredTokens(config?: object): {
+    type: string;
+    whitelist?: string[];
+    blacklist?: string[];
+} | null;
+/**
+ * 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.
+ * @template {{config?: object}} T
+ * @param {T[] | undefined} layers
+ * @param {string} role
+ * @returns {T | null}
+ */
+export function findByRole<T extends {
+    config?: object;
+}>(layers: T[] | undefined, role: string): T | null;
+/**
+ * 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. */
+/**
+ * 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";
+/**
+ * Word layer config key holding the ignored-tokens rule,
+ * `{type, whitelist, blacklist}`: under `type: 'unicodePunctuation'` a word made
+ * only of punctuation is ignored and each one-character entry of `whitelist` is
+ * a letter, under `type: 'blacklist'` the entries of `blacklist` are the words
+ * ignored and its one-character entries the only characters that part words.
+ * Plaid's text rules and the built-in tokenizer read it. See the manual's
+ * `Changing a text's body`.
+ */
+export const IGNORED_TOKENS_KEY: "ignoredTokens";
+/**
+ * Project config key (false to hide): whether the project's tartan shows beside
+ * its name. Absent means shown.
+ */
+export const TARTAN_KEY: "tartan";
+/**
+ * Project config key holding the research settings, `{telemetry}`. Client
+ * events are recorded only while `telemetry` is true. See the manual's
+ * `Research telemetry`.
+ */
+export const RESEARCH_KEY: "research";
+export const ROLES: Readonly<{
+    BASELINE: "baseline";
+    SENTENCE: "sentence";
+    WORD: "word";
+    SYNTACTIC_WORD: "syntactic-word";
+    MORPHEME: "morpheme";
+    TIME_ALIGNMENT: "time-alignment";
+}>;

package/src/roles.js

@@ -25,6 +25,57 @@ 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';
+
+/**
+ * Word layer config key holding the ignored-tokens rule,
+ * `{type, whitelist, blacklist}`: under `type: 'unicodePunctuation'` a word made
+ * only of punctuation is ignored and each one-character entry of `whitelist` is
+ * a letter, under `type: 'blacklist'` the entries of `blacklist` are the words
+ * ignored and its one-character entries the only characters that part words.
+ * Plaid's text rules and the built-in tokenizer read it. See the manual's
+ * `Changing a text's body`.
+ */
+export const IGNORED_TOKENS_KEY = 'ignoredTokens';
+
+/**
+ * Project config key (false to hide): whether the project's tartan shows beside
+ * its name. Absent means shown.
+ */
+export const TARTAN_KEY = 'tartan';
+
+/**
+ * Project config key holding the research settings, `{telemetry}`. Client
+ * events are recorded only while `telemetry` is true. See the manual's
+ * `Research telemetry`.
+ */
+export const RESEARCH_KEY = 'research';
+
+/**
+ * Whether a project records research telemetry: `config.plaid.research.telemetry`
+ * is exactly true.
+ * @param {object} [config] a project's `config` object
+ * @returns {boolean}
+ */
+export function readResearchTelemetry(config) {
+  return config?.[PLAID_NAMESPACE]?.[RESEARCH_KEY]?.telemetry === true;
+}
+
 export const ROLES = Object.freeze({
   BASELINE: 'baseline',
   SENTENCE: 'sentence',
@@ -44,13 +95,24 @@ export function readRole(config) {
   return v == null ? null : v;
 }
 
+/**
+ * The ignored-tokens rule on a word layer's `config` (see
+ * `IGNORED_TOKENS_KEY`), or null if none. The one reader of the key in JS.
+ * @param {object} [config] a token layer's `config` object
+ * @returns {{type: string, whitelist?: string[], blacklist?: string[]}|null}
+ */
+export function readIgnoredTokens(config) {
+  return config?.[PLAID_NAMESPACE]?.[IGNORED_TOKENS_KEY] ?? null;
+}
+
 /**
  * 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]
+ * @template {{config?: object}} T
+ * @param {T[] | undefined} layers
  * @param {string} role
- * @returns {object|null}
+ * @returns {T | null}
  */
 export function findByRole(layers, role) {
   return (layers || []).find(l => readRole(l?.config) === role) || null;

package/src/serviceSchema.d.ts

@@ -0,0 +1,337 @@
+/**
+ * One choice for an `enum` or `multiselect` service parameter.
+ * @typedef {{value: string, label: string}} ServiceParamOption
+ */
+/**
+ * A single user-controllable argument a service advertises.
+ * @typedef {object} ServiceParam
+ * @property {string} key Key the value is sent under in the request payload.
+ * @property {string} label
+ * @property {"string" | "number" | "boolean" | "enum" | "multiselect" | "field"} type
+ * @property {string} [description]
+ * @property {any} [default]
+ * @property {boolean} [required]
+ * @property {ServiceParamOption[]} [options] Required for `enum` and `multiselect`.
+ * @property {number} [min] `number` only.
+ * @property {number} [max] `number` only.
+ * @property {number} [step] `number` only.
+ * @property {boolean} [slider] `number` only: render as a slider to drag
+ *   rather than a box to type in.
+ * @property {string} [placeholder] `string` only.
+ * @property {boolean} [multiline] `string` only.
+ * @property {"Sentence" | "Word" | "Morpheme"} [scope] `field` only: the
+ *   scope of the project's annotation fields the value names one of. A
+ *   `field` value is a string everywhere else.
+ * @property {string} [role] `field` only: the lexicon role whose paired field,
+ *   or the sentence role whose field, fills the parameter when nothing else
+ *   does.
+ */
+/**
+ * A service's standardized self-description (lives in `extras`).
+ * @typedef {object} ServiceExtras
+ * @property {number} [schemaVersion]
+ * @property {string[]} [tasks] Tasks this service serves, from the TASKS vocabulary.
+ * @property {string} [summary] Rich human description (Markdown), beyond the
+ *   short `description`.
+ * @property {ServiceParam[]} [parameters] Ordered parameter schema, rendered
+ *   into a form by the UI.
+ */
+/**
+ * What a service says about itself when it registers.
+ * @typedef {object} ServiceInfo
+ * @property {string} serviceId
+ * @property {string} serviceName
+ * @property {string} description
+ * @property {ServiceExtras & Record<string, any>} [extras]
+ */
+/**
+ * A service as `messages.discoverServices` lists it.
+ * @typedef {object} DiscoveredService
+ * @property {string} serviceId
+ * @property {string} serviceName
+ * @property {string} description
+ * @property {ServiceExtras & Record<string, any>} extras
+ * @property {boolean} online True while the service holds an open request
+ *   channel, false for a previously seen offline service.
+ * @property {string | null} [lastSeenAt] ISO-8601 stamp of when the service
+ *   was last seen alive, or null when never stored.
+ * @property {string} [runnerName] Online services only: the display name of
+ *   the account that runs the service.
+ * @property {boolean} [runByYou] Online services only: the caller runs it.
+ * @property {boolean} [servesYou] Online services only: it would take the
+ *   caller's requests on this project. A delegating service serves members
+ *   other than its runner only where the runner is a maintainer or an admin.
+ */
+/**
+ * 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: {
+    serviceId?: string;
+    extras?: {
+        tasks?: string[];
+    };
+}, task: string): boolean;
+/**
+ * The discovered services that serve `task`.
+ * @param {DiscoveredService[] | undefined} services result of client.messages.discoverServices()
+ * @param {string} task one of TASKS
+ * @returns {DiscoveredService[]}
+ */
+export function filterServicesByTask(services: DiscoveredService[] | undefined, task: string): DiscoveredService[];
+/**
+ * The parameter schema a service declares (ordered array), or [].
+ * @param {{extras?: {parameters?: ServiceParam[]}}} service
+ * @returns {ServiceParam[]}
+ */
+export function getParamSchema(service: {
+    extras?: {
+        parameters?: ServiceParam[];
+    };
+}): ServiceParam[];
+/**
+ * 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: {
+    description?: string;
+    extras?: {
+        summary?: string;
+    };
+}): string;
+/**
+ * Default values keyed by param key — the initial form state.
+ * @param {ServiceParam[]} schema getParamSchema(service)
+ * @returns {Record<string, any>} { [key]: defaultValue }
+ */
+export function buildDefaultValues(schema: ServiceParam[]): Record<string, any>;
+export function coerceParamValues(schema: any, raw: any): {
+    values: {};
+    errors: {};
+};
+/**
+ * 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 (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?, slider?,   // number (slider: drag, don't type)
+ *         placeholder?, multiline?,     // string
+ *         scope?, role? }               // 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. Its optional
+ * `role` names a lexicon role ("gloss") or, at Sentence scope, a sentence
+ * field's role ("translation", "literalTranslation", "note"): a UI that knows
+ * the project fills the parameter with the one field at `scope` whose stored
+ * Lexicon field holds that role, or whose stored role it is. A field is never
+ * chosen by its name.
+ *
+ * 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: Readonly<{
+    TOKENIZE: "tokenize";
+    PARSE: "parse";
+    TRANSCRIBE: "transcribe";
+    /** Create vocab links for unlinked tokens. */
+    LINK_VOCAB: "link-vocab";
+    /** Propose an interlinear analysis (morpheme segmentation + glosses) for words. */
+    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";
+}>;
+/**
+ * One choice for an `enum` or `multiselect` service parameter.
+ */
+export type ServiceParamOption = {
+    value: string;
+    label: string;
+};
+/**
+ * A single user-controllable argument a service advertises.
+ */
+export type ServiceParam = {
+    /**
+     * Key the value is sent under in the request payload.
+     */
+    key: string;
+    label: string;
+    type: "string" | "number" | "boolean" | "enum" | "multiselect" | "field";
+    description?: string;
+    default?: any;
+    required?: boolean;
+    /**
+     * Required for `enum` and `multiselect`.
+     */
+    options?: ServiceParamOption[];
+    /**
+     * `number` only.
+     */
+    min?: number;
+    /**
+     * `number` only.
+     */
+    max?: number;
+    /**
+     * `number` only.
+     */
+    step?: number;
+    /**
+     * `number` only: render as a slider to drag
+     * rather than a box to type in.
+     */
+    slider?: boolean;
+    /**
+     * `string` only.
+     */
+    placeholder?: string;
+    /**
+     * `string` only.
+     */
+    multiline?: boolean;
+    /**
+     * `field` only: the
+     * scope of the project's annotation fields the value names one of. A
+     * `field` value is a string everywhere else.
+     */
+    scope?: "Sentence" | "Word" | "Morpheme";
+    /**
+     * `field` only: the lexicon role whose paired field,
+     * or the sentence role whose field, fills the parameter when nothing else
+     * does.
+     */
+    role?: string;
+};
+/**
+ * A service's standardized self-description (lives in `extras`).
+ */
+export type ServiceExtras = {
+    schemaVersion?: number;
+    /**
+     * Tasks this service serves, from the TASKS vocabulary.
+     */
+    tasks?: string[];
+    /**
+     * Rich human description (Markdown), beyond the
+     * short `description`.
+     */
+    summary?: string;
+    /**
+     * Ordered parameter schema, rendered
+     * into a form by the UI.
+     */
+    parameters?: ServiceParam[];
+};
+/**
+ * What a service says about itself when it registers.
+ */
+export type ServiceInfo = {
+    serviceId: string;
+    serviceName: string;
+    description: string;
+    extras?: ServiceExtras & Record<string, any>;
+};
+/**
+ * A service as `messages.discoverServices` lists it.
+ */
+export type DiscoveredService = {
+    serviceId: string;
+    serviceName: string;
+    description: string;
+    extras: ServiceExtras & Record<string, any>;
+    /**
+     * True while the service holds an open request
+     * channel, false for a previously seen offline service.
+     */
+    online: boolean;
+    /**
+     * ISO-8601 stamp of when the service
+     * was last seen alive, or null when never stored.
+     */
+    lastSeenAt?: string | null;
+    /**
+     * Online services only: the display name of
+     * the account that runs the service.
+     */
+    runnerName?: string;
+    /**
+     * Online services only: the caller runs it.
+     */
+    runByYou?: boolean;
+    /**
+     * Online services only: it would take the
+     * caller's requests on this project. A delegating service serves members
+     * other than its runner only where the runner is a maintainer or an admin.
+     */
+    servesYou?: boolean;
+};