@metad/contracts 3.6.2 → 3.6.7

package/src/ai/xpert-agent.model.ts

@@ -0,0 +1,264 @@
+import { IBasePerTenantAndOrganizationEntityModel } from '../base-entity.model'
+import { ICopilotModel, TCopilotModel } from './copilot-model.model'
+import { IKnowledgebase, TKBRecallParams } from './knowledgebase.model'
+import { I18nObject, TAvatar } from '../types'
+import { IXpertToolset } from './xpert-toolset.model'
+import { IXpert, TXpertParameter } from './xpert.model'
+import { TVariableAssigner } from './xpert-workflow.model'
+import { TErrorHandling } from './types'
+import { TInterruptCommand } from '../agent'
+
+export type TXpertAgent = {
+  key: string
+  name?: string
+  title?: string
+  description?: string
+  avatar?: TAvatar
+  /**
+   * System prompt
+   */
+  prompt?: string
+  /**
+   * Prompt templates (ai or human)
+   */
+  promptTemplates?: TAgentPromptTemplate[]
+  /**
+   * Input parameters for agent
+   */
+  parameters?: TXpertParameter[]
+  /**
+   * Output variables of agent
+   */
+  outputVariables?: TAgentOutputVariable[]
+
+  /**
+   * More configuration
+   */
+  options?: TXpertAgentOptions
+
+  // One to one
+  /**
+   * This is the xpert's primary agent
+   */
+  xpert?: IXpert
+  xpertId?: string
+  /**
+   * Copilot model of this agent
+   */
+  copilotModel?: ICopilotModel
+  copilotModelId?: string
+
+  // Many to one
+  /**
+   * This is one of the xpert team's agent
+   */
+  team?: IXpert
+  teamId?: string
+
+  /**
+   * My leader in xpert team
+   */
+  leader?: IXpertAgent
+  leaderKey?: string
+  /**
+   * I am the leader of followers in xpert's team
+   */
+  followers?: IXpertAgent[]
+
+  // Many to many
+  /**
+   * External xpert teams
+   */
+  collaborators?: IXpert[]
+  collaboratorNames?: string[]
+  /**
+   * I used toolsets
+   */
+  toolsets?: IXpertToolset[]
+  toolsetIds?: string[]
+  /**
+   * I used knowledgebases
+   */
+  knowledgebases?: IKnowledgebase[]
+  knowledgebaseIds?: string[]
+}
+
+/**
+ * Expert agent, ai agent for the xperts.
+ */
+export interface IXpertAgent extends IBasePerTenantAndOrganizationEntityModel, TXpertAgent {
+  
+}
+
+export type TXpertAgentOptions = {
+  /**
+   * Hide this agent node in the graph
+   */
+  hidden?: boolean
+  
+  /**
+   * Disable message history for agent conversation
+   */
+  disableMessageHistory?: boolean
+
+  /**
+   * The variable of message history to use
+   */
+  historyVariable?: string
+
+  /**
+   * Write output variables to memory (state)
+   */
+  memories?: TVariableAssigner[]
+
+  /**
+   * Whether to enable parallel tool calls, default: true
+   */
+  parallelToolCalls?: boolean
+
+  /**
+   * Retry on failure
+   */
+  retry?: {
+    enabled?: boolean
+    stopAfterAttempt?: number
+  }
+
+  /**
+   * Fallback model
+   */
+  fallback?: {
+    enabled?: boolean
+    copilotModel?: TCopilotModel
+  }
+
+  /**
+   * Error handling
+   */
+  errorHandling?: TErrorHandling
+
+  /**
+   * Recall params for kbs
+   */
+  recall?: TKBRecallParams
+
+  /**
+   * Available tools
+   */
+  availableTools?: Record<string, string[]>
+  /**
+   * Options for tools of agent
+   */
+  tools?: Record<string, {
+    timeout?: number
+  }>
+  
+  /**
+   * How to achieve structured output (`StructuredOutputMethodOptions['method']`)
+   * - *functionCalling*
+   * - *jsonMode*
+   * - *jsonSchema*
+   * 
+   */
+  structuredOutputMethod?: "functionCalling" | "jsonMode" | "jsonSchema" | string
+  /**
+   * Vision config of agent
+   */
+  vision?: {
+    enabled?: boolean
+    /**
+     * Variable name that store the list of files to be understood
+     */
+    variable?: string
+    /**
+     * Image resolution for vision tasks
+     */
+    resolution?: 'high' | 'low'
+  }
+}
+
+export type TAgentPromptTemplate = {
+  id: string;
+  role: 'ai' | 'human';
+  text: string
+}
+
+export type TAgentOutputVariable = TXpertParameter & {
+  /**
+     * value write to state's variable
+     */
+  variableSelector: string
+  /**
+   * How to write value to variable
+   */
+  operation: 'append' | 'extends' | 'overwrite' | 'clear'
+}
+
+/**
+ * @deprecated use TChatRequest
+ */
+export type TChatAgentParams = {
+  input: {
+    input?: string
+    [key: string]: unknown
+  }
+  agentKey: string
+  xpertId: string
+  executionId?: string
+  environmentId?: string
+  /**
+   */
+  command?: TInterruptCommand
+  /**
+   * Reject the sensitive tool calls
+   */
+  reject?: boolean
+}
+
+export function agentLabel(agent: Partial<IXpertAgent>) {
+  return agent.title || agent.name || agent.key
+}
+
+export function agentUniqueName(agent: IXpertAgent) {
+  return agent ? (convertToUrlPath(agent.name) || agent.key) : null
+}
+
+export function convertToUrlPath(title: string) {
+  return title?.toLowerCase() // Convert to lowercase
+    .replace(/\s+/g, '-') // Replace spaces with -
+    .replace(/[^a-z0-9-]/g, ''); // Remove non-alphanumeric characters
+}
+
+export const VariableOperations: {
+  value: TAgentOutputVariable['operation'];
+  label: I18nObject
+}[] = [
+  {
+    value: 'append',
+    label: {
+      zh_Hans: '追加',
+      en_US: 'Append'
+    }
+  },
+  {
+    value: 'extends',
+    label: {
+      zh_Hans: '扩展',
+      en_US: 'Extend'
+    }
+  },
+  {
+    value: 'overwrite',
+    label: {
+      zh_Hans: '覆盖',
+      en_US: 'Overwrite'
+    }
+  },
+  {
+    value: 'clear',
+    label: {
+      zh_Hans: '清除',
+      en_US: 'Clear'
+    }
+  }
+]

