@aeye/ai 0.3.7 → 0.3.8

package/README.md

@@ -2,114 +2,48 @@
 
 > **Multi-provider AI library with intelligent model selection, type-safe context management, and comprehensive hooks system.**
 
-The `@aeye/ai` package is the main AI library built on `@aeye/core`, providing a unified interface for working with multiple AI providers (OpenAI, Anthropic, Google, etc.) with automatic model selection, cost tracking, and extensible architecture.
+The `@aeye/ai` package is the main AI library built on `@aeye/core`, providing a unified interface for working with multiple AI providers with automatic model selection, cost tracking, and extensible architecture.
 
 ```ts
+import { AI } from '@aeye/ai';
+import { OpenAIProvider } from '@aeye/openai';
+import z from 'zod';
+
+const openai = new OpenAIProvider({ apiKey: process.env.OPENAI_API_KEY! });
+
 const ai = AI.with<MyContext>()
   .providers({ openai })
-  .create(/* options, hooks, etc */)
-
-ai.chat.get(request, ctx?)
-ai.chat.stream(request, ctx?)
-ai.image.generate.get(request, ctx?)
-ai.image.generate.stream(request, ctx?)
-ai.image.edit.get(request, ctx?)
-ai.image.edit.stream(request, ctx?)
-ai.image.analyze.get(request, ctx?)
-ai.image.analyze.stream(request, ctx?)
-ai.transcribe.get(request, ctx?)
-ai.transcribe.stream(request, ctx?)
-ai.speech.get(request, ctx?)
-ai.speech.stream(request, ctx?)
+  .create({ /* defaultContext, providedContext, defaultWeights, hooks, ... */ });
+
+// Low-level APIs
+ai.chat.get(request, ctx?)           // or .stream(request, ctx?)
+ai.image.generate.get(request, ctx?) // or .stream(request, ctx?)
+ai.image.edit.get(request, ctx?)     // or .stream(request, ctx?)
+ai.image.analyze.get(request, ctx?)  // or .stream(request, ctx?)
+ai.transcribe.get(request, ctx?)     // or .stream(request, ctx?)
+ai.speech.get(request, ctx?)         // or .stream(request, ctx?)
 ai.embed.get(request, ctx?)
-ai.embed.stream(request, ctx?)
-ai.models.list() // get(id), search(criteria), select(criteria), refresh()
-ai.providers.openai // Provider
-ai.hooks // Hook events to implement BYOK
-ai.components // all prompts/tools/agents created on this ai
-
-// Define prompts, tools, agents
-const chatPrompt = ai.prompt({
-  name: 'chat_prompt',
-  description: 'A helpful chat assistant that answers user questions',
-  content: `You are a helpful assistant. The user {{user}} has asked: {{question}}
-Answer their question clearly and concisely. If you need more information, use the available tools.`,
-  input: (input: { user: string; question: string }) => input,
-  schema: z.object({ answer: z.string() }),
-  refs: [relevantInfo],
-});
+ai.models.list()  // .get(id), .search(criteria), .select(criteria), .refresh()
 
-const analyzeConversation = ai.prompt({
-  name: 'analyze_conversation',
-  description: 'Analyzes a conversation to judge how accurately the agent performed the requests',
-  content: `You are a conversational analyst. Analyze the following conversation between user {{user}} and the assistant.
-Messages: {{messages}}
-Return a summary of how well the agent performed and a rating between 0 and 100.`,
-  input: (input: { user: string; messages: string }) => input,
-  schema: z.object({ summary: z.string(), rating: z.number() }),
-});
-
-// Tool
-const relevantInfo = ai.tool({
-  name: 'relevant_info',
-  description: `Searches for info relevant to a user's question`,
-  instructions: 'Use the relevant_info tool to look up information to better answer questions',
-  schema: z.object({
-    query: z.string(),
-  }),
-  call: async ({ query }, refs, ctx) => {
-    return await DB.getRelevantInfo(query, 10);
-  }
-});
+// Components bound to this AI instance
+const myTool   = ai.tool({ name, description, schema, call, ... });
+const myPrompt = ai.prompt({ name, description, content, tools, schema, ... });
+const myAgent  = ai.agent({ name, description, refs, call });
 
-// Agent
-const chatAgent = ai.agent({
-  name: 'chat_agent',
-  description: 'An agent to chat with the user and analyze the conversation',
-  refs: [relevantInfo, chatPrompt, analyzeConversation],
-  call: async (input: { user: string; question: string }, refs, ctx) => {
-    // Get the chat response
-    const chatResponse = await refs[1].run({
-      user: input.user,
-      question: input.question
-    }, ctx);
-
-    // Analyze the conversation
-    const messages = JSON.stringify([
-      { role: 'user', content: input.question },
-      { role: 'assistant', content: chatResponse.answer }
-    ]);
-
-    const analysis = await refs[2].run({
-      user: input.user,
-      messages
-    }, ctx);
-
-    return {
-      answer: chatResponse.answer,
-      analysis: {
-        summary: analysis.summary,
-        rating: analysis.rating
-      }
-    };
-  },
-});
-
-// Use the agent
-const result = await chatAgent.run(
-  { user: 'ClickerMonkey', question: 'What is TypeScript?' },
-  { messages: [] }
-);
-console.log(result.answer);
-console.log(`Quality rating: ${result.analysis.rating}/100`);
+myTool.run(input, ctx?)
+myPrompt.run(input, ctx?)                    // streaming generator
+myPrompt.get('result', input, ctx?)          // awaitable result
+myPrompt.get('stream', input, ctx?)          // stream all events
+myPrompt.get('streamContent', input, ctx?)   // stream text only
+myAgent.run(input, ctx?)
 ```
 
 ## Features
 
-- **Multi-Provider Support**: Single interface for OpenAI, Anthropic, Google, Replicate, and custom providers
+- **Multi-Provider Support**: Single interface for OpenAI, OpenRouter, Replicate, AWS Bedrock, and custom providers
 - **Intelligent Model Selection**: Automatic model selection based on capabilities, cost, speed, and quality
 - **Type-Safe Context**: Strongly-typed context and metadata with compiler validation
-- **Comprehensive APIs**: Chat, Image Generation/Analysis, Speech Synthesis/Transcription, Embeddings
+- **Comprehensive APIs**: Chat, Image Generation/Analysis/Editing, Speech Synthesis, Transcription, Embeddings
 - **Lifecycle Hooks**: Intercept and modify operations at every stage
 - **Cost Tracking**: Automatic token usage and cost calculation
 - **Streaming Support**: Full streaming support across all compatible capabilities
@@ -129,13 +63,14 @@ console.log(`Quality rating: ${result.analysis.rating}/100`);
   - [Transcribe API](#transcribe-api)
   - [Embed API](#embed-api)
   - [Models API](#models-api)
+- [Tools, Prompts & Agents](#tools-prompts--agents)
 - [Advanced Features](#advanced-features)
   - [Custom Context & Metadata](#custom-context--metadata)
   - [Lifecycle Hooks](#lifecycle-hooks)
   - [Model Selection](#model-selection)
   - [Model Sources](#model-sources)
   - [Custom Providers](#custom-providers)
-- [TypeScript Guide](#typescript-guide)
+  - [Extending AI Instances](#extending-ai-instances)
 - [Examples](#examples)
 
 ## Installation
@@ -147,7 +82,10 @@ npm install @aeye/ai @aeye/core
 You'll also need provider packages:
 
 ```bash
