@posthog/ai

Provides a unified JavaScript/TypeScript API that abstracts over multiple LLM providers (OpenAI, Anthropic, Google Gemini) by normalizing their different request/response schemas into a common interface. Internally maps provider-specific parameters (temperature, max_tokens, stop sequences) to each provider's native format, eliminating the need for developers to write conditional logic for each provider.

Automatically captures and sends LLM interaction events (prompts, completions, token usage, latency, errors) to PostHog analytics backend for observability and debugging. Hooks into the LLM call lifecycle to extract structured event data without requiring manual instrumentation, enabling teams to track AI feature adoption, cost, and performance in production.

Provides a templating system for prompts with variable interpolation, type validation, and automatic escaping to prevent prompt injection. Supports Handlebars-style syntax for conditionals and loops, validates that all required variables are provided before sending to LLM, and logs template variables for debugging.

Enables LLM responses to be constrained to a JSON schema (via provider-native features like OpenAI's JSON mode or Anthropic's tool_use) and automatically parses/validates the output against the schema. Handles provider differences in schema enforcement (some providers support JSON Schema directly, others use tool definitions) and provides fallback parsing for providers without native support.

Provides a declarative schema-based registry for defining tools/functions that LLMs can invoke, automatically converting tool definitions to each provider's native format (OpenAI function calling, Anthropic tool_use, Google function calling). Handles tool execution, result formatting, and multi-turn agentic loops where the LLM can iteratively call tools and refine responses.

Manages conversation history and automatically handles context window constraints by implementing sliding window or summarization strategies. Tracks token counts per message, calculates remaining context budget, and can automatically trim or summarize older messages to fit within provider token limits while preserving conversation coherence.

Provides an event-based streaming API that normalizes streaming responses across different LLM providers, emitting events for token chunks, completion status, and errors. Internally handles provider-specific streaming protocols (Server-Sent Events for OpenAI, different formats for Anthropic) and buffers partial tokens to emit complete words/sentences rather than individual tokens.

Automatically calculates and tracks LLM API costs by multiplying token counts (input/output) by provider-specific pricing rates. Maintains cost aggregations by model, provider, and time period, and integrates with PostHog analytics for cost dashboards. Supports custom pricing configurations for fine-tuned models or enterprise pricing agreements.

Implements provider-aware error handling that distinguishes between retryable errors (rate limits, temporary outages) and non-retryable errors (authentication failures, invalid requests). Applies exponential backoff with jitter for retryable errors, respects provider-specific retry-after headers, and provides detailed error context for debugging.

Generates type-safe LLM client code from TypeScript interfaces, ensuring that LLM calls and responses are type-checked at compile time. Converts TypeScript types to JSON Schema for structured output validation, and generates wrapper functions with proper typing for tool definitions and message handling.

Enables runtime model selection and automatic fallback to alternative providers/models if the primary choice fails or is unavailable. Supports cost-based model selection (choosing cheaper models for non-critical requests) and performance-based selection (choosing faster models for latency-sensitive operations).