confused-ai-core 0.1.0 → 0.1.2

package/Readme.md

@@ -0,0 +1,331 @@
+# @confused-ai/core
+
+**Production-grade TypeScript framework for orchestrating multi-agent workflows.**
+
+- **One-line agents** — `createAgent({ name, instructions })` with auto LLM, session, tools, guardrails
+- **Model-agnostic** — OpenAI, OpenRouter, Ollama via `model: "openai:gpt-4o"` or env
+- **Production-ready** — Circuit breaker, rate limiter, health checks, graceful shutdown, OTLP
+- **Pluggable** — Session stores, vector stores, RAG, tools, guardrails, voice (TTS/STT)
+
+---
+
+## Install
+
+```bash
+npm install @confused-ai/core
+# or
+pnpm add @confused-ai/core
+# or
+bun add @confused-ai/core
+```
+
+**Peer dependencies (optional):** `openai` (for OpenAIProvider), `better-sqlite3` (for SQLite session store). Install if you use those features.
+
+**Requirements:** Node.js >= 18.
+
+---
+
+## Quick Start
+
+### Minimal agent (uses `OPENAI_API_KEY` + default tools)
+
+```typescript
+import { createAgent } from '@confused-ai/core';
+
+const agent = createAgent({
+  name: 'Assistant',
+  instructions: 'You are helpful and concise.',
+});
+
+const result = await agent.run('What is 2 + 2?');
+console.log(result.text);
+```
+
+### With conversation memory (session)
+
+```typescript
+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 });
+console.log(result.text);
+```
+
+### Custom model (OpenRouter, Ollama, etc.)
+
+```typescript
+const agent = createAgent({
+  name: 'Assistant',
+  instructions: 'You are helpful.',
+  model: 'openrouter:anthropic/claude-3.5-sonnet',
+  // or Ollama: model: 'ollama:llama3.2', baseURL: 'http://localhost:11434/v1'
+});
+const result = await agent.run('Hello!');
+```
+
+### Streaming
+
+```typescript
+await agent.run('Explain TypeScript in 3 sentences.', {
+  sessionId,
+  onChunk: (chunk) => process.stdout.write(chunk),
+});
+```
+
+---
+
+## Feature overview
+
+| Category        | Features                                                                                                                                               |
+| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| **Learning**    | User profiles, persistent memory stores, RAG, always/agentic learning modes.                                                                           |
+| **Core**        | Model-agnostic (OpenAI/OpenRouter/Ollama), type-safe I/O with Zod, async-first, retries, multimodal messages.                                         |
+| **Knowledge**   | RAGEngine, hybrid search, reranking, session/state persistence, pluggable vector stores.                                                               |
+| **Orchestration** | Human-in-the-loop hooks, guardrails (sensitive data/schema), MCP & A2A, 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 (images, audio, video).                                                          |
+| **Voice**       | TTS/STT with OpenAI and ElevenLabs, voice ID selection, streaming audio.                                                                                |
+
+---
+
+## API reference
+
+### Main entry: `createAgent`
+
+```typescript
+import {
+  createAgent,
+  type CreateAgentOptions,
+  type CreateAgentResult,
+  type AgentRunOptions,
+} from '@confused-ai/core';
+
+const agent: CreateAgentResult = createAgent({
+  name: string;
+  instructions: string;
+  model?: string;                    // e.g. 'gpt-4o', 'openrouter:...', 'ollama:...'
+  apiKey?: string;
+  baseURL?: string;
+  tools?: Tool[] | ToolRegistry;
+  sessionStore?: SessionStore;
+  guardrails?: GuardrailEngine | false;
+  maxSteps?: number;
+  timeoutMs?: number;
+  dev?: boolean;
+  // ... see CreateAgentOptions
+});
+
+// Run once
+const result = await agent.run(prompt, { sessionId?, onChunk?, onToolCall? });
+
+// Sessions
+const sessionId = await agent.createSession(userId?);
+const messages = await agent.getSessionMessages(sessionId);
+```
+
+---
+
+## Subpath imports and examples
+
+Use subpath imports for smaller bundles and clear separation.
+
+### Production: circuit breaker
+
+```typescript
+import { createLLMCircuitBreaker } from '@confused-ai/core/production';
+
+const breaker = createLLMCircuitBreaker('openai');
+
+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);
+}
+```
+
+### Production: rate limiter
+
+```typescript
+import { createOpenAIRateLimiter } from '@confused-ai/core/production';
+
+const limiter = createOpenAIRateLimiter('tier1'); // 60 RPM
+
+await limiter.execute(async () => {
+  return await openai.chat.completions.create({ ... });
+});
+```
+
+### Production: health checks
+
+```typescript
+import {
+  HealthCheckManager,
+  createLLMHealthCheck,
+} from '@confused-ai/core/production';
+
+const health = new HealthCheckManager({ version: '1.0.0' });
+health.addComponent(createLLMHealthCheck(llmProvider));
+
+// Express
+app.get('/health', async (req, res) => {
+  const result = await health.check();
+  res.status(result.status === 'HEALTHY' ? 200 : 503).json(result);
+});
+```
+
+### Production: graceful shutdown
+
+```typescript
+import { GracefulShutdown, createGracefulShutdown } from '@confused-ai/core/production';
+
+const shutdown = createGracefulShutdown({ timeoutMs: 30000 });
+
+shutdown.addHandler('database', async () => {
+  await db.close();
+});
+shutdown.addHandler('http-server', async () => {
+  await server.close();
+});
+
+shutdown.listen(); // Handles SIGTERM/SIGINT
+```
+
+### Production: resumable streaming
+
+```typescript
+import {
+  ResumableStreamManager,
+  formatSSE,
+} from '@confused-ai/core/production';
+
+const manager = new ResumableStreamManager();
+const streamId = manager.createStream();
+
+// On each chunk from LLM
+manager.saveChunk(streamId, { type: 'text', content: 'Hello' });
+
+// Client reconnects
+const checkpoint = manager.getCheckpoint(streamId);
+const missed = manager.getChunksSince(streamId, clientPosition);
+for (const chunk of missed) {
+  res.write(formatSSE(chunk));
+}
+```
+
+### LLM: caching
+
+```typescript
+import { LLMCache, withCache } from '@confused-ai/core/llm';
+
+const cache = new LLMCache({ maxEntries: 1000, ttlMs: 60000 });
+const cachedLLM = withCache(llm, cache);
+
+const response = await cachedLLM.generateText(messages);
+```
+
+### Artifacts
+
+```typescript
+import {
+  InMemoryArtifactStorage,
+  createPlanArtifact,
+  createTextArtifact,
+  createReasoningArtifact,
+} from '@confused-ai/core/artifacts';
+
+const storage = new InMemoryArtifactStorage();
+
+const plan = await storage.save(
+  createPlanArtifact('project-plan', 'Build a chatbot', [
+    { description: 'Design conversation flows' },
+    { description: 'Implement intent detection' },
+  ])
+);
+
+const text = await storage.save(
+  createTextArtifact('readme', 'markdown', '# Hello')
+);
+
+const retrieved = await storage.get(plan.id);
+```
+
+### Voice (TTS / STT)
+
+```typescript
+import {
+  OpenAIVoiceProvider,
+  ElevenLabsVoiceProvider,
+  createVoiceProvider,
+} from '@confused-ai/core/voice';
+
+const voice = createVoiceProvider({ provider: 'openai' }); // or { provider: 'elevenlabs' }
+
+// Text-to-Speech
+const { audio } = await voice.textToSpeech('Hello, world!', {
+  voiceId: 'nova',
+  speed: 1.0,
+});
+
+// Speech-to-Text
+const { text } = await voice.speechToText(audioBuffer);
+```
+
+### Observability (OTLP)
+
+```typescript
+import {
+  OTLPTraceExporter,
+  OTLPMetricsExporter,
+} from '@confused-ai/core/observability';
+
+// Configure OTLP exporters for traces and metrics
+const traceExporter = new OTLPTraceExporter({ endpoint: 'http://localhost:4318' });
+const metricsExporter = new OTLPMetricsExporter({ endpoint: 'http://localhost:4318' });
+```
+
+---
+
+## Module map (subpaths)
+
+| Import path                 | Contents                                                                 |
+| --------------------------- | ------------------------------------------------------------------------ |
+| `@confused-ai/core`        | Main API: `createAgent`, Agent, tools, session, guardrails, errors, etc. |
+| `@confused-ai/core/production` | Circuit breaker, rate limiter, health, graceful shutdown, resumable stream |
+| `@confused-ai/core/llm`     | OpenAIProvider, OpenRouter, model resolver, LLMCache, withCache          |
+| `@confused-ai/core/artifacts` | InMemoryArtifactStorage, createPlanArtifact, createTextArtifact, MediaManager |
+| `@confused-ai/core/voice`  | OpenAIVoiceProvider, ElevenLabsVoiceProvider, createVoiceProvider       |
+| `@confused-ai/core/observability` | ConsoleLogger, InMemoryTracer, OTLPTraceExporter, OTLPMetricsExporter |
+| `@confused-ai/core/session`    | InMemorySessionStore, SQLiteSessionStore, SessionStore types            |
+| `@confused-ai/core/guardrails`  | GuardrailValidator, createSensitiveDataRule, allowlist                   |
+| `@confused-ai/core/tools`      | HttpClientTool, BrowserTool, registry, base tools                       |
+| `@confused-ai/core/memory`     | Vector store, in-memory memory store                                    |
+| `@confused-ai/core/orchestration` | Orchestrator, pipeline, supervisor, swarm, MCP types                  |
+| `@confused-ai/core/agentic`    | Agentic runner and types (used by createAgent)                          |
+| `@confused-ai/core/core`       | Base agent, context builder, schemas                                    |
+| `@confused-ai/core/planner`    | Classical planner, LLM planner                                          |
+| `@confused-ai/core/execution`  | Execution engine, graph builder, worker pool                            |
+
+---
+
+## Environment variables
+
+| Variable                 | Purpose                          |
+| ------------------------ | -------------------------------- |
+| `OPENAI_API_KEY`         | Default OpenAI API key           |
+| `OPENAI_MODEL`           | Default model (e.g. `gpt-4o`)     |
+| `OPENAI_BASE_URL`        | Custom API base (e.g. Ollama)    |
+| `OPENROUTER_API_KEY`     | OpenRouter API key               |
+| `OPENROUTER_MODEL`       | OpenRouter model                 |
+
+---
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "confused-ai-core",
-    "version": "0.1.0",
+    "version": "0.1.2",
     "description": "Confused AI - Production-grade TypeScript framework for orchestrating multi-agent workflows",
     "type": "module",
     "main": "./dist/index.js",

package/FEATURES.md

@@ -1,169 +0,0 @@
-# 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';
-```