@jterrazz/intelligence 3.0.2 → 4.0.0

package/README.md

@@ -1,6 +1,6 @@
 # @jterrazz/intelligence
 
-Lightweight utilities for AI SDK apps — structured output parsing, text sanitization, and provider helpers.
+Lightweight, composable utilities for AI SDK apps - middleware for logging and observability, structured output parsing, result handling, and provider helpers.
 
 ## Installation
 
@@ -8,112 +8,309 @@ Lightweight utilities for AI SDK apps — structured output parsing, text saniti
 npm install @jterrazz/intelligence ai zod
 ```
 
-## Parsing Utilities
+## Generation
 
-### `parseObject` — Extract structured data from AI responses
+### `generateStructured` - Type-safe structured generation with error handling
 
-Extracts and validates JSON from messy AI outputs (markdown blocks, embedded JSON, malformed syntax).
+Combines `generateText` + `parseObject` + error classification into a single function that returns a discriminated union result.
 
 ```typescript
-import { parseObject } from '@jterrazz/intelligence';
-import { z } from 'zod';
+import { generateStructured, withObservability } from "@jterrazz/intelligence";
+import { z } from "zod";
 
 const schema = z.object({
-    title: z.string(),
-    tags: z.array(z.string()),
+  sentiment: z.string(),
+  score: z.number(),
 });
 
-// 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'] }
+const result = await generateStructured({
+  model,
+  prompt: "Analyze this article...",
+  schema,
+  providerOptions: withObservability({ traceId: "trace-123" }),
+});
+
+if (result.success) {
+  console.log(result.data.sentiment, result.data.score);
+} else {
+  // Typed error with code: TIMEOUT | RATE_LIMITED | PARSING_FAILED | etc.
+  console.error(result.error.code, result.error.message);
+}
 ```
 
-### `createSchemaPrompt` — Generate schema instructions for prompts
+## Result Utilities
 
-Creates system prompt instructions for models that don't support native structured outputs.
+Discriminated union result type for explicit error handling.
 
 ```typescript
-import { generateText } from 'ai';
-import { createSchemaPrompt, parseObject } from '@jterrazz/intelligence';
-import { z } from 'zod';
+import {
+  generationSuccess,
+  generationFailure,
+  isSuccess,
+  isFailure,
+  unwrap,
+  unwrapOr,
+  classifyError,
+  type GenerationResult,
+} from "@jterrazz/intelligence";
+
+// Create results
+const success = generationSuccess({ data: "value" });
+const failure = generationFailure("TIMEOUT", "Request timed out");
+
+// Type guards
+if (isSuccess(result)) {
+  console.log(result.data);
+}
+
+// Unwrap with default
+const value = unwrapOr(result, defaultValue);
+
+// Classify errors automatically
+try {
+  await someOperation();
+} catch (error) {
+  const code = classifyError(error); // TIMEOUT, RATE_LIMITED, PARSING_FAILED, etc.
+}
+```
 
-const schema = z.object({ summary: z.string(), score: z.number() });
+## Middleware
 
-const { text } = await generateText({
-    model,
-    prompt: 'Analyze this article...',
-    system: createSchemaPrompt(schema), // Injects JSON schema instructions
+Composable middlewares that wrap AI SDK models. Stack them together for logging, observability, and more.
+
+### Composing Middlewares
+
+```typescript
+import { wrapLanguageModel } from "ai";
+import {
+  createLoggingMiddleware,
+  createObservabilityMiddleware,
+  LangfuseAdapter,
+  OpenRouterMetadataAdapter,
+} from "@jterrazz/intelligence";
+
+const model = wrapLanguageModel({
+  model: provider.model("anthropic/claude-sonnet-4-20250514"),
+  middleware: [
+    createLoggingMiddleware({ logger, include: { usage: true } }),
+    createObservabilityMiddleware({
+      observability: new LangfuseAdapter({
+        secretKey: process.env.LANGFUSE_SECRET_KEY,
+        publicKey: process.env.LANGFUSE_PUBLIC_KEY,
+      }),
+      providerMetadata: new OpenRouterMetadataAdapter(),
+    }),
+  ],
 });
