@xpert-ai/plugin-sdk 3.6.0-beta.6 → 3.6.1

package/package.json

@@ -1,11 +1,24 @@
 {
   "name": "@xpert-ai/plugin-sdk",
-  "version": "3.6.0-beta.6",
+  "version": "3.6.1",
   "license": "AGPL-3.0",
   "dependencies": {},
   "main": "./index.cjs.js",
   "module": "./index.esm.js",
   "publishConfig": {
     "access": "public"
+  },
+  "peerDependencies": {
+    "@langchain/core": "*",
+    "@metad/contracts": "*",
+    "@nestjs/common": "*",
+    "@nestjs/core": "*",
+    "@nestjs/microservices": "*",
+    "lodash-es": "*",
+    "i18next-fs-backend": "*",
+    "i18next": "*",
+    "zod": "*",
+    "fs": "*",
+    "path": "*"
   }
-}
+}

package/src/index.d.ts

@@ -3,10 +3,10 @@ export * from './lib/plugin.interface';
 export * from './lib/plugin-metadata';
 export * from './lib/types';
 export * from './lib/logger';
-export * from './lib/knowledge';
 export * from './lib/integration/index';
 export * from './lib/workflow/index';
 export * from './lib/vectorstore/index';
 export * from './lib/rag/index';
 export * from './lib/toolset/index';
 export * from './lib/core/index';
+export * from './lib/ai-model/index';

package/src/lib/ai-model/abstract-provider.d.ts

@@ -0,0 +1,41 @@
+import { Embeddings } from '@langchain/core/embeddings';
+import { BaseLanguageModel } from '@langchain/core/language_models/base';
+import { BaseChatModel } from '@langchain/core/language_models/chat_models';
+import { AIModelEntity, AiModelTypeEnum, IAiProviderEntity, ICopilotModel, ProviderModel } from '@metad/contracts';
+import { Logger } from '@nestjs/common';
+import { AIModel } from './ai-model';
+import { IAIModelProviderStrategy } from './ai-model-provider.interface';
+import { TChatModelOptions, IRerank } from './types/';
+export declare abstract class ModelProvider implements IAIModelProviderStrategy {
+    readonly logger: Logger;
+    protected _name?: string;
+    protected _meta?: IAiProviderEntity;
+    get name(): string;
+    protected modelManagers: Map<AiModelTypeEnum, AIModel>;
+    private dir?;
+    constructor();
+    validateCredentials(credentials: Record<string, any>): Promise<void>;
+    abstract getAuthorization(credentials: Record<string, any>): string;
+    abstract getBaseUrl(credentials: Record<string, any>): string;
+    abstract validateProviderCredentials(credentials: Record<string, any>): Promise<void>;
+    /**
+     * Get provider lib root path.
+     *
+     * @returns Root of library
+     */
+    getProviderServerPath(): string;
+    getProviderSchema(): IAiProviderEntity;
+    getModels(modelType: AiModelTypeEnum): Promise<AIModelEntity[]>;
+    registerAIModelInstance(modelType: AiModelTypeEnum, modelInstance: AIModel): void;
+    getModelManager<T extends AIModel>(modelType: AiModelTypeEnum): T;
+    /**
+     * Get provider models.
+     * @param modelType - model type
+     * @param onlyActive - only active models
+     * @return provider models
+     */
+    getProviderModels(modelType?: AiModelTypeEnum, onlyActive?: boolean): ProviderModel[];
+    getSystemProviderModels(modelTypes: AiModelTypeEnum[]): any[];
+    getChatModel(copilotModel: ICopilotModel, options?: TChatModelOptions): BaseChatModel<import("@langchain/core/language_models/chat_models").BaseChatModelCallOptions, import("@langchain/core/messages").AIMessageChunk>;
+    getModelInstance(type: AiModelTypeEnum, copilotModel: ICopilotModel, options?: TChatModelOptions): Promise<BaseLanguageModel | BaseChatModel | Embeddings | IRerank>;
+}

package/src/lib/ai-model/ai-model-provider.decorator.d.ts

@@ -0,0 +1,2 @@
+export declare const AI_MODEL_PROVIDER = "AI_MODEL_PROVIDER";
+export declare function AIModelProviderStrategy(provider: string): (target: any) => void;

