zorya-classifier 0.2.1 → 0.2.3

package/dist/entities/decision.d.ts

@@ -0,0 +1,211 @@
+import { z } from 'zod';
+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, {
+    choice: string;
+    type: "choice";
+    probabilities: Record<string, number>;
+    confidence?: number | undefined;
+    probabilityRoundingStep?: 0.01 | undefined;
+}, {
+    choice: string;
+    type: "choice";
+    probabilities: Record<string, number>;
+    confidence?: number | undefined;
+    probabilityRoundingStep?: 0.01 | undefined;
+}>;
+export type ChoiceAnswer = z.infer<typeof choiceAnswerSchema>;
+export declare const decisionMetadataSchema: 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;
+}>;
+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, {
+        choice: string;
+        type: "choice";
+        probabilities: Record<string, number>;
+        confidence?: number | undefined;
+        probabilityRoundingStep?: 0.01 | undefined;
+    }, {
+        choice: string;
+        type: "choice";
+        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, {
+        noul: number;
+        type: "noul";
+    }, {
+        noul: number;
+        type: "noul";
+    }>]>>;
+    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, {
+        choice: string;
+        type: "choice";
+        probabilities: Record<string, number>;
+        confidence?: number | undefined;
+        probabilityRoundingStep?: 0.01 | undefined;
+    } | {
+        type: "ranked-choice";
+        ranking: string[];
+    } | {
+        type: "presence";
+        presence: "unknown" | "present" | "absent";
+    } | {
+        noul: number;
+        type: "noul";
+    }>;
+    metadata: {
+        model: string | null;
+        provider: string | null;
+        requestId: string | null;
+        durationMs: number;
+        costUsd: number | null;
+        attempts: number;
+    };
+}, {
+    answers: Record<string, {
+        choice: string;
+        type: "choice";
+        probabilities: Record<string, number>;
+        confidence?: number | undefined;
+        probabilityRoundingStep?: 0.01 | undefined;
+    } | {
+        type: "ranked-choice";
+        ranking: string[];
+    } | {
+        type: "presence";
+        presence: "unknown" | "present" | "absent";
+    } | {
+        noul: number;
+        type: "noul";
+    }>;
+    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 {};

package/dist/entities/decision.js

@@ -0,0 +1,33 @@
+import { z } from 'zod';
+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) }),
+]));
+export const decisionMetadataSchema = 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: decisionMetadataSchema,
+});

package/dist/entities/geometry.d.ts

@@ -0,0 +1,37 @@
+import { z } from 'zod';
+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[];
+}
+/** Containment with zero inner width/height allowed when endpoints fit inside outer. */
+export declare function containsRect(outer: PixelRect, inner: PixelRect): boolean;
+/** Containment requiring strictly positive inner width and height. */
+export declare function containsNonEmptyRect(outer: PixelRect, inner: PixelRect): boolean;
+export declare function intersectsRect(first: PixelRect, second: PixelRect): boolean;

package/dist/entities/geometry.js

@@ -0,0 +1,26 @@
+import { z } from 'zod';
+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();
+/** Containment with zero inner width/height allowed when endpoints fit inside outer. */
+export function containsRect(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);
+}
+/** Containment requiring strictly positive inner width and height. */
+export function containsNonEmptyRect(outer, inner) {
+    return inner.width > 0 && inner.height > 0 && containsRect(outer, inner);
+}
+export function intersectsRect(first, second) {
+    return (first.left < second.left + second.width &&
+        second.left < first.left + first.width &&
+        first.top < second.top + second.height &&
+        second.top < first.top + first.height);
+}

package/dist/entities/image.d.ts

