@promptbook/javascript 0.111.0-4 → 0.112.0-11

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

@@ -0,0 +1,126 @@
+import 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';
+import type { Usage } from '../../execution/Usage';
+import type { Prompt } from '../../types/Prompt';
+import type { string_markdown, string_markdown_text, string_model_name, string_title } from '../../types/typeAliases';
+import { computeOpenAiUsage } from './computeOpenAiUsage';
+import type { OpenAiCompatibleExecutionToolsNonProxiedOptions } from './OpenAiCompatibleExecutionToolsOptions';
+/**
+ * Execution Tools for calling OpenAI API or other OpenAI compatible provider
+ *
+ * @public exported from `@promptbook/openai`
+ */
+export declare abstract class OpenAiCompatibleExecutionTools implements LlmExecutionTools {
+    protected readonly options: OpenAiCompatibleExecutionToolsNonProxiedOptions;
+    /**
+     * OpenAI API client.
+     */
+    private client;
+    /**
+     * Rate limiter instance
+     */
+    private limiter;
+    /**
+     * Creates OpenAI compatible Execution Tools.
+     *
+     * @param options which are relevant are directly passed to the OpenAI compatible client
+     */
+    constructor(options: OpenAiCompatibleExecutionToolsNonProxiedOptions);
+    abstract get title(): string_title & string_markdown_text;
+    abstract get description(): string_markdown;
+    getClient(): Promise<OpenAI>;
+    /**
+     * Check the `options` passed to `constructor`
+     */
+    checkConfiguration(): Promise<void>;
+    /**
+     * 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.
+     */
+    callChatModel(prompt: Prompt): Promise<ChatPromptResult>;
+    /**
+     * Calls OpenAI compatible API to use a chat model with streaming.
+     */
+    callChatModelStream(prompt: Prompt, onProgress: (chunk: ChatPromptResult) => void, options?: CallChatModelStreamOptions): Promise<ChatPromptResult>;
+    /**
+     * Internal method that handles parameter retry for chat model calls
+     */
+    private callChatModelWithRetry;
+    /**
+     * 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
+     */
+    protected getDefaultModel(defaultModelName: string_model_name): AvailableModel;
+    /**
+     * List all available models (non dynamically)
+     *
+     * Note: Purpose of this is to provide more information about models than standard listing from API
+     */
+    protected abstract get HARDCODED_MODELS(): ReadonlyArray<AvailableModel>;
+    /**
+     * Computes the usage of the OpenAI API based on the response from OpenAI Compatible API
+     */
+    protected abstract computeUsage(...args: Parameters<typeof computeOpenAiUsage>): Usage;
+    /**
+     * Default model for chat variant.
+     */
+    protected abstract getDefaultChatModel(): AvailableModel;
+    /**
+     * Default model for completion variant.
+     */
+    protected abstract getDefaultCompletionModel(): AvailableModel;
+    /**
+     * Default model for completion variant.
+     */
+    protected abstract getDefaultEmbeddingModel(): AvailableModel;
+    /**
+     * 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;
+}
+/**
+ * TODO: [🛄] Some way how to re-wrap the errors from `OpenAiCompatibleExecutionTools`
+ * TODO: [🛄] Maybe make custom `OpenAiCompatibleError`
+ * TODO: [🧠][🈁] Maybe use `isDeterministic` from options
+ * TODO: [🧠][🌰] Allow to pass `title` for tracking purposes
+ * TODO: [🧠][🦢] Make reverse adapter from LlmExecutionTools to OpenAI-compatible:
+ */

package/esm/src/llm-providers/openai/computeOpenAiUsage.d.ts

@@ -0,0 +1,20 @@
+import type OpenAI from 'openai';
+import type { PartialDeep } from 'type-fest';
+import type { UncertainNumber } from '../../execution/UncertainNumber';
+import type { Usage } from '../../execution/Usage';
+import type { Prompt } from '../../types/Prompt';
+/**
+ * Computes the usage of the OpenAI API based on the response from OpenAI
+ *
+ * @param promptContent The content of the prompt
+ * @param resultContent The content of the result (for embedding prompts or failed prompts pass empty string)
+ * @param rawResponse The raw response from OpenAI API
+ * @param duration The duration of the execution
+ * @throws {PipelineExecutionError} If the usage is not defined in the response from OpenAI
+ * @private internal utility of `OpenAiExecutionTools`
+ */
+export declare function computeOpenAiUsage(promptContent: Prompt['content'], // <- Note: Intentionally using [] to access type properties to bring jsdoc from Prompt/PromptResult to consumer
+resultContent: string, rawResponse: PartialDeep<Pick<OpenAI.Chat.Completions.ChatCompletion | OpenAI.Completions.Completion | OpenAI.Embeddings.CreateEmbeddingResponse, 'model' | 'usage'>>, duration?: UncertainNumber): Usage;
+/**
+ * TODO: [🤝] DRY Maybe some common abstraction between `computeOpenAiUsage` and `computeAnthropicClaudeUsage`
+ */

package/esm/src/pipeline/prompt-notation/helpers/ParameterEscaping.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Normalizes a JSON string so it can be safely rendered without double escaping.
+ *
+ * @param value Candidate JSON string.
+ * @private function of ParameterEscaping
+ */
+declare function normalizeJsonString(value: string): string | null;
+/**
+ * Hides brackets in a string to avoid confusion with template parameters.
+ *
+ * @param value Input string with literal brackets.
+ * @private function of ParameterEscaping
+ */
+declare function hideBrackets(value: string): string;
+/**
+ * Restores hidden brackets.
+ *
+ * @param value String with hidden brackets.
+ * @private function of ParameterEscaping
+ */
+declare function restoreBrackets(value: string): string;
+/**
+ * Decides whether a parameter can be inlined safely.
+ *
+ * @param value Parameter rendered as string.
+ * @private function of ParameterEscaping
+ */
+declare function shouldInlineParameterValue(value: string): boolean;
+/**
+ * Escapes prompt parameter content to avoid breaking the template structure.
+ *
+ * @param value Parameter value to escape.
+ * @param options Escape options for additional characters.
+ * @private function of ParameterEscaping
+ */
+declare function escapePromptParameterValue(value: string, options: {
+    includeBraces: boolean;
+}): string;
+/**
+ * Collection of utilities that keep prompt parameters safe during interpolation.
+ *
+ * @private helper of prompt notation
+ */
+export declare const ParameterEscaping: {
+    normalizeJsonString: typeof normalizeJsonString;
+    hideBrackets: typeof hideBrackets;
+    restoreBrackets: typeof restoreBrackets;
+    shouldInlineParameterValue: typeof shouldInlineParameterValue;
+    escapePromptParameterValue: typeof escapePromptParameterValue;
+};
+export {};

package/esm/src/pipeline/prompt-notation/helpers/ParameterNaming.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Builds placeholder names while avoiding collisions with parameter content.
+ *
+ * @param values Parameter values to scan for conflicting tokens.
+ * @private function of ParameterNaming
+ */
+declare function buildParameterNames(values: string[]): string[];
+/**
+ * Provides naming utilities for prompt parameters.
+ *
+ * @private helper of prompt notation
+ */
+export declare const ParameterNaming: {
+    buildParameterNames: typeof buildParameterNames;
+};
+export {};

package/esm/src/pipeline/prompt-notation/helpers/ParameterSection.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Represents a structured parameter entry.
+ *
+ * @private type of ParameterSection
+ */
+type StructuredParameterEntry = {
+    name: string;
+    value: string;
+    jsonValue: string | null;
+};
+/**
+ * Formats the placeholder used in the prompt body for a parameter.
+ *
+ * @param name Parameter placeholder name.
+ * @private function of ParameterSection
+ */
+declare function formatParameterPlaceholder(name: string): string;
+/**
+ * Builds the structured parameters section appended to the prompt.
+ *
+ * @param items Parameter entries to include.
+ * @private function of ParameterSection
+ */
+declare function buildParametersSection(items: StructuredParameterEntry[]): string;
+/**
+ * Provides helpers for rendering structured parameter placeholders.
+ *
+ * @private helper of prompt notation
+ */
+export declare const ParameterSection: {
+    formatParameterPlaceholder: typeof formatParameterPlaceholder;
+    buildParametersSection: typeof buildParametersSection;
+};
+export {};

package/esm/src/playground/playground.d.ts

@@ -0,0 +1,6 @@
+#!/usr/bin/env ts-node
+export {};
+/**
+ * TODO: !!!!!!! Extract to `other` and append DigitalOcean instructions
+ * Note: [⚫] Code in this file should never be published in any package
+ */

package/esm/src/speech-recognition/OpenAiSpeechRecognition.d.ts

@@ -0,0 +1,83 @@
+import type { SpeechRecognition, SpeechRecognitionEvent, SpeechRecognitionStartOptions, SpeechRecognitionState } from '../types/SpeechRecognition';
+/**
+ * Options for OpenAiSpeechRecognition
+ */
+export type OpenAiSpeechRecognitionOptions = {
+    /**
+     * OpenAI API base URL or proxy endpoint
+     * @default '/api/openai/v1'
+     */
+    readonly baseUrl?: string;
+};
+/**
+ * Speech recognition using OpenAI Whisper API to transcribe audio into text
+ *
+ * @private because it requires server-client communication with a proxy endpoint
+ *
+ * Note: This implementation uses a server-side proxy to avoid exposing the OpenAI API key on the client.
+ */
+export declare class OpenAiSpeechRecognition implements SpeechRecognition {
+    private readonly options;
+    private mediaRecorder;
+    private mediaStream;
+    private audioContext;
+    private mediaStreamSource;
+    private analyser;
+    private silenceCheckAnimationFrameId;
+    private audioChunks;
+    private callbacks;
+    private _state;
+    private pendingStopDuringStart;
+    private isStopping;
+    private recordingStartedAt;
+    private lastSpeechDetectedAt;
+    private ambientNoiseLevel;
+    private voiceLevelMultiplier;
+    private silenceAutoStopDelayMs;
+    get state(): SpeechRecognitionState;
+    constructor(options?: OpenAiSpeechRecognitionOptions);
+    $start(options?: SpeechRecognitionStartOptions): Promise<void>;
+    $stop(): void;
+    private transcribe;
+    /**
+     * Handles `MediaRecorder.onstop` by releasing audio resources and forwarding the clip to transcription.
+     *
+     * @param language Optional language hint for Whisper.
+     */
+    private handleRecorderStop;
+    /**
+     * Starts continuous silence detection and auto-stops recording shortly after speech ends.
+     */
+    private startSilenceDetection;
+    /**
+     * Stops the silence-detection animation loop.
+     */
+    private stopSilenceDetection;
+    /**
+     * Measures current voice intensity from the waveform (`0` silent .. `1` loud).
+     *
+     * @param sampleBuffer Buffer reused across animation frames.
+     * @returns RMS-based volume level.
+     */
+    private measureVoiceLevel;
+    /**
+     * Returns an adaptive speech threshold based on recently observed ambient noise.
+     */
+    private resolveAdaptiveVoiceThreshold;
+    /**
+     * Updates the rolling ambient noise estimate during silent frames.
+     *
+     * @param voiceLevel Observed frame loudness.
+     */
+    private updateAmbientNoiseLevel;
+    /**
+     * Releases browser audio resources so the microphone is fully freed for other apps.
+     */
+    private releaseRecordingResources;
+    /**
+     * Stops all microphone tracks if an active media stream exists.
+     */
+    private stopMediaStreamTracks;
+    subscribe(callback: (event: SpeechRecognitionEvent) => void): () => void;
+    private emit;
+}

package/esm/src/types/SpeechRecognition.d.ts

@@ -0,0 +1,72 @@
+import type { string_language } from './typeAliases';
+/**
+ * Stable speech-recognition error codes consumed by UI and telemetry.
+ */
+export type SpeechRecognitionErrorCode = 'permission-denied' | 'audio-capture' | 'network' | 'no-speech' | 'aborted' | 'unsupported-browser' | 'unknown';
+/**
+ * Interface for speech-to-text recognition
+ *
+ * @🚉 fully serializable as JSON
+ */
+export type SpeechRecognition = {
+    /**
+     * Start the speech recognition
+     */
+    $start(options: SpeechRecognitionStartOptions): void;
+    /**
+     * Stop the speech recognition
+     */
+    $stop(): void;
+    /**
+     * Current state of the speech recognition
+     */
+    readonly state: SpeechRecognitionState;
+    /**
+     * Subscribe to speech recognition events
+     */
+    subscribe(callback: (event: SpeechRecognitionEvent) => void): () => void;
+};
+/**
+ * Options for starting speech recognition
+ */
+export type SpeechRecognitionStartOptions = {
+    /**
+     * Language for speech recognition
+     * @default 'en-US'
+     */
+    readonly language?: string_language;
+    /**
+     * Whether to return interim results
+     * @default true
+     */
+    readonly interimResults?: boolean;
+    /**
+     * Enables a more sensitive profile for quiet speech.
+     */
+    readonly whisperMode?: boolean;
+};
+/**
+ * Current state of the speech recognition
+ */
+export type SpeechRecognitionState = 'IDLE' | 'STARTING' | 'RECORDING' | 'TRANSCRIBING' | 'ERROR';
+/**
+ * Event emitted by speech recognition
+ */
+export type SpeechRecognitionEvent = {
+    readonly type: 'START';
+} | {
+    readonly type: 'TRANSCRIBING';
+} | {
+    readonly type: 'RESULT';
+    readonly text: string;
+    readonly isFinal: boolean;
+} | {
+    readonly type: 'ERROR';
+    readonly message: string;
+    readonly code?: SpeechRecognitionErrorCode;
+    readonly providerId?: string;
+    readonly canRetry?: boolean;
+    readonly canOpenBrowserSettings?: boolean;
+} | {
+    readonly type: 'STOP';
+};

package/esm/src/types/ToolCall.d.ts

@@ -0,0 +1,172 @@
+import type { TODO_any } from '../utils/organization/TODO_any';
+import type { string_date_iso8601 } from './typeAliases';
+/**
+ * Explicit lifecycle state of one tool call snapshot.
+ */
+export type ToolCallState = 'PENDING' | 'PARTIAL' | 'COMPLETE' | 'ERROR';
+/**
+ * Severity level attached to one tool-call log entry.
+ */
+export type ToolCallLogLevel = 'info' | 'warning' | 'error';
+/**
+ * Incremental log entry emitted while one tool call is running.
+ *
+ * These logs are designed to stream progressively so chat chips can expose
+ * partial details before the final result is available.
+ */
+export type ToolCallLogEntry = {
+    /**
+     * Timestamp when this log entry was observed.
+     */
+    readonly createdAt?: string_date_iso8601;
+    /**
+     * Stable machine-friendly log kind such as `request`, `browser-action`, or `result`.
+     */
+    readonly kind?: string;
+    /**
+     * Severity level used by UI renderers.
+     */
+    readonly level?: ToolCallLogLevel;
+    /**
+     * Short human-readable title for the log row.
+     */
+    readonly title?: string;
+    /**
+     * Human-readable message associated with the log row.
+     */
+    readonly message?: string;
+    /**
+     * Optional structured payload for advanced/raw inspection.
+     */
+    readonly payload?: TODO_any;
+};
+/**
+ * Represents a single tool call with its inputs, outputs, and timing.
+ *
+ * Note: This is fully serializable as JSON.
+ */
+export type ToolCall = {
+    /**
+     * Name of the tool.
+     */
+    readonly name: string;
+    /**
+     * Arguments for the tool call.
+     */
+    readonly arguments?: string | Record<string, TODO_any>;
+    /**
+     * Result of the tool call.
+     */
+    readonly result?: TODO_any;
+    /**
+     * Raw tool call payload from the model.
+     */
+    readonly rawToolCall?: TODO_any;
+    /**
+     * Explicit lifecycle state of this tool call snapshot.
+     *
+     * When omitted, consumers should infer the state from available result/error data.
+     */
+    readonly state?: ToolCallState;
+    /**
+     * Idempotency identifier that should not change between partial updates of the same tool call.
+     *
+     * @public exported from `@promptbook/types`
+     */
+    readonly idempotencyKey?: string;
+    /**
+     * Timestamp when the tool call was initiated.
+     */
+    readonly createdAt?: string_date_iso8601;
+    /**
+     * Errors thrown during tool execution.
+     */
+    readonly errors?: ReadonlyArray<TODO_any>;
+    /**
+     * Warnings reported during tool execution.
+     */
+    readonly warnings?: ReadonlyArray<TODO_any>;
+    /**
+     * Incremental logs observed while the tool call is running.
+     */
+    readonly logs?: ReadonlyArray<ToolCallLogEntry>;
+};
+/**
+ * Breakdown of teacher-learned commitment categories for self-learning.
+ */
+export type SelfLearningCommitmentTypeCounts = {
+    /**
+     * Total number of learned commitments.
+     */
+    readonly total: number;
+    /**
+     * Count of knowledge commitments.
+     */
+    readonly knowledge: number;
+    /**
+     * Count of rule commitments.
+     */
+    readonly rule: number;
+    /**
+     * Count of persona commitments.
+     */
+    readonly persona: number;
+    /**
+     * Count of other commitment types.
+     */
+    readonly other: number;
+};
+/**
+ * Summary of the teacher review step during self-learning.
+ */
+export type SelfLearningTeacherSummary = {
+    /**
+     * Indicates whether the teacher step was used.
+     */
+    readonly used: boolean;
+    /**
+     * Commitment breakdown produced by the teacher step.
+     */
+    readonly commitmentTypes: SelfLearningCommitmentTypeCounts;
+    /**
+     * Normalized commitment lines produced by the teacher step.
+     */
+    readonly commitments?: ReadonlyArray<string>;
+};
+/**
+ * Result payload for the self-learning tool call.
+ */
+export type SelfLearningToolCallResult = {
+    /**
+     * Indicates whether self-learning completed successfully.
+     */
+    readonly success: boolean;
+    /**
+     * Timestamp for when self-learning started.
+     */
+    readonly startedAt?: string_date_iso8601;
+    /**
+     * Timestamp for when self-learning finished.
+     */
+    readonly completedAt?: string_date_iso8601;
+    /**
+     * Number of conversation examples saved from this turn.
+     */
+    readonly samplesAdded?: number;
+    /**
+     * Summary of the teacher review step.
+     */
+    readonly teacher?: SelfLearningTeacherSummary;
+};
+/**
+ * Tool call name emitted while preparing a GPT assistant for an agent.
+ *
+ * @public exported from `@promptbook/types`
+ */
+export declare const ASSISTANT_PREPARATION_TOOL_CALL_NAME = "assistant_preparation";
+/**
+ * Checks whether a tool call is the assistant preparation marker.
+ *
+ * @public exported from `@promptbook/types`
+ */
+export declare function isAssistantPreparationToolCall(toolCall: ToolCall): boolean;

package/esm/src/types/number_usd.d.ts

@@ -0,0 +1,110 @@
+/**
+ * Semantic helper for US Dollars
+ */
+export type number_usd = number;
+/**
+ * Semantic helper for incremental IDs
+ */
+export type number_id = number_integer & (number_positive | 0);
+/**
+ * Semantic helper for number of rows and columns
+ */
+export type number_linecol_number = number_integer & number_positive;
+/**
+ * Semantic helper for number of tokens
+ */
+export type number_tokens = number_integer & (number_positive | 0);
+/**
+ * Positive number helper.
+ */
+export type number_positive = number;
+/**
+ * Negative number helper.
+ */
+export type number_negative = number;
+/**
+ * Integer number helper.
+ */
+export type number_integer = number;
+/**
+ * TCP/UDP port helper.
+ */
+export type number_port = number_positive & number_integer;
+/**
+ * Semantic helper;
+ * Percentage from 0 to 1 (100%) (and below and above)
+ */
+export type number_percent = number;
+/**
+ * Semantic helper;
+ * Model temperature
+ */
+export type number_model_temperature = number_percent;
+/**
+ * Semantic helper;
+ * Seed for random generator
+ *
+ * Percentage from 0 to 1 (100%)
+ * TODO: Is seed (in OpenAI) number from 0 to 1?
+ */
+export type number_seed = number_percent;
+/**
+ * Likeness of the wallpaper
+ *
+ * - 👍 is equivalent to 1
+ * - 👎 is equivalent to -1
+ * - ❤ is equivalent to more than 1
+ */
+export type number_likeness = number;
+/**
+ * Milliseconds helper.
+ */
+export type number_milliseconds = number_integer;
+/**
+ * Seconds helper.
+ */
+export type number_seconds = number;
+/**
+ * Minutes helper.
+ */
+export type number_minutes = number;
+/**
+ * Hours helper.
+ */
+export type number_hours = number;
+/**
+ * Days helper.
+ */
+export type number_days = number;
+/**
+ * Weeks helper.
+ */
+export type number_weeks = number;
+/**
+ * Months helper.
+ */
+export type number_months = number;
+/**
+ * Years helper.
+ */
+export type number_years = number;
+/**
+ * Byte count helper.
+ */
+export type number_bytes = number_integer & number_positive;
+/**
+ * Kilobyte count helper.
+ */
+export type number_kilobytes = number_positive;
+/**
+ * Megabyte count helper.
+ */
+export type number_megabytes = number_positive;
+/**
+ * Gigabyte count helper.
+ */
+export type number_gigabytes = number_positive;
+/**
+ * Terabyte count helper.
+ */
+export type number_terabytes = number_positive;