package/src/lib/ai-model/ai-model-provider.interface.d.ts

@@ -0,0 +1,42 @@
+import { AiModelTypeEnum, IAiProviderEntity, ICopilotModel, ProviderModel, AIModelEntity } from '@metad/contracts';
+import { BaseLanguageModel } from '@langchain/core/language_models/base';
+import { Embeddings } from '@langchain/core/embeddings';
+import { BaseChatModel } from '@langchain/core/language_models/chat_models';
+import { IRerank } from './types';
+import { AIModel } from './ai-model';
+export interface IAIModelProviderStrategy {
+    /**
+     * Provider metadata
+     */
+    /**
+     * Validate whether the credentials are valid
+     */
+    validateCredentials(credentials: Record<string, any>): Promise<void>;
+    /**
+     * @deprecated use validateCredentials instead
+     */
+    validateProviderCredentials(credentials: Record<string, any>): Promise<void>;
+    /**
+     * Get the provider's Base URL
+     */
+    getBaseUrl(credentials: Record<string, any>): string;
+    /**
+     * Get authorization information, such as API Key, Token, etc.
+     */
+    getAuthorization(credentials: Record<string, any>): string;
+    /**
+     * Get the list of models supported by the provider
+     */
+    getModels(modelType: AiModelTypeEnum): Promise<AIModelEntity[]>;
+    /**
+     * Return a directly usable model instance (LLM / Embedding / TTS / Rerank)
+     */
+    getModelInstance(type: AiModelTypeEnum, copilotModel: ICopilotModel, options?: Record<string, any>): Promise<BaseLanguageModel | BaseChatModel | Embeddings | IRerank>;
+    /**
+     * Return the defined provider models (metadata)
+     */
+    getProviderModels?(modelType?: AiModelTypeEnum, onlyActive?: boolean): ProviderModel[];
+    getProviderSchema(): IAiProviderEntity;
+    getProviderServerPath(): string;
+    getModelManager<T extends AIModel>(modelType: AiModelTypeEnum): T;
+}

package/src/lib/ai-model/ai-model-provider.registry.d.ts

@@ -0,0 +1,6 @@
+import { DiscoveryService, Reflector } from '@nestjs/core';
+import { BaseStrategyRegistry } from '../strategy';
+import { IAIModelProviderStrategy } from './ai-model-provider.interface';
+export declare class AIModelProviderRegistry extends BaseStrategyRegistry<IAIModelProviderStrategy> {
+    constructor(discoveryService: DiscoveryService, reflector: Reflector);
+}

package/src/lib/ai-model/ai-model.d.ts

@@ -0,0 +1,33 @@
+import { BaseChatModel } from '@langchain/core/language_models/chat_models';
+import { AIModelEntity, AiModelTypeEnum, ICopilotModel, ParameterRule, PriceInfo, PriceType } from '@metad/contracts';
+import { Logger } from '@nestjs/common';
+import { IAIModel, TChatModelOptions } from './types/';
+import { ModelProvider } from './abstract-provider';
+export declare abstract class AIModel implements IAIModel {
+    protected readonly modelProvider: ModelProvider;
+    modelType: AiModelTypeEnum;
+    protected logger: Logger;
+    protected modelSchemas: AIModelEntity[] | null;
+    private positions;
+    constructor(modelProvider: ModelProvider, modelType: AiModelTypeEnum);
+    abstract validateCredentials(model: string, credentials: Record<string, any>): Promise<void>;
+    getChatModel(copilotModel: ICopilotModel, options?: TChatModelOptions): BaseChatModel;
+    getPrice(model: string, credentials: Record<string, any>, priceType: PriceType, tokens: number): PriceInfo;
+    protected getModelPath(): string;
+    predefinedModels(): AIModelEntity[];
+    getModelSchema(model: string, credentials?: Record<string, any>): AIModelEntity | null;
+    /**
+     * Get customizable model schema.
+     * Implement this method in ai model sub class that can customize model
+     *
+     * @param model model name
+     * @param credentials model credentials
+     * @returns model schema
+     */
+    protected getCustomizableModelSchemaFromCredentials(model: string, credentials: Record<string, any>): AIModelEntity | null;
+    private processParameterRules;
+    private processLabel;
+    private sortModelSchemas;
+    protected _commonParameterRules(model: string): ParameterRule[];
+    getParameterRules(model: string, credentials: Record<string, string>): ParameterRule[];
+}

