@gobing-ai/ts-decision-fm 0.5.3

package/src/estimate.ts

@@ -0,0 +1,97 @@
+/**
+ * Probability estimation from repeated samples (task 0084 R6, ADR-030,
+ * design § Probability estimation). Every probability is an empirical sample
+ * frequency — never a self-reported confidence — so the resolution limit is
+ * 1/k and `confidence` measures how much the k samples agreed, not calibration.
+ */
+import type { ChoiceAnswer, Desc, NoulAnswer, ScoreAnswer } from '@gobing-ai/ts-ai-runner';
+/**
+ * Laya reference `confidence_from_probs` on the empirical distribution:
+ * `1 − H(p) / ln(n)` over the n declared options. One-hot ⇒ 1, uniform ⇒ 0.
+ */
+export function entropyConfidence(probabilities: number[]): number {
+    const n = probabilities.length;
+    if (n <= 1) return 1;
+    let entropy = 0;
+    for (const p of probabilities) {
+        if (p > 0) entropy -= p * Math.log(p);
+    }
+    return 1 - entropy / Math.log(n);
+}
+
+/**
+ * Choice frequencies over every supplied label (unsampled ⇒ 0). The answer
+ * label is the most frequent with ties broken by label declaration order.
+ */
+export function estimateChoice(labels: readonly string[], samples: readonly string[]): ChoiceAnswer<string> {
+    const counts = new Map<string, number>(labels.map((label) => [label, 0]));
+    for (const sample of samples) counts.set(sample, (counts.get(sample) ?? 0) + 1);
+    const k = samples.length;
+    const probabilities: Record<string, number> = {};
+    const distribution: number[] = [];
+    let bestLabel = labels[0] ?? '';
+    let bestCount = -1;
+    for (const label of labels) {
+        const count = counts.get(label) ?? 0;
+        const probability = count / k;
+        distribution.push(probability);
+        probabilities[label] = probability;
+        // Declaration order wins ties: strict `>` keeps the earlier label.
+        if (count > bestCount) {
+            bestCount = count;
+            bestLabel = label;
+        }
+    }
+    return {
+        kind: 'choice',
+        label: bestLabel,
+        confidence: entropyConfidence(distribution),
+        probabilities,
+    };
+}
+
+/**
+ * Score frequencies over the level indices `0…n-1`. The answer score is the
+ * most frequent level with ties going to the lower level; the legend maps each
+ * index back to its rubric description.
+ */
+export function estimateScore(rubric: readonly Desc[], samples: readonly string[]): ScoreAnswer {
+    const k = samples.length;
+    const counts: number[] = [];
+    for (const sample of samples) {
+        const level = Number.parseInt(sample, 10);
+        counts[level] = (counts[level] ?? 0) + 1;
+    }
+    const probabilities: Record<number, number> = {};
+    const distribution: number[] = [];
+    let bestLevel = 0;
+    let bestCount = -1;
+    for (let level = 0; level < rubric.length; level++) {
+        const count = counts[level] ?? 0;
+        const probability = count / k;
+        distribution.push(probability);
+        probabilities[level] = probability;
+        // Lower level wins ties: strict `>` keeps the smaller index.
+        if (count > bestCount) {
+            bestCount = count;
+            bestLevel = level;
+        }
+    }
+    const legend: Record<number, Desc> = {};
+    rubric.forEach((desc, level) => {
+        legend[level] = desc;
+    });
+    return {
+        kind: 'score',
+        score: bestLevel,
+        confidence: entropyConfidence(distribution),
+        legend,
+        probabilities,
+    };
+}
+
+/** Noul is a bare yes-probability — no `confidence` key, by contract. */
+export function estimateNoul(samples: readonly string[]): NoulAnswer {
+    const yes = samples.filter((sample) => sample === 'yes').length;
+    return { kind: 'noul', probability: yes / samples.length };
+}

package/src/fm-process.ts

