zorya-classifier 0.2.1 → 0.2.3

package/dist/app/create-classifier.js

@@ -1,77 +1,35 @@
-import { z } from 'zod';
 import { classifySchema, locateSchema, parse } from '../entities/contracts.js';
 import { ClassifierError } from '../entities/errors.js';
 import { createSharpRaster } from '../infrastructure/raster.js';
 import { classifyInput } from '../processes/classify.js';
 import { locateInput } from '../processes/locate.js';
-import { OperationGate } from '../shared/gate.js';
-import { OperationScope } from '../shared/scope.js';
-import { InputBudget } from '../shared/input-budget.js';
 import { wholeObjectSchema } from '../entities/whole-object.js';
-import { locateWholeObjectInput } from '../processes/whole-object.js';
-import { preparedTextSchema, representationLimits } from '../entities/representation.js';
 import { extractSchema } from '../entities/segmentation.js';
-import { extractObject } from '../processes/extract.js';
-import { extractFromRegion } from '../processes/extract-from-region.js';
 import { createSharpCutoutRaster } from '../infrastructure/segmentation/cutout-raster.js';
-import { locateFromProposals } from '../processes/proposal-location.js';
 import { createSharpObjectProposalPresentation } from '../infrastructure/segmentation/proposal-presentation.js';
 import { createSegmentationBoxCheck } from '../features/segmentation/box-check.js';
 import { createSharpSegmentationBoxPresentation } from '../infrastructure/segmentation/box-presentation.js';
