confused-ai-core 0.1.0

package/src/core/types.ts

@@ -0,0 +1,158 @@
+/**
+ * Core types and interfaces for the Agent Framework
+ */
+
+import type { MemoryStore } from '../memory/types.js';
+import type { ToolRegistry } from '../tools/types.js';
+import type { Planner } from '../planner/types.js';
+
+/**
+ * Unique identifier for agents, tasks, and other entities
+ */
+export type EntityId = string;
+
+/**
+ * Agent execution state
+ */
+export enum AgentState {
+    IDLE = 'idle',
+    PLANNING = 'planning',
+    EXECUTING = 'executing',
+    PAUSED = 'paused',
+    COMPLETED = 'completed',
+    FAILED = 'failed',
+    CANCELLED = 'cancelled',
+}
+
+/**
+ * Context provided to agents during execution
+ */
+export interface AgentContext {
+    readonly agentId: EntityId;
+    readonly memory: MemoryStore;
+    readonly tools: ToolRegistry;
+    readonly planner: Planner;
+    readonly metadata: Record<string, unknown>;
+}
+
+/**
+ * Configuration for creating an agent
+ */
+export interface AgentConfig {
+    readonly id?: EntityId;
+    readonly name: string;
+    readonly description?: string;
+    readonly persona?: string;
+    readonly maxIterations?: number;
+    readonly timeoutMs?: number;
+    /** Enable debug logging for this agent */
+    readonly debug?: boolean;
+}
+
+/**
+ * Input to an agent execution
+ */
+export interface AgentInput {
+    readonly prompt: string;
+    readonly context?: Record<string, unknown>;
+    readonly attachments?: Attachment[];
+}
+
+/**
+ * Output from an agent execution
+ */
+export interface AgentOutput {
+    readonly result: unknown;
+    readonly state: AgentState;
+    readonly metadata: ExecutionMetadata;
+}
+
+/**
+ * Attachment for agent input/output
+ */
+export interface Attachment {
+    readonly id: EntityId;
+    readonly type: string;
+    readonly content: unknown;
+    readonly metadata?: Record<string, unknown>;
+}
+
+/**
+ * Execution metadata
+ */
+export interface ExecutionMetadata {
+    readonly startTime: Date;
+    readonly endTime?: Date;
+    readonly durationMs?: number;
+    readonly iterations: number;
+    readonly tokensUsed?: number;
+    readonly cost?: number;
+}
+
+/**
+ * Hook for agent lifecycle events
+ */
+export interface AgentHooks {
+    beforeExecution?: (input: AgentInput, ctx: AgentContext) => Promise<void> | void;
+    afterExecution?: (output: AgentOutput, ctx: AgentContext) => Promise<void> | void;
+    onError?: (error: Error, ctx: AgentContext) => Promise<void> | void;
+    onStateChange?: (oldState: AgentState, newState: AgentState, ctx: AgentContext) => Promise<void> | void;
+}
+
+/**
+ * Abstract base class for all agents
+ */
+export abstract class Agent {
+    readonly id: EntityId;
+    readonly name: string;
+    readonly description: string;
+    readonly persona?: string;
+    readonly config: AgentConfig;
+    protected state: AgentState = AgentState.IDLE;
+    protected hooks: AgentHooks = {};
+
+    constructor(config: AgentConfig) {
+        this.config = config;
+        this.id = config.id ?? generateId();
+        this.name = config.name;
+        this.description = config.description ?? '';
+        this.persona = config.persona;
+    }
+
+    /**
+     * Execute the agent with the given input and context
+     */
+    abstract run(input: AgentInput, ctx: AgentContext): Promise<AgentOutput>;
+
+    /**
+     * Get current agent state
+     */
+    getState(): AgentState {
+        return this.state;
+    }
+
+    /**
+     * Set lifecycle hooks
+     */
+    setHooks(hooks: AgentHooks): void {
+        this.hooks = hooks;
+    }
+
+    /**
+     * Update agent state with hook notification
+     */
+    protected async setState(newState: AgentState, ctx: AgentContext): Promise<void> {
+        const oldState = this.state;
+        this.state = newState;
+        if (this.hooks.onStateChange) {
+            await this.hooks.onStateChange(oldState, newState, ctx);
+        }
+    }
+}
+
+/**
+ * Generate a unique identifier
+ */
+function generateId(): EntityId {
+    return `${Date.now()}-${Math.random().toString(36).substring(2, 11)}`;
+}