-npm install @aeye/openai @aeye/anthropic  # etc.
+npm install @aeye/openai openai       # OpenAI
+npm install @aeye/openrouter          # OpenRouter
+npm install @aeye/replicate replicate # Replicate
+npm install @aeye/aws                 # AWS Bedrock
 ```
 
 ## Quick Start
@@ -157,29 +95,23 @@ import { AI } from '@aeye/ai';
 import { OpenAIProvider } from '@aeye/openai';
 import { OpenRouterProvider } from '@aeye/openrouter';
 
-// Create providers
-const openai = new OpenAIProvider({ apiKey: '123' });
-const openrouter = new OpenRouterProvider({ apiKey: 'abc' });
+const openai = new OpenAIProvider({ apiKey: process.env.OPENAI_API_KEY! });
+const openrouter = new OpenRouterProvider({ apiKey: process.env.OPENROUTER_API_KEY! });
 
-// Create an AI instance
 const ai = AI.with()
   .providers({ openai, openrouter })
-  .create({
-    defaultContext: {
-      apiVersion: 'v1'
-    }
-  });
+  .create();
 
 // Simple chat completion
-const response = await ai.chat.get([
-  { role: 'user', content: 'What is TypeScript?' }
-]);
+const response = await ai.chat.get({
+  messages: [{ role: 'user', content: 'What is TypeScript?' }]
+});
 console.log(response.content);
 
 // Streaming
-for await (const chunk of ai.chat.stream([
-  { role: 'user', content: 'Write a poem' }
-])) {
+for await (const chunk of ai.chat.stream({
+  messages: [{ role: 'user', content: 'Write a poem' }]
+})) {
   if (chunk.content) {
     process.stdout.write(chunk.content);
   }
@@ -188,127 +120,76 @@ for await (const chunk of ai.chat.stream([
 
 ## Architecture
 
-The `@aeye/ai` library is structured around several key components:
+```mermaid
+graph TD
+    AI["<b>AI Class</b><br/>Context Management<br/>Model Registry<br/>Lifecycle Hooks"]
+    APIs["<b>APIs</b><br/>Chat · Image<br/>Speech · Embed"]
+    Registry["<b>Registry</b><br/>Models · Search · Select"]
+    Providers["<b>Providers</b><br/>OpenAI · OpenRouter<br/>Replicate · AWS · Custom"]
 
+    AI --> APIs
+    AI --> Registry
+    Registry --> Providers
+    APIs --> Providers
 ```
-┌─────────────────────────────────────────────────────────┐
-│                        AI Class                         │
-│  - Context Management                                   │
-│  - Model Registry                                       │
-│  - Lifecycle Hooks                                      │
-└─────────────────┬───────────────────────────────────────┘
-                  │
-         ┌────────┴─────────┐
-         │                  │
-    ┌────▼────┐      ┌─────▼──────┐
-    │  APIs   │      │  Registry  │
-    │         │      │            │
-    │ • Chat  │      │ • Models   │
-    │ • Image │      │ • Search   │
-    │ • Speech│      │ • Select   │
-    │ • Embed │      └────┬───────┘
-    └────┬────┘           │
-         │         ┌──────▼──────┐
-         │         │  Providers  │
-         │         │             │
-         │         │ • OpenAI    │
-         │         │ • Anthropic │
-         │         │ • Google    │
-         │         │ • Custom    │
-         └─────────┴─────────────┘
-```
-
-### Key Components
-
-1. **AI Class**: Central orchestrator managing context, metadata, providers, and APIs
-2. **APIs**: Specialized interfaces for different capabilities (chat, images, speech, etc.)
-3. **Model Registry**: Centralized model management with selection logic
-4. **Providers**: Pluggable implementations for different AI services
-5. **Context System**: Type-safe context and metadata threading
 
 ## Core Concepts
 
 ### Context
 
-Context is data passed through your entire AI operation. It's composed of:
+Context is data passed through your entire AI operation:
 
-- **Default Context**: Static values provided at AI creation
-- **Provided Context**: Async-loaded values (e.g., from database)
-- **Required Context**: Values that must be provided per-request
+- **Default Context**: Static values provided at AI creation via `defaultContext`
+- **Provided Context**: Async-loaded values (e.g., from a database) via `providedContext`
+- **Required Context**: Values that must be supplied per-call
 
 ```typescript
 interface AppContext {
-  user: User;
-  db: Database;
-  apiVersion: string;
+  userId: string;
+  user?: User;       // loaded by providedContext
+  db?: Database;     // loaded by providedContext
 }
 
 const ai = AI.with<AppContext>()
   .providers({ openai })
   .create({
-    defaultContext: {
-      apiVersion: 'v1'
-    },
     providedContext: async (ctx) => ({
-      user: await getUser(ctx.userId),
-      db: database
-    })
+      user: await db.users.findById(ctx.userId),
+      db,
+    }),
   });
 
-// Usage: only provide what's not already available
-await ai.chat.get(request, { userId: '123' });
+// At call time only userId is required — the rest is loaded automatically
+const response = await ai.chat.get(
+  { messages: [{ role: 'user', content: 'Hi!' }] },
+  { userId: 'user123' }
+);
 ```
 
 ### Metadata
 
