@yaklabs-ai/plugin-sdk 0.13.7 → 0.13.8

package/dist/system-one.d.ts

@@ -0,0 +1,321 @@
+/**
+ * The client a host with no System One binds: every call throws `not-served` without touching the
+ * network, so a caller's own `catch` runs exactly as it would for an unavailable model.
+ */
+export declare function createUnavailableSystemOneClient(): SystemOneClient;
+
+export declare type DecideAnswer = DecideBoolAnswer | DecideChoiceAnswer | DecideScoreAnswer;
+
+export declare type DecideAnswerFor<Q> = Q extends DecideBoolQuestion ? DecideBoolAnswer : Q extends DecideChoiceQuestion<infer L> ? DecideChoiceAnswer<L> : Q extends DecideScoreQuestion ? DecideScoreAnswer : never;
+
+export declare interface DecideBoolAnswer {
+    readonly type: "bool";
+    /** P(yes), from 0 to 1. */
+    readonly probability: number;
+}
+
+/** A yes/no question. `criteria` says what yes and what no mean; omit it to leave both open. */
+export declare interface DecideBoolQuestion {
+    readonly type: "bool";
+    readonly instructions: string;
+    readonly criteria?: {
+        readonly true: string;
+        readonly false: string;
+    };
+}
+
+export declare interface DecideChoiceAnswer<L extends string = string> {
+    readonly type: "choice";
+    readonly choice: L;
+    readonly confidence: number;
+    /** P(label) for every offered label. */
+    readonly probabilities: Readonly<Record<L, number>>;
+}
+
+/** A choice among labels. Each label maps to what it means; an empty string leaves it open. */
+export declare interface DecideChoiceQuestion<L extends string = string> {
+    readonly type: "choice";
+    readonly instructions: string;
+    readonly criteria: Readonly<Record<L, string>>;
+}
+
+export declare type DecideModelId = "jev" | "clef" | "clef-flash";
+
+export declare type DecideQuestion = DecideBoolQuestion | DecideChoiceQuestion | DecideScoreQuestion;
+
+/** Questions keyed by the name each answer comes back under. */
+export declare type DecideQuestions = Readonly<Record<string, DecideQuestion>>;
+
+export declare interface DecideRequest<Q extends DecideQuestions = DecideQuestions> {
+    /** Defaults to `jev`. */
+    readonly model?: DecideModelId;
+    readonly state: DecideState;
+    readonly questions: Q;
+}
+
+export declare interface DecideScoreAnswer {
+    readonly type: "score";
+    /** The expected level, from 0 to the number of levels minus one. */
+    readonly score: number;
+    readonly confidence: number;
+}
+
+/** A score over ordered levels: the first criterion scores 0, the next 1, and so on. */
+export declare interface DecideScoreQuestion {
+    readonly type: "score";
+    readonly instructions: string;
+    readonly criteria: readonly string[];
+}
+
+/**
+ * What a decide call reads. A JSON value is sent as JSON; every value must survive
+ * `JSON.stringify` unchanged.
+ */
+export declare type DecideState = string | object;
+
+/** Every asked question has an answer of its own kind. */
+export declare interface Decision<Q extends DecideQuestions = DecideQuestions> {
+    readonly model: DecideModelId;
+    readonly answers: {
+        readonly [K in keyof Q]: DecideAnswerFor<Q[K]>;
+    };
+    readonly usage?: SystemOneTokenUsage;
+}
+
+declare type DurationUnit = "seconds" | "minutes" | "hours" | "days" | "weeks" | "months" | "years";
+
+export declare interface EstimateDistribution<V> {
+    readonly value: V | null;
+    readonly mean?: V;
+    readonly median?: V;
+    readonly p10?: V;
+    readonly p90?: V;
+    /** P(value < min). */
+    readonly pBelow?: number;
+    /** P(value > max). */
+    readonly pAbove?: number;
+}
+
+export declare type ExtractAnswer = ExtractAnswerFor<ExtractField>;
+
+export declare type ExtractAnswerFor<F> = F extends ExtractTextField ? ExtractValueAnswer<"text", string> : F extends ExtractNumberField ? ExtractValueAnswer<"number", number> : F extends ExtractDateTimeField ? ExtractValueAnswer<F["type"], string> : F extends ExtractDurationField ? ExtractValueAnswer<"duration", number> : F extends ExtractListField ? ExtractListAnswer<F["items"] extends "number" ? number : string> : F extends ExtractEstimateField ? ExtractEstimateAnswer<F["min"] extends string ? string : number> : F extends ExtractForecastField ? ExtractForecastAnswer : never;
+
+/** `date` answers are ISO dates, `time` ISO times, `datetime` ISO date-times. */
+export declare interface ExtractDateTimeField extends ExtractFieldBase {
+    readonly type: "date" | "time" | "datetime";
+}
+
+export declare interface ExtractDurationField extends ExtractFieldBase {
+    readonly type: "duration";
+    /** Seconds when omitted. */
+    readonly unit?: DurationUnit;
+    readonly integer?: boolean;
+    readonly decimals?: number;
+}
+
+export declare interface ExtractEstimateAnswer<V = number | string> extends EstimateDistribution<V> {
+    readonly type: "estimate";
+}
+
+/** A distribution over one value. `min`/`max` are numbers, or ISO dates for a date estimate. */
+export declare interface ExtractEstimateField extends ExtractFieldBase {
+    readonly type: "estimate";
+    readonly min: number | string;
+    readonly max: number | string;
+    /** Grid step: a positive number (days for a date estimate), `month` or `year`. */
+    readonly step?: number | "month" | "year";
+    readonly scale?: "linear" | "log";
+    readonly unit?: string;
+}
+
+export declare type ExtractField = ExtractTextField | ExtractNumberField | ExtractDateTimeField | ExtractDurationField | ExtractListField | ExtractEstimateField | ExtractForecastField;
+
+declare interface ExtractFieldBase {
+    readonly instructions?: string;
+    /** P(null) above which the value is null. Clairic's default is 0.5. */
+    readonly nullThreshold?: number;
+}
+
+/** Fields keyed by name. A name matches `^[A-Za-z_][A-Za-z0-9_.\-]{0,63}$`. */
+export declare type ExtractFields = Readonly<Record<string, ExtractField>>;
+
+export declare interface ExtractForecastAnswer {
+    readonly type: "forecast";
+    /** One value per step; `null` when the state does not determine the forecast. */
+    readonly value: readonly number[] | null;
+    readonly steps: readonly EstimateDistribution<number>[];
+}
+
+/** One distribution per future step. */
+export declare interface ExtractForecastField extends ExtractFieldBase {
+    readonly type: "forecast";
+    readonly min: number;
+    readonly max: number;
+    /** Number of steps, 1 to 64. */
+    readonly horizon: number;
+    readonly interval?: ForecastInterval;
+    readonly scale?: "linear" | "log";
+    readonly unit?: string;
+}
+
+export declare interface Extraction<F extends ExtractFields = ExtractFields> {
+    readonly model: ExtractModelId;
+    readonly answers: {
+        readonly [K in keyof F]: ExtractAnswerFor<F[K]>;
+    };
+    /** The state was cut to fit the model's context. */
+    readonly truncated: boolean;
+    readonly usage?: SystemOneTokenUsage;
+}
+
+export declare interface ExtractListAnswer<V> {
+    readonly type: "list";
+    readonly value: readonly V[] | null;
+    readonly confidence?: number;
+    /** One per item in `value`. */
+    readonly confidences?: readonly number[];
+    readonly spans?: readonly TextSpan[];
+}
+
+export declare interface ExtractListField extends ExtractFieldBase {
+    readonly type: "list";
+    readonly items: "text" | "number" | "date";
+    readonly decimals?: number;
+}
+
+export declare type ExtractModelId = "clairic";
+
+export declare interface ExtractNumberField extends ExtractFieldBase {
+    readonly type: "number";
+    readonly unit?: string;
+    readonly integer?: boolean;
+    /** 0 to 6. */
+    readonly decimals?: number;
+}
+
+export declare interface ExtractRequest<F extends ExtractFields = ExtractFields> {
+    readonly model: ExtractModelId;
+    /** Text only; JSON is not accepted. */
+    readonly state: string;
+    readonly fields: F;
+    /** ISO date that anchors dates written without a year. */
+    readonly referenceDate?: string;
+}
+
+export declare interface ExtractTextField extends ExtractFieldBase {
+    readonly type: "text";
+}
+
+export declare interface ExtractValueAnswer<T extends "text" | "number" | "date" | "time" | "datetime" | "duration", V> {
+    readonly type: T;
+    /** `null` when the state does not determine the value. */
+    readonly value: V | null;
+    /** The best candidate even when `value` is null. */
+    readonly guess?: V;
+    readonly confidence?: number;
+    readonly pNull?: number;
+    readonly span?: TextSpan;
+    readonly unit?: string;
+}
+
+declare type ForecastInterval = "step" | "minute" | "hour" | "day" | "week" | "month" | "quarter" | "year";
+
+export declare function isSystemOneError(error: unknown): error is SystemOneError;
+
+export declare interface SystemOneAvailability {
+    readonly available: boolean;
+    readonly reason?: string;
+    readonly cause?: SystemOneFailureCause;
+}
+
+export declare interface SystemOneCallOptions {
+    readonly signal?: AbortSignal;
+    /** Bounds the whole call, retries included. */
+    readonly timeoutMs?: number;
+}
+
+export declare interface SystemOneClient {
+    decide<const Q extends DecideQuestions>(request: DecideRequest<Q>, options?: SystemOneCallOptions): Promise<Decision<Q>>;
+    extract<const F extends ExtractFields>(request: ExtractRequest<F>, options?: SystemOneCallOptions): Promise<Extraction<F>>;
+    /** Whether some provider in the current order can serve `(kind, model)`. Never rejects. */
+    availability(kind: SystemOneKind, model?: SystemOneModelId): Promise<SystemOneAvailability>;
+}
+
+/**
+ * The one error a System One call rejects with. Its message names the cause, model, and
+ * provider, never the vendor's body: bodies can echo the request's state, and this error
+ * reaches logs.
+ */
+export declare class SystemOneError extends Error {
+    readonly cause: SystemOneFailureCause;
+    readonly kind: SystemOneKind;
+    readonly model: string;
+    /** The provider that failed; absent when no provider was tried. */
+    readonly providerId: string | undefined;
+    constructor(init: {
+        readonly cause: SystemOneFailureCause;
+        readonly kind: SystemOneKind;
+        readonly model: string;
+        readonly providerId?: string | undefined;
+    });
+}
+
+/**
+ * Why a call failed or a provider can't serve, as a closed set. Never prose, and never the
+ * vendor's body: bodies can echo the request's state.
+ */
+export declare type SystemOneFailureCause = {
+    readonly kind: "no-credential";
+} | {
+    readonly kind: "credential-store";
+} | {
+    readonly kind: "not-served";
+} | {
+    readonly kind: "not-permitted";
+} | {
+    readonly kind: "unknown-model";
+} | {
+    readonly kind: "invalid-request";
+    readonly detail: string;
+} | {
+    readonly kind: "too-large";
+} | {
+    readonly kind: "http";
+    readonly status: number;
+} | {
+    readonly kind: "transport";
+} | {
+    readonly kind: "timeout";
+} | {
+    readonly kind: "aborted";
+} | {
+    readonly kind: "invalid-answer";
+};
+
+/**
+ * ---
+ * responsibility: The data shapes of the System One surface: models, the decide and extract
+ *   vocabularies, providers, and the failure causes.
+ * owns:
+ *   - The caller-facing question, field, answer, and result types, in Bonsai's own words
+ *     (`bool` for yes/no, camelCase options). The vendors' words (`noul`, snake_case) appear
+ *     only in `wire.ts`.
+ *   - {@link SystemOneProvider}, the seam a transport implements.
+ * does_not_own:
+ *   - Which models exist (`models.ts`), how answers are checked (`wire.ts`), or how a provider is
+ *     picked (`system-one-client.ts`).
+ * ---
+ */
+export declare type SystemOneKind = "decide" | "extract";
+
+export declare type SystemOneModelId = DecideModelId | ExtractModelId;
+
+export declare interface SystemOneTokenUsage {
+    readonly inputTokens: number;
+    readonly outputTokens: number;
+}
+
+/** `[start, end)` character offsets into the state. */
+export declare type TextSpan = readonly [number, number];
+
+export { }

