confused-ai-core 0.1.0

package/src/sdk/index.ts

@@ -0,0 +1,374 @@
+/**
+ * SDK for building agents with a fluent API
+ *
+ * This module provides a high-level, chainable API for creating and configuring
+ * agents, making it easy for developers to get started quickly.
+ */
+
+import { z } from 'zod';
+import {
+    Agent,
+    AgentConfig,
+    AgentContext,
+    AgentInput,
+    AgentOutput,
+    AgentState,
+    BaseAgent,
+} from '../core/index.js';
+import { MemoryStore, InMemoryStore } from '../memory/index.js';
+import { ToolRegistry, ToolRegistryImpl, Tool } from '../tools/index.js';
+import { Planner, ClassicalPlanner, PlanningAlgorithm } from '../planner/index.js';
+import { ExecutionEngine, ExecutionEngineImpl } from '../execution/index.js';
+
+/**
+ * Agent definition configuration
+ */
+export interface AgentDefinitionConfig<TInput, TOutput> {
+    name: string;
+    description?: string;
+    inputSchema: z.ZodType<TInput>;
+    outputSchema: z.ZodType<TOutput>;
+    tools?: Tool[];
+    memory?: MemoryStore;
+    planner?: Planner;
+    maxIterations?: number;
+    timeoutMs?: number;
+}
+
+/**
+ * Agent run configuration
+ */
+export interface AgentRunConfig<TInput> {
+    input: TInput;
+    context?: Record<string, unknown>;
+    metadata?: Record<string, unknown>;
+}
+
+/**
+ * Define a new agent with typed input/output
+ */
+export function defineAgent<TInput = string, TOutput = unknown>(
+    config: AgentDefinitionConfig<TInput, TOutput>
+): DefinedAgent<TInput, TOutput> {
+    return new DefinedAgent(config);
+}
+
+/**
+ * Defined agent class with fluent API
+ */
+export class DefinedAgent<TInput, TOutput> {
+    private config: AgentDefinitionConfig<TInput, TOutput>;
+    private toolRegistry: ToolRegistry;
+    private memoryStore: MemoryStore;
+    private plannerInstance: Planner;
+    private _executionEngine: ExecutionEngine;
+
+    constructor(config: AgentDefinitionConfig<TInput, TOutput>) {
+        this.config = config;
+        this.toolRegistry = new ToolRegistryImpl();
+        this.memoryStore = config.memory ?? new InMemoryStore();
+        this.plannerInstance = config.planner ?? new ClassicalPlanner({ algorithm: PlanningAlgorithm.HIERARCHICAL });
+        // _executionEngine is initialized for future use in distributed execution scenarios
+        this._executionEngine = new ExecutionEngineImpl();
+
+        // Register provided tools
+        if (config.tools) {
+            for (const tool of config.tools) {
+                this.toolRegistry.register(tool);
+            }
+        }
+    }
+
+    /**
+     * Add a tool to the agent
+     */
+    withTool(tool: Tool): this {
+        this.toolRegistry.register(tool);
+        return this;
+    }
+
+    /**
+     * Add multiple tools
+     */
+    withTools(tools: Tool[]): this {
+        for (const tool of tools) {
+            this.toolRegistry.register(tool);
+        }
+        return this;
+    }
+
+    /**
+     * Set the memory store
+     */
+    withMemory(memory: MemoryStore): this {
+        Object.assign(this, { memoryStore: memory });
+        return this;
+    }
+
+    /**
+     * Set the planner
+     */
+    withPlanner(planner: Planner): this {
+        Object.assign(this, { plannerInstance: planner });
+        return this;
+    }
+
+    /**
+     * Set the execution engine
+     */
+    withExecutionEngine(engine: ExecutionEngine): this {
+        this._executionEngine = engine;
+        return this;
+    }
+
+    /**
+     * Get the execution engine
+     */
+    getExecutionEngine(): ExecutionEngine {
+        return this._executionEngine;
+    }
+
+    /**
+     * Run the agent with input
+     */
+    async run(config: AgentRunConfig<TInput>): Promise<TOutput> {
+        // Validate input
+        const validatedInput = this.config.inputSchema.parse(config.input);
+
+        // Create agent instance
+        const agent = new TypedAgent({
+            name: this.config.name,
+            description: this.config.description,
+            maxIterations: this.config.maxIterations,
+            timeoutMs: this.config.timeoutMs,
+        }, this.config.outputSchema);
+
+        // Create context
+        const { AgentContextBuilder } = await import('../core/context-builder.js');
+        const context = new AgentContextBuilder()
+            .withAgentId(agent.id)
+            .withMemory(this.memoryStore)
+            .withTools(this.toolRegistry)
+            .withPlanner(this.plannerInstance)
+            .withMetadataEntries(config.metadata ?? {})
+            .build();
+
+        // Run agent
+        const output = await agent.run(
+            {
+                prompt: JSON.stringify(validatedInput),
+                context: config.context,
+            },
+            context
+        );
+
+        // Parse and validate output
+        return this.config.outputSchema.parse(output.result);
+    }
+
+    /**
+     * Create a plan for a goal
+     */
+    async plan(goal: string): Promise<import('../planner/types.js').Plan> {
+        return this.plannerInstance.plan(goal, {
+            availableTools: this.toolRegistry.list().map(t => t.name),
+        });
+    }
+
+    /**
+     * Get agent configuration
+     */
+    getConfig(): AgentDefinitionConfig<TInput, TOutput> {
+        return { ...this.config };
+    }
+}
+
+/**
+ * Typed agent implementation
+ */
+class TypedAgent<TOutput> extends BaseAgent {
+    constructor(
+        config: AgentConfig,
+        _outputSchema: z.ZodType<TOutput>
+    ) {
+        super(config);
+        // _outputSchema is available for potential future validation use
+        void _outputSchema;
+    }
+
+    protected async execute(input: AgentInput, _ctx: AgentContext): Promise<unknown> {
+        // Get the output schema from the config to validate result
+        // This is a demo implementation that generates a mock research result
+        const parsedInput = JSON.parse(input.prompt);
+
+        // In a real implementation, this would:
+        // 1. Use the planner to create a plan
+        // 2. Execute tasks using available tools
+        // 3. Process results and generate output
+
+        // For demo purposes, return a mock result that matches ResearchOutput schema
+        return {
+            summary: `Research on "${parsedInput.topic}" completed. This is a demo result showing the agent framework is working correctly.`,
+            sources: [
+                'https://example.com/source1',
+                'https://example.com/source2',
+                'https://example.com/source3',
+            ],
+            confidence: 0.85,
+        };
+    }
+}
+
+/**
+ * Create a workflow builder
+ */
+export function createWorkflow(): WorkflowBuilder {
+    return new WorkflowBuilder();
+}
+
+/**
+ * Workflow builder for chaining agents
+ */
+export class WorkflowBuilder {
+    private steps: WorkflowStep[] = [];
+
+    /**
+     * Add a task to the workflow
+     */
+    task(name: string, agent: DefinedAgent<unknown, unknown>): this {
+        this.steps.push({ type: 'task', name, agent });
+        return this;
+    }
+
+    /**
+     * Add parallel execution
+     */
+    parallel(): this {
+        this.steps.push({ type: 'parallel' });
+        return this;
+    }
+
+    /**
+     * Add sequential execution
+     */
+    sequential(): this {
+        this.steps.push({ type: 'sequential' });
+        return this;
+    }
+
+    /**
+     * Add dependency
+     */
+    dependsOn(...taskNames: string[]): this {
+        const lastStep = this.steps[this.steps.length - 1];
+        if (lastStep && lastStep.type === 'task') {
+            lastStep.dependencies = taskNames;
+        }
+        return this;
+    }
+
+    /**
+     * Build the workflow
+     */
+    build(): Workflow {
+        return new Workflow(this.steps);
+    }
+
+    /**
+     * Execute the workflow
+     */
+    async execute(context?: Record<string, unknown>): Promise<WorkflowResult> {
+        const workflow = this.build();
+        return workflow.execute(context);
+    }
+}
+
+/**
+ * Workflow step definition
+ */
+interface WorkflowStep {
+    type: 'task' | 'parallel' | 'sequential';
+    name?: string;
+    agent?: DefinedAgent<unknown, unknown>;
+    dependencies?: string[];
+}
+
+/**
+ * Workflow class
+ */
+export class Workflow {
+    private steps: WorkflowStep[];
+
+    constructor(steps: WorkflowStep[]) {
+        this.steps = steps;
+    }
+
+    /**
+     * Execute the workflow
+     */
+    async execute(context?: Record<string, unknown>): Promise<WorkflowResult> {
+        const results: Record<string, unknown> = {};
+
+        for (const step of this.steps) {
+            if (step.type === 'task' && step.agent && step.name) {
+                const result = await step.agent.run({
+                    input: context ?? {},
+                    context,
+                });
+                results[step.name] = result;
+            }
+            // TODO: Implement parallel/sequential execution
+        }
+
+        return { results };
+    }
+}
+
+/**
+ * Workflow execution result
+ */
+export interface WorkflowResult {
+    results: Record<string, unknown>;
+}
+
+/**
+ * Wrap a DefinedAgent as a core Agent for use with the Orchestrator (supervisor, pipeline).
+ */
+export function asOrchestratorAgent(definedAgent: DefinedAgent<unknown, unknown>): Agent {
+    return new DefinedAgentAdapter(definedAgent);
+}
+
+class DefinedAgentAdapter extends Agent {
+    constructor(private readonly definedAgent: DefinedAgent<unknown, unknown>) {
+        super({
+            name: definedAgent.getConfig().name,
+            description: definedAgent.getConfig().description ?? '',
+        });
+    }
+
+    async run(input: AgentInput, _ctx: AgentContext): Promise<AgentOutput> {
+        const parsedInput =
+            typeof input.prompt === 'string' && (input.prompt.startsWith('{') || input.prompt.startsWith('['))
+                ? (JSON.parse(input.prompt) as unknown)
+                : input.prompt;
+        const result = await this.definedAgent.run({
+            input: parsedInput,
+            context: input.context ?? _ctx.metadata,
+        });
+        return {
+            result,
+            state: AgentState.COMPLETED,
+            metadata: {
+                startTime: new Date(),
+                iterations: 0,
+            },
+        };
+    }
+}
+
+// Re-export core types for convenience
+export * from '../core/types.js';
+export * from '../memory/types.js';
+export * from '../tools/types.js';
+export * from '../planner/types.js';
+export * from '../execution/types.js';

