@corbits/system-one 0.3.1 → 0.4.0

package/dist/config.js

@@ -61,6 +61,8 @@ export const DEFAULT_TIMEOUT_MS = 1500;
  * distinguishes caller-routed traffic from the official endpoint —
  * `'gateway'` is reserved for the proxy quirks path. The model always
  * resolves here: a `custom` target without one sends `typesafe-ai/jev`.
+ * `auth` is `"none"` only when the caller set `auth: "none"` on a custom
+ * endpoint; every other target still requires a key.
  */
 export function resolveEndpoint(endpoint) {
     if (endpoint?.kind === "custom") {
@@ -71,6 +73,7 @@ export function resolveEndpoint(endpoint) {
             url: endpoint.url,
             backend: "custom",
             model: endpoint.model ?? GATEWAY_QUIRKS.model,
+            auth: endpoint.auth === "none" ? "none" : "key",
         };
     }
     const kind = endpoint?.kind ?? "official";
@@ -83,5 +86,6 @@ export function resolveEndpoint(endpoint) {
         url,
         backend: kind === "gateway" ? "gateway" : "corbits-system-one",
         model: endpoint?.model ?? quirks.model,
+        auth: "key",
     };
 }

package/dist/decisions.d.ts

@@ -0,0 +1,99 @@
+import { Image } from "./assets.js";
+import type { EvaluateDeps } from "./client.js";
+import { type EvaluateOptions } from "./evaluate.js";
+import { type DecisionQuestion, type Description, type EvaluateConfig, type FallbackResult } from "./schemas.js";
+type ChoiceCriteria = Record<string, Description | null>;
+type NoulCriteria = {
+    true?: Description;
+    false?: Description;
+};
+export declare function choice<const Criteria extends ChoiceCriteria>(instructions: unknown, criteria: Criteria): {
+    type: "choice";
+    instructions: unknown;
+    criteria: Criteria;
+};
+export declare function noul(instructions: unknown, criteria?: NoulCriteria): {
+    type: "noul";
+    instructions: unknown;
+    criteria?: NoulCriteria;
+};
+export declare function score<const Criteria extends readonly Description[]>(instructions: unknown, criteria: Criteria): {
+    type: "score";
+    instructions: unknown;
+    criteria: Criteria;
+};
+/**
+ * Locate what `instructions` describe. The answer's `box` edges are fractions
+ * of the image. Box questions need the `jev-preview` model; pass it as
+ * `model` (or on the endpoint). This client does not reject other models.
+ */
+export declare function box(instructions: unknown): {
+    type: "box";
+    instructions: unknown;
+};
+type ChoiceAnswer<Criteria extends ChoiceCriteria> = {
+    type: "choice";
+    choice: keyof Criteria & string;
+    probabilities: Record<keyof Criteria & string, number>;
+    confidence: number;
+};
+type NoulAnswer = {
+    type: "noul";
+    noul: number;
+};
+type ScoreAnswer = {
+    type: "score";
+    score: number;
+    legend: Record<string, string>;
+    probabilities: Record<string, number>;
+    confidence: number;
+};
+type BoxAnswer = {
+    type: "box";
+    box: {
+        top: number;
+        bottom: number;
+        left: number;
+        right: number;
+    };
+    confidence: number | null;
+};
+type AnswerOf<QuestionSpec> = QuestionSpec extends {
+    type: "choice";
+    criteria: infer Criteria extends ChoiceCriteria;
+} ? ChoiceAnswer<Criteria> : QuestionSpec extends {
+    type: "noul";
+} ? NoulAnswer : QuestionSpec extends {
+    type: "score";
+} ? ScoreAnswer : QuestionSpec extends {
+    type: "box";
+} ? BoxAnswer : never;
+export type SystemOneAnswers<Questions extends Record<string, unknown>> = {
+    [Key in keyof Questions]: AnswerOf<Questions[Key]>;
+};
+export type SystemOneSuccess<Questions extends Record<string, unknown>> = {
+    fallback: false;
+    answers: SystemOneAnswers<Questions>;
+    modelId: string;
+    backend: "corbits-system-one" | "gateway" | "custom";
+    latencyMs: number;
+    usage?: {
+        inputTokens: number;
+        outputTokens: number;
+    };
+};
+export type SystemOneResult<Questions extends Record<string, unknown>> = SystemOneSuccess<Questions> | FallbackResult;
+export type SystemOneInput<Questions extends Record<string, DecisionQuestion>> = {
+    state: unknown;
+    questions: Questions;
+    assets?: Record<string, Image>;
+    model?: string;
+    config?: EvaluateConfig;
+};
+/**
+ * Keyed decisions call. `choice`, `noul`, `score`, and `box` compile to the
+ * question list `evaluate` already sends. Transport failures return
+ * `fallback` and `reason` and do not throw.
+ */
+export declare function systemOne<const Questions extends Record<string, DecisionQuestion>>(input: SystemOneInput<Questions>, options?: Pick<EvaluateOptions, "deps" | "onTelemetry">): Promise<SystemOneResult<Questions>>;
+export type { EvaluateDeps };

