@voltx/ai 0.3.0

package/dist/index.d.cts

@@ -0,0 +1,326 @@
+import { ZodType } from 'zod';
+
+interface TextContent {
+    type: "text";
+    text: string;
+}
+interface ImageContent {
+    type: "image_url";
+    image_url: {
+        url: string;
+        detail?: "auto" | "low" | "high";
+    };
+}
+type ContentPart = TextContent | ImageContent;
+interface Message {
+    role: "system" | "user" | "assistant" | "tool";
+    content: string | ContentPart[];
+    name?: string;
+    tool_call_id?: string;
+    tool_calls?: ToolCallResult[];
+}
+interface ToolDefinition {
+    name: string;
+    description: string;
+    parameters: ZodType | Record<string, unknown>;
+}
+interface ToolCallResult {
+    id: string;
+    type: "function";
+    function: {
+        name: string;
+        arguments: string;
+    };
+}
+interface ProviderConfig {
+    apiKey?: string;
+    baseUrl?: string;
+    headers?: Record<string, string>;
+}
+interface ModelRef {
+    provider: string;
+    model: string;
+    config: ProviderConfig;
+}
+interface GenerateTextOptions {
+    model: string | ModelRef;
+    messages?: Message[];
+    system?: string;
+    prompt?: string;
+    tools?: Record<string, ToolDefinition>;
+    temperature?: number;
+    maxTokens?: number;
+    topP?: number;
+    stop?: string[];
+    /** Abort signal for cancellation */
+    signal?: AbortSignal;
+}
+interface GenerateTextResult {
+    text: string;
+    toolCalls: ParsedToolCall[];
+    usage: TokenUsage;
+    finishReason: FinishReason;
+    /** Raw response from the provider */
+    raw: unknown;
+}
+interface StreamTextOptions extends GenerateTextOptions {
+}
+interface StreamTextResult {
+    /** Async iterator of text chunks */
+    textStream: AsyncIterable<string>;
+    /** Full text (available after stream completes) */
+    text: Promise<string>;
+    /** Convert to SSE Response for HTTP endpoints */
+    toSSEResponse(): Response;
+    /** Convert to a ReadableStream of SSE events */
+    toReadableStream(): ReadableStream<Uint8Array>;
+    /** Usage info (available after stream completes) */
+    usage: Promise<TokenUsage>;
+    /** Abort the stream */
+    abort(): void;
+}
+interface GenerateObjectOptions<T = unknown> {
+    model: string | ModelRef;
+    messages?: Message[];
+    system?: string;
+    prompt?: string;
+    schema: ZodType<T>;
+    schemaName?: string;
+    schemaDescription?: string;
+    temperature?: number;
+    maxTokens?: number;
+    signal?: AbortSignal;
+}
+interface GenerateObjectResult<T = unknown> {
+    object: T;
+    usage: TokenUsage;
+    raw: unknown;
+}
+interface EmbedOptions {
+    model: string | ModelRef;
+    value: string;
+}
+interface EmbedManyOptions {
+    model: string | ModelRef;
+    values: string[];
+}
+interface EmbedResult {
+    embedding: number[];
+    usage: {
+        tokens: number;
+    };
+}
+interface EmbedManyResult {
+    embeddings: number[][];
+    usage: {
+        tokens: number;
+    };
+}
+interface ParsedToolCall {
+    id: string;
+    name: string;
+    args: Record<string, unknown>;
+}
+interface TokenUsage {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+}
+type FinishReason = "stop" | "length" | "tool_calls" | "content_filter" | "error" | "unknown";
+interface AIProvider {
+    name: string;
+    chat(options: ProviderChatOptions): Promise<ProviderChatResponse>;
+    stream(options: ProviderChatOptions): Promise<ProviderStreamResponse>;
+    embed?(options: ProviderEmbedOptions): Promise<ProviderEmbedResponse>;
+}
+interface ProviderChatOptions {
+    model: string;
+    messages: ProviderMessage[];
+    tools?: ProviderTool[];
+    temperature?: number;
+    maxTokens?: number;
+    topP?: number;
+    stop?: string[];
+    responseFormat?: {
+        type: "json_object" | "json_schema";
+        json_schema?: unknown;
+    };
+    signal?: AbortSignal;
+}
+interface ProviderMessage {
+    role: "system" | "user" | "assistant" | "tool";
+    content: string | null;
+    tool_calls?: ToolCallResult[];
+    tool_call_id?: string;
+}
+interface ProviderTool {
+    type: "function";
+    function: {
+        name: string;
+        description: string;
+        parameters: Record<string, unknown>;
+    };
+}
+interface ProviderChatResponse {
+    text: string | null;
+    toolCalls: ToolCallResult[];
+    usage: TokenUsage;
+    finishReason: FinishReason;
+    raw: unknown;
+}
+interface ProviderStreamResponse {
+    stream: AsyncIterable<StreamChunk>;
+    raw?: unknown;
+}
+interface StreamChunk {
+    type: "text-delta" | "tool-call-delta" | "finish" | "error";
+    textDelta?: string;
+    toolCallDelta?: Partial<ToolCallResult>;
+    finishReason?: FinishReason;
+    usage?: TokenUsage;
+    error?: string;
+}
+interface ProviderEmbedOptions {
+    model: string;
+    input: string | string[];
+}
+interface ProviderEmbedResponse {
+    embeddings: number[][];
+    usage: {
+        tokens: number;
+    };
+}
+
+/**
+ * Generate a complete text response from an LLM.
+ *
+ * @example
+ * ```ts
+ * const result = await generateText({
+ *   model: "openai:gpt-4o",
+ *   system: "You are a helpful assistant.",
+ *   prompt: "What is TypeScript?",
+ * });
+ * console.log(result.text);
+ * ```
+ */
+declare function generateText(options: GenerateTextOptions): Promise<GenerateTextResult>;
+
+/**
+ * Stream text from an LLM using Server-Sent Events.
+ *
+ * @example
+ * ```ts
+ * const result = await streamText({
+ *   model: "cerebras:llama-4-scout-17b-16e",
+ *   prompt: "Write a poem about TypeScript",
+ * });
+ *
+ * for await (const chunk of result.textStream) {
+ *   process.stdout.write(chunk);
+ * }
+ * ```
+ */
+declare function streamText(options: StreamTextOptions): Promise<StreamTextResult>;
+
+/**
+ * Generate a structured JSON object from an LLM, validated against a Zod schema.
+ *
+ * @example
+ * ```ts
+ * import { z } from "zod";
+ *
+ * const result = await generateObject({
+ *   model: "openai:gpt-4o",
+ *   prompt: "Generate a user profile",
+ *   schema: z.object({
+ *     name: z.string(),
+ *     age: z.number(),
+ *     interests: z.array(z.string()),
+ *   }),
+ * });
+ * console.log(result.object); // { name: "...", age: 25, interests: [...] }
+ * ```
+ */
+declare function generateObject<T>(options: GenerateObjectOptions<T>): Promise<GenerateObjectResult<T>>;
+
+/**
+ * Generate an embedding vector for a single text.
+ *
+ * @example
+ * ```ts
+ * const { embedding } = await embed({
+ *   model: "openai:text-embedding-3-small",
+ *   value: "What is TypeScript?",
+ * });
+ * ```
+ */
+declare function embed(options: EmbedOptions): Promise<EmbedResult>;
+/**
+ * Generate embedding vectors for multiple texts in a single batch.
+ *
+ * @example
+ * ```ts
+ * const { embeddings } = await embedMany({
+ *   model: "openai:text-embedding-3-small",
+ *   values: ["Hello world", "TypeScript is great"],
+ * });
+ * ```
+ */
+declare function embedMany(options: EmbedManyOptions): Promise<EmbedManyResult>;
+
+declare function createOpenAIProvider(config?: ProviderConfig): AIProvider;
+/** Shorthand: openai("gpt-4o") returns a ModelRef */
+declare function openai(model: string): {
+    provider: string;
+    model: string;
+    config: {};
+};
+
+declare function createAnthropicProvider(config?: ProviderConfig): AIProvider;
+/** Shorthand: anthropic("claude-sonnet-4") returns a ModelRef */
+declare function anthropic(model: string): {
+    provider: string;
+    model: string;
+    config: {};
+};
+
+declare function createGoogleProvider(config?: ProviderConfig): AIProvider;
+/** Shorthand: google("gemini-2.0-flash") returns a ModelRef */
+declare function google(model: string): {
+    provider: string;
+    model: string;
+    config: {};
+};
+
+declare function createCerebrasProvider(config?: ProviderConfig): AIProvider;
+/** Shorthand: cerebras("llama-4-scout-17b-16e") returns a ModelRef */
+declare function cerebras(model: string): {
+    provider: string;
+    model: string;
+    config: {};
+};
+
+declare function createOpenRouterProvider(config?: ProviderConfig): AIProvider;
+/** Shorthand: openrouter("meta-llama/llama-4-scout") returns a ModelRef */
+declare function openrouter(model: string): {
+    provider: string;
+    model: string;
+    config: {};
+};
+
+declare function createOllamaProvider(config?: ProviderConfig): AIProvider;
+/** Shorthand: ollama("llama3") returns a ModelRef */
+declare function ollama(model: string): {
+    provider: string;
+    model: string;
+    config: {};
+};
+
+declare function registerProvider(name: string, factory: (config: ProviderConfig) => AIProvider): void;
+declare function getProvider(name: string, config?: ProviderConfig): AIProvider;
+declare function resolveModel(model: string | ModelRef): ModelRef;
+
+declare const VERSION = "0.3.0";
+
+export { type AIProvider, type ContentPart, type EmbedManyOptions, type EmbedManyResult, type EmbedOptions, type EmbedResult, type FinishReason, type GenerateObjectOptions, type GenerateObjectResult, type GenerateTextOptions, type GenerateTextResult, type ImageContent, type Message, type ModelRef, type ParsedToolCall, type ProviderConfig, type StreamChunk, type StreamTextOptions, type StreamTextResult, type TextContent, type TokenUsage, type ToolCallResult, type ToolDefinition, VERSION, anthropic, cerebras, createAnthropicProvider, createCerebrasProvider, createGoogleProvider, createOllamaProvider, createOpenAIProvider, createOpenRouterProvider, embed, embedMany, generateObject, generateText, getProvider, google, ollama, openai, openrouter, registerProvider, resolveModel, streamText };

