@xpert-ai/plugin-sdk 3.6.0 → 3.6.2

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

@@ -1,36 +0,0 @@
-import { IDocumentSourceProvider, IIntegration } from '@metad/contracts';
-import { Document } from '@langchain/core/documents';
-import { Permissions } from '../../core';
-
-export interface IDocumentSourceStrategy<TConfig = any> {
-  readonly permissions: Permissions
-  /**
-   * Metadata about this document source
-   */
-  readonly meta: IDocumentSourceProvider
-
-  /**
-   * Validate the configuration
-   */
-  validateConfig(config: TConfig): Promise<void>;
-
-  /**
-   * Test the connection to the source
-   * 
-   * @param config 
-   */
-  test(config: TConfig): Promise<any>;
-
-  /**
-   * Load documents from the source
-   */
-  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/source/strategy.registry.ts

@@ -1,17 +0,0 @@
-import { Injectable } from '@nestjs/common';
-import { DiscoveryService, Reflector } from '@nestjs/core';
-import { BaseStrategyRegistry } from '../../strategy';
-import { DOCUMENT_SOURCE_STRATEGY } from './strategy.decorator';
-import { IDocumentSourceStrategy } from './strategy.interface';
-
-@Injectable()
-export class DocumentSourceRegistry<TConfig = any>
-  extends BaseStrategyRegistry<IDocumentSourceStrategy<TConfig>> 
-{
-  constructor(
-    discoveryService: DiscoveryService,
-    reflector: Reflector
-  ) {
-    super(DOCUMENT_SOURCE_STRATEGY, discoveryService, reflector);
-  }
-}

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

@@ -1,3 +0,0 @@
-export * from './strategy.decorator'
-export * from './strategy.interface'
-export * from './strategy.registry'

package/src/lib/rag/textsplitter/strategy.decorator.ts

@@ -1,6 +0,0 @@
-import { SetMetadata } from '@nestjs/common';
-
-export const TEXT_SPLITTER_STRATEGY = 'TEXT_SPLITTER_STRATEGY';
-
-export const TextSplitterStrategy = (provider: string) =>
-  SetMetadata(TEXT_SPLITTER_STRATEGY, provider);

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

@@ -1,28 +0,0 @@
-import { IDocumentChunkerProvider, KnowledgeStructureEnum } from '@metad/contracts'
-import { DocumentInterface } from '@langchain/core/documents'
-import { ChunkMetadata } from '../types'
-
-/**
- * Split text content into chunks for embedding and retrieval
- */
-export interface ITextSplitterStrategy<TConfig = any> {
-  /**
-   * Metadata about this splitter
-   */
-  readonly meta: IDocumentChunkerProvider
-
-  readonly structure: KnowledgeStructureEnum
-
-  /**
-   * Validate the configuration
-   */
-  validateConfig(config: TConfig): Promise<void>
-
-  /**
-   * Split a text into chunks and pages (if applicable)
-   */
-  splitDocuments(
-    documents: DocumentInterface[],
-    options?: TConfig
-  ): Promise<{ chunks: DocumentInterface<ChunkMetadata>[] }>
-}

package/src/lib/rag/textsplitter/strategy.registry.ts

@@ -1,17 +0,0 @@
-import { Injectable } from '@nestjs/common';
-import { DiscoveryService, Reflector } from '@nestjs/core';
-import { BaseStrategyRegistry } from '../../strategy';
-import { TEXT_SPLITTER_STRATEGY } from './strategy.decorator';
-import { ITextSplitterStrategy } from './strategy.interface';
-
-@Injectable()
-export class TextSplitterRegistry<TConfig = any>
-  extends BaseStrategyRegistry<ITextSplitterStrategy<TConfig>> 
-{
-  constructor(
-    discoveryService: DiscoveryService,
-    reflector: Reflector
-  ) {
-    super(TEXT_SPLITTER_STRATEGY, discoveryService, reflector);
-  }
-}

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

@@ -1,3 +0,0 @@
-export * from './strategy.decorator'
-export * from './strategy.interface'
-export * from './strategy.registry'

package/src/lib/rag/transformer/strategy.decorator.ts

@@ -1,9 +0,0 @@
-import { SetMetadata } from '@nestjs/common';
-
-export const DOCUMENT_TRANSFORMER_STRATEGY = 'DOCUMENT_TRANSFORMER_STRATEGY';
-
-/**
- * Decorator to mark a provider as a Document Transformer Strategy
- */
-export const DocumentTransformerStrategy = (provider: string) =>
-  SetMetadata(DOCUMENT_TRANSFORMER_STRATEGY, provider);

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

@@ -1,34 +0,0 @@
-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
-  permissions?: {
-    fileSystem?: XpFileSystem
-    integration?: IIntegration
-  }
-}
-
-export interface IDocumentTransformerStrategy<TConfig extends TDocumentTransformerConfig = TDocumentTransformerConfig> {
-  /**
-   * Metadata about this transformer
-   */
-  readonly meta: IDocumentProcessorProvider
-
-  readonly permissions: Permissions
-
-  /**
-   * Validate the configuration
-   */
-  validateConfig(config: TConfig): Promise<void>
-
-  /**
-   * Transform documents (e.g., extract, OCR, normalize, enrich metadata)
-   */
-  transformDocuments(
-    files: Partial<IKnowledgeDocument>[],
-    config: TConfig
-  ): Promise<Partial<IKnowledgeDocument<ChunkMetadata>>[]>
-}

