@xpert-ai/plugin-sdk 0.0.1 → 0.0.2

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

@@ -0,0 +1,29 @@
+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;
+    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
+ */
+export declare function mergeParentChildChunks(chunks: DocumentInterface<ChunkMetadata>[], // Parent chunks
+children: DocumentInterface<ChunkMetadata>[]): DocumentInterface<ChunkMetadata>[];
+export declare function isRemoteFile(path: string): boolean;
+export declare function downloadRemoteFile(url: string, dest: string): Promise<string>;

package/src/lib/strategy.d.ts

@@ -0,0 +1,12 @@
+import { OnModuleInit } from "@nestjs/common";
+import { DiscoveryService, Reflector } from "@nestjs/core";
+export declare class BaseStrategyRegistry<S> implements OnModuleInit {
+    protected readonly strategyKey: string;
+    protected discoveryService: DiscoveryService;
+    protected reflector: Reflector;
+    protected strategies: Map<string, S>;
+    constructor(strategyKey: string, discoveryService: DiscoveryService, reflector: Reflector);
+    onModuleInit(): void;
+    get(type: string): S;
+    list(): S[];
+}

package/src/lib/toolset/builtin.d.ts

@@ -0,0 +1,54 @@
+import { StructuredToolInterface } from '@langchain/core/tools';
+import { BaseStore } from '@langchain/langgraph';
+import { I18nObject, 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 declare abstract class BuiltinToolset<T extends StructuredToolInterface = StructuredToolInterface, C = TToolCredentials> extends BaseToolset<T> implements IBuiltinToolset {
+    providerName: string;
+    protected toolset?: IXpertToolset;
+    protected params?: TBuiltinToolsetParams;
+    static provider: string;
+    protected logger: Logger;
+    providerType: XpertToolsetCategoryEnum.BUILTIN;
+    credentialsSchema?: {
+        [key: string]: ToolProviderCredentials;
+    };
+    get tenantId(): string;
+    get organizationId(): string;
+    get commandBus(): CommandBus<import("@nestjs/cqrs").ICommand>;
+    get queryBus(): QueryBus<import("@nestjs/cqrs").IQuery>;
+    get xpertId(): string;
+    constructor(providerName: string, toolset?: IXpertToolset, params?: TBuiltinToolsetParams);
+    validateCredentials(credentials: C): Promise<void>;
+    _validateCredentials(credentials: C): Promise<void>;
+    getId(): string;
+    getCredentials(): C;
+    getToolTitle(name: string): string | I18nObject;
+    /**
+     * Get credentials schema
+     *
+     * @returns Credentials schema
+     */
+    getCredentialsSchema(): {
+        [key: string]: ToolProviderCredentials;
+    };
+    /**
+     * Get toolset entity
+     *
+     * @returns XpertToolset
+     */
+    getToolset(): IXpertToolset;
+    getName(): string;
+}

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

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

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

@@ -0,0 +1,5 @@
+export declare const TOOLSET_STRATEGY = "TOOLSET_STRATEGY";
+/**
+ * Decorator to mark a provider as a Toolset Strategy
+ */
+export declare const ToolsetStrategy: (provider: string) => import("@nestjs/common").CustomDecorator<string>;

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

@@ -0,0 +1,28 @@
+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;
+        tags: string[];
+        name: string;
+        label: I18nObject;
+        description?: I18nObject;
+        configSchema: any;
+        icon?: {
+            svg?: string;
+            png?: string;
+            color?: string;
+        };
+    };
+    /**
+     * Validate the configuration
+     */
+    validateConfig(config: TConfig): Promise<void>;
+    create(config: TConfig): Promise<BuiltinToolset>;
+    createTools(): DynamicStructuredTool<ZodSchema>[];
+}

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

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

package/src/lib/toolset/toolset.d.ts

