@promptbook/openai 0.92.0-22 → 0.92.0-24

package/esm/typings/src/execution/createPipelineExecutor/30-executeFormatSubvalues.d.ts

@@ -3,18 +3,23 @@ import type { TODO_any } from '../../utils/organization/TODO_any';
 import type { PipelineExecutorResult } from '../PipelineExecutorResult';
 import type { ExecuteAttemptsOptions } from './40-executeAttempts';
 /**
- * @@@
+ * Options for executing a pipeline task that involves formatting subvalues (e.g., iterating over CSV rows).
+ * Extends ExecuteAttemptsOptions with a progress callback.
  *
  * @private internal type of `executeFormatSubvalues`
  */
 type ExecuteFormatCellsOptions = ExecuteAttemptsOptions & {
     /**
-     * @@@
+     * Callback invoked with partial results as the execution progresses.
      */
     readonly onProgress: (newOngoingResult: PartialDeep<PipelineExecutorResult>) => Promisable<void>;
 };
 /**
- * @@@
+ * Executes a pipeline task that requires mapping or iterating over subvalues of a parameter (such as rows in a CSV).
+ * Handles format and subformat resolution, error handling, and progress reporting.
+ *
+ * @param options - Options for execution, including task details and progress callback.
+ * @returns The result of the subvalue mapping or execution attempts.
  *
  * @private internal utility of `createPipelineExecutor`
  */

package/esm/typings/src/execution/createPipelineExecutor/getReservedParametersForTask.d.ts

@@ -5,7 +5,7 @@ import type { Parameters } from '../../types/typeAliases';
 import type { ReservedParameters } from '../../types/typeAliases';
 import type { ExecutionTools } from '../ExecutionTools';
 /**
- * @@@
+ * Options for retrieving reserved parameters for a pipeline task, including context, pipeline, and identification.
  *
  * @private internal type of `getReservedParametersForTask`
  */
@@ -15,26 +15,28 @@ type GetReservedParametersForTaskOptions = {
      */
     readonly tools: ExecutionTools;
     /**
-     * @@@
+     * The prepared and validated pipeline in which the task resides.
      */
     readonly preparedPipeline: ReadonlyDeep<PipelineJson>;
     /**
-     * @@@
+     * The task for which reserved parameters are being retrieved.
      */
     readonly task: ReadonlyDeep<TaskJson>;
     /**
-     * @@@
-     *
-     * Parameters to complete the content of the task for embedding
+     * Parameters to complete the content of the task for embedding and context.
      */
     readonly parameters: Readonly<Parameters>;
     /**
-     * @@@
+     * String identifier for the pipeline, used in error messages and reporting.
      */
     readonly pipelineIdentification: string;
 };
 /**
- * @@@
+ * Retrieves all reserved parameters for a given pipeline task, including context, knowledge, examples, and metadata.
+ * Ensures all reserved parameters are defined and throws if any are missing.
+ *
+ * @param options - Options including tools, pipeline, task, and context.
+ * @returns An object containing all reserved parameters for the task.
  *
  * @private internal utility of `createPipelineExecutor`
  */

package/esm/typings/src/formats/_common/FormatParser.d.ts

@@ -4,9 +4,11 @@ import type { string_SCREAMING_CASE } from '../../utils/normalization/normalizeT
 import type { empty_object } from '../../utils/organization/empty_object';
 import type { FormatSubvalueParser } from './FormatSubvalueParser';
 /**
- * A format definition is a set of functions that define how to validate, heal and convert response from LLM
+ * A format definition is a set of functions that define how to validate, heal and convert response from LLM.
  *
- * @@@ Describe setting vs schema
+ * @remarks
+ * - "settings" are runtime options that affect parsing (e.g., delimiter for CSV).
+ * - "schema" is a structural definition or contract for the data (e.g., expected fields in JSON).
  *
  * @see https://github.com/webgptorg/promptbook/discussions/36
  * @private still in development [🏢]
@@ -56,7 +58,7 @@ export type FormatParser<TValue extends TPartialValue, TPartialValue extends str
      */
     heal(value: string, settings?: TSettings, scheme?: TSchema): TValue;
     /**
-     * @@@
+     * Parsers for extracting or mapping subvalues from the main value (e.g., rows from CSV, items from JSON array).
      */
     readonly subvalueParsers: ReadonlyArray<FormatSubvalueParser<TValue, TSettings>>;
 };

