@xpert-ai/contracts 3.9.0-beta.1

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

@@ -0,0 +1,105 @@
+import { StoredMessage } from '@langchain/core/messages';
+import { IBasePerTenantAndOrganizationEntityModel } from '../base-entity.model';
+import { IXpert, TXpertTeamNodeType } from './xpert.model';
+import { IXpertAgent } from './xpert-agent.model';
+import { TSensitiveOperation } from './chat.model';
+import { WorkflowNodeTypeEnum } from './xpert-workflow.model';
+export type TXpertExecution = {
+    category?: TXpertTeamNodeType;
+    type?: WorkflowNodeTypeEnum | string;
+    title?: string;
+    inputs?: any;
+    outputs?: any;
+    status?: XpertAgentExecutionStatusEnum;
+    error?: string;
+    elapsedTime?: number;
+    threadId?: string;
+    checkpointNs?: string;
+    checkpointId?: string;
+    channelName?: string;
+    parent_thread_id?: string;
+    /**
+     * Include workflow node key
+     */
+    agentKey?: string;
+    predecessor?: string;
+    xpert?: IXpert;
+    xpertId?: string;
+    parentId?: string;
+};
+export type TXpertAgentExecutionCheckpoint = {
+    threadId: string;
+    checkpointNs: string;
+    checkpointId: string;
+    parentCheckpointId?: string | null;
+    createdAt?: string | null;
+    metadata?: Record<string, unknown> | null;
+    isCurrent?: boolean;
+};
+/**
+ * Corresponds to the run in the [Agent Protocol](https://github.com/langchain-ai/agent-protocol).
+ */
+export type TXpertAgentExecution = TXpertExecution & {
+    /**
+     * Total token usage of chat model
+     */
+    tokens?: number;
+    /**
+     * Token usage of embedding
+     */
+    embedTokens?: number;
+    metadata?: TAgentExecutionMetadata;
+    /**
+     * Latency of response from provider (s)
+     */
+    responseLatency?: number;
+    totalPrice?: number;
+    currency?: string;
+    inputTokens?: number;
+    inputUnitPrice?: number;
+    inputPriceUnit?: number;
+    outputTokens?: number;
+    outputUnitPrice?: number;
+    outputPriceUnit?: number;
+    /**
+     * Latest operation when interrupted
+     */
+    operation?: TSensitiveOperation;
+    messages?: StoredMessage[];
+    agent?: IXpertAgent;
+    totalTokens?: number;
+    /**
+     * Summary of conversation
+     */
+    summary?: string;
+};
+/**
+ * Execution of agent or workflow nodes.
+ *
+ * Corresponds to the run in the [Agent Protocol](https://github.com/langchain-ai/agent-protocol).
+ */
+export interface IXpertAgentExecution extends IBasePerTenantAndOrganizationEntityModel, TXpertAgentExecution {
+    subExecutions?: IXpertAgentExecution[];
+    runningExecution?: IXpertAgentExecution;
+}
+/**
+ * Corresponds to the status of Run in [Agent Protocol](https://github.com/langchain-ai/agent-protocol).
+ */
+export declare enum XpertAgentExecutionStatusEnum {
+    RUNNING = "running",
+    SUCCESS = "success",
+    ERROR = "error",
+    PENDING = "pending",
+    TIMEOUT = "timeout",
+    INTERRUPTED = "interrupted"
+}
+export type TAgentExecutionMetadata = {
+    /**
+     * AI model provider
+     */
+    provider: string;
+    /**
+     * AI Model
+     */
+    model: string;
+};

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