package/src/lib/rag/transformer/strategy.registry.ts

@@ -1,14 +0,0 @@
-import { Injectable } from '@nestjs/common'
-import { DiscoveryService, Reflector } from '@nestjs/core'
-import { BaseStrategyRegistry } from '../../strategy'
-import { DOCUMENT_TRANSFORMER_STRATEGY } from './strategy.decorator'
-import { IDocumentTransformerStrategy, TDocumentTransformerConfig } from './strategy.interface'
-
-@Injectable()
-export class DocumentTransformerRegistry<
-  TConfig extends TDocumentTransformerConfig = TDocumentTransformerConfig
-> extends BaseStrategyRegistry<IDocumentTransformerStrategy<TConfig>> {
-  constructor(discoveryService: DiscoveryService, reflector: Reflector) {
-    super(DOCUMENT_TRANSFORMER_STRATEGY, discoveryService, reflector)
-  }
-}

package/src/lib/rag/types.ts

@@ -1,76 +0,0 @@
-import { DocumentInterface } from '@langchain/core/documents'
-import { IDocChunkMetadata } from '@metad/contracts'
-import fs from 'fs'
-import http from 'http'
-import https from 'https'
-
-export { TDocumentAsset } from '@metad/contracts'
-
-export interface ChunkMetadata extends IDocChunkMetadata{
-  startOffset?: number // Start position in the original text
-  endOffset?: number // End position in the original text
-  type?: 'parent' | 'child' // Chunk type
-  
-  [key: string]: any // Allow plugin extensions
-}
-
-/**
- * Merge parent chunks with their child chunks based on metadata (parentId and chunkId)
- * 
- * @deprecated use buildChunkTreeAndFindLeaves instead
- */
-export function mergeParentChildChunks(
-  chunks: DocumentInterface<ChunkMetadata>[], // Parent chunks
-  children: DocumentInterface<ChunkMetadata>[] // Child chunks
-): DocumentInterface<ChunkMetadata>[] {
-  const chunkMap = new Map<string, DocumentInterface<ChunkMetadata>>()
-  for (const chunk of chunks) {
-    chunkMap.set(chunk.metadata.chunkId, chunk)
-  }
-  for (const child of children) {
-    if (!child.metadata.parentId) {
-      if (chunkMap.has(child.metadata.chunkId)) {
-        console.warn(`Duplicate chunkId found: ${child.metadata.chunkId}, skipping...`)
-        continue
-      }
-      chunkMap.set(child.metadata.chunkId, child)
-      continue
-    }
-    const parent = chunkMap.get(child.metadata.parentId)
-    if (parent) {
-      if (!parent.metadata.children) {
-        parent.metadata.children = []
-      }
-      parent.metadata.children.push(child)
-    }
-  }
-  return Array.from(chunkMap.values())
-}
-
-export function isRemoteFile(path: string): boolean {
-  return path.startsWith('http://') || path.startsWith('https://') || path.startsWith('ftp://')
-}
-
-export async function downloadRemoteFile(url: string, dest: string): Promise<string> {
-  return new Promise((resolve, reject) => {
-    const file = fs.createWriteStream(dest)
-    const client = url.startsWith('https') ? https : http
-    const request = client.get(url, (response) => {
-      if (response.statusCode !== 200) {
-        reject(new Error(`Failed to get '${url}' (${response.statusCode})`))
-        return
-      }
-      response.pipe(file)
-    })
-    file.on('finish', () => {
-      file.close()
-      resolve(dest)
-    })
-    request.on('error', (err) => {
-      fs.unlink(dest, () => reject(err))
-    })
-    file.on('error', (err) => {
-      fs.unlink(dest, () => reject(err))
-    })
-  })
-}

