@tstdl/base 0.92.13 → 0.92.15

package/ai/ai-session.d.ts

@@ -1,9 +1,18 @@
-import type { TypedOmit } from '../types.js';
-import type { AiService } from './ai.service.js';
-import type { Content, GenerationRequest, GenerationResult } from './types.js';
+import type { SchemaTestable } from '../schema/index.js';
+import type { Enumeration, OneOrMany, TypedOmit } from '../types.js';
+import type { AiService, AnalyzeContentResult, ClassificationResult, SpecializedGenerationResult } from './ai.service.js';
+import type { Content, ContentPart, GenerationOptions, GenerationRequest, GenerationResult, SchemaFunctionDeclarations, SchemaFunctionDeclarationsResult } from './types.js';
 export declare class AiSession {
     #private;
     readonly contents: Content[];
     constructor(aiService: AiService);
+    addContent(content: OneOrMany<Content>): void;
+    analyzeContent<T extends Enumeration>(parts: OneOrMany<ContentPart>, types: T, options?: GenerationOptions & {
+        targetLanguage?: string;
+        maximumNumberOfTags?: number;
+    }): Promise<SpecializedGenerationResult<AnalyzeContentResult<T>>>;
+    classify<T extends Enumeration>(parts: OneOrMany<ContentPart>, types: T, options?: GenerationOptions & Pick<GenerationRequest, 'model'>): Promise<SpecializedGenerationResult<ClassificationResult<T>>>;
+    extractData<T>(parts: OneOrMany<ContentPart>, schema: SchemaTestable<T>, options?: GenerationOptions & Pick<GenerationRequest, 'model'>): Promise<SpecializedGenerationResult<T>>;
+    callFunctions<const T extends SchemaFunctionDeclarations>(functions: T, content: Content | [Content, ...Content[]], options?: Pick<GenerationRequest, 'model' | 'systemInstruction'> & GenerationOptions): Promise<SpecializedGenerationResult<SchemaFunctionDeclarationsResult<T>[]>>;
     generate(content: Content | [Content, ...Content[]], request?: TypedOmit<GenerationRequest, 'contents'>): Promise<GenerationResult>;
 }

package/ai/ai-session.js

@@ -5,13 +5,39 @@ export class AiSession {
     constructor(aiService) {
         this.#aiService = aiService;
     }
-    async generate(content, request) {
-        const newContents = toArray(content);
-        const result = await this.#aiService.generate({
-            ...request,
-            contents: [...this.contents, ...newContents]
-        });
+    addContent(content) {
+        this.contents.push(...toArray(content));
+    }
+    async analyzeContent(parts, types, options) {
+        const newContents = this.#aiService.getAnalyzeContentConents(parts);
         this.contents.push(...newContents);
+        const result = await this.#aiService.analyzeContent(parts, types, options);
+        this.contents.push(result.raw.content);
+        return result;
+    }
+    async classify(parts, types, options) {
+        const newContents = this.#aiService.getExtractDataConents(parts);
+        this.contents.push(...newContents);
+        const result = await this.#aiService.classify(parts, types, options);
+        this.contents.push(result.raw.content);
+        return result;
+    }
+    async extractData(parts, schema, options) {
+        const newContents = this.#aiService.getExtractDataConents(parts);
+        this.contents.push(...newContents);
+        const result = await this.#aiService.extractData(parts, schema, options);
+        this.contents.push(result.raw.content);
+        return result;
+    }
+    async callFunctions(functions, content, options) {
+        this.contents.push(...toArray(content));
+        const result = await this.#aiService.callFunctions(functions, this.contents, options);
+        this.contents.push(result.raw.content);
+        return result;
+    }
+    async generate(content, request) {
+        this.contents.push(...toArray(content));
+        const result = await this.#aiService.generate({ ...request, contents: this.contents });
         this.contents.push(result.content);
         return result;
     }

package/ai/ai.service.d.ts

@@ -3,39 +3,44 @@ import { Resolvable, type resolveArgumentType } from '../injector/interfaces.js'
 import { OneOrMany, SchemaTestable } from '../schema/index.js';
 import { Enumeration as EnumerationType, EnumerationValue } from '../types.js';
 import { AiSession } from './ai-session.js';