@@ -0,0 +1,194 @@
+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';
+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;
+    /**
+     * This is the xpert's primary agent
+     */
+    xpert?: IXpert;
+    xpertId?: string;
+    /**
+     * Copilot model of this agent
+     */
+    copilotModel?: ICopilotModel;
+    copilotModelId?: string;
+    /**
+     * 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[];
+    /**
+     * 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;
+    /**
+     * @deprecated use attachment
+     */
+    vision?: TXpertAgentVision;
+    /**
+     * Attachment config of agent
+     */
+    attachment?: TXpertAgentAttachment;
+    /**
+     * Config of middlewares for agent
+     */
+    middlewares?: {
+        order: string[];
+    };
+};
+export type TXpertAgentVision = {
+    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 TXpertAgentAttachment = TXpertAgentVision & {
+    /**
+     * Max number of files to be processed
+     */
+    maxNum?: number;
+};
+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';
+};
+export declare function agentLabel(agent: Partial<IXpertAgent>): string;
+export declare function agentUniqueName(agent: IXpertAgent): string;
+export declare function convertToUrlPath(title: string): string;
+export declare const VariableOperations: {
+    value: TAgentOutputVariable['operation'];
+    label: I18nObject;
+}[];

package/src/ai/xpert-chat.model.d.ts

@@ -0,0 +1,66 @@
+import type { TChatRequestHuman, TInterruptCommand } from '@xpert-ai/chatkit-types';
+import { STATE_VARIABLE_HUMAN } from '@xpert-ai/chatkit-types';
+export type TXpertChatState = {
+    [STATE_VARIABLE_HUMAN]?: TChatRequestHuman;
+} & Record<string, any>;
+export type TXpertChatResumeDecision = {
+    type: 'confirm' | 'reject';
+    payload?: unknown;
+};
+export type TXpertChatInterruptPatch = Pick<TInterruptCommand, 'agentKey' | 'toolCalls' | 'update'>;
+export type TXpertChatTarget = {
+    aiMessageId?: string;
+    executionId?: string;
+};
+export type TXpertChatSource = {
+    aiMessageId?: string;
+    executionId?: string;
+};
+export type TXpertChatSendRequest = {
+    action: 'send';
+    conversationId?: string;
+    projectId?: string;
+    environmentId?: string;
+    sandboxEnvironmentId?: string;
+    message: {
+        clientMessageId?: string;
+        input: TChatRequestHuman;
+    };
+    state?: TXpertChatState;
+};
+export type TXpertChatResumeRequest = {
+    action: 'resume';
+    conversationId: string;
+    target: TXpertChatTarget;
+    decision: TXpertChatResumeDecision;
+    patch?: TXpertChatInterruptPatch;
+    state?: TXpertChatState;
+};
+export type TXpertChatRetryRequest = {
+    action: 'retry';
+    conversationId: string;
+    source: TXpertChatSource;
+    environmentId?: string;
+    checkpointId?: string;
+};
+export type TChatRequest = TXpertChatSendRequest | TXpertChatResumeRequest | TXpertChatRetryRequest;
+export type TXpertAgentChatRunRequest = {
+    action: 'run';
+    state: TXpertChatState;
+    agentKey: string;
+    xpertId: string;
+    environmentId?: string;
+};
+export type TXpertAgentChatResumeRequest = {
+    action: 'resume';
+    agentKey: string;
+    xpertId: string;
+    target: {
+        executionId: string;
+    };
+    decision: TXpertChatResumeDecision;
+    patch?: TXpertChatInterruptPatch;
+    environmentId?: string;
+    state?: TXpertChatState;
+};
+export type TXpertAgentChatRequest = TXpertAgentChatRunRequest | TXpertAgentChatResumeRequest;

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

