or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

embedding-models.mderrors.mdimage-models.mdindex.mdjson-utilities.mdlanguage-models.mdmiddleware.mdprovider.mdspeech-models.mdtranscription-models.md
tile.json

index.mddocs/

AI SDK Provider

AI SDK Provider provides a comprehensive TypeScript specification and interface definitions for AI language model providers within the Vercel AI SDK ecosystem. It serves as the foundational contract that enables consistent integration with various AI services by defining standardized interfaces for language models, embedding models, image models, speech models, and transcription models.

Package Information

  • Package Name: @ai-sdk/provider
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @ai-sdk/provider

Core Imports

import {
  LanguageModelV2,
  EmbeddingModelV2,
  ImageModelV2,
  SpeechModelV2,
  TranscriptionModelV2,
  ProviderV2,
  JSONValue,
  JSONSchema7
} from "@ai-sdk/provider";

For CommonJS:

const {
  LanguageModelV2,
  EmbeddingModelV2,
  ImageModelV2,
  SpeechModelV2,
  TranscriptionModelV2,
  ProviderV2,
  JSONValue,
  JSONSchema7
} = require("@ai-sdk/provider");

Basic Usage

import { ProviderV2, LanguageModelV2, LanguageModelV2CallOptions } from "@ai-sdk/provider";

// Implement a custom provider
class CustomProvider implements ProviderV2 {
  languageModel(modelId: string): LanguageModelV2 {
    return new CustomLanguageModel(modelId);
  }
  
  textEmbeddingModel(modelId: string): EmbeddingModelV2<string> {
    return new CustomEmbeddingModel(modelId);
  }
  
  imageModel(modelId: string): ImageModelV2 {
    return new CustomImageModel(modelId);
  }
}

// Implement a language model
class CustomLanguageModel implements LanguageModelV2 {
  specificationVersion = 'v2' as const;
  provider = 'custom';
  modelId: string;
  supportedUrls = {};

  constructor(modelId: string) {
    this.modelId = modelId;
  }

  async doGenerate(options: LanguageModelV2CallOptions) {
    // Implementation here
    return {
      content: [{ type: 'text', text: 'Hello world' }],
      finishReason: 'stop' as const,
      usage: {
        inputTokens: 10,
        outputTokens: 5,
        totalTokens: 15
      }
    };
  }

  async doStream(options: LanguageModelV2CallOptions) {
    // Implementation here
    return {
      stream: new ReadableStream()
    };
  }
}

Architecture

AI SDK Provider is built around several key components:

  • Model Interfaces: Standardized contracts for language, embedding, image, speech, and transcription models
  • Provider Interface: Main entry point for accessing different model types
  • Error System: Comprehensive error handling with specific error types for different failure scenarios
  • Type System: Complete TypeScript definitions for all data structures and interfaces
  • Middleware Support: Pluggable middleware system for language models to add custom behavior
  • Streaming Support: Built-in support for streaming responses with detailed stream part types
  • Tool Integration: Support for function calling and provider-defined tools

Capabilities

Language Models

Core interface for text generation models supporting streaming, tool calling, and structured output generation.

type LanguageModelV2 = {
  specificationVersion: 'v2';
  provider: string;
  modelId: string;
  supportedUrls: PromiseLike<Record<string, RegExp[]>> | Record<string, RegExp[]>;
  doGenerate(options: LanguageModelV2CallOptions): PromiseLike<LanguageModelV2GenerateResult>;
  doStream(options: LanguageModelV2CallOptions): PromiseLike<LanguageModelV2StreamResult>;
};

interface LanguageModelV2GenerateResult {
  content: LanguageModelV2Content[];
  finishReason: LanguageModelV2FinishReason;
  usage: LanguageModelV2Usage;
  providerMetadata?: SharedV2ProviderMetadata;
  request?: { body?: unknown };
  response?: LanguageModelV2ResponseMetadata & { headers?: SharedV2Headers; body?: unknown };
  warnings: LanguageModelV2CallWarning[];
}

interface LanguageModelV2StreamResult {
  stream: ReadableStream<LanguageModelV2StreamPart>;
  request?: { body?: unknown };
  response?: { headers?: SharedV2Headers };
}

Language Models

Embedding Models

Interface for text embedding models that convert text into numerical vectors for similarity and search operations.

type EmbeddingModelV2<VALUE> = {
  specificationVersion: 'v2';
  provider: string;
  modelId: string;
  maxEmbeddingsPerCall: PromiseLike<number | undefined> | number | undefined;
  supportsParallelCalls: PromiseLike<boolean> | boolean;
  doEmbed(options: {
    values: Array<VALUE>;
    abortSignal?: AbortSignal;
    providerOptions?: SharedV2ProviderOptions;
    headers?: Record<string, string | undefined>;
  }): PromiseLike<EmbeddingModelV2Result>;
};

interface EmbeddingModelV2Result {
  embeddings: EmbeddingModelV2Embedding[];
  usage?: { tokens: number };
  providerMetadata?: SharedV2ProviderMetadata;
  response?: { headers?: SharedV2Headers; body?: unknown };
}

type EmbeddingModelV2Embedding = Array<number>;

Embedding Models

Image Models

Interface for image generation models that create images from text prompts.

type ImageModelV2 = {
  specificationVersion: 'v2';
  provider: string;
  modelId: string;
  maxImagesPerCall: number | undefined | GetMaxImagesPerCallFunction;
  doGenerate(options: ImageModelV2CallOptions): PromiseLike<ImageModelV2Result>;
};

