@flomatai/core 0.1.0

package/dist/agent.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Agent — an intelligent orchestrator that composes Skills via a Strategy.
+ *
+ * Agents can spawn sub-agents (hierarchical up to configurable depth).
+ */
+import type { Skill } from './skill.js';
+import type { LLMRegistry } from './llm-provider.js';
+import type { StateStore } from './state/types.js';
+import type { Logger } from './logger.js';
+import { type PlanAndExecuteOptions } from './strategies/plan-and-execute.js';
+import { type ReActOptions } from './strategies/react.js';
+import type { StrategyName, AgentResult, AgentContext, AgentRunner, CustomStrategyFn } from './strategies/types.js';
+export interface AgentConfig {
+    /** Unique name for this agent. */
+    name: string;
+    /**
+     * The agent's role/persona, used as the system prompt for decision-making.
+     * Be specific about what this agent does and what constraints it follows.
+     */
+    role: string;
+    /** Skills this agent can use. */
+    skills: Skill[];
+    /**
+     * Which strategy to use for skill orchestration.
+     * @default 'sequential'
+     */
+    strategy?: StrategyName;
+    /**
+     * The LLM registry key to use for decision-making.
+     * @default 'default'
+     */
+    llm?: string;
+    /**
+     * Max iterations for 'react' strategy.
+     * @default 10
+     */
+    maxIterations?: number;
+    /**
+     * Options for 'plan-and-execute' strategy.
+     */
+    planAndExecuteOptions?: PlanAndExecuteOptions;
+    /**
+     * Options for 'react' strategy.
+     */
+    reactOptions?: ReActOptions;
+    /**
+     * Custom strategy function (used when strategy='custom').
+     */
+    customStrategy?: CustomStrategyFn;
+    /**
+     * Maximum depth of sub-agent spawning (default: inherited from orchestrator).
+     */
+    maxDepth?: number;
+}
+export declare class Agent implements AgentRunner {
+    readonly config: AgentConfig;
+    private readonly strategy;
+    constructor(config: AgentConfig);
+    run(input: unknown, ctx: AgentContext): Promise<AgentResult>;
+    /** Create an AgentContext for standalone execution (outside a pipeline). */
+    createContext(options: {
+        llmRegistry: LLMRegistry;
+        state: StateStore;
+        logger: Logger;
+        config?: Record<string, unknown>;
+        runId?: string;
+        abortController?: AbortController;
+        emit?: (event: string, data: unknown) => void;
+        depth?: number;
+        maxDepth?: number;
+    }): AgentContext;
+}
+export declare const createAgent: (config: AgentConfig) => Agent;
+/** Ergonomic namespace: Agent.create(...) */
+export declare namespace AgentFactory {
+    const create: (config: AgentConfig) => Agent;
+}
+export declare function buildAgentContext(params: {
+    agentName: string;
+    agentRole: string;
+    llmKey: string;
+    llmRegistry: LLMRegistry;
+    state: StateStore;
+    logger: Logger;
+    config: Record<string, unknown>;
+    runId: string;
+    abortSignal: AbortSignal;
+    emit: (event: string, data: unknown) => void;
+    depth: number;
+    maxDepth: number;
+}): AgentContext;
+//# sourceMappingURL=agent.d.ts.map

package/dist/agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../src/agent.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAgB,MAAM,YAAY,CAAC;AACtD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAG1C,OAAO,EAA0B,KAAK,qBAAqB,EAAE,MAAM,kCAAkC,CAAC;AACtG,OAAO,EAAiB,KAAK,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAEzE,OAAO,KAAK,EAEV,YAAY,EACZ,WAAW,EACX,YAAY,EACZ,WAAW,EAEX,gBAAgB,EACjB,MAAM,uBAAuB,CAAC;AAM/B,MAAM,WAAW,WAAW;IAC1B,kCAAkC;IAClC,IAAI,EAAE,MAAM,CAAC;IACb;;;OAGG;IACH,IAAI,EAAE,MAAM,CAAC;IACb,iCAAiC;IACjC,MAAM,EAAE,KAAK,EAAE,CAAC;IAChB;;;OAGG;IACH,QAAQ,CAAC,EAAE,YAAY,CAAC;IACxB;;;OAGG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;OAEG;IACH,qBAAqB,CAAC,EAAE,qBAAqB,CAAC;IAC9C;;OAEG;IACH,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B;;OAEG;IACH,cAAc,CAAC,EAAE,gBAAgB,CAAC;IAClC;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAID,qBAAa,KAAM,YAAW,WAAW;IACvC,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAW;gBAExB,MAAM,EAAE,WAAW;IAKzB,GAAG,CACP,KAAK,EAAE,OAAO,EACd,GAAG,EAAE,YAAY,GAChB,OAAO,CAAC,WAAW,CAAC;IASvB,4EAA4E;IAC5E,aAAa,CAAC,OAAO,EAAE;QACrB,WAAW,EAAE,WAAW,CAAC;QACzB,KAAK,EAAE,UAAU,CAAC;QAClB,MAAM,EAAE,MAAM,CAAC;QACf,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QACjC,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,eAAe,CAAC,EAAE,eAAe,CAAC;QAClC,IAAI,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,KAAK,IAAI,CAAC;QAC9C,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,QAAQ,CAAC,EAAE,MAAM,CAAC;KACnB,GAAG,YAAY;CAgBjB;AAID,eAAO,MAAM,WAAW,GAAI,QAAQ,WAAW,KAAG,KAA0B,CAAC;AAE7E,6CAA6C;AAE7C,yBAAiB,YAAY,CAAC;IACrB,MAAM,MAAM,WALe,WAAW,KAAG,KAKf,CAAC;CACnC;AAID,wBAAgB,iBAAiB,CAAC,MAAM,EAAE;IACxC,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,WAAW,CAAC;IACzB,KAAK,EAAE,UAAU,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,WAAW,CAAC;IACzB,IAAI,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,KAAK,IAAI,CAAC;IAC7C,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;CAClB,GAAG,YAAY,CAqEf"}

