@xpert-ai/plugin-sdk 3.7.1 → 3.7.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xpert-ai/plugin-sdk",
-  "version": "3.7.1",
+  "version": "3.7.2",
   "license": "AGPL-3.0",
   "repository": {
     "type": "git",
@@ -23,13 +23,16 @@
     "@nestjs/common": "*",
     "@nestjs/core": "*",
     "@nestjs/cqrs": "*",
+    "ajv": "*",
     "lodash-es": "*",
     "i18next-fs-backend": "*",
     "i18next": "*",
+    "json-schema": "*",
     "jsonwebtoken": "*",
     "fs": "*",
     "path": "*",
     "passport-jwt": "*",
+    "rxjs": "*",
     "stream": "*",
     "yaml": "*",
     "zod": "*"

package/src/lib/agent/middleware/types.d.ts

@@ -1,8 +1,15 @@
 import { LanguageModelLike } from '@langchain/core/language_models/base';
 import { AIMessage, BaseMessage, SystemMessage } from '@langchain/core/messages';
-import { DynamicStructuredTool } from '@langchain/core/tools';
-import { InteropZodObject } from '@langchain/core/utils/types';
-import { Runtime } from './runtime';
+import { DynamicStructuredTool, DynamicTool, StructuredToolInterface } from '@langchain/core/tools';
+import type { ToolCall, ToolMessage } from "@langchain/core/messages/tool";
+import { InferInteropZodOutput, InteropZodObject } from '@langchain/core/utils/types';
+import { RunnableToolLike } from '@langchain/core/runnables';
+import { AgentBuiltInState, Runtime } from './runtime';
+import { Command } from '@langchain/langgraph';
+export type ServerTool = Record<string, unknown>;
+export type ClientTool = StructuredToolInterface | DynamicTool | RunnableToolLike;
+export type NormalizedSchemaInput<TSchema extends InteropZodObject | undefined | never = any> = [TSchema] extends [never] ? AgentBuiltInState : TSchema extends InteropZodObject ? InferInteropZodOutput<TSchema> & AgentBuiltInState : TSchema extends Record<string, unknown> ? TSchema & AgentBuiltInState : AgentBuiltInState;
+type NormalizeContextSchema<TContextSchema extends InteropZodObject | undefined = undefined> = TContextSchema extends InteropZodObject ? InferInteropZodOutput<TContextSchema> : never;
 /**
  * jump targets (user facing)
  */
@@ -95,7 +102,7 @@ export type AfterAgentHook<TSchema extends InteropZodObject | undefined = undefi
  * @template TState - The agent's state type, must extend Record<string, unknown>. Defaults to Record<string, unknown>.
  * @template TContext - The runtime context type for accessing metadata and control flow. Defaults to unknown.
  */
-export interface ModelRequest<TState = any, TContext = unknown> {
+export interface ModelRequest<TState extends Record<string, unknown> = Record<string, unknown>, TContext = unknown> {
     /**
      * The model to use for this step.
      */
@@ -105,6 +112,31 @@ export interface ModelRequest<TState = any, TContext = unknown> {
      */
     messages: BaseMessage[];
     systemMessage?: SystemMessage;
+    /**
+     * Tool choice configuration (model-specific format).
+     * Can be one of:
+     * - `"auto"`: means the model can pick between generating a message or calling one or more tools.
+     * - `"none"`: means the model will not call any tool and instead generates a message.
+     * - `"required"`: means the model must call one or more tools.
+     * - `{ type: "function", function: { name: string } }`: The model will use the specified function.
+     */
+    toolChoice?: "auto" | "none" | "required" | {
+        type: "function";
+        function: {
+            name: string;
+        };
+    };
+    /**
+     * The tools to make available for this step.
+     */
+    tools: (ServerTool | ClientTool)[];
+    /**
+     * The current agent state (includes both middleware state and built-in state).
+     */
+    state: TState & AgentBuiltInState;
+    /**
+     * The runtime context containing metadata, signal, writer, interrupt, etc.
+     */
     runtime: Runtime<TContext>;
 }
 /**
@@ -114,7 +146,7 @@ export interface ModelRequest<TState = any, TContext = unknown> {
  * @param request - The model request containing model, messages, systemPrompt, tools, state, and runtime
  * @returns The AI message response from the model
  */
-export type WrapModelCallHandler<TSchema extends InteropZodObject | undefined = undefined, TContext = unknown> = (request: ModelRequest<TSchema, TContext>) => PromiseOrValue<AIMessage>;
+export type WrapModelCallHandler<TSchema extends InteropZodObject | undefined = undefined, TContext = unknown> = (request: ModelRequest<NormalizedSchemaInput<TSchema>, TContext>) => PromiseOrValue<AIMessage>;
 /**
  * Wrapper function type for the wrapModelCall hook.
  * Allows middleware to intercept and modify model execution.
@@ -128,7 +160,40 @@ export type WrapModelCallHandler<TSchema extends InteropZodObject | undefined =
  * @param handler - The function that invokes the model. Call this with a ModelRequest to get the response
  * @returns The AI message response from the model (or a modified version)
  */
-export type WrapModelCallHook<TSchema extends InteropZodObject | undefined = undefined, TContext = unknown> = (request: ModelRequest<TSchema, TContext>, handler: WrapModelCallHandler<TSchema, TContext>) => PromiseOrValue<AIMessage>;
+export type WrapModelCallHook<TSchema extends InteropZodObject | undefined = undefined, TContext = unknown> = (request: ModelRequest<NormalizedSchemaInput<TSchema>, TContext>, handler: WrapModelCallHandler<TSchema, TContext>) => PromiseOrValue<AIMessage>;
+/**
+ * Represents a tool call request for the wrapToolCall hook.
+ * Contains the tool call information along with the agent's current state and runtime.
+ */
+export interface ToolCallRequest<TState extends Record<string, unknown> = Record<string, unknown>, TContext = unknown> {
+    /**
+     * The tool call to be executed
+     */
+    toolCall: ToolCall;
+    /**
+     * The BaseTool instance being invoked.
+     * Provides access to tool metadata like name, description, schema, etc.
+     */
+    tool: ClientTool | ServerTool;
+    /**
+     * The current agent state (includes both middleware state and built-in state).
+     */
+    state: TState & AgentBuiltInState;
+    /**
+     * The runtime context containing metadata, signal, writer, interrupt, etc.
+     */
+    runtime: Runtime<TContext>;
+}
+/**
+ * Handler function type for wrapping tool calls.
+ * Takes a tool call request and returns the tool result or a command.
+ */
+export type ToolCallHandler<TSchema extends Record<string, unknown> = AgentBuiltInState, TContext = unknown> = (request: ToolCallRequest<TSchema, TContext>) => PromiseOrValue<ToolMessage | Command>;
+/**
+ * Wrapper function type for the wrapToolCall hook.
+ * Allows middleware to intercept and modify tool execution.
+ */
+export type WrapToolCallHook<TSchema extends InteropZodObject | undefined = undefined, TContext = unknown> = (request: ToolCallRequest<NormalizedSchemaInput<TSchema>, TContext>, handler: ToolCallHandler<NormalizedSchemaInput<TSchema>, TContext>) => PromiseOrValue<ToolMessage | Command>;
 export interface AgentMiddleware<TSchema extends InteropZodObject | undefined = any, TContextSchema extends InteropZodObject | undefined = any, TFullContext = any> {
     /**
      * The name of the middleware.
@@ -246,6 +311,6 @@ export interface AgentMiddleware<TSchema extends InteropZodObject | undefined =
      * }
      * ```
      */
-    wrapToolCall?: (request: ModelRequest<TSchema, TFullContext>, handler: WrapModelCallHandler<TSchema, TFullContext>) => PromiseOrValue<AIMessage>;
+    wrapToolCall?: WrapToolCallHook<TSchema, NormalizeContextSchema<TContextSchema>>;
 }
 export {};

package/src/lib/ai-model/ai-model.d.ts

@@ -1,8 +1,9 @@
 import { BaseChatModel } from '@langchain/core/language_models/chat_models';
 import { AIModelEntity, AiModelTypeEnum, ICopilotModel, ParameterRule, PriceInfo, PriceType } from '@metad/contracts';
 import { Logger } from '@nestjs/common';
-import { IAIModel, TChatModelOptions } from './types/';
 import { ModelProvider } from './abstract-provider';
+import { IAIModel, TChatModelOptions } from './types/model';
+import { ModelProfile } from './types/profile';
 export declare abstract class AIModel implements IAIModel {
     protected readonly modelProvider: ModelProvider;
     modelType: AiModelTypeEnum;
@@ -30,4 +31,5 @@ export declare abstract class AIModel implements IAIModel {
     private sortModelSchemas;
     protected _commonParameterRules(model: string): ParameterRule[];
     getParameterRules(model: string, credentials: Record<string, string>): ParameterRule[];
+    getModelProfile(model: string, credentials: unknown): ModelProfile;
 }

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

@@ -1,4 +1,5 @@
 import { Logger } from '@nestjs/common';
+import { JSONSchema4 } from 'json-schema';
 export declare function loadYamlFile<T>(filePath: string, logger?: Logger, ignoreError?: boolean, defaultValue?: T): T;
 /**
  * Get the mapping from name to index from a YAML file
@@ -10,3 +11,8 @@ export declare function loadYamlFile<T>(filePath: string, logger?: Logger, ignor
 export declare function getPositionMap(folderPath: string, fileName?: string, logger?: Logger): Record<string, number>;
 export declare function getPositionList(folderPath: string, fileName?: string, logger?: Logger): string[];
 export declare function getErrorMessage(err: any): string;
+export declare class JsonSchemaValidator {
+    private ajv;
+    constructor();
+    parseAndValidate(schemaStr?: string): JSONSchema4 | undefined;
+}