package/src/create-agent.ts

@@ -0,0 +1,309 @@
+/**
+ * One-line production-grade agent creation.
+ *
+ * Auto-configures: LLM (from env), memory/session, default tools, optional guardrails.
+ * Use createAgent({ name, instructions }) for minimal setup; override any part as needed.
+ */
+
+import type { LLMProvider } from './llm/types.js';
+import type { Message } from './llm/types.js';
+import type { Tool, ToolRegistry, ToolMiddleware } from './tools/types.js';
+import type { SessionStore } from './session/types.js';
+import type { GuardrailEngine } from './guardrails/types.js';
+import type { UserProfileStore } from './learning/types.js';
+import type { LearningMode } from './learning/types.js';
+import type { MemoryStore } from './memory/types.js';
+import type { RAGEngine } from './knowledge/types.js';
+import type { z } from 'zod';
+import type { AgenticStreamHooks } from './agentic/types.js';
+import type { AgenticRunResult } from './agentic/types.js';
+import type { Logger } from './observability/types.js';
+import { createAgenticAgent } from './agentic/index.js';
+import { OpenAIProvider, resolveModelString, isModelString } from './llm/index.js';
+import { HttpClientTool } from './tools/http-tool.js';
+import { BrowserTool } from './tools/browser-tool.js';
+import { InMemorySessionStore } from './session/index.js';
+import { GuardrailValidator, createSensitiveDataRule } from './guardrails/index.js';
+import { SessionState } from './session/types.js';
+import { ConfigError } from './errors.js';
+import { toToolRegistry, type ToolProvider } from './tools/registry.js';
+import { createDevLogger } from './dx/dev-logger.js';
+import { createDevToolMiddleware } from './dx/dev-logger.js';
+
+/** Environment variable names for auto LLM config */
+const ENV_API_KEY = 'OPENAI_API_KEY';
+const ENV_MODEL = 'OPENAI_MODEL';
+const ENV_BASE_URL = 'OPENAI_BASE_URL';
+const ENV_OPENROUTER_API_KEY = 'OPENROUTER_API_KEY';
+const ENV_OPENROUTER_MODEL = 'OPENROUTER_MODEL';
+const OPENROUTER_BASE_URL = 'https://openrouter.ai/api/v1';
+
+export interface CreateAgentOptions {
+    /** Agent name */
+    name: string;
+    /** System instructions / prompt */
+    instructions: string;
+    /** LLM provider. If omitted, uses OpenAI from OPENAI_API_KEY (and optional OPENAI_MODEL). */
+    llm?: LLMProvider;
+    /**
+     * Model: either a plain model id (e.g. gpt-4o) or Agno-style "provider:model_id".
+     * Examples: "openai:gpt-4o", "openrouter:anthropic/claude-3.5-sonnet", "ollama:llama3.2".
+     * Ignored if llm is provided.
+     */
+    model?: string;
+    /** API key when using auto OpenAI. Falls back to OPENAI_API_KEY. Optional when baseURL is a local server (e.g. Ollama). */
+    apiKey?: string;
+    /** Base URL for the API (e.g. http://localhost:11434/v1 for Ollama). Falls back to OPENAI_BASE_URL. */
+    baseURL?: string;
+    /** Use OpenRouter (many models via one API). Set OPENROUTER_API_KEY or pass apiKey/model here. */
+    openRouter?: { apiKey?: string; model?: string };
+    /** Tools: array or registry. Default: [HttpClientTool(), BrowserTool()]. */
+    tools?: Tool[] | ToolRegistry;
+    /** Cross-tool middleware (logging, rate limit, etc.). */
+    toolMiddleware?: ToolMiddleware[];
+    /** Session store for conversation persistence. Default: InMemorySessionStore(). Plug any DB by implementing SessionStore. */
+    sessionStore?: SessionStore;
+    /** Guardrails. Default: GuardrailValidator with sensitive-data rule. Set false to disable. */
+    guardrails?: GuardrailEngine | false;
+    /** Max agentic steps (default: 10) */
+    maxSteps?: number;
+    /** Run timeout ms (default: 60000) */
+    timeoutMs?: number;
+    /** Retry policy for LLM/tool calls */
+    retry?: { maxRetries?: number; backoffMs?: number; maxBackoffMs?: number };
+    /** Optional logger for production observability */
+    logger?: Logger;
+    /** Learning: always persist/learn vs agentic (default: always when sessionStore used) */
+    learningMode?: LearningMode;
+    /** User profiles that persist across sessions (plug any DB) */
+    userProfileStore?: UserProfileStore;
+    /** Long-term memory / knowledge store (for RAG, memories that accumulate) */
+    memoryStore?: MemoryStore;
+    /** RAG engine: agentic RAG, hybrid search, reranking (optional) */
+    ragEngine?: RAGEngine;
+    /** Type-safe input: Zod schema for run input (optional) */
+    inputSchema?: z.ZodType;
+    /** Type-safe output: Zod schema for run output (optional) */
+    outputSchema?: z.ZodType;
+    /** Dev mode: auto-attach console logger + tool call logging (best DX) */
+    dev?: boolean;
+}
+
+export interface AgentRunOptions {
+    /** Optional session ID to load/save conversation. If provided, messages are persisted. */
+    sessionId?: string;
+    /** Optional user ID for session metadata */
+    userId?: string;
+    /** Stream / progress hooks */
+    onChunk?: (text: string) => void;
+    onToolCall?: (name: string, args: Record<string, unknown>) => void;
+    onToolResult?: (name: string, result: unknown) => void;
+    onStep?: (step: number) => void;
+}
+
+export interface CreateAgentResult {
+    name: string;
+    instructions: string;
+    /** Run the agent with a prompt. Use sessionId in options for conversation persistence. */
+    run(prompt: string, options?: AgentRunOptions): Promise<AgenticRunResult>;
+    /** Create a new session for this agent (returns sessionId to pass to run). */
+    createSession(userId?: string): Promise<string>;
+    /** Get messages for a session (if using sessionStore). */
+    getSessionMessages(sessionId: string): Promise<Message[]>;
+}
+
+/**
+ * Create a production-grade agent with one line.
+ * Auto-configures LLM (OpenAI from env), default tools (HTTP), session store, and optional guardrails.
+ *
+ * @example
+ * // Minimal: uses OPENAI_API_KEY, default tools and session
+ * const agent = createAgent({ name: 'Assistant', instructions: 'You are helpful.' });
+ * const result = await agent.run('Hello!');
+ *
+ * @example
+ * // With session for conversation memory
+ * const agent = createAgent({ name: 'Assistant', instructions: 'You are helpful.' });
+ * const sessionId = await agent.createSession('user-1');
+ * const result = await agent.run('What did I just say?', { sessionId });
+ *
+ * @example
+ * // Override model or provide your own LLM
+ * const agent = createAgent({
+ *   name: 'Assistant',
+ *   instructions: 'You are helpful.',
+ *   model: 'gpt-4o-mini',
+ *   apiKey: process.env.MY_KEY,
+ * });
+ *
+ * @example
+ * // Llama/Bern or any OpenAI-compatible endpoint (e.g. Ollama)
+ * const agent = createAgent({
+ *   name: 'Assistant',
+ *   instructions: 'You are helpful.',
+ *   baseURL: 'http://localhost:11434/v1',
+ *   model: 'llama3.2',
+ * });
+ *
+ * @example
+ * // Agno-style model string: provider:model_id (openai, openrouter, ollama)
+ * const agent = createAgent({
+ *   name: 'Assistant',
+ *   instructions: 'You are helpful.',
+ *   model: 'openrouter:anthropic/claude-3.5-sonnet',
+ * });
+ */
+export function createAgent(options: CreateAgentOptions): CreateAgentResult {
+    const {
+        name,
+        instructions,
+        llm: providedLlm,
+        model = typeof process !== 'undefined' && process.env?.[ENV_MODEL] ? process.env[ENV_MODEL] : 'gpt-4o',
+        apiKey = typeof process !== 'undefined' && process.env?.[ENV_API_KEY] ? process.env[ENV_API_KEY] : undefined,
+        baseURL = (typeof process !== 'undefined' && process.env?.[ENV_BASE_URL]) ? process.env[ENV_BASE_URL] : undefined,
+        tools: toolsOption = [new HttpClientTool(), new BrowserTool()],
+        toolMiddleware,
+        sessionStore = new InMemorySessionStore(),
+        guardrails: guardrailsOption = true,
+        maxSteps = 10,
+        timeoutMs = 60_000,
+        retry,
+        logger,
+        dev,
+    } = options;
+
+    if (!name || typeof name !== 'string' || name.trim() === '') {
+        throw new ConfigError('createAgent: name is required and must be a non-empty string', { context: { options: { name } } });
+    }
+    if (!instructions || typeof instructions !== 'string' || instructions.trim() === '') {
+        throw new ConfigError('createAgent: instructions is required and must be a non-empty string', { context: { options: { name } } });
+    }
+
+    const tools = toToolRegistry(toolsOption as ToolProvider);
+
+    const getEnv = typeof process !== 'undefined' ? (k: string) => process.env?.[k] : undefined;
+    let llm: LLMProvider;
+    if (providedLlm) {
+        llm = providedLlm;
+    } else if (model && isModelString(model)) {
+        const resolved = resolveModelString(model, getEnv);
+        if (!resolved) {
+            throw new Error(`createAgent: Unknown provider in model string "${model}". Use openai:, openrouter:, or ollama:.`);
+        }
+        if (!resolved.apiKey) {
+            throw new Error(
+                `createAgent: Model "${model}" requires an API key. Set OPENAI_API_KEY or OPENROUTER_API_KEY (Ollama needs no key).`
+            );
+        }
+        llm = new OpenAIProvider({
+            apiKey: resolved.apiKey,
+            baseURL: resolved.baseURL,
+            model: resolved.model,
+        });
+    } else {
+        const openRouterKey =
+            options.openRouter?.apiKey ?? getEnv?.(ENV_OPENROUTER_API_KEY);
+        if (openRouterKey) {
+            const openRouterModel =
+                options.openRouter?.model ?? getEnv?.(ENV_OPENROUTER_MODEL) ?? model;
+            llm = new OpenAIProvider({
+                apiKey: openRouterKey,
+                baseURL: OPENROUTER_BASE_URL,
+                model: (openRouterModel as string) || 'openai/gpt-4o',
+            });
+        } else if (apiKey || baseURL) {
+            llm = new OpenAIProvider({ apiKey, baseURL, model: model as string });
+        } else {
+            throw new Error(
+                `createAgent: No LLM provided. Set ${ENV_API_KEY}, or ${ENV_OPENROUTER_API_KEY}, or ${ENV_BASE_URL}, or pass model "provider:model_id", { llm }, { apiKey }, or { baseURL }.`
+            );
+        }
+    }
+
+    const guardrails: GuardrailEngine | undefined =
+        guardrailsOption === false
+            ? undefined
+            : guardrailsOption === true
+                ? (() => {
+                    const engine = new GuardrailValidator({ rules: [createSensitiveDataRule()] });
+                    return engine;
+                })()
+                : guardrailsOption;
+
+    const effectiveLogger = logger ?? (dev ? createDevLogger() : undefined);
+    const effectiveToolMiddleware = [
+        ...(toolMiddleware ?? []),
+        ...(dev ? [createDevToolMiddleware()] : []),
+    ];
+
+    if (effectiveLogger?.debug) {
+        effectiveLogger.debug('createAgent: initializing', { agentId: name }, { toolsCount: tools.list().length });
+    }
+
+    const agent = createAgenticAgent({
+        name,
+        instructions,
+        llm,
+        tools: tools,
+        toolMiddleware: effectiveToolMiddleware.length ? effectiveToolMiddleware : undefined,
+        maxSteps,
+        timeoutMs,
+        retry,
+        guardrails,
+    });
+
+    return {
+        name,
+        instructions,
+        async run(prompt: string, runOptions?: AgentRunOptions): Promise<AgenticRunResult> {
+            const sessionId = runOptions?.sessionId;
+            const hooks: AgenticStreamHooks = {
+                onChunk: runOptions?.onChunk,
+                onToolCall: runOptions?.onToolCall,
+                onToolResult: runOptions?.onToolResult,
+                onStep: runOptions?.onStep,
+            };
+
+            let messages: Message[] | undefined;
+            if (sessionId) {
+                const session = await sessionStore.get(sessionId);
+                const history = session?.messages ?? [];
+                messages = [...history, { role: 'user', content: prompt }];
+            }
+
+            const result = await agent.run(
+                {
+                    prompt: messages ? '' : prompt,
+                    instructions,
+                    messages,
+                    maxSteps,
+                    timeoutMs,
+                },
+                hooks
+            );
+
+            if (sessionId && result.messages?.length) {
+                await sessionStore.update(sessionId, {
+                    messages: result.messages,
+                    state: SessionState.ACTIVE,
+                });
+            }
+
+            return result;
+        },
+        async createSession(userId?: string): Promise<string> {
+            const session = await sessionStore.create({
+                agentId: name,
+                userId,
+                state: SessionState.ACTIVE,
+                messages: [],
+                metadata: {},
+                context: {},
+            });
+            return session.id;
+        },
+        async getSessionMessages(sessionId: string): Promise<Message[]> {
+            return sessionStore.getMessages(sessionId);
+        },
+    };
+}

