confused-ai-core 0.1.0

package/FEATURES.md

@@ -0,0 +1,169 @@
+# Core Framework Features
+
+| Category          | Features                                                                                                                                               |
+| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| **Learning**      | User profiles, persistent memory stores, RAG (Retrieval-Augmented Generation), always/agentic learning modes.                                          |
+| **Core**          | Model-agnostic (OpenAI/OpenRouter/Ollama via strings), Type-safe I/O with Zod, async-first, long-running operations with retries, multimodal messages. |
+| **Knowledge**     | RAGEngine, hybrid search, reranking, session/state persistence, pluggable vector stores.                                                               |
+| **Orchestration** | Human-in-the-loop hooks, guardrails (sensitive data/schema validation), MCP & A2A support, supervisors & sub-agents.                                   |
+| **Production**    | Circuit breaker, rate limiter, health checks, graceful shutdown, OTLP export, LLM caching, resumable streaming.                                        |
+| **Artifacts**     | Typed artifacts (text, data, reasoning, plan), versioned storage, media support (images, audio, video).                                                |
+| **Voice**         | TTS/STT with OpenAI and ElevenLabs, voice ID selection, streaming audio.                                                                               |
+
+---
+
+## Quick Start Examples
+
+### 🔧 Circuit Breaker
+```typescript
+import { createLLMCircuitBreaker } from '@confused-ai/core/production';
+
+const breaker = createLLMCircuitBreaker('openai');
+
+// Wrap LLM calls - automatically opens circuit on repeated failures
+const result = await breaker.execute(async () => {
+  return await llm.generateText({ messages });
+});
+
+if (result.success) {
+  console.log(result.value);
+} else {
+  console.error('Circuit open:', result.error);
+}
+```
+
+### ⏱️ Rate Limiter
+```typescript
+import { createOpenAIRateLimiter } from '@confused-ai/core/production';
+
+// Create limiter matching OpenAI tier limits
+const limiter = createOpenAIRateLimiter('tier1'); // 60 RPM
+
+await limiter.execute(async () => {
+  return await openai.chat.completions.create({ ... });
+});
+```
+
+### 🏥 Health Checks
+```typescript
+import { HealthCheckManager, createLLMHealthCheck } from '@confused-ai/core/production';
+
+const health = new HealthCheckManager({ version: '1.0.0' });
+health.addComponent(createLLMHealthCheck(llmProvider));
+
+// Express endpoint
+app.get('/health', async (req, res) => {
+  const result = await health.check();
+  res.status(result.status === 'HEALTHY' ? 200 : 503).json(result);
+});
+```
+
+### 💾 LLM Response Cache
+```typescript
+import { LLMCache, withCache } from '@confused-ai/core/llm';
+
+const cache = new LLMCache({ maxEntries: 1000, ttlMs: 60000 });
+const cachedLLM = withCache(llm, cache);
+
+// Identical requests return cached responses
+const response = await cachedLLM.generateText({ messages });
+```
+
+### 📦 Artifacts
+```typescript
+import { InMemoryArtifactStorage, createPlanArtifact } from '@confused-ai/core/artifacts';
+
+const storage = new InMemoryArtifactStorage();
+
+// Create a plan artifact
+const plan = await storage.save(createPlanArtifact(
+  'project-plan',
+  'Build a chatbot',
+  [
+    { description: 'Design conversation flows' },
+    { description: 'Implement intent detection' },
+    { description: 'Add response generation' },
+  ]
+));
+
+// Retrieve with versioning
+const retrieved = await storage.get(plan.id);
+```
+
+### 🎤 Voice (TTS/STT)
+```typescript
+import { OpenAIVoiceProvider } from '@confused-ai/core/voice';
+
+const voice = new OpenAIVoiceProvider();
+
+// Text-to-Speech
+const { audio } = await voice.textToSpeech('Hello, world!', { 
+  voiceId: 'nova',
+  speed: 1.0 
+});
+
+// Speech-to-Text
+const { text } = await voice.speechToText(audioBuffer);
+```
+
+### 🔄 Resumable Streaming
+```typescript
+import { ResumableStreamManager, formatSSE } from '@confused-ai/core/production';
+
+const manager = new ResumableStreamManager();
+
+// Create stream
+const streamId = manager.createStream();
+
+// On each chunk from LLM
+manager.saveChunk(streamId, { type: 'text', content: 'Hello' });
+
+// Client reconnects after disconnect
+const checkpoint = manager.getCheckpoint(streamId);
+const missed = manager.getChunksSince(streamId, clientPosition);
+
+for (const chunk of missed) {
+  res.write(formatSSE(chunk)); // SSE compatible
+}
+```
+
+### 🛡️ Graceful Shutdown
+```typescript
+import { GracefulShutdown } from '@confused-ai/core/production';
+
+const shutdown = new GracefulShutdown({ timeoutMs: 30000 });
+
+shutdown.addHandler('database', async () => {
+  await db.close();
+});
+
+shutdown.addHandler('http-server', async () => {
+  await server.close();
+});
+
+shutdown.listen(); // Handles SIGTERM/SIGINT
+```
+
+---
+
+## Module Imports
+
+```typescript
+// Production resilience
+import { 
+  CircuitBreaker, RateLimiter, HealthCheckManager, 
+  GracefulShutdown, ResumableStreamManager 
+} from '@confused-ai/core/production';
+
+// Observability
+import { OTLPTraceExporter, OTLPMetricsExporter } from '@confused-ai/core/observability';
+
+// LLM with caching
+import { LLMCache, withCache } from '@confused-ai/core/llm';
+
+// Artifacts
+import { InMemoryArtifactStorage, MediaManager } from '@confused-ai/core/artifacts';
+
+// Voice
+import { OpenAIVoiceProvider, ElevenLabsVoiceProvider } from '@confused-ai/core/voice';
+```

