@providerprotocol/ai 0.0.1

package/src/types/content.ts

@@ -0,0 +1,133 @@
+/**
+ * Content block types for messages
+ */
+
+/**
+ * Image source types
+ */
+export type ImageSource =
+  | { type: 'base64'; data: string }
+  | { type: 'url'; url: string }
+  | { type: 'bytes'; data: Uint8Array };
+
+/**
+ * Text content block
+ */
+export interface TextBlock {
+  type: 'text';
+  text: string;
+}
+
+/**
+ * Image content block
+ */
+export interface ImageBlock {
+  type: 'image';
+  source: ImageSource;
+  mimeType: string;
+  width?: number;
+  height?: number;
+}
+
+/**
+ * Audio content block
+ */
+export interface AudioBlock {
+  type: 'audio';
+  data: Uint8Array;
+  mimeType: string;
+  duration?: number;
+}
+
+/**
+ * Video content block
+ */
+export interface VideoBlock {
+  type: 'video';
+  data: Uint8Array;
+  mimeType: string;
+  duration?: number;
+  width?: number;
+  height?: number;
+}
+
+/**
+ * Binary content block for arbitrary data
+ */
+export interface BinaryBlock {
+  type: 'binary';
+  data: Uint8Array;
+  mimeType: string;
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * All content block types
+ */
+export type ContentBlock =
+  | TextBlock
+  | ImageBlock
+  | AudioBlock
+  | VideoBlock
+  | BinaryBlock;
+
+/**
+ * Content types allowed in user messages
+ */
+export type UserContent =
+  | TextBlock
+  | ImageBlock
+  | AudioBlock
+  | VideoBlock
+  | BinaryBlock;
+
+/**
+ * Content types allowed in assistant messages
+ */
+export type AssistantContent =
+  | TextBlock
+  | ImageBlock
+  | AudioBlock
+  | VideoBlock;
+
+/**
+ * Helper to create a text block
+ */
+export function text(content: string): TextBlock {
+  return { type: 'text', text: content };
+}
+
+/**
+ * Type guard for TextBlock
+ */
+export function isTextBlock(block: ContentBlock): block is TextBlock {
+  return block.type === 'text';
+}
+
+/**
+ * Type guard for ImageBlock
+ */
+export function isImageBlock(block: ContentBlock): block is ImageBlock {
+  return block.type === 'image';
+}
+
+/**
+ * Type guard for AudioBlock
+ */
+export function isAudioBlock(block: ContentBlock): block is AudioBlock {
+  return block.type === 'audio';
+}
+
+/**
+ * Type guard for VideoBlock
+ */
+export function isVideoBlock(block: ContentBlock): block is VideoBlock {
+  return block.type === 'video';
+}
+
+/**
+ * Type guard for BinaryBlock
+ */
+export function isBinaryBlock(block: ContentBlock): block is BinaryBlock {
+  return block.type === 'binary';
+}

package/src/types/errors.ts

@@ -0,0 +1,85 @@
+/**
+ * UPP Error Codes
+ * Normalized error codes for cross-provider error handling
+ */
+export type ErrorCode =
+  | 'AUTHENTICATION_FAILED'
+  | 'RATE_LIMITED'
+  | 'CONTEXT_LENGTH_EXCEEDED'
+  | 'MODEL_NOT_FOUND'
+  | 'INVALID_REQUEST'
+  | 'INVALID_RESPONSE'
+  | 'CONTENT_FILTERED'
+  | 'QUOTA_EXCEEDED'
+  | 'PROVIDER_ERROR'
+  | 'NETWORK_ERROR'
+  | 'TIMEOUT'
+  | 'CANCELLED';
+
+/**
+ * Modality types supported by UPP
+ */
+export type Modality = 'llm' | 'embedding' | 'image' | 'audio' | 'video';
+
+/**
+ * Unified Provider Protocol Error
+ * All provider errors are normalized to this type
+ */
+export class UPPError extends Error {
+  readonly code: ErrorCode;
+  readonly provider: string;
+  readonly modality: Modality;
+  readonly statusCode?: number;
+  override readonly cause?: Error;
+
+  override readonly name = 'UPPError';
+
+  constructor(
+    message: string,
+    code: ErrorCode,
+    provider: string,
+    modality: Modality,
+    statusCode?: number,
+    cause?: Error
+  ) {
+    super(message);
+    this.code = code;
+    this.provider = provider;
+    this.modality = modality;
+    this.statusCode = statusCode;
+    this.cause = cause;
+
+    // Maintain proper stack trace in V8 environments
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, UPPError);
+    }
+  }
+
+  /**
+   * Create a string representation of the error
+   */
+  override toString(): string {
+    let str = `UPPError [${this.code}]: ${this.message}`;
+    str += ` (provider: ${this.provider}, modality: ${this.modality}`;
+    if (this.statusCode) {
+      str += `, status: ${this.statusCode}`;
+    }
+    str += ')';
+    return str;
+  }
+
+  /**
+   * Convert to JSON for serialization
+   */
+  toJSON(): Record<string, unknown> {
+    return {
+      name: this.name,
+      message: this.message,
+      code: this.code,
+      provider: this.provider,
+      modality: this.modality,
+      statusCode: this.statusCode,
+      cause: this.cause?.message,
+    };
+  }
+}