-Metadata controls model selection and operation configuration:
+Metadata controls model selection and per-request configuration:
 
 ```typescript
 interface AppMetadata {
   priority: 'cost' | 'speed' | 'quality';
 }
 
-const ai = AI.with<AppContext, AppMetadata>()
+const ai = AI.with<{}, AppMetadata>()
   .providers({ openai, openrouter })
   .create({
-    defaultMetadata: {
-      priority: 'balanced'
-    }
+    defaultMetadata: { priority: 'cost' },
   });
 
-// Override per request
-await ai.chat.get(request, {
-  metadata: {
-    model: 'gpt-4',  // Specific model
-    required: ['chat', 'vision'],  // Required capabilities
-    weights: { cost: 0.7, speed: 0.3 }  // Selection weights
-  }
-});
-```
-
-### Model Selection
-
-Models are automatically selected based on:
-
-1. **Capabilities**: Required and optional features
-2. **Constraints**: Provider filters, context window, budget
-3. **Scoring**: Weighted evaluation of cost, speed, accuracy, context size
-
-```typescript
-// Automatic selection for vision task
+// Override per request via context
 const response = await ai.chat.get(
-  [{
-    role: 'user',
-    content: [
-      { type: 'text', content: 'What is in this image?' },
-      { type: 'image', content: imageUrl }
-    ]
-  }],
+  { messages: [{ role: 'user', content: 'Hello' }] },
   {
     metadata: {
-      required: ['chat', 'vision'],
-      weights: { cost: 0.5, speed: 0.5 }
-    }
+      model: 'openai/gpt-4o',        // pin a specific model
+      weights: { cost: 0.2, speed: 0.3, accuracy: 0.5 },
+      priority: 'quality',
+    },
   }
 );
 ```
