@flomatai/core 0.1.0

package/src/agent.ts

@@ -0,0 +1,243 @@
+/**
+ * Agent — an intelligent orchestrator that composes Skills via a Strategy.
+ *
+ * Agents can spawn sub-agents (hierarchical up to configurable depth).
+ */
+
+import type { Skill, SkillContext } from './skill.js';
+import type { LLMRegistry } from './llm-provider.js';
+import type { StateStore } from './state/types.js';
+import type { Logger } from './logger.js';
+import { SequentialStrategy } from './strategies/sequential.js';
+import { RouterStrategy } from './strategies/router.js';
+import { PlanAndExecuteStrategy, type PlanAndExecuteOptions } from './strategies/plan-and-execute.js';
+import { ReActStrategy, type ReActOptions } from './strategies/react.js';
+import { CustomStrategy } from './strategies/custom.js';
+import type {
+  Strategy,
+  StrategyName,
+  AgentResult,
+  AgentContext,
+  AgentRunner,
+  SpawnAgentConfig,
+  CustomStrategyFn,
+} from './strategies/types.js';
+import { AgentMaxDepthError } from './errors.js';
+import { resolveLLM } from './llm-provider.js';
+
+// ── Agent Config ──────────────────────────────────────────────────────────────
+
+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;
+}
+
+// ── Agent ─────────────────────────────────────────────────────────────────────
+
+export class Agent implements AgentRunner {
+  readonly config: AgentConfig;
+  private readonly strategy: Strategy;
+
+  constructor(config: AgentConfig) {
+    this.config = config;
+    this.strategy = resolveStrategy(config);
+  }
+
+  async run(
+    input: unknown,
+    ctx: AgentContext,
+  ): Promise<AgentResult> {
+    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: {
+    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 {
+    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: AgentConfig): Agent => new Agent(config);
+
+/** Ergonomic namespace: Agent.create(...) */
+// eslint-disable-next-line @typescript-eslint/no-namespace
+export namespace AgentFactory {
+  export const create = createAgent;
+}
+
+// ── Internal: Context Builder ─────────────────────────────────────────────────
+
+export 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 {
+  let totalTokens = 0;
+
+  const ctx: AgentContext = {
+    agentName: params.agentName,
+    agentRole: params.agentRole,
+    llm: resolveLLM(params.llmRegistry, params.llmKey),
+    getLLM: (key: string) => 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: number) { totalTokens += n; },
+    emit: params.emit,
+
+    toSkillContext(): SkillContext {
+      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: SpawnAgentConfig): AgentRunner {
+      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: unknown) => childAgent.run(input, childCtx),
+      };
+    },
+  };
+
+  return ctx;
+}
+
+// ── Internal: Strategy Resolution ─────────────────────────────────────────────
+
+function resolveStrategy(config: AgentConfig): Strategy {
+  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 as string}"`);
+  }
+}

package/src/cli-utils.ts

