zorya-classifier 0.0.0-stage → 0.1.0

package/dist/infrastructure/openrouter.d.ts

@@ -0,0 +1,19 @@
+import type { DecisionPort } from '../entities/contracts.js';
+export interface OpenRouterJevOptions {
+    apiKey: string;
+    fetch?: typeof globalThis.fetch;
+    maxRequestBytes?: number;
+    maxResponseBytes?: number;
+}
+export interface OpenRouterDecisionsOptions extends OpenRouterJevOptions {
+    model: string;
+    provider: string;
+    providerName?: string;
+    responseModelIds?: string[];
+    /** Only enable after confirming this wire quantization for the selected model. */
+    probabilityRoundingStep?: 0.01;
+}
+/** One pinned provider call; the caller owns the absolute deadline through its signal. */
+export declare function createOpenRouterDecisions(input: OpenRouterDecisionsOptions): DecisionPort;
+/** Optional historical integration; never an automatic fallback. */
+export declare function createOpenRouterJev(input: OpenRouterJevOptions): DecisionPort;

package/dist/infrastructure/openrouter.js

@@ -0,0 +1,207 @@
+import { z } from 'zod';
+import { ClassifierError } from '../entities/errors.js';
+import { acceptsChoiceMass } from '../shared/choice-mass.js';
+import { active, validated, ownedError, invalid, preflightJson, requestSchema, validateImage, failure, readResponse, requestLimit, responseLimit, probability, key, } from './openrouter-common.js';
+const endpoint = 'https://openrouter.ai/api/alpha/decisions';
+const responseSchema = z
+    .object({
+    id: z.string().min(1).max(512).nullable().optional(),
+    model: z.string().min(1).max(128).nullable().optional(),
+    provider: z.string().min(1).max(128).nullable().optional(),
+    usage: z
+        .object({
+        input_tokens: z.number().int().nonnegative().optional(),
+        output_tokens: z.number().int().nonnegative().optional(),
+        prompt_tokens: z.number().int().nonnegative().optional(),
+        completion_tokens: z.number().int().nonnegative().optional(),
+        total_tokens: z.number().int().nonnegative().optional(),
+        cost: z.number().finite().nonnegative().nullable().optional(),
+    })
+        .strict()
+        .nullable()
+        .optional(),
+    answers: z.record(key, z.discriminatedUnion('type', [
+        z
+            .object({
+            type: z.literal('choice'),
+            choice: key,
+            probabilities: z.record(key, probability),
+            confidence: probability.optional(),
+        })
+            .strict(),
+        z.object({ type: z.literal('noul'), noul: probability }).strict(),
+    ])),
+})
+    .strict();
+const legacyOptionsSchema = z
+    .object({
+    apiKey: z
+        .string()
+        .min(1)
+        .max(4096)
+        .refine((value) => !/\s/u.test(value)),
+    fetch: z.custom((value) => typeof value === 'function').optional(),
+    maxRequestBytes: z.number().int().min(1).max(requestLimit).default(requestLimit),
+    maxResponseBytes: z.number().int().min(1).max(responseLimit).default(responseLimit),
+})
+    .strict();
+const identifier = z
+    .string()
+    .min(1)
+    .max(256)
+    .regex(/^[a-zA-Z0-9][a-zA-Z0-9._:/-]*$/u);
+const optionsSchema = legacyOptionsSchema
+    .extend({
+    model: identifier,
+    provider: identifier,
+    providerName: z.string().min(1).max(256).optional(),
+    responseModelIds: z.array(identifier).max(8).optional(),
+    probabilityRoundingStep: z.literal(0.01).optional(),
+})
+    .strict();
+function routeName(value) {
+    return value.toLowerCase().replace(/[^a-z0-9]/gu, '');
+}
+function serialize(input, maxBytes, options) {
+    const envelope = {
+        model: options.model,
+        provider: { only: [options.provider], allow_fallbacks: false },
+    };
+    const snapshot = preflightJson(input, maxBytes - Buffer.byteLength(JSON.stringify(envelope)) + 1);
+    const request = validated(requestSchema, snapshot, 'INVALID_INPUT');
+    const questions = Object.fromEntries(Object.entries(request.questions).map(([id, question]) => [
+        id,
+        question.type === 'choice'
+            ? { type: question.type, instructions: question.instructions, criteria: question.criteria }
+            : question,
+    ]));
+    const body = JSON.stringify({ ...request, questions, ...envelope });
+    if (Buffer.byteLength(body) > maxBytes)
+        throw ownedError('RESOURCE_LIMIT', 'Decision request exceeds byte limit');
+    for (const part of request.state)
+        if (typeof part !== 'string')
+            validateImage(part.image_url.url);
+    return { request, body };
+}
+function acceptedModel(value, options) {
+    if (value === options.model || options.responseModelIds?.includes(value))
+        return true;
+    if (!value.startsWith(options.model + '-'))
+        return false;
+    const suffix = value.slice(options.model.length + 1);
+    if (!/^\d{4}-?\d{2}-?\d{2}$/u.test(suffix))
+        return false;
+    const digits = suffix.replaceAll('-', ''), date = `${digits.slice(0, 4)}-${digits.slice(4, 6)}-${digits.slice(6, 8)}`;
+    const parsed = new Date(date + 'T00:00:00.000Z');
+    return Number.isFinite(parsed.valueOf()) && parsed.toISOString().slice(0, 10) === date;
+}
+function result(raw, request, response, durationMs, options) {
+    let json;
+    try {
+        json = JSON.parse(raw);
+    }
+    catch {
+        throw invalid('INVALID_RESPONSE', 'Provider returned invalid JSON');
+    }
+    const value = validated(responseSchema, json, 'INVALID_RESPONSE');
+    if (value.model && !acceptedModel(value.model, options))
+        throw invalid('INVALID_RESPONSE', 'Provider returned an unexpected model');
+    if (value.provider &&
+        routeName(value.provider) !== routeName(options.providerName ?? options.provider))
+        throw invalid('INVALID_RESPONSE', 'Provider returned an unexpected route');
+    const questionIds = Object.keys(request.questions);
+    if (Object.keys(value.answers).length !== questionIds.length)
+        throw invalid('INVALID_RESPONSE', 'Provider returned mismatched questions');
+    const answers = { ...value.answers };
+    for (const id of questionIds) {
+        const question = request.questions[id], answer = value.answers[id];
+        if (!question || !answer || question.type !== answer.type)
+            throw invalid('INVALID_RESPONSE', 'Provider returned mismatched answer types');
+        if (question.type === 'choice' && answer.type === 'choice') {
+            const keys = Object.keys(question.criteria);
+            const scores = answer.probabilities;
+            if (Object.keys(scores).length !== keys.length ||
+                keys.some((option) => !Object.hasOwn(scores, option)) ||
+                !Object.hasOwn(question.criteria, answer.choice) ||
+                scores[answer.choice] !== Math.max(...Object.values(scores)) ||
+                !acceptsChoiceMass(Object.values(scores), options.probabilityRoundingStep))
+                throw invalid('INVALID_RESPONSE', 'Provider returned an invalid choice distribution');
+            // Explicitly configured wire quantization; retain raw scores and native ties.
+            if (!acceptsChoiceMass(Object.values(scores)))
+                answers[id] = { ...answer, probabilityRoundingStep: 0.01 };
+        }
+    }
+    const requestId = value.id ?? response.headers.get('x-generation-id');
+    if (requestId !== null && requestId.length > 512)
+        throw invalid('INVALID_RESPONSE', 'Provider returned an invalid request identity');
+    return {
+        answers,
+        metadata: {
+            model: value.model ?? null,
+            provider: value.provider ?? null,
+            requestId,
+            costUsd: value.usage?.cost ?? null,
+            durationMs,
+            attempts: 1,
+        },
+    };
+}
+/** One pinned provider call; the caller owns the absolute deadline through its signal. */
+export function createOpenRouterDecisions(input) {
+    const options = validated(optionsSchema, input, 'INVALID_INPUT');
+    const fetcher = options.fetch ?? globalThis.fetch;
+    return {
+        async decide(input, signal) {
+            active(signal);
+            let prepared;
+            try {
+                prepared = serialize(input, options.maxRequestBytes, options);
+            }
+            catch (error) {
+                active(signal);
+                if (error instanceof ClassifierError)
+                    throw error;
+                throw invalid('INVALID_INPUT', 'Decision input could not be serialized');
+            }
+            active(signal);
+            const started = performance.now();
+            let response;
+            try {
+                response = await fetcher(endpoint, {
+                    method: 'POST',
+                    headers: {
+                        Authorization: `Bearer ${options.apiKey}`,
+                        'Content-Type': 'application/json',
+                    },
+                    body: prepared.body,
+                    signal,
+                    redirect: 'error',
+                });
+            }
+            catch {
+                active(signal);
+                throw ownedError('PROVIDER', 'OpenRouter transport failed');
+            }
+            try {
+                const raw = await readResponse(response, signal, options.maxResponseBytes);
+                const value = result(raw, prepared.request, response, Math.max(0, performance.now() - started), options);
+                active(signal);
+                return value;
+            }
+            catch (error) {
+                throw failure(error, signal);
+            }
+        },
+    };
+}
+/** Optional historical integration; never an automatic fallback. */
+export function createOpenRouterJev(input) {
+    const { fetch: fetcher, ...options } = validated(legacyOptionsSchema, input, 'INVALID_INPUT');
+    return createOpenRouterDecisions({
+        ...options,
+        ...(fetcher ? { fetch: fetcher } : {}),
+        model: 'typesafe/jev-1.14',
+        provider: 'typesafe',
+        probabilityRoundingStep: 0.01,
+    });
+}

