@aeye/core 0.3.7 → 0.3.9

package/README.md

@@ -19,6 +19,8 @@ Core primitives for building AI agents, tools, and prompts with TypeScript. Prov
 npm install @aeye/core zod handlebars
 ```
 
+> **Note:** `@aeye/core` defines the primitives — you need an executor/streamer to run prompts. These are provided by `@aeye/ai` via `ai.buildCoreContext()`, or you can supply your own `execute` / `stream` functions.
+
 ## Core Concepts
 
 ### Components
@@ -46,29 +48,29 @@ const summarizer = new Prompt({
   name: 'summarize',
   description: 'Summarizes text concisely',
   content: 'Summarize the following text:\n\n{{text}}',
-  
-  // Transform input
+
+  // Transform raw input into template variables
   input: (input: { text: string }) => ({ text: input.text }),
-  
-  // Define output schema
+
+  // Define output schema (structured JSON)
   schema: z.object({
     summary: z.string().describe('A concise summary'),
-    keyPoints: z.array(z.string()).describe('Main points')
-  })
+    keyPoints: z.array(z.string()).describe('Main points'),
+  }),
 });
 
-// Execute with a context that has an executor
+// Execute — ctx must provide execute or stream (from @aeye/ai or custom)
 const result = await summarizer.get(
   'result',
   { text: 'Long article text...' },
   {
-    execute: yourAIExecutor, // Executor function from a provider
-    messages: []
+    execute: yourAIExecutor,  // (request, ctx, metadata?, signal?) => Promise<Response>
+    messages: [],
   }
 );
 
-console.log(result.summary);
-console.log(result.keyPoints);
+console.log(result?.summary);
+console.log(result?.keyPoints);
 ```
 
 ### Creating Tools
@@ -77,69 +79,73 @@ console.log(result.keyPoints);
 import { Tool } from '@aeye/core';
 import z from 'zod';
 