package/dist/agent.js

@@ -0,0 +1,137 @@
+/**
+ * Agent — an intelligent orchestrator that composes Skills via a Strategy.
+ *
+ * Agents can spawn sub-agents (hierarchical up to configurable depth).
+ */
+import { SequentialStrategy } from './strategies/sequential.js';
+import { RouterStrategy } from './strategies/router.js';
+import { PlanAndExecuteStrategy } from './strategies/plan-and-execute.js';
+import { ReActStrategy } from './strategies/react.js';
+import { CustomStrategy } from './strategies/custom.js';
+import { AgentMaxDepthError } from './errors.js';
+import { resolveLLM } from './llm-provider.js';
+// ── Agent ─────────────────────────────────────────────────────────────────────
+export class Agent {
+    config;
+    strategy;
+    constructor(config) {
+        this.config = config;
+        this.strategy = resolveStrategy(config);
+    }
+    async run(input, ctx) {
+        ctx.logger.info(`Agent "${this.config.name}" starting`);
+        const result = await this.strategy.execute(this.config.skills, input, ctx);
+        ctx.logger.info(`Agent "${this.config.name}" completed in ${result.durationMs}ms (${result.tokensUsed} tokens)`);
+        return result;
+    }
+    /** Create an AgentContext for standalone execution (outside a pipeline). */
+    createContext(options) {
+        return buildAgentContext({
+            agentName: this.config.name,
+            agentRole: this.config.role,
+            llmKey: this.config.llm ?? 'default',
+            llmRegistry: options.llmRegistry,
+            state: options.state,
+            logger: options.logger.child(this.config.name),
+            config: options.config ?? {},
+            runId: options.runId ?? `agent-${Date.now()}`,
+            abortSignal: options.abortController?.signal ?? new AbortController().signal,
+            emit: options.emit ?? (() => { }),
+            depth: options.depth ?? 0,
+            maxDepth: options.maxDepth ?? 5,
+        });
+    }
+}
+// ── Factory ───────────────────────────────────────────────────────────────────
+export const createAgent = (config) => new Agent(config);
+/** Ergonomic namespace: Agent.create(...) */
+// eslint-disable-next-line @typescript-eslint/no-namespace
+export var AgentFactory;
+(function (AgentFactory) {
+    AgentFactory.create = createAgent;
+})(AgentFactory || (AgentFactory = {}));
+// ── Internal: Context Builder ─────────────────────────────────────────────────
+export function buildAgentContext(params) {
+    let totalTokens = 0;
+    const ctx = {
+        agentName: params.agentName,
+        agentRole: params.agentRole,
+        llm: resolveLLM(params.llmRegistry, params.llmKey),
+        getLLM: (key) => resolveLLM(params.llmRegistry, key),
+        logger: params.logger,
+        state: params.state,
+        config: params.config,
+        abortSignal: params.abortSignal,
+        runId: params.runId,
+        depth: params.depth,
+        maxDepth: params.maxDepth,
+        get totalTokens() { return totalTokens; },
+        addTokens(n) { totalTokens += n; },
+        emit: params.emit,
+        toSkillContext() {
+            return {
+                llm: ctx.llm,
+                logger: ctx.logger,
+                state: ctx.state,
+                emit: ctx.emit,
+                config: ctx.config,
+                abortSignal: ctx.abortSignal,
+                runId: ctx.runId,
+                getLLM: ctx.getLLM,
+            };
+        },
+        spawnAgent(spawnConfig) {
+            if (params.depth >= params.maxDepth) {
+                throw new AgentMaxDepthError(spawnConfig.name, params.maxDepth);
+            }
+            const childAgent = new Agent({
+                name: spawnConfig.name,
+                role: spawnConfig.role,
+                skills: spawnConfig.skills,
+                strategy: spawnConfig.strategy,
+                llm: spawnConfig.llm ?? params.llmKey,
+                maxIterations: spawnConfig.maxIterations,
+                customStrategy: spawnConfig.customStrategy,
+            });
+            const childCtx = buildAgentContext({
+                ...params,
+                agentName: spawnConfig.name,
+                agentRole: spawnConfig.role,
+                llmKey: spawnConfig.llm ?? params.llmKey,
+                logger: params.logger.child(spawnConfig.name),
+                depth: params.depth + 1,
+            });
+            params.emit('agent:spawn', {
+                parent: params.agentName,
+                child: spawnConfig.name,
+                depth: params.depth + 1,
+            });
+            return {
+                run: (input) => childAgent.run(input, childCtx),
+            };
+        },
+    };
+    return ctx;
+}
+// ── Internal: Strategy Resolution ─────────────────────────────────────────────
+function resolveStrategy(config) {
+    const strategyName = config.strategy ?? 'sequential';
+    switch (strategyName) {
+        case 'sequential':
+            return new SequentialStrategy();
+        case 'router':
+            return new RouterStrategy();
+        case 'plan-and-execute':
+            return new PlanAndExecuteStrategy(config.planAndExecuteOptions);
+        case 'react':
+            return new ReActStrategy(config.reactOptions);
+        case 'custom':
+            if (!config.customStrategy) {
+                throw new Error(`Agent "${config.name}": strategy='custom' requires customStrategy function`);
+            }
+            return new CustomStrategy(config.customStrategy);
+        default:
+            throw new Error(`Unknown agent strategy: "${strategyName}"`);
+    }
+}
+//# sourceMappingURL=agent.js.map

