@corbits/system-one 0.3.2 → 0.4.0

package/dist/extraction.js

@@ -0,0 +1,332 @@
+import { type } from "arktype";
+const CLAIRIC_MODEL = "@cf/cloudflare/clairic";
+function definedString(value) {
+    if (value === undefined || value === "")
+        return undefined;
+    return value;
+}
+function text(instructions) {
+    return instructions === undefined
+        ? { type: "text" }
+        : { type: "text", instructions };
+}
+function date(instructions) {
+    return instructions === undefined
+        ? { type: "date" }
+        : { type: "date", instructions };
+}
+function number(options) {
+    const field = { type: "number" };
+    if (options?.decimals !== undefined)
+        field.decimals = options.decimals;
+    if (options?.unit !== undefined)
+        field.unit = options.unit;
+    if (options?.instructions !== undefined)
+        field.instructions = options.instructions;
+    return field;
+}
+function list(items) {
+    return { type: "list", items };
+}
+function estimate(options) {
+    const field = { type: "estimate" };
+    if (options?.min !== undefined)
+        field.min = options.min;
+    if (options?.max !== undefined)
+        field.max = options.max;
+    if (options?.step !== undefined)
+        field.step = options.step;
+    if (options?.instructions !== undefined)
+        field.instructions = options.instructions;
+    return field;
+}
+export { date, estimate, list, number, text };
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+const finiteNumber = type("number").narrow((value) => Number.isFinite(value));
+const finiteOrNull = type("number | null").narrow((value) => value === null || Number.isFinite(value));
+const TextWire = type({
+    "type?": "string",
+    "value?": "string | null",
+    "text?": "string | null",
+    "start?": finiteNumber,
+    "end?": finiteNumber,
+    "span?": [finiteNumber, finiteNumber],
+    "offsets?": {
+        "start?": finiteNumber,
+        "end?": finiteNumber,
+    },
+});
+const DateWire = type("string").or(type({
+    "type?": "string",
+    "value?": "string | null",
+    "date?": "string | null",
+}));
+const NumberWire = finiteNumber.or(type({
+    "type?": "string",
+    "value?": finiteOrNull,
+    "number?": finiteOrNull,
+    "unit?": "string",
+}));
+const stringItems = type("string[]").or("null");
+const numberItems = finiteNumber.array().or("null");
+const StringListWire = type("string[]").or(type({
+    "type?": "string",
+    "value?": stringItems,
+    "items?": stringItems,
+}));
+const NumberListWire = finiteNumber.array().or(type({
+    "type?": "string",
+    "value?": numberItems,
+    "items?": numberItems,
+}));
+const EstimateInterval = type([finiteNumber, finiteNumber]).or(type({
+    "p10?": finiteNumber,
+    "low?": finiteNumber,
+    "p90?": finiteNumber,
+    "high?": finiteNumber,
+}));
+const EstimateWire = type({
+    "type?": "string",
+    "value?": finiteOrNull,
+    "median?": finiteOrNull,
+    "p10?": finiteNumber,
+    "p90?": finiteNumber,
+    "interval?": EstimateInterval,
+});
+function isParseError(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        "parseError" in value &&
+        typeof value.parseError === "string");
+}
+function textAnswer(raw) {
+    if (typeof raw === "string")
+        return { value: raw };
+    if (raw === null || raw === undefined)
+        return { value: null };
+    const parsed = TextWire(raw);
+    if (parsed instanceof type.errors)
+        return { parseError: parsed.summary };
+    const value = typeof parsed.value === "string"
+        ? parsed.value
+        : typeof parsed.text === "string"
+            ? parsed.text
+            : null;
+    const start = parsed.start ?? parsed.span?.[0] ?? parsed.offsets?.start;
+    const end = parsed.end ?? parsed.span?.[1] ?? parsed.offsets?.end;
+    const answer = { value };
+    if (start !== undefined)
+        answer.start = start;
+    if (end !== undefined)
+        answer.end = end;
+    return answer;
+}
+function dateAnswer(raw) {
+    if (raw === null || raw === undefined)
+        return { value: null };
+    const parsed = DateWire(raw);
+    if (parsed instanceof type.errors)
+        return { parseError: parsed.summary };
+    if (typeof parsed === "string")
+        return { value: parsed };
+    const value = typeof parsed.value === "string"
+        ? parsed.value
+        : typeof parsed.date === "string"
+            ? parsed.date
+            : null;
+    return { value };
+}
+function numberAnswer(raw) {
+    if (raw === null || raw === undefined)
+        return { value: null };
+    const parsed = NumberWire(raw);
+    if (parsed instanceof type.errors)
+        return { parseError: parsed.summary };
+    if (typeof parsed === "number")
+        return { value: parsed };
+    const value = typeof parsed.value === "number"
+        ? parsed.value
+        : typeof parsed.number === "number"
+            ? parsed.number
+            : null;
+    const answer = { value };
+    if (parsed.unit !== undefined)
+        answer.unit = parsed.unit;
+    return answer;
+}
+function listValues(parsed) {
+    if (Array.isArray(parsed))
+        return parsed;
+    if (parsed.value !== undefined)
+        return parsed.value;
+    return parsed.items ?? null;
+}
+function listAnswer(items, raw) {
+    if (raw === null || raw === undefined)
+        return { value: null };
+    const parsed = (items === "number" ? NumberListWire : StringListWire)(raw);
+    if (parsed instanceof type.errors)
+        return { parseError: parsed.summary };
+    const values = listValues(parsed);
+    if (values === null)
+        return { value: null };
+    if (items === "number") {
+        if (!values.every((item) => typeof item === "number")) {
+            return { parseError: "list items must be numbers" };
+        }
+        return { value: values };
+    }
+    if (!values.every((item) => typeof item === "string")) {
+        return { parseError: "list items must be strings" };
+    }
+    return { value: values };
+}
+function isNumberPair(value) {
+    return Array.isArray(value);
+}
+function estimateInterval(parsed) {
+    if (parsed.p10 !== undefined && parsed.p90 !== undefined) {
+        return { p10: parsed.p10, p90: parsed.p90 };
+    }
+    const interval = parsed.interval;
+    if (interval === undefined)
+        return undefined;
+    if (isNumberPair(interval)) {
+        const low = interval[0];
+        const high = interval[1];
+        if (low === undefined || high === undefined)
+            return undefined;
+        return { p10: low, p90: high };
+    }
+    const low = interval.p10 ?? interval.low;
+    const high = interval.p90 ?? interval.high;
+    if (low === undefined || high === undefined)
+        return undefined;
+    return { p10: low, p90: high };
+}
+function estimateAnswer(raw) {
+    if (raw === null || raw === undefined)
+        return { median: null };
+    const parsed = EstimateWire(raw);
+    if (parsed instanceof type.errors)
+        return { parseError: parsed.summary };
+    const median = parsed.median ?? parsed.value ?? null;
+    const answer = { median };
+    const interval = estimateInterval(parsed);
+    if (interval !== undefined)
+        answer.interval = interval;
+    return answer;
+}
+function mapAnswer(field, raw) {
+    if (field.type === "text")
+        return textAnswer(raw);
+    if (field.type === "date")
+        return dateAnswer(raw);
+    if (field.type === "number")
+        return numberAnswer(raw);
+    if (field.type === "list")
+        return listAnswer(field.items, raw);
+    return estimateAnswer(raw);
+}
+function isExtractionAnswers(fields, answers) {
+    return Object.keys(fields).every((key) => Object.hasOwn(answers, key));
+}
+function answersOf(fields, raw) {
+    const envelope = isRecord(raw) && isRecord(raw["result"]) ? raw["result"] : raw;
+    if (!isRecord(envelope) || !isRecord(envelope["answers"])) {
+        return { parseError: "response has no answers" };
+    }
+    const source = envelope["answers"];
+    const answers = {};
+    for (const [name, field] of Object.entries(fields)) {
+        const parsed = mapAnswer(field, source[name]);
+        if (isParseError(parsed)) {
+            return {
+                parseError: `answer "${name}" failed schema validation: ${parsed.parseError}`,
+            };
+        }
+        answers[name] = parsed;
+    }
+    if (!isExtractionAnswers(fields, answers)) {
+        return { parseError: "response has no answers" };
+    }
+    return answers;
+}
+function fallback(reason, started, extra) {
+    const result = {
+        fallback: true,
+        reason,
+        latencyMs: Math.max(0, Date.now() - started),
+        backendAttempted: "cloudflare-workers-ai",
+    };
+    if (extra?.httpStatus !== undefined)
+        result.httpStatus = extra.httpStatus;
+    if (extra?.detail !== undefined)
+        result.detail = extra.detail;
+    return result;
+}
+/**
+ * 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 async function extract(input, options) {
+    const started = Date.now();
+    const accountId = definedString(options?.accountId) ??
+        definedString(process.env["CLOUDFLARE_ACCOUNT_ID"]);
+    const token = definedString(options?.token) ??
+        definedString(process.env["CLOUDFLARE_API_TOKEN"]);
+    if (accountId === undefined || token === undefined) {
+        return fallback("no-key", started, {
+            detail: "no Cloudflare credentials; set accountId and token or CLOUDFLARE_ACCOUNT_ID and CLOUDFLARE_API_TOKEN",
+        });
+    }
+    const url = `https://api.cloudflare.com/client/v4/accounts/${accountId}/ai/run/${CLAIRIC_MODEL}`;
+    const fetchImpl = options?.fetch ?? fetch;
+    let response;
+    try {
+        response = await fetchImpl(url, {
+            method: "POST",
+            headers: {
+                authorization: `Bearer ${token}`,
+                "content-type": "application/json",
+            },
+            body: JSON.stringify({
+                model: "clairic",
+                state: input.state,
+                fields: input.fields,
+            }),
+        });
+    }
+    catch (cause) {
+        return fallback("network", started, {
+            detail: cause instanceof Error ? cause.message : String(cause),
+        });
+    }
+    if (!response.ok) {
+        return fallback("http-error", started, { httpStatus: response.status });
+    }
+    let body;
+    try {
+        body = await response.json();
+    }
+    catch (cause) {
+        return fallback("parse-error", started, {
+            detail: cause instanceof Error ? cause.message : String(cause),
+        });
+    }
+    const answers = answersOf(input.fields, body);
+    if (isParseError(answers)) {
+        return fallback("parse-error", started, {
+            detail: answers.parseError.slice(0, 240),
+        });
+    }
+    return {
+        fallback: false,
+        answers,
+        modelId: "clairic",
+        latencyMs: Math.max(0, Date.now() - started),
+    };
+}

package/dist/index.d.ts

@@ -2,8 +2,11 @@ export { DEFAULT_TIMEOUT_MS } from "./config.js";
 export type { EvaluateDeps } from "./client.js";
 export { evaluate } from "./evaluate.js";
 export type { EvaluateOptions } from "./evaluate.js";
+export { choice, noul, score, box, systemOne } from "./decisions.js";
+export type { SystemOneResult, SystemOneSuccess } from "./decisions.js";
+export { Image, image, withAssets } from "./assets.js";
 export { createSystemOneAdapter, createSystemOneAdapterFactory, SYSTEM_ONE_PROVIDER, } from "./adapter.js";
 export { SystemOneError } from "./errors.js";
 export type { SystemOneErrorCode } from "./errors.js";
 export { SystemOneTelemetryEvent } from "./telemetry.js";
-export { BooleanQuestion, ChoiceQuestion, Decision, Description, EndpointConfig, EvaluateConfig, EvaluateInput, EvaluateResult, FallbackReason, FallbackResult, NoulQuestion, ProbabilityMap, Question, QuestionList, ScoreQuestion, State, Usage, } from "./schemas.js";
+export { BooleanQuestion, ChoiceQuestion, Decision, DecisionQuestion, DecisionQuestionRecord, Description, EndpointConfig, EvaluateConfig, EvaluateInput, EvaluateResult, FallbackReason, FallbackResult, NoulQuestion, ProbabilityMap, Question, QuestionList, ScoreQuestion, State, Usage, } from "./schemas.js";

package/dist/index.js

@@ -1,6 +1,8 @@
 export { DEFAULT_TIMEOUT_MS } from "./config.js";
 export { evaluate } from "./evaluate.js";
+export { choice, noul, score, box, systemOne } from "./decisions.js";
+export { Image, image, withAssets } from "./assets.js";
 export { createSystemOneAdapter, createSystemOneAdapterFactory, SYSTEM_ONE_PROVIDER, } from "./adapter.js";
 export { SystemOneError } from "./errors.js";
 export { SystemOneTelemetryEvent } from "./telemetry.js";
-export { BooleanQuestion, ChoiceQuestion, Decision, Description, EndpointConfig, EvaluateConfig, EvaluateInput, EvaluateResult, FallbackReason, FallbackResult, NoulQuestion, ProbabilityMap, Question, QuestionList, ScoreQuestion, State, Usage, } from "./schemas.js";
+export { BooleanQuestion, ChoiceQuestion, Decision, DecisionQuestion, DecisionQuestionRecord, Description, EndpointConfig, EvaluateConfig, EvaluateInput, EvaluateResult, FallbackReason, FallbackResult, NoulQuestion, ProbabilityMap, Question, QuestionList, ScoreQuestion, State, Usage, } from "./schemas.js";

package/dist/schemas.d.ts

@@ -66,6 +66,50 @@ export declare const BooleanQuestion: import("arktype/internal/variants/object.t
     };
 }, {}>;
 export type BooleanQuestion = typeof BooleanQuestion.infer;
+export declare const BoxQuestion: import("arktype/internal/variants/object.ts").ObjectType<{
+    id: string;
+    type: "box";
+    instructions: string | {
+        [x: string]: unknown;
+    } | unknown[];
+}, {}>;
+export type BoxQuestion = typeof BoxQuestion.infer;
+export declare const DecisionQuestion: import("arktype/internal/variants/object.ts").ObjectType<{
+    type: "choice";
+    instructions: unknown;
+    criteria: unknown;
+} | {
+    type: "noul";
+    instructions?: unknown;
+    criteria?: unknown;
+} | {
+    type: "score";
+    instructions: unknown;
+    criteria: unknown;
+} | {
+    type: "box";
+    instructions: unknown;
+}, {}>;
+export type DecisionQuestion = typeof DecisionQuestion.infer;
+export declare const DecisionQuestionRecord: import("arktype/internal/variants/object.ts").ObjectType<{
+    [x: string]: {
+        type: "choice";
+        instructions: unknown;
+        criteria: unknown;
+    } | {
+        type: "noul";
+        instructions?: unknown;
+        criteria?: unknown;
+    } | {
+        type: "score";
+        instructions: unknown;
+        criteria: unknown;
+    } | {
+        type: "box";
+        instructions: unknown;
+    };
+}, {}>;
+export type DecisionQuestionRecord = typeof DecisionQuestionRecord.infer;
 export declare const Question: import("arktype/internal/variants/object.ts").ObjectType<{
     id: string;
     type: "choice";
@@ -114,6 +158,12 @@ export declare const Question: import("arktype/internal/variants/object.ts").Obj
             [x: string]: unknown;
         } | unknown[];
     };
+} | {
+    id: string;
+    type: "box";
+    instructions: string | {
+        [x: string]: unknown;
+    } | unknown[];
 }, {}>;
 export type Question = typeof Question.infer;
 export declare const QuestionList: import("arktype/internal/variants/array.ts").ArrayType<({
@@ -164,12 +214,19 @@ export declare const QuestionList: import("arktype/internal/variants/array.ts").
             [x: string]: unknown;
         } | unknown[];
     };
+} | {
+    id: string;
+    type: "box";
+    instructions: string | {
+        [x: string]: unknown;
+    } | unknown[];
 })[], {}>;
 export type QuestionList = typeof QuestionList.infer;
 export declare const EndpointConfig: import("arktype/internal/variants/object.ts").ObjectType<{
     kind: "custom";
     url: string;
     model?: string;
+    auth?: "none";
 } | {
     kind: "official" | "gateway";
     model?: string;
@@ -180,6 +237,7 @@ export declare const EvaluateConfig: import("arktype/internal/variants/object.ts
         kind: "custom";
         url: string;
         model?: string;
+        auth?: "none";
     } | {
         kind: "official" | "gateway";
         model?: string;
@@ -240,12 +298,19 @@ export declare const EvaluateInput: import("arktype/internal/variants/object.ts"
                 [x: string]: unknown;
             } | unknown[];
         };
+    } | {
+        id: string;
+        type: "box";
+        instructions: string | {
+            [x: string]: unknown;
+        } | unknown[];
     })[];
     config?: {
         endpoint?: {
             kind: "custom";
             url: string;
             model?: string;
+            auth?: "none";
         } | {
             kind: "official" | "gateway";
             model?: string;
@@ -257,14 +322,14 @@ export declare const EvaluateInput: import("arktype/internal/variants/object.ts"
 export type EvaluateInput = typeof EvaluateInput.infer;
 /** One question in wire form: no id (the map key carries it). */
 export declare const WireQuestion: import("arktype/internal/variants/object.ts").ObjectType<{
-    type: "choice" | "score" | "noul";
+    type: "choice" | "score" | "noul" | "box";
     instructions: string | {
         [x: string]: unknown;
     } | unknown[];
     criteria?: unknown;
 }, {}>;
 export type WireQuestion = typeof WireQuestion.infer;
