@stabrise/scaledp 0.1.0

package/dist/pipeline-DACqGkpN.js

@@ -0,0 +1,240 @@
+//#region src/core/config.ts
+const DEFAULTS = {
+	modelHost: "https://huggingface.co",
+	cache: "indexeddb",
+	cacheDbName: "scaledp-models",
+	executionProviders: ["wasm"],
+	numThreads: 0,
+	pdf: {},
+	tesseract: {},
+	hf: {}
+};
+let current = { ...DEFAULTS };
+/** Merge `patch` into the global config. Nested asset maps merge per key. */
+function configure(patch) {
+	current = {
+		...current,
+		...patch,
+		pdf: {
+			...current.pdf,
+			...patch.pdf
+		},
+		tesseract: {
+			...current.tesseract,
+			...patch.tesseract
+		},
+		hf: {
+			...current.hf,
+			...patch.hf
+		}
+	};
+	return current;
+}
+function getConfig() {
+	return current;
+}
+/** Restore defaults. Primarily for tests. */
+function resetConfig() {
+	current = {
+		...DEFAULTS,
+		pdf: {},
+		tesseract: {},
+		hf: {}
+	};
+}
+/**
+* Threads to request from onnxruntime-web.
+*
+* Leaves one core for the UI and caps at 4 -- past that, ORT's own
+* synchronisation overhead outweighs the gain on these model sizes.
+*/
+function defaultNumThreads() {
+	const cores = typeof navigator !== "undefined" && typeof navigator.hardwareConcurrency === "number" ? navigator.hardwareConcurrency : 4;
+	return Math.max(1, Math.min(4, cores - 1));
+}
+function resolveNumThreads() {
+	const configured = getConfig().numThreads;
+	return configured > 0 ? configured : defaultNumThreads();
+}
+//#endregion
+//#region src/core/errors.ts
+/**
+* ScaleDP stages never throw by default: a failure is captured into the output
+* schema's `exception` field so a pipeline always completes and partial results
+* survive. `propagateError: true` opts a stage into throwing instead.
+*/
+var ScaleDpError = class extends Error {
+	stage;
+	cause;
+	constructor(message, stage, cause) {
+		super(message);
+		this.stage = stage;
+		this.cause = cause;
+		this.name = "ScaleDpError";
+	}
+};
+var ImageError = class extends ScaleDpError {
+	name = "ImageError";
+};
+var OcrError = class extends ScaleDpError {
+	name = "OcrError";
+};
+var DetectionError = class extends ScaleDpError {
+	name = "DetectionError";
+};
+var NerError = class extends ScaleDpError {
+	name = "NerError";
+};
+var ConfigError = class extends ScaleDpError {
+	name = "ConfigError";
+};
+/** Render a caught value the way Python writes a traceback into `exception`. */
+function formatException(stage, error) {
+	if (error instanceof Error) return `${stage}: ${error.name}: ${error.message}${error.stack ? `\n${error.stack}` : ""}`;
+	return `${stage}: ${String(error)}`;
+}
+//#endregion
+//#region src/core/pipeline.ts
+/**
+* The pipeline runner, modelled on `scaledp/pipeline/PandasPipeline.py` rather
+* than on Spark.
+*
+* ScaleDP's Spark coupling is thin: every stage is a pure `Transformer` (there
+* are no Estimators, so no fit/transform duality) and the only DataFrame surface
+* stages use is withColumn / drop / select. That reduces to an array of plain
+* row objects, which is what this file implements.
+*/
+const EXECUTION_TIME_COL = "execution_time";
+const ROW_TIME_COL = "row_time";
+/**
+* Base class for every stage.
+*
+* Subclasses implement `apply`, which transforms a single row's input value.
+* The base handles column wiring, error capture and the `keepInputData`
+* contract, so those behave identically everywhere.
+*/
+var Stage = class {
+	params;
+	constructor(params) {
+		this.params = params;
+	}
+	/** Optional per-stage setup (model download, session creation). Called once. */
+	async init() {}
+	/** Release any held resources (ONNX sessions, workers). */
+	async dispose() {}
+	/**
+	* A stage may emit several rows per input row -- PDF page explosion, box
+	* cropping. Returning `null` means "use the single-row path".
+	*/
+	async expand(_input, _row, _ctx) {
+		return null;
+	}
+	async transform(rows, ctx) {
+		const { inputCol, outputCol, keepInputData, propagateError } = this.params;
+		const out = [];
+		for (const row of rows) {
+			ctx.signal?.throwIfAborted();
+			const input = row[inputCol];
+			let next;
+			const started = performance.now();
+			try {
+				next = await this.expand(input, row, ctx) ?? [{
+					...row,
+					[outputCol]: await this.apply(input, row, ctx)
+				}];
+			} catch (error) {
+				if (propagateError) throw error;
+				next = [{
+					...row,
+					[outputCol]: this.onError(formatException(this.name, error), row)
+				}];
+			}
+			const elapsed = performance.now() - started;
+			if (!keepInputData && inputCol !== outputCol) for (const r of next) delete r[inputCol];
+			for (const r of next) chargeRow(r, this.name, elapsed / next.length);
+			out.push(...next);
+		}
+		return out;
+	}
+};
+/**
+* Add a stage's cost to one row's running total.
+*
+* The row inherited its predecessor's timings by the spread that built it, so
+* the record is copied before writing -- sibling rows from one expand would
+* otherwise share it and every charge would land on all of them.
+*/
+function chargeRow(row, name, ms) {
+	const previous = row[ROW_TIME_COL];
+	const stages = { ...previous?.stages };
+	stages[name] = (stages[name] ?? 0) + ms;
+	row[ROW_TIME_COL] = {
+		stages,
+		total: (previous?.total ?? 0) + ms
+	};
+}
+var Pipeline = class {
+	stages;
+	constructor(stages) {
+		this.stages = stages;
+	}
+	/** Run every stage in order. Input is normalised into rows first. */
+	async transform(input, options = {}) {
+		let rows = await toRows(input);
+		const timings = {};
+		const started = performance.now();
+		for (const [index, stage] of this.stages.entries()) {
+			options.signal?.throwIfAborted();
+			const t0 = performance.now();
+			await stage.init();
+			rows = await stage.transform(rows, {
+				index,
+				signal: options.signal
+			});
+			const elapsed = performance.now() - t0;
+			const key = timings[stage.name] === void 0 ? stage.name : `${stage.name}#${index}`;
+			timings[key] = elapsed;
+			options.onStage?.(stage.name, elapsed, rows.length);
+		}
+		const executionTime = {
+			stages: timings,
+			total: performance.now() - started
+		};
+		return rows.map((row) => ({
+			...row,
+			[EXECUTION_TIME_COL]: executionTime
+		}));
+	}
+	async dispose() {
+		await Promise.all(this.stages.map((s) => s.dispose()));
+	}
+};
+/** Normalise any accepted input into pipeline rows with `content` and `path`. */
+async function toRows(input) {
+	if (Array.isArray(input)) return input.map((r) => ({ ...r }));
+	if (typeof input === "string") {
+		const response = await fetch(input);
+		if (!response.ok) throw new Error(`Failed to fetch ${input}: ${response.status} ${response.statusText}`);
+		return [{
+			content: new Uint8Array(await response.arrayBuffer()),
+			path: input
+		}];
+	}
+	if (input instanceof Uint8Array) return [{
+		content: input,
+		path: "memory"
+	}];
+	if (input instanceof ArrayBuffer) return [{
+		content: new Uint8Array(input),
+		path: "memory"
+	}];
+	if (typeof Blob !== "undefined" && input instanceof Blob) return [{
+		content: new Uint8Array(await input.arrayBuffer()),
+		path: "name" in input && typeof input.name === "string" ? input.name : "memory"
+	}];
+	return [{ ...input }];
+}
+//#endregion
+export { resolveNumThreads as _, toRows as a, ImageError as c, ScaleDpError as d, formatException as f, resetConfig as g, getConfig as h, Stage as i, NerError as l, defaultNumThreads as m, Pipeline as n, ConfigError as o, configure as p, ROW_TIME_COL as r, DetectionError as s, EXECUTION_TIME_COL as t, OcrError as u };
+
+//# sourceMappingURL=pipeline-DACqGkpN.js.map

