@xpert-ai/plugin-sdk 0.0.3-0 → 3.6.0-beta.10

package/package.json

@@ -1,11 +1,24 @@
 {
   "name": "@xpert-ai/plugin-sdk",
-  "version": "0.0.3-0",
+  "version": "3.6.0-beta.10",
   "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/lib/core/i18n.d.ts

@@ -0,0 +1,2 @@
+import { i18n as I18nInstance } from 'i18next';
+export declare function createI18nInstance(pluginDir: string, language?: string): Promise<I18nInstance>;

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

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

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

@@ -1,5 +1,5 @@
 /**
- * 通用 UI Schema 字段定义
+ * Common UI Schema field definitions
  */
 export interface ISchemaUIBase {
     component: string;
@@ -12,7 +12,7 @@ export interface ISchemaUIBase {
     enabledWhen?: Record<string, any>;
 }
 /**
- * Secret 字段扩展
+ * Secret field extensions
  */
 export interface ISchemaSecretField extends ISchemaUIBase {
     component: 'secretInput';

package/src/lib/integration/strategy.interface.d.ts

@@ -5,4 +5,5 @@ export type TIntegrationStrategyParams = {
 export interface IntegrationStrategy<T = unknown> {
     meta: TIntegrationProvider;
     execute(integration: IIntegration<T>, payload: TIntegrationStrategyParams): Promise<any>;
+    validateConfig?(config: T): Promise<void>;
 }

package/src/lib/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/image/strategy.interface.d.ts

@@ -1,8 +1,8 @@
+import { Document } 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,10 +10,6 @@ export type TImageUnderstandingConfig = {
         fileSystem?: XpFileSystem;
     };
 };
-export type TImageUnderstandingInput = {
-    chunks: Document<ChunkMetadata>[];
-    files: TDocumentAsset[];
-};
 export type TImageUnderstandingResult = {
     chunks: Document<Partial<ChunkMetadata>>[];
     pages?: Document<Partial<ChunkMetadata>>[];
@@ -32,5 +28,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/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;
@@ -23,4 +23,14 @@ export interface IDocumentSourceStrategy<TConfig = any> {
     loadDocuments(config: TConfig, context?: {
         integration?: IIntegration;
     }): Promise<Document[]>;
+    /**
+     * Load a single document by its ID
+     *
+     * @deprecated Planning
+     * @param documentId
+     * @param context
+     */
+    loadDocument?(document: Document, context: {
+        integration?: IIntegration;
+    }): Promise<Document>;
 }

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 { Document } from '@langchain/core/documents';
 import { ChunkMetadata } from '../types';
 /**
  * Split text content into chunks for embedding and retrieval

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

@@ -1,7 +1,6 @@
-import { DocumentInterface } from '@langchain/core/documents';
-import { _TFile, IDocumentProcessorProvider, IIntegration } from '@metad/contracts';
+import { IDocumentProcessorProvider, IIntegration, IKnowledgeDocument } from '@metad/contracts';
 import { Permissions, XpFileSystem } from '../../core/index';
-import { ChunkMetadata, TDocumentAsset } from '../types';
+import { ChunkMetadata } from '../types';
 export type TDocumentTransformerConfig = {
     stage: 'test' | 'prod';
     tempDir?: string;
@@ -10,19 +9,6 @@ export type TDocumentTransformerConfig = {
         integration?: IIntegration;
     };
 };
-export type TDocumentTransformerFile = _TFile & {
-    id?: string;
-    filename: string;
-    extension: string | undefined;
-};
-export type TDocumentTransformerInput = TDocumentTransformerFile[] | string | string[];
-export type TDocumentTransformerResult = {
-    id?: string;
-    chunks: DocumentInterface<ChunkMetadata>[];
-    metadata: {
-        assets?: TDocumentAsset[];
-    };
-};
 export interface IDocumentTransformerStrategy<TConfig extends TDocumentTransformerConfig = TDocumentTransformerConfig> {
     /**
      * Metadata about this transformer
@@ -36,5 +22,5 @@ export interface IDocumentTransformerStrategy<TConfig extends TDocumentTransform
     /**
      * Transform documents (e.g., extract, OCR, normalize, enrich metadata)
      */
-    transformDocuments(files: TDocumentTransformerInput, config: TConfig): Promise<TDocumentTransformerResult[]>;
+    transformDocuments(files: Partial<IKnowledgeDocument>[], config: TConfig): Promise<Partial<IKnowledgeDocument<ChunkMetadata>>[]>;
 }

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

@@ -13,7 +13,15 @@ export interface ChunkMetadata {
     startOffset?: number;
     endOffset?: number;
     type?: 'parent' | 'child';
+    /**
+     * Default to 'text'. Indicates the original media type of the chunk.
+     * @default text
+     */
+    mediaType?: 'text' | 'image' | 'video' | 'audio';
     children?: DocumentInterface<ChunkMetadata>[];
+    /**
+     * Associated assets like images, videos, etc.
+     */
     assets?: TDocumentAsset[];
     [key: string]: any;
 }

package/src/lib/types.d.ts

@@ -2,15 +2,15 @@ import { PluginMeta } from '@metad/contracts';
 import type { DynamicModule, INestApplicationContext } from '@nestjs/common';
 import type { ZodSchema } from 'zod';
 export interface PluginLifecycle {
-    /** 在模块注册完成但应用启动前调用 */
+    /** Called after module registration but before application startup */
     onInit?(ctx: PluginContext): Promise<void> | void;
-    /** 在应用启动后调用（可开始对外服务） */
+    /** Called after application startup (can start serving externally) */
     onStart?(ctx: PluginContext): Promise<void> | void;
-    /** 优雅停机时调用 */
+    /** Called during graceful shutdown */
     onStop?(ctx: PluginContext): Promise<void> | void;
 }
 export interface PluginHealth {
-    /** 返回健康状态与可选的依赖检查详情 */
+    /** Returns health status and optional dependency check details */
     checkHealth?(ctx: PluginContext): Promise<{
         status: 'up' | 'down';
         details?: any;
@@ -20,22 +20,22 @@ export interface PluginHealth {
     };
 }
 export interface PluginConfigSpec<T extends object = any> {
-    /** 插件级配置的 zod 校验 schema（可选） */
+    /** Zod validation schema for plugin-level config (optional) */
     schema?: ZodSchema<T>;
-    /** 默认配置 */
+    /** Default configuration */
     defaults?: Partial<T>;
 }
 export interface XpertPlugin<TConfig extends object = any> extends PluginLifecycle, PluginHealth {
     meta: PluginMeta;
     config?: PluginConfigSpec<TConfig>;
-    /** 返回要挂载到主应用的 DynamicModule（可设为 global） */
+    /** Returns the DynamicModule to be mounted to the main application (can be set as global) */
     register(ctx: PluginContext<TConfig>): DynamicModule;
 }
 export interface PluginContext<TConfig extends object = any> {
     app: INestApplicationContext;
     logger: PluginLogger;
     config: TConfig;
-    /** 访问容器中其他 Provider 的辅助方法 */
+    /** Helper method to access other Providers in the container */
     resolve<TInput = any, TResult = TInput>(token: any): TResult;
 }
 export interface PluginLogger {