package/dist/decisions.js

@@ -0,0 +1,166 @@
+import { type } from "arktype";
+import { contentTypeOf, Image, serializeRequest } from "./assets.js";
+import { evaluate } from "./evaluate.js";
+import { SystemOneError } from "./errors.js";
+import { DecisionQuestionRecord, QuestionList, } from "./schemas.js";
+export function choice(instructions, criteria) {
+    if (Array.isArray(criteria)) {
+        throw new SystemOneError("parse-error", "Choice criteria must be a map of labels to descriptions, not a list.");
+    }
+    return { type: "choice", instructions, criteria };
+}
+export function noul(instructions, criteria) {
+    const question = { type: "noul", instructions };
+    if (criteria !== undefined)
+        question.criteria = criteria;
+    return question;
+}
+export function score(instructions, criteria) {
+    if (!Array.isArray(criteria)) {
+        throw new SystemOneError("parse-error", "Score criteria must be a list of descriptions indexed by score from zero, not a map.");
+    }
+    return { type: "score", instructions, criteria };
+}
+/**
+ * Locate what `instructions` describe. The answer's `box` edges are fractions
+ * of the image. Box questions need the `jev-preview` model; pass it as
+ * `model` (or on the endpoint). This client does not reject other models.
+ */
+export function box(instructions) {
+    return { type: "box", instructions };
+}
+function withModel(config, model) {
+    const next = {};
+    if (config?.apiKey !== undefined)
+        next.apiKey = config.apiKey;
+    if (config?.timeoutMs !== undefined)
+        next.timeoutMs = config.timeoutMs;
+    const endpoint = config?.endpoint;
+    if (model !== undefined) {
+        next.endpoint = { ...(endpoint ?? { kind: "official" }), model };
+    }
+    else if (endpoint !== undefined) {
+        next.endpoint = endpoint;
+    }
+    return next;
+}
+function answersFrom(decisions) {
+    const answers = {};
+    for (const decision of decisions) {
+        if (decision.type === "choice") {
+            answers[decision.id] = {
+                type: "choice",
+                choice: decision.choice,
+                probabilities: decision.probabilities,
+                confidence: decision.confidence,
+            };
+        }
+        else if (decision.type === "noul") {
+            answers[decision.id] = { type: "noul", noul: decision.noul };
+        }
+        else if (decision.type === "score") {
+            answers[decision.id] = {
+                type: "score",
+                score: decision.score,
+                legend: decision.legend,
+                probabilities: decision.probabilities,
+                confidence: decision.confidence,
+            };
+        }
+        else {
+            answers[decision.id] = {
+                type: "box",
+                box: decision.box,
+                confidence: decision.confidence,
+            };
+        }
+    }
+    return answers;
+}
+async function loadImages(assets) {
+    const parts = [];
+    const wire = {};
+    let index = 0;
+    for (const [alias, asset] of Object.entries(assets)) {
+        let bytes;
+        if (asset.data instanceof Blob) {
+            bytes = new Uint8Array(await asset.data.arrayBuffer());
+        }
+        else {
+            bytes = asset.data;
+        }
+        const contentType = contentTypeOf(bytes);
+        if (contentType !== "image/png" && contentType !== "image/jpeg") {
+            throw new SystemOneError("parse-error", `Image "${alias}" must be PNG or JPEG.`);
+        }
+        const name = `asset-${index}`;
+        parts.push({
+            name,
+            bytes,
+            contentType,
+        });
+        wire[alias] = { type: "image", part: name };
+        index += 1;
+    }
+    return { assets: wire, parts };
+}
+/**
+ * Keyed decisions call. `choice`, `noul`, `score`, and `box` compile to the
+ * question list `evaluate` already sends. Transport failures return
+ * `fallback` and `reason` and do not throw.
+ */
+export async function systemOne(input, options) {
+    const parsed = DecisionQuestionRecord(input.questions);
+    if (parsed instanceof type.errors) {
+        throw new SystemOneError("parse-error", `systemOne: invalid questions: ${parsed.summary}`);
+    }
+    const serialized = serializeRequest({ state: input.state, questions: input.questions }, input.assets);
+    let payload;
+    try {
+        payload = JSON.parse(serialized.json);
+    }
+    catch (cause) {
+        throw new SystemOneError("parse-error", `systemOne: request is not JSON: ${cause instanceof Error ? cause.message : String(cause)}`);
+    }
+    const questions = QuestionList(Object.entries(payload.questions !== null &&
+        typeof payload.questions === "object" &&
+        !Array.isArray(payload.questions)
+        ? payload.questions
+        : {}).map(([id, question]) => typeof question === "object" && question !== null
+        ? { id, ...question }
+        : { id }));
+    if (questions instanceof type.errors) {
+        throw new SystemOneError("parse-error", `systemOne: invalid questions: ${questions.summary}`);
+    }
+    const state = payload.state;
+    if (state === undefined) {
+        throw new SystemOneError("parse-error", "systemOne: state is required");
+    }
+    const images = serialized.assets === undefined
+        ? undefined
+        : await loadImages(serialized.assets);
+    const config = withModel(input.config, input.model);
+    const result = await evaluate({
+        state: state,
+        questions,
+        ...(input.config !== undefined || input.model !== undefined
+            ? { config }
+            : {}),
+    }, {
+        ...(options?.deps !== undefined ? { deps: options.deps } : {}),
+        ...(options?.onTelemetry !== undefined
+            ? { onTelemetry: options.onTelemetry }
+            : {}),
+        ...(images !== undefined ? { images } : {}),
+    });
+    if (result.fallback)
+        return result;
+    return {
+        fallback: false,
+        answers: answersFrom(result.decisions),
+        modelId: result.modelId,
+        backend: result.backend,
+        latencyMs: result.latencyMs,
+        ...(result.usage !== undefined ? { usage: result.usage } : {}),
+    };
+}

