@promptbook/core 0.92.0-22 โ†’ 0.92.0-24

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (35) hide show
  1. package/esm/index.es.js +154 -80
  2. package/esm/index.es.js.map +1 -1
  3. package/esm/typings/src/_packages/core.index.d.ts +6 -0
  4. package/esm/typings/src/collection/PipelineCollection.d.ts +0 -2
  5. package/esm/typings/src/collection/SimplePipelineCollection.d.ts +1 -1
  6. package/esm/typings/src/commands/FOREACH/ForeachJson.d.ts +6 -6
  7. package/esm/typings/src/commands/FORMFACTOR/formfactorCommandParser.d.ts +1 -1
  8. package/esm/typings/src/config.d.ts +33 -11
  9. package/esm/typings/src/execution/createPipelineExecutor/10-executePipeline.d.ts +12 -9
  10. package/esm/typings/src/execution/createPipelineExecutor/20-executeTask.d.ts +11 -8
  11. package/esm/typings/src/execution/createPipelineExecutor/30-executeFormatSubvalues.d.ts +8 -3
  12. package/esm/typings/src/execution/createPipelineExecutor/getReservedParametersForTask.d.ts +10 -8
  13. package/esm/typings/src/formats/_common/FormatParser.d.ts +5 -3
  14. package/esm/typings/src/formats/_common/FormatSubvalueParser.d.ts +31 -6
  15. package/esm/typings/src/formats/csv/utils/isValidCsvString.d.ts +1 -1
  16. package/esm/typings/src/formats/json/utils/isValidJsonString.d.ts +1 -1
  17. package/esm/typings/src/formats/xml/utils/isValidXmlString.d.ts +1 -1
  18. package/esm/typings/src/formfactors/_boilerplate/BoilerplateFormfactorDefinition.d.ts +3 -2
  19. package/esm/typings/src/formfactors/_common/string_formfactor_name.d.ts +2 -1
  20. package/esm/typings/src/formfactors/index.d.ts +1 -1
  21. package/esm/typings/src/formfactors/sheets/SheetsFormfactorDefinition.d.ts +3 -2
  22. package/esm/typings/src/llm-providers/_common/register/LlmToolsOptions.d.ts +4 -1
  23. package/esm/typings/src/llm-providers/_common/utils/cache/cacheLlmTools.d.ts +3 -3
  24. package/esm/typings/src/scrapers/_common/register/$scrapersMetadataRegister.d.ts +3 -3
  25. package/esm/typings/src/types/typeAliases.d.ts +9 -7
  26. package/esm/typings/src/utils/$Register.d.ts +8 -7
  27. package/esm/typings/src/utils/environment/$getGlobalScope.d.ts +2 -1
  28. package/esm/typings/src/utils/parameters/mapAvailableToExpectedParameters.d.ts +7 -7
  29. package/esm/typings/src/utils/serialization/clonePipeline.d.ts +4 -3
  30. package/esm/typings/src/utils/serialization/deepClone.d.ts +5 -1
  31. package/esm/typings/src/utils/validators/javascriptName/isValidJavascriptName.d.ts +3 -3
  32. package/esm/typings/src/utils/validators/parameterName/validateParameterName.d.ts +5 -4
  33. package/package.json +1 -1
  34. package/umd/index.umd.js +156 -79
  35. package/umd/index.umd.js.map +1 -1
package/esm/index.es.js CHANGED
@@ -27,7 +27,7 @@ const BOOK_LANGUAGE_VERSION = '1.0.0';
27
27
  * @generated
28
28
  * @see https://github.com/webgptorg/promptbook
29
29
  */
30
- const PROMPTBOOK_ENGINE_VERSION = '0.92.0-22';
30
+ const PROMPTBOOK_ENGINE_VERSION = '0.92.0-24';
31
31
  /**
32
32
  * TODO: string_promptbook_version should be constrained to the all versions of Promptbook engine
33
33
  * Note: [๐Ÿ’ž] Ignore a discrepancy between file name and entity name
@@ -274,6 +274,28 @@ const DEFAULT_BOOK_OUTPUT_PARAMETER_NAME = 'result';
274
274
  * @public exported from `@promptbook/core`
275
275
  */
276
276
  const DEFAULT_MAX_FILE_SIZE = 100 * 1024 * 1024; // 100MB
277
+ /**
278
+ * Threshold value that determines when a dataset is considered "big"
279
+ * and may require special handling or optimizations
280
+ *
281
+ * For example, when error occurs in one item of the big dataset, it will not fail the whole pipeline
282
+ *
283
+ * @public exported from `@promptbook/core`
284
+ */
285
+ const BIG_DATASET_TRESHOLD = 50;
286
+ /**
287
+ * Placeholder text used to represent a placeholder value of failed operation
288
+ *
289
+ * @public exported from `@promptbook/core`
290
+ */
291
+ const FAILED_VALUE_PLACEHOLDER = '!?';
292
+ /**
293
+ * Placeholder text used to represent operations or values that are still in progress
294
+ * or awaiting completion in UI displays and logging
295
+ *
296
+ * @public exported from `@promptbook/core`
297
+ */
298
+ const PENDING_VALUE_PLACEHOLDER = 'โ€ฆ';
277
299
  // <- TODO: [๐Ÿง ] Better system for generator warnings - not always "code" and "by `@promptbook/cli`"
