@gobing-ai/ts-ai-runner 0.5.0 → 0.5.2

package/src/decision/types.ts

@@ -0,0 +1,111 @@
+/**
+ * Provider-neutral decision vocabulary — deliberately not re-exported from
+ * `@typesafe-ai/sdk`. Re-exporting the SDK's response types would bind every
+ * caller to the vendor; the neutral names here (`kind`, `labels`, `rubric`,
+ * `probability`) keep vendor mapping explicit and confined to the driver.
+ * This file imports nothing — no SDK, no workspace package (boundary rule).
+ */
+
+/** Any JSON-serializable value. */
+export type Json = string | number | boolean | null | Json[] | { [k: string]: Json };
+
+/** Caller-supplied decision context: free text, a structured object, or a list. */
+export type DecisionState = string | Json[] | { [k: string]: Json } | null;
+
+/** A description; `null` means "left undescribed" (e.g. a label needing no rationale). */
+export type Desc = string | Json[] | { [k: string]: Json } | null;
+
+/** Pick one label from a fixed set. Labels are the answer's type parameter. */
+export type ChoiceQuestion<L extends string> = { kind: 'choice'; prompt?: Desc; labels: Record<L, Desc> };
+
+/** Score against a rubric; at least two levels, enforced at compile time. */
+export type ScoreQuestion = { kind: 'score'; prompt?: Desc; rubric: readonly [Desc, Desc, ...Desc[]] };
+
+/** Binary yes/no judgment with optional per-outcome descriptions. */
+export type NoulQuestion = { kind: 'noul'; prompt?: Desc; yes?: Desc; no?: Desc };
+
+/** Any question the decision surface accepts. */
+export type Question = ChoiceQuestion<string> | ScoreQuestion | NoulQuestion;
+
+/** Selected label, calibration confidence, and a probability per label. */
+export type ChoiceAnswer<L extends string> = {
+    kind: 'choice';
+    label: L;
+    confidence: number;
+    probabilities: Record<L, number>;
+};
+
+/** Rubric score, confidence, per-level legend, and a probability per level. */
+export type ScoreAnswer = {
+    kind: 'score';
+    score: number;
+    confidence: number;
+    legend: Record<number, Desc>;
+    probabilities: Record<number, number>;
+};
+
+/**
+ * Bare yes-probability — no `confidence`, on purpose. The wire response
+ * returns only a probability; synthesizing a confidence would fabricate
+ * calibration data. The asymmetry is load-bearing: later code cannot paper
+ * over it.
+ */
+export type NoulAnswer = { kind: 'noul'; probability: number };
+
+/** Any answer the decision surface returns — discriminate on `kind`. */
+export type Answer = ChoiceAnswer<string> | ScoreAnswer | NoulAnswer;
+
+/** The answer type a question of shape `Q` decodes to. */
+export type AnswerFor<Q> =
+    Q extends ChoiceQuestion<infer L>
+        ? ChoiceAnswer<L>
+        : Q extends ScoreQuestion
+          ? ScoreAnswer
+          : Q extends NoulQuestion
+            ? NoulAnswer
+            : never;
+
+/** Conditional answer record for a keyed question map. */
+export type AnswersFor<Q extends Record<string, Question>> = { readonly [K in keyof Q]: AnswerFor<Q[K]> };
+
+/**
+ * Question builders for the batch path. Namespaced under `q` because
+ * `choice` / `score` / `noul` are already `DecisionMaker` method names.
+ */
+export const q = {
+    /**
+     * Build a choice question. `const` on the type parameter keeps an inline
+     * label map from widening to `string` — the caller keeps the union.
+     */
+    choice: <const L extends string>(prompt: Desc, labels: Record<L, Desc>): ChoiceQuestion<L> => ({
+        kind: 'choice',
+        prompt,
+        labels,
+    }),
+    /** Build a score question from a rubric of at least two levels. */
+    score: (prompt: Desc, rubric: readonly [Desc, Desc, ...Desc[]]): ScoreQuestion => ({
+        kind: 'score',
+        prompt,
+        rubric,
+    }),
+    /** Build a yes/no question; outcomes are optional and default undescribed. */
+    noul: (prompt?: Desc, outcomes?: { yes?: Desc; no?: Desc }): NoulQuestion => ({
+        kind: 'noul',
+        prompt,
+        ...outcomes,
+    }),
+};
+
+/**
+ * The one-method internal seam every backend driver implements. The loose
+ * `Record<string, Answer>` return is narrowed to `AnswersFor<Q>` by a single
+ * documented cast at the facade boundary — drivers stay trivial to write.
+ */
+export interface DecisionDriver {
+    readonly name: string;
+    ask(req: {
+        state: DecisionState;
+        questions: Record<string, Question>;
+        model?: string;
+    }): Promise<Record<string, Answer>>;
+}

