@promptbook/browser 0.112.0-72 → 0.112.0-73

package/umd/src/llm-providers/openai/OpenAiAssistantExecutionToolsProgressReporter.d.ts

@@ -0,0 +1,62 @@
+import type { ChatPromptResult } from '../../execution/PromptResult';
+import type { Prompt } from '../../types/Prompt';
+import type { string_markdown } from '../../types/string_markdown';
+import type { string_date_iso8601 } from '../../types/string_token';
+import type { chococake } from '../../utils/organization/really_any';
+/**
+ * Handles progress emission, verbose logging, and final result assembly.
+ *
+ * @private helper of `OpenAiAssistantExecutionTools`
+ */
+export declare class OpenAiAssistantExecutionToolsProgressReporter {
+    private readonly options;
+    /**
+     * Creates one reporter instance.
+     */
+    constructor(options: {
+        readonly isVerbose: boolean;
+    });
+    /**
+     * Logs one assistant chat call when verbose output is enabled.
+     */
+    logAssistantChatCall(prompt: Prompt): void;
+    /**
+     * Logs one assistant request payload when verbose output is enabled.
+     */
+    logVerboseAssistantRequest(label: string, rawRequest: unknown): void;
+    /**
+     * Emits one assistant progress chunk with shared timing and prompt metadata.
+     */
+    emitAssistantProgress(options: {
+        readonly start: string_date_iso8601;
+        readonly rawPromptContent: string;
+        readonly onProgress: (chunk: ChatPromptResult) => void;
+        readonly content?: string;
+        readonly rawRequest?: chococake;
+        readonly rawResponse?: chococake;
+        readonly toolCalls?: ChatPromptResult['toolCalls'];
+    }): void;
+    /**
+     * Creates the final assistant prompt result with uncertain usage plus measured duration.
+     */
+    createAssistantPromptResult(options: {
+        readonly content: string_markdown;
+        readonly start: string_date_iso8601;
+        readonly complete: string_date_iso8601;
+        readonly rawPromptContent: string;
+        readonly rawRequest: chococake;
+        readonly rawResponse: chococake;
+        readonly toolCalls?: ChatPromptResult['toolCalls'];
+    }): ChatPromptResult;
+    /**
+     * Wraps the final assistant prompt result in the standard exported JSON envelope.
+     */
+    exportAssistantPromptResult(options: {
+        readonly result: ChatPromptResult;
+        readonly isWithTools: boolean;
+    }): ChatPromptResult;
+    /**
+     * Computes the usage payload for assistant responses.
+     */
+    private createAssistantUsage;
+}

package/umd/src/llm-providers/openai/OpenAiAssistantExecutionToolsPromptBuilder.d.ts

@@ -0,0 +1,29 @@
+import type OpenAI from 'openai';
+import type { Prompt } from '../../types/Prompt';
+/**
+ * Builds assistant prompt content and thread messages.
+ *
+ * @private helper of `OpenAiAssistantExecutionTools`
+ */
+export declare class OpenAiAssistantExecutionToolsPromptBuilder {
+    /**
+     * Resolves the raw user-visible prompt content sent to the assistant.
+     */
+    createAssistantRawPromptContent(prompt: Prompt): string;
+    /**
+     * Builds the thread history plus the current user message for one assistant call.
+     */
+    createAssistantThreadMessages(options: {
+        readonly client: OpenAI;
+        readonly prompt: Prompt;
+        readonly rawPromptContent: string;
+    }): Promise<Array<OpenAI.Beta.ThreadCreateAndRunParams.Thread.Message>>;
+    /**
+     * Converts the existing prompt thread into OpenAI assistant thread messages.
+     */
+    private createAssistantThreadHistoryMessages;
+    /**
+     * Creates the current user message, including uploaded file attachments when present.
+     */
+    private createAssistantCurrentUserMessage;
+}

package/umd/src/llm-providers/openai/OpenAiAssistantExecutionToolsStreamRunner.d.ts