package/src/lib/strategy.ts

@@ -1,37 +0,0 @@
-import { OnModuleInit } from "@nestjs/common"
-import { DiscoveryService, Reflector } from "@nestjs/core"
-
-export class BaseStrategyRegistry<S> implements OnModuleInit {
-    protected strategies = new Map<string, S>()
-
-    constructor(
-        protected readonly strategyKey: string,
-        protected discoveryService: DiscoveryService,
-        protected reflector: Reflector
-    ) {}
-
-    onModuleInit() {
-        const providers = this.discoveryService.getProviders()
-        for (const wrapper of providers) {
-            const { instance } = wrapper
-            if (!instance) continue
-
-            const type = this.reflector.get<string>(this.strategyKey, instance.constructor)
-            if (type) {
-                this.strategies.set(type, instance as S)
-            }
-        }
-    }
-
-    get(type: string): S {
-        const strategy = this.strategies.get(type)
-        if (!strategy) {
-            throw new Error(`No strategy found for type ${type}`)
-        }
-        return strategy
-    }
-
-    list(): S[] {
-        return Array.from(this.strategies.values())
-    }
-}

package/src/lib/toolset/builtin.ts

@@ -1,111 +0,0 @@
-import { StructuredToolInterface } from '@langchain/core/tools'
-import { BaseStore } from '@langchain/langgraph'
-import {
-	I18nObject,
-	IBuiltinTool,
-	IXpertToolset,
-	ToolProviderCredentials,
-	TToolCredentials,
-	TToolsetParams,
-	XpertToolsetCategoryEnum
-} from '@metad/contracts'
-import { Logger } from '@nestjs/common'
-import { CommandBus, QueryBus } from '@nestjs/cqrs'
-import { BaseToolset } from './toolset'
-
-/**
- * The context params of creating toolset
- */
-export type TBuiltinToolsetParams = TToolsetParams & {
-	commandBus: CommandBus
-	queryBus: QueryBus
-	store?: BaseStore
-}
-
-export interface IBuiltinToolset {
-	validateCredentials(credentials: TToolCredentials): Promise<void>
-}
-
-export abstract class BuiltinToolset<T extends StructuredToolInterface = StructuredToolInterface, C = TToolCredentials>
-	extends BaseToolset<T>
-	implements IBuiltinToolset
-{
-	static provider = ''
-	protected logger = new Logger(this.constructor.name)
-
-	providerType: XpertToolsetCategoryEnum.BUILTIN
-
-	credentialsSchema?: { [key: string]: ToolProviderCredentials }
-
-	get tenantId() {
-		return this.params?.tenantId
-	}
-	get organizationId() {
-		return this.params?.organizationId
-	}
-	get commandBus() {
-		return this.params?.commandBus
-	}
-	get queryBus() {
-		return this.params?.queryBus
-	}
-
-	get xpertId() {
-		return this.params?.xpertId
-	}
-
-	constructor(
-		public providerName: string,
-		protected toolset?: IXpertToolset,
-		protected override params?: TBuiltinToolsetParams
-	) {
-		super(params)
-	}
-
-	async validateCredentials(credentials: C): Promise<void> {
-		await this._validateCredentials(credentials)
-	}
-
-	async _validateCredentials(credentials: C) {
-		throw new Error('Method not implemented.')
-	}
-
-	getId() {
-		return this.toolset?.id
-	}
-
-	getCredentials() {
-		return this.toolset?.credentials as C
-	}
-
-	getToolTitle(name: string): string | I18nObject {
-		const tool = this.toolset?.tools?.find((tool) => tool.name === name)
-		const identity = (<IBuiltinTool>tool?.schema)?.identity
-		if (identity) {
-			return identity.label
-		}
-		return null
-	}
-
-	/**
-	 * Get credentials schema
-	 *
-	 * @returns Credentials schema
-	 */
-	getCredentialsSchema(): { [key: string]: ToolProviderCredentials } {
-		return { ...this.credentialsSchema }
-	}
-
-	/**
-	 * Get toolset entity
-	 *
-	 * @returns XpertToolset
-	 */
-	getToolset() {
-		return this.toolset
-	}
-
-	getName() {
-		return this.getToolset()?.name
-	}
-}