package/src/decision/typesafe-driver.ts

@@ -0,0 +1,175 @@
+/**
+ * The TypeSafe backend driver — the only decision file that imports
+ * `@typesafe-ai/sdk` (0069 pin). Client wiring (R1/R2), neutral⇄SDK question
+ * and answer mapping (R4/R5), and the error translation table (R7) live here;
+ * everything above this file stays vendor-neutral.
+ */
+
+import type { Question as SdkQuestion, ResultFor as SdkResultFor, SystemOneResult } from '@typesafe-ai/sdk';
+import {
+    APIConnectionError,
+    APIError,
+    APITimeoutError,
+    AuthenticationError,
+    choice,
+    noul,
+    PermissionDeniedError,
+    RateLimitError,
+    score,
+    TypeSafeClient,
+    TypeSafeError,
+} from '@typesafe-ai/sdk';
+import {
+    DecisionAuthError,
+    DecisionBackendError,
+    DecisionConnectionError,
+    DecisionRateLimitError,
+    DecisionRequestError,
+    DecisionTimeoutError,
+} from './errors';
+import type { Answer, DecisionDriver, Question } from './types';
+import { validateAnswers, validateQuestions } from './validation';
+
+/** Configuration the facade resolves (key per R7) and forwards to the TypeSafe driver. */
+export interface TypesafeDriverConfig {
+    apiKey: string;
+    model?: string;
+    baseURL?: string;
+    timeoutMs?: number;
+    maxRetries?: number;
+    fetch?: typeof fetch;
+}
+
+/**
+ * Build the TypeSafe driver: exactly one `TypeSafeClient` per driver instance
+ * (R2), the API key always passed explicitly so the SDK's `TYPESAFE_API_KEY`
+ * self-resolution never runs (R1). All transport failures — at construction
+ * or at ask time — come back as `DecisionError`s, never SDK classes (R7).
+ */
+export function createTypesafeDriver(config: TypesafeDriverConfig): DecisionDriver {
+    let client: TypeSafeClient;
+    try {
+        client = new TypeSafeClient({
+            apiKey: config.apiKey,
+            // baseURL is forwarded as-is. SDK 0.6.0 exports no default
+            // base-URL constant (`ENV` holds env-var names only), so an
+            // omitted baseURL still lets the SDK self-resolve
+            // `TYPESAFE_BASE_URL` — documented residual for 0073.
+            baseURL: config.baseURL,
+            defaultModel: config.model,
+            timeout: config.timeoutMs,
+            retry: config.maxRetries === undefined ? undefined : { maxRetries: config.maxRetries },
+            fetch: config.fetch,
+        });
+    } catch (err) {
+        translateError(err);
+    }
+
+    return {
+        name: 'typesafe',
+        async ask({ state, questions, model }) {
+            validateQuestions(questions);
+            let result: SystemOneResult<Record<string, SdkQuestion>>;
+            try {
+                const sdkQuestions = Object.fromEntries(
+                    Object.entries(questions).map(([name, question]) => [name, toSdkQuestion(question)]),
+                );
+                result = await client.systemOne({ state, questions: sdkQuestions, model });
+            } catch (err) {
+                translateError(err);
+            }
+
+            // R6: the SDK echoes the request's question names, so the mapped
+            // record keeps the caller's keys in correspondence. R8: `model`
+            // and `usage` on the result are deliberately not surfaced.
+            if (!result?.answers || typeof result.answers !== 'object' || Array.isArray(result.answers)) {
+                throw new DecisionBackendError('Invalid decision response: expected answers map', undefined);
+            }
+            const answers = Object.fromEntries(
+                Object.entries(result.answers).map(([name, answer]) => [name, fromSdkAnswer(answer)]),
+            );
+            validateAnswers(questions, answers);
+            return answers;
+        },
+    };
+}
+
+/** Neutral question → SDK wire question (R4). `null` is "undescribed" on the wire. */
+function toSdkQuestion(question: Question): SdkQuestion {
+    switch (question.kind) {
+        case 'choice':
+            return choice(question.prompt ?? null, question.labels);
+        case 'score':
+            return score(question.prompt ?? null, question.rubric);
+        case 'noul': {
+            const outcomes =
+                question.yes === undefined && question.no === undefined
+                    ? undefined
+                    : { true: question.yes, false: question.no };
+            return noul(question.prompt ?? null, outcomes);
+        }
+    }
+}
+
+/** SDK wire response → neutral answer (R5). Noul gets no confidence — the wire has none and none is invented. */
+function fromSdkAnswer(answer: SdkResultFor<SdkQuestion>): Answer {
+    if (!answer || typeof answer !== 'object')
+        throw new DecisionBackendError('Invalid decision response: expected answer object', undefined);
+    switch (answer.type) {
+        case 'choice':
+            return {
+                kind: 'choice',
+                label: answer.choice,
+                confidence: answer.confidence,
+                probabilities: answer.probabilities,
+            };
+        case 'score':
+            return {
+                kind: 'score',
+                score: answer.score,
+                confidence: answer.confidence,
+                legend: answer.legend,
+                probabilities: answer.probabilities,
+            };
+        case 'noul':
+            return { kind: 'noul', probability: answer.noul };
+        default:
+            throw new DecisionBackendError('Invalid decision response: unknown answer kind', undefined);
+    }
+}
+
+/**
+ * R7, per the design doc's error table. Ordered subclass-before-base:
+ * `APITimeoutError` extends `APIConnectionError`, and the HTTP subclasses
+ * extend `APIError`. Rows the table does not name fall to the nearest home:
+ * 4xx (`NotFoundError` included) is a `DecisionRequestError`, and any local
+ * `TypeSafeError` (empty questions, invalid client config) lands there too
+ * with `status: undefined` — so no SDK class ever escapes. Foreign errors are
+ * rethrown untouched; they are not this package's to translate.
+ */
+function translateError(err: unknown): never {
+    const message = err instanceof Error ? err.message : String(err);
+    if (err instanceof RateLimitError) {
+        throw new DecisionRateLimitError(message, err.status, err.retryAfterMs, { cause: err });
+    }
+    if (err instanceof AuthenticationError || err instanceof PermissionDeniedError) {
+        throw new DecisionAuthError(message, err.status, { cause: err });
+    }
+    if (err instanceof APITimeoutError) {
+        throw new DecisionTimeoutError(message, err.timeoutMs, { cause: err });
+    }
+    if (err instanceof APIConnectionError) {
+        throw new DecisionConnectionError(message, { cause: err });
+    }
+    if (err instanceof APIError) {
+        if (err.status < 500) {
+            const raw = typeof err.body === 'string' ? err.body : (JSON.stringify(err.body) ?? '');
+            throw new DecisionRequestError(message, err.status, raw.slice(0, 200) || undefined, { cause: err });
+        }
+        throw new DecisionBackendError(message, err.status, { cause: err });
+    }
+    if (err instanceof TypeSafeError) {
+        throw new DecisionRequestError(message, undefined, message, { cause: err });
+    }
+    throw err;
+}

