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

package/src/lib/toolset/toolset.ts

@@ -0,0 +1,76 @@
+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

@@ -0,0 +1,47 @@
+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

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

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

@@ -0,0 +1,6 @@
+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

@@ -0,0 +1,25 @@
+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

@@ -0,0 +1,17 @@
+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

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

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

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

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

@@ -0,0 +1,9 @@
+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);

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

@@ -0,0 +1,51 @@
+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
+}
+
+export type TWorkflowNodeResult = {
+  name?: string
+  graph: Runnable
+  ends: string[]
+  channel?: {
+    name: string
+    annotation: BaseChannel
+  }
+  navigator?: (state, config) => Promise<any>
+}
+
+/**
+ * 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
+  }): TWorkflowNodeResult
+
+  outputVariables(entity: IWorkflowNode): TXpertParameter[]
+}

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

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

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

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

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

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

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

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

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

package/tsconfig.json

@@ -0,0 +1,22 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "module": "commonjs",
+    "forceConsistentCasingInFileNames": true,
+    "strict": true,
+    "noImplicitOverride": true,
+    "noPropertyAccessFromIndexSignature": true,
+    "noImplicitReturns": true,
+    "noFallthroughCasesInSwitch": true
+  },
+  "files": [],
+  "include": [],
+  "references": [
+    {
+      "path": "./tsconfig.lib.json"
+    },
+    {
+      "path": "./tsconfig.spec.json"
+    }
+  ]
+}

package/tsconfig.lib.json

@@ -0,0 +1,10 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "outDir": "../../dist/out-tsc",
+    "declaration": true,
+    "types": ["node"]
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": ["jest.config.ts", "src/**/*.spec.ts", "src/**/*.test.ts"]
+}

package/tsconfig.spec.json

@@ -0,0 +1,9 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "outDir": "../../dist/out-tsc",
+    "module": "commonjs",
+    "types": ["jest", "node"]
+  },
+  "include": ["jest.config.ts", "src/**/*.test.ts", "src/**/*.spec.ts", "src/**/*.d.ts"]
+}

package/index.cjs.d.ts

@@ -1 +0,0 @@
-export * from "./src/index";

package/index.esm.d.ts

@@ -1 +0,0 @@
-export * from "./src/index";