package/package.json

@@ -0,0 +1,119 @@
+{
+    "name": "confused-ai-core",
+    "version": "0.1.0",
+    "description": "Confused AI - Production-grade TypeScript framework for orchestrating multi-agent workflows",
+    "type": "module",
+    "main": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "exports": {
+        ".": {
+            "import": "./dist/index.js",
+            "types": "./dist/index.d.ts"
+        },
+        "./core": {
+            "import": "./dist/core/index.js",
+            "types": "./dist/core/index.d.ts"
+        },
+        "./memory": {
+            "import": "./dist/memory/index.js",
+            "types": "./dist/memory/index.d.ts"
+        },
+        "./tools": {
+            "import": "./dist/tools/index.js",
+            "types": "./dist/tools/index.d.ts"
+        },
+        "./planner": {
+            "import": "./dist/planner/index.js",
+            "types": "./dist/planner/index.d.ts"
+        },
+        "./execution": {
+            "import": "./dist/execution/index.js",
+            "types": "./dist/execution/index.d.ts"
+        },
+        "./orchestration": {
+            "import": "./dist/orchestration/index.js",
+            "types": "./dist/orchestration/index.d.ts"
+        },
+        "./observability": {
+            "import": "./dist/observability/index.js",
+            "types": "./dist/observability/index.d.ts"
+        },
+        "./llm": {
+            "import": "./dist/llm/index.js",
+            "types": "./dist/llm/index.d.ts"
+        },
+        "./agentic": {
+            "import": "./dist/agentic/index.js",
+            "types": "./dist/agentic/index.d.ts"
+        },
+        "./session": {
+            "import": "./dist/session/index.js",
+            "types": "./dist/session/index.d.ts"
+        },
+        "./guardrails": {
+            "import": "./dist/guardrails/index.js",
+            "types": "./dist/guardrails/index.d.ts"
+        },
+        "./production": {
+            "import": "./dist/production/index.js",
+            "types": "./dist/production/index.d.ts"
+        },
+        "./artifacts": {
+            "import": "./dist/artifacts/index.js",
+            "types": "./dist/artifacts/index.d.ts"
+        },
+        "./voice": {
+            "import": "./dist/voice/index.js",
+            "types": "./dist/voice/index.d.ts"
+        }
+    },
+    "scripts": {
+        "build": "tsc",
+        "dev": "tsc --watch",
+        "typecheck": "tsc --noEmit",
+        "test": "vitest run",
+        "test:watch": "vitest",
+        "test:coverage": "vitest run --coverage"
+    },
+    "keywords": [
+        "agent",
+        "ai",
+        "framework",
+        "typescript",
+        "multi-agent",
+        "orchestration",
+        "llm"
+    ],
+    "author": "",
+    "license": "MIT",
+    "devDependencies": {
+        "@types/bun": "latest",
+        "@types/uuid": "^9.0.8",
+        "@vitest/coverage-v8": "^4.0.18",
+        "typescript": "^5.9.3",
+        "vitest": "^4.0.18"
+    },
+    "dependencies": {
+        "commander": "^14.0.3",
+        "duck-duck-scrape": "^2.2.5",
+        "openai": "^6.17.0",
+        "uuid": "^13.0.0",
+        "yahoo-finance2": "^2.11.3",
+        "zod": "^4.3.6"
+    },
+    "peerDependencies": {
+        "openai": "^6.17.0",
+        "better-sqlite3": "^11.0.0"
+    },
+    "peerDependenciesMeta": {
+        "openai": {
+            "optional": true
+        },
+        "better-sqlite3": {
+            "optional": true
+        }
+    },
+    "engines": {
+        "node": ">=18.0.0"
+    }
+}