+```
 
-const result = parseObject(text, schema);
+### Logging Middleware
+
+Logs AI SDK requests with timing, usage, and optional content.
+
+```typescript
+import { wrapLanguageModel, generateText } from "ai";
+import { createLoggingMiddleware } from "@jterrazz/intelligence";
+
+const model = wrapLanguageModel({
+  model: provider.model("anthropic/claude-sonnet-4-20250514"),
+  middleware: createLoggingMiddleware({
+    logger,
+    include: {
+      params: false,  // Log request params
+      content: false, // Log response content
+      usage: true,    // Log token usage (default: true)
+    },
+  }),
+});
+
+await generateText({ model, prompt: "Hello!" });
+// Logs: ai.generate.start, ai.generate.complete (with durationMs, usage, etc.)
 ```
 
-### `parseText` — Sanitize AI-generated text
+### Observability Middleware
 
-Removes invisible characters, normalizes typography, and cleans common AI artifacts.
+Sends generation data to observability platforms (Langfuse, etc.).
 
 ```typescript
-import { parseText } from '@jterrazz/intelligence';
+import { wrapLanguageModel, generateText } from "ai";
+import {
+  createObservabilityMiddleware,
+  withObservability,
+  LangfuseAdapter,
+} from "@jterrazz/intelligence";
+
+const observability = new LangfuseAdapter({
+  secretKey: process.env.LANGFUSE_SECRET_KEY,
+  publicKey: process.env.LANGFUSE_PUBLIC_KEY,
+});
 
