@jterrazz/intelligence 1.6.1 → 3.0.0

package/README.md

@@ -1,208 +1,112 @@
 # @jterrazz/intelligence
 
-**A composable, type-safe, and framework-agnostic AI agent library for TypeScript.**
-
-[![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.
-
----
-
-## Core Principles
-
-- **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.
-
-- **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.
+Lightweight utilities for AI SDK apps — structured output parsing, text sanitization, and provider helpers.
 
 ## Installation
 
 ```bash
-npm install @jterrazz/intelligence
+npm install @jterrazz/intelligence ai zod
 ```
 
----
+## Parsing Utilities
 
-## Quick Start
+### `parseObject` — Extract structured data from AI responses
 
-Get your first agent running in minutes. This example creates a helpful agent for a Discord community.
+Extracts and validates JSON from messy AI outputs (markdown blocks, embedded JSON, malformed syntax).
 
 ```typescript
-import {
-  AutonomousAgentAdapter,
-  OpenRouterAdapter,
-  SystemPromptAdapter,
-  PROMPT_LIBRARY,
-} from '@jterrazz/intelligence';
-
-// 1. Set up the model provider
-const model = new OpenRouterAdapter({
-  apiKey: process.env.OPENROUTER_API_KEY!, // Make sure to set this environment variable
-  modelName: 'anthropic/claude-3.5-sonnet',
-});
+import { parseObject } from '@jterrazz/intelligence';
+import { z } from 'zod';
 
-// 2. Create an agent using a preset prompt
-const agent = new AutonomousAgentAdapter('discord-bot', {
-  model,
-  systemPrompt: new SystemPromptAdapter(PROMPT_LIBRARY.PRESETS.COMMUNITY_ANIMATOR),
+const schema = z.object({
+    title: z.string(),
+    tags: z.array(z.string()),
 });
 
-// 3. 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?"
+// Handles markdown code blocks, embedded JSON, trailing commas, etc.
+const text = '```json\n{"title": "Hello", "tags": ["ai", "typescript"]}\n```';
+const result = parseObject(text, schema);
+// → { title: 'Hello', tags: ['ai', 'typescript'] }
 ```
 
-## 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.
+### `createSchemaPrompt` — Generate schema instructions for prompts
 
-### 1. Data Extraction Agent (`BasicAgentAdapter`)
-
-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.
+Creates system prompt instructions for models that don't support native structured outputs.
 
 ```typescript
-import {
-  BasicAgentAdapter,
-  ModelPort,
-  OpenRouterAdapter,
-  SystemPromptAdapter,
-  UserPromptAdapter,
-  PROMPT_LIBRARY,
-} from '@jterrazz/intelligence';
+import { generateText } from 'ai';
+import { createSchemaPrompt, parseObject } from '@jterrazz/intelligence';
 import { z } from 'zod';
 
-// 1. Define the output type for compile-time type-safety
-interface Contact {
-  name: string;
-  email: string;
-}
-
-// 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,
-        'You are an expert at extracting contact details from text.',
-      ),
-    });
-  }
-}
-
-// 3. Instantiate and use the agent
-const model = new OpenRouterAdapter({
-  apiKey: process.env.OPENROUTER_API_KEY!,
-  modelName: 'anthropic/claude-3.5-sonnet',
-});
-const agent = new ContactExtractorAgent(model);
+const schema = z.object({ summary: z.string(), score: z.number() });
 
-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 } = await generateText({
+    model,
+    prompt: 'Analyze this article...',
+    system: createSchemaPrompt(schema), // Injects JSON schema instructions
+});
 
-console.log(contact);
-// Output: { name: 'John Doe', email: 'john.doe@example.com' }
+const result = parseObject(text, schema);
 ```
 
-### 2. Autonomous Agent with a Custom Tool (`AutonomousAgentAdapter`)
+### `parseText` — Sanitize AI-generated text
 
-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.
+Removes invisible characters, normalizes typography, and cleans common AI artifacts.
 
 ```typescript
-import {
-  AutonomousAgentAdapter,
-  ModelPort,
-  OpenRouterAdapter,
-  SafeToolAdapter,
-  SystemPromptAdapter,
-  UserPromptAdapter,
-} from '@jterrazz/intelligence';
-import { z } from 'zod';
+import { parseText } from '@jterrazz/intelligence';
 
-// 1. Define the agent's final output type
-interface WeatherReport {
-  city: string;
-  temperature: number;
-  conditions: string;
-  forecast: 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({
-  name: 'get_weather',
-  description: 'Gets the current weather for a specified 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.
-    if (city.toLowerCase() === 'paris') {
-      return JSON.stringify({
-        city: 'Paris',
-        temperature: 25,
-        conditions: 'sunny',
-        forecast: 'clear skies for the next 24 hours',
-      });
-    }
-    return `Sorry, I don't have weather information for ${city}.`;
-  },
+const clean = parseText(messyAiOutput, {
+    normalizeTypography: true, // Smart quotes → straight quotes
+    removeInvisibleChars: true, // Zero-width chars, etc.
+    trimWhitespace: true,
 });
+```
 
-// 3. Create a specialized agent that uses the tool and has a structured output
-class WeatherAssistantAgent extends AutonomousAgentAdapter<WeatherReport> {
-  constructor(model: ModelPort) {
-    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(
-        'You are a helpful weather assistant.',
-        'You must use the provided tools to get weather information and then respond with a structured JSON object.',
-      ),
-    });
-  }
-}
-
-// 4. Instantiate and use the agent
-const model = new OpenRouterAdapter({
-  apiKey: process.env.OPENROUTER_API_KEY!,
-  modelName: 'anthropic/claude-3.5-sonnet',
-});
-const agent = new WeatherAssistantAgent(model);
+## Provider
+
+### `createOpenRouterProvider` — OpenRouter for AI SDK
 
-const response = await agent.run(new UserPromptAdapter("What's the weather like in Paris?"));
+```typescript
+import { generateText } from 'ai';
+import { createOpenRouterProvider } from '@jterrazz/intelligence';
+
+const provider = createOpenRouterProvider({
+    apiKey: process.env.OPENROUTER_API_KEY,
+});
 
-console.log(response);
-// Output: { city: 'Paris', temperature: 25, conditions: 'sunny', forecast: 'clear skies for the next 24 hours' }
+const { text } = await generateText({
+    model: provider.model('anthropic/claude-sonnet-4-20250514'),
+    prompt: 'Hello!',
+});
 ```
 
-## Development
+With reasoning models:
 
-- **Linting**: `npm run lint`
-- **Testing**: `npm run test`
+```typescript
+const model = provider.model('anthropic/claude-sonnet-4-20250514', {
+    maxTokens: 16000,
+    reasoning: { effort: 'high' },
+});
+```
 
-## Contributing
+## Middleware
 
-Contributions are welcome! Please feel free to open an issue or submit a pull request.
+### `createLoggingMiddleware` — Log AI SDK requests
 
----
+```typescript
+import { wrapLanguageModel } from 'ai';
+import { createLoggingMiddleware } from '@jterrazz/intelligence';
+
+const model = wrapLanguageModel({
+    model: provider.model('anthropic/claude-sonnet-4-20250514'),
+    middleware: createLoggingMiddleware({
+        logger, // Any logger with debug/error methods
+        verbose: false, // Include full request/response in logs
+    }),
+});
+```
 
 ## License
 
-This project is licensed under the [MIT License](./LICENSE).
+MIT