@cellaware/utils 8.11.19 → 8.11.20

package/dist/llm/chain-store.js

@@ -0,0 +1,284 @@
+import fs from 'fs';
+import { BaseChain } from 'langchain/chains';
+import { ChatPromptTemplate } from "@langchain/core/prompts";
+import { ChatOpenAI } from "@langchain/openai";
+import { StringOutputParser } from "@langchain/core/output_parsers";
+import { getLLMTransactionCost } from './cost.js';
+const CHAIN_TIMEOUT_MS = 150_000;
+const TRANSLATION_CHAIN_NAME = 'translation_chain';
+/**
+ * `SingleActionChain` only supports single interaction with LLM, and only 1
+ * output key is allowed. Output key is defaulted to `answer`.
+ */
+export class SingleActionChain extends BaseChain {
+    constructor(fields, name, inputKeys) {
+        super(fields);
+        Object.defineProperty(this, "_name", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "llm", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "_inputKeys", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "_outputKey", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "prompt", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "promptTemplate", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        if (inputKeys.length == 0) {
+            throw new Error(`SINGLE_ACTION_CHAIN: Chain '${name}' needs at least one input key!`);
+        }
+        this._name = name;
+        this.llm = fields.llm;
+        this._inputKeys = inputKeys;
+        this._outputKey = 'answer';
+        this.prompt = fields.prompt;
+        this.promptTemplate = ChatPromptTemplate.fromTemplate(this.prompt);
+    }
+    async _call(values, runManager) {
+        let output = {
+            [this._outputKey]: ''
+        };
+        const llmChain = this.promptTemplate
+            .pipe(this.llm)
+            .pipe(new StringOutputParser());
+        let llmInputs = {};
+        for (const inputKey of this._inputKeys) {
+            llmInputs[inputKey] = values[inputKey];
+        }
+        let callbacks = undefined;
+        if (!!runManager && !!runManager.getChild()) {
+            callbacks = runManager.getChild().handlers;
+        }
+        const llmAnswer = await llmChain.invoke(llmInputs, {
+            callbacks
+        });
+        output[this._outputKey] = llmAnswer;
+        return output;
+    }
+    _chainType() {
+        return this._name;
+    }
+    get inputKeys() {
+        return this._inputKeys;
+    }
+    get outputKeys() {
+        return [this._outputKey];
+    }
+    getModelName() {
+        return this.llm.modelName;
+    }
+    getPrompt() {
+        return this.prompt;
+    }
+}
+export function createSingleActionChain(name, modelName, inputKeys, prompt, temperature, verbose) {
+    const llm = new ChatOpenAI({
+        modelName, temperature: temperature ?? 0, configuration: {
+            organization: process.env.OPENAI_ORGANIZATION,
+            timeout: CHAIN_TIMEOUT_MS
+        }
+    });
+    return new SingleActionChain({
+        llm,
+        prompt,
+        verbose: verbose ?? false
+    }, name, inputKeys);
+}
+/**
+ * A `ChainStore` is a chain registry and calling interface. The `ChainStore`
+ * keeps a map of all registered chains.
+ *
+ * The following chains are built-in:
+ *  - `translation_chain`: `translate()`
+ *
+ */
+export class ChainStore {
+    constructor(promptsPath, defaultModelName) {
+        Object.defineProperty(this, "promptsPath", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "chains", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        this.promptsPath = promptsPath;
+        this.chains = new Map();
+        this.initBuiltinChains(defaultModelName);
+    }
+    initBuiltinChains(defaultModelName) {
+        // Translation Chain:
+        {
+            this.addExistingChain(createSingleActionChain(TRANSLATION_CHAIN_NAME, defaultModelName ?? 'gpt-4o-mini', ['statement', 'language'], `You are a helpful AI translator who translates an English statement to {language}.
+
+Given an English statement, translate the English statement into {language}. 
+
+Here is the English statement that you need to translate to {language}:
+{statement}
+
+Your translation here:
+`));
+        }
+    }
+    static getTokenUsage(chainName, modelName, tokenUsage) {
+        return {
+            chain: chainName,
+            model: modelName,
+            tokenUsage,
+            cost: getLLMTransactionCost(tokenUsage, modelName)
+        };
+    }
+    getPrompt(chainName, templateChainName) {
+        let prompt = {
+            content: '',
+            variables: []
+        };
+        const path = !!templateChainName ? `${this.promptsPath}/${templateChainName}.md` : `${this.promptsPath}/${chainName}.md`;
+        if (!fs.existsSync(path)) {
+            throw new Error(`CHAIN_STORE: Prompt file '${path}' not found`);
+        }
+        const content = fs.readFileSync(path, 'utf8');
+        if (content.length === 0) {
+            throw new Error(`CHAIN_STORE: Prompt file '${path}' is empty`);
+        }
+        let matches = content.matchAll(/{.*?}/gm);
+        let distinctMatches = new Set();
+        for (const match of Array.from(matches)) {
+            let matchStr = match[0];
+            // Exclude escaped curly braces.
+            if (!matchStr.startsWith('{{')) {
+                distinctMatches.add(matchStr.substring(1, matchStr.length - 1));
+            }
+        }
+        prompt.content = content;
+        prompt.variables = Array.from(distinctMatches);
+        return prompt;
+    }
+    /**
+     * - `name`: Chain name
+     * - `template`: Template chain name to copy prompt from
+     * - `options`: LLM options
+     * - `verbose`: OpenAI verbose parameter
+     */
+    addChain(name, template, options, verbose) {
+        const prompt = this.getPrompt(name, template);
+        let llmArgs = {
+            modelName: options.modelName,
+            temperature: options.temperature ?? 0,
+            configuration: {
+                organization: process.env.OPENAI_ORGANIZATION,
+                timeout: CHAIN_TIMEOUT_MS
+            }
+        };
+        if (!!options.openai) {
+            if (!!options.openai.reasoning_effort) {
+                llmArgs.reasoning_effort = options.openai.reasoning_effort;
+            }
+            if (!!options.openai.verbosity) {
+                llmArgs.verbosity = options.openai.verbosity;
+            }
+        }
+        const llm = new ChatOpenAI(llmArgs);
+        const chain = new SingleActionChain({
+            llm,
+            prompt: prompt.content,
+            verbose: verbose ?? false
+        }, name, prompt.variables);
+        this.chains.set(name, chain);
+    }
+    addExistingChain(chain) {
+        this.chains.set(chain._chainType(), chain);
+    }
+    async callChain(name, args, tokenUsages) {
+        let chain = this.chains.get(name);
+        if (!chain) {
+            throw new Error(`CHAIN_STORE: Chain '${name}' does not exist`);
+        }
+        let presentInputKeySet = new Set();
+        for (const inputKey of Object.keys(args)) {
+            presentInputKeySet.add(inputKey);
+        }
+        let presentInputKeys = Array.from(presentInputKeySet);
+        // Make sure all input keys are present.
+        for (const inputKey of chain.inputKeys) {
+            if (!presentInputKeys.includes(inputKey)) {
+                throw new Error(`CHAIN_STORE: Input key '${inputKey}' not present for chain '${chain._chainType()}'`);
+            }
+        }
+        return chain.invoke(args, {
+            callbacks: [
+                {
+                    handleLLMEnd: async (output) => {
+                        const usage = output?.llmOutput?.tokenUsage;
+                        tokenUsages.push(ChainStore.getTokenUsage(chain._chainType(), chain.getModelName(), usage));
+                    },
+                }
+            ]
+        });
+    }
+    async translate(statement, language, tokenUsages) {
+        // No need to translate if requested language is in default language.
+        const DEFAULT_LANGUAGE = 'English';
+        if (language.toLowerCase() === DEFAULT_LANGUAGE.toLowerCase()) {
+            return statement;
+        }
+        const translationAnswer = await this.callChain(TRANSLATION_CHAIN_NAME, { statement, language }, tokenUsages ?? []);
+        let translationAnswerStr = translationAnswer.answer;
+        /*
+            Need to check if AI indicator exists in the answer. It is possible that the
+            translation chain will include this in an answer. Pretty sure this happens
+            because the translation chain can see conversation history, and messages from
+            AI will be prefixed as such.
+        */
+        const AI_PREFIX = 'AI: ';
+        if (translationAnswerStr.includes(AI_PREFIX)) {
+            console.log(`CHAIN_STORE: Removing AI indicator from translation answer`);
+            translationAnswerStr = translationAnswerStr.substring(translationAnswerStr.indexOf(AI_PREFIX) + AI_PREFIX.length);
+        }
+        // Remove 'Your translation here:' if it is there.
+        if (translationAnswerStr.includes('Your translation here:')) {
+            translationAnswerStr = translationAnswerStr.substring(translationAnswerStr.indexOf('Your translation here:') + 'Your translation here:'.length);
+        }
+        return translationAnswerStr.trim();
+    }
+    getPrompts() {
+        let buf = '';
+        for (const chain of Array.from(this.chains.values())) {
+            buf += `================================================= =================================================
+                                            ${chain._chainType()}
+================================================= =================================================
+${chain.getPrompt()}
+`;
+        }
+        return buf;
+    }
+}

package/dist/llm/cost.d.ts

@@ -0,0 +1,3 @@
+import { ModelName } from "./model.js";
+export declare function getLLMCostPerToken(modelName: ModelName): any;
+export declare function getLLMTransactionCost(tokenUsage: any, modelName: ModelName): number;

package/dist/llm/cost.js

@@ -0,0 +1,42 @@
+// https://platform.openai.com/docs/pricing
+const MODEL_COSTS = {
+    'gpt-5.2-pro': { inputCost: 21.00, outputCost: 168.00 },
+    'gpt-5.2': { inputCost: 1.75, outputCost: 14.00 },
+    'gpt-5.2-chat-latest': { inputCost: 1.75, outputCost: 14.00 },
+    'gpt-5.2-codex': { inputCost: 1.75, outputCost: 14.00 },
+    'gpt-5.1': { inputCost: 1.25, outputCost: 10.00 },
+    'gpt-5': { inputCost: 1.25, outputCost: 10.00 },
+    'gpt-5-mini': { inputCost: 0.25, outputCost: 2.00 },
+    'gpt-5-nano': { inputCost: 0.05, outputCost: 0.40 },
+    'gpt-4.1': { inputCost: 2.00, outputCost: 8.00 },
+    'gpt-4.1-mini': { inputCost: 0.40, outputCost: 1.60 },
+    'gpt-4.1-nano': { inputCost: 0.10, outputCost: 0.40 },
+    'gpt-4o': { inputCost: 2.50, outputCost: 10.00 },
+    'gpt-4o-mini': { inputCost: 0.15, outputCost: 0.60 },
+    'o1': { inputCost: 15.00, outputCost: 60.00 },
+    'o1-mini': { inputCost: 1.10, outputCost: 4.40 },
+    'o3': { inputCost: 2.00, outputCost: 8.00 },
+    'o3-mini': { inputCost: 1.10, outputCost: 4.40 },
+    'o4-mini': { inputCost: 1.10, outputCost: 4.40 },
+};
+export function getLLMCostPerToken(modelName) {
+    const cost = MODEL_COSTS[modelName];
+    if (!cost) {
+        throw new Error(`Model '${modelName}' cost is not configured`);
+    }
+    let inputCost = cost.inputCost;
+    let outputCost = cost.outputCost;
+    // OpenAI model costs are measured in millions of tokens -- therefore we need to divide each figure by 1,000,000 before returning.
+    const unit = 1_000_000.0;
+    inputCost /= unit;
+    outputCost /= unit;
+    return { inputCost, outputCost };
+}
+export function getLLMTransactionCost(tokenUsage, modelName) {
+    let cost = 0.0;
+    if (!!tokenUsage) {
+        const { inputCost, outputCost } = getLLMCostPerToken(modelName);
+        cost = (tokenUsage.promptTokens * inputCost) + (tokenUsage.completionTokens * outputCost);
+    }
+    return cost;
+}

package/dist/llm/model.d.ts

@@ -0,0 +1,12 @@
+export type ModelName = 'gpt-5.2-pro' | 'gpt-5.2-codex' | 'gpt-5.2-chat-latest' | 'gpt-5.2' | 'gpt-5.1' | 'gpt-5' | 'gpt-5-mini' | 'gpt-5-nano' | 'gpt-4.1' | 'gpt-4.1-mini' | 'gpt-4.1-nano' | 'gpt-4o' | 'gpt-4o-mini' | 'o1' | 'o1-mini' | 'o3' | 'o3-mini' | 'o4-mini';
+export type ReasoningEffort = 'minimal' | 'low' | 'medium' | 'high';
+export type Verbosity = 'low' | 'medium' | 'high';
+export interface OpenAIModelOptions {
+    reasoning_effort?: ReasoningEffort;
+    verbosity?: Verbosity;
+}
+export interface ModelOptions {
+    modelName: string;
+    temperature?: number;
+    openai?: OpenAIModelOptions;
+}

package/dist/llm/model.js

@@ -0,0 +1 @@
+export {};

package/dist/stopwatch.d.ts

@@ -0,0 +1,8 @@
+export declare class Stopwatch {
+    private startTime?;
+    private elapsed;
+    start(): void;
+    stop(): void;
+    reset(): void;
+    getElapsedMs(): number;
+}

package/dist/stopwatch.js

@@ -0,0 +1,36 @@
+export class Stopwatch {
+    constructor() {
+        Object.defineProperty(this, "startTime", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "elapsed", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: 0n
+        });
+    }
+    start() {
+        if (!this.startTime) {
+            this.startTime = process.hrtime.bigint();
+        }
+    }
+    stop() {
+        if (!!this.startTime) {
+            this.elapsed += process.hrtime.bigint() - this.startTime;
+            this.startTime = undefined;
+        }
+    }
+    reset() {
+        this.elapsed = 0n;
+        this.startTime = undefined;
+    }
+    getElapsedMs() {
+        const now = this.startTime ? process.hrtime.bigint() : 0n;
+        const total = this.elapsed + (this.startTime ? now - this.startTime : 0n);
+        return Number(total) / 1e6;
+    }
+}

package/dist/util.d.ts

@@ -0,0 +1,45 @@
+export interface KeyValuePair {
+    key: string;
+    value: any;
+}
+export declare function sleep(ms: number): Promise<any>;
+export declare function reverse(str: string): string;
+export declare function base64Encode(str: string): string;
+export declare function base64Decode(str: string): string;
+export declare function isArrayLike(obj: any): boolean;
+/**
+ * Default `idx` is 100.
+ */
+export declare function truncateValue(value: any, idx?: number): any;
+/**
+ * Default `idx` is 100.
+ */
+export declare function truncateValuePreserveNewLines(value: string, idx?: number): string;
+export declare function initDate(timeZone?: string): Date;
+export declare function convertDateTimeZone(date: Date, timeZone: string): Date;
+export declare function isDaylightSavingTime(timeZone?: string): boolean;
+export declare function isLeapYear(timeZone?: string): boolean;
+export declare function getDaysInMonth(timeZone?: string): number;
+export declare function getCurrentDayInMonth(timeZone?: string): number;
+export declare function getDaysInYear(timeZone?: string): 366 | 365;
+export declare function getCurrentMonth(timeZone?: string): number;
+export declare function getCurrentYear(timeZone?: string): number;
+export declare function isDateString(value: any): boolean;
+/**
+ * NOTE: `stopIdx` represents last character index of word
+ *      ex: ABC -> `startIdx`: 0 `stopIdx`: 2
+ */
+export interface QueryRegexMatch {
+    word: string;
+    startIdx: number;
+    stopIdx: number;
+}
+/**
+ * Will only return matches that **are not** contained in single quotes,
+ * double quotes, single line, or multiline comments.
+ */
+export declare function getQueryMatches(query: string, regex: RegExp, specificMatchGroup?: number): QueryRegexMatch[];
+export declare function removeQueryMatches(query: string, matches: QueryRegexMatch[]): string;
+export declare function replaceQueryMatches(query: string, matches: QueryRegexMatch[], replacement: string, useMatchAsSuffix?: boolean): string;
+export declare function removeMarkdownIndicators(input: string): string;
+export declare function removePrefixIndicators(input: string, prefixes: string[]): string;