package/dist/agent.js.map

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

package/dist/cli-utils.d.ts

@@ -0,0 +1,41 @@
+/**
+ * cli-utils — lightweight CLI argument and input helpers.
+ *
+ * Extracted from the repeated boilerplate found in every example's run.ts.
+ * Covers the three patterns used across all examples:
+ *   • Named flag parsing:  --flag value
+ *   • Boolean flag check:  --flag
+ *   • Text input reading:  --file path | stdin | env var | fallback string
+ */
+/**
+ * Parse a named CLI flag and return its value.
+ *
+ * @example getArg('--topic')  // node run.js --topic "foo" → "foo"
+ */
+export declare function getArg(flag: string): string | undefined;
+/**
+ * Check whether a boolean CLI flag is present.
+ *
+ * @example hasFlag('--mock')  // node run.js --mock → true
+ */
+export declare function hasFlag(flag: string): boolean;
+/**
+ * Read a text document from the first available source:
+ *   1. `--file <path>` CLI flag
+ *   2. `envVar` environment variable (if provided)
+ *   3. stdin (when not a TTY)
+ *   4. `fallback` string (demo/default content)
+ *
+ * Logs a one-line message indicating which source was used.
+ *
+ * @param options.envVar   Environment variable name to check (e.g. 'DOCS').
+ * @param options.fallback Demo text to use when no other source is available.
+ * @param options.label    Human-readable name for the input (e.g. 'documentation').
+ *                         Used in log messages. Defaults to 'input'.
+ */
+export declare function readTextInput(options: {
+    envVar?: string;
+    fallback?: string;
+    label?: string;
+}): Promise<string>;
+//# sourceMappingURL=cli-utils.d.ts.map

package/dist/cli-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-utils.d.ts","sourceRoot":"","sources":["../src/cli-utils.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;;;;GAIG;AACH,wBAAgB,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAGvD;AAED;;;;GAIG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAE7C;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,aAAa,CAAC,OAAO,EAAE;IAC3C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,GAAG,OAAO,CAAC,MAAM,CAAC,CAyBlB"}

package/dist/cli-utils.js

