@tstdl/base 0.92.145 → 0.92.147

package/ai/ai-file.service.d.ts

@@ -1,7 +1,9 @@
-import '../polyfills.js';
 import type { Resolvable, resolveArgumentType } from '../injector/interfaces.js';
 import type { AiServiceOptions } from './ai.service.js';
 import type { FileContentPart, FileInput } from './types.js';
+/**
+ * Options for {@link AiFileService}.
+ */
 export type AiFileServiceOptions = Pick<AiServiceOptions, 'apiKey' | 'keyFile' | 'vertex'>;
 export type AiFileServiceArgument = AiFileServiceOptions;
 type File = {
@@ -10,12 +12,38 @@ type File = {
     uri: string;
     mimeType: string;
 };
+/**
+ * Manages file uploads and state for use with AI models.
+ * Handles both Google Generative AI File API and Google Cloud Storage for Vertex AI.
+ */
 export declare class AiFileService implements Resolvable<AiFileServiceArgument> {
     #private;
     readonly [resolveArgumentType]: AiFileServiceArgument;
+    /**
+     * 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.
+     */
     processFile(fileInput: FileInput): Promise<FileContentPart>;
+    /**
+     * 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.
+     */
     processFiles(fileInputs: FileInput[]): Promise<FileContentPart[]>;
+    /**
+     * 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: string): File | undefined;
+    /**
+     * 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: string): File | undefined;
     private getFile;
     private getFiles;

package/ai/ai-file.service.js

@@ -4,21 +4,25 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
     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 '../polyfills.js';
 import { openAsBlob } from 'node:fs';
+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 { NotImplementedError } from '../errors/not-implemented.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 { timeout } from '../utils/timing.js';
 import { assertDefinedPass, isBlob, isDefined, isUndefined } from '../utils/type-guards.js';
-import { millisecondsPerSecond } from '../utils/units.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);
     #genAI = new GoogleGenAI({
@@ -32,13 +36,32 @@ let AiFileService = class AiFileService {
     #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) => {
@@ -47,9 +70,21 @@ let AiFileService = class AiFileService {
             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);
     }
@@ -74,18 +109,16 @@ let AiFileService = class AiFileService {
             : await openAsBlob(fileInput.path, { type: fileInput.mimeType });
         this.#logger.verbose(`Uploading file "${id}" (${formatBytes(blob.size)})...`);
         if (isDefined(this.#storage)) {
-            throw new NotImplementedError();
-            /*
             const bucket = await this.getBucket();
-            const [file] = await bucket.upload(path, { destination: id, contentType: mimeType });
-      
+            const file = bucket.file(id);
+            const blobStream = Readable.fromWeb(blob.stream());
+            await file.save(blobStream, { contentType: blob.type, resumable: false });
             return {
-              id,
-              name: id,
-              uri: file.cloudStorageURI.toString(),
-              mimeType
+                id,
+                name: id, // For Vertex, name is the GCS object id
+                uri: `gs://${bucket.name}/${file.name}`,
+                mimeType: blob.type,
             };
-            */
         }
         const response = await this.#genAI.files.upload({ file: blob, config: { mimeType: blob.type } });
         return {
@@ -103,9 +136,11 @@ let AiFileService = class AiFileService {
             return this.#bucket;
         }
         const bucketName = assertDefinedPass(this.#options.vertex.bucket, 'Bucket not specified');
-        const [exists] = await this.#storage.bucket(bucketName).exists();
+        const bucket = this.#storage.bucket(bucketName);
+        const [exists] = await bucket.exists();
         if (!exists) {
-            const [bucket] = await this.#storage.createBucket(bucketName, {
+            this.#logger.info(`Bucket "${bucketName}" not found, creating...`);
+            const [createdBucket] = await this.#storage.createBucket(bucketName, {
                 location: this.#options.vertex.location,
                 lifecycle: {
                     rule: [{
@@ -114,24 +149,32 @@ let AiFileService = class AiFileService {
                         }],
                 },
             });
+            this.#bucket = createdBucket;
+        }
+        else {
             this.#bucket = bucket;
         }
         return this.#bucket;
     }
     async waitForFileActive(file) {
-        if (isUndefined(this.#genAI)) {
+        if (isDefined(this.#options.vertex)) {
+            // For Vertex, uploads to GCS are instantly "active"
             return;
         }
-        let state = await this.#genAI.files.get({ name: file.name });
-        while (state.state == FileState.PROCESSING) {
-            await timeout(millisecondsPerSecond);
-            state = await this.#genAI.files.get({ name: file.name });
-        }
-        if (state.state == FileState.FAILED) {
-            throw new DetailsError(state.error?.message ?? `Failed to process file ${state.name}`, state.error?.details);
+        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);
         }

package/ai/ai-session.d.ts

@@ -1,11 +1,38 @@
-import type { OneOrMany } from '../types.js';
+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,19 +1,46 @@
 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 });

package/ai/ai.service.d.ts

@@ -1,23 +1,43 @@
 import type { Resolvable, resolveArgumentType } from '../injector/interfaces.js';
 import { type SchemaTestable } from '../schema/index.js';
-import type { Enumeration as EnumerationType, EnumerationValue } from '../types.js';
+import type { Enumeration as EnumerationType, EnumerationValue } from '../types/index.js';
 import { AiSession } from './ai-session.js';
-import { type AiModel, type FileContentPart, type FileInput, type FunctionResultContentPart, type GenerationOptions, type GenerationRequest, type GenerationResult, type SchemaFunctionDeclarations, type SchemaFunctionDeclarationsResult } from './types.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>;
 };
+/**
+ * Options for configuring the {@link AiService}.
+ */
 export declare class AiServiceOptions {
+    /** 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 'gemini-2.5-flash-lite'
+     */
     defaultModel?: AiModel;
 }
 export type AiServiceArgument = AiServiceOptions;
@@ -32,22 +52,79 @@ export type AnalyzeContentResult<T extends EnumerationType> = {
     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;
-    callFunctions<const T extends SchemaFunctionDeclarations>(options: CallFunctionsOptions<T>): Promise<SpecializedGenerationResult<SchemaFunctionDeclarationsResult<T>[]> & {
-        getFunctionResultContentParts: () => FunctionResultContentPart[];
-    }>;
+    /**
+     * 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;
@@ -57,4 +134,11 @@ export declare class AiService implements Resolvable<AiServiceArgument> {
     private convertFunctions;
     private convertGoogleContent;
 }
+/**
+ * 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>;