package/src/agent.ts

@@ -0,0 +1,187 @@
+/**
+ * Agno-style Agent class: one-line agent with clean process.
+ *
+ * Build agents that remember users across sessions and run anytime.
+ * Uses model (from env), db (session store), optional learning/session memory, and default tools.
+ *
+ * @see https://github.com/agno-agi/agno
+ */
+
+import type { SessionStore } from './session/types.js';
+import type { Tool, ToolRegistry } from './tools/types.js';
+import type { CreateAgentOptions, CreateAgentResult, AgentRunOptions } from './create-agent.js';
+import { createAgent } from './create-agent.js';
+import { InMemorySessionStore } from './session/index.js';
+import { HttpClientTool } from './tools/http-tool.js';
+import { BrowserTool } from './tools/browser-tool.js';
+import type { AgenticRunResult } from './agentic/types.js';
+
+/**
+ * Agno-style agent options: minimal config for a clean agent process.
+ */
+export interface AgentOptions {
+    /** Agent name (default: 'Agent') */
+    name?: string;
+    /** System instructions / prompt */
+    instructions: string;
+    /**
+     * Model: id (e.g. gpt-4o) or "provider:model_id" (e.g. openai:gpt-4o, openrouter:anthropic/claude-3.5-sonnet, ollama:llama3.2).
+     * Omitted: uses OPENAI_API_KEY + OPENAI_MODEL from env.
+     */
+    model?: string;
+    /** API key (optional; falls back to OPENAI_API_KEY / OPENROUTER_API_KEY) */
+    apiKey?: string;
+    /** Base URL for API (e.g. Ollama). Falls back to OPENAI_BASE_URL. */
+    baseURL?: string;
+    /** Use OpenRouter (set apiKey/model here or via env) */
+    openRouter?: { apiKey?: string; model?: string };
+    /**
+     * Session store for conversation persistence (db in Agno terms).
+     * Default: InMemorySessionStore(). Use a persistent store (e.g. SQLite) for production.
+     */
+    db?: SessionStore;
+    /**
+     * When true, agent uses session memory: pass sessionId to run() to continue conversations.
+     * Default: true. Set false for stateless single-turn runs only.
+     */
+    learning?: boolean;
+    /** Tools: array or registry. Default: [HttpClientTool, BrowserTool]. Plug any tools by implementing Tool[] or ToolRegistry. */
+    tools?: Tool[] | ToolRegistry;
+    /** Max agentic steps (default: 10) */
+    maxSteps?: number;
+    /** Run timeout ms (default: 60000) */
+    timeoutMs?: number;
+    /** Guardrails. Default: true (sensitive-data rule). Set false to disable. */
+    guardrails?: CreateAgentOptions['guardrails'];
+    /** Retry policy for LLM/tool calls */
+    retry?: CreateAgentOptions['retry'];
+    /** Cross-tool middleware (logging, rate limit, etc.). */
+    toolMiddleware?: CreateAgentOptions['toolMiddleware'];
+    /** Optional logger for production observability */
+    logger?: CreateAgentOptions['logger'];
+    /** Learning mode: always vs agentic */
+    learningMode?: CreateAgentOptions['learningMode'];
+    /** User profile store (profiles that persist across sessions) */
+    userProfileStore?: CreateAgentOptions['userProfileStore'];
+    /** Memory store (memories that accumulate, knowledge that transfers) */
+    memoryStore?: CreateAgentOptions['memoryStore'];
+    /** RAG engine (agentic RAG, hybrid search, reranking) */
+    ragEngine?: CreateAgentOptions['ragEngine'];
+    /** Type-safe input/output schemas (Zod) */
+    inputSchema?: CreateAgentOptions['inputSchema'];
+    outputSchema?: CreateAgentOptions['outputSchema'];
+}
+
+/**
+ * Agno-style Agent: create once, run anytime with a clean process.
+ *
+ * @example
+ * // One line – uses OPENAI_API_KEY, default tools (http + browser), session memory
+ * const agent = new Agent({
+ *   instructions: 'You are a helpful assistant. Use the web when needed.',
+ * });
+ * const result = await agent.run('What is the weather in Tokyo?');
+ *
+ * @example
+ * // With session (learning) – remembers conversation
+ * const agent = new Agent({ instructions: '...', learning: true });
+ * const sessionId = await agent.createSession('user-1');
+ * const r1 = await agent.run('My name is Alice.', { sessionId });
+ * const r2 = await agent.run('What is my name?', { sessionId }); // "Alice"
+ *
+ * @example
+ * // Model from env or explicit
+ * const agent = new Agent({
+ *   instructions: '...',
+ *   model: 'openai:gpt-4o',  // or just 'gpt-4o' with OPENAI_API_KEY set
+ * });
+ *
+ * @example
+ * // Local Ollama
+ * const agent = new Agent({
+ *   instructions: '...',
+ *   baseURL: 'http://localhost:11434/v1',
+ *   model: 'llama3.2',
+ * });
+ */
+export class Agent {
+    readonly name: string;
+    readonly instructions: string;
+    readonly learning: boolean;
+    private readonly delegate: CreateAgentResult;
+
+    constructor(options: AgentOptions) {
+        const {
+            name = 'Agent',
+            instructions,
+            model,
+            apiKey,
+            baseURL,
+            openRouter,
+            db,
+            learning = true,
+            tools = [new HttpClientTool(), new BrowserTool()],
+            maxSteps,
+            timeoutMs,
+            guardrails,
+            retry,
+            toolMiddleware,
+            logger,
+            learningMode,
+            userProfileStore,
+            memoryStore,
+            ragEngine,
+            inputSchema,
+            outputSchema,
+        } = options;
+
+        const createOpts: CreateAgentOptions = {
+            name,
+            instructions,
+            model,
+            apiKey,
+            baseURL,
+            openRouter,
+            tools,
+            toolMiddleware,
+            sessionStore: db ?? new InMemorySessionStore(),
+            guardrails,
+            maxSteps,
+            timeoutMs,
+            retry,
+            logger,
+            learningMode,
+            userProfileStore,
+            memoryStore,
+            ragEngine,
+            inputSchema,
+            outputSchema,
+        };
+
+        this.delegate = createAgent(createOpts);
+        this.name = this.delegate.name;
+        this.instructions = this.delegate.instructions;
+        this.learning = learning;
+    }
+
+    /**
+     * Run the agent with a prompt. Pass sessionId for conversation memory (when learning is true).
+     */
+    async run(prompt: string, options?: AgentRunOptions): Promise<AgenticRunResult> {
+        return this.delegate.run(prompt, options);
+    }
+
+    /**
+     * Create a new session (returns sessionId to pass to run() for multi-turn memory).
+     */
+    async createSession(userId?: string): Promise<string> {
+        return this.delegate.createSession(userId);
+    }
+
+    /**
+     * Get messages for a session (if using a session store).
+     */
+    async getSessionMessages(sessionId: string) {
+        return this.delegate.getSessionMessages(sessionId);
+    }
+}

