zorya-classifier 0.0.0-stage → 0.2.0

package/dist/entities/contracts.d.ts

@@ -0,0 +1,471 @@
+import { z } from 'zod';
+export declare const limits: Readonly<{
+    imageBytes: number;
+    imagePixels: 16777216;
+    bodyBytes: number;
+    maxClasses: 255;
+    maxImages: 9;
+}>;
+export declare const pixelRectSchema: z.ZodObject<{
+    left: z.ZodNumber;
+    top: z.ZodNumber;
+    width: z.ZodNumber;
+    height: z.ZodNumber;
+}, "strict", z.ZodTypeAny, {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+}, {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+}>;
+export type PixelRect = z.infer<typeof pixelRectSchema>;
+export interface GridCell {
+    id: string;
+    column: number;
+    row: number;
+    region: PixelRect;
+    xId?: string;
+    yId?: string;
+    kind?: 'cell';
+}
+export interface GridPanel {
+    id: string;
+    region: PixelRect;
+    cells: readonly GridCell[];
+}
+export declare const classSchema: z.ZodObject<{
+    id: z.ZodString;
+    description: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    id: string;
+    description: string;
+}, {
+    id: string;
+    description: string;
+}>;
+export type ClassDefinition = z.infer<typeof classSchema>;
+export declare const representationSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
+    type: z.ZodLiteral<"vision">;
+}, "strict", z.ZodTypeAny, {
+    type: "vision";
+}, {
+    type: "vision";
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"experimental-text">;
+    profile: z.ZodLiteral<"text-image-v1">;
+}, "strict", z.ZodTypeAny, {
+    type: "experimental-text";
+    profile: "text-image-v1";
+}, {
+    type: "experimental-text";
+    profile: "text-image-v1";
+}>]>;
+export type Representation = z.infer<typeof representationSchema>;
+export declare const classifySchema: z.ZodObject<{
+    input: z.ZodUnion<[z.ZodString, z.ZodEffects<z.ZodObject<{
+        text: z.ZodOptional<z.ZodString>;
+        image: z.ZodOptional<z.ZodEffects<z.ZodType<Uint8Array<ArrayBufferLike>, z.ZodTypeDef, Uint8Array<ArrayBufferLike>>, Uint8Array<ArrayBufferLike>, Uint8Array<ArrayBufferLike>>>;
+    }, "strict", z.ZodTypeAny, {
+        text?: string | undefined;
+        image?: Uint8Array<ArrayBufferLike> | undefined;
+    }, {
+        text?: string | undefined;
+        image?: Uint8Array<ArrayBufferLike> | undefined;
+    }>, {
+        text?: string | undefined;
+        image?: Uint8Array<ArrayBufferLike> | undefined;
+    }, {
+        text?: string | undefined;
+        image?: Uint8Array<ArrayBufferLike> | undefined;
+    }>]>;
+    classes: z.ZodEffects<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        description: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        id: string;
+        description: string;
+    }, {
+        id: string;
+        description: string;
+    }>, "many">, {
+        id: string;
+        description: string;
+    }[], {
+        id: string;
+        description: string;
+    }[]>;
+    instructions: z.ZodOptional<z.ZodString>;
+    representation: z.ZodOptional<z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
+        type: z.ZodLiteral<"vision">;
+    }, "strict", z.ZodTypeAny, {
+        type: "vision";
+    }, {
+        type: "vision";
+    }>, z.ZodObject<{
+        type: z.ZodLiteral<"experimental-text">;
+        profile: z.ZodLiteral<"text-image-v1">;
+    }, "strict", z.ZodTypeAny, {
+        type: "experimental-text";
+        profile: "text-image-v1";
+    }, {
+        type: "experimental-text";
+        profile: "text-image-v1";
+    }>]>>;
+}, "strict", z.ZodTypeAny, {
+    input: string | {
+        text?: string | undefined;
+        image?: Uint8Array<ArrayBufferLike> | undefined;
+    };
+    classes: {
+        id: string;
+        description: string;
+    }[];
+    instructions?: string | undefined;
+    representation?: {
+        type: "vision";
+    } | {
+        type: "experimental-text";
+        profile: "text-image-v1";
+    } | undefined;
+}, {
+    input: string | {
+        text?: string | undefined;
+        image?: Uint8Array<ArrayBufferLike> | undefined;
+    };
+    classes: {
+        id: string;
+        description: string;
+    }[];
+    instructions?: string | undefined;
+    representation?: {
+        type: "vision";
+    } | {
+        type: "experimental-text";
+        profile: "text-image-v1";
+    } | undefined;
+}>;
+export type ClassifyInput = z.input<typeof classifySchema> & {
+    signal?: AbortSignal;
+};
+export declare const locateSchema: z.ZodObject<{
+    image: z.ZodEffects<z.ZodType<Uint8Array<ArrayBufferLike>, z.ZodTypeDef, Uint8Array<ArrayBufferLike>>, Uint8Array<ArrayBufferLike>, Uint8Array<ArrayBufferLike>>;
+    target: z.ZodString;
+    exclusions: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    roi: z.ZodOptional<z.ZodObject<{
+        left: z.ZodNumber;
+        top: z.ZodNumber;
+        width: z.ZodNumber;
+        height: z.ZodNumber;
+    }, "strict", z.ZodTypeAny, {
+        left: number;
+        top: number;
+        width: number;
+        height: number;
+    }, {
+        left: number;
+        top: number;
+        width: number;
+        height: number;
+    }>>;
+    mode: z.ZodOptional<z.ZodLiteral<"region">>;
+    representation: z.ZodOptional<z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
+        type: z.ZodLiteral<"vision">;
+    }, "strict", z.ZodTypeAny, {
+        type: "vision";
+    }, {
+        type: "vision";
+    }>, z.ZodObject<{
+        type: z.ZodLiteral<"experimental-text">;
+        profile: z.ZodLiteral<"text-image-v1">;
+    }, "strict", z.ZodTypeAny, {
+        type: "experimental-text";
+        profile: "text-image-v1";
+    }, {
+        type: "experimental-text";
+        profile: "text-image-v1";
+    }>]>>;
+}, "strict", z.ZodTypeAny, {
+    image: Uint8Array<ArrayBufferLike>;
+    target: string;
+    exclusions: string[];
+    representation?: {
+        type: "vision";
+    } | {
+        type: "experimental-text";
+        profile: "text-image-v1";
+    } | undefined;
+    roi?: {
+        left: number;
+        top: number;
+        width: number;
+        height: number;
+    } | undefined;
+    mode?: "region" | undefined;
+}, {
+    image: Uint8Array<ArrayBufferLike>;
+    target: string;
+    representation?: {
+        type: "vision";
+    } | {
+        type: "experimental-text";
+        profile: "text-image-v1";
+    } | undefined;
+    exclusions?: string[] | undefined;
+    roi?: {
+        left: number;
+        top: number;
+        width: number;
+        height: number;
+    } | undefined;
+    mode?: "region" | undefined;
+}>;
+export type LocateInput = z.input<typeof locateSchema> & {
+    signal?: AbortSignal;
+};
+export type ImagePart = {
+    type: 'image_url';
+    image_url: {
+        url: string;
+        detail: 'high';
+    };
+};
+export type DecisionState = (string | ImagePart)[];
+export type ChoiceQuestion = {
+    type: 'choice';
+    rankingSize?: 1 | 4;
+    instructions: string;
+    criteria: Record<string, string>;
+};
+type NoulQuestion = {
+    type: 'noul';
+    instructions: string;
+};
+type DecisionQuestion = ChoiceQuestion | NoulQuestion;
+export type DecisionRequest = {
+    state: DecisionState;
+    questions: Record<string, DecisionQuestion>;
+};
+export interface DecisionMetadata {
+    model: string | null;
+    provider: string | null;
+    requestId: string | null;
+    durationMs: number;
+    costUsd: number | null;
+    attempts: number;
+}
+declare const choiceAnswerSchema: z.ZodObject<{
+    type: z.ZodLiteral<"choice">;
+    choice: z.ZodString;
+    probabilities: z.ZodRecord<z.ZodString, z.ZodNumber>;
+    confidence: z.ZodOptional<z.ZodNumber>;
+    probabilityRoundingStep: z.ZodOptional<z.ZodLiteral<0.01>>;
+}, "strip", z.ZodTypeAny, {
+    type: "choice";
+    choice: string;
+    probabilities: Record<string, number>;
+    confidence?: number | undefined;
+    probabilityRoundingStep?: 0.01 | undefined;
+}, {
+    type: "choice";
+    choice: string;
+    probabilities: Record<string, number>;
+    confidence?: number | undefined;
+    probabilityRoundingStep?: 0.01 | undefined;
+}>;
+export type ChoiceAnswer = z.infer<typeof choiceAnswerSchema>;
+export declare const decisionResultSchema: z.ZodObject<{
+    answers: z.ZodRecord<z.ZodString, z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
+        type: z.ZodLiteral<"choice">;
+        choice: z.ZodString;
+        probabilities: z.ZodRecord<z.ZodString, z.ZodNumber>;
+        confidence: z.ZodOptional<z.ZodNumber>;
+        probabilityRoundingStep: z.ZodOptional<z.ZodLiteral<0.01>>;
+    }, "strip", z.ZodTypeAny, {
+        type: "choice";
+        choice: string;
+        probabilities: Record<string, number>;
+        confidence?: number | undefined;
+        probabilityRoundingStep?: 0.01 | undefined;
+    }, {
+        type: "choice";
+        choice: string;
+        probabilities: Record<string, number>;
+        confidence?: number | undefined;
+        probabilityRoundingStep?: 0.01 | undefined;
+    }>, z.ZodObject<{
+        type: z.ZodLiteral<"ranked-choice">;
+        ranking: z.ZodArray<z.ZodString, "many">;
+    }, "strict", z.ZodTypeAny, {
+        type: "ranked-choice";
+        ranking: string[];
+    }, {
+        type: "ranked-choice";
+        ranking: string[];
+    }>, z.ZodObject<{
+        type: z.ZodLiteral<"presence">;
+        presence: z.ZodEnum<["present", "absent", "unknown"]>;
+    }, "strict", z.ZodTypeAny, {
+        type: "presence";
+        presence: "unknown" | "present" | "absent";
+    }, {
+        type: "presence";
+        presence: "unknown" | "present" | "absent";
+    }>, z.ZodObject<{
+        type: z.ZodLiteral<"noul">;
+        noul: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        type: "noul";
+        noul: number;
+    }, {
+        type: "noul";
+        noul: number;
+    }>]>>;
+    metadata: z.ZodObject<{
+        model: z.ZodNullable<z.ZodString>;
+        provider: z.ZodNullable<z.ZodString>;
+        requestId: z.ZodNullable<z.ZodString>;
+        durationMs: z.ZodNumber;
+        costUsd: z.ZodNullable<z.ZodNumber>;
+        attempts: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        model: string | null;
+        provider: string | null;
+        requestId: string | null;
+        durationMs: number;
+        costUsd: number | null;
+        attempts: number;
+    }, {
+        model: string | null;
+        provider: string | null;
+        requestId: string | null;
+        durationMs: number;
+        costUsd: number | null;
+        attempts: number;
+    }>;
+}, "strip", z.ZodTypeAny, {
+    answers: Record<string, {
+        type: "choice";
+        choice: string;
+        probabilities: Record<string, number>;
+        confidence?: number | undefined;
+        probabilityRoundingStep?: 0.01 | undefined;
+    } | {
+        type: "ranked-choice";
+        ranking: string[];
+    } | {
+        type: "presence";
+        presence: "unknown" | "present" | "absent";
+    } | {
+        type: "noul";
+        noul: number;
+    }>;
+    metadata: {
+        model: string | null;
+        provider: string | null;
+        requestId: string | null;
+        durationMs: number;
+        costUsd: number | null;
+        attempts: number;
+    };
+}, {
+    answers: Record<string, {
+        type: "choice";
+        choice: string;
+        probabilities: Record<string, number>;
+        confidence?: number | undefined;
+        probabilityRoundingStep?: 0.01 | undefined;
+    } | {
+        type: "ranked-choice";
+        ranking: string[];
+    } | {
+        type: "presence";
+        presence: "unknown" | "present" | "absent";
+    } | {
+        type: "noul";
+        noul: number;
+    }>;
+    metadata: {
+        model: string | null;
+        provider: string | null;
+        requestId: string | null;
+        durationMs: number;
+        costUsd: number | null;
+        attempts: number;
+    };
+}>;
+export type DecisionResult = z.infer<typeof decisionResultSchema>;
+export interface DecisionPort {
+    decide(request: DecisionRequest, signal: AbortSignal): Promise<DecisionResult>;
+}
+export interface ChoiceSelection {
+    choice: string;
+    nativeChoice: string | null;
+    probabilities: Record<string, number> | null;
+    ranking?: string[];
+    confidence?: number;
+    probabilityRoundingStep?: 0.01;
+    tied: string[];
+}
+export interface ClassificationResult extends ChoiceSelection {
+    metadata: DecisionMetadata;
+}
+export interface LocalizationMetadata {
+    image: {
+        width: number;
+        height: number;
+        coordinateSpace: 'oriented-source-pixels';
+    };
+    stages: DecisionMetadata[];
+    durationMs: number;
+    knownCostUsd: number;
+    unknownCostCount: number;
+}
+export type LocalizationResult = ({
+    status: 'located';
+    region: PixelRect;
+    normalizedRegion: PixelRect;
+    selection: ChoiceSelection;
+    method: 'three-choice-grid-v1';
+    refinement?: RefinementResult;
+} | {
+    status: 'not-found';
+    reason: 'absent-in-evaluated-region';
+} | {
+    status: 'unknown';
+    reason: 'uncertain-presence' | 'candidate-union-empty' | 'contradictory-evidence' | 'layout-limit';
+}) & {
+    metadata: LocalizationMetadata;
+};
+export type RefinementResult = {
+    status: 'refined';
+    region: PixelRect;
+    method: string;
+} | {
+    status: 'unknown';
+    reason: string;
+};
+export interface RefinementPort {
+    refine(input: {
+        image: Uint8Array;
+        target: string;
+        region: PixelRect;
+        signal: AbortSignal;
+    }): Promise<RefinementResult>;
+}
+export declare function parse<T>(schema: z.ZodType<T, z.ZodTypeDef, unknown>, value: unknown, code?: 'INVALID_INPUT' | 'INVALID_RESPONSE'): T;
+export interface RasterImage {
+    bytes: Uint8Array;
+    width: number;
+    height: number;
+}
+export interface RasterPort {
+    normalize(bytes: Uint8Array, signal: AbortSignal): Promise<RasterImage>;
+    crop(image: RasterImage, region: PixelRect, signal: AbortSignal, scale?: number): Promise<RasterImage>;
+    imageState(image: RasterImage, signal: AbortSignal): Promise<DecisionState>;
+    grid(image: RasterImage, region: PixelRect, cells: readonly GridCell[], labels: ReadonlyMap<string, string>, signal: AbortSignal): Promise<RasterImage>;
+}
+export {};

