genai-lite 0.11.0 → 0.13.0

package/README.md

@@ -6,6 +6,7 @@ A lightweight, portable Node.js/TypeScript library providing a unified interface
 
 - 🔌 **Unified API** - Single interface for multiple AI providers
 - 🏠 **Local & Cloud Models** - Run models locally with llama.cpp or use cloud APIs
+- ⚡ **Text Streaming** - Async iterable token deltas for OpenAI, Anthropic, Gemini, Mistral, OpenRouter, and llama.cpp
 - 🖼️ **Image Generation** - First-class support for AI image generation (OpenAI, local diffusion)
 - 🔐 **Flexible API Key Management** - Bring your own key storage solution
 - 📦 **Zero Electron Dependencies** - Works in any Node.js environment
@@ -77,6 +78,33 @@ if (response.object === 'chat.completion') {
 }
 ```
 
+### Streaming Text
+
+```typescript
+import { LLMService } from 'genai-lite';
+
+const llmService = new LLMService(async () => 'not-needed');
+
+for await (const event of llmService.streamMessage({
+  providerId: 'llamacpp',
+  modelId: 'llamacpp',
+  messages: [{ role: 'user', content: 'Say hello in five words.' }],
+  settings: { maxTokens: 32 }
+})) {
+  if (event.type === 'content_delta') {
+    process.stdout.write(event.delta);
+  } else if (event.type === 'reasoning_delta') {
+    process.stderr.write(event.delta);
+  } else if (event.type === 'complete') {
+    console.log('\nTokens:', event.response.usage?.total_tokens);
+  } else if (event.type === 'error') {
+    console.error(event.error.error.message);
+  }
+}
+```
+
+Streaming is implemented for all text providers: `openai`, `anthropic`, `gemini`, `mistral`, `openrouter`, and `llamacpp`. The final `complete.response` event contains the same normalized response shape returned by `sendMessage()`.
+
 ### Image Generation
 
 ```typescript
@@ -134,7 +162,7 @@ Comprehensive documentation is available in the **[`genai-lite-docs`](./genai-li
 - **Google Gemini** - Gemini 3 (Pro, Flash preview), Gemini 2.5, Gemma 3 & 4 (free)
 - **Mistral** - Codestral, Devstral
 - **OpenRouter** - Unified gateway to 100+ models (unknown models assumed reasoning-capable)
-- **llama.cpp** - Run any GGUF model locally (no API keys required); local reasoning toggle for detected models
+- **llama.cpp** - Run any GGUF model locally (no API keys required); streaming and local reasoning toggle for detected models
 
 ### Image Providers
 - **OpenAI Images** - gpt-image-1, dall-e-3, dall-e-2

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 export type { ApiKeyProvider, PresetMode } from "./types";
 export { LLMService } from "./llm/LLMService";
-export type { LLMServiceOptions, SendMessageOptions, CreateMessagesResult } from "./llm/LLMService";
+export type { LLMServiceOptions, SendMessageOptions, StreamMessageOptions, CreateMessagesResult } from "./llm/LLMService";
 export { withRetry, DEFAULT_RETRY_POLICY } from "./shared/services/withRetry";
 export type { RetryPolicy, RetryVerdict, WithRetryOptions } from "./shared/services/withRetry";
 export type { ModelPreset } from "./types/presets";

package/dist/llm/LLMService.d.ts

@@ -1,6 +1,6 @@
 import type { ApiKeyProvider, PresetMode } from '../types';
 import type { Logger, LogLevel } from '../logging/types';
-import type { LLMChatRequest, LLMChatRequestWithPreset, LLMResponse, LLMFailureResponse, ProviderInfo, ModelInfo, ApiProviderId, LLMSettings, ModelContext, LLMMessage } from "./types";
+import type { LLMChatRequest, LLMChatRequestWithPreset, LLMResponse, LLMFailureResponse, ProviderInfo, ModelInfo, ApiProviderId, LLMSettings, ModelContext, LLMMessage, LLMStreamEvent, LLMRequestCapabilityPreflight, LLMRequestCapabilityValidationResult, ModelCapabilitiesResult, StructuredOutputSupport } from "./types";
 import type { ModelPreset } from "../types/presets";
 import { type RetryPolicy } from "../shared/services/withRetry";
 export type { PresetMode };
@@ -43,6 +43,18 @@ export interface SendMessageOptions {
     /** Per-request retry cap (overrides the service-level retry.maxRetries) */
     maxRetries?: number;
 }
+/**
+ * Per-call options for LLMService.streamMessage
+ */
+export interface StreamMessageOptions {
+    /**
+     * Abort signal to cancel the request (client-side - the provider may still
+     * process and bill an already-dispatched request).
+     */
+    signal?: AbortSignal;
+    /** Per-request timeout in ms (overrides the service-level timeoutMs) */
+    timeoutMs?: number;
+}
 /**
  * Result from createMessages method
  */
@@ -89,6 +101,31 @@ export declare class LLMService {
      * @returns Promise resolving to array of model information
      */
     getModels(providerId: ApiProviderId): Promise<ModelInfo[]>;
+    /**
+     * Gets static capability metadata for a provider/model pair without retrieving
+     * API keys, calling provider adapters, or performing network I/O.
+     *
+     * Unknown or unregistered models use the same fallback model resolution policy
+     * as sendMessage(), but their optional capabilities are reported as unknown.
+     */
+    getModelCapabilities(providerId: ApiProviderId, modelId: string): Promise<ModelCapabilitiesResult | LLMFailureResponse>;
+    /**
+     * Convenience wrapper for checking structured-output support.
+     *
+     * Returns `unknown` when genai-lite has no explicit capability metadata. Callers
+     * should decide whether unknown is acceptable for their use case.
+     */
+    supportsStructuredOutput(providerId: ApiProviderId, modelId: string): Promise<StructuredOutputSupport | LLMFailureResponse>;
+    /**
+     * Preflights provider/model capability requirements for a request without
+     * retrieving API keys, calling provider adapters, or performing network I/O.
+     *
+     * This checks the effective settings after preset and model defaults are
+     * applied. Unknown/unspecified capabilities are reported as unknown and remain
+     * valid; explicitly unsupported capabilities return the same validation error
+     * shape as sendMessage() where possible.
+     */
+    validateRequestCapabilities(request: LLMRequestCapabilityPreflight): Promise<LLMRequestCapabilityValidationResult>;
     /**
      * Sends a chat message to an LLM provider
      *
@@ -96,6 +133,20 @@ export declare class LLMService {
      * @returns Promise resolving to either success or failure response
      */
     sendMessage(request: LLMChatRequest | LLMChatRequestWithPreset, callOptions?: SendMessageOptions): Promise<LLMResponse | LLMFailureResponse>;
+    /**
+     * Streams a chat message from an LLM provider.
+     *
+     * The final `complete` event contains the same normalized response shape as
+     * sendMessage(). Validation/API key failures and unsupported streaming adapters
+     * are yielded as a single `error` event.
+     */
+    streamMessage(request: LLMChatRequest | LLMChatRequestWithPreset, callOptions?: StreamMessageOptions): AsyncGenerator<LLMStreamEvent>;
+    private resolveAndValidateCapabilities;
+    private buildModelCapabilities;
+    private getStructuredOutputSupport;
+    private getCapabilitySource;
+    private prepareRequest;
+    private postProcessResponse;
     /**
      * Gets all configured model presets
      *