package/src/ai/xpert-project.model.ts

@@ -0,0 +1,103 @@
+import { IBasePerTenantAndOrganizationEntityModel } from '../base-entity.model'
+import { IIntegration } from '../integration.model'
+import { IStorageFile, TFile } from '../storage-file.model'
+import { TAvatar } from '../types'
+import { IUser } from '../user.model'
+import { ICopilotModel } from './copilot-model.model'
+import { IKnowledgebase } from './knowledgebase.model'
+import { IXpertToolset } from './xpert-toolset.model'
+import { IXpertWorkspace } from './xpert-workspace.model'
+import { IXpert, TXpertTeamDraft } from './xpert.model'
+
+export type TXpertProjectSettings = {
+  instruction: string
+  mode?: '' | 'plan'
+}
+export type TXpertProjectStatus = 'active' | 'deprecated' | 'archived'
+
+export type TXpertProject = {
+  name: string
+  avatar?: TAvatar
+  description?: string
+  status: TXpertProjectStatus
+  settings?: TXpertProjectSettings
+
+  // Used copilot model
+  copilotModel?: ICopilotModel
+  copilotModelId?: string
+
+  vcsId?: string
+}
+
+/**
+ * Expert Project
+ */
+export interface IXpertProject extends TXpertProject, IBasePerTenantAndOrganizationEntityModel {
+  workspaceId?: string
+  workspace?: IXpertWorkspace
+
+  // Many to one
+  ownerId: string
+  owner?: IUser
+
+  // One to many
+  xperts?: IXpert[]
+  toolsets?: IXpertToolset[]
+  knowledges?: IKnowledgebase[]
+  members?: IUser[]
+  /**
+   * @deprecated Use *file volume* instead
+   */
+  files?: IXpertProjectFile[]
+  attachments?: IStorageFile[]
+
+  vcs?: IXpertProjectVCS
+}
+
+export interface IBasePerXpertProjectEntityModel extends IBasePerTenantAndOrganizationEntityModel {
+  projectId?: string
+  project?: IXpertProject
+}
+
+export interface IXpertProjectTask extends IBasePerXpertProjectEntityModel {
+  threadId?: string
+  name: string
+  type?: string
+  status: 'pending' | 'in_progress' | 'completed' | 'failed'
+  steps: IXpertProjectTaskStep[]
+}
+
+export interface IXpertProjectTaskStep extends IBasePerXpertProjectEntityModel {
+  taskId: string
+  stepIndex: number
+  description: string
+  notes: string
+  status: 'pending' | 'running' | 'done' | 'failed'
+}
+
+export interface IXpertProjectTaskLog extends IBasePerXpertProjectEntityModel {
+  stepId: string
+  logType: 'input' | 'output' | 'error'
+  content: string
+}
+
+export interface IXpertProjectVCS extends IBasePerXpertProjectEntityModel {
+  integrationId?: string
+  integration?: IIntegration
+  auth?: {
+		token_type?: string
+		access_token?: string
+    state?: string
+	}
+  installationId?: number | string // For GitHub Apps
+  repository?: string
+}
+
+/**
+ * @deprecated Use `attachments`
+ */
+export interface IXpertProjectFile extends IBasePerXpertProjectEntityModel, Omit<TFile, 'createdAt'> {}
+
+export type TXpertProjectDSL = IXpertProject & {
+  xperts?: TXpertTeamDraft[]
+}