@@ -0,0 +1,63 @@
+import OpenAI from 'openai';
+import type { ChatPromptResult } from '../../execution/PromptResult';
+import type { Prompt } from '../../types/Prompt';
+import type { string_date_iso8601, string_token } from '../../types/string_token';
+import { OpenAiAssistantExecutionToolsProgressReporter } from './OpenAiAssistantExecutionToolsProgressReporter';
+/**
+ * Shared context for one assistant chat call after prompt preparation finishes.
+ *
+ * @private helper of `OpenAiAssistantExecutionToolsStreamRunner`
+ */
+type AssistantChatCallContext = {
+    readonly client: OpenAI;
+    readonly prompt: Prompt;
+    readonly rawPromptContent: string;
+    readonly threadMessages: ReadonlyArray<OpenAI.Beta.ThreadCreateAndRunParams.Thread.Message>;
+    readonly start: string_date_iso8601;
+    readonly onProgress: (chunk: ChatPromptResult) => void;
+};
+/**
+ * Runs streaming assistant requests that do not require hosted tool execution.
+ *
+ * @private helper of `OpenAiAssistantExecutionTools`
+ */
+export declare class OpenAiAssistantExecutionToolsStreamRunner {
+    private readonly options;
+    /**
+     * Creates one stream runner instance.
+     */
+    constructor(options: {
+        readonly assistantId: string_token;
+        readonly isVerbose: boolean;
+        readonly progressReporter: OpenAiAssistantExecutionToolsProgressReporter;
+    });
+    /**
+     * Runs assistant calls without tools through the streaming Assistants API.
+     */
+    callChatModelStreamWithoutTools(context: AssistantChatCallContext): Promise<ChatPromptResult>;
+    /**
+     * Builds the streaming assistant request payload used when no tool execution flow is needed.
+     */
+    private createAssistantStreamingRequest;
+    /**
+     * Registers verbose stream diagnostics plus incremental text progress forwarding.
+     */
+    private attachAssistantStreamListeners;
+    /**
+     * Resolves the final visible assistant text from a streaming response.
+     */
+    private resolveAssistantStreamingResultContent;
+    /**
+     * Extracts the single text content block returned by the assistant stream.
+     */
+    private extractSingleAssistantTextContentBlock;
+    /**
+     * Rewrites file citation markers to use retrieved filenames instead of generic source labels.
+     */
+    private replaceAssistantFileCitationMarkers;
+    /**
+     * Returns one citation filename, caching OpenAI file lookups across annotations.
+     */
+    private retrieveAssistantCitationFilename;
+}
+export {};

package/umd/src/llm-providers/openai/OpenAiAssistantExecutionToolsToolRunner.d.ts