package/src/session/db-driver.ts

@@ -0,0 +1,50 @@
+/**
+ * Database driver interface for session persistence.
+ * Implement for SQLite, PostgreSQL, or any SQL-compatible store.
+ */
+
+/**
+ * Minimal SQL driver: run queries and execute statements.
+ * Plug any DB by implementing this interface.
+ */
+export interface SessionDbDriver {
+    /** Run a SELECT and return rows */
+    query<T = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<T[]>;
+
+    /** Run INSERT/UPDATE/DELETE; no return value */
+    run(sql: string, params?: unknown[]): Promise<void>;
+
+    /** Run DDL (e.g. CREATE TABLE). Optional; use run() if not supported. */
+    exec?(sql: string): Promise<void>;
+}
+
+/**
+ * Row shape for sessions table (driver-agnostic)
+ */
+export interface SessionRow {
+    id: string;
+    agent_id: string;
+    user_id: string | null;
+    state: string;
+    messages: string;
+    metadata: string;
+    context: string;
+    created_at: string;
+    updated_at: string;
+    expires_at: string | null;
+}
+
+/**
+ * Row shape for session_runs table
+ */
+export interface SessionRunRow {
+    id: string;
+    session_id: string;
+    agent_id: string;
+    start_time: string;
+    end_time: string | null;
+    status: string;
+    steps: number;
+    result: string | null;
+    error: string | null;
+}