@@ -0,0 +1,187 @@
+/**
+ * The one-shot `fm` process bridge (task 0084 R4, R5, R7, R8; design § Errors).
+ * Argv builders plus run/error mapping. Spawned exclusively through the
+ * injected ts-runtime {@link ProcessExecutor} — never `node:child_process`.
+ * Prompt and instructions travel as positional arguments because
+ * `ProcessExecutor.run` has no stdin input; fm's argv limit is far above the
+ * token budget, and the pre-flight `count-tokens` check keeps it bounded.
+ */
+
+import {
+    DecisionBackendError,
+    DecisionConfigError,
+    DecisionRequestError,
+    DecisionTimeoutError,
+} from '@gobing-ai/ts-ai-runner';
+import type { ProcessExecutor, ProcessResult } from '@gobing-ai/ts-runtime';
+
+/** `--guardrails` levels accepted by `fm respond` (design: fm CLI facts). */
+export type FmGuardrails = 'default' | 'permissive-content-transformations';
+
+/** Subcommand + flag order verified against the design's live observations. */
+export function countTokensArgv(instructions: string, prompt: string): string[] {
+    return ['count-tokens', '-q', '-i', instructions, prompt];
+}
+
+/** Builds the `fm respond` argv: schema flag, `-i` instructions, positional prompt, optional `-g`/`--guardrails`. */
+export function respondArgv(options: {
+    schemaPath: string;
+    instructions: string;
+    prompt: string;
+    /** Deterministic mode: single greedy sample. */
+    greedy?: boolean;
+    /** Omitted ⇒ the flag is omitted (fm's `default`). */
+    guardrails?: FmGuardrails;
+}): string[] {
+    return [
+        'respond',
+        '--no-stream',
+        '--schema',
+        options.schemaPath,
+        '-i',
+        options.instructions,
+        ...(options.guardrails !== undefined ? ['--guardrails', options.guardrails] : []),
+        ...(options.greedy ? ['-g'] : []),
+        options.prompt,
+    ];
+}
+
+/** Bare `fm available` always exits 0 — only `--model system` is a real probe. */
+export function availableArgv(): string[] {
+    return ['available', '--model', 'system'];
+}
+
+/** The executor reports a failed spawn (ENOENT, …) as an `error` outcome. */
+function isSpawnFailure(result: ProcessResult): boolean {
+    return result.outcome === 'error' && result.exitCode === null;
+}
+
+/** fm's own text, preferring stderr, for carrying into error messages. */
+function fmText(result: ProcessResult): string {
+    const text = (result.stderr.trim().length > 0 ? result.stderr : result.stdout).trim();
+    return text.length > 0 ? text : '(no output)';
+}
+
+/**
+ * R8 prerequisite probe: `fm available --model system`. A spawn failure maps to
+ * `DecisionConfigError` "fm not found"; a non-zero exit carries fm's printed
+ * reason (e.g. `modelNotReady`). An exit 0 caches availability in the driver.
+ */
+export async function probeFmAvailability(executor: ProcessExecutor, fmPath: string): Promise<void> {
+    const result = await executor.run({ command: fmPath, args: availableArgv() });
+    if (isSpawnFailure(result)) {
+        throw new DecisionConfigError(`fm not found: '${fmPath}' could not be spawned`, 'fmPath');
+    }
+    if (result.exitCode !== 0) {
+        throw new DecisionConfigError(`fm system model unavailable: ${fmText(result)}`, 'fm-system-model');
+    }
+}
+
+/**
+ * R4 pre-flight: `fm count-tokens -q -i <instructions> <prompt>` prints a bare
+ * integer. Non-zero exit or unparseable output is a `DecisionBackendError` —
+ * the budget comparison itself happens in the driver.
+ */
+export async function countPromptTokens(
+    executor: ProcessExecutor,
+    fmPath: string,
+    instructions: string,
+    prompt: string,
+): Promise<number> {
+    const result = await executor.run({ command: fmPath, args: countTokensArgv(instructions, prompt) });
+    if (isSpawnFailure(result)) {
+        throw new DecisionConfigError(`fm not found: '${fmPath}' could not be spawned`, 'fmPath');
+    }
+    if (result.exitCode !== 0) {
+        throw new DecisionBackendError(
+            `fm count-tokens failed (exit ${result.exitCode}): ${fmText(result)}`,
+            undefined,
+        );
+    }
+    const tokens = Number.parseInt(result.stdout.trim(), 10);
+    if (!Number.isFinite(tokens)) {
+        throw new DecisionBackendError(
+            `fm count-tokens did not print a token count: ${result.stdout.trim() || '(empty)'}`,
+            undefined,
+        );
+    }
+    return tokens;
+}
+
+/** Stable substrings of fm's failure text (design § Errors discrimination). */
+const CONTEXT_SIZE_MARKER = "exceeded the model's context size";
+const GUARDRAILS_MARKER = 'safety guardrails were triggered';
+
+/**
+ * One `fm respond` sample: run with the per-sample timeout, map every failure
+ * row of the error table, return stdout on success (parsing happens in
+ * {@link parseFmRespond}).
+ */
+export async function runFmRespond(
+    executor: ProcessExecutor,
+    fmPath: string,
+    args: string[],
+    requestTimeoutMs: number,
+): Promise<string> {
+    const result = await executor.run({ command: fmPath, args, timeout: requestTimeoutMs });
+    if (result.outcome === 'timeout') {
+        throw new DecisionTimeoutError(
+            `fm respond exceeded requestTimeoutMs (${requestTimeoutMs}): ${fmPath} ${args.join(' ')}`,
+            requestTimeoutMs,
+        );
+    }
+    if (isSpawnFailure(result)) {
+        throw new DecisionConfigError(`fm not found: '${fmPath}' could not be spawned`, 'fmPath');
+    }
+    if (result.exitCode !== 0) {
+        const text = fmText(result);
+        if (text.includes(CONTEXT_SIZE_MARKER)) {
+            throw new DecisionRequestError(`fm prompt exceeded the model context size: ${text}`, undefined, undefined);
+        }
+        if (text.includes(GUARDRAILS_MARKER)) {
+            // Typed failure, never an answer, and the ask is not retried.
+            throw new DecisionBackendError(`fm safety guardrails were triggered: ${text}`, undefined);
+        }
+        throw new DecisionBackendError(`fm respond failed (exit ${result.exitCode}): ${text}`, undefined);
+    }
+    return result.stdout;
+}
+
+/**
+ * Parse one sample's stdout as the schema-conformant JSON object. fm prints one
+ * JSON object per call, but the key order varies — callers read by key, never
+ * by position. Non-JSON or non-object output is a `DecisionBackendError`.
+ */
+export function parseFmRespond(stdout: string): Record<string, string> {
+    let parsed: unknown;
+    try {
+        parsed = JSON.parse(stdout);
+    } catch (cause) {
+        throw new DecisionBackendError(`fm respond printed non-JSON output: ${stdout.trim() || '(empty)'}`, undefined, {
+            cause,
+        });
+    }
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new DecisionBackendError(`fm respond printed non-object JSON: ${stdout.trim()}`, undefined);
+    }
+    const record: Record<string, string> = {};
+    for (const [key, value] of Object.entries(parsed)) {
+        if (typeof value !== 'string') {
+            throw new DecisionBackendError(`fm respond printed a non-string value for '${key}'`, undefined);
+        }
+        record[key] = value;
+    }
+    return record;
+}
+
+/** A parsed value outside the declared enum is a schema violation, never an answer (R7). */
+export function requireEnumValue(parsed: Record<string, string>, key: string, allowed: readonly string[]): string {
+    const value = parsed[key];
+    if (value === undefined || !allowed.includes(value)) {
+        throw new DecisionBackendError(
+            `fm sample for '${key}' violates the schema enum: ${value === undefined ? '(missing)' : `'${value}'`}`,
+            undefined,
+        );
+    }
+    return value;
+}