@@ -0,0 +1,64 @@
+/**
+ * cli-utils — lightweight CLI argument and input helpers.
+ *
+ * Extracted from the repeated boilerplate found in every example's run.ts.
+ * Covers the three patterns used across all examples:
+ *   • Named flag parsing:  --flag value
+ *   • Boolean flag check:  --flag
+ *   • Text input reading:  --file path | stdin | env var | fallback string
+ */
+/**
+ * Parse a named CLI flag and return its value.
+ *
+ * @example getArg('--topic')  // node run.js --topic "foo" → "foo"
+ */
+export function getArg(flag) {
+    const idx = process.argv.indexOf(flag);
+    return idx !== -1 ? process.argv[idx + 1] : undefined;
+}
+/**
+ * Check whether a boolean CLI flag is present.
+ *
+ * @example hasFlag('--mock')  // node run.js --mock → true
+ */
+export function hasFlag(flag) {
+    return process.argv.includes(flag);
+}
+/**
+ * Read a text document from the first available source:
+ *   1. `--file <path>` CLI flag
+ *   2. `envVar` environment variable (if provided)
+ *   3. stdin (when not a TTY)
+ *   4. `fallback` string (demo/default content)
+ *
+ * Logs a one-line message indicating which source was used.
+ *
+ * @param options.envVar   Environment variable name to check (e.g. 'DOCS').
+ * @param options.fallback Demo text to use when no other source is available.
+ * @param options.label    Human-readable name for the input (e.g. 'documentation').
+ *                         Used in log messages. Defaults to 'input'.
+ */
+export async function readTextInput(options) {
+    const { envVar, fallback = '', label = 'input' } = options;
+    const filePath = getArg('--file');
+    if (filePath) {
+        const { readFile } = await import('fs/promises');
+        const text = await readFile(filePath, 'utf-8');
+        console.log(`Reading ${label} from: ${filePath}`);
+        return text;
+    }
+    if (envVar && process.env[envVar]) {
+        console.log(`Reading ${label} from ${envVar} env var`);
+        return process.env[envVar];
+    }
+    if (!process.stdin.isTTY) {
+        const chunks = [];
+        for await (const chunk of process.stdin)
+            chunks.push(chunk);
+        console.log(`Reading ${label} from stdin`);
+        return Buffer.concat(chunks).toString('utf-8');
+    }
+    console.log(`Using demo ${label} (pass --file <path> for real ${label})`);
+    return fallback;
+}
+//# sourceMappingURL=cli-utils.js.map

package/dist/cli-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-utils.js","sourceRoot":"","sources":["../src/cli-utils.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;;;;GAIG;AACH,MAAM,UAAU,MAAM,CAAC,IAAY;IACjC,MAAM,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IACvC,OAAO,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;AACxD,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,OAAO,CAAC,IAAY;IAClC,OAAO,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;AACrC,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,OAInC;IACC,MAAM,EAAE,MAAM,EAAE,QAAQ,GAAG,EAAE,EAAE,KAAK,GAAG,OAAO,EAAE,GAAG,OAAO,CAAC;IAE3D,MAAM,QAAQ,GAAG,MAAM,CAAC,QAAQ,CAAC,CAAC;IAClC,IAAI,QAAQ,EAAE,CAAC;QACb,MAAM,EAAE,QAAQ,EAAE,GAAG,MAAM,MAAM,CAAC,aAAa,CAAC,CAAC;QACjD,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;QAC/C,OAAO,CAAC,GAAG,CAAC,WAAW,KAAK,UAAU,QAAQ,EAAE,CAAC,CAAC;QAClD,OAAO,IAAI,CAAC;IACd,CAAC;IAED,IAAI,MAAM,IAAI,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC;QAClC,OAAO,CAAC,GAAG,CAAC,WAAW,KAAK,SAAS,MAAM,UAAU,CAAC,CAAC;QACvD,OAAO,OAAO,CAAC,GAAG,CAAC,MAAM,CAAE,CAAC;IAC9B,CAAC;IAED,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;QACzB,MAAM,MAAM,GAAa,EAAE,CAAC;QAC5B,IAAI,KAAK,EAAE,MAAM,KAAK,IAAI,OAAO,CAAC,KAAK;YAAE,MAAM,CAAC,IAAI,CAAC,KAAe,CAAC,CAAC;QACtE,OAAO,CAAC,GAAG,CAAC,WAAW,KAAK,aAAa,CAAC,CAAC;QAC3C,OAAO,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;IACjD,CAAC;IAED,OAAO,CAAC,GAAG,CAAC,cAAc,KAAK,iCAAiC,KAAK,GAAG,CAAC,CAAC;IAC1E,OAAO,QAAQ,CAAC;AAClB,CAAC"}

package/dist/errors.d.ts