package/src/session/in-memory-store.ts

@@ -0,0 +1,235 @@
+/**
+ * In-memory session store implementation
+ */
+
+import {
+    SessionStore,
+    Session,
+    SessionRun,
+    SessionId,
+    SessionState,
+    SessionQuery,
+    SessionStoreConfig,
+} from './types.js';
+import type { Message } from '../llm/types.js';
+
+/**
+ * Default configuration
+ */
+const DEFAULT_CONFIG: Required<SessionStoreConfig> = {
+    defaultTtlMs: 24 * 60 * 60 * 1000, // 24 hours
+    maxSessionsPerAgent: 100,
+    maxMessagesPerSession: 1000,
+};
+
+/**
+ * In-memory implementation of SessionStore
+ * Suitable for development and testing
+ */
+export class InMemorySessionStore implements SessionStore {
+    private sessions: Map<SessionId, Session> = new Map();
+    private runs: Map<string, SessionRun[]> = new Map();
+    private config: Required<SessionStoreConfig>;
+
+    constructor(config: SessionStoreConfig = {}) {
+        this.config = { ...DEFAULT_CONFIG, ...config };
+    }
+
+    async create(session: Omit<Session, 'id' | 'createdAt' | 'updatedAt'>): Promise<Session> {
+        const id = this.generateId();
+        const now = new Date();
+
+        const newSession: Session = {
+            ...session,
+            id,
+            createdAt: now,
+            updatedAt: now,
+        };
+
+        this.sessions.set(id, newSession);
+        this.runs.set(id, []);
+
+        // Enforce max sessions per agent
+        this.enforceMaxSessions(session.agentId);
+
+        return newSession;
+    }
+
+    async get(sessionId: SessionId): Promise<Session | null> {
+        const session = this.sessions.get(sessionId);
+        if (!session) return null;
+
+        // Check expiration
+        if (session.expiresAt && session.expiresAt < new Date()) {
+            await this.delete(sessionId);
+            return null;
+        }
+
+        return session;
+    }
+
+    async update(sessionId: SessionId, updates: Partial<Omit<Session, 'id' | 'createdAt'>>): Promise<Session> {
+        const existing = this.sessions.get(sessionId);
+        if (!existing) {
+            throw new Error(`Session not found: ${sessionId}`);
+        }
+
+        const updated: Session = {
+            ...existing,
+            ...updates,
+            id: existing.id,
+            createdAt: existing.createdAt,
+            updatedAt: new Date(),
+        };
+
+        this.sessions.set(sessionId, updated);
+        return updated;
+    }
+
+    async delete(sessionId: SessionId): Promise<boolean> {
+        this.runs.delete(sessionId);
+        return this.sessions.delete(sessionId);
+    }
+
+    async list(query?: SessionQuery): Promise<Session[]> {
+        let sessions = Array.from(this.sessions.values());
+
+        if (query?.agentId) {
+            sessions = sessions.filter(s => s.agentId === query.agentId);
+        }
+
+        if (query?.userId) {
+            sessions = sessions.filter(s => s.userId === query.userId);
+        }
+
+        if (query?.state) {
+            sessions = sessions.filter(s => s.state === query.state);
+        }
+
+        if (query?.before) {
+            sessions = sessions.filter(s => s.createdAt < query.before!);
+        }
+
+        if (query?.after) {
+            sessions = sessions.filter(s => s.createdAt > query.after!);
+        }
+
+        // Sort by updatedAt desc
+        sessions.sort((a, b) => b.updatedAt.getTime() - a.updatedAt.getTime());
+
+        if (query?.limit) {
+            sessions = sessions.slice(0, query.limit);
+        }
+
+        return sessions;
+    }
+
+    async addMessage(sessionId: SessionId, message: Message): Promise<Session> {
+        const session = await this.get(sessionId);
+        if (!session) {
+            throw new Error(`Session not found: ${sessionId}`);
+        }
+
+        const messages = [...session.messages, message];
+
+        // Enforce max messages
+        if (messages.length > this.config.maxMessagesPerSession) {
+            messages.shift(); // Remove oldest
+        }
+
+        return this.update(sessionId, {
+            messages,
+            state: SessionState.ACTIVE,
+        });
+    }
+
+    async getMessages(sessionId: SessionId): Promise<Message[]> {
+        const session = await this.get(sessionId);
+        if (!session) {
+            throw new Error(`Session not found: ${sessionId}`);
+        }
+        return [...session.messages];
+    }
+
+    async clearMessages(sessionId: SessionId): Promise<Session> {
+        return this.update(sessionId, { messages: [] });
+    }
+
+    async setContext(sessionId: SessionId, key: string, value: unknown): Promise<Session> {
+        const session = await this.get(sessionId);
+        if (!session) {
+            throw new Error(`Session not found: ${sessionId}`);
+        }
+
+        return this.update(sessionId, {
+            context: { ...session.context, [key]: value },
+        });
+    }
+
+    async getContext(sessionId: SessionId, key: string): Promise<unknown> {
+        const session = await this.get(sessionId);
+        if (!session) {
+            throw new Error(`Session not found: ${sessionId}`);
+        }
+        return session.context[key];
+    }
+
+    async recordRun(run: Omit<SessionRun, 'id'>): Promise<SessionRun> {
+        const session = await this.get(run.sessionId);
+        if (!session) {
+            throw new Error(`Session not found: ${run.sessionId}`);
+        }
+
+        const newRun: SessionRun = {
+            ...run,
+            id: `run-${Date.now()}-${Math.random().toString(36).substring(2, 11)}`,
+        };
+
+        const runs = this.runs.get(run.sessionId) ?? [];
+        runs.push(newRun);
+        this.runs.set(run.sessionId, runs);
+
+        return newRun;
+    }
+
+    async getRuns(sessionId: SessionId): Promise<SessionRun[]> {
+        return [...(this.runs.get(sessionId) ?? [])];
+    }
+
+    async cleanup(): Promise<number> {
+        const now = new Date();
+        let cleaned = 0;
+
+        for (const [id, session] of this.sessions) {
+            if (session.expiresAt && session.expiresAt < now) {
+                await this.delete(id);
+                cleaned++;
+            }
+        }
+
+        return cleaned;
+    }
+
+    /**
+     * Generate a unique ID
+     */
+    private generateId(): SessionId {
+        return `session-${Date.now()}-${Math.random().toString(36).substring(2, 11)}`;
+    }
+
+    /**
+     * Enforce max sessions per agent
+     */
+    private enforceMaxSessions(agentId: string): void {
+        const agentSessions = Array.from(this.sessions.values())
+            .filter(s => s.agentId === agentId)
+            .sort((a, b) => a.createdAt.getTime() - b.createdAt.getTime());
+
+        const excess = agentSessions.length - this.config.maxSessionsPerAgent;
+        if (excess > 0) {
+            for (let i = 0; i < excess; i++) {
+                this.delete(agentSessions[i].id);
+            }
+        }
+    }
+}

package/src/session/index.ts

@@ -0,0 +1,12 @@
+/**
+ * Session management module
+ *
+ * Provides session state management for conversation and run state persistence.
+ * In-memory (dev) or DB-backed (SQLite, PostgreSQL via SessionDbDriver).
+ */
+
+export * from './types.js';
+export { InMemorySessionStore } from './in-memory-store.js';
+export type { SessionDbDriver, SessionRow, SessionRunRow } from './db-driver.js';
+export { SqlSessionStore } from './sql-store.js';
+export { createSqliteSessionStore } from './sqlite-store.js';