@tstdl/base 0.93.123 → 0.93.126

package/ai/ai.service.js

@@ -1,481 +0,0 @@
-var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
-    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
-    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
-    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
-    return c > 3 && r && Object.defineProperty(target, key, r), r;
-};
-var _a;
-var AiService_1;
-import { ApiError, FinishReason, FunctionCallingConfigMode as GoogleFunctionCallingMode, GoogleGenAI } from '@google/genai';
-import { match } from 'ts-pattern';
-import { CancellationSignal } from '../cancellation/index.js';
-import { NotSupportedError } from '../errors/not-supported.error.js';
-import { Singleton } from '../injector/decorators.js';
-import { inject, injectArgument } from '../injector/inject.js';
-import { Logger } from '../logger/logger.js';
-import { DeferredPromise } from '../promise/deferred-promise.js';
-import { LazyPromise } from '../promise/lazy-promise.js';
-import { convertToOpenApiSchema } from '../schema/converters/open-api-converter.js';
-import { Schema } from '../schema/index.js';
-import { toArray } from '../utils/array/array.js';
-import { mapAsync } from '../utils/async-iterable-helpers/map.js';
-import { toArrayAsync } from '../utils/async-iterable-helpers/to-array.js';
-import { backoffGenerator } from '../utils/backoff.js';
-import { lazyObject } from '../utils/object/lazy-property.js';
-import { hasOwnProperty, objectEntries } from '../utils/object/object.js';
-import { assertDefinedPass, isDefined, isError, isInstanceOf, isNotNull, isNull, isUndefined } from '../utils/type-guards.js';
-import { resolveValueOrAsyncProvider } from '../utils/value-or-provider.js';
-import { AiFileService } from './ai-file.service.js';
-import { AiSession } from './ai-session.js';
-import { AiModuleOptions } from './module.js';
-import { isSchemaFunctionDeclarationWithHandler } from './types.js';
-const functionCallingModeMap = {
-    auto: GoogleFunctionCallingMode.AUTO,
-    force: GoogleFunctionCallingMode.ANY,
-    none: GoogleFunctionCallingMode.NONE,
-};
-let generationCounter = 0;
-/**
- * A service for interacting with Google's Generative AI models (Gemini).
- *
- * This service provides methods for content generation, function calling, and file processing,
- * supporting both standard Google AI and Vertex AI endpoints.
- */
-let AiService = AiService_1 = class AiService {
-    #options = injectArgument(this, { optional: true }) ?? inject(AiModuleOptions);
-    #fileService = inject(AiFileService, this.#options);
-    #logger = inject(Logger, AiService_1.name);
-    #cancellationSignal = inject(CancellationSignal);
-    #genAI = new GoogleGenAI({
-        vertexai: isDefined(this.#options.vertex?.project),
-        project: this.#options.vertex?.project,
-        location: this.#options.vertex?.location,
-        googleAuthOptions: isDefined(this.#options.vertex?.project) ? { apiKey: this.#options.apiKey, keyFile: this.#options.keyFile } : undefined,
-        apiKey: isUndefined(this.#options.vertex?.project) ? assertDefinedPass(this.#options.apiKey, 'Api key not defined') : undefined,
-    });
-    #maxOutputTokensCache = new Map();
-    #backoffOptions = {
-        cancellationSignal: this.#cancellationSignal,
-        strategy: 'exponential',
-        initialDelay: 5000,
-        increase: 1.5,
-        jitter: 0.2,
-        maximumDelay: 30000,
-    };
-    /**
-     * The default AI model to use for requests if not specified otherwise.
-     */
-    defaultModel = this.#options.defaultModel ?? 'gemini-2.5-flash-lite';
-    /**
-     * Creates a new {@link AiSession} for managing conversational history.
-     */
-    createSession() {
-        return new AiSession(this);
-    }
-    /**
-     * Processes a single file for use in AI requests by uploading it and making it available to the model.
-     * @param fileInput The file to process.
-     * @returns A promise that resolves to a {@link FileContentPart} which can be included in a generation request.
-     */
-    async processFile(fileInput) {
-        return await this.#fileService.processFile(fileInput);
-    }
-    /**
-     * Processes multiple files in parallel for use in AI requests.
-     * @param fileInputs The files to process.
-     * @returns A promise that resolves to an array of {@link FileContentPart}s which can be included in generation requests.
-     */
-    async processFiles(fileInputs) {
-        return await this.#fileService.processFiles(fileInputs);
-    }
-    /**
-     * Creates a file content part from a previously processed file ID.
-     * This does not re-upload the file.
-     * @param id The ID of the file, obtained from {@link AiFileService.processFile} or {@link AiFileService.processFiles}.
-     * @returns A {@link FileContentPart} for use in a generation request.
-     */
-    getFileById(id) {
-        return { file: id };
-    }
-    /**
-     * A high-level method to prompt the model to call one or more functions.
-     * This method sends the request and parses the model's response to identify function calls.
-     * If the function declaration includes a handler, it will be executed automatically.
-     * @param options The options for the function call request.
-     * @returns A promise that resolves to a {@link SpecializedGenerationResult} containing the function call results.
-     */
-    async callFunctions(options) {
-        const generation = await this.generate({
-            model: options.model,
-            generationOptions: {
-                temperature: 0.5,
-                ...options,
-            },
-            systemInstruction: options.systemInstruction,
-            functions: options.functions,
-            functionCallingMode: options.functionCallingMode ?? 'force',
-            contents: options.contents,
-        });
-        const result = [];
-        for (const call of generation.functionCalls) {
-            const fn = assertDefinedPass(options.functions[call.name], 'Function in response not declared.');
-            const parametersSchema = await resolveValueOrAsyncProvider(fn.parameters);
-            const parameters = isDefined(parametersSchema) ? parametersSchema.parse(call.parameters) : call.parameters;
-            const handlerResult = isSchemaFunctionDeclarationWithHandler(fn) ? await fn.handler(parameters) : undefined;
-            result.push({
-                functionName: call.name,
-                parameters: parameters,
-                handlerResult: handlerResult,
-                getFunctionResultContentPart: () => ({ functionResult: { name: call.name, value: handlerResult } }),
-            });
-        }
-        return {
-            result,
-            raw: generation,
-        };
-    }
-    /**
-     * A streaming version of `callFunctions`.
-     * Yields function call results as they are received from the model.
-     * If function declarations include handlers, they are executed as soon as a complete function call is parsed.
-     * @param options The options for the function call request.
-     * @returns A {@link SpecializedGenerationResultGenerator} that yields function call results.
-     */
-    callFunctionsStream(options) {
-        const itemsPromise = new DeferredPromise();
-        const generator = this._callFunctionsStream(options, itemsPromise);
-        generator.raw = new LazyPromise(async () => {
-            const items = await itemsPromise;
-            return mergeGenerationStreamItems(items);
-        });
-        return generator;
-    }
-    /**
-     * Generates content from the model based on a request.
-     * This method waits for the full response from the model. For streaming, use {@link generateStream}.
-     * @param request The generation request.
-     * @returns A promise that resolves to the complete {@link GenerationResult}.
-     */
-    async generate(request) {
-        const items = await toArrayAsync(this.generateStream(request));
-        return mergeGenerationStreamItems(items, request.generationSchema);
-    }
-    /**
-     * Generates content as a stream.
-     * Yields partial generation results as they are received from the model.
-     * @param request The generation request.
-     * @returns An `AsyncGenerator` that yields {@link GenerationResult} chunks.
-     */
-    async *generateStream(request) {
-        const generationNumber = ++generationCounter;
-        const googleFunctionDeclarations = isDefined(request.functions) ? await this.convertFunctions(request.functions) : undefined;
-        const config = {
-            systemInstruction: request.systemInstruction,
-            temperature: request.generationOptions?.temperature,
-            topP: request.generationOptions?.topP,
-            topK: request.generationOptions?.topK,
-            presencePenalty: request.generationOptions?.presencePenalty,
-            frequencyPenalty: request.generationOptions?.frequencyPenalty,
-            responseMimeType: isDefined(request.generationSchema) ? 'application/json' : undefined,
-            responseSchema: isDefined(request.generationSchema) ? convertToOpenApiSchema(request.generationSchema) : undefined,
-            safetySettings: [],
-            tools: (isDefined(googleFunctionDeclarations) && (googleFunctionDeclarations.length > 0)) ? [{ functionDeclarations: googleFunctionDeclarations }] : undefined,
-            toolConfig: isDefined(request.functionCallingMode)
-                ? { functionCallingConfig: { mode: functionCallingModeMap[request.functionCallingMode] } }
-                : undefined,
-            thinkingConfig: {
-                thinkingBudget: request.generationOptions?.thinkingBudget,
-            },
-        };
-        const model = this.mapModel(request.model);
-        const maxModelTokens = await this.getModelOutputTokenLimit(model);
-        const maxTotalOutputTokens = request.generationOptions?.maxOutputTokens ?? maxModelTokens ?? 65535;
-        const inputContent = this.convertContents(request.contents);
-        let iterations = 0;
-        let totalPromptTokens = 0;
-        let totalCachedTokens = 0;
-        let totalThoughtsTokens = 0;
-        let totalOutputTokens = 0;
-        let totalToolsTokens = 0;
-        while (totalOutputTokens < maxTotalOutputTokens) {
-            let generation;
-            let triesLeft = 10;
-            for await (const backoff of backoffGenerator(this.#backoffOptions)) {
-                try {
-                    this.#logger.verbose(`[C:${generationNumber}] [I:${iterations + 1}] Generating...`);
-                    generation = await this.#genAI.models.generateContentStream({
-                        model,
-                        config: {
-                            ...config,
-                            maxOutputTokens: Math.min(1000000, maxTotalOutputTokens - totalOutputTokens),
-                        },
-                        contents: inputContent,
-                    });
-                    break;
-                }
-                catch (error) {
-                    triesLeft -= 1;
-                    if ((triesLeft > 0) && isInstanceOf(error, ApiError) && ((error.status == 429) || (error.status == 503))) {
-                        this.#logger.verbose(`Retrying after transient error: ${error.message}`);
-                        backoff();
-                        continue;
-                    }
-                    throw error; // Non-retryable error
-                }
-            }
-            iterations++;
-            let lastUsageMetadata;
-            let candidate;
-            for await (const generationResponse of generation) {
-                candidate = generationResponse.candidates?.at(0);
-                const rawContent = candidate?.content;
-                if (isUndefined(candidate)) {
-                    throw new Error('No candidate returned.');
-                }
-                if (isUndefined(rawContent)) {
-                    throw new Error('No content returned.');
-                }
-                inputContent.push(rawContent);
-                const { cachedContentTokenCount = 0, candidatesTokenCount = 0, promptTokenCount = 0, thoughtsTokenCount = 0, toolUsePromptTokenCount = 0, totalTokenCount = 0, } = generationResponse.usageMetadata ?? {};
-                lastUsageMetadata = generationResponse.usageMetadata;
-                const content = this.convertGoogleContent(rawContent);
-                let text;
-                let functionCallParts;
-                const result = {
-                    content,
-                    get text() {
-                        if (isUndefined(text)) {
-                            const textParts = content.parts.filter((part) => hasOwnProperty(part, 'text')).map((part) => part.text);
-                            text = (textParts.length > 0) ? textParts.join('') : null;
-                        }
-                        return text;
-                    },
-                    get json() {
-                        throw new NotSupportedError('JSON not supported in streamed items. Use mergeGenerationStreamItems to combine all streamed items.');
-                    },
-                    get functionCalls() {
-                        if (isUndefined(functionCallParts)) {
-                            functionCallParts = content.parts.filter((part) => hasOwnProperty(part, 'functionCall')).map((part) => part.functionCall);
-                        }
-                        return functionCallParts;
-                    },
-                    finishReason: candidate.finishReason == FinishReason.MAX_TOKENS
-                        ? 'maxTokens'
-                        : candidate.finishReason == FinishReason.STOP
-                            ? 'stop'
-                            : 'unknown',
-                    usage: {
-                        iterations,
-                        cached: totalCachedTokens + cachedContentTokenCount,
-                        prompt: totalPromptTokens + promptTokenCount,
-                        thoughts: totalThoughtsTokens + thoughtsTokenCount,
-                        output: totalOutputTokens + candidatesTokenCount,
-                        tools: totalToolsTokens + toolUsePromptTokenCount,
-                        total: totalTokenCount,
-                    },
-                };
-                yield result;
-            }
-            totalCachedTokens += lastUsageMetadata?.cachedContentTokenCount ?? 0;
-            totalPromptTokens += lastUsageMetadata?.promptTokenCount ?? 0;
-            totalThoughtsTokens += lastUsageMetadata?.thoughtsTokenCount ?? 0;
-            totalOutputTokens += lastUsageMetadata?.responseTokenCount ?? 0;
-            totalToolsTokens += lastUsageMetadata?.toolUsePromptTokenCount ?? 0;
-            if (candidate?.finishReason != FinishReason.MAX_TOKENS) {
-                break;
-            }
-        }
-    }
-    async *_callFunctionsStream(options, itemsPromise) {
-        const generationStream = this.generateStream({
-            model: options.model,
-            generationOptions: {
-                temperature: 0.5,
-                ...options,
-            },
-            systemInstruction: options.systemInstruction,
-            functions: options.functions,
-            functionCallingMode: options.functionCallingMode ?? 'force',
-            contents: options.contents,
-        });
-        const items = [];
-        for await (const generation of generationStream) {
-            items.push(generation);
-            for (const call of generation.functionCalls) {
-                const fn = assertDefinedPass(options.functions[call.name], 'Function in response not declared.');
-                const parametersSchema = await resolveValueOrAsyncProvider(fn.parameters);
-                const parameters = isDefined(parametersSchema) ? parametersSchema.parse(call.parameters, { coerce: true }) : call.parameters;
-                const handlerResult = isSchemaFunctionDeclarationWithHandler(fn) ? await fn.handler(parameters) : undefined;
-                yield {
-                    functionName: call.name,
-                    parameters: parameters,
-                    handlerResult: handlerResult,
-                    getFunctionResultContentPart: () => ({ functionResult: { name: call.name, value: handlerResult } }),
-                };
-            }
-        }
-        itemsPromise.resolve(items);
-    }
-    async getModelOutputTokenLimit(model) {
-        const existingValue = this.#maxOutputTokensCache.get(model);
-        if (isDefined(existingValue)) {
-            return await existingValue;
-        }
-        const promise = this._getModelOutputTokenLimit(model);
-        this.#maxOutputTokensCache.set(model, promise);
-        promise
-            .then((limit) => this.#maxOutputTokensCache.set(model, limit))
-            .catch(() => this.#maxOutputTokensCache.delete(model));
-        return await promise;
-    }
-    async _getModelOutputTokenLimit(model) {
-        let modelInfo;
-        let triesLeft = 10;
-        for await (const backoff of backoffGenerator(this.#backoffOptions)) {
-            try {
-                modelInfo = await this.#genAI.models.get({ model });
-                break;
-            }
-            catch (error) {
-                triesLeft -= 1;
-                if ((triesLeft > 0) && isError(error) && (error.message.includes('429 Too Many Requests') || error.message.includes('503 Service Unavailable'))) {
-                    this.#logger.verbose(`Could not get model info for ${model} due to a transient error (${error.message}). Retrying...`);
-                    backoff();
-                    continue;
-                }
-                throw error;
-            }
-        }
-        if (isUndefined(modelInfo.outputTokenLimit)) {
-            return null;
-        }
-        return modelInfo.outputTokenLimit;
-    }
-    convertContents(contents) {
-        return toArray(contents).map((content) => this.convertContent(content));
-    }
-    convertContent(content) {
-        return {
-            role: content.role,
-            parts: content.parts.map((part) => {
-                if (hasOwnProperty(part, 'text')) {
-                    return { text: part.text };
-                }
-                if (hasOwnProperty(part, 'file')) {
-                    const file = assertDefinedPass(this.#fileService.getFileById(part.file), `File ${part.file} not found.`);
-                    return { fileData: { fileUri: file.uri, mimeType: file.mimeType } };
-                }
-                if (hasOwnProperty(part, 'functionResult')) {
-                    return { functionResponse: { name: part.functionResult.name, response: part.functionResult.value } };
-                }
-                if (hasOwnProperty(part, 'functionCall')) {
-                    return { functionCall: { name: part.functionCall.name, args: part.functionCall.parameters } };
-                }
-                throw new NotSupportedError('Unsupported content part.');
-            }),
-        };
-    }
-    async convertFunctions(functions) {
-        const mapped = mapAsync(objectEntries(functions), async ([name, declaration]) => {
-            const enabled = await resolveValueOrAsyncProvider(declaration.enabled);
-            if (enabled == false) {
-                return undefined;
-            }
-            const parametersSchema = await resolveValueOrAsyncProvider(declaration.parameters);
-            return {
-                name,
-                description: declaration.description,
-                parameters: isDefined(parametersSchema) ? convertToOpenApiSchema(parametersSchema) : undefined,
-            };
-        });
-        const functionsArray = await toArrayAsync(mapped);
-        return functionsArray.filter(isDefined);
-    }
-    convertGoogleContent(content) {
-        return {
-            role: content.role,
-            parts: isUndefined(content.parts)
-                ? []
-                : content.parts
-                    .map((part) => {
-                    if (isDefined(part.text)) {
-                        if (part.text.length == 0) {
-                            return null;
-                        }
-                        return { text: part.text };
-                    }
-                    if (isDefined(part.fileData)) {
-                        const file = assertDefinedPass(this.#fileService.getFileByUri(assertDefinedPass(part.fileData.fileUri, 'Missing file uri')), 'File not found.');
-                        return { file: file.id };
-                    }
-                    if (isDefined(part.functionResponse)) {
-                        return { functionResult: { name: assertDefinedPass(part.functionResponse.name, 'Missing function name'), value: part.functionResponse.response } };
-                    }
-                    if (isDefined(part.functionCall)) {
-                        return { functionCall: { name: assertDefinedPass(part.functionCall.name, 'Missing function name'), parameters: part.functionCall.args } };
-                    }
-                    throw new NotSupportedError('Unsupported content part.');
-                })
-                    .filter(isNotNull),
-        };
-    }
-    mapModel(model) {
-        return match(model)
-            .with('small', () => 'gemini-2.5-flash-lite')
-            .with('medium', () => 'gemini-2.5-flash')
-            .with('large', () => 'gemini-2.5-pro')
-            .otherwise(() => model ?? this.defaultModel);
-    }
-};
-AiService = AiService_1 = __decorate([
-    Singleton()
-], AiService);
-export { AiService };
-/**
- * Merges an array of streaming generation results into a single, consolidated result.
- * This is useful for combining the chunks from a streaming response into a final object.
- * @param items The array of {@link GenerationResult} items from a stream.
- * @param schema An optional schema to parse the merged JSON output.
- * @returns A single, merged {@link GenerationResult}.
- */
-export function mergeGenerationStreamItems(items, schema) {
-    if (items.length == 0) {
-        return {
-            content: { role: 'model', parts: [] },
-            text: null,
-            json: undefined,
-            functionCalls: [],
-            finishReason: 'unknown',
-            usage: { iterations: 0, cached: 0, prompt: 0, thoughts: 0, output: 0, tools: 0, total: 0 },
-        };
-    }
-    const parts = items.flatMap((item) => item.content.parts);
-    return lazyObject({
-        content: { value: { role: 'model', parts } },
-        text() {
-            const textParts = parts.filter((part) => hasOwnProperty(part, 'text')).map((part) => part.text);
-            return (textParts.length > 0) ? textParts.join('') : null;
-        },
-        json() {
-            if (isUndefined(schema)) {
-                return undefined;
-            }
-            if (isNull(this.text)) {
-                throw new Error('No text to parse available.');
-            }
-            let parsed;
-            try {
-                parsed = JSON.parse(this.text);
-            }
-            catch (error) {
-                throw new SyntaxError(`Failed to parse model output as JSON. Raw text: "${this.text}"`, { cause: error });
-            }
-            return Schema.parse(schema, parsed, { coerce: true });
-        },
-        functionCalls() {
-            return parts.filter((part) => hasOwnProperty(part, 'functionCall')).map((part) => part.functionCall);
-        },
-        finishReason: { value: items.at(-1).finishReason },
-        usage: { value: items.at(-1).usage },
-    });
-}

package/ai/functions.d.ts

@@ -1,9 +0,0 @@
-import type { FunctionDeclaration } from '@google/genai';
-import type { AbstractConstructor } from '../types/index.js';
-/**
- * Extracts Google AI function declarations from a class decorated with schema information.
- * It iterates over the properties of the class schema and converts `FunctionSchema` instances
- * into the format required by the Google Generative AI API.
- * @param type The constructor of the class to extract function declarations from.
- */
-export declare function getFunctionDeclarations(type: AbstractConstructor): FunctionDeclaration[];

package/ai/functions.js

@@ -1,38 +0,0 @@
-import { convertToOpenApiSchema } from '../schema/converters/open-api-converter.js';
-import { FunctionSchema, getObjectSchema, object } from '../schema/index.js';
-import { fromEntries, objectEntries } from '../utils/object/object.js';
-import { isNotNull, isNull, isString } from '../utils/type-guards.js';
-/**
- * Extracts Google AI function declarations from a class decorated with schema information.
- * It iterates over the properties of the class schema and converts `FunctionSchema` instances
- * into the format required by the Google Generative AI API.
- * @param type The constructor of the class to extract function declarations from.
- */
-export function getFunctionDeclarations(type) {
-    const objectSchema = getObjectSchema(type);
-    return objectEntries(objectSchema.properties)
-        .map(([key, schema]) => {
-        if (!(schema instanceof FunctionSchema)) {
-            return null;
-        }
-        return {
-            name: `${type.name}.${key}`,
-            description: schema.description ?? undefined,
-            parameters: isNull(schema.parameterSchemas)
-                ? undefined
-                : getFunctionDeclarationParameters(schema),
-        };
-    })
-        .filter(isNotNull);
-}
-function getFunctionDeclarationParameters(functionSchema) {
-    const entries = functionSchema.parameterSchemas.map((schema, index) => {
-        const parameterName = functionSchema.parameterNames[index];
-        if (!isString(parameterName)) {
-            throw new Error(`Parameter ${index} requires a name.`);
-        }
-        return [parameterName, schema];
-    });
-    const parametersSchema = object(fromEntries(entries));
-    return convertToOpenApiSchema(parametersSchema);
-}

package/ai/module.d.ts

@@ -1,26 +0,0 @@
-import type { AiModel } from './types.js';
-/**
- * Options for configuring the AI Module.
- */
-export declare class AiModuleOptions {
-    /** Google AI API key. */
-    apiKey?: string;
-    /** Path to the Google Cloud credentials file. */
-    keyFile?: string;
-    /** Vertex AI specific options. If provided, the service will use Vertex AI endpoints. */
-    vertex?: {
-        project: string;
-        location: string;
-        bucket?: string;
-    };
-    /**
-     * The default model to use for generation requests.
-     * @default 'small'
-     */
-    defaultModel?: AiModel;
-}
-/**
- * Configures the {@link AiService}.
- * @param options The configuration options for the AI services.
- */
-export declare function configureAiService(options: AiModuleOptions): void;

package/ai/module.js

@@ -1,25 +0,0 @@
-import { Injector } from '../injector/injector.js';
-/**
- * Options for configuring the AI Module.
- */
-export class AiModuleOptions {
-    /** Google AI API key. */
-    apiKey;
-    /** Path to the Google Cloud credentials file. */
-    keyFile;
-    /** Vertex AI specific options. If provided, the service will use Vertex AI endpoints. */
-    vertex;
-    /**
-     * The default model to use for generation requests.
-     * @default 'small'
-     */
-    defaultModel;
-}
-;
-/**
- * Configures the {@link AiService}.
- * @param options The configuration options for the AI services.
- */
-export function configureAiService(options) {
-    Injector.register(AiModuleOptions, { useValue: options });
-}