package/esm/typings/src/formats/_common/FormatSubvalueParser.d.ts

@@ -5,7 +5,8 @@ import type { string_parameter_name } from '../../types/typeAliases';
 import type { string_SCREAMING_CASE } from '../../utils/normalization/normalizeTo_SCREAMING_CASE';
 import type { empty_object } from '../../utils/organization/empty_object';
 /**
- * @@@
+ * Defines how to extract or map subvalues from a main value in a specific format (e.g., cells from CSV, items from JSON array).
+ * Used for iterating or transforming structured data in pipeline tasks.
  */
 export type FormatSubvalueParser<TValue extends string, TSettings extends empty_object> = {
     /**
@@ -19,21 +20,45 @@ export type FormatSubvalueParser<TValue extends string, TSettings extends empty_
      */
     readonly aliases?: ReadonlyArray<string_name & string_SCREAMING_CASE>;
     /**
-     * Maps values
+     * Maps or transforms subvalues from the main value. For example, iterates over all CSV cells or JSON array items.
      *
-     * For example, if you have a JSON object and you want to map all values to uppercase
-     * Or iterate over all CSV cells @@@
+     * @param options - Options for mapping, including callbacks for progress and value transformation.
+     * @returns The final mapped string result.
      */
     mapValues(options: FormatSubvalueParserMapValuesOptions<TValue, TSettings>): Promise<string>;
 };
 /**
- * @@@
+ * Options for mapping or extracting subvalues from a main value using a FormatSubvalueParser.
  */
 export type FormatSubvalueParserMapValuesOptions<TValue extends string, TSettings extends empty_object> = {
+    /**
+     * The input string value to parse for subvalues
+     */
     readonly value: TValue;
+    /**
+     * The name of the output parameter where the processed value will be stored
+     */
     readonly outputParameterName: string_parameter_name;
+    /**
+     * Format-specific settings that control how subvalues are parsed or processed
+     */
     readonly settings: TSettings;
-    mapCallback: (subvalues: Parameters, index: number) => Promisable<TValue>;
+    /**
+     * Callback function that processes each subvalue and returns the transformed value
+     *
+     * @param subvalues Object containing the extracted subvalues
+     * @param index Current index of the subvalue which is being mapped
+     * @param length Full length of the subvalues
+     * @param number Total number of subvalues to process
+     * @returns Transformed value after processing
+     */
+    mapCallback(subvalues: Parameters, index: number, length: number): Promisable<TValue>;
+    /**
+     * Progress callback that receives partial results during processing
+     *
+     * @param partialResultString The current partial result as processing progresses
+     * @returns Promise or void to continue execution
+     */
     onProgress(partialResultString: TValue): Promisable<void>;
 };
 /**

package/esm/typings/src/formats/csv/utils/isValidCsvString.d.ts

@@ -2,7 +2,7 @@
  * Function to check if a string is valid CSV
  *
  * @param value The string to check
- * @returns True if the string is a valid CSV string, false otherwise
+ * @returns `true` if the string is a valid CSV string, false otherwise
  *
  * @public exported from `@promptbook/utils`
  */

package/esm/typings/src/formats/json/utils/isValidJsonString.d.ts

@@ -2,7 +2,7 @@
  * Function isValidJsonString will tell you if the string is valid JSON or not
  *
  * @param value The string to check
- * @returns True if the string is a valid JSON string, false otherwise
+ * @returns `true` if the string is a valid JSON string, false otherwise
  *
  * @public exported from `@promptbook/utils`
  */

package/esm/typings/src/formats/xml/utils/isValidXmlString.d.ts