package/dist/index.d.ts

@@ -0,0 +1,326 @@
+import { ZodType } from 'zod';
+
+interface TextContent {
+    type: "text";
+    text: string;
+}
+interface ImageContent {
+    type: "image_url";
+    image_url: {
+        url: string;
+        detail?: "auto" | "low" | "high";
+    };
+}
+type ContentPart = TextContent | ImageContent;
+interface Message {
+    role: "system" | "user" | "assistant" | "tool";
+    content: string | ContentPart[];
+    name?: string;
+    tool_call_id?: string;
+    tool_calls?: ToolCallResult[];
+}
+interface ToolDefinition {
+    name: string;
+    description: string;
+    parameters: ZodType | Record<string, unknown>;
+}
+interface ToolCallResult {
+    id: string;
+    type: "function";
+    function: {
+        name: string;
+        arguments: string;
+    };
+}
+interface ProviderConfig {
+    apiKey?: string;
+    baseUrl?: string;
+    headers?: Record<string, string>;
+}
+interface ModelRef {
+    provider: string;
+    model: string;
+    config: ProviderConfig;
+}
+interface GenerateTextOptions {
+    model: string | ModelRef;
+    messages?: Message[];
+    system?: string;
+    prompt?: string;
+    tools?: Record<string, ToolDefinition>;
+    temperature?: number;
+    maxTokens?: number;
+    topP?: number;
+    stop?: string[];
+    /** Abort signal for cancellation */
+    signal?: AbortSignal;
+}
+interface GenerateTextResult {
+    text: string;
+    toolCalls: ParsedToolCall[];
+    usage: TokenUsage;
+    finishReason: FinishReason;
+    /** Raw response from the provider */
+    raw: unknown;
+}
+interface StreamTextOptions extends GenerateTextOptions {
+}
+interface StreamTextResult {
+    /** Async iterator of text chunks */
+    textStream: AsyncIterable<string>;
+    /** Full text (available after stream completes) */
+    text: Promise<string>;
+    /** Convert to SSE Response for HTTP endpoints */
+    toSSEResponse(): Response;
+    /** Convert to a ReadableStream of SSE events */
+    toReadableStream(): ReadableStream<Uint8Array>;
+    /** Usage info (available after stream completes) */
+    usage: Promise<TokenUsage>;
+    /** Abort the stream */
+    abort(): void;
+}
+interface GenerateObjectOptions<T = unknown> {
+    model: string | ModelRef;
+    messages?: Message[];
+    system?: string;
+    prompt?: string;
+    schema: ZodType<T>;
+    schemaName?: string;
+    schemaDescription?: string;
+    temperature?: number;
+    maxTokens?: number;
+    signal?: AbortSignal;
+}
+interface GenerateObjectResult<T = unknown> {
+    object: T;
+    usage: TokenUsage;
+    raw: unknown;
+}
+interface EmbedOptions {
+    model: string | ModelRef;
+    value: string;
+}
+interface EmbedManyOptions {
+    model: string | ModelRef;
+    values: string[];
+}
+interface EmbedResult {
+    embedding: number[];
+    usage: {
+        tokens: number;
+    };
+}
+interface EmbedManyResult {
+    embeddings: number[][];
+    usage: {
+        tokens: number;
+    };
+}
+interface ParsedToolCall {
+    id: string;
+    name: string;
+    args: Record<string, unknown>;
+}
+interface TokenUsage {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+}
+type FinishReason = "stop" | "length" | "tool_calls" | "content_filter" | "error" | "unknown";
+interface AIProvider {
+    name: string;
+    chat(options: ProviderChatOptions): Promise<ProviderChatResponse>;
+    stream(options: ProviderChatOptions): Promise<ProviderStreamResponse>;
+    embed?(options: ProviderEmbedOptions): Promise<ProviderEmbedResponse>;
+}
+interface ProviderChatOptions {
+    model: string;
+    messages: ProviderMessage[];
+    tools?: ProviderTool[];
+    temperature?: number;
+    maxTokens?: number;
+    topP?: number;
+    stop?: string[];
+    responseFormat?: {
+        type: "json_object" | "json_schema";
+        json_schema?: unknown;
+    };
+    signal?: AbortSignal;
+}
+interface ProviderMessage {
+    role: "system" | "user" | "assistant" | "tool";
+    content: string | null;
+    tool_calls?: ToolCallResult[];
+    tool_call_id?: string;
+}
+interface ProviderTool {
+    type: "function";
+    function: {
+        name: string;
+        description: string;
+        parameters: Record<string, unknown>;
+    };
+}
+interface ProviderChatResponse {
+    text: string | null;
+    toolCalls: ToolCallResult[];
+    usage: TokenUsage;
+    finishReason: FinishReason;
+    raw: unknown;
+}
+interface ProviderStreamResponse {
+    stream: AsyncIterable<StreamChunk>;
+    raw?: unknown;
+}
+interface StreamChunk {
+    type: "text-delta" | "tool-call-delta" | "finish" | "error";
+    textDelta?: string;
+    toolCallDelta?: Partial<ToolCallResult>;
+    finishReason?: FinishReason;
+    usage?: TokenUsage;
+    error?: string;
+}
+interface ProviderEmbedOptions {
+    model: string;
+    input: string | string[];
+}
+interface ProviderEmbedResponse {
+    embeddings: number[][];
+    usage: {
+        tokens: number;
+    };
+}
+
+/**
+ * Generate a complete text response from an LLM.
+ *
+ * @example
+ * ```ts
+ * const result = await generateText({
+ *   model: "openai:gpt-4o",
+ *   system: "You are a helpful assistant.",
+ *   prompt: "What is TypeScript?",
+ * });
+ * console.log(result.text);
+ * ```
+ */
+declare function generateText(options: GenerateTextOptions): Promise<GenerateTextResult>;
+
+/**
+ * Stream text from an LLM using Server-Sent Events.
+ *
+ * @example
+ * ```ts
+ * const result = await streamText({
+ *   model: "cerebras:llama-4-scout-17b-16e",
+ *   prompt: "Write a poem about TypeScript",
+ * });
+ *
+ * for await (const chunk of result.textStream) {
+ *   process.stdout.write(chunk);
+ * }
+ * ```
+ */
+declare function streamText(options: StreamTextOptions): Promise<StreamTextResult>;
+
+/**
+ * Generate a structured JSON object from an LLM, validated against a Zod schema.
+ *
+ * @example
+ * ```ts
+ * import { z } from "zod";
+ *
+ * const result = await generateObject({
+ *   model: "openai:gpt-4o",
+ *   prompt: "Generate a user profile",
+ *   schema: z.object({
+ *     name: z.string(),
+ *     age: z.number(),
+ *     interests: z.array(z.string()),
+ *   }),
+ * });
+ * console.log(result.object); // { name: "...", age: 25, interests: [...] }
+ * ```
+ */
+declare function generateObject<T>(options: GenerateObjectOptions<T>): Promise<GenerateObjectResult<T>>;
+
+/**
+ * Generate an embedding vector for a single text.
+ *
+ * @example
+ * ```ts
+ * const { embedding } = await embed({
+ *   model: "openai:text-embedding-3-small",
+ *   value: "What is TypeScript?",
+ * });
+ * ```
+ */
+declare function embed(options: EmbedOptions): Promise<EmbedResult>;
+/**
+ * Generate embedding vectors for multiple texts in a single batch.
+ *
+ * @example
+ * ```ts
+ * const { embeddings } = await embedMany({
+ *   model: "openai:text-embedding-3-small",
+ *   values: ["Hello world", "TypeScript is great"],
+ * });
+ * ```
+ */
+declare function embedMany(options: EmbedManyOptions): Promise<EmbedManyResult>;
+
+declare function createOpenAIProvider(config?: ProviderConfig): AIProvider;
+/** Shorthand: openai("gpt-4o") returns a ModelRef */
+declare function openai(model: string): {
+    provider: string;
+    model: string;
+    config: {};
+};
+
+declare function createAnthropicProvider(config?: ProviderConfig): AIProvider;
+/** Shorthand: anthropic("claude-sonnet-4") returns a ModelRef */
+declare function anthropic(model: string): {
+    provider: string;
+    model: string;
+    config: {};
+};
+
+declare function createGoogleProvider(config?: ProviderConfig): AIProvider;
+/** Shorthand: google("gemini-2.0-flash") returns a ModelRef */
+declare function google(model: string): {
+    provider: string;
+    model: string;
+    config: {};
+};
+
+declare function createCerebrasProvider(config?: ProviderConfig): AIProvider;
+/** Shorthand: cerebras("llama-4-scout-17b-16e") returns a ModelRef */
+declare function cerebras(model: string): {
+    provider: string;
+    model: string;
+    config: {};
+};
+
+declare function createOpenRouterProvider(config?: ProviderConfig): AIProvider;
+/** Shorthand: openrouter("meta-llama/llama-4-scout") returns a ModelRef */
+declare function openrouter(model: string): {
+    provider: string;
+    model: string;
+    config: {};
+};
+
+declare function createOllamaProvider(config?: ProviderConfig): AIProvider;
+/** Shorthand: ollama("llama3") returns a ModelRef */
+declare function ollama(model: string): {
+    provider: string;
+    model: string;
+    config: {};
+};
+
+declare function registerProvider(name: string, factory: (config: ProviderConfig) => AIProvider): void;
+declare function getProvider(name: string, config?: ProviderConfig): AIProvider;
+declare function resolveModel(model: string | ModelRef): ModelRef;
+
+declare const VERSION = "0.3.0";
+
+export { type AIProvider, type ContentPart, type EmbedManyOptions, type EmbedManyResult, type EmbedOptions, type EmbedResult, type FinishReason, type GenerateObjectOptions, type GenerateObjectResult, type GenerateTextOptions, type GenerateTextResult, type ImageContent, type Message, type ModelRef, type ParsedToolCall, type ProviderConfig, type StreamChunk, type StreamTextOptions, type StreamTextResult, type TextContent, type TokenUsage, type ToolCallResult, type ToolDefinition, VERSION, anthropic, cerebras, createAnthropicProvider, createCerebrasProvider, createGoogleProvider, createOllamaProvider, createOpenAIProvider, createOpenRouterProvider, embed, embedMany, generateObject, generateText, getProvider, google, ollama, openai, openrouter, registerProvider, resolveModel, streamText };