package/dist/entities/contracts.js

@@ -0,0 +1,97 @@
+import { z } from 'zod';
+import { ClassifierError } from './errors.js';
+export const limits = Object.freeze({
+    imageBytes: 16 * 1024 * 1024,
+    imagePixels: 16_777_216,
+    bodyBytes: 32 * 1024 * 1024,
+    maxClasses: 255,
+    maxImages: 9,
+});
+export const pixelRectSchema = z
+    .object({
+    left: z.number().int().nonnegative().safe(),
+    top: z.number().int().nonnegative().safe(),
+    width: z.number().int().positive().max(16384),
+    height: z.number().int().positive().max(16384),
+})
+    .strict();
+export const classSchema = z
+    .object({
+    id: z
+        .string()
+        .min(1)
+        .max(128)
+        .regex(/^[a-zA-Z][a-zA-Z0-9_-]*$/),
+    description: z.string().trim().min(1).max(300),
+})
+    .strict();
+const imageSchema = z
+    .custom((value) => value instanceof Uint8Array)
+    .refine((v) => v.byteLength > 0 && v.byteLength <= limits.imageBytes, 'Expected 1..16MiB image bytes');
+export const representationSchema = z.discriminatedUnion('type', [
+    z.object({ type: z.literal('vision') }).strict(),
+    z.object({ type: z.literal('experimental-text'), profile: z.literal('text-image-v1') }).strict(),
+]);
+const mediaInputSchema = z
+    .object({ text: z.string().trim().min(1).max(32000).optional(), image: imageSchema.optional() })
+    .strict()
+    .refine((v) => v.text !== undefined || v.image !== undefined, 'Provide text or image');
+export const classifySchema = z
+    .object({
+    input: z.union([z.string().trim().min(1).max(32000), mediaInputSchema]),
+    classes: z
+        .array(classSchema)
+        .min(2)
+        .max(limits.maxClasses)
+        .refine((v) => new Set(v.map((c) => c.id)).size === v.length, 'Class IDs must be unique'),
+    instructions: z.string().trim().min(1).max(4000).optional(),
+    representation: representationSchema.optional(),
+})
+    .strict();
+export const locateSchema = z
+    .object({
+    image: imageSchema,
+    target: z.string().trim().min(1).max(2000),
+    exclusions: z.array(z.string().trim().min(1).max(500)).max(16).default([]),
+    roi: pixelRectSchema.optional(),
+    mode: z.literal('region').optional(),
+    representation: representationSchema.optional(),
+})
+    .strict();
+const choiceAnswerSchema = z.object({
+    type: z.literal('choice'),
+    choice: z.string(),
+    probabilities: z.record(z.number().finite().min(0).max(1)),
+    confidence: z.number().finite().min(0).max(1).optional(),
+    probabilityRoundingStep: z.literal(0.01).optional(),
+});
+const answersSchema = z.record(z.discriminatedUnion('type', [
+    choiceAnswerSchema,
+    z
+        .object({
+        type: z.literal('ranked-choice'),
+        ranking: z.array(z.string().min(1).max(128)).min(1).max(4),
+    })
+        .strict(),
+    z
+        .object({ type: z.literal('presence'), presence: z.enum(['present', 'absent', 'unknown']) })
+        .strict(),
+    z.object({ type: z.literal('noul'), noul: z.number().finite().min(0).max(1) }),
+]));
+const metadataSchema = z.object({
+    model: z.string().nullable(),
+    provider: z.string().nullable(),
+    requestId: z.string().nullable(),
+    durationMs: z.number().finite().nonnegative(),
+    costUsd: z.number().finite().nonnegative().nullable(),
+    attempts: z.number().int().positive(),
+});
+export const decisionResultSchema = z.object({ answers: answersSchema, metadata: metadataSchema });
+export function parse(schema, value, code = 'INVALID_INPUT') {
+    const result = schema.safeParse(value);
+    if (!result.success)
+        throw new ClassifierError(code, 'Schema validation failed', {
+            paths: result.error.issues.map((v) => v.path.join('.')),
+        });
+    return result.data;
+}

