zorya-classifier 0.0.0-stage → 0.2.0

package/dist/app/create-classifier.js

@@ -0,0 +1,312 @@
+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;
+}
+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);
+    const raster = createSharpRaster();
+    const cutoutRaster = createSharpCutoutRaster();
+    const boxCheck = segmenter
+        ? (options.segmentationBoxCheck ??
+            createSegmentationBoxCheck({
+                decision: options.decision,
+                presentation: createSharpSegmentationBoxPresentation(),
+                imageState: raster.imageState,
+            }))
+        : undefined;
+    const proposalDependencies = objectProposals
+        ? {
+            decision: options.decision,
+            raster,
+            image: cutoutRaster,
+            proposals: objectProposals,
+            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;
+    }
+    async function locate(input) {
+        if (disposed)
+            throw new ClassifierError('DISPOSED', 'Classifier has been disposed');
+        gate.assertAvailable();
+        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();
+        }
+    }
+    return {
+        async classify(input) {
+            if (disposed)
+                throw new ClassifierError('DISPOSED', 'Classifier has been disposed');
+            gate.assertAvailable();
+            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 hasImage = typeof parsed.input !== 'string' && parsed.input.image !== undefined;
+            const representation = hasImage ? representationFor(parsed.representation) : 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'
+                    ? parsed.input
+                    : {
+                        ...parsed.input,
+                        ...(parsed.input.image === undefined
+                            ? {}
+                            : { image: new Uint8Array(parsed.input.image) }),
+                    };
+                return await run(parent, (s) => classifyInput({ ...parsed, input: media }, options.decision, raster, s, representation));
+            }
+            finally {
+                release();
+            }
+        },
+        locate,
+        async extract(input) {
+            if (disposed)
+                throw new ClassifierError('DISPOSED', 'Classifier has been disposed');
+            gate.assertAvailable();
+            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);
+            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());
+        },
+    };
+}

package/dist/app/extraction-files.d.ts

@@ -0,0 +1,9 @@
+import type { ExtractionResult } from '../entities/segmentation.js';
+/** Reserve every destination exclusively before writing; never overwrite an existing artifact. */
+export declare function writeExtractionFiles(prefix: string, result: Extract<ExtractionResult, {
+    status: 'extracted';
+}>): Promise<{
+    png: string;
+    mask: string;
+    descriptor: string;
+}>;

package/dist/app/extraction-files.js

@@ -0,0 +1,28 @@
+import { open, unlink } from 'node:fs/promises';
+/** Reserve every destination exclusively before writing; never overwrite an existing artifact. */
+export async function writeExtractionFiles(prefix, result) {
+    const files = { png: `${prefix}.png`, mask: `${prefix}.mask.u8`, descriptor: `${prefix}.json` };
+    const { png, mask, ...description } = result;
+    const descriptor = JSON.stringify({
+        ...description,
+        mask: { width: mask.width, height: mask.height, format: mask.format },
+        files,
+    }, null, 2);
+    const owned = [];
+    try {
+        for (const path of Object.values(files))
+            owned.push({ path, handle: await open(path, 'wx') });
+        for (const [index, bytes] of [png, mask.data, descriptor].entries())
+            await owned[index].handle.writeFile(bytes);
+        await Promise.all(owned.map(({ handle }) => handle.close()));
+        return files;
+    }
+    catch (error) {
+        const closed = await Promise.allSettled(owned.map(({ handle }) => handle.close()));
+        const removed = await Promise.allSettled(owned.map(({ path }) => unlink(path)));
+        const cleanupErrors = [...closed, ...removed].flatMap((outcome) => outcome.status === 'rejected' ? [outcome.reason] : []);
+        if (cleanupErrors.length)
+            throw new AggregateError([error, ...cleanupErrors], 'Extraction output and cleanup failed');
+        throw error;
+    }
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,77 @@
+#!/usr/bin/env node
+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 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]\nzorya-classifier extract <image> <target> --output <prefix> --backend mobile-sam --encoder <path> --decoder <path> [--provider cpu|dml]\nzorya-classifier extract <image> <target> --output <prefix> --backend grabcut --opencv <path>\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 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;
+    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 {
+        // 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, limits } = await import('./entities/contracts.js');
+            const unknownClasses = JSON.parse(await readFile(target, 'utf8'));
+            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 {
+        process.removeListener('SIGINT', abort);
+        process.removeListener('SIGTERM', abort);
+        try {
+            await client?.dispose();
+        }
+        finally {
+            await segmenter?.dispose();
+        }
+    }
+}
+main().catch((error) => {
+    console.error(error instanceof Error ? error.message : 'Command failed');
+    process.exitCode = 1;
+});

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 {};