-const clean = parseText(messyAiOutput);
-// Removes: BOM, zero-width chars, AI citation markers
-// Normalizes: smart quotes → straight, em dashes → ", ", ellipsis → ...
-// Collapses multiple spaces and trims
-
-// Options
-parseText(text, {
-    normalizeEmDashesToCommas: true, // Convert em/en dashes to ", " (default: true)
-    collapseSpaces: true, // Collapse multiple spaces, trim (default: true)
+const model = wrapLanguageModel({
+  model: provider.model("anthropic/claude-sonnet-4-20250514"),
+  middleware: createObservabilityMiddleware({ observability }),
+});
+
+// Use withObservability() helper for type-safe metadata
+await generateText({
+  model,
+  prompt: "Analyze this...",
+  providerOptions: withObservability({
+    traceId: "trace-123",
+    name: "analyzer",
+    metadata: { userId: "user-1" },
+  }),
 });
 ```
 
-## Provider
+### Custom Adapters
 
-### `createOpenRouterProvider` — OpenRouter for AI SDK
+Implement ports to integrate with any platform:
 
 ```typescript
-import { generateText } from 'ai';
-import { createOpenRouterProvider } from '@jterrazz/intelligence';
+import type { ObservabilityPort, ProviderMetadataPort } from "@jterrazz/intelligence";
+
+// Observability adapter (Datadog, etc.)
+class DatadogAdapter implements ObservabilityPort {
+  trace(params) { /* ... */ }
+  generation(params) { /* ... */ }
+  async flush() { /* ... */ }
+  async shutdown() { /* ... */ }
+}
+
+// Provider metadata adapter (extract usage/cost)
+class AnthropicMetadataAdapter implements ProviderMetadataPort {
+  extract(metadata) {
+    return { usage: { ... }, cost: { ... } };
+  }
+}
+```
 
-const provider = createOpenRouterProvider({
-    apiKey: process.env.OPENROUTER_API_KEY,
+## Parsing Utilities
+
+### `parseObject` - Extract structured data from AI responses
+
+Extracts and validates JSON from messy AI outputs (markdown blocks, malformed syntax).
+
+````typescript
+import { parseObject } from "@jterrazz/intelligence";
+import { z } from "zod";
+
+const schema = z.object({
+  title: z.string(),
+  tags: z.array(z.string()),
 });
 
+const text = '```json\n{"title": "Hello", "tags": ["ai"]}\n```';
+const result = parseObject(text, schema);
+// { title: "Hello", tags: ["ai"] }
+````
+
+### `createSchemaPrompt` - Generate schema instructions
+
+Creates system prompt instructions for models without native structured output.
+
+```typescript
+import { generateText } from "ai";
+import { createSchemaPrompt, parseObject } from "@jterrazz/intelligence";
+import { z } from "zod";
+
+const schema = z.object({ summary: z.string(), score: z.number() });
+
 const { text } = await generateText({
-    model: provider.model('anthropic/claude-sonnet-4-20250514'),
-    prompt: 'Hello!',
+  model,
+  prompt: "Analyze this article...",
+  system: createSchemaPrompt(schema),
 });
+
+const result = parseObject(text, schema);
 ```
 
-With reasoning models:
+### `parseText` - Sanitize AI-generated text
+
+Removes invisible characters, normalizes typography, cleans AI artifacts.
 
 ```typescript
-const model = provider.model('anthropic/claude-sonnet-4-20250514', {
-    maxTokens: 16000,
-    reasoning: { effort: 'high' },
-});
+import { parseText } from "@jterrazz/intelligence";
+
+const clean = parseText(messyAiOutput);
+// Removes: BOM, zero-width chars, citation markers
+// Normalizes: smart quotes, em dashes, ellipsis
 ```
 
-## Middleware
+## Provider
 
-### `createLoggingMiddleware` — Log AI SDK requests
+### `createOpenRouterProvider` - OpenRouter for AI SDK
 
 ```typescript
-import { wrapLanguageModel } from 'ai';
-import { createLoggingMiddleware } from '@jterrazz/intelligence';
+import { generateText } from "ai";
+import { createOpenRouterProvider } from "@jterrazz/intelligence";
 
-const model = wrapLanguageModel({
-    model: provider.model('anthropic/claude-sonnet-4-20250514'),
-    middleware: createLoggingMiddleware({
-        logger, // Any logger with debug/error methods
-        include: {
-            params: false, // Include request params (default: false)
-            content: false, // Include response content (default: false)
-            usage: true, // Include token usage (default: true)
-        },
-    }),
+const provider = createOpenRouterProvider({
+  apiKey: process.env.OPENROUTER_API_KEY,
+});
+
+const { text } = await generateText({
+  model: provider.model("anthropic/claude-sonnet-4-20250514"),
+  prompt: "Hello!",
+});
+
+// With reasoning models
+const reasoningModel = provider.model("anthropic/claude-sonnet-4-20250514", {
+  maxTokens: 16000,
+  reasoning: { effort: "high" },
 });
 ```
 
-Happy coding! 🚀
+## API Reference
+
+### Generation
+
+| Export                        | Description                                            |
+| ----------------------------- | ------------------------------------------------------ |
+| `generateStructured(options)` | Generate and parse structured data with error handling |
+
+### Result
+
+| Export                                     | Description                                              |
+| ------------------------------------------ | -------------------------------------------------------- |
+| `GenerationResult<T>`                      | Discriminated union result type                          |
+| `generationSuccess(data)`                  | Create success result                                    |
+| `generationFailure(code, message, cause?)` | Create failure result                                    |
+| `isSuccess(result)`                        | Type guard for success                                   |
+| `isFailure(result)`                        | Type guard for failure                                   |
+| `unwrap(result)`                           | Extract data or throw                                    |
+| `unwrapOr(result, default)`                | Extract data or return default                           |
+| `classifyError(error)`                     | Classify error into error code                           |
+| `GenerationErrorCode`                      | Error codes: TIMEOUT, RATE_LIMITED, PARSING_FAILED, etc. |
+
+### Middleware
+
+| Export                                   | Description                                  |
+| ---------------------------------------- | -------------------------------------------- |
+| `createLoggingMiddleware(options)`       | Creates logging middleware                   |
+| `createObservabilityMiddleware(options)` | Creates observability middleware             |
+| `withObservability(meta)`                | Helper for type-safe observability metadata  |
+| `LangfuseAdapter`                        | Langfuse implementation of ObservabilityPort |
+| `NoopObservabilityAdapter`               | No-op adapter for testing/development        |
+| `OpenRouterMetadataAdapter`              | Extract usage/cost from OpenRouter           |
+
+### Ports
+
+| Export                 | Description                                |
+| ---------------------- | ------------------------------------------ |
+| `ObservabilityPort`    | Interface for observability adapters       |
+| `ProviderMetadataPort` | Interface for provider metadata extraction |
+
+### Parsing
+
+| Export                       | Description                              |
+| ---------------------------- | ---------------------------------------- |
+| `parseObject(text, schema)`  | Parse and validate JSON from AI output   |
+| `createSchemaPrompt(schema)` | Generate schema instructions for prompts |
+| `parseText(text, options?)`  | Sanitize AI-generated text               |
+
+### Provider
+
+| Export                             | Description                           |
+| ---------------------------------- | ------------------------------------- |
+| `createOpenRouterProvider(config)` | Create OpenRouter provider for AI SDK |