package/src/ai/xpert-table.model.ts

@@ -0,0 +1,100 @@
+import { letterStartSUID } from '../types'
+import { IWorkflowNode, WorkflowNodeTypeEnum } from './xpert-workflow.model'
+import { IBasePerWorkspaceEntityModel } from './xpert-workspace.model'
+
+/**
+ * 表状态：符合我们前面讨论的多状态流程
+ */
+export enum XpertTableStatus {
+  DRAFT = 'draft',
+  READY = 'ready',
+  PENDING_ACTIVATION = 'pendingActivation',
+  ACTIVE = 'active',
+  NEEDS_MIGRATION = 'needsMigration',
+  DEPRECATED = 'deprecated',
+  ERROR = 'error'
+}
+
+/**
+ * Custom Table for Xpert
+ */
+export interface IXpertTable extends IBasePerWorkspaceEntityModel, TXpertTable {}
+
+export type TXpertTable = {
+  name: string // 逻辑表名（用户侧看到的名称，如 "customer_orders"）
+  description?: string
+  database?: string
+  schema?: string
+  columns?: TXpertTableColumn[]
+  status: XpertTableStatus
+  version?: number
+  activatedAt?: Date
+  message?: string
+}
+
+export type TXpertTableColumn = {
+  name: string
+  type: 'string' | 'number' | 'boolean' | 'date' | 'datetime' | 'json'
+  label?: string
+  required?: boolean
+}
+
+
+// ===============================
+// 📦 Database Operation Nodes
+// ===============================
+
+export interface IWorkflowNodeDBOperation extends IWorkflowNode {
+  tableId: string
+}
+
+export interface IWFNDBInsert extends IWorkflowNodeDBOperation {
+  type: WorkflowNodeTypeEnum.DB_INSERT,
+  columns?: Record<string, {
+    type: 'string' | 'number' | 'boolean' | 'date' | 'datetime' | 'json';
+    value?: any
+    valueSelector?: string
+  }>
+}
+
+export function genXpertDBInsertKey() {
+  return letterStartSUID('DBInsert_')
+}
+
+export interface IWFNDBUpdate extends IWorkflowNodeDBOperation {
+  type: WorkflowNodeTypeEnum.DB_UPDATE
+  columns?: Record<string, {
+    type: 'string' | 'number' | 'boolean' | 'date' | 'datetime' | 'json';
+    value?: any
+    valueSelector?: string
+  }>
+}
+
+export function genXpertDBUpdateKey() {
+  return letterStartSUID('DBUpdate_')
+}
+
+export interface IWFNDBDelete extends IWorkflowNodeDBOperation {
+  type: WorkflowNodeTypeEnum.DB_DELETE,
+}
+
+export function genXpertDBDeleteKey() {
+  return letterStartSUID('DBDelete_')
+}
+
+export interface IWFNDBQuery extends IWorkflowNodeDBOperation {
+  type: WorkflowNodeTypeEnum.DB_QUERY,
+}
+
+export function genXpertDBQueryKey() {
+  return letterStartSUID('DBQuery_')
+}
+
+export interface IWFNDBSql extends IWorkflowNodeDBOperation {
+  type: WorkflowNodeTypeEnum.DB_SQL
+  sqlTemplate?: string
+}
+
+export function genXpertDBSqlKey() {
+  return letterStartSUID('DBSql_')
+}

package/src/ai/xpert-task.model.ts