package/src/debug-logger.ts

@@ -0,0 +1,188 @@
+/**
+ * Centralized debug logger for the agent framework
+ *
+ * Provides comprehensive debug logging across all components with
+ * configurable debug mode support.
+ */
+
+import type { Logger, LogContext } from './observability/types.js';
+
+/**
+ * Debug logger configuration
+ */
+export interface DebugLoggerConfig {
+    /** Enable debug logging */
+    enabled: boolean;
+    /** Component name prefix */
+    component: string;
+    /** Parent logger for nested contexts */
+    parent?: DebugLogger;
+    /** Additional context to include in all logs */
+    context?: Partial<LogContext>;
+}
+
+/**
+ * Format metadata for output
+ */
+function formatMetadata(metadata?: Record<string, unknown>): string {
+    if (!metadata || Object.keys(metadata).length === 0) return '';
+    try {
+        return JSON.stringify(metadata);
+    } catch {
+        return '[metadata serialization failed]';
+    }
+}
+
+/**
+ * Centralized debug logger that respects debug mode settings
+ */
+export class DebugLogger implements Logger {
+    private config: DebugLoggerConfig;
+    private prefix: string;
+
+    constructor(config: DebugLoggerConfig) {
+        this.config = config;
+        this.prefix = `[${config.component}]`;
+    }
+
+    /**
+     * Check if debug logging is enabled
+     */
+    isEnabled(): boolean {
+        return this.config.enabled;
+    }
+
+    /**
+     * Log a debug message (only if debug is enabled)
+     */
+    debug(message: string, _context?: Partial<LogContext>, metadata?: Record<string, unknown>): void {
+        if (!this.config.enabled) return;
+        console.debug(`${this.prefix} ${message}`, formatMetadata(metadata));
+    }
+
+    /**
+     * Log an info message
+     */
+    info(message: string, _context?: Partial<LogContext>, metadata?: Record<string, unknown>): void {
+        console.info(`${this.prefix} ${message}`, formatMetadata(metadata));
+    }
+
+    /**
+     * Log a warning message
+     */
+    warn(message: string, _context?: Partial<LogContext>, metadata?: Record<string, unknown>): void {
+        console.warn(`${this.prefix} ⚠️ ${message}`, formatMetadata(metadata));
+    }
+
+    /**
+     * Log an error message
+     */
+    error(message: string, _context?: Partial<LogContext>, metadata?: Record<string, unknown>): void {
+        console.error(`${this.prefix} ❌ ${message}`, formatMetadata(metadata));
+    }
+
+    /**
+     * Log a fatal message
+     */
+    fatal(message: string, _context?: Partial<LogContext>, metadata?: Record<string, unknown>): void {
+        console.error(`${this.prefix} 💀 [FATAL] ${message}`, formatMetadata(metadata));
+    }
+
+    /**
+     * Create a child logger with additional context
+     */
+    child(additionalContext: Partial<LogContext>): DebugLogger {
+        return new DebugLogger({
+            enabled: this.config.enabled,
+            component: this.config.component,
+            parent: this,
+            context: { ...this.config.context, ...additionalContext },
+        });
+    }
+
+    /**
+     * Log the start of an operation
+     */
+    logStart(operation: string, metadata?: Record<string, unknown>): void {
+        if (!this.config.enabled) return;
+        console.debug(`${this.prefix} ▶️ Starting: ${operation}`, formatMetadata(metadata));
+    }
+
+    /**
+     * Log the completion of an operation
+     */
+    logComplete(operation: string, durationMs?: number, metadata?: Record<string, unknown>): void {
+        if (!this.config.enabled) return;
+        const duration = durationMs !== undefined ? ` (${durationMs}ms)` : '';
+        console.debug(`${this.prefix} ✅ Completed: ${operation}${duration}`, formatMetadata(metadata));
+    }
+
+    /**
+     * Log a step in a multi-step process
+     */
+    logStep(step: string, current: number, total: number, metadata?: Record<string, unknown>): void {
+        if (!this.config.enabled) return;
+        console.debug(`${this.prefix} 📍 Step ${current}/${total}: ${step}`, formatMetadata(metadata));
+    }
+
+    /**
+     * Log state changes
+     */
+    logStateChange(entity: string, from: string, to: string, metadata?: Record<string, unknown>): void {
+        if (!this.config.enabled) return;
+        console.debug(`${this.prefix} 🔄 ${entity} state: ${from} → ${to}`, formatMetadata(metadata));
+    }
+
+    /**
+     * Log data for debugging
+     */
+    logData(label: string, data: unknown): void {
+        if (!this.config.enabled) return;
+        const preview = typeof data === 'string' ? data : JSON.stringify(data);
+        const truncated = preview.length > 200 ? preview.slice(0, 200) + '...' : preview;
+        console.debug(`${this.prefix} 📊 ${label}: ${truncated}`);
+    }
+}
+
+/**
+ * Global debug configuration
+ */
+let globalDebugEnabled = false;
+
+/**
+ * Enable or disable global debug mode
+ */
+export function setGlobalDebug(enabled: boolean): void {
+    globalDebugEnabled = enabled;
+}
+
+/**
+ * Check if global debug mode is enabled
+ */
+export function isGlobalDebugEnabled(): boolean {
+    return globalDebugEnabled;
+}
+
+/**
+ * Create a debug logger for a component
+ */
+export function createDebugLogger(component: string, enabled?: boolean): DebugLogger {
+    return new DebugLogger({
+        enabled: enabled ?? globalDebugEnabled,
+        component,
+    });
+}
+
+/**
+ * Create a no-op logger for when debugging is disabled
+ */
+export function createNoopLogger(): Logger {
+    return {
+        debug: () => { },
+        info: () => { },
+        warn: () => { },
+        error: () => { },
+        fatal: () => { },
+        child: () => createNoopLogger(),
+    };
+}