278
300
  /**
279
301
  * The maximum number of iterations for a loops
@@ -334,19 +356,21 @@ const DEFAULT_MAX_PARALLEL_COUNT = 5; // <- TODO: [๐Ÿคนโ€โ™‚๏ธ]
334
356
  */
335
357
  const DEFAULT_MAX_EXECUTION_ATTEMPTS = 10; // <- TODO: [๐Ÿคนโ€โ™‚๏ธ]
336
358
  /**
337
- * @@@
338
- * TODO: [๐Ÿ][main] !!3 Use
359
+ * The maximum depth to which knowledge sources will be scraped when building a knowledge base.
360
+ * This prevents infinite recursion and limits resource usage.
339
361
  *
340
362
  * @public exported from `@promptbook/core`
341
363
  */
342
364
  const DEFAULT_MAX_KNOWLEDGE_SOURCES_SCRAPING_DEPTH = 3;
365
+ // <- TODO: [๐Ÿ]
343
366
  /**
344
- * @@@
345
- * TODO: [๐Ÿ][main] !!3 Use
367
+ * The maximum total number of knowledge sources that will be scraped in a single operation.
368
+ * This acts as a global limit to avoid excessive resource consumption.
346
369
  *
347
370
  * @public exported from `@promptbook/core`
348
371
  */
349
372
  const DEFAULT_MAX_KNOWLEDGE_SOURCES_SCRAPING_TOTAL = 200;
373
+ // <- TODO: [๐Ÿ]
350
374
  /**
351
375
  * Where to store your books
352
376
  * This is kind of a "src" for your books
@@ -424,7 +448,7 @@ const MOMENT_ARG_THRESHOLDS = {
424
448
  const DEFAULT_REMOTE_SERVER_URL = REMOTE_SERVER_URLS[0].urls[0];
425
449
  // <- TODO: [๐Ÿงœโ€โ™‚๏ธ]
426
450
  /**
427
- * @@@
451
+ * Default settings for parsing and generating CSV files in Promptbook.
428
452
  *
429
453
  * @public exported from `@promptbook/core`
430
454
  */
@@ -435,15 +459,15 @@ const DEFAULT_CSV_SETTINGS = Object.freeze({
435
459
  skipEmptyLines: true,
436
460
  });
437
461
  /**
438
- * @@@
462
+ * Controls whether verbose logging is enabled by default throughout the application.
439
463
  *
440
464
  * @public exported from `@promptbook/core`
441
465
  */
442
466
  let DEFAULT_IS_VERBOSE = false;
443
467
  /**
444
- * @@@
468
+ * Enables or disables verbose logging globally at runtime.
445
469
  *
446
- * Note: This is experimental feature
470
+ * Note: This is an experimental feature.
447
471
  *
448
472
  * @public exported from `@promptbook/core`
449
473
  */
@@ -451,7 +475,7 @@ function SET_IS_VERBOSE(isVerbose) {
451
475
  DEFAULT_IS_VERBOSE = isVerbose;
452
476
  }
453
477
  /**
454
- * @@@
478
+ * Controls whether auto-installation of dependencies is enabled by default.
455
479
  *
456
480
  * @public exported from `@promptbook/core`
457
481
  */
@@ -471,7 +495,7 @@ const DEFAULT_GET_PIPELINE_COLLECTION_FUNCTION_NAME = `getPipelineCollection`;
471
495
  */
472
496
  const DEFAULT_RPM = 60;
473
497
  /**
474
- * @@@
498
+ * Indicates whether pipeline logic validation is enabled. When true, the pipeline logic is checked for consistency.
475
499
  *
476
500
  * @private within the repository
477
501
  */