@@ -2,7 +2,7 @@
  * Function to check if a string is valid XML
  *
  * @param value
- * @returns True if the string is a valid XML string, false otherwise
+ * @returns `true` if the string is a valid XML string, false otherwise
  *
  * @public exported from `@promptbook/utils`
  */

package/esm/typings/src/formfactors/_boilerplate/BoilerplateFormfactorDefinition.d.ts

@@ -1,11 +1,12 @@
 /**
- * Boilerplate is form of app that @@@
+ * Boilerplate is form of app that serves as a template structure for creating other formfactors
+ * and should not be used directly in production.
  *
  * @public exported from `@promptbook/core`
  */
 export declare const BoilerplateFormfactorDefinition: {
     readonly name: "BOILERPLATE";
-    readonly description: "@@@";
+    readonly description: "A template structure for creating new formfactors, providing the base architecture and interfaces that should be implemented.";
     readonly documentationUrl: "https://github.com/webgptorg/promptbook/discussions/@@";
     readonly pipelineInterface: {
         readonly inputParameters: readonly [];

package/esm/typings/src/formfactors/_common/string_formfactor_name.d.ts

@@ -1,5 +1,6 @@
 import type { FormfactorDefinition } from './FormfactorDefinition';
 /**
- * @@@
+ * A type alias representing the name of a formfactor, used for type checking and validation
+ * in the formfactor registry and selection processes
  */
 export type string_formfactor_name = FormfactorDefinition['name'];

package/esm/typings/src/formfactors/index.d.ts

@@ -71,7 +71,7 @@ export declare const FORMFACTOR_DEFINITIONS: readonly [{
 }, {
     readonly name: "SHEETS";
     readonly aliasNames: readonly ["SHEETS", "SHEET"];
-    readonly description: "@@@";
+    readonly description: "A formfactor for processing spreadsheet-like data in CSV format, enabling AI transformations on tabular data";
     readonly documentationUrl: "https://github.com/webgptorg/promptbook/discussions/176";
     readonly pipelineInterface: {
         readonly inputParameters: readonly [{

package/esm/typings/src/formfactors/sheets/SheetsFormfactorDefinition.d.ts

@@ -1,12 +1,13 @@
 /**
- * Sheets is form of app that @@@
+ * Sheets is form of app that processes tabular data in CSV format, allowing transformation
+ * and analysis of structured data through AI-powered operations
  *
  * @public exported from `@promptbook/core`
  */
 export declare const SheetsFormfactorDefinition: {
     readonly name: "SHEETS";
     readonly aliasNames: readonly ["SHEETS", "SHEET"];
-    readonly description: "@@@";
+    readonly description: "A formfactor for processing spreadsheet-like data in CSV format, enabling AI transformations on tabular data";
     readonly documentationUrl: "https://github.com/webgptorg/promptbook/discussions/176";
     readonly pipelineInterface: {
         readonly inputParameters: readonly [{

package/esm/typings/src/llm-providers/_common/register/LlmToolsOptions.d.ts

@@ -1,6 +1,9 @@
 import type { TODO_object } from '../../../utils/organization/TODO_object';
 /**
- * @@@
+ * Options for configuring LLM (Large Language Model) tools.
+ *
+ * This type is used to pass provider-specific options to LLM execution tools.
+ *
  *
  * @@@ `LlmToolsMetadata` vs `LlmToolsConfiguration` vs `LlmToolsOptions` (vs `Registered`)
  */

package/esm/typings/src/llm-providers/_common/utils/cache/cacheLlmTools.d.ts

@@ -13,7 +13,7 @@ export declare function cacheLlmTools<TLlmTools extends LlmExecutionTools>(llmTo
 /**
  * TODO: [🧠][💸] Maybe make some common abstraction `interceptLlmTools` and use here (or use javascript Proxy?)
  * TODO: [🧠] Is there some meaningfull way how to test this util
- * TODO: [👷‍♂️] @@@ Manual about construction of llmTools
- *            @@@ write discussion about this and storages
- *            @@@ write how to combine multiple interceptors
+ * TODO: [👷‍♂️] Comprehensive manual about construction of llmTools
+ *            Detailed explanation about caching strategies and appropriate storage selection for different use cases
+ *            Examples of how to combine multiple interceptors for advanced caching, logging, and usage tracking
  */

package/esm/typings/src/scrapers/_common/register/$scrapersMetadataRegister.d.ts

@@ -1,10 +1,10 @@
 import { $Register } from '../../../utils/$Register';
 import type { ScraperAndConverterMetadata } from './ScraperAndConverterMetadata';
 /**
- * @@@
+ * Global registry for storing metadata about all available scrapers and converters.
  *
- * Note: `$` is used to indicate that this interacts with the global scope
- * @singleton Only one instance of each register is created per build, but thare can be more @@@
+ * Note: `$` is used to indicate that this interacts with the global scope.
+ * @singleton Only one instance of each register is created per build, but there can be more in different contexts (e.g., tests).
  * @public exported from `@promptbook/core`
  */
 export declare const $scrapersMetadataRegister: $Register<ScraperAndConverterMetadata>;

package/esm/typings/src/types/typeAliases.d.ts

@@ -123,7 +123,8 @@ export type InputParameters = Exclude<Record<string_parameter_name, really_unkno
  */
 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
  */
@@ -233,7 +234,9 @@ export type string_markdown_text = string;
  */
 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}`}`;
 /**
@@ -448,15 +451,14 @@ export type string_uuid = string & {
     readonly _type: 'uuid';
 };
 /**
- * Application identifier
+ * Application identifier, used to distinguish different apps or clients.
  *
- * @@@
+ * For example: 'cli', 'playground', or a custom app id.
  */
 export type string_app_id = id | 'app';
 /**
- * End user identifier
- *
- * @@@
+ * End user identifier, can be a user id or email address.
+ * Used for tracking and abuse prevention.
  */
 export type string_user_id = id | string_email;
 /**

package/esm/typings/src/utils/$Register.d.ts

@@ -2,33 +2,34 @@ import { type IDestroyable } from 'destroyable';
 import type { string_name } from '../types/typeAliases';
 import type { TODO_string } from './organization/TODO_string';
 /**
- * @@@
+ * Represents an entity in a global registry.
+ * Contains identifying information about the package and class.
  */
 export type Registered = {
     /**
-     * @@@
+     * The name of the package where the registered entity is defined.
      */
     readonly packageName: TODO_string;
     /**
-     * @@@
+     * The name of the class being registered.
      */
     readonly className: TODO_string;
 };
 /**
- * @@@
+ * Represents a registration record, including destroyable interface and registry name.
  */
 export type Registration = Registered & IDestroyable & {
     /**
-     * @@@
+     * The name of the register this entity is registered in.
      */
     readonly registerName: string_name;
 };
 /**
- * Register is @@@
+ * Global registry for storing and managing registered entities of a given type.
  *
  * Note: `$` is used to indicate that this function is not a pure function - it accesses and adds variables in global scope.
  *
- * @private internal utility, exported are only signleton instances of this class
+ * @private internal utility, exported are only singleton instances of this class
  */
 export declare class $Register<TRegistered extends Registered> {
     private readonly registerName;

package/esm/typings/src/utils/environment/$getGlobalScope.d.ts

@@ -1,6 +1,7 @@
 import type { really_any } from '../organization/really_any';
 /**
- * @@@
+ * Safely retrieves the global scope object (window in browser, global in Node.js)
+ * regardless of the JavaScript environment in which the code is running
  *
  * Note: `$` is used to indicate that this function is not a pure function - it access global scope
  *

package/esm/typings/src/utils/parameters/mapAvailableToExpectedParameters.d.ts

@@ -1,26 +1,26 @@
 import type { string_parameter_name } from '../../types/typeAliases';
 import type { string_parameter_value } from '../../types/typeAliases';
 /**
- * @@@
+ * Options for mapping available parameters to expected parameters in a pipeline task.
  */
 type MakeapAvailableToExpectedParametersOptions = {
     /**
-     * @@@
+     * The set of expected parameter names (keys) for the task, all values are null.
      */
     readonly expectedParameters: Readonly<Record<string_parameter_name, null>>;
     /**
-     * @@@
+     * The set of available parameters (name-value pairs) to map to the expected parameters.
      */
     readonly availableParameters: Readonly<Record<string_parameter_name, string_parameter_value>>;
 };
 /**
- * Maps available parameters to expected parameters
+ * Maps available parameters to expected parameters for a pipeline task.
  *
  * The strategy is:
- * 1) @@@
- * 2) @@@
+ * 1) First, match parameters by name where both available and expected.
+ * 2) Then, if there are unmatched expected and available parameters, map them by order.
  *
- * @throws {PipelineExecutionError} @@@
+ * @throws {PipelineExecutionError} If the number of unmatched expected and available parameters does not match, or mapping is ambiguous.
  * @private within the repository used in `createPipelineExecutor`
  */
 export declare function mapAvailableToExpectedParameters(options: MakeapAvailableToExpectedParametersOptions): Readonly<Record<string_parameter_name, string_parameter_value>>;

package/esm/typings/src/utils/serialization/clonePipeline.d.ts

@@ -1,10 +1,11 @@
 import type { PipelineJson } from '../../pipeline/PipelineJson/PipelineJson';
 /**
- * @@@
+ * Creates a deep clone of a PipelineJson object, copying all properties explicitly.
  *
- * Note: It is usefull @@@
+ * Note: It is useful for ensuring that modifications to the returned pipeline do not affect the original.
  *
- * @param pipeline
+ * @param pipeline The pipeline to clone.
+ * @returns A new PipelineJson object with the same properties as the input.
  * @public exported from `@promptbook/utils`
  */
 export declare function clonePipeline(pipeline: PipelineJson): PipelineJson;

package/esm/typings/src/utils/serialization/deepClone.d.ts

@@ -1,7 +1,11 @@
 import type { WritableDeep } from 'type-fest';
 /**
- * @@@
+ * Creates a deep clone of the given object
  *
+ * Note: This method only works for objects that are fully serializable to JSON and do not contain functions, Dates, or special types.
+ *
+ * @param objectValue The object to clone.
+ * @returns A deep, writable clone of the input object.
  * @public exported from `@promptbook/utils`
  */
 export declare function deepClone<TObject>(objectValue: TObject): WritableDeep<TObject>;

package/esm/typings/src/utils/validators/javascriptName/isValidJavascriptName.d.ts

@@ -1,10 +1,10 @@
 import type { string_javascript_name } from '../../../types/typeAliases';
 import type { really_unknown } from '../../organization/really_unknown';
 /**
- * @@@
+ * Checks if the given value is a valid JavaScript identifier name.
  *
- * @param javascriptName @@@
- * @returns @@@
+ * @param javascriptName The value to check for JavaScript identifier validity.
+ * @returns `true` if the value is a valid JavaScript name, false otherwise.
  * @public exported from `@promptbook/utils`
  */
 export declare function isValidJavascriptName(javascriptName: really_unknown): javascriptName is string_javascript_name;

package/esm/typings/src/utils/validators/parameterName/validateParameterName.d.ts

@@ -1,10 +1,11 @@
 import type { string_parameter_name } from '../../../types/typeAliases';
 /**
- * Function `validateParameterName` will @@@
+ * Function `validateParameterName` will normalize and validate a parameter name for use in pipelines.
+ * It removes diacritics, emojis, and quotes, normalizes to camelCase, and checks for reserved names and invalid characters.
  *
- * @param parameterName @@@
- * @returns @@@
- * @throws {ParseError} @@@
+ * @param parameterName The parameter name to validate and normalize.
+ * @returns The validated and normalized parameter name.
+ * @throws {ParseError} If the parameter name is empty, reserved, or contains invalid characters.
  * @private within the repository
  */
 export declare function validateParameterName(parameterName: string): string_parameter_name;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@promptbook/openai",
-    "version": "0.92.0-22",
+    "version": "0.92.0-24",
     "description": "It's time for a paradigm shift. The future of software in plain English, French or Latin",
     "private": false,
     "sideEffects": false,
@@ -51,7 +51,7 @@
     "module": "./esm/index.es.js",
     "typings": "./esm/typings/src/_packages/openai.index.d.ts",
     "peerDependencies": {
-        "@promptbook/core": "0.92.0-22"
+        "@promptbook/core": "0.92.0-24"
     },
     "dependencies": {
         "bottleneck": "^2.19.5",

package/umd/index.umd.js

@@ -25,7 +25,7 @@
      * @generated
      * @see https://github.com/webgptorg/promptbook
      */
-    const PROMPTBOOK_ENGINE_VERSION = '0.92.0-22';
+    const PROMPTBOOK_ENGINE_VERSION = '0.92.0-24';
     /**
      * TODO: string_promptbook_version should be constrained to the all versions of Promptbook engine
      * Note: [💞] Ignore a discrepancy between file name and entity name
@@ -285,7 +285,7 @@
     const SMALL_NUMBER = 0.001;
     // <- TODO: [🧜‍♂️]
     /**
-     * @@@
+     * Default settings for parsing and generating CSV files in Promptbook.
      *
      * @public exported from `@promptbook/core`
      */
@@ -578,8 +578,12 @@
      */
 
     /**
-     * @@@
+     * Creates a deep clone of the given object
+     *
+     * Note: This method only works for objects that are fully serializable to JSON and do not contain functions, Dates, or special types.
      *
+     * @param objectValue The object to clone.
+     * @returns A deep, writable clone of the input object.
      * @public exported from `@promptbook/utils`
      */
     function deepClone(objectValue) {
@@ -1740,14 +1744,23 @@
     resultContent, rawResponse) {
         var _a, _b;
         if (rawResponse.usage === undefined) {
+            console.log('!!! computeOpenAiUsage', 'The usage is not defined in the response from OpenAI');
             throw new PipelineExecutionError('The usage is not defined in the response from OpenAI');
         }
         if (((_a = rawResponse.usage) === null || _a === void 0 ? void 0 : _a.prompt_tokens) === undefined) {
+            console.log('!!! computeOpenAiUsage', 'In OpenAI response `usage.prompt_tokens` not defined');
             throw new PipelineExecutionError('In OpenAI response `usage.prompt_tokens` not defined');
         }
         const inputTokens = rawResponse.usage.prompt_tokens;
         const outputTokens = ((_b = rawResponse.usage) === null || _b === void 0 ? void 0 : _b.completion_tokens) || 0;
         const modelInfo = OPENAI_MODELS.find((model) => model.modelName === rawResponse.model);
+        console.log('!!! computeOpenAiUsage', {
+            inputTokens,
+            outputTokens,
+            rawResponse,
+            resultContent,
+            modelInfo,
+        });
         let price;
         if (modelInfo === undefined || modelInfo.pricing === undefined) {
             price = uncertainNumber();
@@ -2332,7 +2345,8 @@
      */
 
     /**
-     * @@@
+     * Safely retrieves the global scope object (window in browser, global in Node.js)
+     * regardless of the JavaScript environment in which the code is running
      *
      * Note: `$` is used to indicate that this function is not a pure function - it access global scope
      *
@@ -2411,11 +2425,11 @@
     }
 
     /**
-     * Register is @@@
+     * Global registry for storing and managing registered entities of a given type.
      *
      * Note: `$` is used to indicate that this function is not a pure function - it accesses and adds variables in global scope.
      *
-     * @private internal utility, exported are only signleton instances of this class
+     * @private internal utility, exported are only singleton instances of this class
      */
     class $Register {
         constructor(registerName) {