@@ -0,0 +1,30 @@
+import { z } from 'zod';
+import type { DecisionState } from './decision.js';
+import type { GridCell, PixelRect } from './geometry.js';
+export declare const limits: Readonly<{
+    imageBytes: number;
+    imagePixels: 16777216;
+    bodyBytes: number;
+    maxClasses: 255;
+    maxImages: 9;
+}>;
+export declare const imageSchema: z.ZodEffects<z.ZodType<Uint8Array<ArrayBufferLike>, z.ZodTypeDef, Uint8Array<ArrayBufferLike>>, Uint8Array<ArrayBufferLike>, Uint8Array<ArrayBufferLike>>;
+export declare const representationSchema: z.ZodObject<{
+    type: z.ZodLiteral<"vision">;
+}, "strict", z.ZodTypeAny, {
+    type: "vision";
+}, {
+    type: "vision";
+}>;
+export type Representation = z.infer<typeof representationSchema>;
+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>;
+}

package/dist/entities/image.js

@@ -0,0 +1,12 @@
+import { z } from 'zod';
+export const limits = Object.freeze({
+    imageBytes: 16 * 1024 * 1024,
+    imagePixels: 16_777_216,
+    bodyBytes: 32 * 1024 * 1024,
+    maxClasses: 255,
+    maxImages: 9,
+});
+export 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.object({ type: z.literal('vision') }).strict();

package/dist/entities/localization.d.ts

@@ -0,0 +1,110 @@
+import { z } from 'zod';
+import type { ChoiceSelection, DecisionMetadata } from './decision.js';
+import { type PixelRect } from './geometry.js';
+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.ZodObject<{
+        type: z.ZodLiteral<"vision">;
+    }, "strict", z.ZodTypeAny, {
+        type: "vision";
+    }, {
+        type: "vision";
+    }>>;
+}, "strict", z.ZodTypeAny, {
+    image: Uint8Array<ArrayBufferLike>;
+    target: string;
+    exclusions: string[];
+    representation?: {
+        type: "vision";
+    } | undefined;
+    roi?: {
+        left: number;
+        top: number;
+        width: number;
+        height: number;
+    } | undefined;
+    mode?: "region" | undefined;
+}, {
+    image: Uint8Array<ArrayBufferLike>;
+    target: string;
+    representation?: {
+        type: "vision";
+    } | undefined;
+    exclusions?: string[] | undefined;
+    roi?: {
+        left: number;
+        top: number;
+        width: number;
+        height: number;
+    } | undefined;
+    mode?: "region" | undefined;
+}>;
+/** Coarse region search; a located grid cell is a hypothesis, not reliable whole-object geometry or proof of absence. */
+export type LocateInput = z.input<typeof locateSchema> & {
+    signal?: AbortSignal;
+};
+export interface LocalizationMetadata {
+    image: {
+        width: number;
+        height: number;
+        coordinateSpace: 'oriented-source-pixels';
+    };
+    stages: DecisionMetadata[];
+    durationMs: number;
+    knownCostUsd: number;
+    unknownCostCount: number;
+}
+/** Outcome of spatial localization; grid regions are not semantic object boxes or masks. */
+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;
+};
+/** Optional legacy region refinement. */
+export type RefinementResult = {
+    status: 'refined';
+    region: PixelRect;
+    method: string;
+} | {
+    status: 'unknown';
+    reason: string;
+};
+/** Caller-owned refinement hook. */
+export interface RefinementPort {
+    refine(input: {
+        image: Uint8Array;
+        target: string;
+        region: PixelRect;
+        signal: AbortSignal;
+    }): Promise<RefinementResult>;
+}

package/dist/entities/localization.js

@@ -0,0 +1,13 @@
+import { z } from 'zod';
+import { pixelRectSchema } from './geometry.js';
+import { imageSchema, representationSchema } from './image.js';
+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();

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