package/src/index.ts

@@ -0,0 +1,21 @@
+/**
+ * @gobing-ai/ts-decision-fm — Apple on-device Foundation Model decision backend
+ * driving the macOS `fm` CLI over a one-shot process bridge (ADR-029).
+ * Implements the {@link DecisionDriver} interface for `@gobing-ai/ts-ai-runner`;
+ * probabilities are empirical sample frequencies (ADR-030).
+ */
+
+export { createFmDriver, type FmDecisionDriver, type FmDriverOptions } from './driver';
+export { entropyConfidence, estimateChoice, estimateNoul, estimateScore } from './estimate';
+export {
+    availableArgv,
+    countPromptTokens,
+    countTokensArgv,
+    type FmGuardrails,
+    parseFmRespond,
+    probeFmAvailability,
+    requireEnumValue,
+    respondArgv,
+    runFmRespond,
+} from './fm-process';
+export { buildFmSchema, buildPrompt, declaredOptions, FM_INSTRUCTIONS, type FmSchema, formatDesc } from './schema';

package/src/schema.ts

@@ -0,0 +1,120 @@
+/**
+ * fm request construction (task 0084 R3, design § Request construction):
+ * the JSON schema passed to `fm respond --schema` and the instruction/prompt
+ * texts passed via `-i` and as the final positional argument.
+ *
+ * The schema always carries `x-order` — a hand-written object schema without it
+ * is rejected by `fm` ("The data couldn't be read because it is missing").
+ * Score levels are string enums so every question uses the same constrained
+ * string path; the driver converts them back to numbers.
+ */
+
+import type { DecisionState, Desc, Question } from '@gobing-ai/ts-ai-runner';
+
+/**
+ * Fixed `-i` instructions. It never asks for confidence, certainty or a
+ * probability — self-reported confidence would be fabricated calibration,
+ * which the decision contract forbids (ADR-030).
+ */
+export const FM_INSTRUCTIONS =
+    'You are a decision engine. Answer every question below using only the supplied state. ' +
+    'For each question choose exactly one of the listed options. ' +
+    'Reply with the JSON object the schema requires.';
+
+/** The JSON schema object handed to `fm respond --schema` (R3). */
+export interface FmSchema {
+    type: 'object';
+    title: string;
+    'x-order': string[];
+    required: string[];
+    additionalProperties: false;
+    properties: Record<string, { type: 'string'; enum: string[] }>;
+}
+
+/** Build the fm schema over the whole question map: one call answers every key. */
+export function buildFmSchema(questions: Record<string, Question>): FmSchema {
+    const properties: Record<string, { type: 'string'; enum: string[] }> = {};
+    for (const [key, question] of Object.entries(questions)) {
+        switch (question.kind) {
+            case 'choice':
+                properties[key] = { type: 'string', enum: Object.keys(question.labels) };
+                break;
+            case 'score':
+                properties[key] = { type: 'string', enum: question.rubric.map((_, level) => String(level)) };
+                break;
+            case 'noul':
+                properties[key] = { type: 'string', enum: ['yes', 'no'] };
+                break;
+        }
+    }
+    const keys = Object.keys(questions);
+    return {
+        type: 'object',
+        title: 'Decision',
+        'x-order': keys,
+        required: keys,
+        additionalProperties: false,
+        properties,
+    };
+}
+
+/** Format a {@link Desc} into prompt text: strings verbatim, structured values JSON, absence empty. */
+export function formatDesc(desc: Desc | undefined): string {
+    if (typeof desc === 'string') return desc;
+    if (desc === null || desc === undefined) return '';
+    return JSON.stringify(desc);
+}
+
+/** The declared option values of a question, in declaration order (estimation + validation share this). */
+export function declaredOptions(question: Question): string[] {
+    switch (question.kind) {
+        case 'choice':
+            return Object.keys(question.labels);
+        case 'score':
+            return question.rubric.map((_, level) => String(level));
+        case 'noul':
+            return ['yes', 'no'];
+    }
+}
+
+/**
+ * Render the positional prompt: the state as text (JSON when structured), then
+ * one block per question key with the prompt `Desc` and its options with
+ * descriptions — choice label keys, score level indices with the rubric text,
+ * noul `yes`/`no` with any outcome descriptions.
+ */
+export function buildPrompt(state: DecisionState, questions: Record<string, Question>): string {
+    const parts: string[] = [];
+    const stateText =
+        typeof state === 'string' ? state : state === null || state === undefined ? '' : JSON.stringify(state);
+    if (stateText.length > 0) parts.push(stateText);
+    for (const [key, question] of Object.entries(questions)) {
+        const lines: string[] = [];
+        const prompt = formatDesc(question.prompt);
+        lines.push(`Question "${key}":${prompt.length > 0 ? ` ${prompt}` : ''}`);
+        lines.push('Options:');
+        switch (question.kind) {
+            case 'choice':
+                for (const [label, desc] of Object.entries(question.labels)) {
+                    const d = formatDesc(desc);
+                    lines.push(d.length > 0 ? `- ${label}: ${d}` : `- ${label}`);
+                }
+                break;
+            case 'score':
+                question.rubric.forEach((desc, level) => {
+                    const d = formatDesc(desc);
+                    lines.push(d.length > 0 ? `- ${level}: ${d}` : `- ${level}`);
+                });
+                break;
+            case 'noul': {
+                for (const outcome of ['yes', 'no'] as const) {
+                    const d = formatDesc(question[outcome]);
+                    lines.push(d.length > 0 ? `- ${outcome}: ${d}` : `- ${outcome}`);
+                }
+                break;
+            }
+        }
+        parts.push(lines.join('\n'));
+    }
+    return parts.join('\n\n');
+}