package/src/lib/toolset/index.ts

@@ -1,5 +0,0 @@
-export * from './strategy.decorator'
-export * from './strategy.interface'
-export * from './strategy.registry'
-export * from './builtin'
-export * from './toolset'

package/src/lib/toolset/strategy.decorator.ts

@@ -1,9 +0,0 @@
-import { SetMetadata } from '@nestjs/common';
-
-export const TOOLSET_STRATEGY = 'TOOLSET_STRATEGY';
-
-/**
- * Decorator to mark a provider as a Toolset Strategy
- */
-export const ToolsetStrategy = (provider: string) =>
-  SetMetadata(TOOLSET_STRATEGY, provider);

package/src/lib/toolset/strategy.interface.ts

@@ -1,32 +0,0 @@
-import { DynamicStructuredTool } from '@langchain/core/tools'
-import { I18nObject } from '@metad/contracts'
-import { ZodSchema } from 'zod'
-import { BuiltinToolset } from './builtin'
-
-export interface IToolsetStrategy<TConfig = any> {
-  /**
-   * Metadata about this toolset
-   */
-  readonly meta: {
-    author: string // author name
-    tags: string[] // tags for categorization
-    name: string // unique key
-    label: I18nObject // i18n label
-    description?: I18nObject // optional i18n description
-    configSchema: any // JSON schema for config validation
-    icon?: {
-      svg?: string
-      png?: string // base64 encoded png image
-      color?: string
-    }
-  }
-
-  /**
-   * Validate the configuration
-   */
-  validateConfig(config: TConfig): Promise<void>
-
-  create(config: TConfig): Promise<BuiltinToolset>
-
-  createTools(): DynamicStructuredTool<ZodSchema>[]
-}

package/src/lib/toolset/strategy.registry.ts

@@ -1,17 +0,0 @@
-import { Injectable } from '@nestjs/common';
-import { DiscoveryService, Reflector } from '@nestjs/core';
-import { TOOLSET_STRATEGY } from './strategy.decorator';
-import { IToolsetStrategy } from './strategy.interface';
-import { BaseStrategyRegistry } from '../strategy';
-
-@Injectable()
-export class ToolsetRegistry<TConfig = any>
-  extends BaseStrategyRegistry<IToolsetStrategy<TConfig>> 
-{
-  constructor(
-    discoveryService: DiscoveryService,
-    reflector: Reflector
-  ) {
-    super(TOOLSET_STRATEGY, discoveryService, reflector);
-  }
-}

package/src/lib/toolset/toolset.ts

@@ -1,76 +0,0 @@
-import { BaseToolkit, StructuredTool, StructuredToolInterface } from "@langchain/core/tools"
-import { I18nObject, TStateVariable, TToolsetParams } from "@metad/contracts"
-import { z } from 'zod'
-
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-type ZodObjectAny = z.ZodObject<any, any, any, any>;
-
-/**
- * Base ability for all toolsets
- */
-export abstract class BaseToolset<T extends StructuredToolInterface = StructuredToolInterface> extends BaseToolkit {
-	abstract providerName: string
-	// For Langchain
-	tools: T[]
-	// For Langgraph
-	stateVariables: TStateVariable[]
-
-	constructor(protected params?: TToolsetParams) {
-		super()
-	}
-
-	/**
-	 * Async init tools
-	 *
-	 * @returns
-	 */
-	async initTools() {
-		return this.tools
-	}
-
-	/**
-	 * Get ID of the toolset
-	 */
-	abstract getId(): string
-	/**
-	 * Get name of the toolset
-	 */
-	abstract getName(): string
-
-	/**
-	 * Get one tool
-	 *
-	 * @param toolName
-	 * @returns
-	 */
-	getTool(toolName: string) {
-		return this.getTools()?.find((tool) => tool.name === toolName)
-	}
-
-	/**
-	 * Get state variables config
-	 *
-	 * @returns State variables
-	 */
-	async getVariables(): Promise<TStateVariable[]> {
-		return null
-	}
-
-	/**
-	 * Get title of tool
-	 */
-	abstract getToolTitle(name: string): string | I18nObject
-
-	/**
-     * Close all (connections).
-     */
-    async close(): Promise<void> {
-		//
-	}
-}
-
-export abstract class BaseTool<T extends ZodObjectAny = ZodObjectAny> extends StructuredTool<T> {
-	schema: any = z
-		.object({ input: z.string().optional() })
-		.transform((obj) => obj.input)
-}