-const weatherTool = new Tool({
+const getWeather = new Tool({
   name: 'getWeather',
   description: 'Get current weather for a location',
-  instructions: 'Use this tool to get weather data',
-  
+  instructions: 'Use this tool to get weather data for {{location}}.',
+
   schema: z.object({
     location: z.string().describe('City name or coordinates'),
-    units: z.enum(['celsius', 'fahrenheit']).default('celsius')
+    units: z.enum(['celsius', 'fahrenheit']).default('celsius'),
   }),
-  
-  call: async (input, refs, ctx) => {
+
+  call: async (input, _refs, _ctx) => {
     const response = await fetch(
-      `https://api.weather.com/v1/${input.location}`
+      `https://api.weather.com/v1/${encodeURIComponent(input.location)}`
     );
     const data = await response.json();
-    
     return {
       temperature: data.temp,
       condition: data.condition,
-      humidity: data.humidity
+      humidity: data.humidity,
     };
-  }
+  },
 });
 ```
 
 ### Prompts with Tools
 
 ```typescript
+import { Prompt } from '@aeye/core';
+import z from 'zod';
+
 const travelAdvisor = new Prompt({
   name: 'travelAdvisor',
   description: 'Provides travel advice based on weather',
   content: `You are a travel advisor. Help plan a trip to {{destination}}.
-  
-Use the weather tool to check current conditions, then provide:
+
+Use the getWeather tool to check current conditions, then provide:
 - What to pack
-- Activities to do
+- Recommended activities
 - Best times to visit`,
-  
-  input: (input: { destination: string }) => ({ 
-    destination: input.destination 
+
+  input: (input: { destination: string }) => ({
+    destination: input.destination,
   }),
-  
-  tools: [weatherTool],
-  
+
+  tools: [getWeather],
+
   schema: z.object({
     recommendations: z.array(z.string()),
     packingList: z.array(z.string()),
-    weatherNotes: z.string()
-  })
+    weatherNotes: z.string(),
+  }),
 });
 
-// The AI will automatically call weatherTool if needed
+// The AI will automatically call getWeather if needed
 const advice = await travelAdvisor.get(
   'result',
   { destination: 'Paris' },
   { execute: yourAIExecutor, messages: [] }
 );
+
+console.log(advice?.recommendations);
 ```
 
 ### Streaming Responses
 
 ```typescript
-// Stream content only
+// Stream text content only
 for await (const chunk of summarizer.get(
   'streamContent',
   { text: 'Long text...' },
@@ -155,11 +161,13 @@ for await (const event of summarizer.get(
   { stream: yourAIStreamer, messages: [] }
 )) {
   if (event.type === 'textPartial') {
-    console.log('Text:', event.content);
+    process.stdout.write(event.content);
   } else if (event.type === 'toolStart') {
     console.log('Tool started:', event.tool.name);
   } else if (event.type === 'toolOutput') {
     console.log('Tool result:', event.result);
+  } else if (event.type === 'complete') {
+    console.log('Final output:', event.output);
   }
 }
 ```
@@ -168,40 +176,39 @@ for await (const event of summarizer.get(
 
 ```typescript
 import { Agent } from '@aeye/core';
+import z from 'zod';
 
+// Assume searchTool, summarizePrompt, and analyzePrompt are defined elsewhere
 const researchAgent = new Agent({
   name: 'researcher',
-  description: 'Conducts research on topics',
-  
-  refs: [searchTool, summarizeTool, analyzeTool],
-  
-  call: async (input: { topic: string }, [search, summarize, analyze], ctx) => {
+  description: 'Conducts research on a topic',
+
+  refs: [searchTool, summarizePrompt, analyzePrompt] as const,
+
+  call: async (
+    input: { topic: string },
+    [search, summarize, analyze],
+    ctx
+  ) => {
     // Step 1: Search for information
-    const searchResults = await search.run(
-      { query: input.topic, limit: 5 },
-      ctx
-    );
-    
-    // Step 2: Summarize findings
-    const summaries = [];
-    for (const result of searchResults) {
-      const summary = await summarize.get(
-        'result',
-        { text: result.content },
-        ctx
-      );
-      summaries.push(summary);
+    const searchResults = await search.run({ query: input.topic, limit: 5 }, ctx);
+
+    // Step 2: Summarize each result
+    const summaries: string[] = [];
+    for (const result of searchResults.items) {
+      const summary = await summarize.get('result', { text: result.content }, ctx);
+      summaries.push(summary?.summary ?? '');
     }
-    
-    // Step 3: Analyze and synthesize
+
+    // Step 3: Synthesize into a final analysis
     const analysis = await analyze.get(
       'result',
       { topic: input.topic, sources: summaries },
       ctx
     );
-    
+
     return analysis;
-  }
+  },
 });
 
 const research = await researchAgent.run(
@@ -212,15 +219,15 @@ const research = await researchAgent.run(
 
 ## Prompt Modes
 
-The `get` method supports different execution modes:
+The `get(mode, input?, ctx?)` method supports different execution modes:
 
 | Mode | Description | Returns |
 |------|-------------|---------|
-| `'result'` | Get final structured output | `TOutput` |
-| `'tools'` | Get tool call results | `PromptToolOutput[]` |
-| `'stream'` | Stream all events | `AsyncGenerator<PromptEvent>` |
-| `'streamTools'` | Stream tool outputs | `AsyncGenerator<PromptToolOutput>` |
-| `'streamContent'` | Stream text content only | `AsyncGenerator<string>` |
+| `'result'` | Await the final structured output | `Promise<TOutput \| undefined>` |
+| `'tools'` | Await all tool call results | `Promise<PromptToolOutput[] \| undefined>` |
+| `'stream'` | Stream all events | `AsyncGenerator<PromptEvent<TOutput, TTools>, TOutput \| undefined>` |
+| `'streamTools'` | Stream tool output events | `AsyncGenerator<PromptToolOutput<TTools>, TOutput \| undefined>` |
+| `'streamContent'` | Stream text content only | `AsyncGenerator<string, TOutput \| undefined>` |
 
 ```typescript
 // Get structured result
@@ -231,95 +238,106 @@ const tools = await prompt.get('tools', input, ctx);
 
 // Stream everything
 for await (const event of prompt.get('stream', input, ctx)) {
-  // Handle different event types
+  // event.type is one of: 'request', 'textPartial', 'text', 'toolStart',
+  //   'toolOutput', 'toolError', 'message', 'complete', 'usage', ...
+}
+
+// Stream text only
+for await (const text of prompt.get('streamContent', input, ctx)) {
+  process.stdout.write(text);
 }
 ```
 
 ## Tool Execution Modes
 
-Control how tools are executed:
+Control how tools are executed by the prompt:
 
 ```typescript
 const prompt = new Prompt({
   name: 'multi-tool',
   description: 'Uses multiple tools',
-  content: 'Analyze the data',
+  content: 'Analyze this data using the available tools.',
   tools: [tool1, tool2, tool3],
-  
-  // Tool execution mode
-  toolExecution: 'parallel', // 'sequential' | 'parallel' | 'immediate'
-  
-  // Retry configuration
-  toolRetries: 2,         // Retry failed tools
-  toolIterations: 3,      // Max iterations for tool calls
-  toolsMax: 5,           // Max total tool calls
+
+  // 'sequential' | 'parallel' | 'immediate' (default: 'immediate')
+  toolExecution: 'parallel',
+
+  // Number of times to retry a failed tool call (default: 2)
+  toolRetries: 2,
+  // Max tool-calling iterations per request (default: 3)
+  toolIterations: 3,
+  // Max total successful tool calls before stopping (no strict limit by default)
+  toolsMax: 5,
 });
 ```
 
-- **`sequential`** - Wait for each tool to finish before continuing
-- **`parallel`** - Start all tools at once, wait for all to complete
-- **`immediate`** - Start tools immediately as they're available
+- **`sequential`** - Wait for each tool to complete before starting the next
+- **`parallel`** - Start all pending tools at once and wait for all to complete
+- **`immediate`** - Start each tool as soon as its call is received (default)
 
 ## Advanced Features
 
 ### Context-Aware Tools
 
+Tool schemas and applicability can depend on the current context:
+
 ```typescript
+interface MyContext {
+  userRole: 'admin' | 'viewer';
+  isAuthenticated: boolean;
+}
+
 const contextTool = new Tool({
-  name: 'contextAware',
-  description: 'A context-aware tool',
-  instructions: 'Use this tool...',
-  
-  // Schema can depend on context
-  schema: (ctx) => {
+  name: 'manageData',
+  description: 'Manage data records',
+  instructions: 'Use this tool to read or write data.',
+
+  // Schema varies based on the caller's role
+  schema: (ctx: Context<MyContext, {}>) => {
     if (ctx.userRole === 'admin') {
-      return z.object({
-        action: z.enum(['read', 'write', 'delete'])
-      });
+      return z.object({ action: z.enum(['read', 'write', 'delete']) });
     }
-    return z.object({
-      action: z.enum(['read'])
-    });
+    return z.object({ action: z.enum(['read']) });
   },
-  
-  // Check if tool is applicable
-  applicable: (ctx) => {
-    return ctx.isAuthenticated === true;
+
+  // Tool is only available to authenticated users
+  applicable: (ctx: Context<MyContext, {}>) => ctx.isAuthenticated,
+
+  call: async (input, _refs, ctx) => {
+    return { action: input.action, executedBy: ctx.userRole };
   },
-  
-  call: async (input, refs, ctx) => {
-    // Implementation with context access
-  }
 });
 ```
 
 ### Custom Validation
 
+Add business-logic validation beyond Zod schema checks:
+
 ```typescript
-const validatedTool = new Tool({
+const placeOrder = new Tool({
   name: 'placeOrder',
-  description: 'Place an order',
-  
+  description: 'Place a product order',
+
   schema: z.object({
     itemId: z.string(),
-    quantity: z.number().min(1)
+    quantity: z.number().int().min(1),
   }),
-  
-  // Additional validation beyond schema
+
+  // Runs after schema parsing succeeds; throw to trigger re-prompting
   validate: async (input, ctx) => {
     const inventory = await checkInventory(input.itemId);
     if (inventory < input.quantity) {
-      throw new Error(`Only ${inventory} items available`);
+      throw new Error(`Only ${inventory} units of ${input.itemId} are available.`);
     }
   },
-  
-  call: async (input, refs, ctx) => {
-    // Place order
-  }
+
+  call: async (input, _refs, _ctx) => {
+    return { orderId: crypto.randomUUID(), ...input };
+  },
 });
 ```
 
-### Event Tracking
+### Event Tracking with `withEvents`
 
 ```typescript
 import { withEvents } from '@aeye/core';
@@ -327,164 +345,291 @@ import { withEvents } from '@aeye/core';
 const runner = withEvents({
   onStatus: (instance) => {
     console.log(`${instance.component.name}: ${instance.status}`);
-    if (instance.status === 'completed') {
-      const duration = instance.completed - instance.started;
-      console.log(`Took ${duration}ms`);
+    if (instance.status === 'completed' && instance.completed && instance.running) {
+      console.log(`  Took ${instance.completed - instance.running}ms`);
     }
   },
-  
-  onPromptEvent: (instance, event) => {
+
+  onPromptEvent: (_instance, event) => {
     if (event.type === 'usage') {
       console.log('Tokens used:', event.usage);
     }
-  }
+  },
 });
 
 const result = await prompt.get(
   'result',
   { text: 'Hello' },
-  {
-    execute: yourAIExecutor,
-    messages: [],
-    runner
-  }
+  { execute: yourAIExecutor, messages: [], runner }
 );
 ```
 
 ### Token Management
 
-Automatic conversation trimming when token limits are reached:
+The prompt automatically trims old messages when the context window is full:
 
 ```typescript
-const context = {
-  execute: yourAIExecutor,
-  messages: conversationHistory,
-  
-  // Token configuration
-  defaultCompletionTokens: 2048,
-  
-  // Custom token estimation
-  estimateTokens: (message) => {
-    return message.content.length / 4; // Rough estimate
-  }
-};
+const result = await prompt.get(
+  'result',
+  { text: 'Query' },
+  {
+    execute: yourAIExecutor,
+    messages: conversationHistory,  // Will be trimmed if needed
 
-// Prompt will automatically trim messages if needed
-const result = await prompt.get('result', { text: 'Query' }, context);
+    // Reserve this many tokens for the model's response
+    maxOutputTokens: 2048,
+
+    // Custom per-message token estimator
+    estimateUsage: (message) => ({
+      text: { input: Math.ceil((message.content as string).length / 4) }
+    }),
+  }
+);
 ```
 
 ### Dynamic Reconfiguration
 
+Use `reconfig` to adapt the prompt based on runtime statistics:
+
 ```typescript
 const adaptivePrompt = new Prompt({
   name: 'adaptive',
-  description: 'Adapts based on execution stats',
+  description: 'Adapts based on runtime stats',
   content: 'Solve: {{problem}}',
   schema: z.object({ solution: z.string() }),
-  
-  // Adjust configuration during execution
-  reconfig: (stats, ctx) => {
-    // If tools are failing, change strategy
+
+  reconfig: (stats, _ctx) => {
+    // If many tool errors occurred, switch to one-at-a-time mode
     if (stats.toolCallErrors > 3) {
-      return {
-        config: { toolsOneAtATime: true },
-        maxIterations: 2
-      };
+      return { config: { toolsOneAtATime: true } };
     }
     return {};
-  }
+  },
+});
+```
+
+## Model Capabilities
+
+@aeye uses a capability system for automatic model selection. Models advertise their capabilities and the library selects the best match for each request:
+
+| Capability | Description |
+|------------|-------------|
+| `chat` | Basic text completion |
+| `streaming` | Real-time response streaming |
+| `image` | Image generation |
+| `vision` | Image understanding |
+| `audio` | Text-to-speech |
+| `hearing` | Speech-to-text |
+| `embedding` | Text embeddings |
+| `tools` | Function/tool calling |
+| `json` | JSON output mode |
+| `structured` | Structured outputs with schemas |
+| `toolsStrict` | Strict-mode tool input schemas (auto-derived; see [Strict Mode](#strict-mode)) |
+| `reasoning` | Extended chain-of-thought reasoning |
+| `zdr` | Zero data retention |
+
+## Strict Mode
+
+Each LLM provider that supports strict mode does so with its own JSON Schema dialect. `@aeye/core` reconciles them under a single `FormatDescriptor` so a Zod schema authored once works against any of them.
+
+### `strict` on Tool / Prompt
+
+`Tool.strict` and `Prompt.strict` are `boolean | number`:
+
+| Value | Meaning |
+|---|---|
+| `true` | **Require** strict. `@aeye/ai` filters selection down to models that declare strict support; the request fails if none qualify. |
+| `false` | **Force** lenient. Standard JSON Schema; no `strict: true` on the wire. |
+| `number > 0` (default `1`) | **Prefer** strict, accept fallback. Higher numbers win when there are more strict-requesting items than the chosen model's per-request budget allows. |
+| omitted | Treated as `1`. |
+
+```typescript
+new Tool({ name: 'must',     /* default 1 */                schema: z.object({...}) }); // best-effort
+new Tool({ name: 'critical', strict: true,                  schema: z.object({...}) }); // hard require
+new Tool({ name: 'meh',      strict: false,                 schema: z.object({...}) }); // never strict
+new Tool({ name: 'top',      strict: 100,                   schema: z.object({...}) }); // high priority
+```
+
+Default `1` keeps "it just works" against unannotated models — strict where the chosen model supports it, lenient elsewhere. Set `true` only when strict is non-negotiable.
+
+### Native format descriptors
+
+Seven descriptors ship out of the box:
+
+| Descriptor | Family / Strict | Notes |
+|---|---|---|
+| `OPENAI_STRICT` | openai / strict | Records → array-of-pairs, tuples → numeric-key objects, `optional → T \| null`, closed objects, restricted format whitelist. |
+| `ANTHROPIC_STRICT` | anthropic / strict | Closed objects, no recursion, no length / numeric range constraints, per-request slot budgets (20 strict tools / 24 optional params / 16 union types). |
+| `GOOGLE_STRICT` | google / strict | `prefixItems`, `$ref: '#'` recursion, `propertyOrdering` emitted, restricted format whitelist. |
+| `LENIENT` | lenient / non-strict | No rewrites, all features pass through. Default for unannotated models. |
+| `OPENAI_NON_STRICT`, `ANTHROPIC_NON_STRICT`, `GOOGLE_NON_STRICT` | family / non-strict | Aliased to `LENIENT` but tagged with the family for diagnostics. |
+
+```typescript
+import { OPENAI_STRICT, ANTHROPIC_STRICT, getDescriptor, toJSONSchema } from '@aeye/core';
+
+const schema = z.object({
+  name: z.string(),
+  tags: z.record(z.string(), z.string()),
 });
+
+// Same Zod, different wire shapes:
+toJSONSchema(schema, OPENAI_STRICT);                    // tags → array of {key, value}
+toJSONSchema(schema, ANTHROPIC_STRICT);                 // tags → array of {key, value} (open records unsupported)
+toJSONSchema(schema, getDescriptor('google', true));    // tags → standard additionalProperties
+
+// Backward-compat overloads still work:
+toJSONSchema(schema, true);   // === OPENAI_STRICT
+toJSONSchema(schema, false);  // === LENIENT
+```
+
+### Registering a custom descriptor
+
+You can ship your own descriptor for a provider or dialect that isn't supported natively. Define it as a `FormatDescriptor` value and register it with `registerDescriptor(descriptor)`:
+
+```typescript
+import { registerDescriptor, type FormatDescriptor, OPENAI_STRICT } from '@aeye/core';
+
+const MY_PROVIDER_STRICT: FormatDescriptor = {
+  ...OPENAI_STRICT,                   // start from a known good baseline
+  id: 'my-provider-strict',
+  family: 'openai',                   // or 'anthropic' | 'google' | 'lenient'
+  // Override only the fields that differ from the baseline:
+  recordEncoding: 'open-record',      // your provider supports additionalProperties: <schema>
+  tupleEncoding: 'prefix-items',
+  supportsRecursion: true,
+};
+
+registerDescriptor(MY_PROVIDER_STRICT);
 ```
 
+Once registered:
+
+- Provider code can pass the descriptor to `toJSONSchema(schema, MY_PROVIDER_STRICT)` and `strictify(schema, MY_PROVIDER_STRICT)`.
+- The Prompt's validation roundtrip (which looks up descriptors by id from the request) will resolve `'my-provider-strict'` correctly.
+- A custom `Provider` implementation can return this descriptor from its `getStrictFormat`-equivalent helper.
+
+The descriptor's full field list is exported as the `FormatDescriptor` interface — every flag is documented inline. Common adjustments:
+
+| Field | Controls |
+|---|---|
+| `objectAllFieldsRequired` | Whether every property must appear in `required[]`. |
+| `objectClosedByDefault` | Whether every object emits `additionalProperties: false`. |
+| `recordEncoding` | `'array-of-pairs'` vs `'open-record'`. |
+| `tupleEncoding` | `'object-numeric-keys'` vs `'prefix-items'` vs `'items-union'`. |
+| `allowAllOf` / `allowAnyOf` / `allowOneOf` | JSON-Schema combinator support. |
+| `supportedStringFormats` | `'all'` or a `Set<string>` whitelist (`'date-time'`, `'email'`, etc.). |
+| `optionalAsNullable` | Whether `optional` fields are emitted as `T \| null` (OpenAI strict) vs omitted from `required[]`. |
+| `supportsRecursion` | Whether `$ref` self-reference works under this dialect. |
+| `maxStrictTools` / `maxStrictOptionalParams` / `maxStrictUnionTypes` | Per-request budget caps; `undefined` means no documented limit. |
+
+You don't need to set every field — spread an existing descriptor and override deltas. Tested via `analyzeSchema` + the schema test suite; see the strict-mode guide in `@aeye/docs` for end-to-end examples.
+
 ## API Reference
 
 ### Prompt
 
 ```typescript
-class Prompt<TContext, TMetadata, TName, TInput, TOutput, TTools>
+class Prompt<TContext, TMetadata, TName extends string, TInput extends object, TOutput extends object | string, TTools extends Tuple<ToolCompatible<TContext, TMetadata>>, TDecoded extends unknown = TOutput>
 ```
 
-**Constructor Options:**
+`TDecoded` is the type a custom `parse` produces from the model's structured output (e.g. a built AST/class instance); it types `validate` and the decoded output. It defaults to `TOutput` (the wire type) when no custom `parse` is supplied — `schema` always stays the wire type.
+
+**Constructor Options (`PromptInput`):**
 - `name: string` - Unique identifier
 - `description: string` - Purpose description
-- `content: string` - Handlebars template
-- `input?: Function` - Transform input for template
-- `schema?: ZodType | Function` - Output schema
-- `config?: Partial<Request> | Function` - AI request config
-- `tools?: Tool[]` - Available tools
-- `toolExecution?: 'sequential' | 'parallel' | 'immediate'`
-- `toolRetries?: number` - Retry failed tools
-- `toolIterations?: number` - Max tool call iterations
-- `outputRetries?: number` - Retry invalid outputs
-- `metadata?: TMetadata` - Execution metadata
-- `validate?: Function` - Post-validation hook
-- `applicable?: Function` - Applicability check
+- `content: string` - Handlebars template for the system/user message
+- `input?: (input: TInput, ctx: Context<TContext, TMetadata>) => Record<string, any>` - Maps raw input to template variables
+- `schema?: ZodType<TOutput> | ((input: TInput | undefined, ctx: Context<TContext, TMetadata>) => ZodType<TOutput> | false)` - Output schema; `false` disables structured output
+- `strict?: boolean` - Enforce strict Zod schema (default: `true`)
+- `config?: Partial<Request> | ((input: TInput | undefined, ctx: Context<TContext, TMetadata>) => Partial<Request> | false)` - AI request overrides
+- `tools?: TTools` - Tools the prompt may call
+- `toolExecution?: 'sequential' | 'parallel' | 'immediate'` - Tool execution mode
+- `toolRetries?: number` - Retry count for failed tools (default: 2)
+- `toolIterations?: number` - Max tool-calling iterations (default: 3)
+- `toolsMax?: number` - Max successful tool calls
+- `outputRetries?: number` - Retry count for invalid structured outputs
+- `metadata?: TMetadata` - Static metadata for this prompt
+- `validate?: (output: TOutput, ctx: Context<TContext, TMetadata>) => void | Promise<void>` - Post-parse validation
+- `applicable?: (ctx: Context<TContext, TMetadata>) => boolean | Promise<boolean>` - Availability check
 
 **Methods:**
-- `get(input, mode, ctx)` - Execute and retrieve output
-- `run(input, ctx)` - Execute with full streaming
-- `applicable(ctx)` - Check if prompt can run
+- `get(mode: PromptGetType, input?: TInput, ctx?: Context<TContext, TMetadata>): PromptGet<...>` - Execute and return output in the specified mode
+- `run(input?: TInput, ctx?: Context<TContext, TMetadata>): AsyncGenerator<PromptEvent<TOutput, TTools>, TOutput | undefined>` - Full streaming generator
+- `applicable(ctx?: Context<TContext, TMetadata>): Promise<boolean>` - Check if prompt is usable
 
 ### Tool
 
 ```typescript
-class Tool<TContext, TMetadata, TName, TParams, TOutput, TRefs>
+class Tool<TContext, TMetadata, TName extends string, TParams extends object, TOutput, TRefs extends Tuple<ComponentCompatible<TContext, TMetadata>>, TDecoded extends unknown = TParams>
 ```
 
-**Constructor Options:**
-- `name: string` - Unique identifier
-- `description: string` - Purpose description  
-- `instructions?: string` - Handlebars usage instructions
-- `schema: ZodType | Function` - Input schema
-- `refs?: Component[]` - Referenced components
-- `call: Function` - Implementation
-- `validate?: Function` - Post-validation hook
-- `applicable?: Function` - Applicability check
+`TDecoded` is the type a custom `parse` produces from the raw wire args (e.g. a built class instance); it types `call`, `validate`, and `metadataFn`. It defaults to `TParams` (the wire type) when no custom `parse` is supplied — `schema` always stays the wire type.
+
+**Constructor Options (`ToolInput`):**
+- `name: string` - Unique identifier (shown to the AI model)
+- `description: string` - What the tool does (shown to the AI model)
+- `instructions?: string` - Handlebars template for usage instructions
+- `schema: ZodType<TParams> | ((ctx: Context<TContext, TMetadata>) => ZodType<TParams> | undefined)` - Input parameter schema
+- `strict?: boolean` - Enforce strict Zod schema (default: `true`)
+- `refs?: TRefs` - Referenced components
+- `call: (input: TParams, refs: TRefs, ctx: Context<TContext, TMetadata>) => TOutput` - Implementation
+- `validate?: (input: TParams, ctx: Context<TContext, TMetadata>) => void | Promise<void>` - Post-parse validation
+- `applicable?: (ctx: Context<TContext, TMetadata>) => boolean | Promise<boolean>` - Availability check
 
 **Methods:**
-- `run(input, ctx)` - Execute the tool
-- `compile(ctx)` - Generate tool definition for AI
-- `parse(ctx, args)` - Parse and validate arguments
-- `applicable(ctx)` - Check if tool can run
+- `run(input?: TParams, ctx?: Context<TContext, TMetadata>): TOutput` - Execute the tool directly
+- `compile(ctx: Context<TContext, TMetadata>): Promise<readonly [string, ToolDefinition] | undefined>` - Generate AI tool definition
+- `applicable(ctx?: Context<TContext, TMetadata>): Promise<boolean>` - Check if tool is usable
 
 ### Agent
 
 ```typescript
-class Agent<TContext, TMetadata, TName, TInput, TOutput, TRefs>
+class Agent<TContext, TMetadata, TName extends string, TInput extends object, TOutput, TRefs extends Tuple<ComponentCompatible<TContext, TMetadata>>>
 ```
 
-**Constructor Options:**
+**Constructor Options (`AgentInput`):**
 - `name: string` - Unique identifier
 - `description: string` - Purpose description
-- `refs?: Component[]` - Referenced components
-- `call: Function` - Implementation with refs
-- `applicable?: Function` - Applicability check
+- `refs: TRefs` - Components this agent uses
+- `call: (input: TInput, refs: TRefs, ctx: Context<TContext, TMetadata>) => TOutput` - Implementation
+- `applicable?: (ctx: Context<TContext, TMetadata>) => boolean | Promise<boolean>` - Availability check
 
 **Methods:**
-- `run(input, ctx)` - Execute the agent
-- `applicable(ctx)` - Check if agent can run
+- `run(input?: TInput, ctx?: Context<TContext, TMetadata>): TOutput` - Execute the agent
+- `applicable(ctx?: Context<TContext, TMetadata>): Promise<boolean>` - Check if agent is usable
 
 ## Context Structure
 
+The `Context<TContext, TMetadata>` type combines your custom context with the core execution context:
+
 ```typescript
-interface Context<TContext, TMetadata> {
-  // Required: AI execution
-  execute?: Executor<TContext, TMetadata>;
-  stream?: Streamer<TContext, TMetadata>;
-  
-  // Messages
-  messages: Message[];
-  
-  // Token management
-  defaultCompletionTokens?: number;
-  estimateTokens?: (message: Message) => number;
-  
-  // Execution control
+// Core fields available in every context
+interface CoreContextFields {
+  // AI executor for non-streaming requests
+  execute?: (request: Request, ctx: TContext, metadata?: TMetadata, signal?: AbortSignal) => Promise<Response>;
+  // AI streamer for streaming requests
+  stream?: (request: Request, ctx: TContext, metadata?: TMetadata, signal?: AbortSignal) => AsyncGenerator<Chunk, Response>;
+
+  // Conversation history passed to the model
+  messages?: Message[];
+
+  // Reserve N tokens for the model's output (used for context trimming)
+  maxOutputTokens?: number;
+  // Override context window size (used for context trimming)
+  contextWindow?: number;
+
+  // Custom per-message usage estimator
+  estimateUsage?: (message: Message) => Usage | undefined;
+
+  // Number of output-format retries (default: 2)
+  outputRetries?: number;
+  // Number of context-trimming retries (default: 1)
+  forgetRetries?: number;
+
+  // Abort signal for cancellation
   signal?: AbortSignal;
+  // Event runner for tracking component lifecycle
   runner?: Events;
-  
-  // User context (TContext) spreads here
-  [key: string]: any;
 }
 ```
 
@@ -493,13 +638,17 @@ interface Context<TContext, TMetadata> {
 ```typescript
 interface Request {
   messages: Message[];
-  temperature?: number;      // 0-2
-  topP?: number;            // 0-1
+  temperature?: number;       // 0.0–2.0
+  topP?: number;              // 0.0–1.0
   maxTokens?: number;
   stop?: string | string[];
   tools?: ToolDefinition[];
-  toolChoice?: 'auto' | 'required' | 'none' | { tool: string };
-  responseFormat?: 'text' | 'json' | ResponseFormat;
+  toolChoice?: 'auto' | 'required' | 'none' | { type: 'tool'; name: string };
+  responseFormat?: 'text' | 'json' | { type: 'json_schema'; schema: object; name: string; strict?: boolean };
+  reason?: { effort?: 'low' | 'medium' | 'high'; maxTokens?: number };
+  frequencyPenalty?: number;
+  presencePenalty?: number;
+  seed?: number;
   // ... more options
 }
 ```
@@ -507,15 +656,13 @@ interface Request {
 ## Best Practices
 
 1. **Type Safety** - Use TypeScript generics for context and metadata
-2. **Schema Validation** - Use Zod for robust input/output validation  
-3. **Error Handling** - Wrap component execution in try-catch blocks
-4. **Token Management** - Provide `estimateTokens` for accurate trimming
-5. **Tool Organization** - Group related tools in agents
-6. **Testing** - Unit test tools and prompts independently
-7. **Documentation** - Document template variables and schemas
-8. **Context Minimization** - Pass only necessary data in context
-9. **Streaming** - Use streaming for better UX with long responses
-10. **Validation** - Use `validate` hooks for business logic validation
+2. **Schema Validation** - Use Zod for robust input/output validation
+3. **Token Management** - Supply `estimateUsage` for accurate context trimming
+4. **Tool Organization** - Group related tools and use agents to orchestrate them
+5. **Testing** - Unit test tools and prompts independently
+6. **Context Minimization** - Pass only necessary data in context
+7. **Streaming** - Use streaming for better UX with long responses
+8. **Validation** - Use `validate` hooks for business-logic checks after schema parsing
 
 ## Examples
 
@@ -532,24 +679,31 @@ See the `src/__tests__` directory for comprehensive examples:
 Full type inference across component hierarchies:
 
 ```typescript
-// Types are automatically inferred
+import { Prompt, Tool } from '@aeye/core';
+import z from 'zod';
+
+// Output type is inferred from the schema
 const prompt = new Prompt({
   name: 'example',
-  schema: z.object({ result: z.string() })
-  // ...
+  description: 'Example prompt',
+  content: 'Say hello to {{name}}.',
+  input: (input: { name: string }) => ({ name: input.name }),
+  schema: z.object({ greeting: z.string() }),
 });
 
-// TypeScript knows the output type
-const output = await prompt.get({}); // { result: string }
+// result is typed as { greeting: string } | undefined
+const result = await prompt.get('result', { name: 'World' }, ctx);
+console.log(result?.greeting);
 
-// Tool parameters are type-safe
-const tool = new Tool({
-  name: 'math',
+// Tool call parameters are type-safe
+const mathTool = new Tool({
+  name: 'add',
+  description: 'Adds two numbers',
   schema: z.object({ a: z.number(), b: z.number() }),
-  call: (input, refs, ctx) => {
-    // input is typed as { a: number, b: number }
+  call: (input, _refs, _ctx) => {
+    // input is typed as { a: number; b: number }
     return input.a + input.b;
-  }
+  },
 });
 ```
 
@@ -563,6 +717,7 @@ GPL-3.0 © [ClickerMonkey](https://github.com/ClickerMonkey)
 
 ## Links
 
+- [Root README](../../README.md)
+- [@aeye/ai README](../ai/README.md)
 - [GitHub Repository](https://github.com/ClickerMonkey/aeye)
-- [Documentation](https://github.com/ClickerMonkey/aeye/tree/main/packages/core)
 - [Issue Tracker](https://github.com/ClickerMonkey/aeye/issues)