package/dist/evaluate.d.ts

@@ -10,6 +10,18 @@ export declare function checkAnswers(questions: Question[], answers: Record<stri
 export type EvaluateOptions = {
     onTelemetry?: (event: SystemOneTelemetryEvent) => void;
     deps?: EvaluateDeps;
+    /** Image parts already checked as PNG or JPEG. Omitted for JSON requests. */
+    images?: {
+        assets: Record<string, {
+            type: "image";
+            part: string;
+        }>;
+        parts: {
+            name: string;
+            bytes: Uint8Array;
+            contentType: "image/png" | "image/jpeg";
+        }[];
+    };
 };
 /**
  * Runs one typed-decision evaluation against System One (or its gateway)
@@ -20,6 +32,9 @@ export type EvaluateOptions = {
  * `TYPESAFE_API_KEY` for official, `AI_GATEWAY_API_KEY` then
  * `VERCEL_OIDC_TOKEN` for gateway — then the `SYSTEM_ONE_API_KEY` alias,
  * then a fail-closed `'no-key'` fallback with zero fetch calls.
+ * A custom endpoint with `auth: "none"` skips that check and sends no
+ * `Authorization` header, even if a key is present. Official and gateway
+ * always require a key; a custom endpoint without `auth: "none"` does too.
  * A `timeoutMs` that is not a finite number >= 0 falls back to
  * `DEFAULT_TIMEOUT_MS`. Transport failures map to matching fallback reasons
  * (`'timeout'`, `'network'`, `'http-error'`, or `'parse-error'` for a 2xx

package/dist/evaluate.js

@@ -3,7 +3,7 @@ import { createDefaultScheduler } from "@intx/inference";
 import { postEvaluate } from "./client.js";
 import { DEFAULT_TIMEOUT_MS, GATEWAY_API_KEY_ENV, GATEWAY_OIDC_ENV, resolveEndpoint, SYSTEM_ONE_API_KEY_ENV, TYPESAFE_API_KEY_ENV, } from "./config.js";
 import { SystemOneError, TransportError, transportFallbackReason, } from "./errors.js";
-import { APPROXIMATE_SUM_TOLERANCE as SUM_TOLERANCE, EvaluateInput, toDecision, toWireQuestions, WireRequest, WireResponseBody, } from "./schemas.js";
+import { APPROXIMATE_SUM_TOLERANCE as SUM_TOLERANCE, EvaluateInput, toDecision, toWireQuestions, WireRequest, WireResponseBody, boxEdgesOutOfRange, } from "./schemas.js";
 // ---------------------------------------------------------------------------
 // evaluate
 // ---------------------------------------------------------------------------
@@ -94,7 +94,12 @@ function checkAnswer(question, id, answer) {
             return `answer "${id}" is missing noul`;
         return undefined;
     }
-    if (answer.confidence === undefined) {
+    if (question.type === "box" && answer.type === "box") {
+        if (answer.box === undefined)
+            return `answer "${id}" is missing box`;
+        return boxEdgesOutOfRange(id, answer.box);
+    }
+    if (answer.confidence == null) {
         return `answer "${id}" is missing confidence`;
     }
     if (question.type === "choice" && answer.type === "choice") {
@@ -183,6 +188,9 @@ function envKey(name) {
  * `TYPESAFE_API_KEY` for official, `AI_GATEWAY_API_KEY` then
  * `VERCEL_OIDC_TOKEN` for gateway — then the `SYSTEM_ONE_API_KEY` alias,
  * then a fail-closed `'no-key'` fallback with zero fetch calls.
+ * A custom endpoint with `auth: "none"` skips that check and sends no
+ * `Authorization` header, even if a key is present. Official and gateway
+ * always require a key; a custom endpoint without `auth: "none"` does too.
  * A `timeoutMs` that is not a finite number >= 0 falls back to
  * `DEFAULT_TIMEOUT_MS`. Transport failures map to matching fallback reasons
  * (`'timeout'`, `'network'`, `'http-error'`, or `'parse-error'` for a 2xx
@@ -195,7 +203,8 @@ function envKey(name) {
  */
 export async function evaluate(input, options) {
     const deps = options?.deps ?? {
-        fetch: globalThis.fetch,
+        // Browsers reject fetch called as a method of another object.
+        fetch: (input, init) => fetch(input, init),
         scheduler: createDefaultScheduler(),
     };
     const start = deps.scheduler.now();
@@ -221,7 +230,12 @@ export async function evaluate(input, options) {
     const rawApiKey = parsed.config?.apiKey;
     let apiKey;
     let keySources;
-    if (rawApiKey !== undefined && rawApiKey !== "") {
+    const keyless = endpoint.auth === "none";
+    if (keyless) {
+        apiKey = undefined;
+        keySources = "";
+    }
+    else if (rawApiKey !== undefined && rawApiKey !== "") {
         apiKey = rawApiKey;
         keySources = "config.apiKey";
     }
@@ -271,15 +285,19 @@ export async function evaluate(input, options) {
         modelId: model,
     };
     emit(startEvent);
-    if (apiKey === undefined || apiKey === "") {
+    if (!keyless && (apiKey === undefined || apiKey === "")) {
         return fallback("no-key", {
             detail: `no API key supplied; set config.apiKey or ${keySources}`,
         });
     }
+    const images = options?.images;
     const wire = WireRequest({
         model,
         state: parsed.state,
         questions: toWireQuestions(parsed.questions),
+        ...(images !== undefined && images.parts.length > 0
+            ? { assets: images.assets }
+            : {}),
     });
     if (wire instanceof type.errors) {
         throw new SystemOneError("parse-error", `evaluate: internal wire serialization failed: ${wire.summary}`);
@@ -287,7 +305,13 @@ export async function evaluate(input, options) {
     let data;
     let transportLatencyMs;
     try {
-        const response = await postEvaluate(endpoint.url, wire, { timeoutMs, apiKey }, deps);
+        const response = await postEvaluate(endpoint.url, wire, {
+            timeoutMs,
+            ...(apiKey === undefined ? {} : { apiKey }),
+            ...(images !== undefined && images.parts.length > 0
+                ? { imageParts: images.parts }
+                : {}),
+        }, deps);
         data = response.data;
         transportLatencyMs = response.latencyMs;
     }

package/dist/extraction.d.ts

@@ -0,0 +1,104 @@
+import type { FallbackResult } from "./schemas.js";
+export type TextField = {
+    type: "text";
+    instructions?: string;
+};
+export type DateField = {
+    type: "date";
+    instructions?: string;
+};
+export type NumberField = {
+    type: "number";
+    decimals?: number;
+    unit?: string;
+    instructions?: string;
+};
+export type ListItemKind = "text" | "number" | "date";
+export type ListField<Items extends ListItemKind = ListItemKind> = {
+    type: "list";
+    items: Items;
+};
+export type EstimateField = {
+    type: "estimate";
+    min?: number;
+    max?: number;
+    step?: number;
+    instructions?: string;
+};
+export type ExtractionField = TextField | DateField | NumberField | ListField | EstimateField;
+export type TextAnswer = {
+    value: string | null;
+    start?: number;
+    end?: number;
+};
+export type DateAnswer = {
+    value: string | null;
+};
+export type NumberAnswer = {
+    value: number | null;
+    unit?: string;
+};
+type ListValue<Items extends string> = Items extends "number" ? number : string;
+export type ListAnswer<Items extends string = "text"> = {
+    value: ListValue<Items>[] | null;
+};
+export type EstimateAnswer = {
+    median: number | null;
+    interval?: {
+        p10: number;
+        p90: number;
+    };
+};
+type AnswerOf<Field> = Field extends {
+    type: "text";
+} ? TextAnswer : Field extends {
+    type: "date";
+} ? DateAnswer : Field extends {
+    type: "number";
+} ? NumberAnswer : Field extends {
+    type: "list";
+    items: infer Items extends string;
+} ? ListAnswer<Items> : Field extends {
+    type: "estimate";
+} ? EstimateAnswer : never;
+export type ExtractionAnswers<Fields extends Record<string, ExtractionField>> = {
+    [Key in keyof Fields]: AnswerOf<Fields[Key]>;
+};
+export type ExtractionSuccess<Fields extends Record<string, ExtractionField>> = {
+    fallback: false;
+    answers: ExtractionAnswers<Fields>;
+    modelId: string;
+    latencyMs: number;
+};
+export type ExtractionResult<Fields extends Record<string, ExtractionField>> = ExtractionSuccess<Fields> | FallbackResult;
+export type ExtractInput<Fields extends Record<string, ExtractionField>> = {
+    state: unknown;
+    fields: Fields;
+};
+export type ExtractFetch = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
+export type ExtractOptions = {
+    accountId?: string;
+    token?: string;
+    fetch?: ExtractFetch;
+};
+declare function text(instructions?: string): TextField;
+declare function date(instructions?: string): DateField;
+declare function number(options?: {
+    decimals?: number;
+    unit?: string;
+    instructions?: string;
+}): NumberField;
+declare function list<const Items extends ListItemKind>(items: Items): ListField<Items>;
+declare function estimate(options?: {
+    min?: number;
+    max?: number;
+    step?: number;
+    instructions?: string;
+}): EstimateField;
+export { date, estimate, list, number, text };
+/**
+ * Keyed extraction against Cloudflare Workers AI Clairic. Missing credentials,
+ * non-2xx responses, and bodies that are not JSON return `fallback` and do
+ * not throw.
+ */
+export declare function extract<const Fields extends Record<string, ExtractionField>>(input: ExtractInput<Fields>, options?: ExtractOptions): Promise<ExtractionResult<Fields>>;