@@ -0,0 +1,73 @@
+/**
+ * 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: string): string | undefined {
+  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: string): boolean {
+  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: {
+  envVar?: string;
+  fallback?: string;
+  label?: string;
+}): Promise<string> {
+  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: Buffer[] = [];
+    for await (const chunk of process.stdin) chunks.push(chunk as Buffer);
+    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;
+}

package/src/errors.ts

@@ -0,0 +1,146 @@
+/**
+ * flomatai error hierarchy.
+ */
+
+export class FlomatAIError extends Error {
+  readonly code: string;
+  readonly details?: unknown;
+
+  constructor(message: string, code: string, details?: unknown) {
+    super(message);
+    this.name = 'FlomatAIError';
+    this.code = code;
+    this.details = details;
+  }
+}
+
+// ── Skill Errors ─────────────────────────────────────────────────────────────
+
+export class SkillError extends FlomatAIError {
+  readonly skillName: string;
+
+  constructor(skillName: string, message: string, details?: unknown) {
+    super(message, 'SKILL_ERROR', details);
+    this.name = 'SkillError';
+    this.skillName = skillName;
+  }
+}
+
+export class SkillValidationError extends FlomatAIError {
+  readonly skillName: string;
+  readonly field: 'input' | 'output';
+
+  constructor(
+    skillName: string,
+    field: 'input' | 'output',
+    message: string,
+    details?: unknown,
+  ) {
+    super(message, 'SKILL_VALIDATION_ERROR', details);
+    this.name = 'SkillValidationError';
+    this.skillName = skillName;
+    this.field = field;
+  }
+}
+
+export class SkillTimeoutError extends SkillError {
+  readonly timeoutMs: number;
+
+  constructor(skillName: string, timeoutMs: number) {
+    super(skillName, `Skill "${skillName}" timed out after ${timeoutMs}ms`);
+    this.name = 'SkillTimeoutError';
+    this.timeoutMs = timeoutMs;
+  }
+}
+
+// ── Pipeline Errors ──────────────────────────────────────────────────────────
+
+export class PipelineError extends FlomatAIError {
+  readonly pipelineName: string;
+  readonly stepName?: string;
+
+  constructor(pipelineName: string, message: string, stepName?: string, details?: unknown) {
+    super(message, 'PIPELINE_ERROR', details);
+    this.name = 'PipelineError';
+    this.pipelineName = pipelineName;
+    this.stepName = stepName;
+  }
+}
+
+export class StepMaxRetriesError extends PipelineError {
+  constructor(pipelineName: string, stepName: string, attempts: number, cause: Error) {
+    super(
+      pipelineName,
+      `Step "${stepName}" failed after ${attempts} attempts: ${cause.message}`,
+      stepName,
+      { cause },
+    );
+    this.name = 'StepMaxRetriesError';
+  }
+}
+
+// ── Agent Errors ─────────────────────────────────────────────────────────────
+
+export class AgentError extends FlomatAIError {
+  readonly agentName: string;
+
+  constructor(agentName: string, message: string, details?: unknown) {
+    super(message, 'AGENT_ERROR', details);
+    this.name = 'AgentError';
+    this.agentName = agentName;
+  }
+}
+
+export class AgentMaxIterationsError extends AgentError {
+  constructor(agentName: string, maxIterations: number) {
+    super(
+      agentName,
+      `Agent "${agentName}" hit max iterations (${maxIterations}) without finishing`,
+    );
+    this.name = 'AgentMaxIterationsError';
+  }
+}
+
+export class AgentMaxDepthError extends AgentError {
+  constructor(agentName: string, maxDepth: number) {
+    super(agentName, `Agent hierarchy exceeded max depth (${maxDepth})`);
+    this.name = 'AgentMaxDepthError';
+  }
+}
+
+// ── LLM Errors ───────────────────────────────────────────────────────────────
+
+export class LLMError extends FlomatAIError {
+  readonly providerName: string;
+  readonly statusCode?: number;
+
+  constructor(providerName: string, message: string, statusCode?: number, details?: unknown) {
+    super(message, 'LLM_ERROR', details);
+    this.name = 'LLMError';
+    this.providerName = providerName;
+    this.statusCode = statusCode;
+  }
+}
+
+export class LLMRateLimitError extends LLMError {
+  readonly retryAfterMs?: number;
+
+  constructor(providerName: string, retryAfterMs?: number) {
+    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: string, details?: unknown) {
+    super(message, 'STATE_ERROR', details);
+    this.name = 'StateError';
+  }
+}

package/src/index.ts