package/dist/pipeline-DACqGkpN.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pipeline-DACqGkpN.js","names":[],"sources":["../src/core/config.ts","../src/core/errors.ts","../src/core/pipeline.ts"],"sourcesContent":["/**\n * Global configuration. Everything an application owns -- asset URLs, model\n * hosts, auth -- is injected here rather than hardcoded, which is the main\n * structural difference from the pdftools prototype this library supersedes.\n */\n\nexport interface ModelProgress {\n    repo: string\n    file: string\n    /** Bytes fetched so far across the request set. */\n    loaded: number\n    /** Total bytes expected; 0 when the server sent no content-length. */\n    total: number\n    phase: 'downloading' | 'initializing' | 'ready'\n}\n\nexport interface ScaleDpConfig {\n    /** Base URL models resolve against. Point at an origin you control to self-host. */\n    modelHost: string\n    /** Where downloaded model files are kept between page loads. */\n    cache: 'indexeddb' | 'none'\n    /** IndexedDB database name, so consumers can isolate or purge their own store. */\n    cacheDbName: string\n    /**\n     * Bearer token supplier for private model repos. Returning `undefined`\n     * means \"fetch anonymously\".\n     */\n    auth?: (repo: string) => Promise<string | undefined> | string | undefined\n    /** Reports download progress for every model file. */\n    onProgress?: (progress: ModelProgress) => void\n    /** Execution providers, in priority order, for ONNX sessions. */\n    executionProviders: readonly string[]\n    /**\n     * WASM threads. `0` lets onnxruntime-web choose from hardwareConcurrency.\n     * Threading only engages on a cross-origin-isolated page (COOP/COEP);\n     * without that ORT silently falls back to the single-threaded build.\n     */\n    numThreads: number\n    /**\n     * Directory holding the onnxruntime-web `.wasm`/`.mjs` pair. The loader and\n     * the binary must come from the same build variant AND the same version --\n     * a mismatch fails at init with an opaque error. Leave unset to let\n     * onnxruntime-web resolve its own default.\n     */\n    ortWasmPaths?: string\n    /** pdf.js assets. All must be served by the consuming application. */\n    pdf: {\n        workerSrc?: string\n        cMapUrl?: string\n        standardFontDataUrl?: string\n        wasmUrl?: string\n    }\n    /** Tesseract assets. */\n    tesseract: {\n        workerUrl?: string\n        /** Base URL for `<lang>.traineddata` files. */\n        dataUrl?: string\n    }\n    /** Hugging Face host overrides, for proxying gated repos through your origin. */\n    hf: {\n        remoteHost?: string\n        /** e.g. 'api/hf-model/{model}/resolve/{revision}/' */\n        remotePathTemplate?: string\n    }\n}\n\nconst DEFAULTS: ScaleDpConfig = {\n    modelHost: 'https://huggingface.co',\n    cache: 'indexeddb',\n    cacheDbName: 'scaledp-models',\n    executionProviders: ['wasm'],\n    numThreads: 0,\n    pdf: {},\n    tesseract: {},\n    hf: {},\n}\n\nlet current: ScaleDpConfig = { ...DEFAULTS }\n\n/** Merge `patch` into the global config. Nested asset maps merge per key. */\nexport function configure(patch: Partial<ScaleDpConfig>): ScaleDpConfig {\n    current = {\n        ...current,\n        ...patch,\n        pdf: { ...current.pdf, ...patch.pdf },\n        tesseract: { ...current.tesseract, ...patch.tesseract },\n        hf: { ...current.hf, ...patch.hf },\n    }\n    return current\n}\n\nexport function getConfig(): Readonly<ScaleDpConfig> {\n    return current\n}\n\n/** Restore defaults. Primarily for tests. */\nexport function resetConfig(): void {\n    current = { ...DEFAULTS, pdf: {}, tesseract: {}, hf: {} }\n}\n\n/**\n * Threads to request from onnxruntime-web.\n *\n * Leaves one core for the UI and caps at 4 -- past that, ORT's own\n * synchronisation overhead outweighs the gain on these model sizes.\n */\nexport function defaultNumThreads(): number {\n    const cores =\n        typeof navigator !== 'undefined' && typeof navigator.hardwareConcurrency === 'number'\n            ? navigator.hardwareConcurrency\n            : 4\n    return Math.max(1, Math.min(4, cores - 1))\n}\n\nexport function resolveNumThreads(): number {\n    const configured = getConfig().numThreads\n    return configured > 0 ? configured : defaultNumThreads()\n}\n","/**\n * ScaleDP stages never throw by default: a failure is captured into the output\n * schema's `exception` field so a pipeline always completes and partial results\n * survive. `propagateError: true` opts a stage into throwing instead.\n */\n\nexport class ScaleDpError extends Error {\n    constructor(\n        message: string,\n        readonly stage: string,\n        override readonly cause?: unknown\n    ) {\n        super(message)\n        this.name = 'ScaleDpError'\n    }\n}\n\nexport class ImageError extends ScaleDpError {\n    override readonly name = 'ImageError'\n}\nexport class OcrError extends ScaleDpError {\n    override readonly name = 'OcrError'\n}\nexport class DetectionError extends ScaleDpError {\n    override readonly name = 'DetectionError'\n}\nexport class NerError extends ScaleDpError {\n    override readonly name = 'NerError'\n}\nexport class ConfigError extends ScaleDpError {\n    override readonly name = 'ConfigError'\n}\n\n/** Render a caught value the way Python writes a traceback into `exception`. */\nexport function formatException(stage: string, error: unknown): string {\n    if (error instanceof Error) {\n        return `${stage}: ${error.name}: ${error.message}${error.stack ? `\\n${error.stack}` : ''}`\n    }\n    return `${stage}: ${String(error)}`\n}\n","/**\n * The pipeline runner, modelled on `scaledp/pipeline/PandasPipeline.py` rather\n * than on Spark.\n *\n * ScaleDP's Spark coupling is thin: every stage is a pure `Transformer` (there\n * are no Estimators, so no fit/transform duality) and the only DataFrame surface\n * stages use is withColumn / drop / select. That reduces to an array of plain\n * row objects, which is what this file implements.\n */\n\nimport { formatException } from './errors.js'\nimport type { BaseStageParams } from './params.js'\n\n/** One record flowing through the pipeline. Stages read and write named fields. */\nexport type Row = Record<string, unknown>\n\n/** Per-stage wall-clock timings, mirroring PandasPipeline's `execution_time` column. */\nexport interface ExecutionTime {\n    stages: Record<string, number>\n    total: number\n}\n\nexport const EXECUTION_TIME_COL = 'execution_time'\n\n/**\n * Per-row timings, accumulated as a row travels the pipeline.\n *\n * `execution_time` is per *run* -- one number per stage, the same on every row,\n * which is what Python records. That cannot answer \"how long did page 7 take\",\n * because a stage's number covers every page at once. This column can: each row\n * carries the time spent on it alone.\n *\n * A stage that expands produces several rows from one call, so its cost is\n * split evenly between them. The parts still sum to the call, but no finer\n * attribution is available from outside the stage.\n */\nexport interface RowTime {\n    stages: Record<string, number>\n    total: number\n}\n\nexport const ROW_TIME_COL = 'row_time'\n\n/** Anything a pipeline can be fed directly. */\nexport type PipelineInput = Uint8Array | ArrayBuffer | Blob | File | string | Row | Row[]\n\n/**\n * A stage described well enough to reconstruct it from plain data.\n *\n * This is the serialised form of a pipeline: `StageDescriptor[]` is JSON, so it\n * crosses the worker boundary (see `@stabrise/scaledp/worker`) and survives a\n * round trip through storage. `@stabrise/scaledp/registry` turns it back into\n * live stages.\n */\nexport interface StageDescriptor {\n    /** Exported class name, e.g. 'PdfToImage'. */\n    type: string\n    /** Constructor options. Must be structured-cloneable. */\n    options?: Record<string, unknown>\n}\n\nexport interface StageContext {\n    /** Zero-based index of this stage in the pipeline. */\n    index: number\n    signal?: AbortSignal\n}\n\n/**\n * Base class for every stage.\n *\n * Subclasses implement `apply`, which transforms a single row's input value.\n * The base handles column wiring, error capture and the `keepInputData`\n * contract, so those behave identically everywhere.\n */\nexport abstract class Stage<P extends BaseStageParams = BaseStageParams> {\n    abstract readonly name: string\n\n    constructor(readonly params: P) {}\n\n    /**\n     * Transform one row's input value into this stage's output value.\n     *\n     * Throwing is fine and expected -- `transform` converts it into the output\n     * schema's `exception` field unless `propagateError` is set.\n     */\n    protected abstract apply(input: unknown, row: Row, ctx: StageContext): Promise<unknown>\n\n    /**\n     * Value written to `outputCol` when `apply` throws. Subclasses return an\n     * empty instance of their output schema carrying the message, so downstream\n     * stages see a well-formed value rather than `undefined`.\n     */\n    protected abstract onError(message: string, row: Row): unknown\n\n    /** Optional per-stage setup (model download, session creation). Called once. */\n    async init(): Promise<void> {}\n\n    /** Release any held resources (ONNX sessions, workers). */\n    async dispose(): Promise<void> {}\n\n    /**\n     * A stage may emit several rows per input row -- PDF page explosion, box\n     * cropping. Returning `null` means \"use the single-row path\".\n     */\n    protected async expand(_input: unknown, _row: Row, _ctx: StageContext): Promise<Row[] | null> {\n        return null\n    }\n\n    async transform(rows: Row[], ctx: StageContext): Promise<Row[]> {\n        const { inputCol, outputCol, keepInputData, propagateError } = this.params\n        const out: Row[] = []\n\n        for (const row of rows) {\n            ctx.signal?.throwIfAborted()\n            const input = row[inputCol]\n            let next: Row[]\n\n            const started = performance.now()\n            try {\n                const expanded = await this.expand(input, row, ctx)\n                next = expanded ?? [{ ...row, [outputCol]: await this.apply(input, row, ctx) }]\n            } catch (error) {\n                if (propagateError) throw error\n                next = [{ ...row, [outputCol]: this.onError(formatException(this.name, error), row) }]\n            }\n            // Failures are timed too: a stage that spent nine seconds before\n            // throwing still cost nine seconds.\n            const elapsed = performance.now() - started\n\n            if (!keepInputData && inputCol !== outputCol) {\n                for (const r of next) delete r[inputCol]\n            }\n            for (const r of next) chargeRow(r, this.name, elapsed / next.length)\n            out.push(...next)\n        }\n        return out\n    }\n}\n\n/**\n * Add a stage's cost to one row's running total.\n *\n * The row inherited its predecessor's timings by the spread that built it, so\n * the record is copied before writing -- sibling rows from one expand would\n * otherwise share it and every charge would land on all of them.\n */\nfunction chargeRow(row: Row, name: string, ms: number): void {\n    const previous = row[ROW_TIME_COL] as RowTime | undefined\n    const stages = { ...previous?.stages }\n    stages[name] = (stages[name] ?? 0) + ms\n    row[ROW_TIME_COL] = { stages, total: (previous?.total ?? 0) + ms }\n}\n\nexport interface PipelineOptions {\n    signal?: AbortSignal\n    /** Called after each stage with its name and elapsed milliseconds. */\n    onStage?: (name: string, ms: number, rows: number) => void\n}\n\nexport class Pipeline {\n    constructor(readonly stages: Stage[]) {}\n\n    /** Run every stage in order. Input is normalised into rows first. */\n    async transform(input: PipelineInput, options: PipelineOptions = {}): Promise<Row[]> {\n        let rows = await toRows(input)\n        const timings: Record<string, number> = {}\n        const started = performance.now()\n\n        for (const [index, stage] of this.stages.entries()) {\n            options.signal?.throwIfAborted()\n            const t0 = performance.now()\n            await stage.init()\n            rows = await stage.transform(rows, { index, signal: options.signal })\n            const elapsed = performance.now() - t0\n\n            // Two stages of the same class in one pipeline must not overwrite\n            // each other's timing, so disambiguate by position.\n            const key = timings[stage.name] === undefined ? stage.name : `${stage.name}#${index}`\n            timings[key] = elapsed\n            options.onStage?.(stage.name, elapsed, rows.length)\n        }\n\n        const executionTime: ExecutionTime = { stages: timings, total: performance.now() - started }\n        return rows.map((row) => ({ ...row, [EXECUTION_TIME_COL]: executionTime }))\n    }\n\n    async dispose(): Promise<void> {\n        await Promise.all(this.stages.map((s) => s.dispose()))\n    }\n}\n\n/** Normalise any accepted input into pipeline rows with `content` and `path`. */\nexport async function toRows(input: PipelineInput): Promise<Row[]> {\n    if (Array.isArray(input)) return input.map((r) => ({ ...r }))\n\n    if (typeof input === 'string') {\n        const response = await fetch(input)\n        if (!response.ok) {\n            throw new Error(`Failed to fetch ${input}: ${response.status} ${response.statusText}`)\n        }\n        const data = new Uint8Array(await response.arrayBuffer())\n        return [{ content: data, path: input }]\n    }\n\n    if (input instanceof Uint8Array) return [{ content: input, path: 'memory' }]\n    if (input instanceof ArrayBuffer) return [{ content: new Uint8Array(input), path: 'memory' }]\n\n    if (typeof Blob !== 'undefined' && input instanceof Blob) {\n        const data = new Uint8Array(await input.arrayBuffer())\n        const path = 'name' in input && typeof input.name === 'string' ? input.name : 'memory'\n        return [{ content: data, path }]\n    }\n\n    return [{ ...(input as Row) }]\n}\n"],"mappings":"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"}

package/dist/pipeline-DeLO-OCE.d.ts

@@ -0,0 +1,139 @@
+//#region src/core/params.d.ts
+/**
+ * The TS analogue of `scaledp/params.py`.
+ *
+ * Python builds params from a frozen `defaultParams` map plus a coercion pass
+ * (`HasDefaultEnum._set`) that unwraps enums, normalises `lang`, and runs any
+ * `validate<Param>` hook. TypeScript needs neither a metaclass nor Param
+ * objects -- an options object merged over a frozen default, with optional
+ * per-key validators, covers the same ground with real types.
+ */
+type Validator<T> = { [K in keyof T]?: (value: T[K], all: T) => void; };
+/** Params every stage accepts, mirroring the Python mixins. */
+interface BaseStageParams {
+  /** Row field this stage reads. */
+  inputCol: string;
+  /** Row field this stage writes. */
+  outputCol: string;
+  /** Row field holding the source path; used to populate output `path`. */
+  pathCol: string;
+  /** Row field holding the page index for multi-page inputs. */
+  pageCol: string;
+  /** Keep `inputCol` in the output rows instead of dropping it. */
+  keepInputData: boolean;
+  /** Throw on failure instead of recording it in the output's `exception`. */
+  propagateError: boolean;
+}
+declare const BASE_STAGE_DEFAULTS: BaseStageParams;
+/**
+ * Merge user options over defaults and run validators.
+ *
+ * `undefined` values are ignored so `{ scoreThreshold: undefined }` falls back
+ * to the default rather than erasing it -- callers spreading optional config
+ * would otherwise silently lose defaults.
+ */
+declare function resolveParams<T extends object>(defaults: Readonly<T>, options?: Partial<T>, validators?: Validator<T>): T;
+/** Throw unless `value` lies within [min, max]. */
+declare function assertInRange(name: string, value: number, min: number, max: number): void;
+/** Throw unless `value` is a positive integer. */
+declare function assertPositiveInt(name: string, value: number): void;
+//#endregion
+//#region src/core/pipeline.d.ts
+/** One record flowing through the pipeline. Stages read and write named fields. */
+type Row = Record<string, unknown>;
+/** Per-stage wall-clock timings, mirroring PandasPipeline's `execution_time` column. */
+interface ExecutionTime {
+  stages: Record<string, number>;
+  total: number;
+}
+declare const EXECUTION_TIME_COL = "execution_time";
+/**
+ * Per-row timings, accumulated as a row travels the pipeline.
+ *
+ * `execution_time` is per *run* -- one number per stage, the same on every row,
+ * which is what Python records. That cannot answer "how long did page 7 take",
+ * because a stage's number covers every page at once. This column can: each row
+ * carries the time spent on it alone.
+ *
+ * A stage that expands produces several rows from one call, so its cost is
+ * split evenly between them. The parts still sum to the call, but no finer
+ * attribution is available from outside the stage.
+ */
+interface RowTime {
+  stages: Record<string, number>;
+  total: number;
+}
+declare const ROW_TIME_COL = "row_time";
+/** Anything a pipeline can be fed directly. */
+type PipelineInput = Uint8Array | ArrayBuffer | Blob | File | string | Row | Row[];
+/**
+ * A stage described well enough to reconstruct it from plain data.
+ *
+ * This is the serialised form of a pipeline: `StageDescriptor[]` is JSON, so it
+ * crosses the worker boundary (see `@stabrise/scaledp/worker`) and survives a
+ * round trip through storage. `@stabrise/scaledp/registry` turns it back into
+ * live stages.
+ */
+interface StageDescriptor {
+  /** Exported class name, e.g. 'PdfToImage'. */
+  type: string;
+  /** Constructor options. Must be structured-cloneable. */
+  options?: Record<string, unknown>;
+}
+interface StageContext {
+  /** Zero-based index of this stage in the pipeline. */
+  index: number;
+  signal?: AbortSignal;
+}
+/**
+ * Base class for every stage.
+ *
+ * Subclasses implement `apply`, which transforms a single row's input value.
+ * The base handles column wiring, error capture and the `keepInputData`
+ * contract, so those behave identically everywhere.
+ */
+declare abstract class Stage<P extends BaseStageParams = BaseStageParams> {
+  readonly params: P;
+  abstract readonly name: string;
+  constructor(params: P);
+  /**
+   * Transform one row's input value into this stage's output value.
+   *
+   * Throwing is fine and expected -- `transform` converts it into the output
+   * schema's `exception` field unless `propagateError` is set.
+   */
+  protected abstract apply(input: unknown, row: Row, ctx: StageContext): Promise<unknown>;
+  /**
+   * Value written to `outputCol` when `apply` throws. Subclasses return an
+   * empty instance of their output schema carrying the message, so downstream
+   * stages see a well-formed value rather than `undefined`.
+   */
+  protected abstract onError(message: string, row: Row): unknown;
+  /** Optional per-stage setup (model download, session creation). Called once. */
+  init(): Promise<void>;
+  /** Release any held resources (ONNX sessions, workers). */
+  dispose(): Promise<void>;
+  /**
+   * A stage may emit several rows per input row -- PDF page explosion, box
+   * cropping. Returning `null` means "use the single-row path".
+   */
+  protected expand(_input: unknown, _row: Row, _ctx: StageContext): Promise<Row[] | null>;
+  transform(rows: Row[], ctx: StageContext): Promise<Row[]>;
+}
+interface PipelineOptions {
+  signal?: AbortSignal;
+  /** Called after each stage with its name and elapsed milliseconds. */
+  onStage?: (name: string, ms: number, rows: number) => void;
+}
+declare class Pipeline {
+  readonly stages: Stage[];
+  constructor(stages: Stage[]);
+  /** Run every stage in order. Input is normalised into rows first. */
+  transform(input: PipelineInput, options?: PipelineOptions): Promise<Row[]>;
+  dispose(): Promise<void>;
+}
+/** Normalise any accepted input into pipeline rows with `content` and `path`. */
+declare function toRows(input: PipelineInput): Promise<Row[]>;
+//#endregion
+export { assertPositiveInt as _, PipelineOptions as a, RowTime as c, StageDescriptor as d, toRows as f, assertInRange as g, Validator as h, PipelineInput as i, Stage as l, BaseStageParams as m, ExecutionTime as n, ROW_TIME_COL as o, BASE_STAGE_DEFAULTS as p, Pipeline as r, Row as s, EXECUTION_TIME_COL as t, StageContext as u, resolveParams as v };
+//# sourceMappingURL=pipeline-DeLO-OCE.d.ts.map

package/dist/registry/index.d.ts

@@ -0,0 +1,169 @@
+import { d as StageDescriptor, l as Stage, r as Pipeline } from "../pipeline-DeLO-OCE.js";
+//#region src/registry/types.d.ts
+/**
+ * Runtime metadata describing every stage's parameters.
+ *
+ * Params in this library are a TypeScript interface plus a frozen defaults
+ * object (see `src/core/params.ts`). Types, enums and ranges live in the `.d.ts`
+ * and in validator closures -- neither readable at runtime, which is what a
+ * parameter form needs. This file declares the shape of that missing metadata;
+ * `catalog.ts` fills it in.
+ *
+ * The defaults themselves are never restated here. Every spec points at the
+ * stage's own `*_DEFAULTS` constant, so a changed default cannot drift out of
+ * the catalogue -- and `test/unit/registry.test.ts` fails when a *new* param is
+ * added to a stage without a matching entry.
+ */
+/** What a column holds, well enough to check that a stage can read it. */
+type ColumnKind = 'bytes' | 'image' | 'boxes' | 'document' | 'ner' | 'orientations' | 'box';
+/** Which widget a parameter wants. */
+type StageParamKind = 'string' | 'number' | 'boolean' | 'enum' |
+/** An array of strings edited as a list: labels, lang, displayDataList. */
+'stringList' |
+/** A single row field name: inputCol, outputCol, orientationCol, boxCol. */
+'column' |
+/** A fixed-length list of row field names: inputCols. */
+'columns' |
+/** A CSS colour, or null for "choose one per group". */
+'color';
+interface StageParamOption {
+  value: string;
+  label: string;
+  /** Longer description, for a tooltip. */
+  title?: string;
+  /** Selectable but not usable as configured -- private repos, say. */
+  disabled?: boolean;
+}
+interface StageParamSpec {
+  /** Key in the stage's params object. */
+  key: string;
+  kind: StageParamKind;
+  label: string;
+  /** One line explaining what the parameter does. */
+  help?: string;
+  min?: number;
+  max?: number;
+  step?: number;
+  /** `columns` only: how many entries the list must have, when it is fixed. */
+  arity?: number;
+  /**
+   * `columns` only: the fewest entries a variable-length list may have.
+   *
+   * `ImageDrawBoxes` takes an image and at least one box column, so its list
+   * grows but never shrinks below two. Without this the constraint lives only
+   * inside the stage's constructor validator, where a form cannot see it.
+   */
+  minArity?: number;
+  /** `columns`/`column` only: what each position must hold. */
+  accepts?: ColumnKind[];
+  /**
+   * Values worth offering.
+   *
+   * On an `enum` these are the only values. On a `stringList` they are the
+   * ones a UI should let you pick from -- the list stays open, but the field
+   * names that actually render are not guessable, so leaving it entirely free
+   * text hides them.
+   */
+  options?: readonly StageParamOption[];
+  /** `enum` only: also accept a value outside `options`. */
+  allowCustom?: boolean;
+  /** Wiring and plumbing rather than behaviour; collapse it by default. */
+  advanced?: boolean;
+  /** Reject the value in the UI before the constructor throws. */
+  required?: boolean;
+}
+/** Where a stage's weights come from, so a UI can report cache state. */
+type StageCacheSpec =
+/** The param names a PaddleOCR preset id. */
+{
+  kind: 'paddle-preset';
+  param: string;
+} |
+/** The param names a Hugging Face repo id or URL. */
+{
+  kind: 'hf-repo';
+  param: string;
+  approxBytes?: number;
+} |
+/** The param names an id in `NER_MODELS`. */
+{
+  kind: 'ner-id';
+  param: string;
+};
+interface StageSpec {
+  /** Exported class name. Also the `StageDescriptor.type` and the stage's `name`. */
+  type: string;
+  label: string;
+  group: 'Read' | 'Detect' | 'Recognise' | 'Understand' | 'Transform';
+  /** Import specifier the class lives behind, shown on the stage card. */
+  subpath: string;
+  summary: string;
+  /** Column kinds this stage reads, in `inputCols` order where it has one. */
+  consumes: readonly ColumnKind[];
+  /** Column kind written to `outputCol`. */
+  produces: ColumnKind;
+  /** Extra columns written by stages that emit more than one. */
+  alsoProduces?: readonly {
+    param: string;
+    kind: ColumnKind;
+  }[];
+  /** Optional peer dependency the stage needs at run time. */
+  peer?: string;
+  cache?: StageCacheSpec;
+  /** One row per input row, or several? PDF page explosion and box cropping. */
+  expands?: boolean;
+  /**
+   * The output is for looking at, not for feeding onward.
+   *
+   * An annotated page is still an image, so a UI choosing "the most recent
+   * image column" would hand it to the next detector -- which would then read
+   * text through the boxes drawn over it. Chaining annotation passes is a real
+   * idiom, so this marks the column rather than forbidding it.
+   */
+  terminal?: boolean;
+  /** The stage's own frozen `*_DEFAULTS` object. */
+  defaults: Readonly<Record<string, unknown>>;
+  params: readonly StageParamSpec[];
+}
+//#endregion
+//#region src/registry/catalog.d.ts
+declare const STAGE_SPECS: readonly StageSpec[];
+/** Name → constructor, for building a stage from a `StageDescriptor`. */
+declare const STAGE_CLASSES: Readonly<Record<string, new (options?: never) => Stage>>;
+//#endregion
+//#region src/registry/codegen.d.ts
+interface PipelineCodeOptions {
+  /** Name bound to the pipeline. */
+  variable?: string;
+  /** Emit the import block above it. */
+  imports?: boolean;
+  /** Spaces per indent level. */
+  indent?: number;
+}
+declare function pipelineCode(descriptors: readonly StageDescriptor[], options?: PipelineCodeOptions): string;
+//#endregion
+//#region src/registry/index.d.ts
+/** Metadata for one stage, by exported class name. */
+declare function getStageSpec(type: string): (typeof STAGE_SPECS)[number] | undefined;
+/**
+ * Build one stage from its serialised form.
+ *
+ * Throws on an unknown type, and lets the stage's own constructor validators
+ * throw on a bad param -- an unknown OCR preset should fail here, where the
+ * message can name the offending field, rather than several stages later.
+ */
+declare function createStage(descriptor: StageDescriptor): Stage;
+/** Build a whole pipeline from its serialised form. */
+declare function pipelineFromDescriptors(descriptors: readonly StageDescriptor[]): Pipeline;
+/**
+ * The serialised form of a live stage.
+ *
+ * `stage.params` is fully resolved -- defaults merged in -- so this round-trips
+ * exactly but is more verbose than the options originally passed.
+ */
+declare function describeStage(stage: Stage): StageDescriptor;
+/** The serialised form of a live pipeline. */
+declare function describePipeline(pipeline: Pipeline): StageDescriptor[];
+//#endregion
+export { type ColumnKind, type PipelineCodeOptions, STAGE_CLASSES, STAGE_SPECS, type StageCacheSpec, type StageDescriptor, type StageParamKind, type StageParamOption, type StageParamSpec, type StageSpec, createStage, describePipeline, describeStage, getStageSpec, pipelineCode, pipelineFromDescriptors };
+//# sourceMappingURL=index.d.ts.map