@flomatai/core 0.1.0

package/dist/pipeline-registry.d.ts

@@ -0,0 +1,120 @@
+/**
+ * Pipeline Registry — discover, load, and manage pipelines from various sources.
+ *
+ * This module provides:
+ * - PipelineSource: define where a pipeline comes from (npm, local path, git)
+ * - PipelineRegistry: local registry that maps names to sources
+ * - loadPipeline(): resolve a source to a BuiltPipeline
+ */
+import type { BuiltPipeline } from './pipeline.js';
+import type { ZodSchema } from 'zod';
+/**
+ * Metadata for a pipeline package.
+ * Exported from the pipeline's main file.
+ */
+export interface PipelinePackageMeta {
+    /** Unique name (e.g., 'content-generation') */
+    name: string;
+    /** Human-readable description */
+    description: string;
+    /** Semantic version */
+    version?: string;
+    /** Tags for discovery */
+    tags?: string[];
+    /** Author information */
+    author?: string;
+    /** Input schema (for display/documentation) */
+    inputSchema?: ZodSchema;
+    /** Output schema (for display/documentation) */
+    outputSchema?: ZodSchema;
+}
+/**
+ * Full pipeline export from a pipeline package.
+ */
+export interface PipelinePackageExports {
+    /** The built pipeline */
+    pipeline: BuiltPipeline;
+    /** Optional metadata */
+    metadata?: PipelinePackageMeta;
+    /** Optional config schema for runtime validation */
+    configSchema?: ZodSchema;
+    /** Optional orchestrator override */
+    orchestrator?: unknown;
+}
+/** Where a pipeline is loaded from */
+export type PipelineSource = {
+    type: 'npm';
+    package: string;
+    export?: string;
+} | {
+    type: 'path';
+    path: string;
+} | {
+    type: 'git';
+    url: string;
+    ref?: string;
+};
+/** Registered pipeline in the local registry */
+export interface RegisteredPipeline {
+    /** Local name (e.g., 'my-pipeline') */
+    name: string;
+    /** Source where the pipeline is loaded from */
+    source: PipelineSource;
+    /** Optional version constraint (for npm) */
+    version?: string;
+    /** When this was registered */
+    registeredAt: Date;
+    /** Cached loaded exports */
+    exports?: PipelinePackageExports;
+}
+/**
+ * Local pipeline registry.
+ * Maps friendly names to pipeline sources.
+ */
+export declare class PipelineRegistry {
+    private readonly pipelines;
+    private readonly pipelineDirs;
+    constructor(pipelineDirs?: string[]);
+    /**
+     * Register a pipeline from an npm package.
+     */
+    register(name: string, packageName: string, options?: {
+        version?: string;
+    }): void;
+    /**
+     * Register a pipeline from a local path.
+     */
+    registerPath(name: string, path: string): void;
+    /**
+     * Register a pipeline from a git repository.
+     */
+    registerGit(name: string, url: string, ref?: string): void;
+    /**
+     * Get a registered pipeline by name.
+     */
+    get(name: string): RegisteredPipeline | undefined;
+    /**
+     * List all registered pipelines.
+     */
+    list(): RegisteredPipeline[];
+    /**
+     * Remove a pipeline from the registry.
+     */
+    unregister(name: string): boolean;
+    /**
+     * Clear all registrations.
+     */
+    clear(): void;
+}
+/**
+ * Load a pipeline from a source.
+ */
+export declare function loadPipeline(source: PipelineSource): Promise<PipelinePackageExports>;
+/**
+ * Create a registry from a config object.
+ */
+export declare function createRegistryFromConfig(config: Record<string, string | {
+    package: string;
+    version?: string;
+}>): PipelineRegistry;
+//# sourceMappingURL=pipeline-registry.d.ts.map

