@flomatai/core 0.1.0

package/src/strategies/types.ts

@@ -0,0 +1,97 @@
+/**
+ * Agent strategy types — shared across all strategy implementations.
+ */
+
+import type { Skill, SkillContext } from '../skill.js';
+import type { LLMProvider } from '../llm-provider.js';
+import type { Logger } from '../logger.js';
+import type { StateStore } from '../state/types.js';
+
+// ── Agent Trace ───────────────────────────────────────────────────────────────
+
+export type AgentTraceEntryType =
+  | 'thought'
+  | 'action'
+  | 'observation'
+  | 'plan'
+  | 'replan'
+  | 'reflection'
+  | 'finish'
+  | 'route'
+  | 'spawn';
+
+export interface AgentTraceEntry {
+  type: AgentTraceEntryType;
+  iteration?: number;
+  skill?: string;
+  input?: unknown;
+  output?: unknown;
+  content?: unknown;
+  timestamp: string;
+}
+
+// ── Agent Result ──────────────────────────────────────────────────────────────
+
+export interface AgentResult {
+  output: unknown;
+  trace: AgentTraceEntry[];
+  tokensUsed: number;
+  durationMs: number;
+}
+
+// ── Agent Context ─────────────────────────────────────────────────────────────
+
+export interface AgentContext {
+  agentName: string;
+  agentRole: string;
+  llm: LLMProvider;
+  getLLM: (key: string) => LLMProvider;
+  logger: Logger;
+  state: StateStore;
+  config: Record<string, unknown>;
+  abortSignal: AbortSignal;
+  runId: string;
+  depth: number;
+  maxDepth: number;
+  totalTokens: number;
+  addTokens: (n: number) => void;
+  emit: (event: string, data: unknown) => void;
+  /** Spawn a sub-agent. */
+  spawnAgent: (config: SpawnAgentConfig) => AgentRunner;
+  /** Get a SkillContext from this AgentContext. */
+  toSkillContext(): SkillContext;
+}
+
+export interface SpawnAgentConfig {
+  name: string;
+  role: string;
+  skills: Skill[];
+  strategy: StrategyName;
+  llm?: string;
+  maxIterations?: number;
+  customStrategy?: CustomStrategyFn;
+}
+
+export type StrategyName =
+  | 'sequential'
+  | 'router'
+  | 'plan-and-execute'
+  | 'react'
+  | 'custom';
+
+export type CustomStrategyFn = (
+  skills: Skill[],
+  input: unknown,
+  ctx: AgentContext,
+) => Promise<AgentResult>;
+
+// ── Strategy Interface ────────────────────────────────────────────────────────
+
+export interface Strategy {
+  execute(skills: Skill[], input: unknown, ctx: AgentContext): Promise<AgentResult>;
+}
+
+/** Minimal agent runner interface (to avoid circular imports). */
+export interface AgentRunner {
+  run(input: unknown, ctx: AgentContext): Promise<AgentResult>;
+}

package/src/types.ts

@@ -0,0 +1,102 @@
+/**
+ * Core shared types used across all flomatai packages.
+ */
+
+// ── LLM Messages ────────────────────────────────────────────────────────────
+
+export type MessageRole = 'system' | 'user' | 'assistant' | 'tool';
+
+export interface Message {
+  role: MessageRole;
+  content: string;
+  name?: string;       // for tool messages
+  toolCallId?: string; // for tool result messages
+}
+
+// ── LLM Options ─────────────────────────────────────────────────────────────
+
+export interface LLMOptions {
+  /** Sampling temperature (0-2). Lower = more deterministic. */
+  temperature?: number;
+  /** Maximum tokens to generate. */
+  maxTokens?: number;
+  /** Force JSON output mode if supported by provider. */
+  responseFormat?: 'text' | 'json';
+  /** Tool definitions for function calling. */
+  tools?: ToolDefinition[];
+  /** Stop sequences. */
+  stop?: string[];
+  /** Timeout in milliseconds. */
+  timeout?: number;
+  /** Number of retry attempts on failure. */
+  retries?: number;
+}
+
+// ── LLM Response ────────────────────────────────────────────────────────────
+
+export interface LLMResponse {
+  /** The generated text content. */
+  content: string;
+  /** Model identifier used. */
+  model: string;
+  /** Token usage statistics. */
+  usage: {
+    inputTokens: number;
+    outputTokens: number;
+    totalTokens: number;
+  };
+  /** Stop reason from the model. */
+  stopReason?: 'stop' | 'max_tokens' | 'tool_use' | string;
+  /** Tool calls requested by the model. */
+  toolCalls?: ToolCall[];
+}
+
+export interface LLMChunk {
+  content: string;
+  done: boolean;
+}
+
+// ── Tools / Function Calling ─────────────────────────────────────────────────
+
+export interface ToolDefinition {
+  name: string;
+  description: string;
+  parameters: Record<string, unknown>; // JSON Schema object
+}
+
+export interface ToolCall {
+  id: string;
+  name: string;
+  arguments: Record<string, unknown>;
+}
+
+// ── Run / Execution ──────────────────────────────────────────────────────────
+
+export type RunStatus = 'pending' | 'running' | 'completed' | 'failed' | 'cancelled';
+
+export interface PipelineRun {
+  id: string;
+  pipelineName: string;
+  status: RunStatus;
+  input: unknown;
+  output?: unknown;
+  error?: string;
+  startedAt: string;   // ISO 8601
+  completedAt?: string;
+  durationMs?: number;
+  tokensUsed: number;
+  steps: StepRecord[];
+}
+
+export interface StepRecord {
+  name: string;
+  status: RunStatus;
+  input?: unknown;
+  output?: unknown;
+  error?: string;
+  startedAt: string;
+  completedAt?: string;
+  durationMs?: number;
+  tokensUsed: number;
+  attempt: number;
+}

package/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./src"
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}