@jterrazz/intelligence

Lightweight, composable utilities for AI SDK apps - middleware for logging and observability, structured output parsing, result handling, and provider helpers.

Installation

npm install @jterrazz/intelligence ai zod

Generation

generateStructured - Type-safe structured generation with error handling

Combines generateText + parseObject + error classification into a single function that returns a discriminated union result.

import { generateStructured, withObservability } from "@jterrazz/intelligence";
import { z } from "zod";

const schema = z.object({
  sentiment: z.string(),
  score: z.number(),
});

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);
}

Result Utilities

Discriminated union result type for explicit error handling.

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.
}

Middleware

Composable middlewares that wrap AI SDK models. Stack them together for logging, observability, and more.

Composing Middlewares

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(),
    }),
  ],
});

Logging Middleware

Logs AI SDK requests with timing, usage, and optional content.

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.)

Observability Middleware

Sends generation data to observability platforms (Langfuse, etc.).

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 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" },
  }),
});

Custom Adapters

Implement ports to integrate with any platform:

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: { ... } };
  }
}

Parsing Utilities

parseObject - Extract structured data from AI responses

Extracts and validates JSON from messy AI outputs (markdown blocks, malformed syntax).

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.

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,
  prompt: "Analyze this article...",
  system: createSchemaPrompt(schema),
});

const result = parseObject(text, schema);

parseText - Sanitize AI-generated text

Removes invisible characters, normalizes typography, cleans AI artifacts.

import { parseText } from "@jterrazz/intelligence";

const clean = parseText(messyAiOutput);
// Removes: BOM, zero-width chars, citation markers
// Normalizes: smart quotes, em dashes, ellipsis

Provider

createOpenRouterProvider - OpenRouter for AI SDK

import { generateText } from "ai";
import { createOpenRouterProvider } from "@jterrazz/intelligence";

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" },
});

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 |