package/dist/pipeline-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pipeline-registry.d.ts","sourceRoot":"","sources":["../src/pipeline-registry.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAKH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AACnD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,KAAK,CAAC;AAIrC;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IAClC,+CAA+C;IAC/C,IAAI,EAAE,MAAM,CAAC;IACb,iCAAiC;IACjC,WAAW,EAAE,MAAM,CAAC;IACpB,uBAAuB;IACvB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,yBAAyB;IACzB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,yBAAyB;IACzB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,+CAA+C;IAC/C,WAAW,CAAC,EAAE,SAAS,CAAC;IACxB,gDAAgD;IAChD,YAAY,CAAC,EAAE,SAAS,CAAC;CAC1B;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,yBAAyB;IACzB,QAAQ,EAAE,aAAa,CAAC;IACxB,wBAAwB;IACxB,QAAQ,CAAC,EAAE,mBAAmB,CAAC;IAC/B,oDAAoD;IACpD,YAAY,CAAC,EAAE,SAAS,CAAC;IACzB,qCAAqC;IACrC,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAID,sCAAsC;AACtC,MAAM,MAAM,cAAc,GACtB;IAAE,IAAI,EAAE,KAAK,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,GACjD;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC9B;IAAE,IAAI,EAAE,KAAK,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAE/C,gDAAgD;AAChD,MAAM,WAAW,kBAAkB;IACjC,uCAAuC;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,+CAA+C;IAC/C,MAAM,EAAE,cAAc,CAAC;IACvB,4CAA4C;IAC5C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,+BAA+B;IAC/B,YAAY,EAAE,IAAI,CAAC;IACnB,4BAA4B;IAC5B,OAAO,CAAC,EAAE,sBAAsB,CAAC;CAClC;AAID;;;GAGG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA8C;IACxE,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAgB;gBAEjC,YAAY,GAAE,MAAM,EAAO;IAIvC;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI;IASjF;;OAEG;IACH,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI;IAQ9C;;OAEG;IACH,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI;IAQ1D;;OAEG;IACH,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,kBAAkB,GAAG,SAAS;IAIjD;;OAEG;IACH,IAAI,IAAI,kBAAkB,EAAE;IAI5B;;OAEG;IACH,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAIjC;;OAEG;IACH,KAAK,IAAI,IAAI;CAGd;AAID;;GAEG;AACH,wBAAsB,YAAY,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAU1F;AA2DD;;GAEG;AACH,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,GACrE,gBAAgB,CAsBlB"}

package/dist/pipeline-registry.js

