@providerprotocol/ai 0.0.10 → 0.0.12

package/src/types/thread.ts

@@ -1,226 +0,0 @@
-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

@@ -1,88 +0,0 @@
-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;
-}

package/src/types/turn.ts

@@ -1,118 +0,0 @@
-import type { Message, AssistantMessage } from './messages.ts';
-import type { ToolExecution } from './tool.ts';
-
-/**
- * Token usage information
- */
-export interface TokenUsage {
-  /** Input tokens across all cycles */
-  inputTokens: number;
-
-  /** Output tokens across all cycles */
-  outputTokens: number;
-
-  /** Total tokens */
-  totalTokens: number;
-
-  /** Per-cycle breakdown (if available) */
-  cycles?: Array<{
-    inputTokens: number;
-    outputTokens: number;
-  }>;
-}
-
-/**
- * A Turn represents the complete result of one inference call,
- * including all messages produced during tool execution loops.
- */
-export interface Turn<TData = unknown> {
-  /**
-   * All messages produced during this inference, in chronological order.
-   * Types: UserMessage, AssistantMessage (may include toolCalls), ToolResultMessage
-   */
-  readonly messages: Message[];
-
-  /** The final assistant response (convenience accessor) */
-  readonly response: AssistantMessage;
-
-  /** Tool executions that occurred during this turn */
-  readonly toolExecutions: ToolExecution[];
-
-  /** Aggregate token usage for the entire turn */
-  readonly usage: TokenUsage;
-
-  /** Total number of inference cycles (1 + number of tool rounds) */
-  readonly cycles: number;
-
-  /**
-   * Structured output data (if structure was provided).
-   * Type is inferred from the schema when using TypeScript.
-   */
-  readonly data?: TData;
-}
-
-/**
- * Create a Turn from accumulated data
- */
-export function createTurn<TData = unknown>(
-  messages: Message[],
-  toolExecutions: ToolExecution[],
-  usage: TokenUsage,
-  cycles: number,
-  data?: TData
-): Turn<TData> {
-  // Find the last assistant message as the response
-  const response = messages
-    .filter((m): m is AssistantMessage => m.type === 'assistant')
-    .pop();
-
-  if (!response) {
-    throw new Error('Turn must contain at least one assistant message');
-  }
-
-  return {
-    messages,
-    response,
-    toolExecutions,
-    usage,
-    cycles,
-    data,
-  };
-}
-
-/**
- * Create empty token usage
- */
-export function emptyUsage(): TokenUsage {
-  return {
-    inputTokens: 0,
-    outputTokens: 0,
-    totalTokens: 0,
-    cycles: [],
-  };
-}
-
-/**
- * Aggregate token usage from multiple cycles
- */
-export function aggregateUsage(usages: TokenUsage[]): TokenUsage {
-  const cycles: TokenUsage['cycles'] = [];
-  let inputTokens = 0;
-  let outputTokens = 0;
-
-  for (const usage of usages) {
-    inputTokens += usage.inputTokens;
-    outputTokens += usage.outputTokens;
-    cycles.push({
-      inputTokens: usage.inputTokens,
-      outputTokens: usage.outputTokens,
-    });
-  }
-
-  return {
-    inputTokens,
-    outputTokens,
-    totalTokens: inputTokens + outputTokens,
-    cycles,
-  };
-}

package/src/utils/id.ts

@@ -1,28 +0,0 @@
-/**
- * Generate a unique ID
- * Uses crypto.randomUUID if available, falls back to a simple implementation
- */
-export function generateId(): string {
-  if (typeof crypto !== 'undefined' && crypto.randomUUID) {
-    return crypto.randomUUID();
-  }
-
-  // Fallback for environments without crypto.randomUUID
-  return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, (c) => {
-    const r = (Math.random() * 16) | 0;
-    const v = c === 'x' ? r : (r & 0x3) | 0x8;
-    return v.toString(16);
-  });
-}
-
-/**
- * Generate a short ID (for tool call IDs, etc.)
- */
-export function generateShortId(prefix = ''): string {
-  const chars = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789';
-  let result = prefix;
-  for (let i = 0; i < 12; i++) {
-    result += chars.charAt(Math.floor(Math.random() * chars.length));
-  }
-  return result;
-}

package/src/xai/index.ts

@@ -1,41 +0,0 @@
-/**
- * xAI provider for UPP (Unified Provider Protocol)
- *
- * This module exports the xAI provider for use with the Grok family of models.
- * xAI's APIs are compatible with both OpenAI and Anthropic SDKs.
- *
- * @example
- * ```ts
- * import { xai } from '@providerprotocol/ai/xai';
- * import { llm } from '@providerprotocol/ai';
- *
- * // Create an LLM instance with Grok
- * const model = llm({
- *   model: xai('grok-4'),
- *   params: { max_tokens: 1000 }
- * });
- *
- * // Generate a response
- * const turn = await model.generate('What is the meaning of life?');
- * console.log(turn.response.text);
- * ```
- *
- * @packageDocumentation
- */
-
-export { xai } from '../providers/xai/index.ts';
-export type {
-  XAIProviderOptions,
-  XAIProvider,
-} from '../providers/xai/index.ts';
-export type {
-  XAICompletionsParams,
-  XAIResponsesParams,
-  XAIMessagesParams,
-  XAIConfig,
-  XAIAPIMode,
-  XAIModelOptions,
-  XAIModelReference,
-  XAISearchParameters,
-  XAIAgentTool,
-} from '../providers/xai/types.ts';