confused-ai-core

The production-grade TypeScript framework for multi-agent workflows.

Build robust AI agents with one line of code. Features built-in state management, tool orchestration, and production safeguards.

🚀 Quick Start

1. Install

npm install confused-ai-core
# or
bun add confused-ai-core

2. Create an Agent

import { createAgent } from 'confused-ai-core';

const agent = createAgent({
  name: 'Assistant',
  instructions: 'You are a helpful AI assistant.',
});

const result = await agent.run('Hello world!');
console.log(result.text);

💡 Common Patterns

Persistence (Sessions)

Keep conversation history across requests using sessions.

// Create a session for a user
const sessionId = await agent.createSession('user-123');

// First turn
await agent.run('My name is Alice', { sessionId });

// Second turn (remembers context)
const response = await agent.run('What is my name?', { sessionId });
console.log(response.text); // "Alice"

Streaming Response

Stream output tokens in real-time.

await agent.run('Write a haiku', {
  onChunk: (chunk) => process.stdout.write(chunk),
});

Custom Models

Support for OpenAI, OpenRouter, and Ollama out of the box.

const agent = createAgent({
  name: 'Researcher',
  instructions: 'Analyze data.',
  model: 'openrouter:anthropic/claude-3.5-sonnet',
  // or 'ollama:llama3' (requires running ollama serve)
});

📦 Features & Modules

The framework is modular. Import what you need.

| Module | Import | Description | | :--- | :--- | :--- | | Core | confused-ai-core | Main entry, Agent, Tools | | Production | confused-ai-core/production | Circuit Breakers, Rate Limiters, Health Checks | | Artifacts | confused-ai-core/artifacts | Typed output (plans, code, reasoning) | | Voice | confused-ai-core/voice | TTS/STT (OpenAI, ElevenLabs) | | Memory | confused-ai-core/memory | Vector Stores, RAG | | Guardrails | confused-ai-core/guardrails | PII Redaction, Policy Checks | | Observability | confused-ai-core/observability | OTLP Tracing & Metrics |

🛠️ Tools Reference

Ready-to-use tools for your agents.

| Tool | Import | Capabilities | | :--- | :--- | :--- | | Browser | BrowserTool | Headless navigation, screenshots, content extraction | | Calculator | CalculatorToolkit | Basic math, factorials, prime checks, exponentiation | | Files | FileTool | Read, write, and manage local files safely | | GitHub | GitHubToolkit | Manage issues, PRs, comments, search repositories | | Slack | SlackToolkit | Send messages, list channels, read history | | Jira | JiraToolkit | Create/search issues, manage tickets | | Notion | NotionToolkit | Create, search, and update pages | | Web Search | WebSearchToolkit | Search web (DuckDuckGo), news aggregation | | Google | SerpApiToolkit | Google Search, YouTube Search (via SerpApi) | | Wikipedia | WikipediaToolkit | Search and retrieve Wikipedia articles | | Shell | ShellToolkit | Execute shell commands (sandboxed) | | OpenAI | OpenAIToolkit | Generate images (DALL-E), transcribe audio | | HackerNews | HackerNewsToolkit | Read top stories, user profiles | | Crypto/Stocks | YahooFinanceTool | Stock prices, crypto data (via Yahoo Finance) |

Example: Production Safeguards

import { createLLMCircuitBreaker } from 'confused-ai-core/production';

const breaker = createLLMCircuitBreaker('openai');

const result = await breaker.execute(async () => {
  return await agent.run('Complex task');
});

🔧 Environment Variables

| Variable | Description | | :--- | :--- | | OPENAI_API_KEY | Key for OpenAI models | | OPENROUTER_API_KEY | Key for OpenRouter models | | OPENAI_BASE_URL | Override for compatible endpoints (e.g. Ollama) |

License

MIT