@@ -35,7 +35,7 @@ export interface ObjectProposalBatch {
 }
 /**
  * Caller-owned. propose settles only after physical work closes; no model calls here.
- * @experimental Mask proposal strategy with no general quality qualification.
+ * Mask proposal strategy; no general quality qualification is implied.
  */
 export interface ObjectProposalPort {
     propose(input: ObjectProposalInput): Promise<ObjectProposalBatch>;

package/dist/entities/representation.d.ts

@@ -1,5 +1,4 @@
 import type { DecisionState, GridCell, PixelRect, RasterImage } from './contracts.js';
-import { z } from 'zod';
 /** Canonical oriented RGBA8. Alpha remains meaningful; transparent is not black. */
 export interface RgbaRaster {
     data: Uint8Array;
@@ -41,185 +40,3 @@ export interface ImageRepresentationPort {
         metadata: RepresentationMetadata;
     }>;
 }
-export declare const representationLimits: Readonly<{
-    totalBytes: number;
-    partCharacters: 64000;
-    maxSide: 64;
-    maxViews: 9;
-}>;
-export declare const preparedTextSchema: z.ZodObject<{
-    state: z.ZodArray<z.ZodString, "many">;
-    metadata: z.ZodObject<{
-        profile: z.ZodString;
-        bytes: z.ZodNumber;
-        views: z.ZodArray<z.ZodObject<{
-            id: z.ZodString;
-            sourceRegion: 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;
-            }>;
-            width: z.ZodNumber;
-            height: z.ZodNumber;
-            scaleX: z.ZodNumber;
-            scaleY: z.ZodNumber;
-            content: 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;
-            }>>;
-        }, "strict", z.ZodTypeAny, {
-            width: number;
-            height: number;
-            id: string;
-            sourceRegion: {
-                left: number;
-                top: number;
-                width: number;
-                height: number;
-            };
-            scaleX: number;
-            scaleY: number;
-            content?: {
-                left: number;
-                top: number;
-                width: number;
-                height: number;
-            } | undefined;
-        }, {
-            width: number;
-            height: number;
-            id: string;
-            sourceRegion: {
-                left: number;
-                top: number;
-                width: number;
-                height: number;
-            };
-            scaleX: number;
-            scaleY: number;
-            content?: {
-                left: number;
-                top: number;
-                width: number;
-                height: number;
-            } | undefined;
-        }>, "many">;
-    }, "strict", z.ZodTypeAny, {
-        profile: string;
-        bytes: number;
-        views: {
-            width: number;
-            height: number;
-            id: string;
-            sourceRegion: {
-                left: number;
-                top: number;
-                width: number;
-                height: number;
-            };
-            scaleX: number;
-            scaleY: number;
-            content?: {
-                left: number;
-                top: number;
-                width: number;
-                height: number;
-            } | undefined;
-        }[];
-    }, {
-        profile: string;
-        bytes: number;
-        views: {
-            width: number;
-            height: number;
-            id: string;
-            sourceRegion: {
-                left: number;
-                top: number;
-                width: number;
-                height: number;
-            };
-            scaleX: number;
-            scaleY: number;
-            content?: {
-                left: number;
-                top: number;
-                width: number;
-                height: number;
-            } | undefined;
-        }[];
-    }>;
-}, "strict", z.ZodTypeAny, {
-    metadata: {
-        profile: string;
-        bytes: number;
-        views: {
-            width: number;
-            height: number;
-            id: string;
-            sourceRegion: {
-                left: number;
-                top: number;
-                width: number;
-                height: number;
-            };
-            scaleX: number;
-            scaleY: number;
-            content?: {
-                left: number;
-                top: number;
-                width: number;
-                height: number;
-            } | undefined;
-        }[];
-    };
-    state: string[];
-}, {
-    metadata: {
-        profile: string;
-        bytes: number;
-        views: {
-            width: number;
-            height: number;
-            id: string;
-            sourceRegion: {
-                left: number;
-                top: number;
-                width: number;
-                height: number;
-            };
-            scaleX: number;
-            scaleY: number;
-            content?: {
-                left: number;
-                top: number;
-                width: number;
-                height: number;
-            } | undefined;
-        }[];
-    };
-    state: string[];
-}>;