package/src/types/index.ts

@@ -0,0 +1,105 @@
+// Error types
+export { UPPError, type ErrorCode, type Modality } from './errors.ts';
+
+// Schema types
+export type {
+  JSONSchema,
+  JSONSchemaProperty,
+  JSONSchemaPropertyType,
+} from './schema.ts';
+
+// Content block types
+export type {
+  ContentBlock,
+  TextBlock,
+  ImageBlock,
+  AudioBlock,
+  VideoBlock,
+  BinaryBlock,
+  ImageSource,
+  UserContent,
+  AssistantContent,
+} from './content.ts';
+export {
+  text,
+  isTextBlock,
+  isImageBlock,
+  isAudioBlock,
+  isVideoBlock,
+  isBinaryBlock,
+} from './content.ts';
+
+// Tool types
+export type {
+  Tool,
+  ToolCall,
+  ToolResult,
+  ToolUseStrategy,
+  ToolExecution,
+} from './tool.ts';
+
+// Message types
+export {
+  Message,
+  UserMessage,
+  AssistantMessage,
+  ToolResultMessage,
+  isUserMessage,
+  isAssistantMessage,
+  isToolResultMessage,
+} from './messages.ts';
+export type { MessageType, MessageMetadata, MessageOptions } from './messages.ts';
+
+// Turn types
+export type { Turn, TokenUsage } from './turn.ts';
+export { createTurn, emptyUsage, aggregateUsage } from './turn.ts';
+
+// Thread types
+export { Thread } from './thread.ts';
+export type { ThreadJSON, MessageJSON } from './thread.ts';
+
+// Stream types
+export type {
+  StreamEvent,
+  StreamEventType,
+  EventDelta,
+  StreamResult,
+} from './stream.ts';
+export {
+  createStreamResult,
+  textDelta,
+  toolCallDelta,
+  messageStart,
+  messageStop,
+  contentBlockStart,
+  contentBlockStop,
+} from './stream.ts';
+
+// Provider types
+export type {
+  Provider,
+  ModelReference,
+  ProviderConfig,
+  KeyStrategy,
+  RetryStrategy,
+  LLMProvider,
+  EmbeddingProvider,
+  ImageProvider,
+  EmbeddingHandler,
+  ImageHandler,
+  BoundEmbeddingModel,
+  BoundImageModel,
+} from './provider.ts';
+
+// LLM types
+export type {
+  LLMOptions,
+  LLMInstance,
+  LLMCapabilities,
+  LLMRequest,
+  LLMResponse,
+  LLMStreamResult,
+  BoundLLMModel,
+  LLMHandler,
+  InferenceInput,
+} from './llm.ts';

package/src/types/llm.ts