@@ -317,33 +198,31 @@ const response = await ai.chat.get(
 
 ### Chat API
 
-The Chat API provides conversational AI with automatic model selection.
-
-#### Methods
-
-**`chat.get(messages, context?)`**
-
-Execute a non-streaming chat completion.
+**`chat.get(request, ctx?)`** — Non-streaming chat completion.
 
 ```typescript
-const response = await ai.chat.get([
-  { role: 'system', content: 'You are a helpful assistant.' },
-  { role: 'user', content: 'Hello!' }
-]);
+const response = await ai.chat.get({
+  messages: [
+    { role: 'system', content: 'You are a helpful assistant.' },
+    { role: 'user', content: 'Hello!' },
+  ],
+  temperature: 0.7,
+  maxTokens: 1024,
+});
 
 console.log(response.content);
-console.log(response.usage);  // Token usage
-console.log(response.finishReason);
+console.log(response.usage?.text?.input, 'input tokens');
+console.log(response.usage?.text?.output, 'output tokens');
+console.log(response.usage?.cost, 'cost in dollars');
+console.log(response.finishReason); // 'stop' | 'length' | 'tool_calls' | ...
 ```
 
-**`chat.stream(messages, context?)`**
-
-Execute a streaming chat completion.
+**`chat.stream(request, ctx?)`** — Streaming chat completion.
 
 ```typescript
-for await (const chunk of ai.chat.stream([
-  { role: 'user', content: 'Count to 10' }
-])) {
+for await (const chunk of ai.chat.stream({
+  messages: [{ role: 'user', content: 'Count to 10' }]
+})) {
   if (chunk.content) {
     process.stdout.write(chunk.content);
   }
@@ -353,849 +232,541 @@ for await (const chunk of ai.chat.stream([
 }
 ```
 
-#### Request Format
+**Vision:**
 
 ```typescript
-interface Request {
-  messages: Message[];
-  maxTokens?: number;
-  temperature?: number;
-  topP?: number;
-  tools?: Tool[];
-  responseFormat?: { type: 'json_object' | 'text' };
-  // ... other options
-}
-
-type Message =
-  | { role: 'system' | 'user' | 'assistant', content: string }
-  | { role: 'user', content: ContentPart[] };  // Multimodal
-
-type ContentPart =
-  | { type: 'text', content: string }
-  | { type: 'image', content: string };  // URL or base64
-```
-
-#### Response Format
-
-TODO: updated
-
-#### Examples
-
-**Basic Conversation**
-
-```typescript
-const messages = [
-  { role: 'system', content: 'You are a TypeScript expert.' },
-  { role: 'user', content: 'Explain generics' }
-];
-
-const response = await ai.chat.get(messages);
-console.log(response.content);
-```
-
-**Vision Analysis**
-
-```typescript
-const response = await ai.chat.get([
-  {
+const response = await ai.chat.get({
+  messages: [{
     role: 'user',
     content: [
       { type: 'text', content: 'What is in this image?' },
-      { type: 'image', content: 'https://example.com/image.jpg' }
-    ]
-  }
-], {
-  metadata: {
-    required: ['chat', 'vision']
-  }
+      { type: 'image', content: 'https://example.com/image.jpg' },
+    ],
+  }],
 });
-```
-
-**Function Calling**
-
-```typescript
-const tools = [
-  {
-    name: 'get_weather',
-    description: 'Get weather for a location',
-    parameters: {
-      type: 'object',
-      properties: {
-        location: { type: 'string' }
-      }
-    }
-  }
-];
-
-const response = await ai.chat.get(
-  [{ role: 'user', content: 'What is the weather in NYC?' }],
-  {
-    metadata: {
-      required: ['chat', 'tools']
-    }
-  }
-);
-
-if (response.toolCalls) {
-  for (const call of response.toolCalls) {
-    console.log(`Tool: ${call.function.name}`);
-    console.log(`Args: ${call.function.arguments}`);
-  }
-}
-```
-
-**Streaming with Token Counting**
-
-TODO: update with new types
-
-```typescript
-let totalTokens = 0;
-
-for await (const chunk of ai.chat.stream(messages)) {
-  if (chunk.content) {
-    process.stdout.write(chunk.content);
-  }
-  if (chunk.usage) {
-    totalTokens = chunk.usage.totalTokens;
-  }
-}
-
-console.log(`\nTotal tokens: ${totalTokens}`);
+// vision capability is detected automatically from the message content
 ```
 
 ### Image API
 
-The Image API provides image generation, editing, and analysis.
-
-#### Sub-APIs
-
-**`image.generate.get(request, context?)`**
-
-Generate images from text prompts.
+**`image.generate.get(request, ctx?)`** — Generate images from a text prompt.
 
 ```typescript
 const response = await ai.image.generate.get({
   prompt: 'A futuristic city at sunset',
   n: 2,
   size: '1024x1024',
-  quality: 'hd'
+  quality: 'high',
 });
 
 for (const image of response.images) {
-  console.log(image.url);
+  console.log(image.url ?? image.b64_json);
 }
 ```
 
-**`image.generate.stream(request, context?)`**
-
-Stream image generation progress.
+**`image.edit.get(request, ctx?)`** — Edit an image with inpainting.
 
 ```typescript
-for await (const chunk of ai.image.generate.stream({
-  prompt: 'A majestic mountain landscape'
-})) {
-  if (chunk.progress) {
-    console.log(`Progress: ${chunk.progress}%`);
-  }
-  if (chunk.done && chunk.image) {
-    console.log('Image URL:', chunk.image.url);
-  }
-}
-```
-
-**`image.edit.get(request, context?)`**
-
-Edit existing images with prompts.
+import fs from 'fs';
 
-```typescript
 const response = await ai.image.edit.get({
-  image: imageBuffer,
-  mask: maskBuffer,
   prompt: 'Add a sunset in the background',
-  size: '1024x1024'
+  image: fs.readFileSync('photo.png'),
+  mask: fs.readFileSync('mask.png'),
+  size: '1024x1024',
 });
 ```
 
-**`image.analyze.get(request, context?)`**
-
-Analyze images with vision models (uses chat models with vision capability).
+**`image.analyze.get(request, ctx?)`** — Analyze image content (uses a vision chat model).
 
 ```typescript
 const response = await ai.image.analyze.get({
   prompt: 'Describe this image in detail',
   images: ['https://example.com/photo.jpg'],
-  maxTokens: 500
 });
-
 console.log(response.content);
 ```
 
-#### Examples
-
-**Batch Generation**
-
-```typescript
-const response = await ai.image.generate.get({
-  prompt: 'Logo designs for a tech startup',
-  n: 4,
-  size: '512x512'
-});
-
-response.images.forEach((img, i) => {
-  console.log(`Design ${i + 1}: ${img.url}`);
-});
-```
-
-**Style Transfer**
-
-```typescript
-const response = await ai.image.generate.get({
-  prompt: 'Van Gogh style starry night over modern city',
-  quality: 'hd',
-  style: 'vivid'
-});
-```
-
 ### Speech API
 
-Text-to-speech synthesis.
-
-**`speech.get(request, context?)`**
+**`speech.get(request, ctx?)`** — Text-to-speech synthesis.
 
 ```typescript
+import fs from 'fs';
+import { Readable } from 'stream';
+
 const response = await ai.speech.get({
-  text: 'Hello, this is a test of text to speech.',
+  text: 'Hello, this is a text-to-speech example.',
   voice: 'alloy',
   speed: 1.0,
-  responseFormat: 'mp3'
 });
 
-// Save audio
-fs.writeFileSync('output.mp3', response.audioBuffer);
-```
-
-**`speech.stream(request, context?)`**
-
-```typescript
-for await (const chunk of ai.speech.stream({
-  text: 'Streaming audio generation...',
-  voice: 'nova'
-})) {
-  if (chunk.audioData) {
-    // Process audio chunks in real-time
-    audioStream.write(chunk.audioData);
-  }
-}
+// Pipe the audio stream to a file
+const fileStream = fs.createWriteStream('output.mp3');
+Readable.fromWeb(response.audio).pipe(fileStream);
 ```
 
 ### Transcribe API
 
-Speech-to-text transcription.
-
-**`transcribe.get(request, context?)`**
+**`transcribe.get(request, ctx?)`** — Speech-to-text transcription.
 
 ```typescript
-const audioBuffer = fs.readFileSync('recording.mp3');
+import fs from 'fs';
 
 const response = await ai.transcribe.get({
-  audio: audioBuffer,
+  audio: fs.readFileSync('recording.mp3'),
   language: 'en',
-  responseFormat: 'verbose_json',
-  timestampGranularities: ['word', 'segment']
 });
 
 console.log(response.text);
-console.log('Words:', response.words);
-console.log('Segments:', response.segments);
 ```
 
 ### Embed API
 
-Generate text embeddings for semantic search and similarity.
-
-**`embed.get(request, context?)`**
+**`embed.get(request, ctx?)`** — Generate text embeddings.
 
 ```typescript
 const response = await ai.embed.get({
   texts: [
     'TypeScript is a typed superset of JavaScript',
     'Python is a high-level programming language',
-    'Rust is a systems programming language'
   ],
-  dimensions: 1536
 });
 
-// Get embeddings
 response.embeddings.forEach(({ embedding, index }) => {
   console.log(`Text ${index}: ${embedding.length} dimensions`);
 });
-
-// Calculate similarity
-function cosineSimilarity(a: number[], b: number[]) {
-  const dot = a.reduce((sum, val, i) => sum + val * b[i], 0);
-  const magA = Math.sqrt(a.reduce((sum, val) => sum + val * val, 0));
-  const magB = Math.sqrt(b.reduce((sum, val) => sum + val * val, 0));
-  return dot / (magA * magB);
-}
-
-const sim = cosineSimilarity(
-  response.embeddings[0].embedding,
-  response.embeddings[1].embedding
-);
-console.log('Similarity:', sim);
 ```
 
 ### Models API
 
-Explore and manage available models.
-
-**`models.list()`**
-
 ```typescript
+// List all registered models
 const models = ai.models.list();
-console.log(`Available models: ${models.length}`);
 
-models.forEach(model => {
-  console.log(`${model.provider}/${model.id}`);
-  console.log(`  Tier: ${model.tier}`);
-  console.log(`  Capabilities: ${Array.from(model.capabilities).join(', ')}`);
-  console.log(`  Cost: $${model.pricing.text.input}/1M input tokens`);
+// Get a specific model
+const model = ai.models.get('gpt-4o');
+if (model) {
+  console.log('Context window:', model.contextWindow);
+  console.log('Capabilities:', Array.from(model.capabilities).join(', '));
+  console.log('Input cost:', model.pricing.text?.input, 'per 1M tokens');
+}
+
+// Search with selection criteria
+const results = ai.models.search({
+  capabilities: new Set(['chat', 'structured']),
+  weights: { cost: 0.6, speed: 0.4 },
+  providers: { allow: ['openai', 'openrouter'] },
+  contextWindow: { min: 100000 },
 });
+console.log('Best match:', results[0]?.model.id);
+
+// Refresh model list from all sources
+await ai.models.refresh();
 ```
 
-**`models.get(id)`**
+## Tools, Prompts & Agents
+
+Use `ai.tool()`, `ai.prompt()`, and `ai.agent()` to create components that are automatically wired to the AI instance (executor, streamer, and context are injected automatically).
+
+### Tool
 
 ```typescript
-const model = ai.models.get('gpt-4');
-if (model) {
-  console.log('Context window:', model.contextWindow);
-  console.log('Max output:', model.maxOutputTokens);
-}
+import z from 'zod';
+
+const searchKnowledge = ai.tool({
+  name: 'searchKnowledge',
+  description: 'Search the knowledge base for relevant information',
+  instructions: 'Use this to find information relevant to the query: "{{query}}"',
+  schema: z.object({
+    query: z.string().describe('Search query'),
+    limit: z.number().int().min(1).max(20).optional().describe('Max results (default: 5)'),
+  }),
+  call: async ({ query, limit = 5 }, _refs, ctx) => {
+    // ctx is the full AI context including your custom fields
+    return { results: await vectorSearch(query, limit) };
+  },
+});
 ```
 
-**`models.search(criteria)`**
+### Prompt
 
 ```typescript
-const results = ai.models.search({
-  required: ['chat', 'structured'],
-  optional: ['vision'],
-  weights: { cost: 0.6, speed: 0.4 },
-  providers: { allow: ['openai', 'anthropic'] },
-  minContextWindow: 100000
+const knowledgeAssistant = ai.prompt({
+  name: 'knowledgeAssistant',
+  description: 'Answers questions using the knowledge base',
+  content: `You are a helpful assistant. Use searchKnowledge to find information, then answer the question.
+
+Question: {{question}}`,
+  input: (input: { question: string }) => ({ question: input.question }),
+  tools: [searchKnowledge],
+  schema: z.object({
+    answer: z.string(),
+    sources: z.array(z.string()),
+  }),
 });
 
-console.log('Best match:', results[0].model.id);
-console.log('Score:', results[0].score);
+// Get structured result
+const result = await knowledgeAssistant.get('result', { question: 'How does X work?' });
+console.log(result?.answer);
+
+// Stream text
+for await (const text of knowledgeAssistant.get('streamContent', { question: 'How does X work?' })) {
+  process.stdout.write(text);
+}
 ```
 
-**`models.refresh()`**
+### Agent
 
 ```typescript
-console.log('Refreshing models...');
-await ai.models.refresh();
-console.log(`Now have ${ai.models.list().length} models`);
+const chatAgent = ai.agent({
+  name: 'chatAgent',
+  description: 'Chat with the user and analyze the response quality',
+  refs: [searchKnowledge, knowledgeAssistant] as const,
+  call: async (
+    input: { userId: string; question: string },
+    [search, assistant],
+    ctx
+  ) => {
+    // Step 1: Search for relevant context
+    const { results } = await search.run({ query: input.question }, ctx);
+
+    // Step 2: Generate answer with knowledge context
+    const answer = await assistant.get(
+      'result',
+      { question: input.question },
+      { ...ctx, messages: [] }
+    );
+
+    return {
+      userId: input.userId,
+      question: input.question,
+      answer: answer?.answer,
+      sources: answer?.sources ?? [],
+      contextUsed: results.length,
+    };
+  },
+});
+
+const result = await chatAgent.run({ userId: 'user1', question: 'What is aeye?' });
+console.log(result.answer);
 ```
 
 ## Advanced Features
 
 ### Custom Context & Metadata
 
-Define your application-specific context and metadata types:
-
 ```typescript
 interface AppContext {
-  user: User;
-  organization: Organization;
-  db: Database;
-  requestId: string;
+  userId: string;
+  user?: User;
+  db?: Database;
 }
 
 interface AppMetadata {
+  feature: 'chat' | 'analysis';
   priority: 'low' | 'normal' | 'high';
-  category: 'support' | 'sales' | 'internal';
-  maxCost: number;
 }
 
 const ai = AI.with<AppContext, AppMetadata>()
-  .providers({ openai, anthropic })
+  .providers({ openai, openrouter })
   .create({
-    defaultContext: {
-      requestId: uuid()
-    },
     providedContext: async (ctx) => {
-      // Load from database
       const user = await db.users.findById(ctx.userId);
-      const org = await db.orgs.findById(user.organizationId);
-      return { user, organization: org, db };
+      return { user, db };
     },
     defaultMetadata: {
       priority: 'normal',
-      maxCost: 0.10
-    }
+    },
   });
 
-// Use with minimal input
-const response = await ai.chat.get(messages, {
-  userId: '123',  // Rest is loaded automatically
-  metadata: {
-    priority: 'high',
-    category: 'support'
-  }
-});
+// At call time only userId is required
+const response = await ai.chat.get(
+  { messages: [{ role: 'user', content: 'Hello' }] },
+  { userId: '123', metadata: { feature: 'chat' } }
+);
 ```
 
 ### Lifecycle Hooks
 
-Intercept and modify AI operations at key points:
-
 ```typescript
-const ai = AI.with<AppContext, AppMetadata>()
-  .providers({ openai, anthropic })
-  .create({
-    // ... config
-  })
+const ai = AI.with<AppContext>()
+  .providers({ openai })
+  .create({ /* ... */ })
   .withHooks({
-    beforeModelSelection: async (ctx, metadata) => {
-      // Adjust selection based on user tier
-      if (ctx.user.tier === 'free') {
-        return {
-          ...metadata,
-          weights: { cost: 1.0, speed: 0 }  // Prioritize cost
-        };
+    beforeModelSelection: async (ctx, request, metadata) => {
+      // Adjust weights based on context (return modified metadata)
+      if (ctx.user?.tier === 'free') {
+        return { ...metadata, weights: { cost: 1.0 } };
       }
       return metadata;
     },
 
-    onModelSelected: async (ctx, selected) => {
-      console.log(`Selected: ${selected.model.id}`);
-
-      // Override model for specific users
-      if (ctx.user.betaTester && selected.model.id === 'gpt-4') {
-        return {
-          ...selected,
-          model: ai.models.get('gpt-4-turbo')!
-        };
-      }
+    onModelSelected: async (ctx, request, selected) => {
+      console.log(`Selected: ${selected.model.id} (score: ${selected.score.toFixed(3)})`);
+      // Return a modified selected model to override, or undefined to accept
     },
 
-    beforeRequest: async (ctx, request, selected, estimatedTokens, estimatedCost) => {
-      // Check budget
-      if (estimatedCost > ctx.user.remainingBudget) {
+    beforeRequest: async (ctx, request, selected, estimatedUsage, estimatedCost) => {
+      // Throw to cancel the request
+      if (ctx.user && estimatedCost > ctx.user.budgetRemaining) {
         throw new Error('Insufficient budget');
       }
-
-      // Log request
-      await db.logs.create({
-        userId: ctx.user.id,
-        model: selected.model.id,
-        estimatedTokens,
-        estimatedCost,
-        timestamp: new Date()
-      });
+      console.log(
+        `[${ctx.userId}] ${selected.model.id} — ` +
+        `~${estimatedUsage.text?.input ?? 0} input tokens, ~$${estimatedCost.toFixed(5)}`
+      );
     },
 
     afterRequest: async (ctx, request, response, responseComplete, selected, usage, cost) => {
-      // Track actual usage
-      await db.users.update(ctx.user.id, {
-        tokensUsed: usage.totalTokens,
-        costAccrued: cost,
-        remainingBudget: ctx.user.remainingBudget - cost
-      });
-
-      // Update model metrics
-      await db.modelMetrics.increment(selected.model.id, {
-        requestCount: 1,
-        successCount: 1,
-        totalTokens: usage.totalTokens,
-        totalCost: cost
-      });
+      // Record actual usage
+      if (ctx.user) {
+        ctx.user.budgetRemaining -= cost;
+        ctx.user.totalSpent += cost;
+        await ctx.user.save();
+      }
+      console.log(
+        `[${ctx.userId}] ${usage.text?.input ?? 0} in / ${usage.text?.output ?? 0} out, ` +
+        `cost: $${cost.toFixed(5)}`
+      );
     },
 
-    onError: (type, message, error, ctx) => {
-      logger.error('AI Error', {
-        type,
-        message,
-        error,
-        userId: ctx?.user?.id,
-        stack: error?.stack
-      });
-
-      // Send to monitoring
-      monitoring.captureException(error, {
-        tags: { type, userId: ctx?.user?.id }
-      });
-    }
+    onError: (errorType, message, error, ctx) => {
+      console.error(`[AI ${errorType}] ${message}`, { error, userId: ctx?.userId });
+    },
   });
 ```
 
 ### Model Selection
 
-Fine-tune model selection with weights and constraints:
-
 ```typescript
 // Cost-optimized
-await ai.chat.get(messages, {
-  metadata: {
-    weights: {
-      cost: 0.9,
-      speed: 0.05,
-      accuracy: 0.05
-    }
-  }
-});
+await ai.chat.get(
+  { messages },
+  { metadata: { weights: { cost: 0.9, speed: 0.05, accuracy: 0.05 } } }
+);
 
-// Performance-optimized
-await ai.chat.get(messages, {
-  metadata: {
-    weights: {
-      cost: 0.1,
-      speed: 0.5,
-      accuracy: 0.4
-    },
-    minContextWindow: 128000
+// Quality-optimized with large context
+await ai.chat.get(
+  { messages },
+  {
+    metadata: {
+      weights: { cost: 0.1, speed: 0.4, accuracy: 0.5 },
+      contextWindow: { min: 128000 },
+    }
   }
-});
+);
 
 // Provider-specific
-await ai.chat.get(messages, {
-  metadata: {
-    providers: {
-      allow: ['anthropic'],  // Only use Anthropic models
-      deny: ['replicate']    // Exclude Replicate
-    }
-  }
-});
+await ai.chat.get(
+  { messages },
+  { metadata: { providers: { allow: ['openai'], deny: ['replicate'] } } }
+);
 
-// Budget-constrained
-await ai.chat.get(messages, {
-  metadata: {
-    budget: {
-      maxCostPerRequest: 0.05,
-      maxCostPerMillionTokens: 10.0
-    }
-  }
-});
+// Explicit model override
+await ai.chat.get(
+  { messages },
+  { metadata: { model: 'openai/gpt-4o' } }
+);
 ```
 
-#### Selection Profiles
-
-Use pre-configured profiles:
+### Named Weight Profiles
 
 ```typescript
 const ai = AI.with()
-  .providers({ openai, anthropic })
+  .providers({ openai, openrouter })
   .create({
-    profiles: {
-      costPriority: { cost: 0.9, speed: 0.1 },
-      balanced: { cost: 0.5, speed: 0.3, accuracy: 0.2 },
-      performance: { cost: 0.1, speed: 0.5, accuracy: 0.4 }
-    }
+    weightProfiles: {
+      costPriority:  { cost: 0.9, speed: 0.1 },
+      balanced:      { cost: 0.4, speed: 0.3, accuracy: 0.3 },
+      performance:   { cost: 0.1, speed: 0.4, accuracy: 0.5 },
+    },
   });
 
-// Reference profile in metadata
-await ai.chat.get(messages, {
-  metadata: {
-    weights: config.profiles.costPriority
-  }
-});
+await ai.chat.get(
+  { messages },
+  { metadata: { weightProfile: 'balanced' } }
+);
 ```
 
 ### Model Sources
 
-Enrich model information from external registries:
-
 ```typescript
-import { openRouterSource } from '@aeye/openrouter';
+import { OpenRouterModelSource } from '@aeye/openrouter';
+
+const source = new OpenRouterModelSource({ apiKey: process.env.OPENROUTER_API_KEY });
 
 const ai = AI.with()
-  .providers({ openai, anthropic, openrouter })
+  .providers({ openai, openrouter })
   .create({
-    // Use OpenRouter as a model source to get pricing/capabilities
-    modelSources: [openRouterSource],
-
-    // Or configure it explicitly
-    fetchOpenRouterModels: {
-      enabled: true,
-      apiKey: process.env.OPENROUTER_API_KEY
-    }
+    modelSources: [source],
   });
 
-// Models now have enriched information from OpenRouter
+// Fetch and register all models from sources
 await ai.models.refresh();
-const models = ai.models.list();
 ```
 
-### Custom Providers
-
-You can create custom provider implementations - just implement the Provider interface.
+### Model Overrides
 
-## TypeScript Guide
+```typescript
+const ai = AI.with()
+  .providers({ openai })
+  .create({
+    modelOverrides: [
+      {
+        modelPattern: /gpt-4/,
+        overrides: {
+          pricing: { text: { input: 30, output: 60 } },
+        },
+      },
+    ],
+  });
+```
 
-### Type Safety
+### Custom Providers
 
-The library provides full TypeScript support with generic type inference:
+Extend an existing provider or implement the `Provider<TConfig>` interface from `@aeye/core`:
 
 ```typescript
-// Define your types
-interface MyContext {
-  userId: string;
-  sessionId: string;
-}
-
-interface MyMetadata {
-  priority: 'low' | 'high';
-}
+import { OpenAIProvider, OpenAIConfig } from '@aeye/openai';
+import OpenAI from 'openai';
 
-// Create strongly-typed AI instance
-const ai = AI.with<MyContext, MyMetadata>()
-  .providers({ openai })
-  .create({
-    defaultContext: {
-      sessionId: 'default'  // ✓ Valid
-      // foo: 'bar'         // ✗ TypeScript error
-    }
-  });
+class MyProvider extends OpenAIProvider {
+  readonly name = 'my-provider';
 
-// Type-safe usage
-await ai.chat.get(messages, {
-  userId: '123',           // ✓ Required (not in default)
-  sessionId: 'override',   // ✓ Optional (in default)
-  // invalidField: 'x'     // ✗ TypeScript error
-  metadata: {
-    priority: 'high'       // ✓ Valid enum value
-    // priority: 'medium'  // ✗ TypeScript error
+  protected createClient(config: OpenAIConfig) {
+    return new OpenAI({
+      apiKey: config.apiKey,
+      baseURL: 'https://my-api.example.com/v1',
+    });
   }
-});
+}
 ```
 
 ### Extending AI Instances
 
-Create extended instances for specific use cases:
+Share providers and configuration between multiple AI instances:
 
 ```typescript
-// Base AI instance
 const baseAI = AI.with<BaseContext>()
-  .providers({ openai, anthropic })
-  .create({ /* ... */ });
+  .providers({ openai, openrouter })
+  .create({ /* base config */ });
 
-// Extended for chat feature
-interface ChatContext extends BaseContext {
-  chat: Chat;
-  chatMessage: ChatMessage;
+// Extend with additional context for a specific feature
+interface ChatFeatureContext extends BaseContext {
+  chatId: string;
+  chatHistory: Message[];
 }
 
-const chatAI = baseAI.extend<ChatContext>({
-  defaultContext: {
-    // chat and chatMessage will be provided per-request
-  },
-  modelOverrides: [
-    {
-      modelPattern: /gpt/,
-      overrides: {
-        pricing: { /* custom pricing */ }
-      }
-    }
-  ]
+const chatAI = baseAI.extend<ChatFeatureContext>({
+  defaultContext: { chatHistory: [] },
 });
 
-// Use extended instance
-await chatAI.chat.get(messages, {
-  chat,
-  chatMessage
-});
+const response = await chatAI.chat.get(
+  { messages: [{ role: 'user', content: 'Hello' }] },
+  { chatId: 'chat-123', chatHistory: [] }
+);
 ```
 
 ## Examples
 
-### Complete Application Example
+### Complete Application
 
 ```typescript
-// types.ts
-export interface AppContext {
-  user: User;
-  organization: Organization;
-  db: Database;
-  cache: Redis;
-  requestId: string;
+import { AI } from '@aeye/ai';
+import { OpenAIProvider } from '@aeye/openai';
+import { OpenRouterProvider } from '@aeye/openrouter';
+import z from 'zod';
+
+interface User {
+  id: string;
+  budgetRemaining: number;
+  totalSpent: number;
+  save: () => Promise<void>;
 }
 
-export interface AppMetadata {
-  feature: 'chat' | 'summary' | 'analysis';
-  priority: 'low' | 'normal' | 'high';
-  maxCost: number;
+interface AppContext {
+  userId: string;
+  user?: User;
 }
 
-// ai.ts
-import { AI } from '@aeye/ai';
-import { openai } from '@aeye/openai';
-import { anthropic } from '@aeye/anthropic';
+const openai = new OpenAIProvider({ apiKey: process.env.OPENAI_API_KEY! });
+const openrouter = new OpenRouterProvider({ apiKey: process.env.OPENROUTER_API_KEY! });
 
-export const ai = AI.with<AppContext, AppMetadata>()
-  .providers({ openai, anthropic })
+export const ai = AI.with<AppContext>()
+  .providers({ openai, openrouter })
   .create({
-    defaultContext: {
-      requestId: () => uuid(),
-      cache: redis
-    },
-    providedContext: async (ctx) => {
-      const user = await db.users.findById(ctx.userId);
-      const org = await db.organizations.findById(user.organizationId);
-      return { user, organization: org, db };
-    },
-    defaultMetadata: {
-      priority: 'normal',
-      maxCost: 0.10
-    },
-    profiles: {
-      costPriority: { cost: 0.9, speed: 0.1 },
-      balanced: { cost: 0.5, speed: 0.3, accuracy: 0.2 },
-      performance: { cost: 0.1, speed: 0.5, accuracy: 0.4 }
-    }
-  })
-  .withHooks({
-    beforeRequest: async (ctx, request, selected, estimatedTokens, estimatedCost) => {
-      const cost = estimateCost(tokens, selected.model);
-      if (cost > ctx.user.remainingBudget) {
-        throw new Error('Insufficient budget');
-      }
-    },
-    afterRequest: async (ctx, request, response, responseComplete, selected, usage, cost) => {
-      await trackUsage(ctx.user.id, usage, cost);
+    providedContext: async (ctx) => ({
+      user: await getUser(ctx.userId),
+    }),
+    defaultWeights: { cost: 0.5, speed: 0.3, accuracy: 0.2 },
+    hooks: {
+      beforeRequest: async (ctx, _request, selected, estimatedUsage, estimatedCost) => {
+        if (ctx.user && estimatedCost > ctx.user.budgetRemaining) {
+          throw new Error(
+            `Estimated cost $${estimatedCost.toFixed(4)} exceeds budget ` +
+            `$${ctx.user.budgetRemaining.toFixed(4)}`
+          );
+        }
+      },
+      afterRequest: async (ctx, _request, _response, _complete, _selected, usage, cost) => {
+        if (ctx.user) {
+          ctx.user.budgetRemaining -= cost;
+          ctx.user.totalSpent += cost;
+          await ctx.user.save();
+        }
+      },
+      onError: (errorType, message, error, ctx) => {
+        console.error(`[AI ${errorType}] ${message}`, { userId: ctx?.userId, error });
+      },
     },
-    onError: (type, message, error, ctx) => {
-      logger.error({ type, message, error, userId: ctx?.user?.id });
-    }
   });
 
-// features/chat.ts
-export async function handleChatMessage(
-  userId: string,
-  message: string
-) {
-  const response = await ai.chat.get(
-    [
-      { role: 'system', content: 'You are a helpful assistant.' },
-      { role: 'user', content: message }
-    ],
-    {
-      userId,
-      metadata: {
-        feature: 'chat',
-        priority: 'normal'
-      }
-    }
-  );
-
-  return response.content;
-}
-
-// features/analysis.ts
-export async function analyzeDocument(
-  userId: string,
-  document: string
-) {
-  const response = await ai.chat.get(
-    [
-      { role: 'system', content: 'You are a document analysis expert.' },
-      { role: 'user', content: `Analyze this document:\n\n${document}` }
-    ],
-    {
-      userId,
-      metadata: {
-        feature: 'analysis',
-        priority: 'high',
-        required: ['chat'],
-        weights: { accuracy: 0.7, cost: 0.3 }
-      }
-    }
-  );
-
-  return response.content;
-}
-```
-
-### Prompt Engineering with Context
-
-```typescript
-import { ai } from './ai';
-
-const summarizer = ai.prompt({
-  name: 'summarizer',
-  description: 'Summarize documents',
-
-  input: async (params: { document: string }, ctx) => {
-    // Access context in prompt construction
-    const userPrefs = await ctx.db.getUserPreferences(ctx.user.id);
-
-    return [{
-      role: 'system',
-      content: `Summarize documents in ${userPrefs.language}.`
-    }, {
-      role: 'user',
-      content: `Summarize:\n\n${params.document}`
-    }];
+// Define a tool
+const webSearch = ai.tool({
+  name: 'webSearch',
+  description: 'Search the web for recent information',
+  schema: z.object({ query: z.string() }),
+  call: async ({ query }) => {
+    // Integrate with a search API
+    return { results: [`Result for: ${query}`] };
   },
-
-  config: {
-    maxTokens: 500,
-    temperature: 0.3
-  }
 });
 
-// Use prompt
-const result = await summarizer.execute(
-  { document: longText },
-  { userId: '123' }
-);
-```
-
-### Multi-Step Agent
-
-```typescript
-const researchAgent = ai.agent({
+// Define a research prompt
+const researcher = ai.prompt({
   name: 'researcher',
-  description: 'Research topics using multiple AI calls',
-
-  call: async (input: { topic: string }, refs, ctx) => {
-    // Step 1: Generate research questions
-    const questions = await ai.chat.get([{
-      role: 'user',
-      content: `Generate 3 research questions about: ${input.topic}`
-    }], ctx);
-
-    // Step 2: Answer each question
-    const answers = [];
-    for (const question of parseQuestions(questions.content)) {
-      const answer = await ai.chat.get([{
-        role: 'user',
-        content: question
-      }], ctx);
-      answers.push({ question, answer: answer.content });
-    }
+  description: 'Researches a topic and provides a structured summary',
+  content: `You are a research assistant. Research the following topic and provide a clear summary.
 
-    // Step 3: Synthesize final report
-    const report = await ai.chat.get([{
-      role: 'user',
-      content: `Create a research report from these Q&As:\n${JSON.stringify(answers, null, 2)}`
-    }], ctx);
-
-    return report.content;
-  }
+Topic: {{topic}}`,
+  input: (input: { topic: string }) => ({ topic: input.topic }),
+  tools: [webSearch],
+  schema: z.object({
+    summary: z.string(),
+    keyFindings: z.array(z.string()),
+    sources: z.array(z.string()),
+  }),
 });
 
-const report = await researchAgent.execute(
-  { topic: 'Quantum Computing' },
-  { userId: '123' }
-);
+// Use the prompt
+async function researchTopic(userId: string, topic: string) {
+  const result = await researcher.get('result', { topic }, { userId });
+  return result;
+}
+
+const findings = await researchTopic('user123', 'TypeScript 5.0 features');
+console.log(findings?.summary);
+console.log(findings?.keyFindings);
 ```
 
 ## License
 
-GPL-3.0
+GPL-3.0 © [ClickerMonkey](https://github.com/ClickerMonkey)
 
----
+## Links
 
-For more information, visit:
-- GitHub: https://github.com/yourusername/aeye
-- Documentation: https://aeye.dev
-- Discord: https://discord.gg/aeye
+- [Root README](../../README.md)
+- [@aeye/core README](../core/README.md)
+- [GitHub Repository](https://github.com/ClickerMonkey/aeye)
+- [Issue Tracker](https://github.com/ClickerMonkey/aeye/issues)