@@ -0,0 +1,171 @@
+/**
+ * Pipeline Registry — discover, load, and manage pipelines from various sources.
+ *
+ * This module provides:
+ * - PipelineSource: define where a pipeline comes from (npm, local path, git)
+ * - PipelineRegistry: local registry that maps names to sources
+ * - loadPipeline(): resolve a source to a BuiltPipeline
+ */
+import { resolve } from 'path';
+import { existsSync } from 'fs';
+import { readFile } from 'fs/promises';
+// ── Pipeline Registry ────────────────────────────────────────────────────────
+/**
+ * Local pipeline registry.
+ * Maps friendly names to pipeline sources.
+ */
+export class PipelineRegistry {
+    pipelines = new Map();
+    pipelineDirs = [];
+    constructor(pipelineDirs = []) {
+        this.pipelineDirs = pipelineDirs;
+    }
+    /**
+     * Register a pipeline from an npm package.
+     */
+    register(name, packageName, options) {
+        this.pipelines.set(name, {
+            name,
+            source: { type: 'npm', package: packageName },
+            version: options?.version,
+            registeredAt: new Date(),
+        });
+    }
+    /**
+     * Register a pipeline from a local path.
+     */
+    registerPath(name, path) {
+        this.pipelines.set(name, {
+            name,
+            source: { type: 'path', path: resolve(path) },
+            registeredAt: new Date(),
+        });
+    }
+    /**
+     * Register a pipeline from a git repository.
+     */
+    registerGit(name, url, ref) {
+        this.pipelines.set(name, {
+            name,
+            source: { type: 'git', url, ref },
+            registeredAt: new Date(),
+        });
+    }
+    /**
+     * Get a registered pipeline by name.
+     */
+    get(name) {
+        return this.pipelines.get(name);
+    }
+    /**
+     * List all registered pipelines.
+     */
+    list() {
+        return Array.from(this.pipelines.values());
+    }
+    /**
+     * Remove a pipeline from the registry.
+     */
+    unregister(name) {
+        return this.pipelines.delete(name);
+    }
+    /**
+     * Clear all registrations.
+     */
+    clear() {
+        this.pipelines.clear();
+    }
+}
+// ── Pipeline Loader ─────────────────────────────────────────────────────────
+/**
+ * Load a pipeline from a source.
+ */
+export async function loadPipeline(source) {
+    switch (source.type) {
+        case 'path':
+            return loadFromPath(source.path);
+        case 'npm':
+            return loadFromNpm(source.package, source.export);
+        case 'git':
+            // TODO: Implement git loading (clone + package.json lookup)
+            throw new Error('Git pipeline loading not yet implemented');
+    }
+}
+/**
+ * Load a pipeline from a local path.
+ */
+async function loadFromPath(absolutePath) {
+    // Check if it's a directory (pipeline package) or a file
+    const dirExists = existsSync(absolutePath);
+    const fileExists = existsSync(absolutePath + '.ts') || existsSync(absolutePath + '.js');
+    if (dirExists) {
+        // It's a directory — look for pipeline.ts or package.json
+        const pkgPath = resolve(absolutePath, 'package.json');
+        if (existsSync(pkgPath)) {
+            const pkg = JSON.parse(await readFile(pkgPath, 'utf-8'));
+            const mainFile = resolve(absolutePath, pkg.main || pkg.exports?.['.'] || 'index.js');
+            return import(mainFile);
+        }
+        const pipelinePath = resolve(absolutePath, 'pipeline.ts');
+        if (existsSync(pipelinePath)) {
+            return import(pipelinePath);
+        }
+        throw new Error(`No pipeline.ts or package.json found in ${absolutePath}`);
+    }
+    if (fileExists) {
+        // Direct file import
+        const ext = existsSync(absolutePath + '.ts') ? '.ts' : '.js';
+        return import(absolutePath + ext);
+    }
+    throw new Error(`Pipeline not found at ${absolutePath}`);
+}
+/**
+ * Load a pipeline from an npm package.
+ * Note: This requires the package to be installed in node_modules.
+ */
+async function loadFromNpm(packageName, exportPath) {
+    try {
+        const resolved = exportPath
+            ? await import(`${packageName}/${exportPath}`)
+            : await import(packageName);
+        if (!resolved.pipeline) {
+            throw new Error(`Package ${packageName} does not export a 'pipeline'`);
+        }
+        return resolved;
+    }
+    catch (err) {
+        if (err instanceof Error && err.message.includes('package')) {
+            throw new Error(`Pipeline package not found: ${packageName}. Did you install it?`);
+        }
+        throw err;
+    }
+}
+// ── Registry Resolution ────────────────────────────────────────────────────────
+/**
+ * Create a registry from a config object.
+ */
+export function createRegistryFromConfig(config) {
+    const registry = new PipelineRegistry();
+    for (const [name, source] of Object.entries(config)) {
+        if (typeof source === 'string') {
+            // Short form: 'my-pipeline': './path' or 'my-pipeline': '@org/pkg'
+            if (source.startsWith('./') || source.startsWith('/')) {
+                registry.registerPath(name, source);
+            }
+            else if (source.startsWith('git+') || source.startsWith('https://')) {
+                const url = source.startsWith('git+') ? source : `git+${source}`;
+                registry.registerGit(name, url);
+            }
+            else {
+                // Assume npm package
+                registry.register(name, source);
+            }
+        }
+        else {
+            // Long form: 'my-pipeline': { package: '@org/pkg', version: '1.0.0' }
+            registry.register(name, source.package, { version: source.version });
+        }
+    }
+    return registry;
+}
+//# sourceMappingURL=pipeline-registry.js.map

package/dist/pipeline-registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pipeline-registry.js","sourceRoot":"","sources":["../src/pipeline-registry.ts"],"names":[],"mappings":"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"}

package/dist/pipeline.d.ts