package/src/lib/ai-model/entities/defaults.d.ts

@@ -0,0 +1,3 @@
+import { ParameterRule } from "@metad/contracts";
+import { DefaultParameterName } from "./model_entities";
+export declare const PARAMETER_RULE_TEMPLATE: Record<DefaultParameterName, ParameterRule>;

package/src/lib/ai-model/entities/index.d.ts

@@ -0,0 +1,2 @@
+export * from './defaults';
+export * from './model_entities';

package/src/lib/ai-model/entities/model_entities.d.ts

@@ -0,0 +1,14 @@
+export declare function valueOf<T>(enumObj: T, value: string): T[keyof T];
+export declare enum DefaultParameterName {
+    TEMPERATURE = "temperature",
+    TOP_P = "top_p",
+    TOP_K = "top_k",
+    PRESENCE_PENALTY = "presence_penalty",
+    FREQUENCY_PENALTY = "frequency_penalty",
+    MAX_TOKENS = "max_tokens",
+    RESPONSE_FORMAT = "response_format",
+    JSON_SCHEMA = "json_schema"
+}
+export interface ModelUsage {
+    token?: number;
+}

package/src/lib/ai-model/errors.d.ts

@@ -0,0 +1,5 @@
+import { ForbiddenException, NotFoundException } from "@nestjs/common";
+export declare class AiModelNotFoundException extends NotFoundException {
+}
+export declare class CredentialsValidateFailedError extends ForbiddenException {
+}

package/src/lib/ai-model/index.d.ts

@@ -0,0 +1,8 @@
+export * from './ai-model-provider.interface';
+export * from './ai-model-provider.decorator';
+export * from './ai-model-provider.registry';
+export * from './abstract-provider';
+export * from './types';
+export * from './llm';
+export * from './errors';
+export * from './openai-compatible';

package/src/lib/ai-model/llm.d.ts

@@ -0,0 +1,49 @@
+import { AIModelEntity, ICopilot, ILLMUsage, ParameterRule, TTokenUsage } from '@metad/contracts';
+import { Logger } from '@nestjs/common';
+import { LLMResult } from '@langchain/core/outputs';
+import { AIModel } from './ai-model';
+import { TChatModelOptions } from './types/';
+export type CommonChatModelParameters = {
+    temperature: number;
+    maxRetries?: number | null;
+};
+export declare class LLMUsage implements ILLMUsage {
+    /**
+     * Model class for llm usage.
+     */
+    promptTokens: number;
+    promptUnitPrice: number;
+    promptPriceUnit: number;
+    promptPrice: number;
+    completionTokens: number;
+    completionUnitPrice: number;
+    completionPriceUnit: number;
+    completionPrice: number;
+    totalTokens: number;
+    totalPrice: number;
+    currency: string;
+    latency: number;
+    constructor(promptTokens: number, promptUnitPrice: number, promptPriceUnit: number, promptPrice: number, completionTokens: number, completionUnitPrice: number, completionPriceUnit: number, completionPrice: number, totalTokens: number, totalPrice: number, currency: string, latency: number);
+    static emptyUsage(): LLMUsage;
+    plus(other: LLMUsage): LLMUsage;
+    add(other: LLMUsage): LLMUsage;
+}
+export declare abstract class LargeLanguageModel extends AIModel {
+    #private;
+    protected startedAt: DOMHighResTimeStamp;
+    protected _commonParameterRules(model: string): ParameterRule[];
+    protected calcResponseUsage(model: string, credentials: Record<string, any>, promptTokens: number, completionTokens: number): ILLMUsage;
+    createHandleUsageCallbacks(copilot: ICopilot, model: string, credentials: any, handleLLMTokens: TChatModelOptions['handleLLMTokens']): {
+        handleLLMStart: () => void;
+        handleLLMEnd: (output: any) => void;
+    }[];
+    createHandleLLMErrorCallbacks(fields: any, logger?: Logger): {
+        handleLLMError: (err: any) => void;
+    };
+    protected getCustomizableModelSchemaFromCredentials(model: string, credentials: Record<string, any>): AIModelEntity | null;
+}
+export declare function calcTokenUsage(output: LLMResult): TTokenUsage;
+/**
+ * @deprecated use calcTokenUsage
+ */
+export declare function sumTokenUsage(output: LLMResult): number;