-/** The exact POST body: model + state + id-keyed questions. */
+/** The exact POST body: model + state + id-keyed questions, plus image parts. */
 export declare const WireRequest: import("arktype/internal/variants/object.ts").ObjectType<{
     model: string;
     state: string | {
@@ -272,13 +337,19 @@ export declare const WireRequest: import("arktype/internal/variants/object.ts").
     } | unknown[];
     questions: {
         [x: string]: {
-            type: "choice" | "score" | "noul";
+            type: "choice" | "score" | "noul" | "box";
             instructions: string | {
                 [x: string]: unknown;
             } | unknown[];
             criteria?: unknown;
         };
     };
+    assets?: {
+        [x: string]: {
+            type: "image";
+            part: string;
+        };
+    };
 }, {}>;
 export type WireRequest = typeof WireRequest.infer;
 /**
@@ -295,19 +366,32 @@ export type ProbabilityMap = typeof ProbabilityMap.infer;
 /** Tolerance for probability-sum checks (backend rounds to 2 decimals). */
 export declare const APPROXIMATE_SUM_TOLERANCE = 0.02;
 export declare const WireAnswer: import("arktype/internal/variants/object.ts").ObjectType<{
-    type: "choice" | "score" | "noul";
+    type: "choice" | "score" | "noul" | "box";
     choice?: string;
     score?: number;
     noul?: number;
     probabilities?: {
         [x: string]: number;
     };
-    confidence?: number;
+    confidence?: number | null;
     legend?: {
         [x: string]: string;
     };
+    box?: {
+        top: number;
+        bottom: number;
+        left: number;
+        right: number;
+    };
 }, {}>;
 export type WireAnswer = typeof WireAnswer.infer;