@@ -0,0 +1,211 @@
+import type { Message, AssistantMessage } from './messages.ts';
+import type { ContentBlock } from './content.ts';
+import type { Tool, ToolUseStrategy } from './tool.ts';
+import type { JSONSchema } from './schema.ts';
+import type { Turn, TokenUsage } from './turn.ts';
+import type { StreamEvent, StreamResult } from './stream.ts';
+import type {
+  ModelReference,
+  ProviderConfig,
+  LLMProvider,
+} from './provider.ts';
+import type { Thread } from './thread.ts';
+
+/**
+ * LLMCapabilities declares what the provider's API supports, not individual model capabilities.
+ * If a user attempts to use a feature with a model that doesn't support it,
+ * the provider's API will return an error—this is expected behavior.
+ *
+ * Capabilities are static - they are constant for the lifetime of the provider instance
+ * and do not vary per-request or per-model.
+ */
+export interface LLMCapabilities {
+  /** Provider API supports streaming responses */
+  streaming: boolean;
+
+  /** Provider API supports tool/function calling */
+  tools: boolean;
+
+  /** Provider API supports native structured output (JSON schema) */
+  structuredOutput: boolean;
+
+  /** Provider API supports image input */
+  imageInput: boolean;
+
+  /** Provider API supports video input */
+  videoInput: boolean;
+
+  /** Provider API supports audio input */
+  audioInput: boolean;
+}
+
+/**
+ * Input types for inference
+ */
+export type InferenceInput = string | Message | ContentBlock;
+
+/**
+ * Options for llm() function
+ */
+export interface LLMOptions<TParams = unknown> {
+  /** A model reference from a provider factory */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  model: ModelReference<any>;
+
+  /** Provider infrastructure configuration (optional - uses env vars if omitted) */
+  config?: ProviderConfig;
+
+  /** Model-specific parameters (temperature, max_tokens, etc.) */
+  params?: TParams;
+
+  /** System prompt for all inferences */
+  system?: string;
+
+  /** Tools available to the model */
+  tools?: Tool[];
+
+  /** Tool execution strategy */
+  toolStrategy?: ToolUseStrategy;
+
+  /** Structured output schema (JSON Schema) */
+  structure?: JSONSchema;
+}
+
+/**
+ * LLM instance returned by llm()
+ */
+export interface LLMInstance<TParams = unknown> {
+  /**
+   * Execute inference and return complete Turn
+   *
+   * @overload No history - single input
+   * generate(input: InferenceInput): Promise<Turn>
+   *
+   * @overload No history - multiple inputs
+   * generate(...inputs: InferenceInput[]): Promise<Turn>
+   *
+   * @overload With history
+   * generate(history: Message[] | Thread, ...inputs: InferenceInput[]): Promise<Turn>
+   */
+  generate(
+    historyOrInput: Message[] | Thread | InferenceInput,
+    ...input: InferenceInput[]
+  ): Promise<Turn>;
+
+  /**
+   * Execute streaming inference
+   *
+   * @overload No history - single input
+   * stream(input: InferenceInput): StreamResult
+   *
+   * @overload No history - multiple inputs
+   * stream(...inputs: InferenceInput[]): StreamResult
+   *
+   * @overload With history
+   * stream(history: Message[] | Thread, ...inputs: InferenceInput[]): StreamResult
+   */
+  stream(
+    historyOrInput: Message[] | Thread | InferenceInput,
+    ...input: InferenceInput[]
+  ): StreamResult;
+
+  /** The bound model */
+  readonly model: BoundLLMModel<TParams>;
+
+  /** Current system prompt */
+  readonly system: string | undefined;
+
+  /** Current parameters */
+  readonly params: TParams | undefined;
+
+  /** Provider API capabilities */
+  readonly capabilities: LLMCapabilities;
+}
+
+/**
+ * Request passed from llm() core to providers
+ * Note: config is required here because llm() core resolves defaults
+ * before passing to providers
+ */
+export interface LLMRequest<TParams = unknown> {
+  /** All messages for this request (history + new input) */
+  messages: Message[];
+
+  /** System prompt */
+  system?: string;
+
+  /** Model-specific parameters (passed through unchanged) */
+  params?: TParams;
+
+  /** Tools available for this request */
+  tools?: Tool[];
+
+  /** Structured output schema (if requested) */
+  structure?: JSONSchema;
+
+  /** Provider infrastructure config (resolved by llm() core) */
+  config: ProviderConfig;
+
+  /** Abort signal for cancellation */
+  signal?: AbortSignal;
+}
+
+/**
+ * Raw provider response (single cycle, no tool loop)
+ */
+export interface LLMResponse {
+  message: AssistantMessage;
+  usage: TokenUsage;
+  stopReason: string;
+
+  /**
+   * Structured output data extracted by the provider.
+   * Present when a structure schema was requested and the provider
+   * successfully extracted the data (via tool call or native JSON mode).
+   * Providers handle their own extraction logic - core just uses this value.
+   */
+  data?: unknown;
+}
+
+/**
+ * Raw provider stream result
+ */
+export interface LLMStreamResult extends AsyncIterable<StreamEvent> {
+  readonly response: Promise<LLMResponse>;
+}
+
+/**
+ * Bound LLM model - full definition
+ */
+export interface BoundLLMModel<TParams = unknown> {
+  /** The model identifier */
+  readonly modelId: string;
+
+  /** Reference to the parent provider */
+  readonly provider: LLMProvider<TParams>;
+
+  /** Provider API capabilities */
+  readonly capabilities: LLMCapabilities;
+
+  /** Execute a single non-streaming inference request */
+  complete(request: LLMRequest<TParams>): Promise<LLMResponse>;
+
+  /** Execute a single streaming inference request */
+  stream(request: LLMRequest<TParams>): LLMStreamResult;
+}
+
+/**
+ * LLM Handler for providers
+ */
+export interface LLMHandler<TParams = unknown> {
+  /** Bind model ID to create executable model */
+  bind(modelId: string): BoundLLMModel<TParams>;
+
+  /**
+   * Internal: Set the parent provider reference.
+   * Called by createProvider() after the provider is constructed.
+   * This allows bind() to return models with the correct provider reference.
+   * @internal
+   */
+  _setProvider?(provider: LLMProvider<TParams>): void;
+}

package/src/types/messages.ts