package/dist/infrastructure/raster.d.ts

@@ -0,0 +1,2 @@
+import type { RasterPort } from '../entities/contracts.js';
+export declare function createSharpRaster(): RasterPort;

package/dist/infrastructure/raster.js

@@ -0,0 +1,121 @@
+import sharp from 'sharp';
+import { limits } from '../entities/contracts.js';
+import { ClassifierError, assertActive } from '../entities/errors.js';
+function contains(outer, inner) {
+    return (inner.left >= outer.left &&
+        inner.top >= outer.top &&
+        inner.left + inner.width <= outer.left + outer.width &&
+        inner.top + inner.height <= outer.top + outer.height);
+}
+async function normalizeImage(bytes, signal) {
+    assertActive(signal);
+    const pipeline = sharp(bytes, { limitInputPixels: limits.imagePixels, failOn: 'error' });
+    try {
+        const metadata = await pipeline.metadata();
+        assertActive(signal);
+        if (!['png', 'jpeg', 'webp'].includes(metadata.format ?? '') || (metadata.pages ?? 1) !== 1)
+            throw new ClassifierError('INVALID_INPUT', 'Use a single PNG, JPEG or WebP image');
+        const normalized = await pipeline.rotate().png().toBuffer({ resolveWithObject: true });
+        assertActive(signal);
+        if (normalized.data.byteLength > limits.imageBytes)
+            throw new ClassifierError('RESOURCE_LIMIT', 'Decoded presentation exceeds image byte limit');
+        return { bytes: normalized.data, width: normalized.info.width, height: normalized.info.height };
+    }
+    catch (error) {
+        assertActive(signal);
+        if (error instanceof ClassifierError)
+            throw error;
+        throw new ClassifierError('INVALID_INPUT', 'Image cannot be decoded within pixel limits');
+    }
+    finally {
+        pipeline.destroy();
+    }
+}
+async function cropImage(image, region, signal, scale = 1) {
+    assertActive(signal);
+    if (!contains({ left: 0, top: 0, width: image.width, height: image.height }, region))
+        throw new ClassifierError('INVALID_INPUT', 'ROI lies outside oriented source image');
+    const pipeline = sharp(image.bytes, { limitInputPixels: limits.imagePixels })
+        .extract(region)
+        .resize(region.width * scale, region.height * scale, { kernel: 'nearest' });
+    try {
+        const data = await pipeline.png().toBuffer();
+        assertActive(signal);
+        return { bytes: data, width: region.width * scale, height: region.height * scale };
+    }
+    finally {
+        pipeline.destroy();
+    }
+}
+async function imageState(image, signal) {
+    assertActive(signal);
+    const scale = Math.min(1568 / Math.max(image.width, image.height), Math.max(1, 280 / Math.min(image.width, image.height)));
+    const width = Math.max(1, Math.round(image.width * scale)), height = Math.max(1, Math.round(image.height * scale));
+    const outWidth = Math.max(280, width), outHeight = Math.max(280, height);
+    const left = Math.floor((outWidth - width) / 2), top = Math.floor((outHeight - height) / 2);
+    const pipeline = sharp(image.bytes, { limitInputPixels: limits.imagePixels })
+        .resize(width, height, { kernel: 'nearest' })
+        .extend({
+        left,
+        top,
+        right: outWidth - width - left,
+        bottom: outHeight - height - top,
+        background: '#000000',
+    });
+    try {
+        const bytes = await pipeline.png().toBuffer();
+        assertActive(signal);
+        if (bytes.length > limits.imageBytes)
+            throw new ClassifierError('RESOURCE_LIMIT', 'Prepared image is too large');
+        const part = {
+            type: 'image_url',
+            image_url: { url: `data:image/png;base64,${bytes.toString('base64')}`, detail: 'high' },
+        };
+        return [
+            part,
+            JSON.stringify({
+                sourceImageTransform: {
+                    source: { width: image.width, height: image.height },
+                    output: { width: outWidth, height: outHeight },
+                    content: { left, top, width, height },
+                    scaleX: width / image.width,
+                    scaleY: height / image.height,
+                },
+            }),
+        ];
+    }
+    finally {
+        pipeline.destroy();
+    }
+}
+async function renderGrid(image, region, cells, labels, signal) {
+    const crop = await cropImage(image, region, signal);
+    const scale = Math.min(1512 / Math.max(crop.width, crop.height), Math.max(1, 900 / Math.min(crop.width, crop.height)));
+    const width = Math.max(1, Math.round(crop.width * scale)), height = Math.max(1, Math.round(crop.height * scale));
+    const rectangles = cells
+        .map((cell) => {
+        const label = labels.get(cell.id);
+        if (!label || !/^[PC][0-9]{2,3}$/.test(label))
+            throw new ClassifierError('INVALID_INPUT', 'Invalid grid label');
+        const x = ((cell.region.left - region.left) * width) / region.width, y = ((cell.region.top - region.top) * height) / region.height;
+        const w = (cell.region.width * width) / region.width, h = (cell.region.height * height) / region.height;
+        const font = Math.max(3, Math.min(18, w / (label.length * 0.7), h / 2));
+        return `<rect x="${x}" y="${y}" width="${w}" height="${h}" fill="none" stroke="white" stroke-width="1"/><rect x="${x + 1}" y="${y + 1}" width="${Math.min(w - 1, font * label.length * 0.7)}" height="${font + 2}" fill="#111827" fill-opacity="0.78"/><text x="${x + 2}" y="${y + font}" font-family="DejaVu Sans,sans-serif" font-size="${font}" fill="white">${label}</text>`;
+    })
+        .join('');
+    const svg = Buffer.from(`<svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="${height}">${rectangles}</svg>`);
+    const pipeline = sharp(crop.bytes, { limitInputPixels: limits.imagePixels })
+        .resize(width, height, { kernel: 'nearest' })
+        .composite([{ input: svg }]);
+    try {
+        const bytes = await pipeline.png().toBuffer();
+        assertActive(signal);
+        return { bytes, width, height };
+    }
+    finally {
+        pipeline.destroy();
+    }
+}
+export function createSharpRaster() {
+    return { normalize: normalizeImage, crop: cropImage, imageState, grid: renderGrid };
+}

