zorya-classifier 0.1.0 → 0.2.0

package/dist/entities/boundary-view.d.ts

@@ -0,0 +1,29 @@
+import type { PixelRect, RasterImage } from './contracts.js';
+import type { BoundaryInterval } from './whole-object.js';
+export type BoundaryAxis = 'left' | 'right' | 'top' | 'bottom';
+export interface BoundaryCandidate {
+    /** Exact closed Choice key; display labels are mapped back to this ID by code. */
+    id: string;
+    display: string;
+    interval: BoundaryInterval;
+}
+export interface BoundaryViewInput {
+    source: RasterImage;
+    sourceRegion: PixelRect;
+    axis: BoundaryAxis;
+    candidates: readonly BoundaryCandidate[];
+    signal: AbortSignal;
+}
+export interface BoundaryView {
+    image: RasterImage;
+    sourceRegion: PixelRect;
+    /** Source pixels occupy this rectangle; rulers/gutters are outside it. */
+    content: PixelRect;
+    scaleX: number;
+    scaleY: number;
+    candidates: readonly BoundaryCandidate[];
+}
+/** Rendering only: never infers target facts or generates source coordinates. */
+export interface BoundaryViewPort {
+    render(input: BoundaryViewInput): Promise<BoundaryView>;
+}

package/dist/entities/boundary-view.js

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

package/dist/entities/contracts.d.ts

@@ -48,6 +48,23 @@ export declare const classSchema: z.ZodObject<{
     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>;
@@ -82,6 +99,22 @@ export declare const classifySchema: z.ZodObject<{
         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;
@@ -92,6 +125,12 @@ export declare const classifySchema: z.ZodObject<{
         description: string;
     }[];
     instructions?: string | undefined;
+    representation?: {
+        type: "vision";
+    } | {
+        type: "experimental-text";
+        profile: "text-image-v1";
+    } | undefined;
 }, {
     input: string | {
         text?: string | undefined;
@@ -102,6 +141,12 @@ export declare const classifySchema: z.ZodObject<{
         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;
@@ -126,19 +171,49 @@ export declare const locateSchema: z.ZodObject<{
         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;
@@ -146,6 +221,7 @@ export declare const locateSchema: z.ZodObject<{
         width: number;
         height: number;
     } | undefined;
+    mode?: "region" | undefined;
 }>;
 export type LocateInput = z.input<typeof locateSchema> & {
     signal?: AbortSignal;
@@ -337,7 +413,7 @@ export interface ChoiceSelection {
 export interface ClassificationResult extends ChoiceSelection {
     metadata: DecisionMetadata;
 }
-interface LocalizationMetadata {
+export interface LocalizationMetadata {
     image: {
         width: number;
         height: number;

package/dist/entities/contracts.js

@@ -28,6 +28,10 @@ export const classSchema = z
 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()
@@ -41,6 +45,7 @@ export const classifySchema = z
         .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
@@ -49,6 +54,8 @@ export const locateSchema = z
     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({

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/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,
+});

package/dist/entities/representation.d.ts

@@ -0,0 +1,225 @@
+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;
+    width: number;
+    height: number;
+    format: 'rgba8';
+}
+export interface RepresentationView {
+    id: string;
+    role: 'source' | 'crop' | 'grid';
+    image: RasterImage;
+    sourceRegion: PixelRect;
+    grid?: {
+        cells: readonly GridCell[];
+        labels: ReadonlyMap<string, string>;
+    };
+}
+export interface RepresentationMetadata {
+    profile: string;
+    bytes: number;
+    views: {
+        id: string;
+        sourceRegion: PixelRect;
+        width: number;
+        height: number;
+        scaleX: number;
+        scaleY: number;
+        content?: PixelRect;
+    }[];
+}
+/** Prepare once for the entire decision request, including all candidate views. */
+export interface ImageRepresentationPort {
+    prepare(input: {
+        source: RasterImage;
+        views: readonly RepresentationView[];
+        signal: AbortSignal;
+    }): Promise<{
+        state: DecisionState;
+        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[];
+}>;

package/dist/entities/representation.js

@@ -0,0 +1,33 @@
+import { pixelRectSchema } from './contracts.js';
+import { z } from 'zod';
+export const representationLimits = Object.freeze({
+    totalBytes: 64 * 1024,
+    partCharacters: 64000,
+    maxSide: 64,
+    maxViews: 9,
+});
+export const preparedTextSchema = z
+    .object({
+    state: z.array(z.string().min(1).max(representationLimits.partCharacters)).min(1).max(64),
+    metadata: z
+        .object({
+        profile: z.string().min(1).max(128),
+        bytes: z.number().int().nonnegative().max(representationLimits.totalBytes),
+        views: z
+            .array(z
+            .object({
+            id: z.string().min(1).max(256),
+            sourceRegion: pixelRectSchema,
+            width: z.number().int().positive().max(16384),
+            height: z.number().int().positive().max(16384),
+            scaleX: z.number().finite().positive(),
+            scaleY: z.number().finite().positive(),
+            content: pixelRectSchema.optional(),
+        })
+            .strict())
+            .min(1)
+            .max(representationLimits.maxViews),
+    })
+        .strict(),
+})
+    .strict();

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

@@ -0,0 +1,11 @@
+/** Diagnostic native scores are uncalibrated finite values, not probabilities. */
+export interface SegmentationMetadata {
+    method: string;
+    backend: string;
+    durationMs: number;
+    input: {
+        width: number;
+        height: number;
+    };
+    qualityScore?: number;
+}

package/dist/entities/segmentation-metadata.js

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

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

@@ -0,0 +1,30 @@
+import type { ChoiceSelection, DecisionMetadata, PixelRect, RasterImage } from './contracts.js';
+import type { RgbaRaster } from './representation.js';
+/** A containment check for the same visible instance identified by the original seed. */
+export interface SegmentationBoxCheckInput {
+    image: RgbaRaster;
+    region: PixelRect;
+    seedRegion: PixelRect;
+    roi: PixelRect;
+    target: string;
+    exclusions: readonly string[];
+    signal: AbortSignal;
+}
+export type SegmentationBoxVerdict = 'complete' | 'needs-expansion' | 'unknown';
+export interface SegmentationBoxCheckResult {
+    verdict: SegmentationBoxVerdict;
+    selection: ChoiceSelection;
+    metadata: DecisionMetadata;
+}
+export interface SegmentationBoxCheckPort {
+    check(input: SegmentationBoxCheckInput): Promise<SegmentationBoxCheckResult>;
+}
+/** Full oriented source with the actual mask box and a seed anchor; no generated geometry. */
+export interface SegmentationBoxPresentationPort {
+    render(input: SegmentationBoxCheckInput): Promise<RasterImage>;
+}
+/** Containment evidence is separate from the correctness of individual mask pixels. */
+export interface SegmentationVerification {
+    checks: SegmentationBoxCheckResult[];
+    expansion: 'not-needed' | 'unsupported' | 'no-enclosing-mask' | 'rejected-mask' | 'expanded';
+}

package/dist/entities/segmentation-verification.js

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