@@ -0,0 +1,124 @@
+/**
+ * @flomatai/core — public API
+ */
+
+// ── Types ─────────────────────────────────────────────────────────────────────
+export type {
+  Message,
+  MessageRole,
+  LLMOptions,
+  LLMResponse,
+  LLMChunk,
+  ToolDefinition,
+  ToolCall,
+  PipelineRun,
+  StepRecord,
+  RunStatus,
+} from './types.js';
+
+// ── Errors ────────────────────────────────────────────────────────────────────
+export {
+  FlomatAIError,
+  SkillError,
+  SkillValidationError,
+  SkillTimeoutError,
+  PipelineError,
+  StepMaxRetriesError,
+  AgentError,
+  AgentMaxIterationsError,
+  AgentMaxDepthError,
+  LLMError,
+  LLMRateLimitError,
+  StateError,
+} from './errors.js';
+
+// ── Logger ────────────────────────────────────────────────────────────────────
+export { Logger, logger, type LogLevel, type LogEntry, type LogTransport } from './logger.js';
+
+// ── LLM Provider ──────────────────────────────────────────────────────────────
+export type { LLMProvider, LLMRegistry } from './llm-provider.js';
+export { resolveLLM, withRetry, withTimeout } from './llm-provider.js';
+
+// ── Skill ─────────────────────────────────────────────────────────────────────
+export type { Skill, SkillMeta, SkillContext, SkillResult, MCPClientLike } from './skill.js';
+
+// ── Skill Builders ────────────────────────────────────────────────────────────
+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';
+
+// ── Pipeline ──────────────────────────────────────────────────────────────────
+export {
+  Pipeline,
+  PipelineBuilder,
+  resolvePath,
+  type BuiltPipeline,
+  type PipelineStep,
+  type StepInputContext,
+  type StepKind,
+} from './pipeline.js';
+
+// ── Pipeline Registry ─────────────────────────────────────────────────────────
+export {
+  PipelineRegistry,
+  loadPipeline,
+  createRegistryFromConfig,
+  type PipelineSource,
+  type RegisteredPipeline,
+  type PipelinePackageMeta,
+  type PipelinePackageExports,
+} from './pipeline-registry.js';
+
+// ── State ─────────────────────────────────────────────────────────────────────
+export type { StateStore, RunFilter } from './state/types.js';
+export { MemoryStore } from './state/memory-store.js';
+export { FileStore } from './state/file-store.js';
+
+// ── Agent ─────────────────────────────────────────────────────────────────────
+export { Agent, createAgent, type AgentConfig } from './agent.js';
+export type {
+  AgentContext,
+  AgentResult,
+  AgentTraceEntry,
+  AgentRunner,
+  SpawnAgentConfig,
+  StrategyName,
+  CustomStrategyFn,
+  Strategy,
+} from './strategies/types.js';
+
+// Strategy classes (for custom usage)
+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';
+
+// ── Orchestrator ──────────────────────────────────────────────────────────────
+export {
+  Orchestrator,
+  type OrchestratorConfig,
+  type OrchestratorHooks,
+  type RunOptions,
+} 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,
+  type MockResponse,
+} from './mock-llm.js';

package/src/llm-provider.ts

@@ -0,0 +1,88 @@
+/**
+ * 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';
+
+// ── Core Provider Interface ───────────────────────────────────────────────────
+
+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>;
+}
+
+// ── LLM Registry ─────────────────────────────────────────────────────────────
+
+/**
+ * A named registry of LLM providers.
+ * The 'default' key is used when no specific provider is requested.
+ */
+export type LLMRegistry = Record<string, LLMProvider>;
+
+export function resolveLLM(registry: LLMRegistry, key?: string): LLMProvider {
+  const resolved = key
+    ? (registry[key] ?? registry['default'])
+    : registry['default'];
+
+  if (!resolved) {
+    throw new Error(
+      `LLM provider "${key ?? 'default'}" not found in registry. ` +
+      `Available: ${Object.keys(registry).join(', ')}`,
+    );
+  }
+  return resolved;
+}
+
+// ── Utility: retry wrapper for LLM calls ─────────────────────────────────────
+
+export async function withRetry<T>(
+  fn: () => Promise<T>,
+  retries: number,
+  onRetry?: (attempt: number, error: Error) => void,
+): Promise<T> {
+  let lastError: Error = new Error('Unknown error');
+  for (let attempt = 1; attempt <= retries + 1; attempt++) {
+    try {
+      return await fn();
+    } catch (err) {
+      lastError = err instanceof Error ? err : new Error(String(err));
+      if (attempt <= retries) {
+        // Exponential backoff: 500ms, 1000ms, 2000ms, ...
+        const delay = Math.min(500 * Math.pow(2, attempt - 1), 10_000);
+        onRetry?.(attempt, lastError);
+        await new Promise((r) => setTimeout(r, delay));
+      }
+    }
+  }
+  throw lastError;
+}
+
+// ── Utility: timeout wrapper ──────────────────────────────────────────────────
+
+export async function withTimeout<T>(
+  fn: () => Promise<T>,
+  timeoutMs: number,
+  label: string,
+): Promise<T> {
+  return new Promise<T>((resolve, reject) => {
+    const timer = setTimeout(
+      () => reject(new Error(`"${label}" timed out after ${timeoutMs}ms`)),
+      timeoutMs,
+    );
+    fn()
+      .then((result) => { clearTimeout(timer); resolve(result); })
+      .catch((err) => { clearTimeout(timer); reject(err); });
+  });
+}