package/dist/entities/cutout-raster.d.ts

@@ -0,0 +1,7 @@
+import type { RasterImage } from './contracts.js';
+import type { RgbaRaster } from './representation.js';
+/** Pixel codec boundary owned by infrastructure; orchestration only sees canonical pixels. */
+export interface CutoutRasterPort {
+    rgba(image: RasterImage, signal: AbortSignal): Promise<RgbaRaster>;
+    png(image: RgbaRaster, signal: AbortSignal): Promise<Uint8Array>;
+}

package/dist/entities/cutout-raster.js

@@ -0,0 +1 @@
+export {};

package/dist/entities/errors.d.ts

@@ -0,0 +1,7 @@
+export type ErrorCode = 'INVALID_INPUT' | 'INVALID_RESPONSE' | 'TIMEOUT' | 'ABORTED' | 'CAPACITY' | 'DISPOSED' | 'PROVIDER' | 'AUTHENTICATION' | 'UNSUPPORTED' | 'RESOURCE_LIMIT';
+export declare class ClassifierError extends Error {
+    readonly code: ErrorCode;
+    readonly details: Readonly<Record<string, unknown>>;
+    constructor(code: ErrorCode, message: string, details?: Readonly<Record<string, unknown>>);
+}
+export declare function assertActive(signal: AbortSignal): void;