package/src/lib/ai-model/openai-compatible/completions.d.ts

@@ -0,0 +1,23 @@
+import { ChatOpenAICompletions, ChatOpenAIFields, ClientOptions, OpenAIClient } from '@langchain/openai';
+export type TOAIAPICompatLLMParams = ChatOpenAIFields & {
+    configuration: ClientOptions;
+};
+/**
+ * A model extended from ChatOpenAICompletions, compatible with OpenAI-style chat completions,
+ * and supports structuring content within `<think>` reasoning tags into the `reasoning_content` field.
+ *
+ * This class overrides the `_convertCompletionsDeltaToBaseMessageChunk` method to detect `<think>` and `</think>` tags in the completion stream:
+ * - When `<think>` is encountered, it enters reasoning content collection mode. Subsequent content is collected into the `reasoning_content` field and does not appear in the main `content` field.
+ * - When `</think>` is encountered, reasoning content collection ends.
+ * - In other cases, the `reasoning_content` field is directly assigned from the `reasoning_content` in the delta.
+ *
+ * In this way, the reasoning process in the model output can be separated from the main content, making it easier for subsequent structured processing and display.
+ */
+export declare class ChatOAICompatReasoningModel extends ChatOpenAICompletions {
+    private thinking;
+    /**
+     *
+     */
+    protected _convertCompletionsDeltaToBaseMessageChunk(delta: Record<string, any>, rawResponse: OpenAIClient.ChatCompletionChunk, defaultRole?: 'function' | 'user' | 'system' | 'developer' | 'assistant' | 'tool'): import("@langchain/core/messages").AIMessageChunk | import("@langchain/core/messages").HumanMessageChunk | import("@langchain/core/messages").SystemMessageChunk | import("@langchain/core/messages").FunctionMessageChunk | import("@langchain/core/messages").ToolMessageChunk | import("@langchain/core/messages").ChatMessageChunk;
+    protected _convertCompletionsMessageToBaseMessage(message: OpenAIClient.ChatCompletionMessage, rawResponse: OpenAIClient.ChatCompletion): import("@langchain/core/messages").BaseMessage;
+}

package/src/lib/ai-model/openai-compatible/index.d.ts

@@ -0,0 +1,3 @@
+export * from './completions';
+export * from './rerank';
+export * from './speech2text';

package/src/lib/ai-model/openai-compatible/rerank.d.ts

@@ -0,0 +1,20 @@
+import { Document } from '@langchain/core/documents';
+import { IRerank, RerankResult } from '../types';
+export declare class OpenAICompatibleReranker implements IRerank {
+    credentials: {
+        endpointUrl: string;
+        apiKey: string;
+        endpointModelName?: string;
+    };
+    constructor(credentials: {
+        endpointUrl: string;
+        apiKey: string;
+        endpointModelName?: string;
+    });
+    rerank(docs: Document<Record<string, any>>[], query: string, options: {
+        topN?: number;
+        scoreThreshold?: number;
+        model: string;
+        returnDocuments?: boolean;
+    }): Promise<RerankResult[]>;
+}

package/src/lib/ai-model/openai-compatible/speech2text.d.ts

@@ -0,0 +1,17 @@
+import { CallbackManagerForLLMRun } from '@langchain/core/callbacks/manager';
+import { BaseChatModel, BaseChatModelParams } from '@langchain/core/language_models/chat_models';
+import { BaseMessage } from '@langchain/core/messages';
+import { ChatResult } from '@langchain/core/outputs';
+export interface ChatSpeech2TextInput extends BaseChatModelParams {
+    /**
+     */
+    apiKey?: string;
+    model: string;
+}
+export declare class Speech2TextChatModel extends BaseChatModel {
+    private fields?;
+    _llmType(): string;
+    protected apiKey: string;
+    constructor(fields?: Partial<ChatSpeech2TextInput>);
+    _generate(messages: BaseMessage[], options: this['ParsedCallOptions'], runManager?: CallbackManagerForLLMRun): Promise<ChatResult>;
+}

package/src/lib/ai-model/types/index.d.ts