-const configSchema = z.object({
-    timeoutMs: z.number().int().min(1).max(120000).default(45000),
-    concurrency: z.number().int().min(1).max(4).default(2),
-    maxQueue: z.number().int().min(0).max(32).default(16),
-    maxInputBytes: z
-        .number()
-        .int()
-        .min(1)
-        .max(256 * 1024 * 1024)
-        .default(64 * 1024 * 1024),
-});
-function signalOf(value) {
-    if (value === undefined)
-        return undefined;
-    if (!(value instanceof AbortSignal))
-        throw new ClassifierError('INVALID_INPUT', 'signal must be an AbortSignal');
-    return value;
+import { validateClassifierOptions } from './classifier-config.js';
+import { createClassifierRuntime, parseOperationSignal } from './classifier-runtime.js';
+import { createClassifierSpatial } from './classifier-spatial.js';
+function prepareResearchOperationInput(rest, research) {
+    if (!research || rest.representation === undefined)
+        return { rest, port: undefined };
+    if (!research.acceptsRepresentation(rest.representation))
+        return { rest, port: undefined };
+    return {
+        rest: { ...rest, representation: { type: 'vision' } },
+        port: research.representationPort,
+    };
 }
 export function createClassifier(options) {
     return composeClassifier(options);
 }
-/** Internal benchmark composition. No research codec is exported by the npm entry points. */
-export function createResearchClassifier(options, experimental, boundaryView, intervalPolicy) {
-    return composeClassifier(options, experimental, boundaryView, intervalPolicy);
-}
-function composeClassifier(options, experimental, boundaryView, intervalPolicy) {
-    if (!options || typeof options.decision?.decide !== 'function')
-        throw new ClassifierError('INVALID_INPUT', 'A DecisionPort is required');
-    const segmenter = options.segmentation;
-    const objectProposals = options.objectProposals;
-    if (segmenter !== undefined &&
-        (!segmenter ||
-            typeof segmenter.segment !== 'function' ||
-            (segmenter.expand !== undefined && typeof segmenter.expand !== 'function') ||
-            typeof segmenter.settle !== 'function' ||
-            typeof segmenter.dispose !== 'function'))
-        throw new ClassifierError('INVALID_INPUT', 'segmentation must implement SegmentationPort');
-    if (options.segmentationBoxCheck !== undefined &&
-        (!options.segmentationBoxCheck || typeof options.segmentationBoxCheck.check !== 'function'))
-        throw new ClassifierError('INVALID_INPUT', 'segmentationBoxCheck must implement its check port');
-    if (objectProposals !== undefined &&
-        (!objectProposals ||
-            typeof objectProposals.propose !== 'function' ||
-            typeof objectProposals.settle !== 'function' ||
-            typeof objectProposals.dispose !== 'function'))
-        throw new ClassifierError('INVALID_INPUT', 'objectProposals must implement ObjectProposalPort');
-    const config = parse(configSchema, {
-        timeoutMs: options.timeoutMs,
-        concurrency: options.concurrency,
-        maxQueue: options.maxQueue,
-        maxInputBytes: options.maxInputBytes,
-    });
-    const gate = new OperationGate(config.concurrency, config.maxQueue);
-    const inputBudget = new InputBudget(config.maxInputBytes);
+/** Internal composition seam for benchmark helpers; not re-exported from public entry points. */
+export function composeClassifier(options, research, boundaryView, intervalPolicy) {
+    const { config, ports } = validateClassifierOptions(options);
+    const { segmenter, objectProposals } = ports;
+    const runtime = createClassifierRuntime(config);
     const raster = createSharpRaster();
     const cutoutRaster = createSharpCutoutRaster();
     const boxCheck = segmenter
@@ -91,146 +49,46 @@ function composeClassifier(options, experimental, boundaryView, intervalPolicy)
             presentation: createSharpObjectProposalPresentation(),
         }
         : undefined;
-    const owned = new Map();
-    let disposed = false;
-    const textRepresentation = experimental
-        ? {
-            async prepare(input) {
-                const result = parse(preparedTextSchema, await experimental.prepare(input), 'INVALID_RESPONSE');
-                const bytes = result.state.reduce((sum, part) => sum + Buffer.byteLength(part, 'utf8'), 0);
-                if (bytes > representationLimits.totalBytes || bytes !== result.metadata.bytes)
-                    throw new ClassifierError('INVALID_RESPONSE', 'Representation byte accounting is inconsistent');
-                return {
-                    state: result.state,
-                    metadata: {
-                        ...result.metadata,
-                        views: result.metadata.views.map(({ content, ...view }) => ({
-                            ...view,
-                            ...(content === undefined ? {} : { content }),
-                        })),
-                    },
-                };
-            },
-        }
-        : undefined;
-    function representationFor(value) {
-        if (value?.type !== 'experimental-text')
-            return undefined;
-        if (!textRepresentation)
-            throw new ClassifierError('UNSUPPORTED', 'No text-image profile has passed release qualification yet');
-        return textRepresentation;
-    }
-    async function locateWhole(input, signal, representation) {
-        if (segmenter) {
-            const result = await extractRegion(input, signal, representation);
-            if (result.status === 'extracted')
-                return result.location;
-            if (result.status === 'unknown' && result.reason === 'segmentation-uncertain')
-                return {
-                    status: 'unknown',
-                    reason: 'segmentation-uncertain',
-                    metadata: 'metadata' in result ? result.metadata : result.location.metadata,
-                    ...(result.verification ? { verification: result.verification } : {}),
-                };
-            return result;
-        }
-        if (proposalDependencies) {
-            if (representation)
-                throw new ClassifierError('UNSUPPORTED', 'Mask proposal selection requires vision input');
-            return (await locateFromProposals(input, proposalDependencies, signal)).location;
-        }
-        return locateWholeObjectInput(input, options.decision, raster, signal, representation, boundaryView, intervalPolicy);
-    }
-    function extractRegion(input, signal, representation) {
-        if (!segmenter || !boxCheck)
-            throw new ClassifierError('UNSUPPORTED', 'Region extraction requires a SegmentationPort');
-        if (representation)
-            throw new ClassifierError('UNSUPPORTED', 'Checked segmentation requires vision input');
-        return extractFromRegion({ ...input, signal }, {
-            raster,
-            image: cutoutRaster,
-            segmenter,
-            boxCheck,
-            locateRegion: (source, { signal: operationSignal, ...request }) => locateInput({ ...request, image: source.bytes }, options.decision, raster, operationSignal, undefined, representation),
-        });
-    }
-    async function run(signal, task) {
-        if (disposed)
-            throw new ClassifierError('DISPOSED', 'Classifier has been disposed');
-        const scope = new OperationScope(config.timeoutMs, signal);
-        const job = (async () => {
-            let acquired = false;
-            try {
-                await gate.acquire(scope.signal);
-                acquired = true;
-                scope.guard();
-                const result = await task(scope.signal);
-                scope.guard();
-                return result;
-            }
-            catch (error) {
-                scope.guard();
-                throw error;
-            }
-            finally {
-                if (acquired)
-                    gate.release();
-                scope.dispose();
-                owned.delete(scope);
-            }
-        })();
-        owned.set(scope, job);
-        return job;
-    }
+    const spatial = createClassifierSpatial({
+        getDecision: () => options.decision,
+        raster,
+        cutoutRaster,
+        segmenter,
+        boxCheck,
+        proposalDependencies,
+        boundaryView,
+        intervalPolicy,
+    });
     async function locate(input) {
-        if (disposed)
-            throw new ClassifierError('DISPOSED', 'Classifier has been disposed');
-        gate.assertAvailable();
+        runtime.assertAcceptingOperations();
         if (!input || typeof input !== 'object')
             throw new ClassifierError('INVALID_INPUT', 'Expected locate input object');
         const { signal, ...rest } = input;
-        const parent = signalOf(signal);
-        if (rest.mode === 'whole-object') {
-            const parsed = parse(wholeObjectSchema, rest);
-            const representation = representationFor(parsed.representation);
-            const release = inputBudget.reserve(parsed.image.byteLength);
-            try {
-                const snapshot = { ...parsed, image: new Uint8Array(parsed.image) };
-                return await run(parent, (s) => locateWhole(snapshot, s, representation));
-            }
-            finally {
-                release();
-            }
-        }
-        const parsed = parse(locateSchema, rest);
-        const representation = representationFor(parsed.representation);
-        const release = inputBudget.reserve(parsed.image.byteLength);
-        try {
-            const snapshot = { ...parsed, image: new Uint8Array(parsed.image) };
-            return await run(parent, (s) => locateInput(snapshot, options.decision, raster, s, options.refinement, representation));
-        }
-        finally {
-            release();
+        const parent = parseOperationSignal(signal);
+        const { rest: rewritten, port } = prepareResearchOperationInput(rest, research);
+        if (rewritten.mode === 'whole-object') {
+            const parsed = parse(wholeObjectSchema, rewritten);
+            return runtime.withOwnedInput(parsed.image.byteLength, parent, () => ({ ...parsed, image: new Uint8Array(parsed.image) }), (snapshot, s) => spatial.locateWhole(snapshot, s, port));
         }
+        const parsed = parse(locateSchema, rewritten);
+        return runtime.withOwnedInput(parsed.image.byteLength, parent, () => ({ ...parsed, image: new Uint8Array(parsed.image) }), (snapshot, s) => locateInput(snapshot, options.decision, raster, s, options.refinement, port));
     }
     return {
         async classify(input) {
-            if (disposed)
-                throw new ClassifierError('DISPOSED', 'Classifier has been disposed');
-            gate.assertAvailable();
+            runtime.assertAcceptingOperations();
             if (!input || typeof input !== 'object')
                 throw new ClassifierError('INVALID_INPUT', 'Expected classify input object');
             const { signal, ...rest } = input;
-            const parent = signalOf(signal);
-            const parsed = parse(classifySchema, rest);
+            const parent = parseOperationSignal(signal);
+            const { rest: rewritten, port } = prepareResearchOperationInput(rest, research);
+            const parsed = parse(classifySchema, rewritten);
             const hasImage = typeof parsed.input !== 'string' && parsed.input.image !== undefined;
-            const representation = hasImage ? representationFor(parsed.representation) : undefined;
+            const representation = hasImage ? port : undefined;
             const byteCount = typeof parsed.input === 'string'
                 ? Buffer.byteLength(parsed.input)
                 : (parsed.input.image?.byteLength ?? 0) + Buffer.byteLength(parsed.input.text ?? '');
-            const release = inputBudget.reserve(byteCount);
-            try {
-                const media = typeof parsed.input === 'string'
+            return runtime.withOwnedInput(byteCount, parent, () => {
+                return typeof parsed.input === 'string'
                     ? parsed.input
                     : {
                         ...parsed.input,
@@ -238,75 +96,25 @@ function composeClassifier(options, experimental, boundaryView, intervalPolicy)
                             ? {}
                             : { image: new Uint8Array(parsed.input.image) }),
                     };
-                return await run(parent, (s) => classifyInput({ ...parsed, input: media }, options.decision, raster, s, representation));
-            }
-            finally {
-                release();
-            }
+            }, (media, s) => classifyInput({ ...parsed, input: media }, options.decision, raster, s, representation));
         },
         locate,
         async extract(input) {
-            if (disposed)
-                throw new ClassifierError('DISPOSED', 'Classifier has been disposed');
-            gate.assertAvailable();
+            runtime.assertAcceptingOperations();
             if (!input || typeof input !== 'object')
                 throw new ClassifierError('INVALID_INPUT', 'Expected extract input object');
             const { signal, ...rest } = input;
-            const parent = signalOf(signal);
-            const parsed = parse(extractSchema, rest);
+            const parent = parseOperationSignal(signal);
+            const { rest: rewritten, port } = prepareResearchOperationInput(rest, research);
+            const parsed = parse(extractSchema, rewritten);
             if (!segmenter && !proposalDependencies)
                 throw new ClassifierError('UNSUPPORTED', 'extract requires an explicit SegmentationPort or ObjectProposalPort');
-            const representation = representationFor(parsed.representation);
-            const release = inputBudget.reserve(parsed.image.byteLength);
-            try {
-                const snapshot = { ...parsed, image: new Uint8Array(parsed.image) };
-                return await run(parent, (s) => {
-                    if (segmenter)
-                        return extractRegion(snapshot, s, representation);
-                    let prepared;
-                    // Per-operation ownership: no global selected-mask cache or second native inference.
-                    const selectedMask = {
-                        async segment() {
-                            if (!prepared?.mask || !prepared.segmentation)
-                                throw new ClassifierError('INVALID_RESPONSE', 'Proposal selection omitted its mask');
-                            return {
-                                status: 'segmented',
-                                mask: prepared.mask,
-                                metadata: prepared.segmentation,
-                            };
-                        },
-                        async settle() { },
-                        async dispose() { },
-                    };
-                    return extractObject({ ...snapshot, mode: 'whole-object', signal: s }, {
-                        raster,
-                        image: cutoutRaster,
-                        segmenter: selectedMask,
-                        locateWhole: async (source, { signal: requestSignal, ...request }) => {
-                            const wholeInput = {
-                                ...request,
-                                mode: 'whole-object',
-                                image: source.bytes,
-                            };
-                            if (!proposalDependencies)
-                                throw new ClassifierError('UNSUPPORTED', 'ObjectProposalPort is required');
-                            if (representation)
-                                throw new ClassifierError('UNSUPPORTED', 'Mask proposal selection requires vision input');
-                            prepared = await locateFromProposals(wholeInput, proposalDependencies, requestSignal);
-                            return prepared.location;
-                        },
-                    });
-                });
-            }
-            finally {
-                release();
-            }
-        },
-        async dispose() {
-            disposed = true;
-            for (const scope of owned.keys())
-                scope.abort();
-            await Promise.allSettled(owned.values());
+            return runtime.withOwnedInput(parsed.image.byteLength, parent, () => ({ ...parsed, image: new Uint8Array(parsed.image) }), (snapshot, s) => {
+                if (segmenter)
+                    return spatial.extractRegion(snapshot, s, port);
+                return spatial.extractWithProposals(snapshot, s, port);
+            });
         },
+        dispose: () => runtime.dispose(),
     };
 }

package/dist/cli.js

@@ -8,7 +8,7 @@ import { createMobileSamSegmenter, createGrabCutSegmenter } from './segmentation
 async function main() {
     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.');
+        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]  (spatial search; grid cells are not whole-object boxes)\nzorya-classifier extract <image> <target> --output <prefix> --backend mobile-sam --encoder <path> --decoder <path> [--provider cpu|dml]  (extraction with caller-owned backend)\nzorya-classifier extract <image> <target> --output <prefix> --backend grabcut --opencv <path>  (extraction with caller-owned backend)\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 available—model, provider and native assets remain caller-supplied. 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;
     }
     const { command, value, target } = args;

package/dist/entities/classification.d.ts

@@ -0,0 +1,83 @@
+import { z } from 'zod';
+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 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.ZodObject<{
+        type: z.ZodLiteral<"vision">;
+    }, "strict", z.ZodTypeAny, {
+        type: "vision";
+    }, {
+        type: "vision";
+    }>>;
+}, "strict", z.ZodTypeAny, {
+    input: string | {
+        text?: string | undefined;
+        image?: Uint8Array<ArrayBufferLike> | undefined;
+    };
+    classes: {
+        id: string;
+        description: string;
+    }[];
+    instructions?: string | undefined;
+    representation?: {
+        type: "vision";
+    } | undefined;
+}, {
+    input: string | {
+        text?: string | undefined;
+        image?: Uint8Array<ArrayBufferLike> | undefined;
+    };
+    classes: {
+        id: string;
+        description: string;
+    }[];
+    instructions?: string | undefined;
+    representation?: {
+        type: "vision";
+    } | undefined;
+}>;
+export type ClassifyInput = z.input<typeof classifySchema> & {
+    signal?: AbortSignal;
+};

package/dist/entities/classification.js

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