interface ImageModelV2Result {
  images: Array<string> | Array<Uint8Array>;
  warnings: ImageModelV2CallWarning[];
  providerMetadata?: ImageModelV2ProviderMetadata;
  response: { timestamp: Date; modelId: string; headers: Record<string, string> | undefined };
}

Image Models

Speech Models

Interface for text-to-speech models that convert text into spoken audio.

type SpeechModelV2 = {
  specificationVersion: 'v2';
  provider: string;
  modelId: string;
  doGenerate(options: SpeechModelV2CallOptions): PromiseLike<SpeechModelV2Result>;
};

interface SpeechModelV2Result {
  audio: string | Uint8Array;
  warnings: SpeechModelV2CallWarning[];
  request?: { body?: unknown };
  response: { timestamp: Date; modelId: string; headers?: SharedV2Headers; body?: unknown };
  providerMetadata?: Record<string, Record<string, JSONValue>>;
}

Speech Models

Transcription Models

Interface for speech-to-text models that convert audio into text transcriptions.

type TranscriptionModelV2 = {
  specificationVersion: 'v2';
  provider: string;
  modelId: string;
  doGenerate(options: TranscriptionModelV2CallOptions): PromiseLike<TranscriptionModelV2Result>;
};

interface TranscriptionModelV2Result {
  text: string;
  segments: Array<{
    text: string;
    startSecond: number;
    endSecond: number;
  }>;
  language: string | undefined;
  durationInSeconds: number | undefined;
  warnings: TranscriptionModelV2CallWarning[];
  request?: { body?: string };
  response: { timestamp: Date; modelId: string; headers?: SharedV2Headers; body?: unknown };
  providerMetadata?: Record<string, Record<string, JSONValue>>;
}

Transcription Models

Provider Interface

Main provider interface for accessing all model types in a unified way.

interface ProviderV2 {
  languageModel(modelId: string): LanguageModelV2;
  textEmbeddingModel(modelId: string): EmbeddingModelV2<string>;
  imageModel(modelId: string): ImageModelV2;
  transcriptionModel?(modelId: string): TranscriptionModelV2;
  speechModel?(modelId: string): SpeechModelV2;
}

Provider Interface

Error Handling

Comprehensive error system with specific error types for different failure scenarios, all extending the base AISDKError class.

class AISDKError extends Error {
  readonly cause?: unknown;
  
  constructor({ name, message, cause }: { name: string; message: string; cause?: unknown });
  static isInstance(error: unknown): error is AISDKError;
}

class APICallError extends AISDKError {
  readonly url: string;
  readonly requestBodyValues: unknown;
  readonly statusCode?: number;
  readonly responseHeaders?: Record<string, string>;
  readonly responseBody?: string;
  readonly isRetryable: boolean;
  readonly data?: unknown;
}

class NoSuchModelError extends AISDKError {
  readonly modelId: string;
  readonly modelType: 'languageModel' | 'textEmbeddingModel' | 'imageModel' | 'transcriptionModel' | 'speechModel';
}

Error Handling

JSON Utilities

Type-safe JSON handling utilities for working with structured data.

type JSONValue = null | string | number | boolean | JSONObject | JSONArray;
type JSONObject = { [key: string]: JSONValue };
type JSONArray = JSONValue[];

function isJSONValue(value: unknown): value is JSONValue;
function isJSONArray(value: unknown): value is JSONArray;
function isJSONObject(value: unknown): value is JSONObject;

JSON Utilities

Middleware System

Pluggable middleware system for language models to add custom behavior like logging, caching, or request modification.

interface LanguageModelV2Middleware {
  middlewareVersion?: 'v2' | undefined;
  overrideProvider?: (options: { model: LanguageModelV2 }) => string;
  overrideModelId?: (options: { model: LanguageModelV2 }) => string;
  transformParams?: (options: {
    type: 'generate' | 'stream';
    params: LanguageModelV2CallOptions;
    model: LanguageModelV2;
  }) => PromiseLike<LanguageModelV2CallOptions>;
  wrapGenerate?: (options: {
    doGenerate: () => ReturnType<LanguageModelV2['doGenerate']>;
    doStream: () => ReturnType<LanguageModelV2['doStream']>;
    params: LanguageModelV2CallOptions;
    model: LanguageModelV2;
  }) => Promise<Awaited<ReturnType<LanguageModelV2['doGenerate']>>>;
  wrapStream?: (options: {
    doGenerate: () => ReturnType<LanguageModelV2['doGenerate']>;
    doStream: () => ReturnType<LanguageModelV2['doStream']>;
    params: LanguageModelV2CallOptions;
    model: LanguageModelV2;
  }) => PromiseLike<Awaited<ReturnType<LanguageModelV2['doStream']>>>;
}

Middleware

Shared Types

Core Shared Types

type SharedV2Headers = Record<string, string>;
type SharedV2ProviderMetadata = Record<string, Record<string, JSONValue>>;
type SharedV2ProviderOptions = Record<string, Record<string, JSONValue>>;

External JSON Schema Types

Re-exported from the json-schema library for convenience:

// From json-schema package
type JSONSchema7 = { ... }; // Complete JSON Schema Draft 7 specification
type JSONSchema7Definition = JSONSchema7 | boolean;