-import { AiModel, Content, FileContentPart, FileInput, GenerationOptions, GenerationRequest, GenerationResult, GenerationUsage, SchemaFunctionDeclarations, SchemaFunctionDeclarationsResult } from './types.js';
+import { AiModel, Content, ContentPart, FileContentPart, FileInput, GenerationOptions, GenerationRequest, GenerationResult, SchemaFunctionDeclarations, SchemaFunctionDeclarationsResult } from './types.js';
 export type SpecializedGenerationResult<T> = {
     result: T;
-    usage: GenerationUsage;
+    raw: GenerationResult;
 };
 export type AiServiceOptions = {
     apiKey: string;
     defaultModel?: AiModel;
 };
 export type AiServiceArgument = AiServiceOptions;
+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[];
+};
 export declare class AiService implements Resolvable<AiServiceArgument> {
     #private;
     readonly defaultModel: AiModel;
     readonly [resolveArgumentType]: AiServiceArgument;
-    newSession(): AiSession;
+    createSession(): AiSession;
     processFile(fileInput: FileInput): Promise<FileContentPart>;
     processFiles(fileInputs: FileInput[]): Promise<FileContentPart[]>;
-    classify<T extends EnumerationType>(files: OneOrMany<FileContentPart>, types: T, model?: AiModel): Promise<SpecializedGenerationResult<{
-        types: {
-            type: EnumerationValue<T>;
-            confidence: 'high' | 'medium' | 'low';
-        }[] | null;
-    }>>;
-    extractData<T>(files: OneOrMany<FileContentPart>, schema: SchemaTestable<T>, options?: GenerationOptions): Promise<SpecializedGenerationResult<T>>;
-    analyzeDocument<T extends EnumerationType>(file: FileContentPart, types: T, options?: GenerationOptions): Promise<SpecializedGenerationResult<{
-        content: string[];
-        documentTypes: {
-            type: EnumerationValue<T>;
-            confidence: 'high' | 'medium' | 'low';
-        }[];
-        tags: string[];
-    }>>;
-    callFunctions<const T extends SchemaFunctionDeclarations>(functions: T, contents: Content[], options?: Pick<GenerationRequest, 'model' | 'systemInstruction'> & GenerationOptions): Promise<SchemaFunctionDeclarationsResult<T>[]>;
+    classify<T extends EnumerationType>(parts: OneOrMany<ContentPart>, types: T, options?: GenerationOptions & Pick<GenerationRequest, 'model'>): Promise<SpecializedGenerationResult<ClassificationResult<T>>>;
+    getClassifyConents(parts: OneOrMany<ContentPart>): Content[];
+    extractData<T>(parts: OneOrMany<ContentPart>, schema: SchemaTestable<T>, options?: GenerationOptions & Pick<GenerationRequest, 'model'>): Promise<SpecializedGenerationResult<T>>;
+    getExtractDataConents(parts: OneOrMany<ContentPart>): Content[];
+    analyzeContent<T extends EnumerationType>(parts: OneOrMany<ContentPart>, types: T, options?: GenerationOptions & {
+        targetLanguage?: string;
+        maximumNumberOfTags?: number;
+    }): Promise<SpecializedGenerationResult<AnalyzeContentResult<T>>>;
+    getAnalyzeContentConents(parts: OneOrMany<ContentPart>): Content[];
+    callFunctions<const T extends SchemaFunctionDeclarations>(functions: T, contents: Content[], options?: Pick<GenerationRequest, 'model' | 'systemInstruction'> & GenerationOptions): Promise<SpecializedGenerationResult<SchemaFunctionDeclarationsResult<T>[]>>;
     generate(request: GenerationRequest): Promise<GenerationResult>;
     private convertContents;
     private convertContent;

package/ai/ai.service.js

@@ -27,7 +27,7 @@ let AiService = class AiService {
     #fileService = inject(AiFileService, this.#options);
     #genAI = new GoogleGenerativeAI(this.#options.apiKey);
     defaultModel = this.#options.defaultModel ?? 'gemini-2.0-flash-exp';
-    newSession() {
+    createSession() {
         return new AiSession(this);
     }
     async processFile(fileInput) {
@@ -36,38 +36,42 @@ let AiService = class AiService {
     async processFiles(fileInputs) {
         return this.#fileService.processFiles(fileInputs);
     }
-    async classify(files, types, model) {
+    async classify(parts, types, options) {
         const generationSchema = object({
             types: nullable(array(object({
                 type: enumeration(types, { description: 'Type of document' }),
-                confidence: enumeration(['high', 'medium', 'low'], { description: 'How sure/certain you are about the classficiation.' })
+                confidence: enumeration(['high', 'medium', 'low'], { description: 'How sure/certain you are about the classficiation' })
             }), { description: 'One or more document types that matches' }))
         });
-        const result = await this.generate({
-            model,
+        const generation = await this.generate({
+            model: options?.model,
             generationOptions: {
                 maxOutputTokens: 1048,
-                temperature: 0.5
+                temperature: 0.5,
+                ...options
             },
             generationSchema,
             systemInstruction: 'You are a highly accurate document classification AI. Your task is to analyze the content of a given document and determine its type based on a predefined list of possible document types.',
-            contents: [{
-                    role: 'user',
-                    parts: [
-                        ...toArray(files),
-                        { text: 'Classify the document. Output as JSON using the provided schema\n\nIf none of the provided document types are a suitable match, return null for types.' }
-                    ]
-                }]
+            contents: this.getClassifyConents(parts)
         });
         return {
-            usage: result.usage,
-            result: JSON.parse(assertNotNullPass(result.text, 'No text returned.'))
+            result: JSON.parse(assertNotNullPass(generation.text, 'No text returned.')),
+            raw: generation
         };
     }
-    async extractData(files, schema, options) {
-        const result = await this.generate({
+    getClassifyConents(parts) {
+        return [{
+                role: 'user',
+                parts: [
+                    ...toArray(parts),
+                    { text: 'Classify the document. Output as JSON using the provided schema\n\nIf none of the provided document types are a suitable match, return null for types.' }
+                ]
+            }];
+    }
+    async extractData(parts, schema, options) {
+        const generation = await this.generate({
+            model: options?.model,
             generationOptions: {
-                maxOutputTokens: 8192,
                 temperature: 0.5,
                 ...options
             },
@@ -76,61 +80,62 @@ let AiService = class AiService {
 
 **Instructions:**
 Carefully read and analyze the provided document. Identify relevant information that corresponds to each field in the JSON schema. Focus on accuracy and avoid making assumptions. If a field has multiple possible values, extract all relevant ones into the correct array structures ONLY IF the schema defines that field as an array; otherwise, extract only the single most relevant value.`,
-            contents: [
-                {
-                    role: 'user',
-                    parts: [
-                        ...toArray(files),
-                        { text: 'Classify the document. Output as JSON.' }
-                    ]
-                }
-            ]
+            contents: this.getExtractDataConents(parts)
         });
         return {
-            usage: result.usage,
-            result: JSON.parse(assertNotNullPass(result.text, 'No text returned.'))
+            result: JSON.parse(assertNotNullPass(generation.text, 'No text returned.')),
+            raw: generation
         };
     }
-    async analyzeDocument(file, types, options) {
+    getExtractDataConents(parts) {
+        return [{
+                role: 'user',
+                parts: [
+                    ...toArray(parts),
+                    { text: 'Extract the data as specified in the schema. Output as JSON.' }
+                ]
+            }];
+    }
+    async analyzeContent(parts, types, options) {
         const schema = object({
             content: string({ description: 'Content of the document with important details only' }),
-            documentTypes: array(object({
+            types: nullable(array(object({
                 type: enumeration(types, { description: 'Type of document' }),
                 confidence: enumeration(['high', 'medium', 'low'], { description: 'How sure/certain you are about the classficiation' })
-            }), { description: 'One or more document types that matches' }),
-            tags: array(string({ description: 'Tag which describes the content' }), { description: 'List of tags', maximum: 5 })
+            }), { description: 'One or more document types that matches' })),
+            tags: array(string({ description: 'Tag which describes the content' }), { description: 'List of tags', maximum: options?.maximumNumberOfTags ?? 5 })
         });
-        const result = await this.generate({
+        const generation = await this.generate({
             generationOptions: {
                 maxOutputTokens: 2048,
                 temperature: 0.5,
                 ...options
             },
             generationSchema: schema,
-            systemInstruction: `You are a highly skilled data extraction AI, specializing in accurately identifying and extracting information from unstructured text documents and converting it into a structured JSON format. Your primary goal is to meticulously follow the provided JSON schema and populate it with data extracted from the given document.
+            systemInstruction: `You are a highly skilled data extraction AI, specializing in accurately identifying and extracting information from unstructured content and converting it into a structured JSON format. Your primary goal is to meticulously follow the provided JSON schema and populate it with data extracted from the given document.
 
 **Instructions:**
-Carefully read and analyze the provided document.
+Carefully read and analyze the provided content.
 Identify key points and relevant information that describes the content. Focus on a general overview without providing specific details.
-Only output as many content items as it is necessary to describe relevant content. It should be around 5 to 10 items.
-Classify the document based on the provided list of types.
-Output up to 5 tags.
-Always output the content and tags in Deutsch.`,
-            contents: [
-                {
-                    role: 'user',
-                    parts: [
-                        file,
-                        { text: 'Classify the document. Output as JSON.' }
-                    ]
-                }
-            ]
+Classify the content based on the provided list of types.
+Output up to ${options?.maximumNumberOfTags ?? 5} tags.
+Always output the content and tags in ${options?.targetLanguage ?? 'the same language as the content'}.`,
+            contents: this.getAnalyzeContentConents(parts)
         });
         return {
-            usage: result.usage,
-            result: JSON.parse(assertNotNullPass(result.text, 'No text returned.'))
+            result: JSON.parse(assertNotNullPass(generation.text, 'No text returned.')),
+            raw: generation
         };
     }
+    getAnalyzeContentConents(parts) {
+        return [{
+                role: 'user',
+                parts: [
+                    ...toArray(parts),
+                    { text: 'Classify the document. Output as JSON.' }
+                ]
+            }];
+    }
     async callFunctions(functions, contents, options) {
         const generation = await this.generate({
             model: options?.model,
@@ -151,14 +156,24 @@ Always output the content and tags in Deutsch.`,
             const handlerResult = isSchemaFunctionDeclarationWithHandler(fn) ? await fn.handler(parameters) : undefined;
             result.push({ functionName: call.name, parameters: parameters, handlerResult: handlerResult });
         }
-        return result;
+        return {
+            result,
+            raw: generation
+        };
     }
     async generate(request) {
         const googleContent = this.convertContents(request.contents);
         const googleFunctionDeclarations = isDefined(request.functions) ? this.convertFunctions(request.functions) : undefined;
-        const generationConfig = isDefined(request.generationSchema)
-            ? { ...request.generationOptions, responseMimeType: 'application/json', responseSchema: convertToOpenApiSchema(request.generationSchema) }
-            : request.generationOptions;
+        const generationConfig = {
+            maxOutputTokens: request.generationOptions?.maxOutputTokens,
+            temperature: request.generationOptions?.temperature,
+            topP: request.generationOptions?.topP,
+            topK: request.generationOptions?.topK,
+            responseMimeType: isDefined(request.generationSchema) ? 'application/json' : undefined,
+            responseSchema: isDefined(request.generationSchema) ? convertToOpenApiSchema(request.generationSchema) : undefined,
+            presencePenalty: request.generationOptions?.presencePenalty,
+            frequencyPenalty: request.generationOptions?.frequencyPenalty
+        };
         const generation = await this.getModel(request.model ?? this.defaultModel).generateContent({
             generationConfig,
             systemInstruction: request.systemInstruction,

package/ai/types.d.ts

@@ -46,7 +46,7 @@ export type FunctionResultContentPart = {
 export type ContentPart = TextContentPart | FileContentPart | FunctionCallContentPart | FunctionResultContentPart;
 export type Content = {
     role: ContentRole;
-    parts: ContentPart[];
+    parts: readonly ContentPart[];
 };
 export type FunctionCallingMode = 'auto' | 'force' | 'none';
 export type AiModel = LiteralUnion<'gemini-2.0-flash-exp' | 'gemini-exp-1206' | 'gemini-2.0-flash-thinking-exp-1219', string>;
@@ -61,7 +61,7 @@ export type GenerationOptions = {
 export type GenerationRequest = {
     model?: AiModel;
     systemInstruction?: string;
-    contents: Content[];
+    contents: readonly Content[];
     functions?: SchemaFunctionDeclarations;
     functionCallingMode?: FunctionCallingMode;
     generationSchema?: SchemaTestable;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tstdl/base",
-  "version": "0.92.13",
+  "version": "0.92.15",
   "author": "Patrick Hein",
   "publishConfig": {
     "access": "public"