@@ -0,0 +1,122 @@
+/**
+ * Pipeline DSL — fluent builder for defining execution graphs.
+ *
+ * A Pipeline is a directed sequence of Steps. Each Step is a Skill, Agent,
+ * or another Pipeline. Built pipelines are immutable value objects executed
+ * by the Orchestrator.
+ */
+import type { ZodSchema } from 'zod';
+import type { Skill } from './skill.js';
+export type StepKind = 'skill' | 'map' | 'filter' | 'reduce' | 'branch' | 'parallel';
+/** A single resolved step in the pipeline graph. */
+export interface PipelineStep {
+    name: string;
+    kind: StepKind;
+    /** For 'skill' steps: the skill to run. */
+    skill?: Skill;
+    /** For 'map' | 'filter' | 'reduce': source field path (e.g. 'parse.services'). */
+    sourceField?: string;
+    /** For 'map': the sub-pipeline to run for each item. */
+    subPipeline?: BuiltPipeline;
+    /** For 'filter': predicate function. */
+    predicate?: (item: unknown, index: number) => boolean;
+    /** For 'reduce': reducer function. */
+    reducer?: (acc: unknown, item: unknown, index: number) => unknown;
+    /** For 'reduce': initial accumulator. */
+    initialValue?: unknown;
+    /** For 'parallel': array of sub-pipelines to run concurrently. */
+    branches?: BuiltPipeline[];
+    /** Concurrency limit for 'map' steps (default 1 = sequential). */
+    concurrency?: number;
+    /** How to handle item errors in 'map' steps. */
+    onItemError?: 'fail' | 'skip' | 'retry';
+    /** Max retries for items in 'map' with onItemError='retry'. */
+    maxItemRetries?: number;
+    /**
+     * Custom input mapper. Receives the current pipeline context and
+     * returns the input for this step. Default: pass entire previous output.
+     */
+    inputMapper?: (ctx: StepInputContext) => unknown;
+    /** Skip this step if this returns true. */
+    skipIf?: (ctx: StepInputContext) => boolean;
+}
+export interface StepInputContext {
+    /** The overall pipeline input. */
+    pipelineInput: unknown;
+    /** Outputs from all previously completed steps, keyed by step name. */
+    stepOutputs: Record<string, unknown>;
+    /** The output of the immediately preceding step. */
+    previousOutput: unknown;
+}
+export interface BuiltPipeline {
+    name: string;
+    steps: PipelineStep[];
+    inputSchema?: ZodSchema;
+    outputSchema?: ZodSchema;
+    /** Whether to save step checkpoints for resume capability. */
+    checkpointing?: boolean;
+}
+export declare class PipelineBuilder {
+    private readonly _name;
+    private _steps;
+    private _inputSchema?;
+    private _outputSchema?;
+    private _checkpointing;
+    constructor(name: string);
+    /** Declare the input schema for validation and documentation. */
+    input(schema: ZodSchema): this;
+    /** Declare the output schema for validation and documentation. */
+    output(schema: ZodSchema): this;
+    /** Enable checkpoint saving for resume capability. */
+    withCheckpointing(): this;
+    /**
+     * Add a skill step.
+     *
+     * @param name    Step name (must be unique within the pipeline).
+     * @param skill   The skill to execute.
+     * @param options Optional input mapper and skip condition.
+     */
+    step(name: string, skill: Skill, options?: {
+        input?: (ctx: StepInputContext) => unknown;
+        skipIf?: (ctx: StepInputContext) => boolean;
+    }): this;
+    /**
+     * Map over an array field, running a sub-pipeline for each item.
+     *
+     * @param sourceField  Dot-path to the array in step outputs (e.g. 'parse.services').
+     *                     Use '*' to use the entire previous step output as array.
+     * @param subPipeline  Sub-pipeline (built or builder) to run per item.
+     * @param options      Concurrency and error handling options.
+     */
+    mapOver(sourceField: string, subPipeline: BuiltPipeline | PipelineBuilder, options?: {
+        concurrency?: number;
+        onItemError?: 'fail' | 'skip' | 'retry';
+        maxItemRetries?: number;
+        name?: string;
+    }): this;
+    /**
+     * Filter an array field, keeping only items where predicate returns true.
+     */
+    filter(sourceField: string, predicate: (item: unknown, index: number) => boolean, name?: string): this;
+    /**
+     * Reduce an array field to a single value.
+     */
+    reduce(sourceField: string, reducer: (acc: unknown, item: unknown, index: number) => unknown, initialValue: unknown, name?: string): this;
+    /**
+     * Run multiple sub-pipelines in parallel, collecting all results.
+     */
+    parallel(branches: Array<BuiltPipeline | PipelineBuilder>, name?: string): this;
+    /**
+     * Conditionally branch: run one of several sub-pipelines based on a condition.
+     */
+    branch(name: string, condition: (ctx: StepInputContext) => string, // returns branch name
+    branches: Record<string, BuiltPipeline | PipelineBuilder>): this;
+    /** Finalize and return the immutable pipeline definition. */
+    build(): BuiltPipeline;
+}
+export declare const Pipeline: {
+    /** Create a new pipeline builder. */
+    create: (name: string) => PipelineBuilder;
+};
+export declare function resolvePath(stepOutputs: Record<string, unknown>, path: string): unknown;
+//# sourceMappingURL=pipeline.d.ts.map

package/dist/pipeline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pipeline.d.ts","sourceRoot":"","sources":["../src/pipeline.ts"],"names":[],"mappings":"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"}

package/dist/pipeline.js