@@ -0,0 +1,11 @@
+export * from './text-embedding-model';
+export * from './rerank';
+export * from './model';
+export * from './speech2text';
+export * from './tts';
+export declare const PROVIDE_AI_MODEL_LLM = "provide_ai_model_llm";
+export declare const PROVIDE_AI_MODEL_MODERATION = "provide_ai_model_moderation";
+export declare const PROVIDE_AI_MODEL_SPEECH2TEXT = "provide_ai_model_speech2text";
+export declare const PROVIDE_AI_MODEL_TEXT_EMBEDDING = "provide_ai_model_text_embedding";
+export declare const PROVIDE_AI_MODEL_TTS = "provide_ai_model_tts";
+export declare const PROVIDE_AI_MODEL_RERANK = "provide_ai_model_rerank";

package/src/lib/ai-model/types/model.d.ts

@@ -0,0 +1,43 @@
+import { BaseChatModel } from "@langchain/core/language_models/chat_models";
+import { AIModelEntity, ICopilot, ICopilotModel, ILLMUsage, ParameterType } from "@metad/contracts";
+export type TChatModelOptions = {
+    modelProperties: Record<string, any>;
+    handleLLMTokens: (input: {
+        copilot: ICopilot;
+        model?: string;
+        usage?: ILLMUsage;
+        /**
+         * @deprecated use usage
+         */
+        tokenUsed?: number;
+    }) => void;
+    verbose: boolean;
+};
+export interface IAIModel {
+    validateCredentials(model: string, credentials: Record<string, any>): Promise<void>;
+    getChatModel(copilotModel: ICopilotModel, options?: TChatModelOptions): BaseChatModel;
+    predefinedModels(): AIModelEntity[];
+}
+export declare const CommonParameterRules: {
+    name: string;
+    label: {
+        zh_Hans: string;
+        en_US: string;
+    };
+    type: ParameterType;
+    help: {
+        zh_Hans: string;
+        en_US: string;
+    };
+    required: boolean;
+    default: number;
+    min: number;
+    max: number;
+    precision: number;
+}[];
+export declare function mergeCredentials(credentials: any, modelProperties: any): any;
+export type TModelProperties = {
+    endpoint_url: string;
+    api_key: string;
+    endpoint_model_name?: string;
+};

package/src/lib/ai-model/types/rerank.d.ts

@@ -0,0 +1,20 @@
+import { Document } from '@langchain/core/documents';
+import { ICopilotModel } from '@metad/contracts';
+import { AIModel } from '../ai-model';
+import { TChatModelOptions } from './model';
+export type RerankResult = {
+    index: number;
+    relevanceScore: number;
+    document?: Document<Record<string, any>>;
+};
+export declare abstract class RerankModel extends AIModel {
+    validateCredentials(model: string, credentials: Record<string, any>): Promise<void>;
+    abstract getReranker(copilotModel: ICopilotModel, options?: TChatModelOptions): Promise<IRerank>;
+}
+export interface IRerank {
+    rerank(docs: Document<Record<string, any>>[], query: string, options: {
+        topN?: number;
+        scoreThreshold?: number;
+        model?: string;
+    }): Promise<RerankResult[]>;
+}

package/src/lib/ai-model/types/speech2text.d.ts

@@ -0,0 +1,3 @@
+import { AIModel } from "../ai-model";
+export declare abstract class SpeechToTextModel extends AIModel {
+}

package/src/lib/ai-model/types/text-embedding-model.d.ts

@@ -0,0 +1,7 @@
+import { Embeddings } from '@langchain/core/embeddings';
+import { ICopilotModel } from '@metad/contracts';
+import { AIModel } from '../ai-model';
+import { TChatModelOptions } from './model';
+export declare abstract class TextEmbeddingModelManager extends AIModel {
+    abstract getEmbeddingInstance(copilotModel: ICopilotModel, options?: TChatModelOptions): Embeddings;
+}

package/src/lib/ai-model/types/tts.d.ts

@@ -0,0 +1,5 @@
+import { ParameterRule } from '@metad/contracts';
+import { AIModel } from '../ai-model';
+export declare abstract class TextToSpeechModel extends AIModel {
+    getParameterRules(model: string, credentials: Record<string, string>): ParameterRule[];
+}

package/src/lib/core/file-system.d.ts