package/dist/entities/errors.js

@@ -0,0 +1,16 @@
+export class ClassifierError extends Error {
+    code;
+    details;
+    constructor(code, message, details = {}) {
+        super(message);
+        this.code = code;
+        this.details = details;
+        this.name = 'ClassifierError';
+    }
+}
+export function assertActive(signal) {
+    if (signal.aborted)
+        throw signal.reason instanceof ClassifierError
+            ? signal.reason
+            : new ClassifierError('ABORTED', 'Operation cancelled');
+}

package/dist/entities/object-proposals.d.ts

@@ -0,0 +1,53 @@
+import type { PixelRect } from './contracts.js';
+import type { RgbaRaster } from './representation.js';
+import type { SegmentationMetadata } from './segmentation-metadata.js';
+/** One-shot packed proposals avoid keeping native workers alive during model requests. */
+export declare const objectProposalLimits: Readonly<{
+    imagePixels: 2097152;
+    candidates: 36;
+    packedBytes: number;
+    presentationBytes: number;
+    presentationImages: 4;
+}>;
+/** Row-major, least-significant bit first; unused bits in the last byte must be zero. */
+export interface PackedBinaryMask {
+    data: Uint8Array;
+    width: number;
+    height: number;
+    format: 'binary-lsb0';
+}
+export interface ObjectProposal {
+    /** Stable input-order alias C00…C35, never a case ID or semantic annotation. */
+    id: string;
+    mask: PackedBinaryMask;
+    /** Uncalibrated native diagnostic only; never included in model requests. */
+    qualityScore?: number;
+}
+export interface ObjectProposalInput {
+    image: RgbaRaster;
+    seedRegion: PixelRect;
+    roi: PixelRect;
+    signal: AbortSignal;
+}
+export interface ObjectProposalBatch {
+    proposals: readonly ObjectProposal[];
+    metadata: SegmentationMetadata;
+}
+/** Caller-owned. propose settles only after physical work closes; no model calls here. */
+export interface ObjectProposalPort {
+    propose(input: ObjectProposalInput): Promise<ObjectProposalBatch>;
+    settle(): Promise<void>;
+    dispose(): Promise<void>;
+}
+/** Pixel-derived boxes are computed and validated by the process, never generated by a model. */
+export interface PresentedObjectProposal extends ObjectProposal {
+    region: PixelRect | null;
+}
+export interface ObjectProposalPresentationPort {
+    render(input: {
+        image: RgbaRaster;
+        seedRegion: PixelRect;
+        proposals: readonly PresentedObjectProposal[];
+        signal: AbortSignal;
+    }): Promise<readonly Uint8Array[]>;
+}

package/dist/entities/object-proposals.js

@@ -0,0 +1,8 @@
+/** One-shot packed proposals avoid keeping native workers alive during model requests. */
+export const objectProposalLimits = Object.freeze({
+    imagePixels: 2_097_152,
+    candidates: 36,
+    packedBytes: 10 * 1024 * 1024,
+    presentationBytes: 16 * 1024 * 1024,
+    presentationImages: 4,
+});