package/dist/infrastructure/vision-chat.d.ts

@@ -0,0 +1,64 @@
+import { z } from 'zod';
+import type { DecisionPort } from '../entities/contracts.js';
+export declare const visionOptionsSchema: z.ZodObject<{
+    endpoint: z.ZodEffects<z.ZodString, string, string>;
+    headers: z.ZodOptional<z.ZodEffects<z.ZodRecord<z.ZodString, z.ZodEffects<z.ZodString, string, string>>, Record<string, string>, Record<string, string>>>;
+    apiKey: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+    model: z.ZodString;
+    provider: z.ZodOptional<z.ZodString>;
+    providerName: z.ZodOptional<z.ZodString>;
+    responseModelIds: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    responseFormat: z.ZodDefault<z.ZodEnum<["prompt", "json-object", "json-schema"]>>;
+    maxOutputTokens: z.ZodDefault<z.ZodNumber>;
+    reasoningEffort: z.ZodOptional<z.ZodEnum<["none", "minimal", "low", "medium", "high"]>>;
+    fetch: z.ZodOptional<z.ZodType<typeof fetch, z.ZodTypeDef, typeof fetch>>;
+    maxRequestBytes: z.ZodDefault<z.ZodNumber>;
+    maxResponseBytes: z.ZodDefault<z.ZodNumber>;
+}, "strict", z.ZodTypeAny, {
+    model: string;
+    endpoint: string;
+    responseFormat: "prompt" | "json-object" | "json-schema";
+    maxOutputTokens: number;
+    maxRequestBytes: number;
+    maxResponseBytes: number;
+    provider?: string | undefined;
+    headers?: Record<string, string> | undefined;
+    apiKey?: string | undefined;
+    providerName?: string | undefined;
+    responseModelIds?: string[] | undefined;
+    reasoningEffort?: "high" | "none" | "minimal" | "low" | "medium" | undefined;
+    fetch?: typeof fetch | undefined;
+}, {
+    model: string;
+    endpoint: string;
+    provider?: string | undefined;
+    headers?: Record<string, string> | undefined;
+    apiKey?: string | undefined;
+    providerName?: string | undefined;
+    responseModelIds?: string[] | undefined;
+    responseFormat?: "prompt" | "json-object" | "json-schema" | undefined;
+    maxOutputTokens?: number | undefined;
+    reasoningEffort?: "high" | "none" | "minimal" | "low" | "medium" | undefined;
+    fetch?: typeof fetch | undefined;
+    maxRequestBytes?: number | undefined;
+    maxResponseBytes?: number | undefined;
+}>;
+export interface VisionChatOptions {
+    endpoint: string;
+    headers?: Record<string, string>;
+    apiKey?: string;
+    model: string;
+    provider?: string;
+    /** Expected display name when it differs from the pinned provider slug. */
+    providerName?: string;
+    /** Explicit additional response snapshot identities; never a routing fallback. */
+    responseModelIds?: string[];
+    responseFormat?: 'prompt' | 'json-object' | 'json-schema';
+    maxOutputTokens?: number;
+    reasoningEffort?: 'none' | 'minimal' | 'low' | 'medium' | 'high';
+    fetch?: typeof globalThis.fetch;
+    maxRequestBytes?: number;
+    maxResponseBytes?: number;
+}
+/** Ordinary text/image chat completion, with no native classifier/Decisions requirement. */
+export declare function createVisionChat(input: unknown): DecisionPort;