@@ -0,0 +1,152 @@
+/**
+ * Pipeline DSL — fluent builder for defining execution graphs.
+ *
+ * A Pipeline is a directed sequence of Steps. Each Step is a Skill, Agent,
+ * or another Pipeline. Built pipelines are immutable value objects executed
+ * by the Orchestrator.
+ */
+// ── Pipeline Builder ──────────────────────────────────────────────────────────
+export class PipelineBuilder {
+    _name;
+    _steps = [];
+    _inputSchema;
+    _outputSchema;
+    _checkpointing = false;
+    constructor(name) {
+        this._name = name;
+    }
+    /** Declare the input schema for validation and documentation. */
+    input(schema) {
+        this._inputSchema = schema;
+        return this;
+    }
+    /** Declare the output schema for validation and documentation. */
+    output(schema) {
+        this._outputSchema = schema;
+        return this;
+    }
+    /** Enable checkpoint saving for resume capability. */
+    withCheckpointing() {
+        this._checkpointing = true;
+        return this;
+    }
+    /**
+     * Add a skill step.
+     *
+     * @param name    Step name (must be unique within the pipeline).
+     * @param skill   The skill to execute.
+     * @param options Optional input mapper and skip condition.
+     */
+    step(name, skill, options) {
+        this._steps.push({
+            name,
+            kind: 'skill',
+            skill,
+            inputMapper: options?.input,
+            skipIf: options?.skipIf,
+        });
+        return this;
+    }
+    /**
+     * Map over an array field, running a sub-pipeline for each item.
+     *
+     * @param sourceField  Dot-path to the array in step outputs (e.g. 'parse.services').
+     *                     Use '*' to use the entire previous step output as array.
+     * @param subPipeline  Sub-pipeline (built or builder) to run per item.
+     * @param options      Concurrency and error handling options.
+     */
+    mapOver(sourceField, subPipeline, options) {
+        const built = subPipeline instanceof PipelineBuilder ? subPipeline.build() : subPipeline;
+        this._steps.push({
+            name: options?.name ?? `map:${sourceField}`,
+            kind: 'map',
+            sourceField,
+            subPipeline: built,
+            concurrency: options?.concurrency ?? 1,
+            onItemError: options?.onItemError ?? 'fail',
+            maxItemRetries: options?.maxItemRetries ?? 0,
+        });
+        return this;
+    }
+    /**
+     * Filter an array field, keeping only items where predicate returns true.
+     */
+    filter(sourceField, predicate, name) {
+        this._steps.push({
+            name: name ?? `filter:${sourceField}`,
+            kind: 'filter',
+            sourceField,
+            predicate,
+        });
+        return this;
+    }
+    /**
+     * Reduce an array field to a single value.
+     */
+    reduce(sourceField, reducer, initialValue, name) {
+        this._steps.push({
+            name: name ?? `reduce:${sourceField}`,
+            kind: 'reduce',
+            sourceField,
+            reducer,
+            initialValue,
+        });
+        return this;
+    }
+    /**
+     * Run multiple sub-pipelines in parallel, collecting all results.
+     */
+    parallel(branches, name) {
+        this._steps.push({
+            name: name ?? 'parallel',
+            kind: 'parallel',
+            branches: branches.map((b) => b instanceof PipelineBuilder ? b.build() : b),
+        });
+        return this;
+    }
+    /**
+     * Conditionally branch: run one of several sub-pipelines based on a condition.
+     */
+    branch(name, condition, // returns branch name
+    branches) {
+        // Implemented as a 'branch' step; orchestrator resolves at runtime
+        this._steps.push({
+            name,
+            kind: 'branch',
+            // Store condition and branches in inputMapper/predicate slots
+            // (Orchestrator handles branch resolution specially)
+            inputMapper: condition,
+            branches: Object.values(branches).map((b) => b instanceof PipelineBuilder ? b.build() : b),
+        });
+        return this;
+    }
+    /** Finalize and return the immutable pipeline definition. */
+    build() {
+        return {
+            name: this._name,
+            steps: [...this._steps],
+            inputSchema: this._inputSchema,
+            outputSchema: this._outputSchema,
+            checkpointing: this._checkpointing,
+        };
+    }
+}
+// ── Public Factory ────────────────────────────────────────────────────────────
+export const Pipeline = {
+    /** Create a new pipeline builder. */
+    create: (name) => new PipelineBuilder(name),
+};
+// ── Utility: resolve a dot-path from step outputs ─────────────────────────────
+export function resolvePath(stepOutputs, path) {
+    if (path === '*')
+        return stepOutputs;
+    const parts = path.split('.');
+    let current = stepOutputs;
+    for (const part of parts) {
+        if (current === null || current === undefined)
+            return undefined;
+        current = current[part];
+    }
+    return current;
+}
+//# sourceMappingURL=pipeline.js.map

package/dist/pipeline.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pipeline.js","sourceRoot":"","sources":["../src/pipeline.ts"],"names":[],"mappings":"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"}