package/src/agentic/index.ts

@@ -0,0 +1,87 @@
+/**
+ * Agentic loop (ReAct-style) exports
+ */
+
+export * from './types.js';
+export { AgenticRunner } from './runner.js';
+
+import type { LLMProvider } from '../llm/types.js';
+import type { ToolRegistry, ToolMiddleware } from '../tools/types.js';
+import type { AgenticRunConfig, AgenticRunResult, AgenticStreamHooks } from './types.js';
+import type { HumanInTheLoopHooks, GuardrailEngine } from '../guardrails/types.js';
+import { AgenticRunner } from './runner.js';
+import { toToolRegistry, type ToolProvider } from '../tools/registry.js';
+
+/**
+ * Create a production-style agentic agent (ReAct loop with LLM + tools).
+ * Use with OpenAIProvider or any LLMProvider implementation.
+ * Supports Tool[] or ToolRegistry and optional tool middleware for cross-tool integration.
+ *
+ * @example
+ * import { createAgenticAgent, OpenAIProvider } from '@agent-framework/core';
+ * const agent = createAgenticAgent({
+ *   name: 'Researcher',
+ *   instructions: 'You research topics and cite sources.',
+ *   llm: new OpenAIProvider({ model: 'gpt-4o' }),
+ *   tools: myToolRegistry,
+ *   toolMiddleware: [loggingMiddleware],
+ *   maxSteps: 10,
+ * });
+ * const result = await agent.run({ prompt: 'Latest TypeScript news', instructions: agent.instructions });
+ */
+export function createAgenticAgent(config: {
+    name: string;
+    instructions: string;
+    llm: LLMProvider;
+    tools: ToolRegistry | import('../tools/types.js').Tool[];
+    maxSteps?: number;
+    timeoutMs?: number;
+    retry?: import('./types.js').AgenticRetryPolicy;
+    humanInTheLoop?: HumanInTheLoopHooks;
+    guardrails?: GuardrailEngine;
+    toolMiddleware?: ToolMiddleware[];
+}): {
+    name: string;
+    instructions: string;
+    run(
+        runConfig: { prompt: string; instructions?: string; messages?: import('../llm/types.js').Message[]; maxSteps?: number; timeoutMs?: number },
+        hooks?: AgenticStreamHooks
+    ): Promise<AgenticRunResult>;
+} {
+    const toolRegistry = toToolRegistry(config.tools as ToolProvider);
+
+    const runner = new AgenticRunner({
+        llm: config.llm,
+        tools: toolRegistry,
+        maxSteps: config.maxSteps ?? 10,
+        timeoutMs: config.timeoutMs ?? 60_000,
+        retry: config.retry,
+        toolMiddleware: config.toolMiddleware,
+    });
+
+    // Set human-in-the-loop hooks if provided
+    if (config.humanInTheLoop) {
+        runner.setHumanInTheLoop(config.humanInTheLoop);
+    }
+
+    // Set guardrails if provided
+    if (config.guardrails) {
+        runner.setGuardrails(config.guardrails);
+    }
+
+    return {
+        name: config.name,
+        instructions: config.instructions,
+        async run(runConfig, hooks) {
+            const instructions = runConfig.instructions ?? config.instructions;
+            const cfg: AgenticRunConfig = {
+                instructions,
+                prompt: runConfig.prompt,
+                messages: runConfig.messages,
+                maxSteps: runConfig.maxSteps,
+                timeoutMs: runConfig.timeoutMs,
+            };
+            return runner.run(cfg, hooks);
+        },
+    };
+}