@providerprotocol/ai 0.0.1

package/src/types/provider.ts

@@ -0,0 +1,195 @@
+import type { UPPError } from './errors.ts';
+
+/**
+ * API key strategy interface for managing multiple keys
+ */
+export interface KeyStrategy {
+  /** Get the next API key to use */
+  getKey(): string | Promise<string>;
+}
+
+/**
+ * Retry strategy interface
+ */
+export interface RetryStrategy {
+  /**
+   * Called when a request fails with a retryable error.
+   * @param error - The error that occurred
+   * @param attempt - The attempt number (1 = first retry)
+   * @returns Delay in ms before retrying, or null to stop retrying
+   */
+  onRetry(error: UPPError, attempt: number): number | null | Promise<number | null>;
+
+  /**
+   * Called before each request. Can be used to implement pre-emptive rate limiting.
+   * Returns delay in ms to wait before making the request, or 0 to proceed immediately.
+   */
+  beforeRequest?(): number | Promise<number>;
+
+  /**
+   * Reset the strategy state (e.g., after a successful request)
+   */
+  reset?(): void;
+}
+
+/**
+ * Provider configuration for infrastructure/connection settings
+ */
+export interface ProviderConfig {
+  /**
+   * API key - string, async function, or key strategy
+   * @example 'sk-xxx'
+   * @example () => fetchKeyFromVault()
+   * @example new RoundRobinKeys(['sk-1', 'sk-2'])
+   */
+  apiKey?: string | (() => string | Promise<string>) | KeyStrategy;
+
+  /** Override the base API URL (for proxies, local models) */
+  baseUrl?: string;
+
+  /** Request timeout in milliseconds */
+  timeout?: number;
+
+  /** Custom fetch implementation (for logging, caching, custom TLS) */
+  fetch?: typeof fetch;
+
+  /** API version override */
+  apiVersion?: string;
+
+  /** Retry strategy for handling failures and rate limits */
+  retryStrategy?: RetryStrategy;
+}
+
+/**
+ * A reference to a model, created by a provider factory
+ *
+ * @typeParam TOptions - Provider-specific options type
+ */
+export interface ModelReference<TOptions = unknown> {
+  /** The model identifier */
+  readonly modelId: string;
+
+  /** The provider that created this reference */
+  readonly provider: Provider<TOptions>;
+}
+
+// Forward declarations for handler types (defined in llm.ts)
+// We use 'any' here since the full types are circular
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export interface LLMHandler<TParams = any> {
+  /** 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;
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export interface EmbeddingHandler<TParams = any> {
+  /** Supported input types */
+  readonly supportedInputs: ('text' | 'image')[];
+  /** Bind model ID to create executable model */
+  bind(modelId: string): BoundEmbeddingModel<TParams>;
+
+  /**
+   * Internal: Set the parent provider reference.
+   * @internal
+   */
+  _setProvider?(provider: EmbeddingProvider<TParams>): void;
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export interface ImageHandler<TParams = any> {
+  /** Bind model ID to create executable model */
+  bind(modelId: string): BoundImageModel<TParams>;
+
+  /**
+   * Internal: Set the parent provider reference.
+   * @internal
+   */
+  _setProvider?(provider: ImageProvider<TParams>): void;
+}
+
+// Forward declarations for bound models
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export interface BoundLLMModel<TParams = any> {
+  readonly modelId: string;
+  readonly provider: LLMProvider<TParams>;
+  // Methods defined in llm.ts
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export interface BoundEmbeddingModel<TParams = any> {
+  readonly modelId: string;
+  readonly provider: EmbeddingProvider<TParams>;
+  readonly maxBatchSize: number;
+  readonly maxInputLength: number;
+  readonly dimensions: number;
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export interface BoundImageModel<TParams = any> {
+  readonly modelId: string;
+  readonly provider: ImageProvider<TParams>;
+}
+
+/**
+ * A provider factory function with metadata and modality handlers.
+ *
+ * @typeParam TOptions - Provider-specific options passed to the factory function
+ */
+export interface Provider<TOptions = unknown> {
+  /** Create a model reference, optionally with provider-specific options */
+  (modelId: string, options?: TOptions): ModelReference<TOptions>;
+
+  /** Provider name */
+  readonly name: string;
+
+  /** Provider version */
+  readonly version: string;
+
+  /** Supported modalities */
+  readonly modalities: {
+    llm?: LLMHandler;
+    embedding?: EmbeddingHandler;
+    image?: ImageHandler;
+  };
+}
+
+/**
+ * Provider with LLM modality
+ *
+ * @typeParam TParams - Model-specific parameters type
+ * @typeParam TOptions - Provider-specific options type
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type LLMProvider<TParams = any, TOptions = unknown> = Provider<TOptions> & {
+  readonly modalities: { llm: LLMHandler<TParams> };
+};
+
+/**
+ * Provider with Embedding modality
+ *
+ * @typeParam TParams - Model-specific parameters type
+ * @typeParam TOptions - Provider-specific options type
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type EmbeddingProvider<TParams = any, TOptions = unknown> = Provider<TOptions> & {
+  readonly modalities: { embedding: EmbeddingHandler<TParams> };
+};
+
+/**
+ * Provider with Image modality
+ *
+ * @typeParam TParams - Model-specific parameters type
+ * @typeParam TOptions - Provider-specific options type
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type ImageProvider<TParams = any, TOptions = unknown> = Provider<TOptions> & {
+  readonly modalities: { image: ImageHandler<TParams> };
+};

package/src/types/schema.ts

@@ -0,0 +1,58 @@
+/**
+ * JSON Schema types for tool parameters and structured outputs
+ */
+
+export type JSONSchemaPropertyType =
+  | 'string'
+  | 'number'
+  | 'integer'
+  | 'boolean'
+  | 'array'
+  | 'object'
+  | 'null';
+
+/**
+ * JSON Schema property definition
+ */
+export interface JSONSchemaProperty {
+  type: JSONSchemaPropertyType;
+  description?: string;
+  enum?: unknown[];
+  const?: unknown;
+  default?: unknown;
+
+  // String-specific
+  minLength?: number;
+  maxLength?: number;
+  pattern?: string;
+  format?: 'email' | 'uri' | 'date' | 'date-time' | 'uuid';
+
+  // Number-specific
+  minimum?: number;
+  maximum?: number;
+  exclusiveMinimum?: number;
+  exclusiveMaximum?: number;
+  multipleOf?: number;
+
+  // Array-specific
+  items?: JSONSchemaProperty;
+  minItems?: number;
+  maxItems?: number;
+  uniqueItems?: boolean;
+
+  // Object-specific
+  properties?: Record<string, JSONSchemaProperty>;
+  required?: string[];
+  additionalProperties?: boolean;
+}
+
+/**
+ * JSON Schema for tool parameters or structured outputs
+ */
+export interface JSONSchema {
+  type: 'object';
+  properties: Record<string, JSONSchemaProperty>;
+  required?: string[];
+  additionalProperties?: boolean;
+  description?: string;
+}

package/src/types/stream.ts

@@ -0,0 +1,146 @@
+import type { Turn } from './turn.ts';
+
+/**
+ * Stream event types
+ */
+export type StreamEventType =
+  | 'text_delta'
+  | 'reasoning_delta'
+  | 'image_delta'
+  | 'audio_delta'
+  | 'video_delta'
+  | 'tool_call_delta'
+  | 'message_start'
+  | 'message_stop'
+  | 'content_block_start'
+  | 'content_block_stop';
+
+/**
+ * Event delta data (type-specific)
+ */
+export interface EventDelta {
+  text?: string;
+  data?: Uint8Array;
+  toolCallId?: string;
+  toolName?: string;
+  argumentsJson?: string;
+}
+
+/**
+ * A streaming event
+ */
+export interface StreamEvent {
+  /** Event type */
+  type: StreamEventType;
+
+  /** Index of the content block this event belongs to */
+  index: number;
+
+  /** Event data (type-specific) */
+  delta: EventDelta;
+}
+
+/**
+ * Stream result - async iterable that also provides final turn
+ */
+export interface StreamResult<TData = unknown>
+  extends AsyncIterable<StreamEvent> {
+  /**
+   * Get the complete Turn after streaming finishes.
+   * Resolves when the stream completes.
+   */
+  readonly turn: Promise<Turn<TData>>;
+
+  /** Abort the stream */
+  abort(): void;
+}
+
+/**
+ * Create a stream result from an async generator and completion promise
+ */
+export function createStreamResult<TData = unknown>(
+  generator: AsyncGenerator<StreamEvent, void, unknown>,
+  turnPromise: Promise<Turn<TData>>,
+  abortController: AbortController
+): StreamResult<TData> {
+  return {
+    [Symbol.asyncIterator]() {
+      return generator;
+    },
+    turn: turnPromise,
+    abort() {
+      abortController.abort();
+    },
+  };
+}
+
+/**
+ * Create a text delta event
+ */
+export function textDelta(text: string, index = 0): StreamEvent {
+  return {
+    type: 'text_delta',
+    index,
+    delta: { text },
+  };
+}
+
+/**
+ * Create a tool call delta event
+ */
+export function toolCallDelta(
+  toolCallId: string,
+  toolName: string,
+  argumentsJson: string,
+  index = 0
+): StreamEvent {
+  return {
+    type: 'tool_call_delta',
+    index,
+    delta: { toolCallId, toolName, argumentsJson },
+  };
+}
+
+/**
+ * Create a message start event
+ */
+export function messageStart(): StreamEvent {
+  return {
+    type: 'message_start',
+    index: 0,
+    delta: {},
+  };
+}
+
+/**
+ * Create a message stop event
+ */
+export function messageStop(): StreamEvent {
+  return {
+    type: 'message_stop',
+    index: 0,
+    delta: {},
+  };
+}
+
+/**
+ * Create a content block start event
+ */
+export function contentBlockStart(index: number): StreamEvent {
+  return {
+    type: 'content_block_start',
+    index,
+    delta: {},
+  };
+}
+
+/**
+ * Create a content block stop event
+ */
+export function contentBlockStop(index: number): StreamEvent {
+  return {
+    type: 'content_block_stop',
+    index,
+    delta: {},
+  };
+}

package/src/types/thread.ts

@@ -0,0 +1,226 @@
+import { generateId } from '../utils/id.ts';
+import {
+  Message,
+  UserMessage,
+  AssistantMessage,
+  ToolResultMessage,
+} from './messages.ts';
+import type { MessageType, MessageMetadata } from './messages.ts';
+import type { ContentBlock, UserContent, AssistantContent } from './content.ts';
+import type { Turn } from './turn.ts';
+import type { ToolCall, ToolResult } from './tool.ts';
+
+/**
+ * Serialized message format
+ */
+export interface MessageJSON {
+  id: string;
+  type: MessageType;
+  content: ContentBlock[];
+  toolCalls?: ToolCall[];
+  results?: ToolResult[];
+  metadata?: MessageMetadata;
+  timestamp: string;
+}
+
+/**
+ * Serialized thread format
+ */
+export interface ThreadJSON {
+  id: string;
+  messages: MessageJSON[];
+  createdAt: string;
+  updatedAt: string;
+}
+
+/**
+ * Thread - A utility class for managing conversation history
+ * Users control their own history; Thread is optional
+ */
+export class Thread {
+  /** Unique thread identifier */
+  readonly id: string;
+
+  /** Internal message storage */
+  private _messages: Message[];
+
+  /** Creation timestamp */
+  private _createdAt: Date;
+
+  /** Last update timestamp */
+  private _updatedAt: Date;
+
+  /**
+   * Create a new thread, optionally with initial messages
+   */
+  constructor(messages?: Message[]) {
+    this.id = generateId();
+    this._messages = messages ? [...messages] : [];
+    this._createdAt = new Date();
+    this._updatedAt = new Date();
+  }
+
+  /** All messages in the thread (readonly) */
+  get messages(): readonly Message[] {
+    return this._messages;
+  }
+
+  /** Number of messages */
+  get length(): number {
+    return this._messages.length;
+  }
+
+  /**
+   * Append messages from a turn
+   */
+  append(turn: Turn): this {
+    this._messages.push(...turn.messages);
+    this._updatedAt = new Date();
+    return this;
+  }
+
+  /**
+   * Add raw messages
+   */
+  push(...messages: Message[]): this {
+    this._messages.push(...messages);
+    this._updatedAt = new Date();
+    return this;
+  }
+
+  /**
+   * Add a user message
+   */
+  user(content: string | UserContent[]): this {
+    this._messages.push(new UserMessage(content));
+    this._updatedAt = new Date();
+    return this;
+  }
+
+  /**
+   * Add an assistant message
+   */
+  assistant(content: string | AssistantContent[]): this {
+    this._messages.push(new AssistantMessage(content));
+    this._updatedAt = new Date();
+    return this;
+  }
+
+  /**
+   * Get messages by type
+   */
+  filter(type: MessageType): Message[] {
+    return this._messages.filter((m) => m.type === type);
+  }
+
+  /**
+   * Get the last N messages
+   */
+  tail(count: number): Message[] {
+    return this._messages.slice(-count);
+  }
+
+  /**
+   * Create a new thread with a subset of messages
+   */
+  slice(start?: number, end?: number): Thread {
+    return new Thread(this._messages.slice(start, end));
+  }
+
+  /**
+   * Clear all messages
+   */
+  clear(): this {
+    this._messages = [];
+    this._updatedAt = new Date();
+    return this;
+  }
+
+  /**
+   * Convert to plain message array
+   */
+  toMessages(): Message[] {
+    return [...this._messages];
+  }
+
+  /**
+   * Serialize to JSON
+   */
+  toJSON(): ThreadJSON {
+    return {
+      id: this.id,
+      messages: this._messages.map((m) => this.messageToJSON(m)),
+      createdAt: this._createdAt.toISOString(),
+      updatedAt: this._updatedAt.toISOString(),
+    };
+  }
+
+  /**
+   * Deserialize from JSON
+   */
+  static fromJSON(json: ThreadJSON): Thread {
+    const messages = json.messages.map((m) => Thread.messageFromJSON(m));
+    const thread = new Thread(messages);
+    // Override the generated id with the serialized one
+    (thread as { id: string }).id = json.id;
+    thread._createdAt = new Date(json.createdAt);
+    thread._updatedAt = new Date(json.updatedAt);
+    return thread;
+  }
+
+  /**
+   * Iterate over messages
+   */
+  [Symbol.iterator](): Iterator<Message> {
+    return this._messages[Symbol.iterator]();
+  }
+
+  /**
+   * Convert a message to JSON
+   */
+  private messageToJSON(m: Message): MessageJSON {
+    const base: MessageJSON = {
+      id: m.id,
+      type: m.type,
+      content: [],
+      metadata: m.metadata,
+      timestamp: m.timestamp.toISOString(),
+    };
+
+    if (m instanceof UserMessage) {
+      base.content = m.content;
+    } else if (m instanceof AssistantMessage) {
+      base.content = m.content;
+      base.toolCalls = m.toolCalls;
+    } else if (m instanceof ToolResultMessage) {
+      base.results = m.results;
+    }
+
+    return base;
+  }
+
+  /**
+   * Reconstruct a message from JSON
+   */
+  private static messageFromJSON(json: MessageJSON): Message {
+    const options = {
+      id: json.id,
+      metadata: json.metadata,
+    };
+
+    switch (json.type) {
+      case 'user':
+        return new UserMessage(json.content as UserContent[], options);
+      case 'assistant':
+        return new AssistantMessage(
+          json.content as AssistantContent[],
+          json.toolCalls,
+          options
+        );
+      case 'tool_result':
+        return new ToolResultMessage(json.results ?? [], options);
+      default:
+        throw new Error(`Unknown message type: ${json.type}`);
+    }
+  }
+}

package/src/types/tool.ts

@@ -0,0 +1,88 @@
+import type { JSONSchema } from './schema.ts';
+
+/**
+ * Tool call requested by the model
+ */
+export interface ToolCall {
+  toolCallId: string;
+  toolName: string;
+  arguments: Record<string, unknown>;
+}
+
+/**
+ * Result of tool execution
+ */
+export interface ToolResult {
+  toolCallId: string;
+  result: unknown;
+  isError?: boolean;
+}
+
+/**
+ * Tool definition
+ */
+export interface Tool<TParams = unknown, TResult = unknown> {
+  /** Tool name (must be unique within a llm() instance) */
+  name: string;
+
+  /** Human-readable description for the model */
+  description: string;
+
+  /** JSON Schema defining parameters */
+  parameters: JSONSchema;
+
+  /** Tool execution function */
+  run(params: TParams): TResult | Promise<TResult>;
+
+  /** Optional approval handler for sensitive operations */
+  approval?(params: TParams): boolean | Promise<boolean>;
+}
+
+/**
+ * Strategy for tool execution
+ */
+export interface ToolUseStrategy {
+  /** Maximum tool execution rounds (default: 10) */
+  maxIterations?: number;
+
+  /** Called when the model requests a tool call */
+  onToolCall?(tool: Tool, params: unknown): void | Promise<void>;
+
+  /** Called before tool execution, return false to skip */
+  onBeforeCall?(tool: Tool, params: unknown): boolean | Promise<boolean>;
+
+  /** Called after tool execution */
+  onAfterCall?(tool: Tool, params: unknown, result: unknown): void | Promise<void>;
+
+  /** Called on tool execution error */
+  onError?(tool: Tool, params: unknown, error: Error): void | Promise<void>;
+
+  /** Called when max iterations reached */
+  onMaxIterations?(iterations: number): void | Promise<void>;
+}
+
+/**
+ * Record of a tool execution
+ */
+export interface ToolExecution {
+  /** The tool that was called */
+  toolName: string;
+
+  /** Tool call ID */
+  toolCallId: string;
+
+  /** Arguments passed to the tool */
+  arguments: Record<string, unknown>;
+
+  /** Result returned by the tool */
+  result: unknown;
+
+  /** Whether the tool execution resulted in an error */
+  isError: boolean;
+
+  /** Execution duration in milliseconds */
+  duration: number;
+
+  /** Whether approval was required and granted */
+  approved?: boolean;
+}