@@ -0,0 +1,89 @@
+import OpenAI from 'openai';
+import type { ChatPromptResult } from '../../execution/PromptResult';
+import type { ScriptExecutionTools } from '../../execution/ScriptExecutionTools';
+import type { Prompt } from '../../types/Prompt';
+import type { string_date_iso8601, string_token } from '../../types/string_token';
+import { OpenAiAssistantExecutionToolsProgressReporter } from './OpenAiAssistantExecutionToolsProgressReporter';
+/**
+ * Shared context for one assistant chat call after prompt preparation finishes.
+ *
+ * @private helper of `OpenAiAssistantExecutionToolsToolRunner`
+ */
+type AssistantChatCallContext = {
+    readonly client: OpenAI;
+    readonly prompt: Prompt;
+    readonly rawPromptContent: string;
+    readonly threadMessages: ReadonlyArray<OpenAI.Beta.ThreadCreateAndRunParams.Thread.Message>;
+    readonly start: string_date_iso8601;
+    readonly onProgress: (chunk: ChatPromptResult) => void;
+};
+/**
+ * Runs assistant requests that require OpenAI Runs API tool execution.
+ *
+ * @private helper of `OpenAiAssistantExecutionTools`
+ */
+export declare class OpenAiAssistantExecutionToolsToolRunner {
+    private readonly options;
+    /**
+     * Creates one tool runner instance.
+     */
+    constructor(options: {
+        readonly assistantId: string_token;
+        readonly isVerbose: boolean;
+        readonly scriptExecutionTools?: ScriptExecutionTools | ReadonlyArray<ScriptExecutionTools>;
+        readonly progressReporter: OpenAiAssistantExecutionToolsProgressReporter;
+    });
+    /**
+     * Runs assistant calls with tools through the non-streaming Runs API.
+     */
+    callChatModelStreamWithTools(context: AssistantChatCallContext): Promise<ChatPromptResult>;
+    /**
+     * Builds the non-streaming assistant request payload used when tool calls are enabled.
+     */
+    private createAssistantToolRunRequest;
+    /**
+     * Starts the assistant run and keeps polling until the run completes or fails.
+     */
+    private executeAssistantToolRun;
+    /**
+     * Polls one assistant run, executing and submitting tool outputs when OpenAI requests them.
+     */
+    private waitForAssistantToolRun;
+    /**
+     * Executes all required assistant tool calls and submits their outputs back to OpenAI.
+     */
+    private submitAssistantRequiredToolOutputs;
+    /**
+     * Waits a bit and then fetches the latest assistant run status.
+     */
+    private retrieveAssistantRunAfterDelay;
+    /**
+     * Executes each function tool requested by the assistant and records progress snapshots.
+     */
+    private executeAssistantRequiredToolCalls;
+    /**
+     * Executes one function tool requested by the assistant.
+     */
+    private executeAssistantRequiredToolCall;
+    /**
+     * Creates the initial pending snapshot for one assistant tool call.
+     */
+    private createPendingAssistantToolCall;
+    /**
+     * Resolves the configured script tools for assistant tool execution.
+     */
+    private resolveAssistantScriptTools;
+    /**
+     * Executes the configured script tool for one assistant-requested function call.
+     */
+    private executeAssistantFunctionTool;
+    /**
+     * Finalizes one assistant tool-call snapshot after execution ends.
+     */
+    private createCompletedAssistantToolCall;
+    /**
+     * Extracts the latest assistant text response from a completed thread.
+     */
+    private extractCompletedAssistantTextContent;
+}
+export {};

package/umd/src/llm-providers/openai/OpenAiCompatibleExecutionTools.d.ts

@@ -1,4 +1,4 @@
-import OpenAI from 'openai';
+import type OpenAI from 'openai';
 import type { AvailableModel } from '../../execution/AvailableModel';
 import type { CallChatModelStreamOptions, LlmExecutionTools } from '../../execution/LlmExecutionTools';
 import type { ChatPromptResult, CompletionPromptResult, EmbeddingPromptResult, ImagePromptResult } from '../../execution/PromptResult';
@@ -17,13 +17,17 @@ import type { OpenAiCompatibleExecutionToolsNonProxiedOptions } from './OpenAiCo
 export declare abstract class OpenAiCompatibleExecutionTools implements LlmExecutionTools {
     protected readonly options: OpenAiCompatibleExecutionToolsNonProxiedOptions;
     /**
-     * OpenAI API client.
+     * OpenAI client lifecycle and shared request execution behavior.
      */
-    private client;
+    private readonly requestManager;
     /**
-     * Rate limiter instance
+     * Live/hardcoded model lookup shared by all provider variants.
      */
-    private limiter;
+    private readonly modelCatalog;
+    /**
+     * Completion, embedding, and image-generation prompt execution.
+     */
+    private readonly nonChatPromptCaller;
     /**
      * Creates OpenAI compatible Execution Tools.
      *
@@ -41,9 +45,6 @@ export declare abstract class OpenAiCompatibleExecutionTools implements LlmExecu
      * List all available OpenAI compatible models that can be used
      */
     listModels(): Promise<ReadonlyArray<AvailableModel>>;
-    /**
-     * Calls OpenAI compatible API to use a chat model.
-     */
     /**
      * Calls OpenAI compatible API to use a chat model.
      */
@@ -60,26 +61,14 @@ export declare abstract class OpenAiCompatibleExecutionTools implements LlmExecu
      * Calls OpenAI API to use a complete model.
      */
     callCompletionModel(prompt: Pick<Prompt, 'content' | 'parameters' | 'modelRequirements'>): Promise<CompletionPromptResult>;
-    /**
-     * Internal method that handles parameter retry for completion model calls
-     */
-    private callCompletionModelWithRetry;
     /**
      * Calls OpenAI compatible API to use a embedding model
      */
     callEmbeddingModel(prompt: Pick<Prompt, 'content' | 'parameters' | 'modelRequirements'>): Promise<EmbeddingPromptResult>;
-    /**
-     * Internal method that handles parameter retry for embedding model calls
-     */
-    private callEmbeddingModelWithRetry;
     /**
      * Calls OpenAI compatible API to use a image generation model
      */
     callImageGenerationModel(prompt: Prompt): Promise<ImagePromptResult>;
-    /**
-     * Internal method that handles parameter retry for image generation model calls
-     */
-    private callImageGenerationModelWithRetry;
     /**
      * Get the model that should be used as default
      */
@@ -110,12 +99,4 @@ export declare abstract class OpenAiCompatibleExecutionTools implements LlmExecu
      * Default model for image generation variant.
      */
     protected abstract getDefaultImageGenerationModel(): AvailableModel;
-    /**
-     * Makes a request with retry logic for network errors like ECONNRESET
-     */
-    private makeRequestWithNetworkRetry;
-    /**
-     * Determines if an error is retryable (network-related errors)
-     */
-    private isRetryableNetworkError;
 }