@@ -604,7 +628,7 @@ function assertsError(whatWasThrown) {
604
628
  * Function isValidJsonString will tell you if the string is valid JSON or not
605
629
  *
606
630
  * @param value The string to check
607
- * @returns True if the string is a valid JSON string, false otherwise
631
+ * @returns `true` if the string is a valid JSON string, false otherwise
608
632
  *
609
633
  * @public exported from `@promptbook/utils`
610
634
  */
@@ -1015,8 +1039,12 @@ function checkSerializableAsJson(options) {
1015
1039
  */
1016
1040
 
1017
1041
  /**
1018
- * @@@
1042
+ * Creates a deep clone of the given object
1019
1043
  *
1044
+ * Note: This method only works for objects that are fully serializable to JSON and do not contain functions, Dates, or special types.
1045
+ *
1046
+ * @param objectValue The object to clone.
1047
+ * @returns A deep, writable clone of the input object.
1020
1048
  * @public exported from `@promptbook/utils`
1021
1049
  */
1022
1050
  function deepClone(objectValue) {
@@ -1603,7 +1631,7 @@ class SimplePipelineCollection {
1603
1631
  /**
1604
1632
  * Constructs a pipeline collection from pipelines
1605
1633
  *
1606
- * @param pipelines @@@
1634
+ * @param pipelines Array of pipeline JSON objects to include in the collection
1607
1635
  *
1608
1636
  * Note: During the construction logic of all pipelines are validated
1609
1637
  * Note: It is not recommended to use this constructor directly, use `createCollectionFromJson` *(or other variant)* instead
@@ -2783,7 +2811,7 @@ function csvParse(value /* <- TODO: string_csv */, settings, schema /* <- TODO:
2783
2811
  * Function to check if a string is valid CSV
2784
2812
  *
2785
2813
  * @param value The string to check
2786
- * @returns True if the string is a valid CSV string, false otherwise
2814
+ * @returns `true` if the string is a valid CSV string, false otherwise
2787
2815
  *
2788
2816
  * @public exported from `@promptbook/utils`
2789
2817
  */
@@ -2840,18 +2868,28 @@ const CsvFormatParser = {
2840
2868
  `));
2841
2869
  }
2842
2870
  const mappedData = [];
2843
- for (let index = 0; index < csv.data.length; index++) {
2871
+ const length = csv.data.length;
2872
+ for (let index = 0; index < length; index++) {
2844
2873
  const row = csv.data[index];
2845
2874
  if (row[outputParameterName]) {
2846
2875
  throw new CsvFormatError(`Can not overwrite existing column "${outputParameterName}" in CSV row`);
2847
2876
  }
2848
2877
  const mappedRow = {
2849
2878
  ...row,
2850
- [outputParameterName]: await mapCallback(row, index),
2879
+ [outputParameterName]: await mapCallback(row, index, length),
2851
2880
  };
2852
2881
  mappedData.push(mappedRow);
2853
2882
  if (onProgress) {
2854
2883
  // Note: Report the CSV with all rows mapped so far
2884
+ /*
2885
+ !!!!
2886
+ // Report progress with updated value
2887
+ const progressData = mappedData.map((row, i) =>
2888
+ i > index ? { ...row, [outputParameterName]: PENDING_VALUE_PLACEHOLDER } : row,
2889
+ );
2890
+
2891
+
2892
+ */
2855
2893
  await onProgress(unparse(mappedData, { ...settings, ...MANDATORY_CSV_SETTINGS }));
2856
2894
  }
2857
2895
  }
@@ -2878,9 +2916,9 @@ const CsvFormatParser = {
2878
2916
  `));
2879
2917
  }
2880
2918
  const mappedData = await Promise.all(csv.data.map(async (row, rowIndex) => {
2881
- return /* not await */ Promise.all(Object.entries(row).map(async ([key, value], columnIndex) => {
2919
+ return /* not await */ Promise.all(Object.entries(row).map(async ([key, value], columnIndex, array) => {
2882
2920
  const index = rowIndex * Object.keys(row).length + columnIndex;
2883
- return /* not await */ mapCallback({ [key]: value }, index);
2921
+ return /* not await */ mapCallback({ [key]: value }, index, array.length);
2884
2922
  }));
2885
2923
  }));
2886
2924
  return unparse(mappedData, { ...settings, ...MANDATORY_CSV_SETTINGS });
@@ -2951,12 +2989,12 @@ const TextFormatParser = {
2951
2989
  async mapValues(options) {
2952
2990
  const { value, mapCallback, onProgress } = options;
2953
2991
  const lines = value.split('\n');
2954
- const mappedLines = await Promise.all(lines.map((lineContent, lineNumber) =>
2992
+ const mappedLines = await Promise.all(lines.map((lineContent, lineNumber, array) =>
2955
2993
  // TODO: [๐Ÿง ] Maybe option to skip empty line
2956
2994
  /* not await */ mapCallback({
2957
2995
  lineContent,
2958
2996
  // TODO: [๐Ÿง ] Maybe also put here `lineNumber`
2959
- }, lineNumber)));
2997
+ }, lineNumber, array.length)));
2960
2998
  return mappedLines.join('\n');
2961
2999
  },
2962
3000
  },
@@ -2977,7 +3015,7 @@ const TextFormatParser = {
2977
3015
  * Function to check if a string is valid XML
2978
3016
  *
2979
3017
  * @param value
2980
- * @returns True if the string is a valid XML string, false otherwise
3018
+ * @returns `true` if the string is a valid XML string, false otherwise
2981
3019
  *
2982
3020
  * @public exported from `@promptbook/utils`
2983
3021
  */
@@ -3039,13 +3077,13 @@ const FORMAT_DEFINITIONS = [JsonFormatParser, XmlFormatParser, TextFormatParser,
3039
3077
  */
3040
3078
 
3041
3079
  /**
3042
- * Maps available parameters to expected parameters
3080
+ * Maps available parameters to expected parameters for a pipeline task.
3043
3081
  *
3044
3082
  * The strategy is:
3045
- * 1) @@@
3046
- * 2) @@@
3083
+ * 1) First, match parameters by name where both available and expected.
3084
+ * 2) Then, if there are unmatched expected and available parameters, map them by order.
3047
3085
  *
3048
- * @throws {PipelineExecutionError} @@@
3086
+ * @throws {PipelineExecutionError} If the number of unmatched expected and available parameters does not match, or mapping is ambiguous.
3049
3087
  * @private within the repository used in `createPipelineExecutor`
3050
3088
  */
3051
3089
  function mapAvailableToExpectedParameters(options) {
@@ -4276,7 +4314,11 @@ async function executeAttempts(options) {
4276
4314
  */
4277
4315
 
4278
4316
  /**
4279
- * @@@
4317
+ * Executes a pipeline task that requires mapping or iterating over subvalues of a parameter (such as rows in a CSV).
4318
+ * Handles format and subformat resolution, error handling, and progress reporting.
4319
+ *
4320
+ * @param options - Options for execution, including task details and progress callback.
4321
+ * @returns The result of the subvalue mapping or execution attempts.
4280
4322
  *
4281
4323
  * @private internal utility of `createPipelineExecutor`
4282
4324
  */
@@ -4341,15 +4383,11 @@ async function executeFormatSubvalues(options) {
4341
4383
  settings: formatSettings,
4342
4384
  onProgress(partialResultString) {
4343
4385
  return onProgress(Object.freeze({
4344
- [task.resultingParameterName]:
4345
- // <- Note: [๐Ÿ‘ฉโ€๐Ÿ‘ฉโ€๐Ÿ‘ง] No need to detect parameter collision here because pipeline checks logic consistency during construction
4346
- partialResultString,
4386
+ [task.resultingParameterName]: partialResultString,
4347
4387
  }));
4348
4388
  },
4349
- async mapCallback(subparameters, index) {
4389
+ async mapCallback(subparameters, index, length) {
4350
4390
  let mappedParameters;
4351
- // TODO: [๐Ÿคนโ€โ™‚๏ธ][๐Ÿช‚] Limit to N concurrent executions
4352
- // TODO: When done [๐Ÿš] Report progress also for each subvalue here
4353
4391
  try {
4354
4392
  mappedParameters = mapAvailableToExpectedParameters({
4355
4393
  expectedParameters: Object.fromEntries(task.foreach.inputSubparameterNames.map((subparameterName) => [subparameterName, null])),
@@ -4360,32 +4398,52 @@ async function executeFormatSubvalues(options) {
4360
4398
  if (!(error instanceof PipelineExecutionError)) {
4361
4399
  throw error;
4362
4400
  }
4363
- throw new PipelineExecutionError(spaceTrim((block) => `
4364
- ${error.message}
4401
+ const highLevelError = new PipelineExecutionError(spaceTrim((block) => `
4402
+ ${error.message}
4365
4403
 
4366
- This is error in FOREACH command
4367
- You have probbably passed wrong data to pipeline or wrong data was generated which are processed by FOREACH command
4404
+ This is error in FOREACH command when mapping data
4405
+ You have probbably passed wrong data to pipeline or wrong data was generated which are processed by FOREACH command
4368
4406
 
4369
- ${block(pipelineIdentification)}
4370
- Subparameter index: ${index}
4371
- `));
4407
+ ${block(pipelineIdentification)}
4408
+ Subparameter index: ${index}
4409
+ `));
4410
+ if (length > BIG_DATASET_TRESHOLD) {
4411
+ console.error(highLevelError);
4412
+ return FAILED_VALUE_PLACEHOLDER;
4413
+ }
4414
+ throw highLevelError;
4372
4415
  }
4373
4416
  const allSubparameters = {
4374
4417
  ...parameters,
4375
4418
  ...mappedParameters,
4376
4419
  };
4377
- // Note: [๐Ÿ‘จโ€๐Ÿ‘จโ€๐Ÿ‘ง] Now we can freeze `subparameters` because we are sure that all and only used parameters are defined and are not going to be changed
4378
4420
  Object.freeze(allSubparameters);
4379
- const subresultString = await executeAttempts({
4380
- ...options,
4381
- priority: priority + index,
4382
- parameters: allSubparameters,
4383
- pipelineIdentification: spaceTrim((block) => `
4384
- ${block(pipelineIdentification)}
4385
- Subparameter index: ${index}
4386
- `),
4387
- });
4388
- return subresultString;
4421
+ try {
4422
+ const subresultString = await executeAttempts({
4423
+ ...options,
4424
+ priority: priority + index,
4425
+ parameters: allSubparameters,
4426
+ pipelineIdentification: spaceTrim((block) => `
4427
+ ${block(pipelineIdentification)}
4428
+ Subparameter index: ${index}
4429
+ `),
4430
+ });
4431
+ return subresultString;
4432
+ }
4433
+ catch (error) {
4434
+ if (length > BIG_DATASET_TRESHOLD) {
4435
+ console.error(spaceTrim((block) => `
4436
+ Error in FOREACH command:
4437
+
4438
+ ${block(pipelineIdentification)}
4439
+
4440
+ ${block(pipelineIdentification)}
4441
+ Subparameter index: ${index}
4442
+ `));
4443
+ return FAILED_VALUE_PLACEHOLDER;
4444
+ }
4445
+ throw error;
4446
+ }
4389
4447
  },
4390
4448
  });
4391
4449
  return resultString;
@@ -4520,7 +4578,11 @@ async function getKnowledgeForTask(options) {
4520
4578
  */
4521
4579
 
4522
4580
  /**
4523
- * @@@
4581
+ * Retrieves all reserved parameters for a given pipeline task, including context, knowledge, examples, and metadata.
4582
+ * Ensures all reserved parameters are defined and throws if any are missing.
4583
+ *
4584
+ * @param options - Options including tools, pipeline, task, and context.
4585
+ * @returns An object containing all reserved parameters for the task.
4524
4586
  *
4525
4587
  * @private internal utility of `createPipelineExecutor`
4526
4588
  */
@@ -4553,7 +4615,10 @@ async function getReservedParametersForTask(options) {
4553
4615
  }
4554
4616
 
4555
4617
  /**
4556
- * @@@
4618
+ * Executes a single task within a pipeline, handling parameter validation, error checking, and progress reporting.
4619
+ *
4620
+ * @param options - Options for execution, including the task, pipeline, parameters, and callbacks.
4621
+ * @returns The output parameters produced by the task.
4557
4622
  *
4558
4623
  * @private internal utility of `createPipelineExecutor`
4559
4624
  */
@@ -4687,9 +4752,12 @@ function filterJustOutputParameters(options) {
4687
4752
  }
4688
4753
 
4689
4754
  /**
4690
- * @@@
4755
+ * Executes an entire pipeline, resolving tasks in dependency order, handling errors, and reporting progress.
4691
4756
  *
4692
- * Note: This is not a `PipelineExecutor` (which is binded with one exact pipeline), but a utility function of `createPipelineExecutor` which creates `PipelineExecutor`
4757
+ * Note: This is not a `PipelineExecutor` (which is bound to a single pipeline), but a utility function used by `createPipelineExecutor` to create a `PipelineExecutor`.
4758
+ *
4759
+ * @param options - Options for execution, including input parameters, pipeline, and callbacks.
4760
+ * @returns The result of the pipeline execution, including output parameters, errors, and usage statistics.
4693
4761
  *
4694
4762
  * @private internal utility of `createPipelineExecutor`
4695
4763
  */
@@ -5211,7 +5279,8 @@ async function preparePersona(personaDescription, tools, options) {
5211
5279
  */
5212
5280
 
5213
5281
  /**
5214
- * @@@
5282
+ * Safely retrieves the global scope object (window in browser, global in Node.js)
5283
+ * regardless of the JavaScript environment in which the code is running
5215
5284
  *
5216
5285
  * Note: `$` is used to indicate that this function is not a pure function - it access global scope
5217
5286
  *
@@ -5290,11 +5359,11 @@ function normalizeTo_snake_case(text) {
5290
5359
  }
5291
5360
 
5292
5361
  /**
5293
- * Register is @@@
5362
+ * Global registry for storing and managing registered entities of a given type.
5294
5363
  *
5295
5364
  * Note: `$` is used to indicate that this function is not a pure function - it accesses and adds variables in global scope.
5296
5365
  *
5297
- * @private internal utility, exported are only signleton instances of this class
5366
+ * @private internal utility, exported are only singleton instances of this class
5298
5367
  */
5299
5368
  class $Register {
5300
5369
  constructor(registerName) {
@@ -5344,10 +5413,10 @@ class $Register {
5344
5413
  }
5345
5414
 
5346
5415
  /**
5347
- * @@@
5416
+ * Global registry for storing metadata about all available scrapers and converters.
5348
5417
  *
5349
- * Note: `$` is used to indicate that this interacts with the global scope
5350
- * @singleton Only one instance of each register is created per build, but thare can be more @@@
5418
+ * Note: `$` is used to indicate that this interacts with the global scope.
5419
+ * @singleton Only one instance of each register is created per build, but there can be more in different contexts (e.g., tests).
5351
5420
  * @public exported from `@promptbook/core`
5352
5421
  */
5353
5422
  const $scrapersMetadataRegister = new $Register('scrapers_metadata');
@@ -6886,11 +6955,12 @@ function removeQuotes(text) {
6886
6955
  }
6887
6956
 
6888
6957
  /**
6889
- * Function `validateParameterName` will @@@
6958
+ * Function `validateParameterName` will normalize and validate a parameter name for use in pipelines.
6959
+ * It removes diacritics, emojis, and quotes, normalizes to camelCase, and checks for reserved names and invalid characters.
6890
6960
  *
6891
- * @param parameterName @@@
6892
- * @returns @@@
6893
- * @throws {ParseError} @@@
6961
+ * @param parameterName The parameter name to validate and normalize.
6962
+ * @returns The validated and normalized parameter name.
6963
+ * @throws {ParseError} If the parameter name is empty, reserved, or contains invalid characters.
6894
6964
  * @private within the repository
6895
6965
  */
6896
6966
  function validateParameterName(parameterName) {
@@ -7383,14 +7453,15 @@ const MatcherFormfactorDefinition = {
7383
7453
  };
7384
7454
 
7385
7455
  /**
7386
- * Sheets is form of app that @@@
7456
+ * Sheets is form of app that processes tabular data in CSV format, allowing transformation
7457
+ * and analysis of structured data through AI-powered operations
7387
7458
  *
7388
7459
  * @public exported from `@promptbook/core`
7389
7460
  */
7390
7461
  const SheetsFormfactorDefinition = {
7391
7462
  name: 'SHEETS',
7392
7463
  aliasNames: ['SHEETS', 'SHEET'],
7393
- description: `@@@`,
7464
+ description: `A formfactor for processing spreadsheet-like data in CSV format, enabling AI transformations on tabular data`,
7394
7465
  documentationUrl: `https://github.com/webgptorg/promptbook/discussions/176`,
7395
7466
  pipelineInterface: {
7396
7467
  inputParameters: [
@@ -7466,7 +7537,7 @@ const FORMFACTOR_DEFINITIONS = [
7466
7537
  /**
7467
7538
  * Parses the formfactor command
7468
7539
  *
7469
- * Note: @@@ This command is used as formfactor for new commands - it should NOT be used in any `.book` file
7540
+ * Note: This command is used as a formfactor for new commands and defines the app type format - it should NOT be used in any `.book` file
7470
7541
  *
7471
7542
  * @see `documentationUrl` for more details
7472
7543
  * @public exported from `@promptbook/editable`
@@ -7488,7 +7559,7 @@ const formfactorCommandParser = {
7488
7559
  /**
7489
7560
  * Description of the FORMFACTOR command
7490
7561
  */
7491
- description: `@@`,
7562
+ description: `Specifies the application type and interface requirements that this promptbook should conform to`,
7492
7563
  /**
7493
7564
  * Link to documentation
7494
7565
  */
@@ -8064,10 +8135,10 @@ function $applyToTaskJson(command, $taskJson, $pipelineJson) {
8064
8135
  }
8065
8136
 
8066
8137
  /**
8067
- * @@@
8138
+ * Checks if the given value is a valid JavaScript identifier name.
8068
8139
  *
8069
- * @param javascriptName @@@
8070
- * @returns @@@
8140
+ * @param javascriptName The value to check for JavaScript identifier validity.
8141
+ * @returns `true` if the value is a valid JavaScript name, false otherwise.
8071
8142
  * @public exported from `@promptbook/utils`
8072
8143
  */
8073
8144
  function isValidJavascriptName(javascriptName) {
@@ -10151,22 +10222,23 @@ function usageToHuman(usage) {
10151
10222
  */
10152
10223
 
10153
10224
  /**
10154
- * Boilerplate is form of app that @@@
10225
+ * Boilerplate is form of app that serves as a template structure for creating other formfactors
10226
+ * and should not be used directly in production.
10155
10227
  *
10156
10228
  * @public exported from `@promptbook/core`
10157
10229
  */
10158
10230
  const BoilerplateFormfactorDefinition = {
10159
10231
  name: 'BOILERPLATE',
10160
- description: `@@@`,
10232
+ description: `A template structure for creating new formfactors, providing the base architecture and interfaces that should be implemented.`,
10161
10233
  documentationUrl: `https://github.com/webgptorg/promptbook/discussions/@@`,
10162
10234
  // <- TODO: https://github.com/webgptorg/promptbook/discussions/new?category=concepts
10163
10235
  // "๐Ÿ”  Boilerplate Formfactor"
10164
10236
  pipelineInterface: {
10165
10237
  inputParameters: [
10166
- /* @@@ */
10238
+ /* <- Example input parameters should be defined here */
10167
10239
  ],
10168
10240
  outputParameters: [
10169
- /* @@@ */
10241
+ /* <- Example output parameters should be defined here */
10170
10242
  ],
10171
10243
  },
10172
10244
  };
@@ -10599,8 +10671,10 @@ function cacheLlmTools(llmTools, options = {}) {
10599
10671
  sha256(hexEncoder.parse(JSON.stringify({ parameters, content, modelRequirements }))).toString( /* hex */));
10600
10672
  const cacheItem = !isCacheReloaded ? await storage.getItem(key) : null;
10601
10673
  if (cacheItem) {
10674
+ console.log('!!! Cache hit for key:', key);
10602
10675
  return cacheItem.promptResult;
10603
10676
  }
10677
+ console.log('!!! Cache miss for key:', key);
10604
10678
  let promptResult;
10605
10679
  variant: switch (prompt.modelRequirements.modelVariant) {
10606
10680
  case 'CHAT':
@@ -10647,9 +10721,9 @@ function cacheLlmTools(llmTools, options = {}) {
10647
10721
  /**
10648
10722
  * TODO: [๐Ÿง ][๐Ÿ’ธ] Maybe make some common abstraction `interceptLlmTools` and use here (or use javascript Proxy?)
10649
10723
  * TODO: [๐Ÿง ] Is there some meaningfull way how to test this util
10650
- * TODO: [๐Ÿ‘ทโ€โ™‚๏ธ] @@@ Manual about construction of llmTools
10651
- * @@@ write discussion about this and storages
10652
- * @@@ write how to combine multiple interceptors
10724
+ * TODO: [๐Ÿ‘ทโ€โ™‚๏ธ] Comprehensive manual about construction of llmTools
10725
+ * Detailed explanation about caching strategies and appropriate storage selection for different use cases
10726
+ * Examples of how to combine multiple interceptors for advanced caching, logging, and usage tracking
10653
10727
  */
10654
10728
 
10655
10729
  /**
@@ -11498,5 +11572,5 @@ class PrefixStorage {
11498
11572
  }
11499
11573
  }
11500
11574
 
11501
- export { $llmToolsMetadataRegister, $llmToolsRegister, $scrapersMetadataRegister, $scrapersRegister, ADMIN_EMAIL, ADMIN_GITHUB_NAME, AbstractFormatError, AuthenticationError, BOOK_LANGUAGE_VERSION, BlackholeStorage, BoilerplateError, BoilerplateFormfactorDefinition, CLAIM, CLI_APP_ID, CallbackInterfaceTools, ChatbotFormfactorDefinition, CollectionError, CompletionFormfactorDefinition, CsvFormatError, CsvFormatParser, DEFAULT_BOOKS_DIRNAME, DEFAULT_BOOK_OUTPUT_PARAMETER_NAME, DEFAULT_BOOK_TITLE, DEFAULT_CSV_SETTINGS, DEFAULT_DOWNLOAD_CACHE_DIRNAME, DEFAULT_EXECUTION_CACHE_DIRNAME, DEFAULT_GET_PIPELINE_COLLECTION_FUNCTION_NAME, DEFAULT_INTERMEDIATE_FILES_STRATEGY, DEFAULT_IS_AUTO_INSTALLED, DEFAULT_IS_VERBOSE, DEFAULT_MAX_EXECUTION_ATTEMPTS, DEFAULT_MAX_FILE_SIZE, DEFAULT_MAX_KNOWLEDGE_SOURCES_SCRAPING_DEPTH, DEFAULT_MAX_KNOWLEDGE_SOURCES_SCRAPING_TOTAL, DEFAULT_MAX_PARALLEL_COUNT, DEFAULT_PIPELINE_COLLECTION_BASE_FILENAME, DEFAULT_PROMPT_TASK_TITLE, DEFAULT_REMOTE_SERVER_URL, DEFAULT_RPM, DEFAULT_SCRAPE_CACHE_DIRNAME, DEFAULT_TASK_TITLE, EXPECTATION_UNITS, EnvironmentMismatchError, ExecutionReportStringOptionsDefaults, ExpectError, FORMFACTOR_DEFINITIONS, GENERIC_PIPELINE_INTERFACE, GeneratorFormfactorDefinition, GenericFormfactorDefinition, ImageGeneratorFormfactorDefinition, KnowledgeScrapeError, LimitReachedError, MANDATORY_CSV_SETTINGS, MAX_FILENAME_LENGTH, MODEL_ORDER, MODEL_TRUST_LEVEL, MODEL_VARIANTS, MatcherFormfactorDefinition, MemoryStorage, MissingToolsError, MultipleLlmExecutionTools, NAME, NonTaskSectionTypes, NotFoundError, NotYetImplementedError, ORDER_OF_PIPELINE_JSON, PLAYGROUND_APP_ID, PROMPTBOOK_ENGINE_VERSION, PROMPTBOOK_ERRORS, ParseError, PipelineExecutionError, PipelineLogicError, PipelineUrlError, PrefixStorage, PromptbookFetchError, REMOTE_SERVER_URLS, RESERVED_PARAMETER_NAMES, SET_IS_VERBOSE, SectionTypes, SheetsFormfactorDefinition, TaskTypes, TextFormatParser, TranslatorFormfactorDefinition, UNCERTAIN_USAGE, UNCERTAIN_ZERO_VALUE, UnexpectedError, WrappedError, ZERO_USAGE, ZERO_VALUE, _AnthropicClaudeMetadataRegistration, _AzureOpenAiMetadataRegistration, _BoilerplateScraperMetadataRegistration, _DeepseekMetadataRegistration, _DocumentScraperMetadataRegistration, _GoogleMetadataRegistration, _LegacyDocumentScraperMetadataRegistration, _MarkdownScraperMetadataRegistration, _MarkitdownScraperMetadataRegistration, _OpenAiAssistantMetadataRegistration, _OpenAiMetadataRegistration, _PdfScraperMetadataRegistration, _WebsiteScraperMetadataRegistration, addUsage, book, cacheLlmTools, collectionToJson, compilePipeline, computeCosineSimilarity, countUsage, createCollectionFromJson, createCollectionFromPromise, createCollectionFromUrl, createLlmToolsFromConfiguration, createPipelineExecutor, createSubcollection, embeddingVectorToString, executionReportJsonToString, extractParameterNamesFromTask, filterModels, getPipelineInterface, identificationToPromptbookToken, isPassingExpectations, isPipelineImplementingInterface, isPipelineInterfacesEqual, isPipelinePrepared, isValidPipelineString, joinLlmExecutionTools, limitTotalUsage, makeKnowledgeSourceHandler, migratePipeline, parsePipeline, pipelineJsonToString, prepareKnowledgePieces, preparePersona, preparePipeline, prepareTasks, prettifyPipelineString, promptbookFetch, promptbookTokenToIdentification, unpreparePipeline, usageToHuman, usageToWorktime, validatePipeline, validatePipelineString };
11575
+ export { $llmToolsMetadataRegister, $llmToolsRegister, $scrapersMetadataRegister, $scrapersRegister, ADMIN_EMAIL, ADMIN_GITHUB_NAME, AbstractFormatError, AuthenticationError, BIG_DATASET_TRESHOLD, BOOK_LANGUAGE_VERSION, BlackholeStorage, BoilerplateError, BoilerplateFormfactorDefinition, CLAIM, CLI_APP_ID, CallbackInterfaceTools, ChatbotFormfactorDefinition, CollectionError, CompletionFormfactorDefinition, CsvFormatError, CsvFormatParser, DEFAULT_BOOKS_DIRNAME, DEFAULT_BOOK_OUTPUT_PARAMETER_NAME, DEFAULT_BOOK_TITLE, DEFAULT_CSV_SETTINGS, DEFAULT_DOWNLOAD_CACHE_DIRNAME, DEFAULT_EXECUTION_CACHE_DIRNAME, DEFAULT_GET_PIPELINE_COLLECTION_FUNCTION_NAME, DEFAULT_INTERMEDIATE_FILES_STRATEGY, DEFAULT_IS_AUTO_INSTALLED, DEFAULT_IS_VERBOSE, DEFAULT_MAX_EXECUTION_ATTEMPTS, DEFAULT_MAX_FILE_SIZE, DEFAULT_MAX_KNOWLEDGE_SOURCES_SCRAPING_DEPTH, DEFAULT_MAX_KNOWLEDGE_SOURCES_SCRAPING_TOTAL, DEFAULT_MAX_PARALLEL_COUNT, DEFAULT_PIPELINE_COLLECTION_BASE_FILENAME, DEFAULT_PROMPT_TASK_TITLE, DEFAULT_REMOTE_SERVER_URL, DEFAULT_RPM, DEFAULT_SCRAPE_CACHE_DIRNAME, DEFAULT_TASK_TITLE, EXPECTATION_UNITS, EnvironmentMismatchError, ExecutionReportStringOptionsDefaults, ExpectError, FAILED_VALUE_PLACEHOLDER, FORMFACTOR_DEFINITIONS, GENERIC_PIPELINE_INTERFACE, GeneratorFormfactorDefinition, GenericFormfactorDefinition, ImageGeneratorFormfactorDefinition, KnowledgeScrapeError, LimitReachedError, MANDATORY_CSV_SETTINGS, MAX_FILENAME_LENGTH, MODEL_ORDER, MODEL_TRUST_LEVEL, MODEL_VARIANTS, MatcherFormfactorDefinition, MemoryStorage, MissingToolsError, MultipleLlmExecutionTools, NAME, NonTaskSectionTypes, NotFoundError, NotYetImplementedError, ORDER_OF_PIPELINE_JSON, PENDING_VALUE_PLACEHOLDER, PLAYGROUND_APP_ID, PROMPTBOOK_ENGINE_VERSION, PROMPTBOOK_ERRORS, ParseError, PipelineExecutionError, PipelineLogicError, PipelineUrlError, PrefixStorage, PromptbookFetchError, REMOTE_SERVER_URLS, RESERVED_PARAMETER_NAMES, SET_IS_VERBOSE, SectionTypes, SheetsFormfactorDefinition, TaskTypes, TextFormatParser, TranslatorFormfactorDefinition, UNCERTAIN_USAGE, UNCERTAIN_ZERO_VALUE, UnexpectedError, WrappedError, ZERO_USAGE, ZERO_VALUE, _AnthropicClaudeMetadataRegistration, _AzureOpenAiMetadataRegistration, _BoilerplateScraperMetadataRegistration, _DeepseekMetadataRegistration, _DocumentScraperMetadataRegistration, _GoogleMetadataRegistration, _LegacyDocumentScraperMetadataRegistration, _MarkdownScraperMetadataRegistration, _MarkitdownScraperMetadataRegistration, _OpenAiAssistantMetadataRegistration, _OpenAiMetadataRegistration, _PdfScraperMetadataRegistration, _WebsiteScraperMetadataRegistration, addUsage, book, cacheLlmTools, collectionToJson, compilePipeline, computeCosineSimilarity, countUsage, createCollectionFromJson, createCollectionFromPromise, createCollectionFromUrl, createLlmToolsFromConfiguration, createPipelineExecutor, createSubcollection, embeddingVectorToString, executionReportJsonToString, extractParameterNamesFromTask, filterModels, getPipelineInterface, identificationToPromptbookToken, isPassingExpectations, isPipelineImplementingInterface, isPipelineInterfacesEqual, isPipelinePrepared, isValidPipelineString, joinLlmExecutionTools, limitTotalUsage, makeKnowledgeSourceHandler, migratePipeline, parsePipeline, pipelineJsonToString, prepareKnowledgePieces, preparePersona, preparePipeline, prepareTasks, prettifyPipelineString, promptbookFetch, promptbookTokenToIdentification, unpreparePipeline, usageToHuman, usageToWorktime, validatePipeline, validatePipelineString };
11502
11576
  //# sourceMappingURL=index.es.js.map