@@ -18,7 +18,20 @@ export declare class XpFileSystem {
      * Check if path is within scope
      */
     private ensureInScope;
+    /**
+     * Get the absolute path of file in the file system.
+     *
+     * @param filePath Relative file path
+     * @returns Absolute file path
+     */
     fullPath(filePath: string): string;
+    /**
+     * Get web url for a given file path in the file system.
+     *
+     * @param filePath Relative file path
+     * @returns Web URL of file
+     */
+    fullUrl(filePath: string): string;
     /**
      * Read file contents
      */

package/src/lib/core/index.d.ts

@@ -2,3 +2,4 @@ export * from './file-system';
 export * from './permissions';
 export * from './schema';
 export * from './i18n';
+export * from './utils';

package/src/lib/core/utils.d.ts

@@ -0,0 +1,12 @@
+import { Logger } from '@nestjs/common';
+export declare function loadYamlFile<T>(filePath: string, logger?: Logger, ignoreError?: boolean, defaultValue?: T): T;
+/**
+ * Get the mapping from name to index from a YAML file
+ *
+ * @param folderPath
+ * @param fileName the YAML file name, default to '_position.yaml'
+ * @return a dict with name as key and index as value
+ */
+export declare function getPositionMap(folderPath: string, fileName?: string, logger?: Logger): Record<string, number>;
+export declare function getPositionList(folderPath: string, fileName?: string, logger?: Logger): string[];
+export declare function getErrorMessage(err: any): string;

package/src/lib/rag/image/strategy.interface.d.ts

@@ -1,8 +1,8 @@
+import { DocumentInterface } from '@langchain/core/documents';
 import { BaseChatModel } from '@langchain/core/language_models/chat_models';
-import { IDocumentUnderstandingProvider } from '@metad/contracts';
-import { Document } from 'langchain/document';
+import { IDocumentUnderstandingProvider, IKnowledgeDocument } from '@metad/contracts';
 import { Permissions, XpFileSystem } from '../../core/index';
-import { ChunkMetadata, TDocumentAsset } from '../types';
+import { ChunkMetadata } from '../types';
 export type TImageUnderstandingConfig = {
     stage: 'test' | 'prod';
     visionModel: BaseChatModel;
@@ -10,13 +10,8 @@ export type TImageUnderstandingConfig = {
         fileSystem?: XpFileSystem;
     };
 };
-export type TImageUnderstandingInput = {
-    chunks: Document<ChunkMetadata>[];
-    files: TDocumentAsset[];
-};
 export type TImageUnderstandingResult = {
-    chunks: Document<Partial<ChunkMetadata>>[];
-    pages?: Document<Partial<ChunkMetadata>>[];
+    chunks: DocumentInterface<Partial<ChunkMetadata>>[];
     metadata: any;
 };
 export interface IImageUnderstandingStrategy<TConfig extends TImageUnderstandingConfig = TImageUnderstandingConfig> {
@@ -32,5 +27,5 @@ export interface IImageUnderstandingStrategy<TConfig extends TImageUnderstanding
     /**
      * Understand image files (e.g., OCR, VLM, Chart Parsing)
      */
-    understandImages(params: TImageUnderstandingInput, config: TConfig): Promise<TImageUnderstandingResult>;
+    understandImages(doc: IKnowledgeDocument<ChunkMetadata>, config: TConfig): Promise<TImageUnderstandingResult>;
 }

package/src/lib/rag/index.d.ts

@@ -4,3 +4,4 @@ export * from './transformer/index';
 export * from './retriever/index';
 export * from './types';
 export * from './image/index';
+export * from './knowledge/index';

package/src/lib/{knowledge → rag/knowledge}/knowledge-strategy.interface.d.ts

@@ -1,5 +1,5 @@
 import { IIntegration } from '@metad/contracts';
-import { Document } from 'langchain/document';
+import { Document } from '@langchain/core/documents';
 export type TKnowledgeStrategyParams = {
     query: string;
     k: number;

package/src/lib/rag/knowledge/knowledge-strategy.registry.d.ts

@@ -0,0 +1,6 @@
+import { DiscoveryService, Reflector } from '@nestjs/core';
+import { BaseStrategyRegistry } from '../../strategy';
+import { KnowledgeStrategy } from './knowledge-strategy.interface';
+export declare class KnowledgeStrategyRegistry extends BaseStrategyRegistry<KnowledgeStrategy> {
+    constructor(discoveryService: DiscoveryService, reflector: Reflector);
+}

package/src/lib/rag/retriever/strategy.interface.d.ts

@@ -1,6 +1,6 @@
 import { VectorStore } from '@langchain/core/vectorstores';
 import { I18nObject } from '@metad/contracts';
-import { Document } from 'langchain/document';
+import { Document } from '@langchain/core/documents';
 export type TRetrieverConfig = {
     vectorStore: VectorStore;
 };

package/src/lib/rag/source/strategy.interface.d.ts

@@ -1,5 +1,5 @@
 import { IDocumentSourceProvider, IIntegration } from '@metad/contracts';
-import { Document } from 'langchain/document';
+import { Document } from '@langchain/core/documents';
 import { Permissions } from '../../core';
 export interface IDocumentSourceStrategy<TConfig = any> {
     readonly permissions: Permissions;

package/src/lib/rag/textsplitter/strategy.interface.d.ts

@@ -1,5 +1,5 @@
 import { IDocumentChunkerProvider, KnowledgeStructureEnum } from '@metad/contracts';
-import { Document } from 'langchain/document';
+import { DocumentInterface } from '@langchain/core/documents';
 import { ChunkMetadata } from '../types';
 /**
  * Split text content into chunks for embedding and retrieval
@@ -17,8 +17,7 @@ export interface ITextSplitterStrategy<TConfig = any> {
     /**
      * Split a text into chunks and pages (if applicable)
      */
-    splitDocuments(documents: Document[], options?: TConfig): Promise<{
-        chunks: Document<ChunkMetadata>[];
-        pages?: Document<ChunkMetadata>[];
+    splitDocuments(documents: DocumentInterface[], options?: TConfig): Promise<{
+        chunks: DocumentInterface<ChunkMetadata>[];
     }>;
 }

package/src/lib/rag/transformer/strategy.interface.d.ts

@@ -1,5 +1,6 @@
 import { IDocumentProcessorProvider, IIntegration, IKnowledgeDocument } from '@metad/contracts';
 import { Permissions, XpFileSystem } from '../../core/index';
+import { ChunkMetadata } from '../types';
 export type TDocumentTransformerConfig = {
     stage: 'test' | 'prod';
     tempDir?: string;
@@ -21,5 +22,5 @@ export interface IDocumentTransformerStrategy<TConfig extends TDocumentTransform
     /**
      * Transform documents (e.g., extract, OCR, normalize, enrich metadata)
      */
-    transformDocuments(files: Partial<IKnowledgeDocument>[], config: TConfig): Promise<Partial<IKnowledgeDocument>[]>;
+    transformDocuments(files: Partial<IKnowledgeDocument>[], config: TConfig): Promise<Partial<IKnowledgeDocument<ChunkMetadata>>[]>;
 }

package/src/lib/rag/types.d.ts

@@ -1,27 +1,16 @@
 import { DocumentInterface } from '@langchain/core/documents';
-export type TDocumentAsset = {
-    type: 'image' | 'video' | 'audio' | 'file';
-    url: string;
-    filePath: string;
-};
-export interface ChunkMetadata {
-    documentId?: string;
-    pageId?: string;
-    chunkId: string;
-    parentId?: string;
-    chunkIndex?: number;
+import { IDocChunkMetadata } from '@metad/contracts';
+export { TDocumentAsset } from '@metad/contracts';
+export interface ChunkMetadata extends IDocChunkMetadata {
     startOffset?: number;
     endOffset?: number;
     type?: 'parent' | 'child';
-    children?: DocumentInterface<ChunkMetadata>[];
-    assets?: TDocumentAsset[];
     [key: string]: any;
 }
 /**
  * Merge parent chunks with their child chunks based on metadata (parentId and chunkId)
- * @param chunks
- * @param children
- * @returns
+ *
+ * @deprecated use buildChunkTreeAndFindLeaves instead
  */
 export declare function mergeParentChildChunks(chunks: DocumentInterface<ChunkMetadata>[], // Parent chunks
 children: DocumentInterface<ChunkMetadata>[]): DocumentInterface<ChunkMetadata>[];