package/dist/system-one.js

@@ -0,0 +1,69 @@
+// packages/system-one/dist/errors.js
+var SystemOneError = class extends Error {
+  cause;
+  kind;
+  model;
+  /** The provider that failed; absent when no provider was tried. */
+  providerId;
+  constructor(init) {
+    super(describe(init));
+    this.name = "SystemOneError";
+    this.cause = init.cause;
+    this.kind = init.kind;
+    this.model = init.model;
+    this.providerId = init.providerId;
+  }
+};
+function describe(init) {
+  const where = init.providerId === void 0 ? "" : ` on provider ${init.providerId}`;
+  const detail = init.cause.kind === "http" ? ` (HTTP ${init.cause.status})` : init.cause.kind === "invalid-request" ? ` (${init.cause.detail})` : "";
+  return `System One ${init.kind} on ${init.model}${where} failed: ${init.cause.kind}${detail}.`;
+}
+function isSystemOneError(error) {
+  return error instanceof SystemOneError;
+}
+
+// packages/system-one/dist/models.js
+var DEFAULT_DECIDE_MODEL = "jev";
+var SYSTEM_ONE_LIMITS = {
+  /** The serialized request body, in bytes. */
+  maxBodyBytes: 64 * 1024,
+  maxQuestions: 8,
+  maxFields: 32,
+  minChoiceOptions: 2,
+  maxChoiceOptions: 255,
+  minScoreLevels: 2,
+  maxScoreLevels: 10,
+  maxForecastHorizon: 64
+};
+
+// packages/system-one/dist/unavailable.js
+var NOT_SERVED = {
+  available: false,
+  reason: "This host has no System One models.",
+  cause: { kind: "not-served" }
+};
+function createUnavailableSystemOneClient() {
+  return {
+    decide(request) {
+      return Promise.reject(new SystemOneError({
+        kind: "decide",
+        model: request.model ?? DEFAULT_DECIDE_MODEL,
+        cause: { kind: "not-served" }
+      }));
+    },
+    extract(request) {
+      return Promise.reject(new SystemOneError({
+        kind: "extract",
+        model: request.model,
+        cause: { kind: "not-served" }
+      }));
+    },
+    availability: () => Promise.resolve(NOT_SERVED)
+  };
+}
+export {
+  SystemOneError,
+  createUnavailableSystemOneClient,
+  isSystemOneError
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yaklabs-ai/plugin-sdk",
-  "version": "0.13.7",
+  "version": "0.13.8",
   "description": "The Kay plugin SDK — types and helpers for authoring a Kay directory plugin.",
   "author": "YakLabs",
   "type": "module",
@@ -64,6 +64,10 @@
     "./vendored-mcp": {
       "types": "./dist/vendored-mcp.d.ts",
       "default": "./dist/vendored-mcp.js"
+    },
+    "./system-one": {
+      "types": "./dist/system-one.d.ts",
+      "default": "./dist/system-one.js"
     }
   },
   "files": [