+/** Box edges are fractions of the image. Shared by `evaluate` and the adapter. */
+export declare function boxEdgesOutOfRange(id: string, box: {
+    top: number;
+    bottom: number;
+    left: number;
+    right: number;
+}): string | undefined;
 export declare const WireUsage: import("arktype/internal/variants/object.ts").ObjectType<{
     input_tokens: number;
     output_tokens: number;
@@ -316,17 +400,23 @@ export type WireUsage = typeof WireUsage.infer;
 export declare const WireResponseBody: import("arktype/internal/variants/object.ts").ObjectType<{
     answers: {
         [x: string]: {
-            type: "choice" | "score" | "noul";
+            type: "choice" | "score" | "noul" | "box";
             choice?: string;
             score?: number;
             noul?: number;
             probabilities?: {
                 [x: string]: number;
             };
-            confidence?: number;
+            confidence?: number | null;
             legend?: {
                 [x: string]: string;
             };
+            box?: {
+                top: number;
+                bottom: number;
+                left: number;
+                right: number;
+            };
         };
     };
     model?: string;
@@ -359,6 +449,16 @@ export declare const Decision: import("arktype/internal/variants/object.ts").Obj
         [x: string]: number;
     };
     confidence: number;
+} | {
+    id: string;
+    type: "box";
+    box: {
+        top: number;
+        bottom: number;
+        left: number;
+        right: number;
+    };
+    confidence: number | null;
 }, {}>;
 export type Decision = typeof Decision.infer;
 /**
@@ -397,6 +497,16 @@ export declare const EvaluateResult: import("arktype/internal/variants/object.ts
             [x: string]: number;
         };
         confidence: number;
+    } | {
+        id: string;
+        type: "box";
+        box: {
+            top: number;
+            bottom: number;
+            left: number;
+            right: number;
+        };
+        confidence: number | null;
     })[];
     modelId: string;
     backend: "custom" | "gateway" | "corbits-system-one";