@@ -0,0 +1,53 @@
+import { BaseToolkit, StructuredTool, StructuredToolInterface } from "@langchain/core/tools";
+import { I18nObject, TStateVariable, TToolsetParams } from "@metad/contracts";
+import { z } from 'zod';
+type ZodObjectAny = z.ZodObject<any, any, any, any>;
+/**
+ * Base ability for all toolsets
+ */
+export declare abstract class BaseToolset<T extends StructuredToolInterface = StructuredToolInterface> extends BaseToolkit {
+    protected params?: TToolsetParams;
+    abstract providerName: string;
+    tools: T[];
+    stateVariables: TStateVariable[];
+    constructor(params?: TToolsetParams);
+    /**
+     * Async init tools
+     *
+     * @returns
+     */
+    initTools(): Promise<T[]>;
+    /**
+     * 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): StructuredToolInterface<import("@langchain/core/tools").ToolSchemaBase, any, any>;
+    /**
+     * Get state variables config
+     *
+     * @returns State variables
+     */
+    getVariables(): Promise<TStateVariable[]>;
+    /**
+     * Get title of tool
+     */
+    abstract getToolTitle(name: string): string | I18nObject;
+    /**
+     * Close all (connections).
+     */
+    close(): Promise<void>;
+}
+export declare abstract class BaseTool<T extends ZodObjectAny = ZodObjectAny> extends StructuredTool<T> {
+    schema: any;
+}
+export {};

package/src/lib/types.d.ts