package/src/decision/validation.ts

@@ -0,0 +1,100 @@
+import { DecisionBackendError, DecisionRequestError } from './errors';
+import type { Question } from './types';
+
+function record(value: unknown): value is Record<string, unknown> {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function json(value: unknown, ancestors = new Set<unknown>()): boolean {
+    if (value === null || typeof value === 'string' || typeof value === 'boolean') return true;
+    if (typeof value === 'number') return Number.isFinite(value);
+    if (typeof value !== 'object' || ancestors.has(value)) return false;
+    ancestors.add(value);
+    const valid = Object.values(value).every((entry) => json(entry, ancestors));
+    ancestors.delete(value);
+    return valid;
+}
+
+function desc(value: unknown): boolean {
+    return (value === null || typeof value === 'string' || typeof value === 'object') && json(value);
+}
+
+/** Validate caller data before either a custom driver or the SDK consumes it. */
+export function validateQuestions(questions: unknown): asserts questions is Record<string, Question> {
+    const fail: (name: string) => never = (name) => {
+        throw new DecisionRequestError(`Invalid decision question: ${name}`, undefined, undefined);
+    };
+    if (!record(questions) || Object.keys(questions).length === 0) fail('expected a nonempty question map');
+    for (const [name, question] of Object.entries(questions)) {
+        if (!record(question)) fail(name);
+        if (question.prompt !== undefined && !desc(question.prompt)) fail(name);
+        switch (question.kind) {
+            case 'choice':
+                if (
+                    !record(question.labels) ||
+                    Object.keys(question.labels).length === 0 ||
+                    !Object.values(question.labels).every(desc)
+                )
+                    fail(name);
+                break;
+            case 'score':
+                if (
+                    !Array.isArray(question.rubric) ||
+                    question.rubric.length < 2 ||
+                    !Array.from(question.rubric).every(desc)
+                )
+                    fail(name);
+                break;
+            case 'noul':
+                if (
+                    (question.yes !== undefined && !desc(question.yes)) ||
+                    (question.no !== undefined && !desc(question.no))
+                )
+                    fail(name);
+                break;
+            default:
+                fail(name);
+        }
+    }
+}
+
+function bounded(value: unknown, max = 1): boolean {
+    return typeof value === 'number' && Number.isFinite(value) && value >= 0 && value <= max;
+}
+
+function keysMatch(value: unknown, keys: string[]): value is Record<string, unknown> {
+    return record(value) && Object.keys(value).length === keys.length && keys.every((key) => Object.hasOwn(value, key));
+}
+
+/** Verify the correspondence that permits the facade's typed answer narrowing. */
+export function validateAnswers(questions: Record<string, Question>, answers: unknown): void {
+    const fail: (name: string) => never = (name) => {
+        throw new DecisionBackendError(`Invalid decision response: ${name}`, undefined);
+    };
+    if (!keysMatch(answers, Object.keys(questions))) fail('answer names do not match questions');
+    for (const [name, question] of Object.entries(questions)) {
+        const answer = answers[name];
+        if (!record(answer) || answer.kind !== question.kind) fail(name);
+        if (question.kind === 'noul') {
+            if (!bounded(answer.probability)) fail(name);
+            continue;
+        }
+        const keys =
+            question.kind === 'choice' ? Object.keys(question.labels) : Array.from(question.rubric.keys(), String);
+        if (
+            !bounded(answer.confidence) ||
+            !keysMatch(answer.probabilities, keys) ||
+            !Object.values(answer.probabilities).every((p) => bounded(p))
+        )
+            fail(name);
+        if (question.kind === 'choice') {
+            if (typeof answer.label !== 'string' || !Object.hasOwn(question.labels, answer.label)) fail(name);
+        } else if (
+            !bounded(answer.score, question.rubric.length - 1) ||
+            !keysMatch(answer.legend, keys) ||
+            !Object.values(answer.legend).every(desc)
+        ) {
+            fail(name);
+        }
+    }
+}

package/src/index.ts

@@ -3,6 +3,9 @@ export * from './agent-spec';
 export * from './agents/auth-shims';
 export * from './agents/shims';
 export * from './ai-runner';
+export * from './decision/decision-maker';
+export * from './decision/errors';
+export * from './decision/types';
 export * from './doctor-runner';
 export * from './events';
 export * from './identity';