@jterrazz/intelligence 1.6.1 → 2.0.0

package/README.md

@@ -5,7 +5,7 @@
 [![NPM Version](https://img.shields.io/npm/v/@jterrazz/intelligence.svg)](https://www.npmjs.com/package/@jterrazz/intelligence)
 [![License](https://img.shields.io/npm/l/@jterrazz/intelligence.svg)](./LICENSE)
 
-`@jterrazz/intelligence` provides a clean, structured, and extensible foundation for building sophisticated AI agents. It's designed to help you create reliable and maintainable AI-powered applications by focusing on composability and type safety.
+`@jterrazz/intelligence` provides a clean, structured, and extensible foundation for building sophisticated AI agents. Built on the **Vercel AI SDK** with **OpenRouter** support, it's designed to help you create reliable and maintainable AI-powered applications by focusing on composability, type safety, and resilience.
 
 ---
 
@@ -13,10 +13,12 @@
 
 - **Composable Prompts**: Instead of monolithic prompts, the library offers a collection of constants. Mix and match them to build a precise system prompt that defines your agent's behavior, personality, and output format.
 
-- **Safe, Typed Tools**: A `SafeToolAdapter` provides built-in error handling and Zod-based schema validation for any tool you create. This ensures that tool inputs are valid and that your agent can gracefully handle execution errors.
+- **Safe, Typed Tools**: A `SafeTool` provides built-in error handling and Zod-based schema validation for any tool you create. This ensures that tool inputs are valid and that your agent can gracefully handle execution errors.
 
 - **Ports & Adapters Architecture**: The library uses a hexagonal architecture to separate core logic from implementation details. This makes it easy to swap out underlying models or services (e.g., switching from OpenAI to Anthropic) without rewriting your application.
 
+- **Structured Outputs**: Leverages both prompt-based schema instructions and OpenRouter's official structured outputs for reliable, validated responses.
+
 ## Installation
 
 ```bash
@@ -25,127 +27,140 @@ npm install @jterrazz/intelligence
 
 ---
 
+## Agent Types
+
+### 🗣️ **ChatAgent**
+
+For conversational AI and text generation with optional schema validation. Perfect for chatbots, content generation, and structured data extraction.
+
+### 🛡️ **ResilientAgent**
+
+A decorator that adds retry logic to any agent for fault-tolerant execution. Wraps other agents to handle transient failures gracefully.
+
+### 🔧 **ToolAgent**
+
+For complex workflows requiring external tools and function calling. Can reason about when to use tools and provide structured responses.
+
+---
+
 ## Quick Start
 
-Get your first agent running in minutes. This example creates a helpful agent for a Discord community.
+Get your first agent running in minutes. This example creates a helpful conversational agent.
 
 ```typescript
-import {
-  AutonomousAgentAdapter,
-  OpenRouterAdapter,
-  SystemPromptAdapter,
-  PROMPT_LIBRARY,
-} from '@jterrazz/intelligence';
+import { ChatAgent, OpenRouterProvider, SystemPrompt, PROMPTS } from '@jterrazz/intelligence';
 
 // 1. Set up the model provider
-const model = new OpenRouterAdapter({
+const provider = new OpenRouterProvider({
   apiKey: process.env.OPENROUTER_API_KEY!, // Make sure to set this environment variable
-  modelName: 'anthropic/claude-3.5-sonnet',
 });
 
-// 2. Create an agent using a preset prompt
-const agent = new AutonomousAgentAdapter('discord-bot', {
+// 2. Get a model instance
+const model = provider.getModel('anthropic/claude-sonnet-4');
+
+// 3. Create a conversational agent
+const agent = new ChatAgent('helpful-assistant', {
   model,
-  systemPrompt: new SystemPromptAdapter(PROMPT_LIBRARY.PRESETS.COMMUNITY_ANIMATOR),
+  systemPrompt: new SystemPrompt(PROMPTS.PRESETS.HELPFUL_ASSISTANT),
 });
 
-// 3. Run the agent
+// 4. Run the agent
 const response = await agent.run();
 
 console.log(response);
-// Output might be: "Hello, community! I'm here to help with any questions and keep the good vibes flowing. What's on your mind today?"
+// Output: "Hello! I'm here to help you with any questions or tasks you might have. What can I assist you with today?"
 ```
 
 ## Creating Domain-Specific Agents
 
 The most powerful feature of `@jterrazz/intelligence` is its ability to create specialized, reusable agents. By extending the base adapters, you can encapsulate an agent's logic, prompts, and tools into a clean, type-safe class.
 
-### 1. Data Extraction Agent (`BasicAgentAdapter`)
+### 1. Data Extraction Agent (`ChatAgent`)
 
-Use `BasicAgentAdapter` for simpler, one-shot tasks where you need a structured response but don't require complex tool use. This example creates a reusable agent to extract contact information.
+Use `ChatAgent` for structured data extraction and conversational tasks. This example creates a reusable agent to extract contact information with full type safety.
 
 ```typescript
 import {
-  BasicAgentAdapter,
-  ModelPort,
-  OpenRouterAdapter,
-  SystemPromptAdapter,
-  UserPromptAdapter,
-  PROMPT_LIBRARY,
+  ChatAgent,
+  OpenRouterProvider,
+  SystemPrompt,
+  UserPrompt,
+  PROMPTS,
 } from '@jterrazz/intelligence';
 import { z } from 'zod';
 
-// 1. Define the output type for compile-time type-safety
-interface Contact {
-  name: string;
-  email: string;
-}
+// 1. Define the output schema for both compile-time and runtime validation
+const contactSchema = z.object({
+  name: z.string().describe('The full name of the person'),
+  email: z.string().email().describe('The email address'),
+  phone: z.string().optional().describe('Phone number if available'),
+});
+
+type Contact = z.infer<typeof contactSchema>;
+
+// 2. Create a specialized agent by extending ChatAgent
+class ContactExtractorAgent extends ChatAgent<Contact> {
+  constructor(provider: OpenRouterProvider) {
+    const model = provider.getModel('anthropic/claude-sonnet-4');
 
-// 2. Create a specialized agent by extending BasicAgentAdapter
-class ContactExtractorAgent extends BasicAgentAdapter<Contact> {
-  constructor(model: ModelPort) {
     super('contact-extractor', {
       model,
-      // Define the schema for runtime validation and type inference
-      schema: z.object({
-        name: z.string().describe('The full name of the person'),
-        email: z.string().email().describe('The email address'),
-      }),
-      // Compose the system prompt from the library
-      systemPrompt: new SystemPromptAdapter(
-        PROMPT_LIBRARY.FORMATS.JSON,
+      schema: contactSchema, // Enables structured outputs + runtime validation
+      systemPrompt: new SystemPrompt(
         'You are an expert at extracting contact details from text.',
+        'Always extract the most complete information available.',
       ),
     });
   }
 }
 
 // 3. Instantiate and use the agent
-const model = new OpenRouterAdapter({
+const provider = new OpenRouterProvider({
   apiKey: process.env.OPENROUTER_API_KEY!,
-  modelName: 'anthropic/claude-3.5-sonnet',
 });
-const agent = new ContactExtractorAgent(model);
+const agent = new ContactExtractorAgent(provider);
 
-const text = 'Say hi to John Doe, you can reach him at john.doe@example.com.';
-const contact = await agent.run(new UserPromptAdapter(text));
+const text =
+  'Say hi to John Doe, you can reach him at john.doe@example.com or call (555) 123-4567.';
+const contact = await agent.run(new UserPrompt(text));
 
 console.log(contact);
-// Output: { name: 'John Doe', email: 'john.doe@example.com' }
+// Output: { name: 'John Doe', email: 'john.doe@example.com', phone: '(555) 123-4567' }
 ```
 
-### 2. Autonomous Agent with a Custom Tool (`AutonomousAgentAdapter`)
+### 2. Tool-Enabled Agent (`ToolAgent`)
 
-Use `AutonomousAgentAdapter` when you need an agent that can reason and use tools to accomplish a task. This example creates a weather assistant that uses a tool and returns a structured JSON response.
+Use `ToolAgent` when you need an agent that can reason and use tools to accomplish complex tasks. This example creates a weather assistant.
 
 ```typescript
 import {
-  AutonomousAgentAdapter,
-  ModelPort,
-  OpenRouterAdapter,
-  SafeToolAdapter,
-  SystemPromptAdapter,
-  UserPromptAdapter,
+  ToolAgent,
+  OpenRouterProvider,
+  SafeTool,
+  SystemPrompt,
+  UserPrompt,
 } from '@jterrazz/intelligence';
 import { z } from 'zod';
 
-// 1. Define the agent's final output type
-interface WeatherReport {
-  city: string;
-  temperature: number;
-  conditions: string;
-  forecast: string;
-}
+// 1. Define the agent's final output schema
+const weatherReportSchema = z.object({
+  city: z.string(),
+  temperature: z.number(),
+  conditions: z.string(),
+  forecast: z.string(),
+});
 
-// 2. Define a tool. Its `execute` function should return a string,
-// as the agent will process this output to formulate a final answer.
-const weatherTool = new SafeToolAdapter({
+type WeatherReport = z.infer<typeof weatherReportSchema>;
+
+// 2. Create a weather tool
+const weatherTool = new SafeTool({
   name: 'get_weather',
   description: 'Gets the current weather for a specified city.',
-  schema: z.object({ city: z.string().describe('The name of the city') }),
+  schema: z.object({
+    city: z.string().describe('The name of the city'),
+  }),
   execute: async ({ city }) => {
-    // In a real app, you would call a weather API here.
-    // The tool returns raw data, often as a JSON string.
+    // In a real app, you would call a weather API here
     if (city.toLowerCase() === 'paris') {
       return JSON.stringify({
         city: 'Paris',
@@ -158,44 +173,145 @@ const weatherTool = new SafeToolAdapter({
   },
 });
 
-// 3. Create a specialized agent that uses the tool and has a structured output
-class WeatherAssistantAgent extends AutonomousAgentAdapter<WeatherReport> {
-  constructor(model: ModelPort) {
+// 3. Create a specialized tool agent
+class WeatherAssistantAgent extends ToolAgent<WeatherReport> {
+  constructor(provider: OpenRouterProvider) {
+    const model = provider.getModel('anthropic/claude-sonnet-4');
+
     super('weather-assistant', {
       model,
       tools: [weatherTool],
-      // This schema defines the agent's FINAL output structure
-      schema: z.object({
-        city: z.string(),
-        temperature: z.number(),
-        conditions: z.string(),
-        forecast: z.string(),
-      }),
-      systemPrompt: new SystemPromptAdapter(
+      schema: weatherReportSchema, // Structured output for the final response
+      systemPrompt: new SystemPrompt(
         'You are a helpful weather assistant.',
-        'You must use the provided tools to get weather information and then respond with a structured JSON object.',
+        'Use the available tools to get weather information, then provide a complete weather report.',
       ),
     });
   }
 }
 
 // 4. Instantiate and use the agent
-const model = new OpenRouterAdapter({
+const provider = new OpenRouterProvider({
   apiKey: process.env.OPENROUTER_API_KEY!,
-  modelName: 'anthropic/claude-3.5-sonnet',
 });
-const agent = new WeatherAssistantAgent(model);
+const agent = new WeatherAssistantAgent(provider);
 
-const response = await agent.run(new UserPromptAdapter("What's the weather like in Paris?"));
+const response = await agent.run(new UserPrompt("What's the weather like in Paris?"));
 
 console.log(response);
 // Output: { city: 'Paris', temperature: 25, conditions: 'sunny', forecast: 'clear skies for the next 24 hours' }
 ```
 
+### 3. Resilient Agent (`ResilientAgent`)
+
+Use `ResilientAgent` to add retry logic and fault tolerance to any existing agent. Perfect for production environments where reliability is crucial.
+
+```typescript
+import {
+  ChatAgent,
+  ResilientAgent,
+  OpenRouterProvider,
+  SystemPrompt,
+  UserPrompt,
+} from '@jterrazz/intelligence';
+import { z } from 'zod';
+
+// 1. Create a base agent
+const provider = new OpenRouterProvider({
+  apiKey: process.env.OPENROUTER_API_KEY!,
+});
+
+const model = provider.getModel('anthropic/claude-sonnet-4');
+
+const baseAgent = new ChatAgent('sentiment-analyzer', {
+  model,
+  schema: z.object({
+    sentiment: z.enum(['positive', 'negative', 'neutral']),
+    confidence: z.number().min(0).max(1),
+  }),
+  systemPrompt: new SystemPrompt(
+    'You are a sentiment analysis expert.',
+    'Analyze the sentiment of the given text and provide your confidence level.',
+  ),
+});
+
+// 2. Wrap with resilient behavior
+const resilientAgent = new ResilientAgent(baseAgent, {
+  retries: 3, // Will retry up to 3 times on failure
+});
+
+// 3. Use the resilient agent - it will automatically retry on failures
+const result = await resilientAgent.run(new UserPrompt('I absolutely love this new feature!'));
+
+console.log(result);
+// Output: { sentiment: 'positive', confidence: 0.95 }
+console.log(resilientAgent.name);
+// Output: "Resilient(sentiment-analyzer)"
+```
+
+## Advanced Configuration
+
+### Model Configuration
+
+Customize model behavior with detailed configuration options:
+
+```typescript
+const provider = new OpenRouterProvider({
+  apiKey: process.env.OPENROUTER_API_KEY!,
+  metadata: {
+    application: 'My AI App',
+    website: 'https://myapp.com',
+  },
+});
+
+// Configure model-specific settings
+const model = provider.getModel('anthropic/claude-sonnet-4', {
+  maxTokens: 100000,
+  reasoning: {
+    effort: 'high', // Use high reasoning effort for complex tasks
+    exclude: true, // Exclude reasoning from the response
+  },
+});
+```
+
+### Combining Agents
+
+Create powerful workflows by combining different agent types:
+
+```typescript
+// Create a pipeline: Chat Agent → Tool Agent → Resilient wrapper
+const extractor = new ChatAgent('data-extractor', {
+  /* ... */
+});
+const processor = new ToolAgent('data-processor', {
+  /* ... */
+});
+const resilientProcessor = new ResilientAgent(processor, { retries: 3 });
+
+// Use them in sequence
+const rawData = await extractor.run(userInput);
+const processedData = await resilientProcessor.run(rawData);
+```
+
 ## Development
 
 - **Linting**: `npm run lint`
 - **Testing**: `npm run test`
+- **Building**: `npm run build`
+
+## Architecture
+
+The library follows **Clean Architecture** principles:
+
+- **Ports**: Define interfaces for models, agents, tools, and prompts
+- **Adapters**: Implement the ports for specific providers (OpenRouter, tools, etc.)
+- **Domain Logic**: Core agent behavior independent of external dependencies
+
+This makes the library:
+
+- **Testable**: Easy to mock dependencies and test business logic
+- **Extensible**: Simple to add new model providers or agent types
+- **Maintainable**: Clear separation between domain logic and infrastructure
 
 ## Contributing
 

package/dist/adapters/agents/{basic-agent.adapter.d.ts → chat-agent.adapter.d.ts}

@@ -3,23 +3,23 @@ import { z } from 'zod/v4';
 import { type AgentPort } from '../../ports/agent.port.js';
 import type { ModelPort } from '../../ports/model.port.js';
 import type { PromptPort } from '../../ports/prompt.port.js';
-import type { SystemPromptAdapter } from '../prompts/system-prompt.adapter.js';
-export interface BasicAgentOptions<TOutput = string> {
+import type { SystemPrompt } from '../prompts/system-prompt.adapter.js';
+export interface ChatAgentOptions<TOutput = string> {
     logger?: LoggerPort;
     model: ModelPort;
     schema?: z.ZodSchema<TOutput>;
-    systemPrompt: SystemPromptAdapter;
+    systemPrompt: SystemPrompt;
     verbose?: boolean;
 }
 /**
- * A basic agent for direct, one-shot interactions with a model.
+ * A conversational agent for direct, one-shot interactions with a model.
  * It supports optional response parsing against a Zod schema but does not use tools.
  * @template TOutput - The TypeScript type of the output
  */
-export declare class BasicAgentAdapter<TOutput = string> implements AgentPort<PromptPort, TOutput> {
+export declare class ChatAgent<TOutput = string> implements AgentPort<PromptPort, TOutput> {
     readonly name: string;
     private readonly options;
-    constructor(name: string, options: BasicAgentOptions<TOutput>);
+    constructor(name: string, options: ChatAgentOptions<TOutput>);
     run(input?: PromptPort): Promise<null | TOutput>;
     private invokeModel;
     private parseResponse;

package/dist/adapters/agents/{basic-agent.adapter.js → chat-agent.adapter.js}

@@ -157,22 +157,23 @@ function _ts_generator(thisArg, body) {
         };
     }
 }
+import { generateText } from 'ai';
 import { z } from 'zod/v4';
-import { AIResponseParser } from '../utils/ai-response-parser.js';
+import { StructuredResponseParser } from '../utils/structured-response-parser.js';
 /**
- * A basic agent for direct, one-shot interactions with a model.
+ * A conversational agent for direct, one-shot interactions with a model.
  * It supports optional response parsing against a Zod schema but does not use tools.
  * @template TOutput - The TypeScript type of the output
- */ export var BasicAgentAdapter = /*#__PURE__*/ function() {
+ */ export var ChatAgent = /*#__PURE__*/ function() {
     "use strict";
-    function BasicAgentAdapter(name, options) {
-        _class_call_check(this, BasicAgentAdapter);
+    function ChatAgent(name, options) {
+        _class_call_check(this, ChatAgent);
         _define_property(this, "name", void 0);
         _define_property(this, "options", void 0);
         this.name = name;
         this.options = options;
     }
-    _create_class(BasicAgentAdapter, [
+    _create_class(ChatAgent, [
         {
             key: "run",
             value: function run(input) {
@@ -213,7 +214,6 @@ import { AIResponseParser } from '../utils/ai-response-parser.js';
                                     (_this_options_logger2 = this.options.logger) === null || _this_options_logger2 === void 0 ? void 0 : _this_options_logger2.debug('Execution finished', {
                                         agent: this.name
                                     });
-                                    // When no schema is provided, we assume TOutput is string (default), so content is the result
                                     return [
                                         2,
                                         content
@@ -227,7 +227,8 @@ import { AIResponseParser } from '../utils/ai-response-parser.js';
                                 error = _state.sent();
                                 (_this_options_logger3 = this.options.logger) === null || _this_options_logger3 === void 0 ? void 0 : _this_options_logger3.error('Execution failed', {
                                     agent: this.name,
-                                    error: _instanceof(error, Error) ? error.message : 'Unknown error'
+                                    error: _instanceof(error, Error) ? error.message : 'Unknown error',
+                                    errorStack: _instanceof(error, Error) ? error.stack : undefined
                                 });
                                 return [
                                     2,
@@ -246,13 +247,12 @@ import { AIResponseParser } from '../utils/ai-response-parser.js';
             key: "invokeModel",
             value: function invokeModel(input) {
                 return _async_to_generator(function() {
-                    var _this_options_logger, userInput, systemMessage, jsonSchema, isPrimitiveType, messages, _this_options_logger1, response, content;
+                    var _this_options_logger, userInput, systemMessage, jsonSchema, isPrimitiveType, messages, _this_options_logger1, generateConfig, jsonSchema1, text;
                     return _ts_generator(this, function(_state) {
                         switch(_state.label){
                             case 0:
                                 userInput = this.resolveUserInput(input);
                                 systemMessage = this.options.systemPrompt.generate();
-                                // Add schema definition to system prompt if schema is provided
                                 if (this.options.schema) {
                                     jsonSchema = z.toJSONSchema(this.options.schema);
                                     isPrimitiveType = [
@@ -288,19 +288,36 @@ import { AIResponseParser } from '../utils/ai-response-parser.js';
                                         messages: messages
                                     });
                                 }
+                                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                                generateConfig = {
+                                    messages: messages,
+                                    model: this.options.model.getVercelModel()
+                                };
+                                // Prepare structured outputs configuration for better schema validation when schema is provided
+                                // NOTE: OpenRouter supports structured outputs, but @openrouter/ai-sdk-provider (v0.7.3)
+                                // doesn't pass through responseFormat parameter yet. Currently relies on prompt-based instructions.
+                                // Once provider support is added, this will provide stronger guarantees than prompts alone.
+                                // See: https://openrouter.ai/docs/features/structured-outputs
+                                if (this.options.schema) {
+                                    jsonSchema1 = z.toJSONSchema(this.options.schema);
+                                    generateConfig.responseFormat = {
+                                        json_schema: {
+                                            name: 'response',
+                                            schema: jsonSchema1,
+                                            strict: true
+                                        },
+                                        type: 'json_schema'
+                                    };
+                                }
                                 return [
                                     4,
-                                    this.options.model.getModel().invoke(messages)
+                                    generateText(generateConfig)
                                 ];
                             case 1:
-                                response = _state.sent();
-                                content = response.content;
-                                if (typeof content !== 'string') {
-                                    throw new Error('Model returned a non-string content type.');
-                                }
+                                text = _state.sent().text;
                                 return [
                                     2,
-                                    content
+                                    text
                                 ];
                         }
                     });
@@ -311,7 +328,7 @@ import { AIResponseParser } from '../utils/ai-response-parser.js';
             key: "parseResponse",
             value: function parseResponse(content, schema) {
                 try {
-                    return new AIResponseParser(schema).parse(content);
+                    return new StructuredResponseParser(schema).parse(content);
                 } catch (error) {
                     var _this_options_logger;
                     (_this_options_logger = this.options.logger) === null || _this_options_logger === void 0 ? void 0 : _this_options_logger.error('Failed to parse model response.', {
@@ -333,7 +350,7 @@ import { AIResponseParser } from '../utils/ai-response-parser.js';
             }
         }
     ]);
-    return BasicAgentAdapter;
+    return ChatAgent;
 }();
 
-//# sourceMappingURL=basic-agent.adapter.js.map
+//# sourceMappingURL=chat-agent.adapter.js.map

package/dist/adapters/agents/chat-agent.adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/adapters/agents/chat-agent.adapter.ts"],"sourcesContent":["import { type LoggerPort } from '@jterrazz/logger';\nimport { generateText } from 'ai';\nimport { z } from 'zod/v4';\n\nimport { type AgentPort } from '../../ports/agent.port.js';\nimport type { ModelPort } from '../../ports/model.port.js';\nimport type { PromptPort } from '../../ports/prompt.port.js';\n\nimport { StructuredResponseParser } from '../utils/structured-response-parser.js';\n\nimport type { SystemPrompt } from '../prompts/system-prompt.adapter.js';\n\nexport interface ChatAgentOptions<TOutput = string> {\n    logger?: LoggerPort;\n    model: ModelPort;\n    schema?: z.ZodSchema<TOutput>;\n    systemPrompt: SystemPrompt;\n    verbose?: boolean;\n}\n\n/**\n * A conversational agent for direct, one-shot interactions with a model.\n * It supports optional response parsing against a Zod schema but does not use tools.\n * @template TOutput - The TypeScript type of the output\n */\nexport class ChatAgent<TOutput = string> implements AgentPort<PromptPort, TOutput> {\n    constructor(\n        public readonly name: string,\n        private readonly options: ChatAgentOptions<TOutput>,\n    ) {}\n\n    async run(input?: PromptPort): Promise<null | TOutput> {\n        this.options.logger?.debug('Starting query execution', { agent: this.name });\n\n        try {\n            const content = await this.invokeModel(input);\n\n            if (this.options.schema) {\n                const parsedResponse = this.parseResponse(content, this.options.schema);\n\n                this.options.logger?.debug('Execution finished and response parsed', {\n                    agent: this.name,\n                });\n\n                return parsedResponse;\n            } else {\n                this.options.logger?.debug('Execution finished', { agent: this.name });\n\n                return content as TOutput;\n            }\n        } catch (error) {\n            this.options.logger?.error('Execution failed', {\n                agent: this.name,\n                error: error instanceof Error ? error.message : 'Unknown error',\n                errorStack: error instanceof Error ? error.stack : undefined,\n            });\n            return null;\n        }\n    }\n\n    private async invokeModel(input?: PromptPort): Promise<string> {\n        const userInput = this.resolveUserInput(input);\n        let systemMessage = this.options.systemPrompt.generate();\n\n        if (this.options.schema) {\n            const jsonSchema = z.toJSONSchema(this.options.schema);\n            const isPrimitiveType = ['boolean', 'integer', 'number', 'string'].includes(\n                jsonSchema.type as string,\n            );\n\n            if (isPrimitiveType) {\n                systemMessage += `\\n\\n<OUTPUT_FORMAT>\nYou must respond with a ${jsonSchema.type} value that matches this schema:\n\n\\`\\`\\`json\n${JSON.stringify(jsonSchema, null, 2)}\n\\`\\`\\`\n\nYour response should be only the ${jsonSchema.type} value, without any JSON wrapping or additional text.\n</OUTPUT_FORMAT>`;\n            } else {\n                systemMessage += `\\n\\n<OUTPUT_FORMAT>\nYou must respond with valid JSON that matches this JSON schema description:\n\n\\`\\`\\`json\n${JSON.stringify(jsonSchema, null, 2)}\n\\`\\`\\`\n\nYour response must be parseable JSON that validates against this schema. Do not include any text outside the JSON.\n</OUTPUT_FORMAT>`;\n            }\n        }\n\n        const messages = [\n            { content: systemMessage, role: 'system' as const },\n            { content: userInput, role: 'user' as const },\n        ];\n\n        this.options.logger?.debug('Invoking model...', {\n            agent: this.name,\n            hasSchema: !!this.options.schema,\n        });\n\n        if (this.options.verbose) {\n            this.options.logger?.debug('Sending messages to model...', {\n                agent: this.name,\n                messages,\n            });\n        }\n\n        // eslint-disable-next-line @typescript-eslint/no-explicit-any\n        const generateConfig: any = {\n            messages,\n            model: this.options.model.getVercelModel(),\n        };\n\n        // Prepare structured outputs configuration for better schema validation when schema is provided\n        // NOTE: OpenRouter supports structured outputs, but @openrouter/ai-sdk-provider (v0.7.3)\n        // doesn't pass through responseFormat parameter yet. Currently relies on prompt-based instructions.\n        // Once provider support is added, this will provide stronger guarantees than prompts alone.\n        // See: https://openrouter.ai/docs/features/structured-outputs\n        if (this.options.schema) {\n            const jsonSchema = z.toJSONSchema(this.options.schema);\n            generateConfig.responseFormat = {\n                json_schema: {\n                    name: 'response',\n                    schema: jsonSchema,\n                    strict: true,\n                },\n                type: 'json_schema',\n            };\n        }\n\n        const { text } = await generateText(generateConfig);\n\n        return text;\n    }\n\n    private parseResponse<TResponse>(content: string, schema: z.ZodSchema<TResponse>): TResponse {\n        try {\n            return new StructuredResponseParser(schema).parse(content);\n        } catch (error) {\n            this.options.logger?.error('Failed to parse model response.', {\n                agent: this.name,\n                error: error instanceof Error ? error.message : 'Unknown error',\n                rawContent: content,\n            });\n            throw new Error('Invalid response format from model.');\n        }\n    }\n\n    private resolveUserInput(input?: PromptPort): string {\n        if (input) {\n            return input.generate();\n        }\n        return 'Proceed with your instructions.';\n    }\n}\n"],"names":["generateText","z","StructuredResponseParser","ChatAgent","name","options","run","input","content","parsedResponse","error","logger","debug","agent","invokeModel","schema","parseResponse","Error","message","errorStack","stack","undefined","userInput","systemMessage","jsonSchema","isPrimitiveType","messages","generateConfig","text","resolveUserInput","systemPrompt","generate","toJSONSchema","includes","type","JSON","stringify","role","hasSchema","verbose","model","getVercelModel","responseFormat","json_schema","strict","parse","rawContent"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AACA,SAASA,YAAY,QAAQ,KAAK;AAClC,SAASC,CAAC,QAAQ,SAAS;AAM3B,SAASC,wBAAwB,QAAQ,yCAAyC;AAYlF;;;;CAIC,GACD,OAAO,IAAA,AAAMC,0BAAN;;aAAMA,UAEL,AAAgBC,IAAY,EAC5B,AAAiBC,OAAkC;gCAH9CF;;;aAEWC,OAAAA;aACCC,UAAAA;;kBAHZF;;YAMHG,KAAAA;mBAAN,SAAMA,IAAIC,KAAkB;;wBACxB,sBAGUC,SAKF,uBAFMC,gBAQN,uBAICC,OACL;;;;iCAnBJ,uBAAA,IAAI,CAACL,OAAO,CAACM,MAAM,cAAnB,2CAAA,qBAAqBC,KAAK,CAAC,4BAA4B;oCAAEC,OAAO,IAAI,CAACT,IAAI;gCAAC;;;;;;;;;gCAGtD;;oCAAM,IAAI,CAACU,WAAW,CAACP;;;gCAAjCC,UAAU;gCAEhB,IAAI,IAAI,CAACH,OAAO,CAACU,MAAM,EAAE;;oCACfN,iBAAiB,IAAI,CAACO,aAAa,CAACR,SAAS,IAAI,CAACH,OAAO,CAACU,MAAM;qCAEtE,wBAAA,IAAI,CAACV,OAAO,CAACM,MAAM,cAAnB,4CAAA,sBAAqBC,KAAK,CAAC,0CAA0C;wCACjEC,OAAO,IAAI,CAACT,IAAI;oCACpB;oCAEA;;wCAAOK;;gCACX,OAAO;;qCACH,wBAAA,IAAI,CAACJ,OAAO,CAACM,MAAM,cAAnB,4CAAA,sBAAqBC,KAAK,CAAC,sBAAsB;wCAAEC,OAAO,IAAI,CAACT,IAAI;oCAAC;oCAEpE;;wCAAOI;;gCACX;;;;;;gCACKE;iCACL,wBAAA,IAAI,CAACL,OAAO,CAACM,MAAM,cAAnB,4CAAA,sBAAqBD,KAAK,CAAC,oBAAoB;oCAC3CG,OAAO,IAAI,CAACT,IAAI;oCAChBM,OAAOA,AAAK,YAALA,OAAiBO,SAAQP,MAAMQ,OAAO,GAAG;oCAChDC,YAAYT,AAAK,YAALA,OAAiBO,SAAQP,MAAMU,KAAK,GAAGC;gCACvD;gCACA;;oCAAO;;;;;;;;gBAEf;;;;YAEcP,KAAAA;mBAAd,SAAcA,YAAYP,KAAkB;;wBAsCxC,sBArCMe,WACFC,eAGMC,YACAC,iBA2BJC,UAWF,uBAOEC,gBAWIH,aAWFI;;;;gCAxEFN,YAAY,IAAI,CAACO,gBAAgB,CAACtB;gCACpCgB,gBAAgB,IAAI,CAAClB,OAAO,CAACyB,YAAY,CAACC,QAAQ;gCAEtD,IAAI,IAAI,CAAC1B,OAAO,CAACU,MAAM,EAAE;oCACfS,aAAavB,EAAE+B,YAAY,CAAC,IAAI,CAAC3B,OAAO,CAACU,MAAM;oCAC/CU,kBAAkB;wCAAC;wCAAW;wCAAW;wCAAU;sCAAUQ,QAAQ,CACvET,WAAWU,IAAI;oCAGnB,IAAIT,iBAAiB;wCACjBF,iBAAiB,AAAC,gDAIhCY,OAHwBX,WAAWU,IAAI,EAAC,iDAMPV,OAHjCW,KAAKC,SAAS,CAACZ,YAAY,MAAM,IAAG,8CAGa,OAAhBA,WAAWU,IAAI,EAAC;oCAEvC,OAAO;wCACHX,iBAAiB,AAAC,gHAII,OAApCY,KAAKC,SAAS,CAACZ,YAAY,MAAM,IAAG;oCAK1B;gCACJ;gCAEME;oCACF;wCAAElB,SAASe;wCAAec,MAAM;oCAAkB;oCAClD;wCAAE7B,SAASc;wCAAWe,MAAM;oCAAgB;;iCAGhD,uBAAA,IAAI,CAAChC,OAAO,CAACM,MAAM,cAAnB,2CAAA,qBAAqBC,KAAK,CAAC,qBAAqB;oCAC5CC,OAAO,IAAI,CAACT,IAAI;oCAChBkC,WAAW,CAAC,CAAC,IAAI,CAACjC,OAAO,CAACU,MAAM;gCACpC;gCAEA,IAAI,IAAI,CAACV,OAAO,CAACkC,OAAO,EAAE;;qCACtB,wBAAA,IAAI,CAAClC,OAAO,CAACM,MAAM,cAAnB,4CAAA,sBAAqBC,KAAK,CAAC,gCAAgC;wCACvDC,OAAO,IAAI,CAACT,IAAI;wCAChBsB,UAAAA;oCACJ;gCACJ;gCAEA,8DAA8D;gCACxDC,iBAAsB;oCACxBD,UAAAA;oCACAc,OAAO,IAAI,CAACnC,OAAO,CAACmC,KAAK,CAACC,cAAc;gCAC5C;gCAEA,gGAAgG;gCAChG,yFAAyF;gCACzF,oGAAoG;gCACpG,4FAA4F;gCAC5F,8DAA8D;gCAC9D,IAAI,IAAI,CAACpC,OAAO,CAACU,MAAM,EAAE;oCACfS,cAAavB,EAAE+B,YAAY,CAAC,IAAI,CAAC3B,OAAO,CAACU,MAAM;oCACrDY,eAAee,cAAc,GAAG;wCAC5BC,aAAa;4CACTvC,MAAM;4CACNW,QAAQS;4CACRoB,QAAQ;wCACZ;wCACAV,MAAM;oCACV;gCACJ;gCAEiB;;oCAAMlC,aAAa2B;;;gCAA5BC,OAAS,cAATA;gCAER;;oCAAOA;;;;gBACX;;;;YAEQZ,KAAAA;mBAAR,SAAQA,cAAyBR,OAAe,EAAEO,MAA8B;gBAC5E,IAAI;oBACA,OAAO,IAAIb,yBAAyBa,QAAQ8B,KAAK,CAACrC;gBACtD,EAAE,OAAOE,OAAO;wBACZ;qBAAA,uBAAA,IAAI,CAACL,OAAO,CAACM,MAAM,cAAnB,2CAAA,qBAAqBD,KAAK,CAAC,mCAAmC;wBAC1DG,OAAO,IAAI,CAACT,IAAI;wBAChBM,OAAOA,AAAK,YAALA,OAAiBO,SAAQP,MAAMQ,OAAO,GAAG;wBAChD4B,YAAYtC;oBAChB;oBACA,MAAM,IAAIS,MAAM;gBACpB;YACJ;;;YAEQY,KAAAA;mBAAR,SAAQA,iBAAiBtB,KAAkB;gBACvC,IAAIA,OAAO;oBACP,OAAOA,MAAMwB,QAAQ;gBACzB;gBACA,OAAO;YACX;;;WAnIS5B;IAoIZ"}

package/dist/adapters/agents/{retryable-agent.adapter.d.ts → resilient-agent.adapter.d.ts}

@@ -1,20 +1,20 @@
 import { type LoggerPort } from '@jterrazz/logger';
 import { type AgentPort } from '../../ports/agent.port.js';
 import type { PromptPort } from '../../ports/prompt.port.js';
-export interface RetryableAgentAdapterOptions {
+export interface ResilientAgentOptions {
     logger?: LoggerPort;
     retries?: number;
 }
 /**
- * A decorator agent that adds retry logic to an existing agent.
+ * A decorator agent that adds retry logic to an existing agent for resilient execution.
  * @template TInput - The TypeScript type of the input
  * @template TOutput - The TypeScript type of the output
  */
-export declare class RetryableAgentAdapter<TInput = PromptPort, TOutput = string> implements AgentPort<TInput, TOutput> {
+export declare class ResilientAgent<TInput = PromptPort, TOutput = string> implements AgentPort<TInput, TOutput> {
     private readonly agent;
     readonly name: string;
     private readonly logger?;
     private readonly retries;
-    constructor(agent: AgentPort<TInput, TOutput>, options?: RetryableAgentAdapterOptions);
+    constructor(agent: AgentPort<TInput, TOutput>, options?: ResilientAgentOptions);
     run(input?: TInput): Promise<null | TOutput>;
 }

package/dist/adapters/agents/{retryable-agent.adapter.js → resilient-agent.adapter.js}

@@ -158,25 +158,25 @@ function _ts_generator(thisArg, body) {
     }
 }
 /**
- * A decorator agent that adds retry logic to an existing agent.
+ * A decorator agent that adds retry logic to an existing agent for resilient execution.
  * @template TInput - The TypeScript type of the input
  * @template TOutput - The TypeScript type of the output
- */ export var RetryableAgentAdapter = /*#__PURE__*/ function() {
+ */ export var ResilientAgent = /*#__PURE__*/ function() {
     "use strict";
-    function RetryableAgentAdapter(agent) {
+    function ResilientAgent(agent) {
         var options = arguments.length > 1 && arguments[1] !== void 0 ? arguments[1] : {};
-        _class_call_check(this, RetryableAgentAdapter);
+        _class_call_check(this, ResilientAgent);
         _define_property(this, "agent", void 0);
         _define_property(this, "name", void 0);
         _define_property(this, "logger", void 0);
         _define_property(this, "retries", void 0);
         this.agent = agent;
         var logger = options.logger, _options_retries = options.retries, retries = _options_retries === void 0 ? 1 : _options_retries;
-        this.name = "Retryable(".concat(agent.name, ")");
+        this.name = "Resilient(".concat(agent.name, ")");
         this.logger = logger;
         this.retries = retries;
     }
-    _create_class(RetryableAgentAdapter, [
+    _create_class(ResilientAgent, [
         {
             key: "run",
             value: function run(input) {
@@ -257,7 +257,7 @@ function _ts_generator(thisArg, body) {
             }
         }
     ]);
-    return RetryableAgentAdapter;
+    return ResilientAgent;
 }();
 
-//# sourceMappingURL=retryable-agent.adapter.js.map
+//# sourceMappingURL=resilient-agent.adapter.js.map

package/dist/adapters/agents/resilient-agent.adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/adapters/agents/resilient-agent.adapter.ts"],"sourcesContent":["import { type LoggerPort } from '@jterrazz/logger';\n\nimport { type AgentPort } from '../../ports/agent.port.js';\nimport type { PromptPort } from '../../ports/prompt.port.js';\n\nexport interface ResilientAgentOptions {\n    logger?: LoggerPort;\n    retries?: number;\n}\n\n/**\n * A decorator agent that adds retry logic to an existing agent for resilient execution.\n * @template TInput - The TypeScript type of the input\n * @template TOutput - The TypeScript type of the output\n */\nexport class ResilientAgent<TInput = PromptPort, TOutput = string>\n    implements AgentPort<TInput, TOutput>\n{\n    public readonly name: string;\n    private readonly logger?: LoggerPort;\n    private readonly retries: number;\n\n    constructor(\n        private readonly agent: AgentPort<TInput, TOutput>,\n        options: ResilientAgentOptions = {},\n    ) {\n        const { logger, retries = 1 } = options;\n        this.name = `Resilient(${agent.name})`;\n        this.logger = logger;\n        this.retries = retries;\n    }\n\n    async run(input?: TInput): Promise<null | TOutput> {\n        const maxAttempts = this.retries + 1;\n\n        for (let attempt = 1; attempt <= maxAttempts; attempt++) {\n            try {\n                this.logger?.debug(`Attempt ${attempt} of ${maxAttempts}`, { agent: this.name });\n                const result = await this.agent.run(input);\n\n                if (result !== null) {\n                    this.logger?.debug(`Attempt ${attempt} of ${maxAttempts} succeeded`, {\n                        agent: this.name,\n                    });\n                    return result;\n                }\n\n                this.logger?.debug(\n                    `Attempt ${attempt} of ${maxAttempts} failed: agent returned null`,\n                    { agent: this.name },\n                );\n            } catch (error) {\n                this.logger?.debug(`Attempt ${attempt} of ${maxAttempts} failed with an error`, {\n                    agent: this.name,\n                    error: error instanceof Error ? error.message : 'Unknown error',\n                });\n            }\n        }\n\n        this.logger?.error(`All ${maxAttempts} attempts failed`, { agent: this.name });\n        return null;\n    }\n}\n"],"names":["ResilientAgent","agent","options","name","logger","retries","run","input","maxAttempts","attempt","result","error","debug","Error","message"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAUA;;;;CAIC,GACD,OAAO,IAAA,AAAMA,+BAAN;;aAAMA,eAQL,AAAiBC,KAAiC;YAClDC,UAAAA,iEAAiC,CAAC;gCAT7BF;;QAGT,uBAAgBG,QAAhB,KAAA;QACA,uBAAiBC,UAAjB,KAAA;QACA,uBAAiBC,WAAjB,KAAA;aAGqBJ,QAAAA;QAGjB,IAAQG,SAAwBF,QAAxBE,2BAAwBF,QAAhBG,SAAAA,wCAAU;QAC1B,IAAI,CAACF,IAAI,GAAG,AAAC,aAAuB,OAAXF,MAAME,IAAI,EAAC;QACpC,IAAI,CAACC,MAAM,GAAGA;QACd,IAAI,CAACC,OAAO,GAAGA;;kBAdVL;;YAiBHM,KAAAA;mBAAN,SAAMA,IAAIC,KAAc;;wBA2BpB,cA1BMC,aAEGC,SAED,eAUA,eATMC,QAGF,eAUCC,OACL;;;;gCAnBFH,cAAc,IAAI,CAACH,OAAO,GAAG;gCAE1BI,UAAU;;;qCAAGA,CAAAA,WAAWD,WAAU;;;;;;;;;;;;iCAEnC,gBAAA,IAAI,CAACJ,MAAM,cAAX,oCAAA,cAAaQ,KAAK,CAAC,AAAC,WAAwBJ,OAAdC,SAAQ,QAAkB,OAAZD,cAAe;oCAAEP,OAAO,IAAI,CAACE,IAAI;gCAAC;gCAC/D;;oCAAM,IAAI,CAACF,KAAK,CAACK,GAAG,CAACC;;;gCAA9BG,SAAS;gCAEf,IAAIA,WAAW,MAAM;;qCACjB,gBAAA,IAAI,CAACN,MAAM,cAAX,oCAAA,cAAaQ,KAAK,CAAC,AAAC,WAAwBJ,OAAdC,SAAQ,QAAkB,OAAZD,aAAY,eAAa;wCACjEP,OAAO,IAAI,CAACE,IAAI;oCACpB;oCACA;;wCAAOO;;gCACX;iCAEA,gBAAA,IAAI,CAACN,MAAM,cAAX,oCAAA,cAAaQ,KAAK,CACd,AAAC,WAAwBJ,OAAdC,SAAQ,QAAkB,OAAZD,aAAY,iCACrC;oCAAEP,OAAO,IAAI,CAACE,IAAI;gCAAC;;;;;;gCAElBQ;iCACL,gBAAA,IAAI,CAACP,MAAM,cAAX,oCAAA,cAAaQ,KAAK,CAAC,AAAC,WAAwBJ,OAAdC,SAAQ,QAAkB,OAAZD,aAAY,0BAAwB;oCAC5EP,OAAO,IAAI,CAACE,IAAI;oCAChBQ,OAAOA,AAAK,YAALA,OAAiBE,SAAQF,MAAMG,OAAO,GAAG;gCACpD;;;;;;gCApBsCL;;;;;;iCAwB9C,eAAA,IAAI,CAACL,MAAM,cAAX,mCAAA,aAAaO,KAAK,CAAC,AAAC,OAAkB,OAAZH,aAAY,qBAAmB;oCAAEP,OAAO,IAAI,CAACE,IAAI;gCAAC;gCAC5E;;oCAAO;;;;gBACX;;;;WA9CSH;IA+CZ"}