@xpert-ai/plugin-sdk 0.0.1 → 0.0.3-0

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/jest.config.ts

@@ -1,28 +0,0 @@
-/* eslint-disable */
-import { readFileSync } from 'fs'
-
-// Reading the SWC compilation config and remove the "exclude"
-// for the test files to be compiled by SWC
-const { exclude: _, ...swcJestConfig } = JSON.parse(readFileSync(`${__dirname}/.swcrc`, 'utf-8'))
-
-// disable .swcrc look-up by SWC core because we're passing in swcJestConfig ourselves.
-// If we do not disable this, SWC Core will read .swcrc and won't transform our test files due to "exclude"
-if (swcJestConfig.swcrc === undefined) {
-  swcJestConfig.swcrc = false
-}
-
-// Uncomment if using global setup/teardown files being transformed via swc
-// https://nx.dev/packages/jest/documents/overview#global-setup/teardown-with-nx-libraries
-// jest needs EsModule Interop to find the default exported setup/teardown functions
-// swcJestConfig.module.noInterop = false;
-
-export default {
-  displayName: 'plugin-sdk',
-  preset: '../../jest.preset.js',
-  transform: {
-    '^.+\\.[tj]s$': ['@swc/jest', swcJestConfig]
-  },
-  moduleFileExtensions: ['ts', 'js', 'html'],
-  testEnvironment: 'node',
-  coverageDirectory: '../../coverage/packages/plugin-sdk'
-}

package/project.json

@@ -1,29 +0,0 @@
-{
-  "name": "plugin-sdk",
-  "$schema": "../../node_modules/nx/schemas/project-schema.json",
-  "sourceRoot": "packages/plugin-sdk/src",
-  "projectType": "library",
-  "tags": [],
-  "targets": {
-    "build": {
-      "executor": "@nx/rollup:rollup",
-      "outputs": ["{options.outputPath}"],
-      "options": {
-        "outputPath": "dist/packages/plugin-sdk",
-        "main": "packages/plugin-sdk/src/index.ts",
-        "tsConfig": "packages/plugin-sdk/tsconfig.lib.json",
-        "assets": [],
-        "project": "packages/plugin-sdk/package.json",
-        "compiler": "swc",
-        "format": ["cjs", "esm"]
-      }
-    },
-    "test": {
-      "executor": "@nx/jest:jest",
-      "outputs": ["{workspaceRoot}/coverage/{projectRoot}"],
-      "options": {
-        "jestConfig": "packages/plugin-sdk/jest.config.ts"
-      }
-    }
-  }
-}

package/src/index.ts

@@ -1,12 +0,0 @@
-export * from './lib/plugin'
-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'

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

@@ -1,96 +0,0 @@
-import fsPromises from 'fs/promises'
-import path from 'path'
-import { FileSystemPermission } from './permissions'
-
-
-/**
- * Restricted FileSystem based on granted permissions
- */
-export class XpFileSystem {
-  private allowedOps: Set<'read' | 'write' | 'delete' | 'list'>
-  private scope: string[] | undefined
-
-  constructor(permission: FileSystemPermission, private basePath: string, private baseUrl: string) {
-    this.allowedOps = new Set(permission.operations)
-    this.scope = permission.scope
-  }
-
-  /**
-   * Check if operation is allowed
-   */
-  private ensureAllowed(op: 'read' | 'write' | 'delete' | 'list') {
-    if (!this.allowedOps.has(op)) {
-      throw new Error(`Permission denied: ${op} operation not allowed`)
-    }
-  }
-
-  /**
-   * Check if path is within scope
-   */
-  private ensureInScope(targetPath: string) {
-    if (!this.scope || this.scope.length === 0) return
-    const resolved = path.resolve(targetPath)
-    for (const s of this.scope) {
-      const absScope = path.resolve(s)
-      if (resolved.startsWith(absScope)) return
-    }
-    throw new Error(`Permission denied: path "${targetPath}" is out of scope`)
-  }
-
-  fullPath(filePath: string): string {
-    return path.join(this.basePath, filePath)
-  }
-
-  /**
-   * Read file contents
-   */
-  async readFile(filePath: string, encoding: BufferEncoding = 'utf-8') {
-    this.ensureAllowed('read')
-    const fullPath = this.fullPath(filePath)
-    this.ensureInScope(fullPath)
-    return await fsPromises.readFile(fullPath)
-  }
-
-  /**
-   * Write file contents
-   */
-  async writeFile(filePath: string, content: string | Buffer): Promise<string> {
-    this.ensureAllowed('write')
-    const fullPath = this.fullPath(filePath)
-    this.ensureInScope(fullPath)
-    await fsPromises.mkdir(path.dirname(fullPath), { recursive: true })
-    await fsPromises.writeFile(fullPath, content)
-    const url = new URL(filePath, this.baseUrl)
-    return url.href
-  }
-
-  /**
-   * Delete a file
-   */
-  async deleteFile(filePath: string): Promise<void> {
-    this.ensureAllowed('delete')
-    this.ensureInScope(filePath)
-    await fsPromises.unlink(filePath)
-  }
-
-  /**
-   * List directory contents
-   */
-  async listDir(dirPath: string): Promise<string[]> {
-    this.ensureAllowed('list')
-    this.ensureInScope(dirPath)
-    return fsPromises.readdir(dirPath)
-  }
-
-  /**
-   * Utility: check if a file or directory exists
-   */
-  async exists(targetPath: string): Promise<boolean> {
-    try {
-      await fsPromises.access(targetPath)
-      return true
-    } catch {
-      return false
-    }
-  }
-}

package/src/lib/core/index.ts

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