package/src/lib/types.ts

@@ -1,47 +0,0 @@
-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 }> | { status: 'up' | 'down'; details?: any };
-}
-
-export interface PluginConfigSpec<T extends object = any> {
-  /** 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>;
-  /** 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;      // Nest runtime context (injected after startup)
-  logger: PluginLogger;              // Logger wrapper provided by SDK
-  config: TConfig;                   // Final config after validation and merging
-  /** Helper method to access other Providers in the container */
-  resolve<TInput = any, TResult = TInput>(token: any): TResult;
-}
-
-export interface PluginLogger {
-  child(meta: Record<string, any>): PluginLogger;
-  debug(msg: string, meta?: any): void;
-  log(msg: string, meta?: any): void;
-  warn(msg: string, meta?: any): void;
-  error(msg: string, meta?: any): void;
-}

package/src/lib/vectorstore/index.ts

@@ -1,3 +0,0 @@
-export * from './strategy.decorator'
-export * from './strategy.interface'
-export * from './strategy.registry'

package/src/lib/vectorstore/strategy.decorator.ts

@@ -1,6 +0,0 @@
-import { SetMetadata } from '@nestjs/common';
-
-export const VECTOR_STORE_STRATEGY = 'VECTOR_STORE_STRATEGY';
-
-export const VectorStoreStrategy = (provider: string) =>
-  SetMetadata(VECTOR_STORE_STRATEGY, provider);

package/src/lib/vectorstore/strategy.interface.ts

@@ -1,25 +0,0 @@
-import { EmbeddingsInterface } from '@langchain/core/embeddings'
-import { VectorStore } from '@langchain/core/vectorstores'
-
-/**
- * Interface for VectorStore strategy。
- * 
- * 
- */
-export interface IVectorStoreStrategy<TConfig extends {collectionName?: string}> {
-  /**
-   * Metadata about the strategy
-   */
-  readonly name: string;
-  readonly description?: string;
-
-  /**
-   * Validate configuration for VectorStore
-   */
-  validateConfig(config: TConfig): Promise<void>;
-
-  /**
-   * Create a VectorStore with given config
-   */
-  createStore(embeddings: EmbeddingsInterface, config: TConfig): Promise<VectorStore>;
-}

package/src/lib/vectorstore/strategy.registry.ts

@@ -1,17 +0,0 @@
-import { Injectable } from '@nestjs/common';
-import { DiscoveryService, Reflector } from '@nestjs/core';
-import { BaseStrategyRegistry } from '../strategy';
-import { VECTOR_STORE_STRATEGY } from './strategy.decorator';
-import { IVectorStoreStrategy } from './strategy.interface';
-
-@Injectable()
-export class VectorStoreRegistry<TConfig = any>
-  extends BaseStrategyRegistry<IVectorStoreStrategy<TConfig>> 
-{
-  constructor(
-    discoveryService: DiscoveryService,
-    reflector: Reflector
-  ) {
-    super(VECTOR_STORE_STRATEGY, discoveryService, reflector);
-  }
-}

package/src/lib/workflow/index.ts

@@ -1,2 +0,0 @@
-export * from './trigger/index'
-export * from './node/index'

package/src/lib/workflow/node/index.ts

@@ -1,3 +0,0 @@
-export * from './strategy.decorator'
-export * from './strategy.interface'
-export * from './strategy.registry'

package/src/lib/workflow/node/strategy.decorator.ts

@@ -1,9 +0,0 @@
-import { SetMetadata } from '@nestjs/common';
-
-export const WORKFLOW_NODE_STRATEGY = 'WORKFLOW_NODE_STRATEGY';
-
-/**
- * Decorator to mark a provider as a Workflow Node Strategy
- */
-export const WorkflowNodeStrategy = (provider: string) =>
-  SetMetadata(WORKFLOW_NODE_STRATEGY, provider);