genai-lite 0.14.1 → 0.15.0

package/README.md

@@ -19,6 +19,9 @@ A lightweight, portable Node.js/TypeScript library providing a unified interface
 - 🎭 **Template Engine** - Sophisticated templating with conditionals and variable substitution
 - 📊 **Configurable Logging** - Debug mode, custom loggers (pino, winston), and silent mode for tests
 
+Prepared calls can inspect and budget the immutable semantic provider request,
+then dispatch that same representation with truthful token/termination evidence.
+
 ## Installation
 
 ```bash
@@ -105,6 +108,24 @@ for await (const event of llmService.streamMessage({
 
 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()`.
 
+### Prepared Calls
+
+```typescript
+const prepared = await llmService.prepareMessage(request, { mode: 'complete' });
+if ('object' in prepared) throw new Error(prepared.error.message);
+
+const inspection = await llmService.inspectPrepared(prepared);
+if ('object' in inspection) throw new Error(inspection.error.message);
+
+console.log(inspection.promptAccounting, inspection.outputTokenLimit);
+const response = await llmService.sendPrepared(prepared);
+```
+
+Preparation is credential-free and mode-bound. See
+**[Prepared Calls & Token Accounting](./genai-lite-docs/prepared-calls-and-accounting.md)**
+for certified structural bounds, the single-margin capacity formula, response
+evidence, and exact active-template llama.cpp counting.
+
 ### Image Generation
 
 ```typescript
@@ -138,6 +159,7 @@ Comprehensive documentation is available in the **[`genai-lite-docs`](./genai-li
 
 ### API Reference
 - **[LLM Service](./genai-lite-docs/llm-service.md)** - Text generation and chat
+- **[Prepared Calls & Token Accounting](./genai-lite-docs/prepared-calls-and-accounting.md)** - Inspect, budget, and dispatch one canonical request
 - **[Image Service](./genai-lite-docs/image-service.md)** - Image generation (cloud and local)
 - **[llama.cpp Integration](./genai-lite-docs/llamacpp-integration.md)** - Local LLM inference
 

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 export type { ApiKeyProvider, PresetMode } from "./types";
 export { LLMService } from "./llm/LLMService";
-export type { LLMServiceOptions, SendMessageOptions, StreamMessageOptions, CreateMessagesResult } from "./llm/LLMService";
+export type { LLMServiceOptions, SendMessageOptions, StreamMessageOptions, PrepareMessageOptions, 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";
@@ -10,7 +10,7 @@ export { fromEnvironment } from "./providers/fromEnvironment";
 export { LlamaCppClientAdapter } from "./llm/clients/LlamaCppClientAdapter";
 export { LlamaCppServerClient } from "./llm/clients/LlamaCppServerClient";
 export type { LlamaCppClientConfig, } from "./llm/clients/LlamaCppClientAdapter";
-export type { LlamaCppHealthResponse, LlamaCppTokenizeResponse, LlamaCppDetokenizeResponse, LlamaCppEmbeddingResponse, LlamaCppInfillResponse, LlamaCppPropsResponse, LlamaCppMetricsResponse, LlamaCppSlot, LlamaCppSlotsResponse, LlamaCppModel, LlamaCppModelsResponse, } from "./llm/clients/LlamaCppServerClient";
+export type { LlamaCppHealthResponse, LlamaCppTokenizeResponse, LlamaCppDetokenizeResponse, LlamaCppEmbeddingResponse, LlamaCppInfillResponse, LlamaCppPropsResponse, LlamaCppMetricsResponse, LlamaCppSlot, LlamaCppSlotsResponse, LlamaCppModel, LlamaCppModelsResponse, LlamaCppChatInputTokensResponse, LlamaCppUtilityRequestOptions, } from "./llm/clients/LlamaCppServerClient";
 export { OpenRouterClientAdapter } from "./llm/clients/OpenRouterClientAdapter";
 export type { OpenRouterClientConfig } from "./llm/clients/OpenRouterClientAdapter";
 export { MistralClientAdapter } from "./llm/clients/MistralClientAdapter";
@@ -19,6 +19,8 @@ export { ImageService } from "./image/ImageService";
 export type { ImageProviderId, ImageMimeType, ImageResponseFormat, ImageQuality, ImageStyle, DiffusionSampler, ImageProgressStage, ImageProgressCallback, DiffusionSettings, OpenAISpecificSettings, ImageGenerationSettings, ResolvedImageGenerationSettings, ImageUsage, GeneratedImage, ImageGenerationRequestBase, ImageGenerationRequest, ImageGenerationRequestWithPreset, ImageGenerationResponse, ImageFailureResponse, ImageProviderCapabilities, ImageModelInfo, ImageProviderInfo, ImagePreset, ImageProviderAdapterConfig, ImageProviderAdapter, ImageServiceOptions, GenerateImageOptions, CreatePromptResult, } from "./types/image";
 export { renderTemplate } from "./prompting/template";
 export { countTokens, getSmartPreview, extractRandomVariables } from "./prompting/content";
+export { TOKEN_PROFILE_MAPPING_REVISION, codePointBoundToTokenUpperBound, countTextTokens, estimateTextTokens, getTokenProfileById, resolveTokenProfile, retokenizationUpperBound, } from "./llm/tokenization";
+export type { TokenBoundResult, TokenCountResult, TokenProfile, TokenProfileId, TokenProfileResolution, } from "./llm/tokenization";
 export { parseStructuredContent, parseRoleTags, extractInitialTaggedContent, extractMarkerDelimitedContent, parseTemplateWithMetadata } from "./prompting/parser";
 export type { TemplateMetadata } from "./prompting/parser";
 export { createFallbackModelInfo, detectGgufCapabilities, KNOWN_GGUF_MODELS } from "./llm/config";

package/dist/index.js

@@ -14,7 +14,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.silentLogger = exports.DEFAULT_LOG_LEVEL = exports.createDefaultLogger = exports.KNOWN_GGUF_MODELS = exports.detectGgufCapabilities = exports.createFallbackModelInfo = exports.parseTemplateWithMetadata = exports.extractMarkerDelimitedContent = exports.extractInitialTaggedContent = exports.parseRoleTags = exports.parseStructuredContent = exports.extractRandomVariables = exports.getSmartPreview = exports.countTokens = exports.renderTemplate = exports.ImageService = exports.MistralClientAdapter = exports.OpenRouterClientAdapter = exports.LlamaCppServerClient = exports.LlamaCppClientAdapter = exports.fromEnvironment = exports.DEFAULT_RETRY_POLICY = exports.withRetry = exports.LLMService = void 0;
+exports.silentLogger = exports.DEFAULT_LOG_LEVEL = exports.createDefaultLogger = exports.KNOWN_GGUF_MODELS = exports.detectGgufCapabilities = exports.createFallbackModelInfo = exports.parseTemplateWithMetadata = exports.extractMarkerDelimitedContent = exports.extractInitialTaggedContent = exports.parseRoleTags = exports.parseStructuredContent = exports.retokenizationUpperBound = exports.resolveTokenProfile = exports.getTokenProfileById = exports.estimateTextTokens = exports.countTextTokens = exports.codePointBoundToTokenUpperBound = exports.TOKEN_PROFILE_MAPPING_REVISION = exports.extractRandomVariables = exports.getSmartPreview = exports.countTokens = exports.renderTemplate = exports.ImageService = exports.MistralClientAdapter = exports.OpenRouterClientAdapter = exports.LlamaCppServerClient = exports.LlamaCppClientAdapter = exports.fromEnvironment = exports.DEFAULT_RETRY_POLICY = exports.withRetry = exports.LLMService = void 0;
 // --- LLM Service ---
 var LLMService_1 = require("./llm/LLMService");
 Object.defineProperty(exports, "LLMService", { enumerable: true, get: function () { return LLMService_1.LLMService; } });
@@ -51,6 +51,14 @@ var content_1 = require("./prompting/content");
 Object.defineProperty(exports, "countTokens", { enumerable: true, get: function () { return content_1.countTokens; } });
 Object.defineProperty(exports, "getSmartPreview", { enumerable: true, get: function () { return content_1.getSmartPreview; } });
 Object.defineProperty(exports, "extractRandomVariables", { enumerable: true, get: function () { return content_1.extractRandomVariables; } });
+var tokenization_1 = require("./llm/tokenization");
+Object.defineProperty(exports, "TOKEN_PROFILE_MAPPING_REVISION", { enumerable: true, get: function () { return tokenization_1.TOKEN_PROFILE_MAPPING_REVISION; } });
+Object.defineProperty(exports, "codePointBoundToTokenUpperBound", { enumerable: true, get: function () { return tokenization_1.codePointBoundToTokenUpperBound; } });
+Object.defineProperty(exports, "countTextTokens", { enumerable: true, get: function () { return tokenization_1.countTextTokens; } });
+Object.defineProperty(exports, "estimateTextTokens", { enumerable: true, get: function () { return tokenization_1.estimateTextTokens; } });
+Object.defineProperty(exports, "getTokenProfileById", { enumerable: true, get: function () { return tokenization_1.getTokenProfileById; } });
+Object.defineProperty(exports, "resolveTokenProfile", { enumerable: true, get: function () { return tokenization_1.resolveTokenProfile; } });
+Object.defineProperty(exports, "retokenizationUpperBound", { enumerable: true, get: function () { return tokenization_1.retokenizationUpperBound; } });
 var parser_1 = require("./prompting/parser");
 Object.defineProperty(exports, "parseStructuredContent", { enumerable: true, get: function () { return parser_1.parseStructuredContent; } });
 Object.defineProperty(exports, "parseRoleTags", { enumerable: true, get: function () { return parser_1.parseRoleTags; } });

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, LLMStreamEvent, LLMRequestCapabilityPreflight, LLMRequestCapabilityValidationResult, ModelCapabilitiesResult, StructuredOutputSupport } from "./types";
+import type { LLMChatRequest, LLMChatRequestWithPreset, LLMResponse, LLMFailureResponse, ProviderInfo, ModelInfo, ApiProviderId, LLMSettings, ModelContext, LLMMessage, LLMServiceStreamEvent, LLMRequestCapabilityPreflight, LLMRequestCapabilityValidationResult, ModelCapabilitiesResult, StructuredOutputSupport, PreparedCallMode, PreparedCall, PreparedCompleteCall, PreparedStreamCall, PrepareMessageResult, PreparedRequestInspection } from "./types";
 import type { ModelPreset } from "../types/presets";
 import { type RetryPolicy } from "../shared/services/withRetry";
 export type { PresetMode };
@@ -55,6 +55,10 @@ export interface StreamMessageOptions {
     /** Per-request timeout in ms (overrides the service-level timeoutMs) */
     timeoutMs?: number;
 }
+/** Selects the immutable dispatch mode fixed during preparation. */
+export interface PrepareMessageOptions<TMode extends PreparedCallMode> {
+    mode: TMode;
+}
 /**
  * Result from createMessages method
  */
@@ -87,6 +91,7 @@ export declare class LLMService {
     private modelResolver;
     private retryOptions;
     private defaultTimeoutMs?;
+    private preparedCalls;
     constructor(getApiKey: ApiKeyProvider, options?: LLMServiceOptions);
     /**
      * Gets list of supported LLM providers
@@ -133,6 +138,15 @@ export declare class LLMService {
      * @returns Promise resolving to either success or failure response
      */
     sendMessage(request: LLMChatRequest | LLMChatRequestWithPreset, callOptions?: SendMessageOptions): Promise<LLMResponse | LLMFailureResponse>;
+    /**
+     * Resolves and freezes the final semantic provider request without retrieving
+     * credentials or creating transport state.
+     */
+    prepareMessage<TMode extends PreparedCallMode>(request: LLMChatRequest | LLMChatRequestWithPreset, options: PrepareMessageOptions<TMode>): Promise<PrepareMessageResult<TMode>>;
+    /** Returns the immutable inspection view for a service-owned prepared call. */
+    inspectPrepared(handle: PreparedCall<PreparedCallMode>): Promise<PreparedRequestInspection | LLMFailureResponse>;
+    /** Dispatches a reusable complete-mode prepared call. */
+    sendPrepared(handle: PreparedCompleteCall, callOptions?: SendMessageOptions): Promise<LLMResponse | LLMFailureResponse>;
     /**
      * Streams a chat message from an LLM provider.
      *
@@ -140,12 +154,30 @@ export declare class LLMService {
      * sendMessage(). Validation/API key failures and unsupported streaming adapters
      * are yielded as a single `error` event.
      */
-    streamMessage(request: LLMChatRequest | LLMChatRequestWithPreset, callOptions?: StreamMessageOptions): AsyncGenerator<LLMStreamEvent>;
+    streamMessage(request: LLMChatRequest | LLMChatRequestWithPreset, callOptions?: StreamMessageOptions): AsyncGenerator<LLMServiceStreamEvent>;
+    /** Dispatches a reusable stream-mode prepared call with no automatic retries. */
+    streamPrepared(handle: PreparedStreamCall, callOptions?: StreamMessageOptions): AsyncGenerator<LLMServiceStreamEvent>;
+    private streamPreparedWithAttempt;
     private resolveAndValidateCapabilities;
     private buildModelCapabilities;
     private getStructuredOutputSupport;
     private getCapabilitySource;
-    private prepareRequest;
+    private isFailureResponse;
+    private createPreparedFailure;
+    private createPreparedHandleError;
+    private resolvePreparedHandle;
+    private resolveDispatchApiKey;
+    private createAdapterOptions;
+    private revalidatePrepared;
+    private nextStreamEvent;
+    private observeStreamPartial;
+    private getStreamPartialChoice;
+    private finalizeStreamFailure;
+    private attachStreamPartial;
+    private isValidPreparedAccounting;
+    private createEffectiveOutputTokenLimit;
+    private createUnexpectedDispatchFailure;
+    private prepareCanonicalRequest;
     private postProcessResponse;
     /**
      * Gets all configured model presets