zorya-classifier 0.1.0 → 0.2.1

package/dist/cli.js

@@ -2,29 +2,73 @@
 import { readFile } from 'node:fs/promises';
 import { createClassifier } from './index.js';
 import { createCliDecision } from './app/cli-route.js';
+import { parseCliArguments } from './app/cli-arguments.js';
+import { writeExtractionFiles } from './app/extraction-files.js';
+import { createMobileSamSegmenter, createGrabCutSegmenter } from './segmentation.js';
 async function main() {
-    const [command, value, target] = process.argv.slice(2);
-    if (command === '--help' || !command) {
-        console.log('zorya-classifier classify-text <text> <classes.json>\nzorya-classifier classify-image <image> <classes.json>\nzorya-classifier locate <image> <target>\nSet ZORYA_MODEL. Default ZORYA_MODE=decisions; use chat for ordinary vision models/custom chat endpoints. OpenRouter: OPENROUTER_API_KEY + ZORYA_PROVIDER. Direct: ZORYA_ENDPOINT + optional ZORYA_API_KEY. Optional ZORYA_REASONING_EFFORT and ZORYA_RESPONSE_FORMAT. One classify request; up to three locate requests.');
+    const args = parseCliArguments(process.argv.slice(2));
+    if (args.command === 'help') {
+        console.log('zorya-classifier classify-text <text> <classes.json>\nzorya-classifier classify-image <image> <classes.json>\nzorya-classifier locate <image> <target> [--mode region|whole-object]  (experimental, unqualified spatial search)\nzorya-classifier extract <image> <target> --output <prefix> --backend mobile-sam --encoder <path> --decoder <path> [--provider cpu|dml]  (experimental extraction)\nzorya-classifier extract <image> <target> --output <prefix> --backend grabcut --opencv <path>  (experimental extraction)\nSet ZORYA_MODEL. Default ZORYA_MODE=decisions; use chat for ordinary vision models/custom chat endpoints. OpenRouter: OPENROUTER_API_KEY + ZORYA_PROVIDER. Direct: ZORYA_ENDPOINT + optional ZORYA_API_KEY. Optional ZORYA_REASONING_EFFORT and ZORYA_RESPONSE_FORMAT. classify is supported; locate/extract/object backends are experimental and not qualified for general use. One classify request; up to three region or six whole-object requests. Extraction additionally runs the explicit local backend. Output files are never overwritten; native assets are never downloaded automatically.');
         return;
     }
-    if (!['classify-text', 'classify-image', 'locate'].includes(command) || !value || !target)
-        throw new Error('Invalid arguments; use --help');
-    const client = createClassifier({ decision: createCliDecision(process.env) });
+    const { command, value, target } = args;
+    const decision = createCliDecision(process.env);
+    const controller = new AbortController();
+    const abort = () => controller.abort();
+    process.once('SIGINT', abort);
+    process.once('SIGTERM', abort);
+    let segmenter;
+    let client;
     try {
-        if (command === 'locate')
-            console.log(JSON.stringify(await client.locate({ image: await readFile(value), target }), null, 2));
-        else {
+        // Validate local data before creating a native worker or dispatching any model request.
+        const image = command === 'classify-text' ? undefined : await readFile(value);
+        let classes;
+        if (command === 'classify-text' || command === 'classify-image') {
             const { z } = await import('zod');
-            const { classSchema } = await import('./entities/contracts.js');
+            const { classSchema, limits } = await import('./entities/contracts.js');
             const unknownClasses = JSON.parse(await readFile(target, 'utf8'));
-            const classes = z.array(classSchema).parse(unknownClasses);
-            const input = command === 'classify-text' ? value : { image: await readFile(value) };
-            console.log(JSON.stringify(await client.classify({ input, classes }), null, 2));
+            classes = z.array(classSchema).min(2).max(limits.maxClasses).parse(unknownClasses);
+        }
+        controller.signal.throwIfAborted();
+        if (command === 'extract')
+            segmenter =
+                args.backend === 'mobile-sam'
+                    ? await createMobileSamSegmenter({
+                        encoderPath: args.encoder,
+                        decoderPath: args.decoder,
+                        executionProvider: args.provider ?? 'cpu',
+                    })
+                    : await createGrabCutSegmenter({ assetPath: args.opencv });
+        client = createClassifier({ decision, ...(segmenter ? { segmentation: segmenter } : {}) });
+        controller.signal.throwIfAborted();
+        if (command === 'locate') {
+            console.log(JSON.stringify(await client.locate({
+                image: image,
+                target,
+                ...(args.mode ? { mode: args.mode } : {}),
+                signal: controller.signal,
+            }), null, 2));
+        }
+        else if (command === 'extract') {
+            const result = await client.extract({ image: image, target, signal: controller.signal });
+            console.log(JSON.stringify(result.status === 'extracted'
+                ? { status: result.status, files: await writeExtractionFiles(args.output, result) }
+                : result, null, 2));
+        }
+        else {
+            const input = command === 'classify-text' ? value : { image: image };
+            console.log(JSON.stringify(await client.classify({ input, classes: classes, signal: controller.signal }), null, 2));
         }
     }
     finally {
-        await client.dispose();
+        process.removeListener('SIGINT', abort);
+        process.removeListener('SIGTERM', abort);
+        try {
+            await client?.dispose();
+        }
+        finally {
+            await segmenter?.dispose();
+        }
     }
 }
 main().catch((error) => {

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,7 +221,9 @@ export declare const locateSchema: z.ZodObject<{
         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;
 };
@@ -337,7 +414,7 @@ export interface ChoiceSelection {
 export interface ClassificationResult extends ChoiceSelection {
     metadata: DecisionMetadata;
 }
-interface LocalizationMetadata {
+export interface LocalizationMetadata {
     image: {
         width: number;
         height: number;
@@ -348,6 +425,7 @@ interface LocalizationMetadata {
     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;
@@ -364,6 +442,7 @@ export type LocalizationResult = ({
 }) & {
     metadata: LocalizationMetadata;
 };
+/** @experimental Optional legacy region refinement with no general quality qualification. */
 export type RefinementResult = {
     status: 'refined';
     region: PixelRect;
@@ -372,6 +451,7 @@ export type RefinementResult = {
     status: 'unknown';
     reason: string;
 };
+/** @experimental Caller-owned refinement hook; unqualified for general spatial accuracy. */
 export interface RefinementPort {
     refine(input: {
         image: Uint8Array;

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,56 @@
+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.
+ * @experimental Mask proposal strategy with no general quality qualification.
+ */
+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 {};