package/umd/src/llm-providers/openai/OpenAiCompatibleModelCatalog.d.ts

@@ -0,0 +1,31 @@
+import type OpenAI from 'openai';
+import type { AvailableModel } from '../../execution/AvailableModel';
+import type { string_model_name } from '../../types/string_model_name';
+import type { string_markdown_text } from '../../types/string_markdown';
+import type { string_title } from '../../types/string_title';
+/**
+ * Dependencies required to resolve OpenAI-compatible models.
+ */
+type OpenAiCompatibleModelCatalogOptions = {
+    readonly getTitle: () => string_title & string_markdown_text;
+    readonly getClient: () => Promise<OpenAI>;
+    readonly getHardcodedModels: () => ReadonlyArray<AvailableModel>;
+};
+/**
+ * Resolves model lists and default-model lookup for OpenAI-compatible execution tools.
+ *
+ * @private helper of `OpenAiCompatibleExecutionTools`
+ */
+export declare class OpenAiCompatibleModelCatalog {
+    private readonly options;
+    constructor(options: OpenAiCompatibleModelCatalogOptions);
+    /**
+     * Lists available models by merging the live API list with hardcoded metadata when possible.
+     */
+    listModels(): Promise<ReadonlyArray<AvailableModel>>;
+    /**
+     * Resolves one default model by exact or family-prefix name.
+     */
+    getDefaultModel(defaultModelName: string_model_name): AvailableModel;
+}
+export {};

package/umd/src/llm-providers/openai/OpenAiCompatibleNonChatPromptCaller.d.ts

