zorya-classifier 0.2.0 → 0.2.2

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,39 @@
+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.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 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,15 @@
+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.discriminatedUnion('type', [
+    z.object({ type: z.literal('vision') }).strict(),
+    z.object({ type: z.literal('experimental-text'), profile: z.literal('text-image-v1') }).strict(),
+]);

package/dist/entities/localization.d.ts

@@ -0,0 +1,125 @@
+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.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;
+}>;
+/** @experimental Unqualified 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;
+}
+/** @experimental Outcome of unqualified 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;
+};
+/** @experimental Optional legacy region refinement with no general quality qualification. */
+export type RefinementResult = {
+    status: 'refined';
+    region: PixelRect;
+    method: string;
+} | {
+    status: 'unknown';
+    reason: string;
+};
+/** @experimental Caller-owned refinement hook; unqualified for general spatial accuracy. */
+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

@@ -33,7 +33,10 @@ export interface ObjectProposalBatch {
     proposals: readonly ObjectProposal[];
     metadata: SegmentationMetadata;
 }
-/** Caller-owned. propose settles only after physical work closes; no model calls here. */
+/**
+ * Caller-owned. propose settles only after physical work closes; no model calls here.
+ * @experimental Mask proposal strategy with no general quality qualification.
+ */
 export interface ObjectProposalPort {
     propose(input: ObjectProposalInput): Promise<ObjectProposalBatch>;
     settle(): Promise<void>;

package/dist/entities/segmentation-metadata.d.ts

@@ -1,3 +1,4 @@
+import { z } from 'zod';
 /** Diagnostic native scores are uncalibrated finite values, not probabilities. */
 export interface SegmentationMetadata {
     method: string;
@@ -9,3 +10,72 @@ export interface SegmentationMetadata {
     };
     qualityScore?: number;
 }
+export declare const segmentationMetadataSchema: z.ZodObject<{
+    method: z.ZodString;
+    backend: z.ZodString;
+    durationMs: z.ZodNumber;
+    input: z.ZodObject<{
+        width: z.ZodNumber;
+        height: z.ZodNumber;
+    }, "strict", z.ZodTypeAny, {
+        width: number;
+        height: number;
+    }, {
+        width: number;
+        height: number;
+    }>;
+    qualityScore: z.ZodOptional<z.ZodNumber>;
+}, "strict", z.ZodTypeAny, {
+    durationMs: number;
+    input: {
+        width: number;
+        height: number;
+    };
+    method: string;
+    backend: string;
+    qualityScore?: number | undefined;
+}, {
+    durationMs: number;
+    input: {
+        width: number;
+        height: number;
+    };
+    method: string;
+    backend: string;
+    qualityScore?: number | undefined;
+}>;
+export declare const segmentationMetadataSafeSchema: z.ZodObject<{
+    method: z.ZodString;
+    backend: z.ZodString;
+    durationMs: z.ZodNumber;
+    qualityScore: z.ZodOptional<z.ZodNumber>;
+} & {
+    input: z.ZodObject<{
+        width: z.ZodNumber;
+        height: z.ZodNumber;
+    }, "strict", z.ZodTypeAny, {
+        width: number;
+        height: number;
+    }, {
+        width: number;
+        height: number;
+    }>;
+}, "strict", z.ZodTypeAny, {
+    durationMs: number;
+    input: {
+        width: number;
+        height: number;
+    };
+    method: string;
+    backend: string;
+    qualityScore?: number | undefined;
+}, {
+    durationMs: number;
+    input: {
+        width: number;
+        height: number;
+    };
+    method: string;
+    backend: string;
+    qualityScore?: number | undefined;
+}>;

package/dist/entities/segmentation-metadata.js

@@ -1 +1,21 @@
-export {};
+import { z } from 'zod';
+const safePositiveDimensionSchema = z
+    .object({
+    width: z.number().int().positive().safe(),
+    height: z.number().int().positive().safe(),
+})
+    .strict();
+export const segmentationMetadataSchema = z
+    .object({
+    method: z.string().min(1).max(128),
+    backend: z.string().min(1).max(128),
+    durationMs: z.number().finite().nonnegative(),
+    input: z
+        .object({ width: z.number().int().positive(), height: z.number().int().positive() })
+        .strict(),
+    qualityScore: z.number().finite().optional(),
+})
+    .strict();
+export const segmentationMetadataSafeSchema = segmentationMetadataSchema
+    .extend({ input: safePositiveDimensionSchema })
+    .strict();

package/dist/entities/segmentation-verification.d.ts

@@ -16,6 +16,7 @@ export interface SegmentationBoxCheckResult {
     selection: ChoiceSelection;
     metadata: DecisionMetadata;
 }
+/** @experimental Closed box containment check; verdicts are unqualified for general spatial accuracy. */
 export interface SegmentationBoxCheckPort {
     check(input: SegmentationBoxCheckInput): Promise<SegmentationBoxCheckResult>;
 }

package/dist/entities/segmentation.d.ts

@@ -84,6 +84,7 @@ export declare const extractSchema: z.ZodObject<{
     boxTolerancePx?: number | undefined;
     maxExtentPasses?: number | undefined;
 }>;
+/** @experimental Region-seeded extraction input; unqualified for general object or mask accuracy. */
 export type ExtractInput = z.input<typeof extractSchema> & {
     signal?: AbortSignal;
 };
@@ -115,7 +116,10 @@ export type SegmentationResult = {
     reason: string;
     metadata: SegmentationMetadata;
 };
-/** Caller-owned. settle joins physical work; dispose closes this adapter only. */
+/**
+ * Caller-owned. settle joins physical work; dispose closes this adapter only.
+ * @experimental Caller-owned segmentation; structural validation does not establish semantic object or mask quality.
+ */
 export interface SegmentationPort {
     segment(input: SegmentationInput): Promise<SegmentationResult>;
     /** Optional actual enclosing mask on the full source; previousMask is full-source binary-u8. */
@@ -123,6 +127,7 @@ export interface SegmentationPort {
     settle(): Promise<void>;
     dispose(): Promise<void>;
 }
+/** @experimental Extraction outcome; `extracted` reflects validation, not guaranteed semantic correctness. */
 export type ExtractionResult = {
     status: 'extracted';
     location: WholeObjectLocated;

package/dist/entities/validation.d.ts

@@ -0,0 +1,2 @@
+import type { ZodType, ZodTypeDef } from 'zod';
+export declare function parse<T>(schema: ZodType<T, ZodTypeDef, unknown>, value: unknown, code?: 'INVALID_INPUT' | 'INVALID_RESPONSE'): T;

package/dist/entities/validation.js

@@ -0,0 +1,9 @@
+import { ClassifierError } from './errors.js';
+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;
+}