@@ -0,0 +1,52 @@
+/**
+ * flomatai error hierarchy.
+ */
+export declare class FlomatAIError extends Error {
+    readonly code: string;
+    readonly details?: unknown;
+    constructor(message: string, code: string, details?: unknown);
+}
+export declare class SkillError extends FlomatAIError {
+    readonly skillName: string;
+    constructor(skillName: string, message: string, details?: unknown);
+}
+export declare class SkillValidationError extends FlomatAIError {
+    readonly skillName: string;
+    readonly field: 'input' | 'output';
+    constructor(skillName: string, field: 'input' | 'output', message: string, details?: unknown);
+}
+export declare class SkillTimeoutError extends SkillError {
+    readonly timeoutMs: number;
+    constructor(skillName: string, timeoutMs: number);
+}
+export declare class PipelineError extends FlomatAIError {
+    readonly pipelineName: string;
+    readonly stepName?: string;
+    constructor(pipelineName: string, message: string, stepName?: string, details?: unknown);
+}
+export declare class StepMaxRetriesError extends PipelineError {
+    constructor(pipelineName: string, stepName: string, attempts: number, cause: Error);
+}
+export declare class AgentError extends FlomatAIError {
+    readonly agentName: string;
+    constructor(agentName: string, message: string, details?: unknown);
+}
+export declare class AgentMaxIterationsError extends AgentError {
+    constructor(agentName: string, maxIterations: number);
+}
+export declare class AgentMaxDepthError extends AgentError {
+    constructor(agentName: string, maxDepth: number);
+}
+export declare class LLMError extends FlomatAIError {
+    readonly providerName: string;
+    readonly statusCode?: number;
+    constructor(providerName: string, message: string, statusCode?: number, details?: unknown);
+}
+export declare class LLMRateLimitError extends LLMError {
+    readonly retryAfterMs?: number;
+    constructor(providerName: string, retryAfterMs?: number);
+}
+export declare class StateError extends FlomatAIError {
+    constructor(message: string, details?: unknown);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,qBAAa,aAAc,SAAQ,KAAK;IACtC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;gBAEf,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO;CAM7D;AAID,qBAAa,UAAW,SAAQ,aAAa;IAC3C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;gBAEf,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO;CAKlE;AAED,qBAAa,oBAAqB,SAAQ,aAAa;IACrD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,QAAQ,CAAC;gBAGjC,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,OAAO,GAAG,QAAQ,EACzB,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,OAAO;CAOpB;AAED,qBAAa,iBAAkB,SAAQ,UAAU;IAC/C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;gBAEf,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM;CAKjD;AAID,qBAAa,aAAc,SAAQ,aAAa;IAC9C,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;gBAEf,YAAY,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO;CAMxF;AAED,qBAAa,mBAAoB,SAAQ,aAAa;gBACxC,YAAY,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK;CASnF;AAID,qBAAa,UAAW,SAAQ,aAAa;IAC3C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;gBAEf,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO;CAKlE;AAED,qBAAa,uBAAwB,SAAQ,UAAU;gBACzC,SAAS,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM;CAOrD;AAED,qBAAa,kBAAmB,SAAQ,UAAU;gBACpC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM;CAIhD;AAID,qBAAa,QAAS,SAAQ,aAAa;IACzC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;gBAEjB,YAAY,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO;CAM1F;AAED,qBAAa,iBAAkB,SAAQ,QAAQ;IAC7C,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;gBAEnB,YAAY,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,MAAM;CASxD;AAID,qBAAa,UAAW,SAAQ,aAAa;gBAC/B,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO;CAI/C"}

package/dist/errors.js

@@ -0,0 +1,105 @@
+/**
+ * flomatai error hierarchy.
+ */
+export class FlomatAIError extends Error {
+    code;
+    details;
+    constructor(message, code, details) {
+        super(message);
+        this.name = 'FlomatAIError';
+        this.code = code;
+        this.details = details;
+    }
+}
+// ── Skill Errors ─────────────────────────────────────────────────────────────
+export class SkillError extends FlomatAIError {
+    skillName;
+    constructor(skillName, message, details) {
+        super(message, 'SKILL_ERROR', details);
+        this.name = 'SkillError';
+        this.skillName = skillName;
+    }
+}
+export class SkillValidationError extends FlomatAIError {
+    skillName;
+    field;
+    constructor(skillName, field, message, details) {
+        super(message, 'SKILL_VALIDATION_ERROR', details);
+        this.name = 'SkillValidationError';
+        this.skillName = skillName;
+        this.field = field;
+    }
+}
+export class SkillTimeoutError extends SkillError {
+    timeoutMs;
+    constructor(skillName, timeoutMs) {
+        super(skillName, `Skill "${skillName}" timed out after ${timeoutMs}ms`);
+        this.name = 'SkillTimeoutError';
+        this.timeoutMs = timeoutMs;
+    }
+}
+// ── Pipeline Errors ──────────────────────────────────────────────────────────
+export class PipelineError extends FlomatAIError {
+    pipelineName;
+    stepName;
+    constructor(pipelineName, message, stepName, details) {
+        super(message, 'PIPELINE_ERROR', details);
+        this.name = 'PipelineError';
+        this.pipelineName = pipelineName;
+        this.stepName = stepName;
+    }
+}
+export class StepMaxRetriesError extends PipelineError {
+    constructor(pipelineName, stepName, attempts, cause) {
+        super(pipelineName, `Step "${stepName}" failed after ${attempts} attempts: ${cause.message}`, stepName, { cause });
+        this.name = 'StepMaxRetriesError';
+    }
+}
+// ── Agent Errors ─────────────────────────────────────────────────────────────
+export class AgentError extends FlomatAIError {
+    agentName;
+    constructor(agentName, message, details) {
+        super(message, 'AGENT_ERROR', details);
+        this.name = 'AgentError';
+        this.agentName = agentName;
+    }
+}
+export class AgentMaxIterationsError extends AgentError {
+    constructor(agentName, maxIterations) {
+        super(agentName, `Agent "${agentName}" hit max iterations (${maxIterations}) without finishing`);
+        this.name = 'AgentMaxIterationsError';
+    }
+}
+export class AgentMaxDepthError extends AgentError {
+    constructor(agentName, maxDepth) {
+        super(agentName, `Agent hierarchy exceeded max depth (${maxDepth})`);
+        this.name = 'AgentMaxDepthError';
+    }
+}
+// ── LLM Errors ───────────────────────────────────────────────────────────────
+export class LLMError extends FlomatAIError {
+    providerName;
+    statusCode;
+    constructor(providerName, message, statusCode, details) {
+        super(message, 'LLM_ERROR', details);
+        this.name = 'LLMError';
+        this.providerName = providerName;
+        this.statusCode = statusCode;
+    }
+}
+export class LLMRateLimitError extends LLMError {
+    retryAfterMs;
+    constructor(providerName, retryAfterMs) {
+        super(providerName, `Rate limit exceeded for provider "${providerName}"${retryAfterMs ? `. Retry after ${retryAfterMs}ms` : ''}`, 429);
+        this.name = 'LLMRateLimitError';
+        this.retryAfterMs = retryAfterMs;
+    }
+}
+// ── State Errors ─────────────────────────────────────────────────────────────
+export class StateError extends FlomatAIError {
+    constructor(message, details) {
+        super(message, 'STATE_ERROR', details);
+        this.name = 'StateError';
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,29 @@
+/**
+ * @flomatai/core — public API
+ */
+export type { Message, MessageRole, LLMOptions, LLMResponse, LLMChunk, ToolDefinition, ToolCall, PipelineRun, StepRecord, RunStatus, } from './types.js';
+export { FlomatAIError, SkillError, SkillValidationError, SkillTimeoutError, PipelineError, StepMaxRetriesError, AgentError, AgentMaxIterationsError, AgentMaxDepthError, LLMError, LLMRateLimitError, StateError, } from './errors.js';
+export { Logger, logger, type LogLevel, type LogEntry, type LogTransport } from './logger.js';
+export type { LLMProvider, LLMRegistry } from './llm-provider.js';
+export { resolveLLM, withRetry, withTimeout } from './llm-provider.js';
+export type { Skill, SkillMeta, SkillContext, SkillResult, MCPClientLike } from './skill.js';
+export { LLMSkill, createLLMSkill, type LLMSkillConfig } from './skills/llm-skill.js';
+export { TransformSkill, createTransformSkill, type TransformSkillConfig } from './skills/transform-skill.js';
+export { IOSkill, createHttpGetSkill, createHttpPostSkill, createReadFileSkill, createWriteFileSkill, } from './skills/io-skill.js';
+export { Pipeline, PipelineBuilder, resolvePath, type BuiltPipeline, type PipelineStep, type StepInputContext, type StepKind, } from './pipeline.js';
+export { PipelineRegistry, loadPipeline, createRegistryFromConfig, type PipelineSource, type RegisteredPipeline, type PipelinePackageMeta, type PipelinePackageExports, } from './pipeline-registry.js';
+export type { StateStore, RunFilter } from './state/types.js';
+export { MemoryStore } from './state/memory-store.js';
+export { FileStore } from './state/file-store.js';
+export { Agent, createAgent, type AgentConfig } from './agent.js';
+export type { AgentContext, AgentResult, AgentTraceEntry, AgentRunner, SpawnAgentConfig, StrategyName, CustomStrategyFn, Strategy, } from './strategies/types.js';
+export { SequentialStrategy } from './strategies/sequential.js';
+export { RouterStrategy } from './strategies/router.js';
+export { PlanAndExecuteStrategy, type PlanAndExecuteOptions } from './strategies/plan-and-execute.js';
+export { ReActStrategy, type ReActOptions } from './strategies/react.js';
+export { CustomStrategy } from './strategies/custom.js';
+export { Orchestrator, type OrchestratorConfig, type OrchestratorHooks, type RunOptions, } from './orchestrator.js';
+export { createConsoleHooks } from './orchestrator-helpers.js';
+export { getArg, hasFlag, readTextInput } from './cli-utils.js';
+export { MockLLMProvider, createTestLLM, createMockLLMRegistry, createTestOrchestrator, type MockResponse, } from './mock-llm.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,YAAY,EACV,OAAO,EACP,WAAW,EACX,UAAU,EACV,WAAW,EACX,QAAQ,EACR,cAAc,EACd,QAAQ,EACR,WAAW,EACX,UAAU,EACV,SAAS,GACV,MAAM,YAAY,CAAC;AAGpB,OAAO,EACL,aAAa,EACb,UAAU,EACV,oBAAoB,EACpB,iBAAiB,EACjB,aAAa,EACb,mBAAmB,EACnB,UAAU,EACV,uBAAuB,EACvB,kBAAkB,EAClB,QAAQ,EACR,iBAAiB,EACjB,UAAU,GACX,MAAM,aAAa,CAAC;AAGrB,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,QAAQ,EAAE,KAAK,QAAQ,EAAE,KAAK,YAAY,EAAE,MAAM,aAAa,CAAC;AAG9F,YAAY,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAClE,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAGvE,YAAY,EAAE,KAAK,EAAE,SAAS,EAAE,YAAY,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAG7F,OAAO,EAAE,QAAQ,EAAE,cAAc,EAAE,KAAK,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACtF,OAAO,EAAE,cAAc,EAAE,oBAAoB,EAAE,KAAK,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AAC9G,OAAO,EACL,OAAO,EACP,kBAAkB,EAClB,mBAAmB,EACnB,mBAAmB,EACnB,oBAAoB,GACrB,MAAM,sBAAsB,CAAC;AAG9B,OAAO,EACL,QAAQ,EACR,eAAe,EACf,WAAW,EACX,KAAK,aAAa,EAClB,KAAK,YAAY,EACjB,KAAK,gBAAgB,EACrB,KAAK,QAAQ,GACd,MAAM,eAAe,CAAC;AAGvB,OAAO,EACL,gBAAgB,EAChB,YAAY,EACZ,wBAAwB,EACxB,KAAK,cAAc,EACnB,KAAK,kBAAkB,EACvB,KAAK,mBAAmB,EACxB,KAAK,sBAAsB,GAC5B,MAAM,wBAAwB,CAAC;AAGhC,YAAY,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC9D,OAAO,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AACtD,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAGlD,OAAO,EAAE,KAAK,EAAE,WAAW,EAAE,KAAK,WAAW,EAAE,MAAM,YAAY,CAAC;AAClE,YAAY,EACV,YAAY,EACZ,WAAW,EACX,eAAe,EACf,WAAW,EACX,gBAAgB,EAChB,YAAY,EACZ,gBAAgB,EAChB,QAAQ,GACT,MAAM,uBAAuB,CAAC;AAG/B,OAAO,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AAChE,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AACxD,OAAO,EAAE,sBAAsB,EAAE,KAAK,qBAAqB,EAAE,MAAM,kCAAkC,CAAC;AACtG,OAAO,EAAE,aAAa,EAAE,KAAK,YAAY,EAAE,MAAM,uBAAuB,CAAC;AACzE,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAGxD,OAAO,EACL,YAAY,EACZ,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,EACtB,KAAK,UAAU,GAChB,MAAM,mBAAmB,CAAC;AAG3B,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAG/D,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAGhE,OAAO,EACL,eAAe,EACf,aAAa,EACb,qBAAqB,EACrB,sBAAsB,EACtB,KAAK,YAAY,GAClB,MAAM,eAAe,CAAC"}

package/dist/index.js

@@ -0,0 +1,35 @@
+/**
+ * @flomatai/core — public API
+ */
+// ── Errors ────────────────────────────────────────────────────────────────────
+export { FlomatAIError, SkillError, SkillValidationError, SkillTimeoutError, PipelineError, StepMaxRetriesError, AgentError, AgentMaxIterationsError, AgentMaxDepthError, LLMError, LLMRateLimitError, StateError, } from './errors.js';
+// ── Logger ────────────────────────────────────────────────────────────────────
+export { Logger, logger } from './logger.js';
+export { resolveLLM, withRetry, withTimeout } from './llm-provider.js';
+// ── Skill Builders ────────────────────────────────────────────────────────────
+export { LLMSkill, createLLMSkill } from './skills/llm-skill.js';
+export { TransformSkill, createTransformSkill } from './skills/transform-skill.js';
+export { IOSkill, createHttpGetSkill, createHttpPostSkill, createReadFileSkill, createWriteFileSkill, } from './skills/io-skill.js';
+// ── Pipeline ──────────────────────────────────────────────────────────────────
+export { Pipeline, PipelineBuilder, resolvePath, } from './pipeline.js';
+// ── Pipeline Registry ─────────────────────────────────────────────────────────
+export { PipelineRegistry, loadPipeline, createRegistryFromConfig, } from './pipeline-registry.js';
+export { MemoryStore } from './state/memory-store.js';
+export { FileStore } from './state/file-store.js';
+// ── Agent ─────────────────────────────────────────────────────────────────────
+export { Agent, createAgent } from './agent.js';
+// Strategy classes (for custom usage)
+export { SequentialStrategy } from './strategies/sequential.js';
+export { RouterStrategy } from './strategies/router.js';
+export { PlanAndExecuteStrategy } from './strategies/plan-and-execute.js';
+export { ReActStrategy } from './strategies/react.js';
+export { CustomStrategy } from './strategies/custom.js';
+// ── Orchestrator ──────────────────────────────────────────────────────────────
+export { Orchestrator, } from './orchestrator.js';
+// ── Orchestrator helpers ──────────────────────────────────────────────────────
+export { createConsoleHooks } from './orchestrator-helpers.js';
+// ── CLI utilities ─────────────────────────────────────────────────────────────
+export { getArg, hasFlag, readTextInput } from './cli-utils.js';
+// ── Testing / Mock ────────────────────────────────────────────────────────────
+export { MockLLMProvider, createTestLLM, createMockLLMRegistry, createTestOrchestrator, } from './mock-llm.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAgBH,iFAAiF;AACjF,OAAO,EACL,aAAa,EACb,UAAU,EACV,oBAAoB,EACpB,iBAAiB,EACjB,aAAa,EACb,mBAAmB,EACnB,UAAU,EACV,uBAAuB,EACvB,kBAAkB,EAClB,QAAQ,EACR,iBAAiB,EACjB,UAAU,GACX,MAAM,aAAa,CAAC;AAErB,iFAAiF;AACjF,OAAO,EAAE,MAAM,EAAE,MAAM,EAAmD,MAAM,aAAa,CAAC;AAI9F,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAKvE,iFAAiF;AACjF,OAAO,EAAE,QAAQ,EAAE,cAAc,EAAuB,MAAM,uBAAuB,CAAC;AACtF,OAAO,EAAE,cAAc,EAAE,oBAAoB,EAA6B,MAAM,6BAA6B,CAAC;AAC9G,OAAO,EACL,OAAO,EACP,kBAAkB,EAClB,mBAAmB,EACnB,mBAAmB,EACnB,oBAAoB,GACrB,MAAM,sBAAsB,CAAC;AAE9B,iFAAiF;AACjF,OAAO,EACL,QAAQ,EACR,eAAe,EACf,WAAW,GAKZ,MAAM,eAAe,CAAC;AAEvB,iFAAiF;AACjF,OAAO,EACL,gBAAgB,EAChB,YAAY,EACZ,wBAAwB,GAKzB,MAAM,wBAAwB,CAAC;AAIhC,OAAO,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AACtD,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAElD,iFAAiF;AACjF,OAAO,EAAE,KAAK,EAAE,WAAW,EAAoB,MAAM,YAAY,CAAC;AAYlE,sCAAsC;AACtC,OAAO,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AAChE,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AACxD,OAAO,EAAE,sBAAsB,EAA8B,MAAM,kCAAkC,CAAC;AACtG,OAAO,EAAE,aAAa,EAAqB,MAAM,uBAAuB,CAAC;AACzE,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAExD,iFAAiF;AACjF,OAAO,EACL,YAAY,GAIb,MAAM,mBAAmB,CAAC;AAE3B,iFAAiF;AACjF,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAE/D,iFAAiF;AACjF,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAEhE,iFAAiF;AACjF,OAAO,EACL,eAAe,EACf,aAAa,EACb,qBAAqB,EACrB,sBAAsB,GAEvB,MAAM,eAAe,CAAC"}

package/dist/llm-provider.d.ts

@@ -0,0 +1,29 @@
+/**
+ * LLMProvider abstraction — the universal interface for all AI model providers.
+ *
+ * Implementations live in @flomatai/provider-* packages.
+ */
+import type { Message, LLMOptions, LLMResponse, LLMChunk } from './types.js';
+export interface LLMProvider {
+    /** Identifier for this provider (e.g. 'anthropic', 'openai', 'ollama'). */
+    readonly name: string;
+    /** The model being used (e.g. 'claude-3-5-sonnet-20241022'). */
+    readonly model: string;
+    /**
+     * Send a chat completion request and await the full response.
+     */
+    chat(messages: Message[], options?: LLMOptions): Promise<LLMResponse>;
+    /**
+     * Stream a chat completion. Yields chunks as they arrive.
+     */
+    stream(messages: Message[], options?: LLMOptions): AsyncIterable<LLMChunk>;
+}
+/**
+ * A named registry of LLM providers.
+ * The 'default' key is used when no specific provider is requested.
+ */
+export type LLMRegistry = Record<string, LLMProvider>;
+export declare function resolveLLM(registry: LLMRegistry, key?: string): LLMProvider;
+export declare function withRetry<T>(fn: () => Promise<T>, retries: number, onRetry?: (attempt: number, error: Error) => void): Promise<T>;
+export declare function withTimeout<T>(fn: () => Promise<T>, timeoutMs: number, label: string): Promise<T>;
+//# sourceMappingURL=llm-provider.d.ts.map