@@ -0,0 +1,32 @@
+import { IBasePerTenantAndOrganizationEntityModel } from '../base-entity.model'
+import { ScheduleTaskStatus, TScheduleOptions } from '../schedule'
+import { IChatConversation } from './chat.model'
+import { IXpert } from './xpert.model'
+
+
+/**
+ * Tools for Xpert
+ */
+export interface IXpertTask extends IBasePerTenantAndOrganizationEntityModel, XpertTaskType {}
+
+export type XpertTaskType = {
+  name?: string
+  schedule?: string
+  options?: TScheduleOptions
+  timeZone?: string
+  prompt?: string
+  status?: ScheduleTaskStatus
+
+  xpert?: IXpert
+  xpertId?: string
+  agentKey?: string
+  // One to many
+  conversations?: IChatConversation[]
+
+  // Temporary properties
+  job?: any
+  scheduleDescription?: string
+  executionCount?: number
+  errorCount?: number
+  successCount?: number
+}

package/src/ai/xpert-template.model.ts

@@ -0,0 +1,53 @@
+import { IBasePerTenantEntityModel } from '../base-entity.model'
+import { IconDefinition, TAvatar } from '../types'
+import { TCopilotModel } from './copilot-model.model'
+import { MCPServerType, TMCPServer } from './xpert-tool-mcp.model'
+import { XpertTypeEnum } from './xpert.model'
+
+export interface IXpertTemplate extends IBasePerTenantEntityModel {
+  key: string
+  name?: string
+  visitCount: number
+  lastVisitedAt?: Date
+}
+
+export type TTemplate = {
+  id: string
+  name: string
+  title: string
+  description: string
+  category: string
+  copyright: string
+  privacyPolicy?: string
+  export_data: string
+}
+
+export type TXpertTemplate = TTemplate & {
+  avatar: TAvatar
+  // icon: IconDefinition | string
+  type: XpertTypeEnum | 'project'
+  copilotModel?: Partial<TCopilotModel>
+}
+
+export interface IXpertMCPTemplate extends TTemplate {
+  /**
+   * string is the backward compatible image file URL format
+   */
+  icon: IconDefinition | string
+  type: MCPServerType
+  author: string
+  transport: MCPServerType
+  explore: string
+  tags?: string[]
+  visitCount?: number
+  server: TMCPServer
+  options?: any
+}
+
+export type TKnowledgePipelineTemplate = TTemplate & {
+  icon: IconDefinition
+  author: string
+  explore: string
+  tags?: string[]
+  visitCount?: number
+}

package/src/ai/xpert-tool-mcp.model.ts

@@ -0,0 +1,77 @@
+export enum MCPServerType {
+  SSE = 'sse',
+  STDIO = 'stdio',
+  CODE = 'code'
+}
+
+/**
+ * Configuration for stdio transport connection
+ */
+export interface StdioConnection {
+  transport: "stdio";
+  command: string;
+  args: string[];
+  env?: Record<string, string>;
+  encoding?: string;
+  encodingErrorHandler?: "strict" | "ignore" | "replace";
+}
+
+/**
+ * Configuration for SSE transport connection
+ */
+export interface SSEConnection {
+  transport: "sse";
+  url: string;
+  headers?: Record<string, string>;
+  useNodeEventSource?: boolean;
+}
+
+export type TMCPServerReconnect = {
+  /**
+   * Whether to automatically restart the process if it exits
+   */
+  enabled?: boolean;
+  /**
+    * Maximum number of restart attempts
+    */
+  maxAttempts?: number;
+  /**
+    * Delay in milliseconds between restart attempts
+    */
+  delayMs?: number;
+}
+
+export type TMCPServer = {
+  type: MCPServerType
+  command?: string
+  args?: string[]
+  env?: Record<string, string>
+  encoding?: string
+  encodingErrorHandler?: string
+  /**
+   * Additional reconnection settings
+   */
+  reconnect?: TMCPServerReconnect
+
+  url?: string,
+  headers?: Record<string, string>
+  useNodeEventSource?: boolean
+  /**
+   * Default timeout in milliseconds for tool execution. Must be greater than 0.
+   * If not specified, tools will use their own configured timeout values.
+   */
+  defaultToolTimeout?: number
+
+  files?: {name: string; content: string}[]
+
+  toolNamePrefix?: string
+  /**
+   * Init scripts for sandbox
+   */
+  initScripts?: string
+}
+
+export type TMCPSchema = {
+  servers?: Record<string, TMCPServer>
+  mcpServers?: Record<string, TMCPServer>
+}