@@ -0,0 +1,57 @@
+import OpenAI from 'openai';
+import type { AvailableModel } from '../../execution/AvailableModel';
+import type { CompletionPromptResult, EmbeddingPromptResult, ImagePromptResult } from '../../execution/PromptResult';
+import type { Usage } from '../../execution/Usage';
+import type { Prompt } from '../../types/Prompt';
+import type { string_markdown_text } from '../../types/string_markdown';
+import type { string_title } from '../../types/string_title';
+import type { computeOpenAiUsage } from './computeOpenAiUsage';
+/**
+ * Dependencies required to run non-chat OpenAI-compatible prompt variants.
+ */
+type OpenAiCompatibleNonChatPromptCallerOptions = {
+    readonly getTitle: () => string_title & string_markdown_text;
+    readonly isVerbose: boolean | undefined;
+    readonly userId: string | number | undefined;
+    readonly getClient: () => Promise<OpenAI>;
+    readonly executeRateLimitedRequest: <T>(requestFn: () => Promise<T>) => Promise<T>;
+    readonly computeUsage: (...args: Parameters<typeof computeOpenAiUsage>) => Usage;
+    readonly getDefaultCompletionModel: () => AvailableModel;
+    readonly getDefaultEmbeddingModel: () => AvailableModel;
+    readonly getDefaultImageGenerationModel: () => AvailableModel;
+    readonly getHardcodedModels: () => ReadonlyArray<AvailableModel>;
+};
+/**
+ * Executes completion, embedding, and image-generation prompts for OpenAI-compatible providers.
+ *
+ * @private helper of `OpenAiCompatibleExecutionTools`
+ */
+export declare class OpenAiCompatibleNonChatPromptCaller {
+    private readonly options;
+    constructor(options: OpenAiCompatibleNonChatPromptCallerOptions);
+    /**
+     * Calls one OpenAI-compatible completion model.
+     */
+    callCompletionModel(prompt: Pick<Prompt, 'content' | 'parameters' | 'modelRequirements'>): Promise<CompletionPromptResult>;
+    /**
+     * Calls one OpenAI-compatible embedding model.
+     */
+    callEmbeddingModel(prompt: Pick<Prompt, 'content' | 'parameters' | 'modelRequirements'>): Promise<EmbeddingPromptResult>;
+    /**
+     * Calls one OpenAI-compatible image-generation model.
+     */
+    callImageGenerationModel(prompt: Prompt): Promise<ImagePromptResult>;
+    /**
+     * Retries completion requests while stripping unsupported model parameters.
+     */
+    private callCompletionModelWithRetry;
+    /**
+     * Retries embedding requests while stripping unsupported model parameters.
+     */
+    private callEmbeddingModelWithRetry;
+    /**
+     * Retries image-generation requests while stripping unsupported model parameters.
+     */
+    private callImageGenerationModelWithRetry;
+}
+export {};

package/umd/src/llm-providers/openai/OpenAiCompatibleRequestManager.d.ts

@@ -0,0 +1,29 @@
+import OpenAI from 'openai';
+import type { OpenAiCompatibleExecutionToolsNonProxiedOptions } from './OpenAiCompatibleExecutionToolsOptions';
+/**
+ * Manages OpenAI-compatible client creation plus shared retry and rate-limit behavior.
+ *
+ * @private helper of `OpenAiCompatibleExecutionTools`
+ */
+export declare class OpenAiCompatibleRequestManager {
+    private readonly options;
+    private client;
+    private readonly limiter;
+    constructor(options: OpenAiCompatibleExecutionToolsNonProxiedOptions);
+    /**
+     * Returns the lazily initialized OpenAI client configured from execution-tool options.
+     */
+    getClient(): Promise<OpenAI>;
+    /**
+     * Schedules one request through the shared limiter and retry policy.
+     */
+    executeRateLimitedRequest<T>(requestFn: () => Promise<T>): Promise<T>;
+    /**
+     * Retries transient transport errors with exponential backoff.
+     */
+    private makeRequestWithNetworkRetry;
+    /**
+     * Determines whether the thrown error should be retried as a transient network failure.
+     */
+    private isRetryableNetworkError;
+}

package/umd/src/llm-providers/openai/OpenAiVectorStoreFileBatchHandler.d.ts

@@ -0,0 +1,51 @@
+import type OpenAI from 'openai';
+import type { TODO_any } from '../../utils/organization/TODO_any';
+/**
+ * Uploads prepared knowledge-source files and starts vector-store ingestion polling.
+ *
+ * @private helper of `OpenAiVectorStoreHandler`
+ */
+export declare class OpenAiVectorStoreFileBatchHandler {
+    private readonly options;
+    /**
+     * Creates one vector-store file-batch handler instance.
+     */
+    constructor(options: {
+        readonly isVerbose: boolean;
+        readonly getVectorStoresApi: (client: OpenAI) => TODO_any;
+    });
+    /**
+     * Uploads knowledge source files to the vector store and polls until processing completes.
+     */
+    uploadKnowledgeSourceFilesToVectorStore(options: {
+        readonly client: OpenAI;
+        readonly vectorStoreId: string;
+        readonly files: ReadonlyArray<File>;
+        readonly totalBytes: number;
+        readonly maxConcurrency: number;
+        readonly pollIntervalMs: number;
+        readonly uploadTimeoutMs: number;
+        readonly shouldContinueOnVectorStoreStall: boolean;
+        readonly logLabel: string;
+    }): Promise<TODO_any | null>;
+    /**
+     * Uploads the prepared knowledge-source files with bounded concurrency.
+     */
+    private uploadPreparedKnowledgeSourceFiles;
+    /**
+     * Reuses the shared iterator to upload one slice of knowledge-source files.
+     */
+    private uploadPreparedKnowledgeSourceFilesWorker;
+    /**
+     * Uploads one prepared knowledge-source file to OpenAI and records detailed diagnostics.
+     */
+    private uploadPreparedKnowledgeSourceFile;
+    /**
+     * Creates the OpenAI vector-store file batch for the uploaded knowledge-source files.
+     */
+    private createVectorStoreFileBatch;
+    /**
+     * Logs warnings for unexpected vector-store batch metadata right after creation.
+     */
+    private logCreatedVectorStoreFileBatchIssues;
+}

