@promptbook/utils 0.106.0-0 → 0.108.0-0

package/esm/index.es.js

@@ -18,7 +18,7 @@ const BOOK_LANGUAGE_VERSION = '2.0.0';
  * @generated
  * @see https://github.com/webgptorg/promptbook
  */
-const PROMPTBOOK_ENGINE_VERSION = '0.106.0-0';
+const PROMPTBOOK_ENGINE_VERSION = '0.108.0-0';
 /**
  * TODO: string_promptbook_version should be constrained to the all versions of Promptbook engine
  * Note: [💞] Ignore a discrepancy between file name and entity name
@@ -2804,13 +2804,125 @@ function escapePromptParameterValue(value, options) {
     return value.replace(pattern, '\\$&');
 }
 /**
- * Builds the parameter name used in prompt placeholders.
+ * Builds numeric parameter name used in prompt placeholders.
  *
  * @param index Zero-based parameter index.
  */
-function buildParameterName(index) {
+function buildNumericParameterName(index) {
     return `${index + 1}`;
 }
+/**
+ * Builds alphabetic parameter name used in prompt placeholders.
+ *
+ * @param index Zero-based parameter index.
+ */
+function buildAlphabeticParameterName(index) {
+    const alphabet = 'abcdefghijklmnopqrstuvwxyz';
+    let result = '';
+    let remaining = index;
+    while (remaining >= 0) {
+        result = alphabet[remaining % alphabet.length] + result;
+        remaining = Math.floor(remaining / alphabet.length) - 1;
+    }
+    return result;
+}
+/**
+ * Converts a positive integer into a Roman numeral string.
+ *
+ * @param value Positive integer value.
+ */
+function toRomanNumeral(value) {
+    const romanTable = [
+        { symbol: 'M', value: 1000 },
+        { symbol: 'CM', value: 900 },
+        { symbol: 'D', value: 500 },
+        { symbol: 'CD', value: 400 },
+        { symbol: 'C', value: 100 },
+        { symbol: 'XC', value: 90 },
+        { symbol: 'L', value: 50 },
+        { symbol: 'XL', value: 40 },
+        { symbol: 'X', value: 10 },
+        { symbol: 'IX', value: 9 },
+        { symbol: 'V', value: 5 },
+        { symbol: 'IV', value: 4 },
+        { symbol: 'I', value: 1 },
+    ];
+    let remaining = Math.max(1, Math.floor(value));
+    let result = '';
+    for (const entry of romanTable) {
+        while (remaining >= entry.value) {
+            result += entry.symbol;
+            remaining -= entry.value;
+        }
+    }
+    return result;
+}
+/**
+ * Builds Roman numeral parameter name used in prompt placeholders.
+ *
+ * @param index Zero-based parameter index.
+ */
+function buildRomanParameterName(index) {
+    return toRomanNumeral(index + 1);
+}
+/**
+ * Creates a parameter name builder that prefixes another builder.
+ *
+ * @param prefix Prefix to add.
+ * @param builder Base builder to wrap.
+ */
+function buildPrefixedParameterName(prefix, builder) {
+    return (index) => `${prefix}${builder(index)}`;
+}
+/**
+ * Ordered list of strategies for parameter naming.
+ */
+const PARAMETER_NAME_STRATEGIES = [
+    { buildName: buildNumericParameterName },
+    { buildName: buildAlphabeticParameterName },
+    { buildName: buildRomanParameterName },
+    { buildName: buildPrefixedParameterName('p', buildNumericParameterName) },
+    { buildName: buildPrefixedParameterName('p', buildAlphabeticParameterName) },
+];
+/**
+ * Collects bracketed tokens from parameter values to avoid placeholder collisions.
+ *
+ * @param values Parameter values to scan.
+ */
+function collectBracketedParameterTokens(values) {
+    const tokens = new Set();
+    for (const value of values) {
+        const pattern = /{(\w+)}/g;
+        let match;
+        while ((match = pattern.exec(value)) !== null) {
+            const token = match[1];
+            if (token) {
+                tokens.add(token);
+            }
+        }
+    }
+    return tokens;
+}
+/**
+ * Builds parameter names used in prompt placeholders while avoiding collisions.
+ *
+ * @param values Parameter values to scan for conflicting tokens.
+ */
+function buildParameterNames(values) {
+    const count = values.length;
+    if (count === 0) {
+        return [];
+    }
+    const conflicts = collectBracketedParameterTokens(values);
+    for (const strategy of PARAMETER_NAME_STRATEGIES) {
+        const names = Array.from({ length: count }, (_, index) => strategy.buildName(index));
+        const hasConflict = names.some((name) => conflicts.has(name));
+        if (!hasConflict) {
+            return names;
+        }
+    }
+    return Array.from({ length: count }, (_, index) => `${REPLACING_NONCE}${index + 1}`);
+}
 /**
  * Formats the placeholder used in the prompt body for a parameter.
  *
@@ -2865,26 +2977,40 @@ function prompt(strings, ...values) {
         return new PromptString(spaceTrim$2(strings.join('')));
     }
     const stringsWithHiddenParameters = strings.map((stringsItem) => hideBrackets(stringsItem));
-    const parameterEntries = values.map((value, index) => {
-        const name = buildParameterName(index);
+    const parameterMetadata = values.map((value) => {
         const isPrompt = isPromptString(value);
         const stringValue = isPrompt ? value.toString() : valueToString(value);
         const isInline = isPrompt ? true : shouldInlineParameterValue(stringValue);
         const jsonValue = !isPrompt && !isInline ? normalizeJsonString(stringValue) : null;
+        return { isPrompt, stringValue, isInline, jsonValue };
+    });
+    const parameterNames = buildParameterNames(parameterMetadata.map((entry) => entry.stringValue));
+    const parameterEntries = parameterMetadata.map((entry, index) => {
+        var _a;
+        const name = (_a = parameterNames[index]) !== null && _a !== void 0 ? _a : buildNumericParameterName(index);
         const promptMarker = `${REPLACING_NONCE}prompt-${index}`;
         const parameterMarker = `${REPLACING_NONCE}parameter-${index}`;
-        const templateValue = isPrompt
+        const templateValue = entry.isPrompt
             ? promptMarker
-            : isInline
-                ? escapePromptParameterValue(stringValue, { includeBraces: false })
+            : entry.isInline
+                ? escapePromptParameterValue(entry.stringValue, { includeBraces: false })
                 : parameterMarker;
-        return { name, stringValue, jsonValue, isPrompt, isInline, promptMarker, parameterMarker, templateValue };
+        return {
+            name,
+            stringValue: entry.stringValue,
+            jsonValue: entry.jsonValue,
+            isPrompt: entry.isPrompt,
+            isInline: entry.isInline,
+            promptMarker,
+            parameterMarker,
+            templateValue,
+        };
     });
     const parameters = Object.fromEntries(parameterEntries.map((entry) => [entry.name, entry.templateValue]));
-    const parameterNames = parameterEntries.map((entry) => entry.name);
+    const parameterNamesOrdered = parameterEntries.map((entry) => entry.name);
     // Combine strings and values
     let pipelineString = stringsWithHiddenParameters.reduce((result, stringsItem, i) => {
-        const parameterName = parameterNames[i];
+        const parameterName = parameterNamesOrdered[i];
         return parameterName === undefined
             ? `${result}${stringsItem}`
             : `${result}${stringsItem}${formatParameterPlaceholder(parameterName)}`;
@@ -2897,7 +3023,7 @@ function prompt(strings, ...values) {
         if (!(error instanceof PipelineExecutionError)) {
             throw error;
         }
-        console.error({ pipelineString, parameters, parameterNames, error });
+        console.error({ pipelineString, parameters, parameterNames: parameterNamesOrdered, error });
         throw new UnexpectedError(spaceTrim$2((block) => `
                     Internal error in prompt template literal
                   
@@ -2912,9 +3038,7 @@ function prompt(strings, ...values) {
             continue;
         }
         if (!entry.isInline) {
-            pipelineString = pipelineString
-                .split(entry.parameterMarker)
-                .join(formatParameterPlaceholder(entry.name));
+            pipelineString = pipelineString.split(entry.parameterMarker).join(formatParameterPlaceholder(entry.name));
         }
     }
     const structuredParameters = parameterEntries.filter((entry) => !entry.isPrompt && !entry.isInline);
@@ -3187,18 +3311,6 @@ const CountUtils = {
  * Note: [💞] Ignore a discrepancy between file name and entity name
  */
 
-/**
- * Simple wrapper `new Date().toISOString()`
- *
- * Note: `$` is used to indicate that this function is not a pure function - it is not deterministic because it depends on the current time
- *
- * @returns string_date branded type
- * @public exported from `@promptbook/utils`
- */
-function $getCurrentDate() {
-    return new Date().toISOString();
-}
-
 /**
  * Computes SHA-256 hash of the given object
  *
@@ -3211,18 +3323,6 @@ function computeHash(value) {
  * TODO: [🥬][🥬] Use this ACRY
  */
 
-/**
- * @public exported from `@promptbook/utils`
- */
-function debounce(fn, delay) {
-    let timeout = null;
-    return (...args) => {
-        if (timeout)
-            clearTimeout(timeout);
-        timeout = setTimeout(() => fn(...args), delay);
-    };
-}
-
 /**
  * Makes first letter of a string uppercase
  *
@@ -3234,103 +3334,564 @@ function capitalize(word) {
     return word.substring(0, 1).toUpperCase() + word.substring(1);
 }
 
-/**
- * Creates a human-readable hash as a short story sentence.
- *
- * @public exported from `@promptbook/utils`
- */
-async function linguisticHash(input) {
-    const hash = computeHash(input);
-    return capitalize(createStorySentence(hash));
-}
-const HASH_SEGMENT_LENGTH = 8;
-const STORY_OPENERS = [
-    'once',
-    'long ago',
-    'at dawn',
-    'at dusk',
-    'suddenly',
-    'quietly',
-    'meanwhile',
-    'today',
-    'tonight',
-    'in the end',
-    'before long',
-    'for a moment',
+// spell-checker: disable
+/**
+ * @@@
+ *
+ * @private utility of `linguisticHash`
+ */
+const ADJECTIVES$1 = [
+    'červený',
+    'modrý',
+    'zelený',
+    'žlutý',
+    'rychlý',
+    'pomalý',
+    'jasný',
+    'temný',
+    'veselý',
+    'smutný',
+    'statečný',
+    'klidný',
+    'chytrý',
+    'bystrý',
+    'dychtivý',
+    'honosný',
+    'velkolepý',
+    'hravý',
+    'laskavý',
+    'šťastný',
+    'hrdý',
+    'pošetilý',
+    'moudrý',
+    'mladý',
+    'starý',
+    'veliký',
+    'malý',
+    'drobný',
+    'obrovský',
+    'krátký',
+    'dlouhý',
+    'blízký',
+    'vzdálený',
+    'vnitřní',
+    'vnější',
+    'trpělivý',
+    'stálý',
+    'ušlechtilý',
+    'čistý',
+    'špinavý',
+    'čerstvý',
+    'zvětralý',
+    'ostrý',
+    'tupý',
+    'tlustý',
+    'tenký',
+    'široký',
+    'úzký',
+    'hluboký',
+    'mělký',
+    'mocný',
+    'jemný',
+    'divoký',
+    'tichý',
+    'hlučný',
+    'pokojný',
+    'rušný',
+    'prázdný',
+    'plný',
+    'kulatý',
+    'hranatý',
+    'plochý',
+    'křivý',
+    'tvrdý',
+    'měkký',
+    'teplý',
+    'chladný',
+    'sladký',
+    'kyselý',
+    'hořký',
+    'slaný',
+    'silný',
+    'slabý',
+    'pevný',
+    'pružný',
+    'křehký',
+    'houževnatý',
+    'lesklý',
+    'matný',
+    'kluzký',
+    'lepkavý',
+    'svěží',
+    'vybledlý',
+    'mlhavý',
+    'bouřlivý',
+    'slunný',
+    'větrný',
+    'deštivý',
+    'mrazivý',
+    'zlatý',
+    'stříbrný',
+    'ledový',
+    'žhavý',
+    'prastarý',
+    'moderní',
+    'skrytý',
+    'ztracený',
+    'nalezený',
+    'magický',
+    'tajemný',
+    'kosmický',
+    'hvězdný',
+    'měsíční',
+    'sluneční',
+    'mlžný',
+    'ranní',
+    'večerní',
+    'noční',
+    'denní',
+    'osamělý',
+    'společenský',
+    'soukromý',
+    'veřejný',
+    'tajný',
+    'slavný',
+    'jistý',
+    'neurčitý',
+    'prostý',
+    'snadný',
+    'krotký',
+    'mírný',
+    'horký',
+    'suchý',
+    'mokrý',
+    'vlhký',
+    'promočený',
+    'vyprahlý',
+    'hladový',
+    'žíznivý',
+    'ospalý',
+    'bdělý',
+    'unavený',
+    'líný',
+    'neklidný',
+    'nestálý',
+    'odvážný',
+    'bázlivý',
+    'upřímný',
+    'věrný',
+    'pravý',
+    'falešný',
+    'spravedlivý',
+    'jednoduchý',
+    'složitý',
+    'přirozený',
+    'umělý',
+    'živý',
+    'mrtvý',
+    'zvídavý',
+    'zvláštní',
+    'běžný',
+    'vzácný',
+    'jedinečný',
+    'základní',
+    'prvotní',
+    'hbitý',
 ];
-const STORY_CONNECTORS = ['while', 'as', 'when', 'because', 'and', 'just as', 'after', 'before'];
-const STORY_PREPOSITIONS = [
-    'near',
-    'beside',
-    'under',
-    'within',
-    'beyond',
-    'around',
-    'behind',
-    'across',
-    'above',
-    'beneath',
-    'over',
-    'inside',
-    'outside',
-    'along',
+const NOUNS$1 = [
+    'jablko',
+    'nebe',
+    'strom',
+    'liška',
+    'kočka',
+    'pták',
+    'pes',
+    'řeka',
+    'hora',
+    'les',
+    'oceán',
+    'hvězda',
+    'měsíc',
+    'slunce',
+    'mrak',
+    'květ',
+    'list',
+    'kámen',
+    'vítr',
+    'déšť',
+    'oheň',
+    'led',
+    'kniha',
+    'sen',
+    'píseň',
+    'cesta',
+    'brána',
+    'klíč',
+    'lampa',
+    'mapa',
+    'dům',
+    'město',
+    'most',
+    'pole',
+    'zahrada',
+    'jezero',
+    'pláž',
+    'ostrov',
+    'údolí',
+    'poušť',
+    'svět',
+    'duch',
+    'srdce',
+    'mysl',
+    'duše',
+    'život',
+    'čas',
+    'prostor',
+    'světlo',
+    'stín',
+    'zvuk',
+    'hudba',
+    'hlas',
+    'slovo',
+    'stránka',
+    'příběh',
+    'perla',
+    'zlato',
+    'stříbro',
+    'krystal',
+    'diamant',
+    'smaragd',
+    'rubín',
+    'stezka',
+    'vrchol',
+    'břeh',
+    'vlna',
+    'příliv',
+    'plamen',
+    'jiskra',
+    'paprsek',
+    'semínko',
+    'kořen',
+    'větev',
+    'pupen',
+    'trn',
+    'kůra',
+    'skořápka',
+    'pírko',
+    'křídlo',
+    'dráp',
+    'tlapa',
+    'hnízdo',
+    'jeskyně',
+    'hájek',
+    'věž',
+    'hrad',
+    'koruna',
+    'meč',
+    'štít',
+    'mince',
+    'drahokam',
+    'prsten',
+    'zvonek',
+    'hodiny',
+    'kompas',
+    'kotva',
+    'pochodeň',
+    'flétna',
+    'harfa',
+    'buben',
+    'čočka',
+    'sklo',
+    'písek',
+    'prach',
+    'mlha',
+    'rosa',
+    'svítání',
+    'soumrak',
+    'noc',
+    'den',
+    'rok',
+    'věk',
+    'blesk',
+    'kapka',
+    'bouře',
+    'sníh',
+    'kroupa',
+    'kouř',
+    'pára',
+    'plyn',
+    'kov',
+    'skála',
+    'hlína',
+    'sůl',
+    'cukr',
+    'dřevo',
+    'kost',
+    'kůže',
+    'tělo',
+    'krev',
+    'buňka',
+    'atom',
+    'tep',
+    'dech',
+    'vzdech',
+    'jméno',
+    'ozvěna',
+    'obraz',
+    'vize',
+    'myšlenka',
+    'nápad',
+    'plán',
+    'cíl',
+    'přání',
+    'naděje',
+    'strach',
+    'radost',
+    'láska',
+    'nenávist',
+    'vůle',
+    'síla',
+    'energie',
+    'pohyb',
+    'rychlost',
+    'místo',
+    'bod',
+    'linie',
+    'tvar',
+    'forma',
+    'velikost',
+    'hmota',
+    'váha',
+    'teplo',
+    'chlad',
+    'barva',
+    'tón',
+    'rytmus',
+    'nálada',
+    'stav',
+    'krok',
+    'pád',
+    'skok',
+    'běh',
+    'let',
+    'klid',
+    'úkol',
+    'práce',
+    'hra',
+    'sport',
+    'umění',
+    'řemeslo',
+    'nástroj',
+    'loď',
+    'člun',
+    'auto',
+    'kolo',
+    'vlak',
+    'letadlo',
+    'uzel',
+    'síť',
+    'krabice',
+    'taška',
+    'dóza',
+    'hrnek',
+    'miska',
+    'talíř',
+    'lžíce',
+    'vidlička',
+    'nůž',
+    'pánev',
+    'hrnec',
+    'postel',
+    'stůl',
+    'židle',
+    'dveře',
+    'stěna',
+    'střecha',
+    'podlaha',
+    'okno',
+    'chodba',
 ];
-const STORY_TEMPLATES = [
-    (parts) => `${parts.opener}, the ${parts.adjective1} ${parts.noun1} was ${parts.verb1} ${parts.connector} the ${parts.adjective2} ${parts.noun2} was ${parts.verb2} ${parts.preposition} the ${parts.adjective3} ${parts.noun3}.`,
-    (parts) => `${parts.opener}, the ${parts.adjective1} ${parts.noun1} was ${parts.verb1} ${parts.preposition} the ${parts.adjective2} ${parts.noun2}, and the ${parts.adjective3} ${parts.noun3} was ${parts.verb2}.`,
-    (parts) => `${parts.opener}, the ${parts.adjective1} ${parts.noun1} was ${parts.verb1}, and the ${parts.adjective2} ${parts.noun2} was ${parts.verb2} ${parts.preposition} the ${parts.adjective3} ${parts.noun3}.`,
-    (parts) => `${parts.opener}, the ${parts.adjective1} ${parts.noun1} was ${parts.verb1} ${parts.connector} the ${parts.adjective2} ${parts.noun2} was ${parts.verb2}, ${parts.preposition} the ${parts.adjective3} ${parts.noun3}.`,
+const VERBS$1 = [
+    'skáče',
+    'tančí',
+    'letí',
+    'běží',
+    'zpívá',
+    'svítí',
+    'roste',
+    'plyne',
+    'padá',
+    'stoupá',
+    'spí',
+    'kráčí',
+    'mluví',
+    'myslí',
+    'sní',
+    'hledá',
+    'nachází',
+    'dává',
+    'bere',
+    'tvoří',
+    'hoří',
+    'mrzne',
+    'taje',
+    'dýchá',
+    'pulzuje',
+    'bije',
+    'žije',
+    'učí',
+    'ví',
+    'skrývá',
+    'ukazuje',
+    'láme',
+    'opravuje',
+    'ztrácí',
+    'nalézá',
+    'začíná',
+    'končí',
+    'plave',
+    'pluje',
+    'klouže',
+    'točí',
+    'mění',
+    'bledne',
+    'mizí',
+    'rodí',
+    'hučí',
+    'pláče',
+    'závodí',
+    'plíží',
+    'sleduje',
+    'slyší',
+    'cítí',
+    'touží',
+    'doufá',
+    'miluje',
+    'bloudí',
+    'putuje',
+    'cestuje',
+    'překračuje',
+    'potkává',
+    'drží',
+    'sdílí',
+    'jiskří',
+    'plápolá',
+    'léčí',
+    'řeší',
+    'otevírá',
+    'zavírá',
+    'zvedá',
+    'táhne',
+    'tlačí',
+    'hází',
+    'chytá',
+    'dělá',
+    'vidí',
+    'chutná',
+    'voní',
+    'spěchá',
+    'zastaví',
+    'jde',
+    'přichází',
+    'odchází',
+    'jedná',
+    'existuje',
+    'zmenšuje',
+    'rozšiřuje',
+    'zužuje',
+    'hřeje',
+    'chladí',
+    'suší',
+    'máčí',
+    'plní',
+    'vyprazdňuje',
+    'pouští',
+    'získává',
+    'vítězí',
+    'selhává',
+    'zkouší',
+    'používá',
+    'dostává',
+    'měří',
+    'stojí',
+    'dosahuje',
+    'míjí',
+    'udeří',
+    'vede',
+    'následuje',
+    'pomáhá',
+    'slouží',
+    'trénuje',
+    'kóduje',
+    'píše',
+    'čte',
+    'kreslí',
+    'maluje',
+    'tvaruje',
+    'spojuje',
+    'dělí',
+    'váže',
+    'zraňuje',
+    'chrání',
+    'bojuje',
+    'brání',
+    'útočí',
+    'uniká',
+    'lapá',
+    'osvobozuje',
+    'poutá',
+    'spřádá',
+    'tká',
+    'vrhá',
+    'nese',
+    'přenáší',
+    'vrací',
+    'zrychluje',
+    'zpomaluje',
+    'probouzí',
+    'uspává',
+    'šeptá',
+    'volá',
+    'hledí',
+    'čeká',
+    'bdí',
+    'rozkvétá',
+    'klíčí',
+    'zraje',
+    'chvěje',
+    'třpytí',
+    'shromažďuje',
+    'rozhazuje',
+    'tápe',
+    'žhne',
+    'vibruje',
+    'šumí',
+    'stéká',
+    'vypráví',
+    'plánuje',
+    'počítá',
+    'váhá',
+    'riskuje',
 ];
 /**
- * Extracts a deterministic numeric seed from a SHA-256 hash.
- */
-function getHashSeed(hash, segmentIndex) {
-    const expandedHash = `${hash}${hash}`;
-    const start = (segmentIndex * HASH_SEGMENT_LENGTH + segmentIndex) % hash.length;
-    return parseInt(expandedHash.substring(start, start + HASH_SEGMENT_LENGTH), 16);
-}
-/**
- * Picks a deterministic item from a list based on the hash seed.
- */
-function pickFromHash(hash, segmentIndex, list) {
-    const seed = getHashSeed(hash, segmentIndex);
-    return list[seed % list.length];
-}
-/**
- * Index constants for story part selection to avoid magic numbers.
- */
-const ADJECTIVE3_INDEX = 9;
-const NOUN3_INDEX = 10;
-/**
- * Creates the deterministic story parts used by the sentence templates.
+ * Czech word lists used by the linguistic hash.
+ *
+ * @private utility of `linguisticHash`
  */
-function createStoryParts(hash) {
-    return {
-        opener: pickFromHash(hash, 0, STORY_OPENERS),
-        connector: pickFromHash(hash, 1, STORY_CONNECTORS),
-        preposition: pickFromHash(hash, 2, STORY_PREPOSITIONS),
-        adjective1: pickFromHash(hash, 3, ADJECTIVES),
-        noun1: pickFromHash(hash, 4, NOUNS),
-        verb1: pickFromHash(hash, 5, VERBS),
-        adjective2: pickFromHash(hash, 6, ADJECTIVES),
-        noun2: pickFromHash(hash, 7, NOUNS),
-        verb2: pickFromHash(hash, 8, VERBS),
-        adjective3: pickFromHash(hash, ADJECTIVE3_INDEX, ADJECTIVES),
-        noun3: pickFromHash(hash, NOUN3_INDEX, NOUNS),
-    };
-}
+const LINGUISTIC_HASH_WORD_LISTS_CS = {
+    adjective: ADJECTIVES$1,
+    noun: NOUNS$1,
+    verb: VERBS$1,
+};
 /**
- * Index constant for story template selection to avoid magic numbers.
+ * Note: [💞] Ignore a discrepancy between file name and entity name
  */
-const STORY_TEMPLATE_INDEX = 11;
+
 /**
- * Builds a short, memorable story sentence from the hash.
+ * @@@
+ *
+ * @private utility of `linguisticHash`
  */
-function createStorySentence(hash) {
-    const parts = createStoryParts(hash);
-    const template = pickFromHash(hash, STORY_TEMPLATE_INDEX, STORY_TEMPLATES);
-    return template(parts).trim();
-}
 const ADJECTIVES = [
     'red',
     'blue',
@@ -4005,8 +4566,227 @@ const VERBS = [
     'spinning',
 ];
 /**
- * TODO: Prompt: Extract number constants and word list to a separate file for reuse.
+ * English word lists used by the linguistic hash.
+ *
+ * @private utility of `linguisticHash`
+ */
+const LINGUISTIC_HASH_WORD_LISTS_EN = {
+    adjective: ADJECTIVES,
+    noun: NOUNS,
+    verb: VERBS,
+};
+/**
+ * Note: [💞] Ignore a discrepancy between file name and entity name
+ */
+
+/**
+ * Default language used for linguistic hashes.
+ *
+ * @private utility of `linguisticHash`
+ */
+const DEFAULT_LINGUISTIC_HASH_LANGUAGE = 'en';
+/**
+ * @@@
+ *
+ * @private utility of `linguisticHash`
+ */
+const LANGUAGE_CONFIGS = {
+    en: {
+        language: 'en',
+        label: 'English',
+        wordLists: LINGUISTIC_HASH_WORD_LISTS_EN,
+    },
+    cs: {
+        language: 'cs',
+        label: 'Czech',
+        wordLists: LINGUISTIC_HASH_WORD_LISTS_CS,
+    },
+};
+/**
+ * Normalizes a requested language to a supported linguistic hash language.
+ *
+ * @private utility of `linguisticHash`
+ */
+function normalizeLinguisticHashLanguage(language) {
+    if (typeof language !== 'string') {
+        return DEFAULT_LINGUISTIC_HASH_LANGUAGE;
+    }
+    const normalized = language.trim().toLowerCase();
+    if (normalized === 'cs') {
+        return 'cs';
+    }
+    if (normalized === 'en') {
+        return 'en';
+    }
+    return DEFAULT_LINGUISTIC_HASH_LANGUAGE;
+}
+/**
+ * Returns the language configuration for linguistic hash generation.
+ *
+ * @private utility of `linguisticHash`
+ */
+function getLinguisticHashLanguageConfig(language) {
+    const normalized = normalizeLinguisticHashLanguage(language);
+    return LANGUAGE_CONFIGS[normalized];
+}
+
+// <- TODO: !!!! Remove re-exports
+/**
+ * Creates a human-readable hash as a short, story-like phrase.
+ *
+ * @param wordCount how many words to include (defaults to {@link DEFAULT_LINGUISTIC_HASH_WORD_COUNT}, clamped to
+ * {@link MIN_LINGUISTIC_HASH_WORD_COUNT}..{@link MAX_LINGUISTIC_HASH_WORD_COUNT})
+ * @param language optional language code (defaults to {@link DEFAULT_LINGUISTIC_HASH_LANGUAGE})
+ *
+ * @public exported from `@promptbook/utils`
+ */
+async function linguisticHash(input, wordCount, language) {
+    const hash = computeHash(input);
+    const normalizedWordCount = normalizeLinguisticHashWordCount(wordCount);
+    const languageConfig = getLinguisticHashLanguageConfig(language);
+    const words = createLinguisticHashWords(hash, normalizedWordCount, languageConfig.wordLists);
+    return capitalize(words.join(' '));
+}
+/**
+ * @@@
+ *
+ * @private utility of `linguisticHash`
+ */
+const HASH_SEGMENT_LENGTH = 8;
+/**
+ * The minimum number of words for a linguistic hash.
+ *
+ * @private utility of `linguisticHash`
+ */
+const MIN_LINGUISTIC_HASH_WORD_COUNT = 1;
+/**
+ * The default number of words for a linguistic hash.
+ *
+ * @private utility of `linguisticHash`
+ */
+const DEFAULT_LINGUISTIC_HASH_WORD_COUNT = 7;
+/**
+ * Extracts a deterministic numeric seed from a SHA-256 hash.
+ *
+ * @private utility of `linguisticHash`
+ */
+function getHashSeed(hash, segmentIndex) {
+    const expandedHash = `${hash}${hash}`;
+    const start = (segmentIndex * HASH_SEGMENT_LENGTH + segmentIndex) % hash.length;
+    return parseInt(expandedHash.substring(start, start + HASH_SEGMENT_LENGTH), 16);
+}
+/**
+ * Picks a deterministic item from a list based on the hash seed.
+ *
+ * @private utility of `linguisticHash`
+ */
+function pickFromHash(hash, segmentIndex, list) {
+    const seed = getHashSeed(hash, segmentIndex);
+    return list[seed % list.length];
+}
+/**
+ * Ordered word kinds used to build the linguistic hash output.
+ *
+ * @private utility of `linguisticHash`
+ */
+const WORD_SEQUENCE = [
+    'adjective',
+    'noun',
+    'verb',
+    'adjective',
+    'noun',
+    'verb',
+    'adjective',
+    'noun',
+    'verb',
+    'adjective',
+    'noun',
+    'verb',
+    'adjective',
+    'noun',
+    'verb',
+    'adjective',
+    'noun',
+    'verb',
+    'adjective',
+    'noun',
+];
+/**
+ * The maximum number of words for a linguistic hash.
+ *
+ * @private utility of `linguisticHash`
+ */
+const MAX_LINGUISTIC_HASH_WORD_COUNT = WORD_SEQUENCE.length;
+/**
+ * Index of the noun used for single-word hashes.
+ *
+ * @private utility of `linguisticHash`
+ */
+const SINGLE_WORD_INDEX = 1;
+/**
+ * Normalizes the word count to a supported integer range.
+ *
+ * @private utility of `linguisticHash`
+ */
+function normalizeLinguisticHashWordCount(wordCount) {
+    if (typeof wordCount !== 'number' || !Number.isFinite(wordCount)) {
+        return DEFAULT_LINGUISTIC_HASH_WORD_COUNT;
+    }
+    const rounded = Math.round(wordCount);
+    return Math.min(MAX_LINGUISTIC_HASH_WORD_COUNT, Math.max(MIN_LINGUISTIC_HASH_WORD_COUNT, rounded));
+}
+/**
+ * Picks a deterministic word from the hash by kind.
+ *
+ * @private utility of `linguisticHash`
+ */
+function pickWordFromHash(hash, segmentIndex, wordKind, wordLists) {
+    return pickFromHash(hash, segmentIndex, wordLists[wordKind]);
+}
+/**
+ * Creates the deterministic word sequence used for the linguistic hash output.
+ *
+ * @private utility of `linguisticHash`
+ */
+function createLinguisticHashWordSequence(hash, wordLists) {
+    return WORD_SEQUENCE.map((wordKind, index) => pickWordFromHash(hash, index, wordKind, wordLists));
+}
+/**
+ * Selects the requested number of words from the hash output.
+ *
+ * @private utility of `linguisticHash`
+ */
+function createLinguisticHashWords(hash, wordCount, wordLists) {
+    const words = createLinguisticHashWordSequence(hash, wordLists);
+    if (wordCount === 1) {
+        return [words[SINGLE_WORD_INDEX]];
+    }
+    return words.slice(0, wordCount);
+}
+
+/**
+ * Simple wrapper `new Date().toISOString()`
+ *
+ * Note: `$` is used to indicate that this function is not a pure function - it is not deterministic because it depends on the current time
+ *
+ * @returns string_date branded type
+ * @public exported from `@promptbook/utils`
+ */
+function $getCurrentDate() {
+    return new Date().toISOString();
+}
+
+/**
+ * @public exported from `@promptbook/utils`
  */
+function debounce(fn, delay) {
+    let timeout = null;
+    return (...args) => {
+        if (timeout)
+            clearTimeout(timeout);
+        timeout = setTimeout(() => fn(...args), delay);
+    };
+}
 
 /**
  * Function parseNumber will parse number from string