@tstdl/base 0.93.123 → 0.93.126

package/ai/ai-file.service.js

@@ -1,233 +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;
-};
-import { createReadStream } from 'node:fs';
-import { stat } from 'node:fs/promises';
-import { Readable } from 'node:stream';
-import { ReadableStream as NodeReadableStream } from 'node:stream/web';
-import { Storage } from '@google-cloud/storage';
-import { FileState, GoogleGenAI } from '@google/genai';
-import { CancellationSignal } from '../cancellation/token.js';
-import { AsyncEnumerable } from '../enumerable/async-enumerable.js';
-import { DetailsError } from '../errors/details.error.js';
-import { Singleton } from '../injector/decorators.js';
-import { inject, injectArgument } from '../injector/inject.js';
-import { Logger } from '../logger/logger.js';
-import { createArray } from '../utils/array/array.js';
-import { backoffGenerator } from '../utils/backoff.js';
-import { formatBytes } from '../utils/format.js';
-import { readBinaryStream } from '../utils/stream/stream-reader.js';
-import { assertDefinedPass, isBlob, isDefined, isUndefined } from '../utils/type-guards.js';
-import { AiModuleOptions } from './module.js';
-import { isPathFileInput } from './types.js';
-/**
- * Manages file uploads and state for use with AI models.
- * Handles both Google Generative AI File API and Google Cloud Storage for Vertex AI.
- */
-let AiFileService = class AiFileService {
-    #options = injectArgument(this, { optional: true }) ?? inject(AiModuleOptions);
-    #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,
-    });
-    #storage = isDefined(this.#options.vertex) ? new Storage({ keyFile: assertDefinedPass(this.#options.keyFile, 'Key file not defined'), projectId: this.#options.vertex.project }) : undefined;
-    #fileMap = new Map();
-    #fileUriMap = new Map();
-    #logger = inject(Logger, 'AiFileService');
-    #cancellationSignal = inject(CancellationSignal);
-    #backoffOptions = {
-        cancellationSignal: this.#cancellationSignal,
-        strategy: 'linear',
-        initialDelay: 1000,
-        increase: 500,
-        jitter: 0.2,
-        maximumDelay: 10000,
-    };
-    #bucket;
-    /**
-     * Uploads and processes a single file, making it available for AI model consumption.
-     * @param fileInput The file to process.
-     * @returns A promise that resolves to a {@link FileContentPart} for use in AI requests.
-     */
-    async processFile(fileInput) {
-        const file = await this.getFile(fileInput);
-        this.#fileMap.set(file.id, file);
-        this.#fileUriMap.set(file.uri, file);
-        return { file: file.id };
-    }
-    /**
-     * Uploads and processes multiple files in parallel, making them available for AI model consumption.
-     * @param fileInputs The files to process.
-     * @returns A promise that resolves to an array of {@link FileContentPart} for use in AI requests.
-     */
-    async processFiles(fileInputs) {
-        const files = await this.getFiles(fileInputs);
-        return files.map((file) => {
-            this.#fileMap.set(file.id, file);
-            this.#fileUriMap.set(file.uri, file);
-            return { file: file.id };
-        });
-    }
-    /**
-     * Retrieves a file by its internal ID.
-     * The file must have been processed by this service instance before.
-     * @param id The internal ID of the file.
-     * @returns The file, or `undefined` if not found.
-     */
-    getFileById(id) {
-        return this.#fileMap.get(id);
-    }
-    /**
-     * Retrieves a file by its URI (e.g., GCS URI).
-     * The file must have been processed by this service instance before.
-     * @param uri The URI of the file.
-     * @returns The file, or `undefined` if not found.
-     */
-    getFileByUri(uri) {
-        return this.#fileUriMap.get(uri);
-    }
-    async getFile(fileInput) {
-        const id = crypto.randomUUID();
-        const file = await this.uploadFile(fileInput, id);
-        this.#logger.verbose(`Processing file "${id}"...`);
-        await this.waitForFileActive(file);
-        return file;
-    }
-    async getFiles(fileInputs) {
-        const ids = createArray(fileInputs.length, () => crypto.randomUUID());
-        const files = await AsyncEnumerable.from(fileInputs).parallelMap(5, true, async (file, index) => await this.uploadFile(file, ids[index])).toArray();
-        this.#logger.verbose(`Processing ${fileInputs.length} files...`);
-        await this.waitForFilesActive(files);
-        return files;
-    }
-    async uploadFile(fileInput, id) {
-        if (isDefined(this.#storage)) {
-            return await this.uploadFileVertex(fileInput, id);
-        }
-        return await this.uploadFileGenAi(fileInput, id);
-    }
-    async uploadFileVertex(fileInput, id) {
-        const bucket = await this.getBucket();
-        const file = bucket.file(id);
-        let stream;
-        let contentType;
-        let size;
-        if (isBlob(fileInput)) {
-            stream = Readable.fromWeb(fileInput.stream());
-            contentType = fileInput.type;
-            size = fileInput.size;
-        }
-        else if (isPathFileInput(fileInput)) {
-            const stats = await stat(fileInput.path);
-            stream = createReadStream(fileInput.path);
-            contentType = fileInput.mimeType;
-            size = stats.size;
-        }
-        else {
-            stream = Readable.fromWeb(fileInput.stream);
-            contentType = fileInput.mimeType;
-            size = fileInput.size;
-        }
-        this.#logger.verbose(`Uploading file "${id}"${isDefined(size) ? ` (${formatBytes(size)})` : ''}...`);
-        await file.save(stream, { contentType, resumable: false });
-        return {
-            id,
-            name: id,
-            uri: `gs://${bucket.name}/${file.name}`,
-            mimeType: contentType,
-        };
-    }
-    async uploadFileGenAi(fileInput, id) {
-        let uploadData;
-        let contentType;
-        let size;
-        if (isBlob(fileInput)) {
-            uploadData = fileInput;
-            contentType = fileInput.type;
-            size = fileInput.size;
-        }
-        else if (isPathFileInput(fileInput)) {
-            const fileState = await stat(fileInput.path);
-            uploadData = fileInput.path;
-            contentType = fileInput.mimeType;
-            size = fileState.size;
-        }
-        else {
-            const fileBytes = await readBinaryStream(fileInput.stream);
-            const blob = new Blob([fileBytes], { type: fileInput.mimeType });
-            uploadData = blob;
-            contentType = blob.type;
-            size = blob.size;
-        }
-        this.#logger.verbose(`Uploading file "${id}" (${formatBytes(size)})...`);
-        // upload supports paths and blobs, but not streams (yet)
-        const response = await this.#genAI.files.upload({ file: uploadData, config: { mimeType: contentType } });
-        return {
-            id,
-            name: assertDefinedPass(response.name, 'Missing file name'),
-            uri: assertDefinedPass(response.uri, 'Missing file uri'),
-            mimeType: assertDefinedPass(response.mimeType, 'Missing file mime type'),
-        };
-    }
-    async getBucket() {
-        if (isUndefined(this.#options.vertex)) {
-            throw new Error('Not using Vertex');
-        }
-        if (isDefined(this.#bucket)) {
-            return this.#bucket;
-        }
-        const bucketName = assertDefinedPass(this.#options.vertex.bucket, 'Bucket not specified');
-        const bucket = this.#storage.bucket(bucketName);
-        const [exists] = await bucket.exists();
-        if (!exists) {
-            this.#logger.info(`Bucket "${bucketName}" not found, creating...`);
-            const [createdBucket] = await this.#storage.createBucket(bucketName, {
-                location: this.#options.vertex.location,
-                lifecycle: {
-                    rule: [{
-                            action: { type: 'Delete' },
-                            condition: { age: 1 },
-                        }],
-                },
-            });
-            this.#bucket = createdBucket;
-        }
-        else {
-            this.#bucket = bucket;
-        }
-        return this.#bucket;
-    }
-    async waitForFileActive(file) {
-        if (isDefined(this.#options.vertex)) {
-            // For Vertex, uploads to GCS are instantly "active"
-            return;
-        }
-        for await (const backoff of backoffGenerator(this.#backoffOptions)) {
-            const state = await this.#genAI.files.get({ name: file.name });
-            if (state.state == FileState.ACTIVE) {
-                this.#logger.verbose(`File "${file.id}" is active.`);
-                return;
-            }
-            if (state.state == FileState.FAILED) {
-                throw new DetailsError(state.error?.message ?? `Failed to process file ${state.name}`, state.error?.details);
-            }
-            backoff();
-        }
-    }
-    async waitForFilesActive(files) {
-        // parallelizing does not help here, as each file upload is independently processed in the background
-        for (const file of files) {
-            await this.waitForFileActive(file);
-        }
-    }
-};
-AiFileService = __decorate([
-    Singleton()
-], AiFileService);
-export { AiFileService };

package/ai/ai-session.d.ts

@@ -1,38 +0,0 @@
-import type { OneOrMany } from '../types/index.js';
-import type { AiService, CallFunctionsOptions, SpecializedGenerationResult } from './ai.service.js';
-import type { Content, GenerationRequest, GenerationResult, SchemaFunctionDeclarations, SchemaFunctionDeclarationsResult } from './types.js';
-/**
- * Represents a conversational session with an AI model.
- *
- * This class maintains the history of contents (messages) in a conversation,
- * allowing for stateful, multi-turn interactions with the AI.
- */
-export declare class AiSession {
-    #private;
-    /**
-     * The history of contents in the session.
-     */
-    readonly contents: Content[];
-    /**
-     * Creates an instance of `AiSession`.
-     * @param aiService The {@link AiService} instance to use for AI interactions.
-     */
-    constructor(aiService: AiService);
-    /**
-     * Adds new content to the session's history without triggering a generation.
-     * @param content The content or contents to add.
-     */
-    addContent(content: OneOrMany<Content>): void;
-    /**
-     * Prompts the model to call one or more functions based on the provided context and session history.
-     * The new user content and the resulting model response (function calls) are automatically added to the session history.
-     * @param options The options for the function call request.
-     */
-    callFunctions<const T extends SchemaFunctionDeclarations>(options: CallFunctionsOptions<T>): Promise<SpecializedGenerationResult<SchemaFunctionDeclarationsResult<T>[]>>;
-    /**
-     * Generates content from the model based on the provided request and the current session history.
-     * The new user content and the resulting model response are automatically added to the session history.
-     * @param request The generation request.
-     */
-    generate(request: GenerationRequest): Promise<GenerationResult>;
-}

package/ai/ai-session.js

@@ -1,50 +0,0 @@
-import { toArray } from '../utils/array/array.js';
-/**
- * Represents a conversational session with an AI model.
- *
- * This class maintains the history of contents (messages) in a conversation,
- * allowing for stateful, multi-turn interactions with the AI.
- */
-export class AiSession {
-    #aiService;
-    /**
-     * The history of contents in the session.
-     */
-    contents = [];
-    /**
-     * Creates an instance of `AiSession`.
-     * @param aiService The {@link AiService} instance to use for AI interactions.
-     */
-    constructor(aiService) {
-        this.#aiService = aiService;
-    }
-    /**
-     * Adds new content to the session's history without triggering a generation.
-     * @param content The content or contents to add.
-     */
-    addContent(content) {
-        this.contents.push(...toArray(content));
-    }
-    /**
-     * Prompts the model to call one or more functions based on the provided context and session history.
-     * The new user content and the resulting model response (function calls) are automatically added to the session history.
-     * @param options The options for the function call request.
-     */
-    async callFunctions(options) {
-        this.contents.push(...toArray(options.contents));
-        const result = await this.#aiService.callFunctions({ ...options, contents: this.contents });
-        this.contents.push(result.raw.content);
-        return result;
-    }
-    /**
-     * Generates content from the model based on the provided request and the current session history.
-     * The new user content and the resulting model response are automatically added to the session history.
-     * @param request The generation request.
-     */
-    async generate(request) {
-        this.contents.push(...toArray(request.contents));
-        const result = await this.#aiService.generate({ ...request, contents: this.contents });
-        this.contents.push(result.content);
-        return result;
-    }
-}

package/ai/ai.service.d.ts

@@ -1,126 +0,0 @@
-import type { Resolvable, resolveArgumentType } from '../injector/interfaces.js';
-import { type SchemaTestable } from '../schema/index.js';
-import type { Enumeration as EnumerationType, EnumerationValue } from '../types/index.js';
-import { AiSession } from './ai-session.js';
-import { AiModuleOptions } from './module.js';
-import { type AiModel, type FileContentPart, type FileInput, type GenerationOptions, type GenerationRequest, type GenerationResult, type SchemaFunctionDeclarations, type SchemaFunctionDeclarationsResult } from './types.js';
-/**
- * A generation result that includes a specialized, typed result alongside the raw generation data.
- * @template T The type of the specialized result.
- */
-export type SpecializedGenerationResult<T> = {
-    /** The specialized, typed result. */
-    result: T;
-    /** The raw, underlying generation result from the AI model. */
-    raw: GenerationResult;
-};
-/**
- * An async generator for specialized generation results, which also provides access to the final raw generation data.
- * @template T The type of the specialized result yielded by the generator.
- */
-export type SpecializedGenerationResultGenerator<T> = AsyncGenerator<T> & {
-    raw: Promise<GenerationResult>;
-};
-export type AiServiceArgument = AiModuleOptions;
-export type ClassificationResult<T extends EnumerationType> = {
-    types: {
-        type: EnumerationValue<T>;
-        confidence: 'high' | 'medium' | 'low';
-    }[] | null;
-};
-export type AnalyzeContentResult<T extends EnumerationType> = {
-    content: string[];
-    documentTypes: ClassificationResult<T>[];
-    tags: string[];
-};
-/**
- * Options for a function-calling request.
- * @template T The schema declarations for the available functions.
- */
-export type CallFunctionsOptions<T extends SchemaFunctionDeclarations> = Pick<GenerationRequest, 'contents' | 'model' | 'systemInstruction' | 'functionCallingMode'> & GenerationOptions & {
-    /** The function declarations available for the model to call. */
-    functions: T;
-};
-/**
- * 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.
- */
-export declare class AiService implements Resolvable<AiServiceArgument> {
-    #private;
-    /**
-     * The default AI model to use for requests if not specified otherwise.
-     */
-    readonly defaultModel: AiModel;
-    readonly [resolveArgumentType]: AiServiceArgument;
-    /**
-     * Creates a new {@link AiSession} for managing conversational history.
-     */
-    createSession(): AiSession;
-    /**
-     * 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.
-     */
-    processFile(fileInput: FileInput): Promise<FileContentPart>;
-    /**
-     * 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.
-     */
-    processFiles(fileInputs: FileInput[]): Promise<FileContentPart[]>;
-    /**
-     * 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: string): FileContentPart;
-    /**
-     * 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.
-     */
-    callFunctions<const T extends SchemaFunctionDeclarations>(options: CallFunctionsOptions<T>): Promise<SpecializedGenerationResult<SchemaFunctionDeclarationsResult<T>[]>>;
-    /**
-     * 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<const T extends SchemaFunctionDeclarations>(options: CallFunctionsOptions<T>): SpecializedGenerationResultGenerator<SchemaFunctionDeclarationsResult<T>>;
-    /**
-     * 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}.
-     */
-    generate<S>(request: GenerationRequest<S>): Promise<GenerationResult<S>>;
-    /**
-     * 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.
-     */
-    generateStream<S>(request: GenerationRequest<S>): AsyncGenerator<GenerationResult<S>>;
-    private _callFunctionsStream;
-    private getModelOutputTokenLimit;
-    private _getModelOutputTokenLimit;
-    private convertContents;
-    private convertContent;
-    private convertFunctions;
-    private convertGoogleContent;
-    private mapModel;
-}
-/**
- * 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 declare function mergeGenerationStreamItems<S>(items: GenerationResult<S>[], schema?: SchemaTestable<S>): GenerationResult<S>;