package/umd/src/llm-providers/openai/OpenAiVectorStoreFileBatchPoller.d.ts

@@ -0,0 +1,75 @@
+import type OpenAI from 'openai';
+import type { TODO_any } from '../../utils/organization/TODO_any';
+/**
+ * Metadata for uploaded knowledge source files used for vector store diagnostics.
+ *
+ * @private internal utility of `OpenAiVectorStoreFileBatchPoller`
+ */
+type KnowledgeSourceUploadMetadata = {
+    readonly fileId: string;
+    readonly filename: string;
+    readonly sizeBytes?: number;
+};
+/**
+ * Polls one vector-store file batch until it settles.
+ *
+ * @private helper of `OpenAiVectorStoreHandler`
+ */
+export declare class OpenAiVectorStoreFileBatchPoller {
+    private readonly options;
+    /**
+     * Creates one vector-store file-batch poller instance.
+     */
+    constructor(options: {
+        readonly isVerbose: boolean;
+        readonly getVectorStoresApi: (client: OpenAI) => TODO_any;
+    });
+    /**
+     * Polls the created vector-store batch until ingestion completes, fails, or times out.
+     */
+    pollVectorStoreFileBatchUntilSettled(options: {
+        readonly client: OpenAI;
+        readonly vectorStoreId: string;
+        readonly batch: TODO_any;
+        readonly expectedBatchId: string;
+        readonly isExpectedBatchIdValid: boolean;
+        readonly uploadedFiles: ReadonlyArray<KnowledgeSourceUploadMetadata>;
+        readonly pollIntervalMs: number;
+        readonly uploadTimeoutMs: number;
+        readonly shouldContinueOnVectorStoreStall: boolean;
+        readonly logLabel: string;
+    }): Promise<TODO_any>;
+    /**
+     * Logs vector store file batch diagnostics to help trace ingestion stalls or failures.
+     */
+    private logVectorStoreFileBatchDiagnostics;
+    /**
+     * Resolves the next batch id to poll and retrieves the freshest OpenAI batch snapshot.
+     */
+    private retrieveVectorStoreFileBatchForPolling;
+    /**
+     * Normalizes the batch identifier returned by OpenAI and logs unusual id situations once.
+     */
+    private resolveVectorStoreFileBatchId;
+    /**
+     * Tracks observed polling progress and emits throttled verbose status logs.
+     */
+    private trackVectorStoreFileBatchProgress;
+    /**
+     * Emits deeper diagnostics when vector-store ingestion appears stalled for too long.
+     */
+    private maybeLogStalledVectorStoreFileBatch;
+    /**
+     * Handles terminal vector-store batch states that do not require further polling.
+     */
+    private handleVectorStoreFileBatchTerminalState;
+    /**
+     * Stops polling once the batch exceeds the configured timeout and handles optional cancellation.
+     */
+    private handleVectorStoreFileBatchTimeout;
+    /**
+     * Attempts to cancel a timed-out vector-store batch and logs any unusual id situation.
+     */
+    private cancelVectorStoreFileBatchAfterTimeout;
+}
+export {};