@promptbook/javascript 0.111.0-7 → 0.112.0-11

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

@@ -19,17 +19,65 @@ export type OpenAiSpeechRecognitionOptions = {
 export declare class OpenAiSpeechRecognition implements SpeechRecognition {
     private readonly options;
     private mediaRecorder;
+    private mediaStream;
     private audioContext;
+    private mediaStreamSource;
     private analyser;
-    private silenceTimeout;
+    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

@@ -1,4 +1,8 @@
 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
  *
@@ -36,6 +40,10 @@ export type SpeechRecognitionStartOptions = {
      * @default true
      */
     readonly interimResults?: boolean;
+    /**
+     * Enables a more sensitive profile for quiet speech.
+     */
+    readonly whisperMode?: boolean;
 };
 /**
  * Current state of the speech recognition
@@ -46,6 +54,8 @@ export type SpeechRecognitionState = 'IDLE' | 'STARTING' | 'RECORDING' | 'TRANSC
  */
 export type SpeechRecognitionEvent = {
     readonly type: 'START';
+} | {
+    readonly type: 'TRANSCRIBING';
 } | {
     readonly type: 'RESULT';
     readonly text: string;
@@ -53,6 +63,10 @@ export type SpeechRecognitionEvent = {
 } | {
     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

@@ -1,5 +1,45 @@
 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.
  *
@@ -22,6 +62,18 @@ export type ToolCall = {
      * 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.
      */
@@ -34,6 +86,10 @@ export type ToolCall = {
      * 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.

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;

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

@@ -0,0 +1,39 @@
+/**
+ * Semantic helper
+ *
+ * For example `"C:/Users/me/work/collboard/modules-sdk/src/colldev/commands/develop/ColldevDevelop.tsx"`
+ */
+export type string_absolute_filename = string;
+/**
+ * Semantic helper
+ *
+ * For example `"./src/colldev/commands/develop/ColldevDevelop.tsx"`
+ */
+export type string_relative_filename = string;
+/**
+ * Semantic helper
+ */
+export type string_filename = string_absolute_filename | string_relative_filename;
+/**
+ * Semantic helper
+ *
+ * For example `"C:/Users/me/work/collboard/modules-sdk/src/colldev/commands/develop/ColldevDevelop.tsx"`
+ */
+export type string_absolute_dirname = string;
+/**
+ * Semantic helper
+ *
+ * For example `"./src/colldev/commands/develop/ColldevDevelop.tsx"`
+ */
+export type string_relative_dirname = string;
+/**
+ * Semantic helper
+ */
+export type string_dirname = string_absolute_dirname | string_relative_dirname;
+/**
+ * Semantic helper
+ *
+ * For example `"C:/Users/me/AppData/Local/Pandoc/pandoc.exe"`
+ * For example `"C:/Program Files/LibreOffice/program/swriter.exe"`
+ */
+export type string_executable_path = string;

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

@@ -0,0 +1,29 @@
+import type { string_filename } from './string_filename';
+import type { string_markdown } from './string_markdown';
+import type { string_url } from './string_url';
+/**
+ * Source of one knowledge piece.
+ *
+ * It can be a link, a relative path to file or direct text content.
+ *
+ * For example `"https://pavolhejny.com/"`
+ * For example `"./pavol-hejny-cv.pdf"`
+ * For example `"Pavol Hejný has web https://pavolhejny.com/"`
+ * For example `"Pavol Hejný is web developer and creator of Promptbook and Collboard"`
+ *
+ * Note: Distinguishes between `string_knowledge_source_content` and `string_knowledge_source_link`:
+ * `string_knowledge_source_content` refers to the actual content or source of knowledge
+ * `string_knowledge_source_link` refers to a reference or link to the knowledge source
+ */
+export type string_knowledge_source_content = string_knowledge_source_link | string_markdown;
+/**
+ * One link to a knowledge source.
+ *
+ * It can be a URL or relative path.
+ *
+ * For example `"https://pavolhejny.com/"`
+ * For example `"./pavol-hejny-cv.pdf"`
+ *
+ * Note: string_knowledge_source_link refers to a reference or link to the knowledge source, while string_knowledge_source_content can be the link or the actual content.
+ */
+export type string_knowledge_source_link = string_url | string_filename;

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

@@ -0,0 +1,138 @@
+/**
+ * Semantic helper
+ *
+ * For example `"<div>Hello World!</div>"`
+ */
+export type string_html = string;
+/**
+ * Semantic helper
+ *
+ * For example `"<foo>bar</foo>"`
+ *
+ *
+ * TODO: [🎞️] Probably use some object-based method for working with XMLs
+ */
+export type string_xml = string;
+/**
+ * Semantic helper
+ *
+ * For example `"**Hello** World!"`
+ *
+ * @public exported from `@promptbook/markdown-utils`
+ */
+export type string_markdown = string;
+/**
+ * Semantic helper
+ *
+ * Markdown text with exactly ONE heading on first line NO less NO more
+ *
+ * @public exported from `@promptbook/markdown-utils`
+ */
+export type string_markdown_section = string;
+/**
+ * Semantic helper
+ *
+ * Markdown without any headings like h1, h2
+ * BUT with formatting, lists, blockquotes, blocks, etc. is allowed
+ *
+ * @public exported from `@promptbook/markdown-utils`
+ */
+export type string_markdown_section_content = string;
+/**
+ * Semantic helper
+ *
+ * Markdown text without any structure like h1, h2, lists, blockquotes, blocks, etc.
+ * BUT with bold, italic, etc. is allowed
+ *
+ * For example `"**Hello** World!"`
+ *
+ * @public exported from `@promptbook/markdown-utils`
+ */
+export type string_markdown_text = string;
+/**
+ * Semantic helper
+ *
+ * Markdown code block language
+ *
+ * For example ```js -> `"js"`
+ *
+ * @public exported from `@promptbook/markdown-utils`
+ */
+export type string_markdown_codeblock_language = 'book' | 'markdown' | 'text' | 'javascript' | 'css' | 'json';
+/**
+ * A URL pointing to Promptbook documentation or a specific discussion.
+ *
+ * For example: `https://github.com/webgptorg/promptbook/discussions/123`
+ */
+export type string_promptbook_documentation_url = `https://github.com/webgptorg/promptbook/discussions/${number | `@@${string}`}`;
+/**
+ * Semantic helper
+ *
+ * For example `.foo{border: 1px solid red}`
+ */
+export type string_css = string;
+/**
+ * Semantic helper
+ *
+ * For example `"<svg><circle cx="50" cy="50" r="40" stroke="green" stroke-width="4" fill="yellow" /></svg>"`
+ */
+export type string_svg = string;
+/**
+ * Semantic helper
+ *
+ * For example `console.info("Hello World!")` or `print("Hello World!")`
+ */
+export type string_script = string;
+/**
+ * Semantic helper
+ *
+ * For example `console.info("Hello World!")`
+ */
+export type string_javascript = string;
+/**
+ * Semantic helper
+ *
+ * For example `console.info("Hello World!" as string)`
+ */
+export type string_typescript = string;
+/**
+ * Semantic helper for JSON strings
+ *
+ * Note: TType is a type of the JSON object inside the string
+ *
+ * For example `{"foo": "bar"}`
+ */
+export type string_json<TType> = string & {
+    _type: 'string_json';
+    scheme: TType;
+};
+/**
+ * Semantic helper
+ *
+ * For example `menu`
+ */
+export type string_css_class = string;
+/**
+ * Semantic helper
+ *
+ * For example `border`
+ */
+export type string_css_property = string;
+/**
+ * Semantic helper
+ *
+ * For example `"Arial, sans-serif"`
+ */
+export type string_fonts = string;
+/**
+ * Semantic helper
+ *
+ * For example `13px`
+ */
+export type string_css_value = string | number;
+/**
+ * Semantic helper
+ *
+ * For example `.foo`
+ */
+export type string_css_selector = string;

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

@@ -0,0 +1,170 @@
+import type { TupleToUnion } from 'type-fest';
+import { RESERVED_PARAMETER_NAMES } from '../constants';
+import type { really_unknown } from '../utils/organization/really_unknown';
+import { string_base_58, string_sha256 } from './string_sha256';
+/**
+ * Semantic helper
+ */
+export type string_business_category_name = 'restaurant' | 'grocery' | 'person' | 'conference' | string;
+/**
+ * Semantic helper
+ *
+ * For example `"gpt-4"`
+ */
+export type string_model_name = 'gpt-4' | 'gpt-4-0314' | 'gpt-4-0613' | 'gpt-4-32k' | 'gpt-4-32k-0314' | 'gpt-4-32k-0613' | 'gpt-3.5-turbo' | 'gpt-3.5-turbo-16k' | 'gpt-3.5-turbo-0301' | 'gpt-3.5-turbo-0613' | 'gpt-3.5-turbo-16k-0613' | string;
+/**
+ * Semantic helper
+ *
+ * For example `"How many eyes does a cat have?"`
+ */
+export type string_prompt = string;
+/**
+ * Semantic helper
+ *
+ * For example `"A cat wearing a hat"`
+ */
+export type string_prompt_image = string;
+/**
+ * Semantic helper
+ *
+ * For example `"A cat wearing a {item}"`
+ */
+export type string_template = string;
+/**
+ * Semantic helper
+ *
+ * For example `"How many hats does the cat wear?"`
+ */
+export type string_text_prompt = string_prompt;
+/**
+ * Semantic helper
+ *
+ * For example `"How many hats does the cat wear?"`
+ */
+export type string_chat_prompt = string_text_prompt;
+/**
+ * Semantic helper
+ *
+ * For example `"You are an AI assistant. You are here to help me with my work."`
+ */
+export type string_system_message = string_text_prompt;
+/**
+ * Semantic helper
+ *
+ * For example `"Following is a text about cats: Once upon a time there was a cat"`
+ */
+export type string_completion_prompt = string_text_prompt;
+/**
+ * Semantic helper
+ *
+ * For example `"index"` or `"explanation"`
+ * Always in kebab-case
+ */
+export type string_page = 'index' | string;
+/**
+ * Semantic helper
+ *
+ * For example `"a"`
+ */
+export type string_char = string;
+/**
+ * Semantic helper
+ * Unique identifier of anything
+ *
+ * For example `"ainautes"`
+ */
+export type string_name = string;
+/**
+ * Semantic helper
+ * Unique identifier of anything
+ *
+ * For example `"eventTitle"`
+ */
+export type string_parameter_name = string_name;
+/**
+ * Semantic helper
+ * Unique identifier of parameter
+ *
+ * For example `"DevConf 2024"`
+ */
+export type string_parameter_value = string;
+/**
+ * Parameters of the pipeline
+ *
+ * There are three types of parameters:
+ * - **INPUT PARAMETERs** are required to execute the pipeline.
+ * - **Intermediate parameters** are used internally in the pipeline.
+ * - **OUTPUT PARAMETERs** are not used internally in the pipeline, but are returned as the result of the pipeline execution.
+ *
+ * Note: [🚉] This is fully serializable as JSON
+ * @see https://ptbk.io/parameters
+ */
+export type Parameters = Exclude<Record<string_parameter_name, string_parameter_value>, ReservedParameters>;
+/**
+ * Parameters to pass to execution of the pipeline
+ *
+ * Note: [🚉] This should be fully serializable as JSON
+ * @see https://ptbk.io/parameters
+ */
+export type InputParameters = Exclude<Record<string_parameter_name, really_unknown>, ReservedParameters>;
+/**
+ * Semantic helper
+ * Unique identifier of reserved parameter
+ *
+ * For example `"context"`
+ */
+export type string_reserved_parameter_name = TupleToUnion<typeof RESERVED_PARAMETER_NAMES>;
+/**
+ * Represents a mapping of reserved parameter names to their values.
+ * Reserved parameters are used internally by the pipeline and should not be set by users.
+ *
+ * Note: [🚉] This is fully serializable as JSON
+ */
+export type ReservedParameters = Record<string_reserved_parameter_name, string_parameter_value>;
+/**
+ * Semantic helper
+ * Title of anything
+ *
+ * For example `"Ai*nautes"`
+ */
+export type string_title = string;
+/**
+ * Semantic helper
+ *
+ * For example `"My AI Assistant"`
+ *
+ * TODO: !!!! Brand the type
+ */
+export type string_agent_name = string;
+/**
+ * Semantic helper
+ *
+ * For example `"My AI Assistant"`
+ */
+export type string_agent_name_in_book = string;
+/**
+ * Semantic helper
+ *
+ * For example `"b126926439c5fcb83609888a11283723c1ef137c0ad599a77a1be81812bd221d"`
+ */
+export type string_agent_hash = string_sha256;
+/**
+ * Semantic helper
+ *
+ * For example `"3mJr7AoUXx2Wqd"`
+ *
+ * TODO: !!!! Brand the type
+ */
+export type string_agent_permanent_id = string_base_58;
+/**
+ * Unstructured description of the persona
+ *
+ * For example `"Skilled copywriter"`
+ */
+export type string_persona_description = string;
+/**
+ * Unstructured description of the model
+ *
+ * For example `"Model with logical reasoning and creative mindset"`
+ */
+export type string_model_description = string;