@@ -0,0 +1,89 @@
+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;
+    copilotModel?: ICopilotModel;
+    copilotModelId?: string;
+    vcsId?: string;
+};
+/**
+ * Expert Project
+ */
+export interface IXpertProject extends TXpertProject, IBasePerTenantAndOrganizationEntityModel {
+    workspaceId?: string;
+    workspace?: IXpertWorkspace;
+    ownerId: string;
+    owner?: IUser;
+    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;
+}
+/**
+ * @deprecated use CodeXpert instead
+ */
+export interface IXpertProjectVCS extends IBasePerXpertProjectEntityModel {
+    integrationId?: string;
+    integration?: IIntegration;
+    auth?: {
+        token_type?: string;
+        access_token?: string;
+        state?: string;
+    };
+    installationId?: number | string;
+    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.d.ts

@@ -0,0 +1,84 @@
+import { IWorkflowNode, WorkflowNodeTypeEnum } from './xpert-workflow.model';
+import { IBasePerWorkspaceEntityModel } from './xpert-workspace.model';
+/**
+ * Table status
+ */
+export declare 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;
+    description?: string;
+    database?: string;
+    schema?: string;
+    columns?: TXpertTableColumn[];
+    status: XpertTableStatus;
+    version?: number;
+    activatedAt?: Date;
+    message?: string;
+};
+/**
+ * Union type for all supported database types
+ * Used when database type is not yet determined or needs to support multiple databases
+ */
+export type DatabaseDataType = string;
+export type TXpertTableColumn = {
+    name: string;
+    type: DatabaseDataType;
+    label?: string;
+    required?: boolean;
+    isPrimaryKey?: boolean;
+    isUnique?: boolean;
+    autoIncrement?: boolean;
+    defaultValue?: string;
+    length?: number;
+    precision?: number;
+    scale?: number;
+    enumValues?: string[];
+    setValues?: string[];
+};
+export interface IWorkflowNodeDBOperation extends IWorkflowNode {
+    tableId: string;
+}
+export interface IWFNDBInsert extends IWorkflowNodeDBOperation {
+    type: WorkflowNodeTypeEnum.DB_INSERT;
+    columns?: Record<string, {
+        type: DatabaseDataType;
+        value?: any;
+        valueSelector?: string;
+    }>;
+}
+export declare function genXpertDBInsertKey(): string;
+export interface IWFNDBUpdate extends IWorkflowNodeDBOperation {
+    type: WorkflowNodeTypeEnum.DB_UPDATE;
+    columns?: Record<string, {
+        type: DatabaseDataType;
+        value?: any;
+        valueSelector?: string;
+    }>;
+}
+export declare function genXpertDBUpdateKey(): string;
+export interface IWFNDBDelete extends IWorkflowNodeDBOperation {
+    type: WorkflowNodeTypeEnum.DB_DELETE;
+}
+export declare function genXpertDBDeleteKey(): string;
+export interface IWFNDBQuery extends IWorkflowNodeDBOperation {
+    type: WorkflowNodeTypeEnum.DB_QUERY;
+}
+export declare function genXpertDBQueryKey(): string;
+export interface IWFNDBSql extends IWorkflowNodeDBOperation {
+    type: WorkflowNodeTypeEnum.DB_SQL;
+    sqlTemplate?: string;
+}
+export declare function genXpertDBSqlKey(): string;

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

@@ -0,0 +1,26 @@
+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;
+    conversations?: IChatConversation[];
+    job?: any;
+    scheduleDescription?: string;
+    executionCount?: number;
+    errorCount?: number;
+    successCount?: number;
+};

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

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

@@ -0,0 +1,91 @@
+export declare enum MCPServerType {
+    SSE = "sse",
+    STDIO = "stdio",
+    CODE = "code",
+    HTTP = "http"
+}
+/**
+ * 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;
+}
+/**
+ * Configuration for Streamable HTTP transport connection
+ */
+export interface HttpConnection {
+    transport: "http";
+    url: string;
+    headers?: Record<string, string>;
+    /**
+     * Whether to automatically fallback to SSE if Streamable HTTP is not available.
+     * Defaults to true.
+     */
+    automaticSSEFallback?: 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;
+    /**
+     * Whether to automatically fallback to SSE if Streamable HTTP is not available.
+     * Defaults to true. Only applicable for HTTP transport.
+     */
+    automaticSSEFallback?: 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>;
+};