@@ -0,0 +1,47 @@
+import { PluginMeta } from '@metad/contracts';
+import type { DynamicModule, INestApplicationContext } from '@nestjs/common';
+import type { ZodSchema } from 'zod';
+export interface PluginLifecycle {
+    /** 在模块注册完成但应用启动前调用 */
+    onInit?(ctx: PluginContext): Promise<void> | void;
+    /** 在应用启动后调用（可开始对外服务） */
+    onStart?(ctx: PluginContext): Promise<void> | void;
+    /** 优雅停机时调用 */
+    onStop?(ctx: PluginContext): Promise<void> | void;
+}
+export interface PluginHealth {
+    /** 返回健康状态与可选的依赖检查详情 */
+    checkHealth?(ctx: PluginContext): Promise<{
+        status: 'up' | 'down';
+        details?: any;
+    }> | {
+        status: 'up' | 'down';
+        details?: any;
+    };
+}
+export interface PluginConfigSpec<T extends object = any> {
+    /** 插件级配置的 zod 校验 schema（可选） */
+    schema?: ZodSchema<T>;
+    /** 默认配置 */
+    defaults?: Partial<T>;
+}
+export interface XpertPlugin<TConfig extends object = any> extends PluginLifecycle, PluginHealth {
+    meta: PluginMeta;
+    config?: PluginConfigSpec<TConfig>;
+    /** 返回要挂载到主应用的 DynamicModule（可设为 global） */
+    register(ctx: PluginContext<TConfig>): DynamicModule;
+}
+export interface PluginContext<TConfig extends object = any> {
+    app: INestApplicationContext;
+    logger: PluginLogger;
+    config: TConfig;
+    /** 访问容器中其他 Provider 的辅助方法 */
+    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.d.ts

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

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

@@ -0,0 +1,2 @@
+export declare const VECTOR_STORE_STRATEGY = "VECTOR_STORE_STRATEGY";
+export declare const VectorStoreStrategy: (provider: string) => import("@nestjs/common").CustomDecorator<string>;

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

@@ -0,0 +1,24 @@
+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.d.ts

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

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

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

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

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

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

@@ -0,0 +1,5 @@
+export declare const WORKFLOW_NODE_STRATEGY = "WORKFLOW_NODE_STRATEGY";
+/**
+ * Decorator to mark a provider as a Workflow Node Strategy
+ */
+export declare const WorkflowNodeStrategy: (provider: string) => import("@nestjs/common").CustomDecorator<string>;

package/src/lib/workflow/node/strategy.interface.d.ts

@@ -0,0 +1,40 @@
+import { Runnable } from '@langchain/core/runnables';
+import { BaseChannel } from '@langchain/langgraph';
+import { IEnvironment, IWorkflowNode, TWorkflowNodeMeta, TXpertGraph, TXpertParameter, TXpertTeamNode } from '@metad/contracts';
+export type TWorkflowNodeParams<TConfig = any> = {
+    xpertId: string;
+    agentKey?: string;
+    node: TXpertTeamNode;
+    config: TConfig;
+};
+/**
+ * Workflow Node Strategy interface
+ */
+export interface IWorkflowNodeStrategy<TConfig = any, TResult = any> {
+    /**
+     * Metadata describing the node (type, label, description, config schema, etc.)
+     */
+    meta: TWorkflowNodeMeta;
+    /**
+     * Create the node subgraph
+     */
+    create(payload: {
+        graph: TXpertGraph;
+        node: TXpertTeamNode & {
+            type: 'workflow';
+        };
+        xpertId: string;
+        environment: IEnvironment;
+        isDraft: boolean;
+    }): {
+        name?: string;
+        graph: Runnable;
+        ends: string[];
+        channel: {
+            name: string;
+            annotation: BaseChannel;
+        };
+        navigator?: (state: any, config: any) => Promise<any>;
+    };
+    outputVariables(entity: IWorkflowNode): TXpertParameter[];
+}

package/src/lib/workflow/node/strategy.registry.d.ts

@@ -0,0 +1,9 @@
+import { DiscoveryService, Reflector } from '@nestjs/core';
+import { BaseStrategyRegistry } from '../../strategy';
+import { IWorkflowNodeStrategy } from './strategy.interface';
+/**
+ * Registry for Workflow Node Strategies
+ */
+export declare class WorkflowNodeRegistry<TConfig = any, TResult = any> extends BaseStrategyRegistry<IWorkflowNodeStrategy<TConfig, TResult>> {
+    constructor(discoveryService: DiscoveryService, reflector: Reflector);
+}

package/src/lib/workflow/trigger/index.d.ts

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

package/src/lib/workflow/trigger/strategy.decorator.d.ts

@@ -0,0 +1,2 @@
+export declare const WORKFLOW_TRIGGER_STRATEGY = "WORKFLOW_TRIGGER_STRATEGY";
+export declare const WorkflowTriggerStrategy: (provider: string) => import("@nestjs/common").CustomDecorator<string>;

package/src/lib/workflow/trigger/strategy.interface.d.ts

@@ -0,0 +1,22 @@
+import { TWorkflowTriggerMeta, TXpertTeamNode } from '@metad/contracts';
+export type TWorkflowTriggerParams<T> = {
+    xpertId: string;
+    agentKey?: string;
+    node?: TXpertTeamNode;
+    config: T;
+};
+export interface IWorkflowTriggerStrategy<T> {
+    meta: TWorkflowTriggerMeta;
+    validate(payload: TWorkflowTriggerParams<T>): Promise<any[]>;
+    /**
+     * Initialize the trigger when publish xpert workflow
+     *
+     * @param payload
+     * @param callback
+     */
+    publish(payload: TWorkflowTriggerParams<T>, callback: (payload: any) => void): Promise<any> | void;
+    /**
+     * Stop the trigger
+     */
+    stop(payload: TWorkflowTriggerParams<T>): void;
+}

package/src/lib/workflow/trigger/strategy.registry.d.ts

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

package/.eslintrc.json

@@ -1,30 +0,0 @@
-{
-  "extends": ["../../.eslintrc.json"],
-  "ignorePatterns": ["!**/*"],
-  "overrides": [
-    {
-      "files": ["*.ts", "*.tsx", "*.js", "*.jsx"],
-      "rules": {}
-    },
-    {
-      "files": ["*.ts", "*.tsx"],
-      "rules": {}
-    },
-    {
-      "files": ["*.js", "*.jsx"],
-      "rules": {}
-    },
-    {
-      "files": ["*.json"],
-      "parser": "jsonc-eslint-parser",
-      "rules": {
-        "@nx/dependency-checks": [
-          "error",
-          {
-            "ignoredFiles": ["{projectRoot}/rollup.config.{js,ts,mjs,mts}"]
-          }
-        ]
-      }
-    }
-  ]
-}

package/.swcrc

@@ -1,29 +0,0 @@
-{
-  "jsc": {
-    "target": "es2017",
-    "parser": {
-      "syntax": "typescript",
-      "decorators": true,
-      "dynamicImport": true
-    },
-    "transform": {
-      "decoratorMetadata": true,
-      "legacyDecorator": true
-    },
-    "keepClassNames": true,
-    "externalHelpers": true,
-    "loose": true
-  },
-  "module": {
-    "type": "es6"
-  },
-  "sourceMaps": true,
-  "exclude": [
-    "jest.config.ts",
-    ".*\\.spec.tsx?$",
-    ".*\\.test.tsx?$",
-    "./src/jest-setup.ts$",
-    "./**/jest-setup.ts$",
-    ".*.js$"
-  ]
-}

package/PERMISSIONS.md

@@ -1,181 +0,0 @@
-# 插件权限设计指南
-
-:::tip
-在 meta 中设计一套可以向核心系统反向请求 大模型 调用权限的（如请求一个 OpenAI Client实例）的配置，例如在 meta中声明大模型的权限请求，在 configSchema 中设计属性让用户配置具体的模型提供商和模型名称，核心系统在识别到权限请求时会根据 config 中用户配置的具体参数实例化大模型 Client 通过 config 传入到 understandImages 这个方法：
-:::
-
-👌明白了，你希望 **在插件 Strategy 的 meta 中声明依赖的大模型权限请求**，核心系统解析后根据用户配置（模型提供商 + 模型名称 + 其他参数）自动注入一个 `client` 到 `config`，这样插件不用自己创建 OpenAI / Anthropic / 其他 VLM 客户端。
-
-我帮你重新设计 `OpenAIGPT4VStrategy` 的 meta 和 configSchema，使它能 **反向请求核心系统提供的 Client**。
-
----
-
-## 新版 Strategy
-
-```ts
-import { Injectable } from '@nestjs/common';
-import { Document } from 'langchain/document';
-import {
-  ImageUnderstandingStrategy,
-  IImageUnderstandingStrategy,
-  TImageUnderstandingFile,
-  TImageUnderstandingResult
-} from './strategy.interface';
-
-@Injectable()
-@ImageUnderstandingStrategy('openai-gpt4v')
-export class OpenAIGPT4VStrategy implements IImageUnderstandingStrategy<any> {
-  readonly meta = {
-    name: 'openai-gpt4v',
-    label: { en: 'OpenAI GPT-4 Vision', zh: 'OpenAI GPT-4 图像理解' },
-
-    /**
-     * 权限声明：告诉核心系统，这个插件需要一个 "llm" 权限，
-     * 提供方是 openai，能力是 vision。
-     * 核心系统识别后会根据 config.provider + config.model 实例化对应的 Client，
-     * 并注入到 config.client
-     */
-    permissions: [
-      {
-        type: 'llm',
-        provider: 'openai',
-        capability: 'vision',
-      },
-    ],
-
-    /**
-     * 配置 schema，用户需要填写 provider 和 model，
-     * 核心系统会根据 provider + model + 用户账号 API Key，
-     * 实例化好 Client 注入。
-     */
-    configSchema: {
-      type: 'object',
-      properties: {
-        provider: { 
-          type: 'string', 
-          enum: ['openai'], 
-          description: '模型提供商' 
-        },
-        model: { 
-          type: 'string', 
-          default: 'gpt-4-vision-preview', 
-          description: '大模型名称' 
-        },
-        prompt: { 
-          type: 'string', 
-          default: 'Describe this image in detail.', 
-          description: '提示词（可以自定义理解任务）' 
-        }
-      },
-      required: ['provider', 'model']
-    },
-
-    icon: {
-      svg: '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 20 20"><circle cx="10" cy="10" r="8" stroke="black" fill="none"/><text x="6" y="14">VLM</text></svg>',
-      color: '#10a37f'
-    }
-  };
-
-  async validateConfig(config: any): Promise<void> {
-    if (!config.client) {
-      throw new Error('Missing injected LLM client in config. Core system must inject client.');
-    }
-  }
-
-  async understandImages(
-    files: TImageUnderstandingFile[],
-    config: any
-  ): Promise<TImageUnderstandingResult[]> {
-    const client = config.client; // ✅ 已由核心系统注入
-    const results: TImageUnderstandingResult[] = [];
-
-    for (const file of files) {
-      const description = await this.runGPT4V(client, file.path, config);
-
-      const doc = new Document({
-        pageContent: description,
-        metadata: {
-          chunkId: `img-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
-          parentChunkId: file.parentChunkId,
-          imagePath: file.path,
-          source: file.filename,
-          type: 'vlm',
-          engine: config.model
-        }
-      });
-
-      results.push({
-        docs: [doc],
-        metadata: { engine: config.model, file: file.filename }
-      });
-    }
-
-    return results;
-  }
-
-  private async runGPT4V(client: any, imagePath: string, config: any): Promise<string> {
-    // client 已经是 openai client，由核心系统实例化
-    const response = await client.chat.completions.create({
-      model: config.model,
-      messages: [
-        {
-          role: 'user',
-          content: [
-            { type: 'text', text: config.prompt || 'Describe this image in detail.' },
-            { type: 'image_url', image_url: { url: imagePath } }
-          ]
-        }
-      ],
-      max_tokens: 500
-    });
-
-    return response.choices[0]?.message?.content || '';
-  }
-}
-```
-
----
-
-## 🔑 核心系统如何处理
-
-* 解析插件的 `meta.permissions`，发现需要：
-
-  ```json
-  { "type": "llm", "provider": "openai", "capability": "vision" }
-  ```
-* 根据用户 `config.provider = "openai"`, `config.model = "gpt-4-vision-preview"`
-  实例化 `OpenAI({ apiKey: userApiKey })`
-* 将 client 注入到 `config.client`
-* 调用 `strategy.understandImages(files, config)`
-
----
-
-## 📌 使用示例
-
-```ts
-const strategy = this.imageUnderstandingRegistry.get('openai-gpt4v');
-const result = await strategy.understandImages(
-  [
-    { 
-      path: 'https://example.com/chart.png', 
-      filename: 'chart.png', 
-      extname: 'png', 
-      parentChunkId: 'uuid-123' 
-    }
-  ],
-  { 
-    provider: 'openai',
-    model: 'gpt-4-vision-preview',
-    prompt: '请用中文详细描述这张图片。',
-    client: openaiClient // ✅ 核心系统注入
-  }
-);
-
-console.log(result[0].docs[0].pageContent);
-```
-
----
-
-这样插件本身不依赖任何 `openai` 包装逻辑，**只声明权限 + 要求 provider/model**，核心系统就能注入合适的 client。
-
-要不要我帮你写一个 **抽象的权限声明接口 (例如 ILLMPermissionRequest)**，这样 OCR/VLM/Embedding 插件都可以统一声明依赖？

package/README.md

@@ -1,19 +0,0 @@
-# plugin-sdk
-
-This library was generated with [Nx](https://nx.dev).
-
-## Building
-
-Run `nx build plugin-sdk` to build the library.
-
-## Running unit tests
-
-Run `nx test plugin-sdk` to execute the unit tests via [Jest](https://jestjs.io).
-
-## Schema config
-
-[Schema UI 扩展规范](./SCHEMA_SPECIFICATION.md)
-
-## Permissions
-
-[插件权限设计指南](./PERMISSIONS.md)