@@ -0,0 +1,182 @@
+import { generateId } from '../utils/id.ts';
+import type {
+  ContentBlock,
+  TextBlock,
+  UserContent,
+  AssistantContent,
+  isTextBlock,
+} from './content.ts';
+import type { ToolCall, ToolResult } from './tool.ts';
+
+/**
+ * Message type discriminator
+ */
+export type MessageType = 'user' | 'assistant' | 'tool_result';
+
+/**
+ * Provider-namespaced metadata
+ * Each provider uses its own namespace
+ */
+export interface MessageMetadata {
+  [provider: string]: Record<string, unknown> | undefined;
+}
+
+/**
+ * Options for message construction
+ */
+export interface MessageOptions {
+  id?: string;
+  metadata?: MessageMetadata;
+}
+
+/**
+ * Base message class
+ * All messages inherit from this
+ */
+export abstract class Message {
+  /** Unique message identifier */
+  readonly id: string;
+
+  /** Timestamp */
+  readonly timestamp: Date;
+
+  /** Provider-specific metadata, namespaced by provider */
+  readonly metadata?: MessageMetadata;
+
+  /** Message type discriminator */
+  abstract readonly type: MessageType;
+
+  /** Raw content - implemented by subclasses */
+  protected abstract getContent(): ContentBlock[];
+
+  constructor(options?: MessageOptions) {
+    this.id = options?.id ?? generateId();
+    this.timestamp = new Date();
+    this.metadata = options?.metadata;
+  }
+
+  /**
+   * Convenience accessor for text content
+   * Concatenates all text blocks with '\n\n'
+   */
+  get text(): string {
+    return this.getContent()
+      .filter((block): block is TextBlock => block.type === 'text')
+      .map((block) => block.text)
+      .join('\n\n');
+  }
+}
+
+/**
+ * User input message
+ */
+export class UserMessage extends Message {
+  readonly type = 'user' as const;
+  readonly content: UserContent[];
+
+  /**
+   * @param content - String (converted to TextBlock) or array of content blocks
+   */
+  constructor(content: string | UserContent[], options?: MessageOptions) {
+    super(options);
+    if (typeof content === 'string') {
+      this.content = [{ type: 'text', text: content }];
+    } else {
+      this.content = content;
+    }
+  }
+
+  protected getContent(): ContentBlock[] {
+    return this.content;
+  }
+}
+
+/**
+ * Assistant response message
+ * May contain text, media, and/or tool calls
+ */
+export class AssistantMessage extends Message {
+  readonly type = 'assistant' as const;
+  readonly content: AssistantContent[];
+
+  /** Tool calls requested by the model (if any) */
+  readonly toolCalls?: ToolCall[];
+
+  /**
+   * @param content - String (converted to TextBlock) or array of content blocks
+   * @param toolCalls - Tool calls requested by the model
+   * @param options - Message ID and metadata
+   */
+  constructor(
+    content: string | AssistantContent[],
+    toolCalls?: ToolCall[],
+    options?: MessageOptions
+  ) {
+    super(options);
+    if (typeof content === 'string') {
+      this.content = [{ type: 'text', text: content }];
+    } else {
+      this.content = content;
+    }
+    this.toolCalls = toolCalls;
+  }
+
+  protected getContent(): ContentBlock[] {
+    return this.content;
+  }
+
+  /** Check if this message requests tool execution */
+  get hasToolCalls(): boolean {
+    return this.toolCalls !== undefined && this.toolCalls.length > 0;
+  }
+}
+
+/**
+ * Result of tool execution (sent back to model)
+ */
+export class ToolResultMessage extends Message {
+  readonly type = 'tool_result' as const;
+  readonly results: ToolResult[];
+
+  /**
+   * @param results - Array of tool execution results
+   * @param options - Message ID and metadata
+   */
+  constructor(results: ToolResult[], options?: MessageOptions) {
+    super(options);
+    this.results = results;
+  }
+
+  protected getContent(): ContentBlock[] {
+    // Tool results don't have traditional content blocks
+    // Return text representations of results
+    return this.results.map((result) => ({
+      type: 'text' as const,
+      text:
+        typeof result.result === 'string'
+          ? result.result
+          : JSON.stringify(result.result),
+    }));
+  }
+}
+
+/**
+ * Type guard for UserMessage
+ */
+export function isUserMessage(msg: Message): msg is UserMessage {
+  return msg.type === 'user';
+}
+
+/**
+ * Type guard for AssistantMessage
+ */
+export function isAssistantMessage(msg: Message): msg is AssistantMessage {
+  return msg.type === 'assistant';
+}
+
+/**
+ * Type guard for ToolResultMessage
+ */
+export function isToolResultMessage(msg: Message): msg is ToolResultMessage {
+  return msg.type === 'tool_result';
+}