@xpert-ai/contracts 3.9.0-beta.1

package/src/ai/assistant-binding.model.d.ts

@@ -0,0 +1,81 @@
+import { IBasePerTenantAndOrganizationEntityModel } from '../base-entity.model';
+import { IUser } from '../user.model';
+export declare enum AssistantCode {
+    CHAT_COMMON = "chat_common",
+    XPERT_SHARED = "xpert_shared",
+    CHATBI = "chatbi",
+    CLAWXPERT = "clawxpert"
+}
+export declare enum AssistantBindingScope {
+    TENANT = "tenant",
+    ORGANIZATION = "organization",
+    USER = "user"
+}
+export declare enum AssistantBindingSourceScope {
+    NONE = "none",
+    TENANT = "tenant",
+    ORGANIZATION = "organization"
+}
+export type AssistantManagement = 'system' | 'user';
+export interface IAssistantBindingToolsetPreference {
+    toolsetId?: string | null;
+    toolsetName: string;
+    disabledTools: string[];
+}
+export interface IAssistantBindingMiddlewarePreference {
+    provider: string;
+    disabledTools: string[];
+}
+export interface IAssistantBindingSkillPreference {
+    workspaceId: string;
+    disabledSkillIds: string[];
+}
+export interface IAssistantBindingConversationPreferences {
+    version: 1;
+    defaultThreadId?: string | null;
+    lastThreadId?: string | null;
+}
+export interface IAssistantBindingToolPreferences {
+    version: 1;
+    toolsets?: Record<string, IAssistantBindingToolsetPreference>;
+    middlewares?: Record<string, IAssistantBindingMiddlewarePreference>;
+    skills?: Record<string, IAssistantBindingSkillPreference>;
+}
+export interface IAssistantBinding extends IBasePerTenantAndOrganizationEntityModel {
+    code: AssistantCode;
+    scope: AssistantBindingScope;
+    assistantId?: string | null;
+    enabled?: boolean | null;
+    userId?: string | null;
+    user?: IUser;
+    preferences?: IAssistantBindingUserPreference[];
+}
+export interface IAssistantBindingUserPreference extends IBasePerTenantAndOrganizationEntityModel {
+    assistantBindingId: string;
+    assistantBinding?: IAssistantBinding;
+    userId?: string | null;
+    user?: IUser;
+    soul?: string | null;
+    profile?: string | null;
+    toolPreferences?: IAssistantBindingToolPreferences | null;
+    conversationPreferences?: IAssistantBindingConversationPreferences | null;
+}
+export interface IResolvedAssistantBinding extends IAssistantBinding {
+    sourceScope: AssistantBindingSourceScope;
+}
+export interface IAssistantBindingUpsertInput {
+    code: AssistantCode;
+    scope: AssistantBindingScope;
+    assistantId?: string | null;
+    enabled?: boolean;
+}
+export interface IAssistantBindingUserPreferenceUpsertInput {
+    scope: AssistantBindingScope;
+    soul?: string | null;
+    profile?: string | null;
+    toolPreferences?: IAssistantBindingToolPreferences | null;
+    conversationPreferences?: IAssistantBindingConversationPreferences | null;
+}
+export declare function getAssistantManagement(code: AssistantCode): AssistantManagement;
+export declare function isUserManagedAssistant(code: AssistantCode): boolean;
+export declare function isSystemManagedAssistant(code: AssistantCode): boolean;

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

@@ -0,0 +1,8 @@
+import type { TChatEventMessage } from '@xpert-ai/chatkit-types';
+export declare const CHAT_EVENT_TYPE_THREAD_CONTEXT_USAGE: "thread_context_usage";
+export declare const CHAT_EVENT_TYPE_CONVERSATION_TITLE_SUMMARY: "conversation_title_summary";
+export type TConversationTitleSummaryEvent = TChatEventMessage & {
+    id?: string;
+    type: typeof CHAT_EVENT_TYPE_CONVERSATION_TITLE_SUMMARY;
+};
+export declare function createConversationTitleSummaryEvent(event: Omit<TConversationTitleSummaryEvent, 'type'>): TConversationTitleSummaryEvent;

package/src/ai/chat-message-feedback.model.d.ts

@@ -0,0 +1,24 @@
+import { IBasePerTenantAndOrganizationEntityModel } from '../base-entity.model';
+import { IChatMessage } from './chat-message.model';
+import { IChatConversation } from './chat.model';
+export declare enum ChatMessageFeedbackRatingEnum {
+    LIKE = "like",
+    DISLIKE = "dislike"
+}
+/**
+ *
+ */
+export interface IChatMessageFeedback extends IBasePerTenantAndOrganizationEntityModel {
+    rating: ChatMessageFeedbackRatingEnum;
+    content?: string;
+    /**
+     * Chat conversation
+     */
+    conversation?: IChatConversation;
+    conversationId?: string | null;
+    /**
+     * Chat conversation message
+     */
+    message?: IChatMessage;
+    messageId?: string | null;
+}

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

@@ -0,0 +1,93 @@
+import { MessageType } from '@langchain/core/messages';
+import type { TChatMessageStep, TMessageContent, TMessageContentReasoning } from '@xpert-ai/chatkit-types';
+import { IBasePerTenantAndOrganizationEntityModel } from '../base-entity.model';
+import { IChatConversation } from './chat.model';
+import { LongTermMemoryTypeEnum } from './xpert.model';
+import { IXpertAgentExecution, XpertAgentExecutionStatusEnum } from './xpert-agent-execution.model';
+import { JSONValue } from '../core.model';
+import { IStorageFile } from '../storage-file.model';
+export type TSummaryJob = Record<LongTermMemoryTypeEnum, {
+    jobId: number | string;
+    status: string;
+    progress?: number;
+    memoryKey?: string;
+}>;
+/**
+ * Chat message entity type
+ */
+export interface IChatMessage extends IBasePerTenantAndOrganizationEntityModel, Omit<Omit<CopilotBaseMessage, 'createdAt'>, 'id'> {
+    parent?: IChatMessage | null;
+    children?: IChatMessage[];
+    parentId?: string | null;
+    /**
+     * Files
+     */
+    attachments?: IStorageFile[];
+    /**
+     * Job of summary
+     */
+    summaryJob?: TSummaryJob;
+    /**
+     * the third-party platform's message
+     */
+    thirdPartyMessage?: any;
+    /**
+     * Step messages from tools or others
+     */
+    events?: TChatMessageStep[];
+    /**
+     * Chat conversation
+     */
+    conversation?: IChatConversation;
+    conversationId?: string | null;
+    executionId?: string;
+    execution?: IXpertAgentExecution;
+}
+/**
+ * @deprecated
+ */
+export type DeprecatedMessageType = 'assistant' | 'user' | 'info' | 'component';
+export type CopilotMessageType = MessageType | DeprecatedMessageType;
+export type ChatMessageStatusEnum = XpertAgentExecutionStatusEnum | 'thinking' | 'reasoning' | 'answering' | 'aborted';
+/**
+ * BaseMessage or AIMessage in Langchain.js
+ */
+export interface CopilotBaseMessage {
+    id?: string;
+    createdAt?: Date;
+    role: CopilotMessageType;
+    /**
+     * Status of the message:
+     */
+    status?: ChatMessageStatusEnum;
+    content?: string | TMessageContent;
+    /**
+     * Reasoning step messages
+     */
+    reasoning?: TMessageContentReasoning[];
+    /**
+     * Error info when status is error
+     */
+    error?: string;
+}
+export type CopilotChatMessage = CopilotBaseMessage & {
+    tool_call_id?: string;
+    /**
+     * If the message has a role of `function`, the `name` field is the name of the function.
+     * Otherwise, the name field should not be set.
+     */
+    name?: string;
+    data?: JSONValue;
+    messages?: Array<any>;
+    executionId?: string;
+};
+/**
+ * @deprecated use data attr in message (subMessages)
+ */
+export interface CopilotMessageGroup extends CopilotBaseMessage {
+    messages?: CopilotChatMessage[];
+}
+/**
+ * @deprecated use content in message
+ */
+export declare function isMessageGroup(message: CopilotBaseMessage): message is CopilotMessageGroup;

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

@@ -0,0 +1,191 @@
+import { IBasePerTenantAndOrganizationEntityModel } from '../base-entity.model';
+import { IXpertAgentExecution } from './xpert-agent-execution.model';
+import { IXpert } from './xpert.model';
+import { I18nObject } from '../types';
+import { CopilotChatMessage, CopilotMessageGroup, IChatMessage } from './chat-message.model';
+import { IXpertAgent } from './xpert-agent.model';
+import { IXpertProject } from './xpert-project.model';
+import { IStorageFile } from '../storage-file.model';
+import { IXpertTask } from './xpert-task.model';
+import { TToolCall } from '../agent';
+import { TInterrupt } from '../agent/interrupt';
+import { IUser } from '../user.model';
+export type TChatConversationOptions = {
+    parameters?: {
+        input?: string;
+        [key: string]: unknown;
+    };
+    knowledgebases?: string[];
+    toolsets?: string[];
+    features?: Array<'timeline' | 'sandbox' | 'files'>;
+    workspacePath?: string;
+    workspaceUrl?: string;
+    sandboxEnvironmentId?: string;
+};
+export type TChatConversationStatus = 'idle' | 'busy' | 'interrupted' | 'error';
+export type TToolCallType = 'agent' | 'tool';
+export type TChatFrom = 'platform' | 'webapp' | 'debugger' | 'knowledge' | 'job' | 'api' | 'feishu' | 'lark' | 'dingtalk' | 'wecom';
+/**
+ * Operation for interrupt
+ */
+export type TSensitiveOperation = {
+    messageId?: string;
+    tasks?: {
+        name: string;
+        interrupts: TInterrupt[];
+        type?: TToolCallType;
+        info?: {
+            name: string;
+            title?: string;
+            description: string;
+        };
+        parameters?: {
+            name: string;
+            title: I18nObject | string;
+            type: string;
+            description: I18nObject | string;
+            placeholder?: I18nObject | string;
+        }[];
+        call?: TToolCall;
+        agent?: IXpertAgent;
+    }[];
+};
+/**
+ * Chat conversation for xpert ai agent.
+ *
+ * Corresponds to the thread in the [Agent Protocol](https://github.com/langchain-ai/agent-protocol).
+ */
+export interface IChatConversation extends IBasePerTenantAndOrganizationEntityModel {
+    /**
+     * Thread id for agent execution
+     */
+    threadId: string;
+    /**
+     * A short title summarizing the session
+     */
+    title?: string;
+    /**
+     * Current status of conversation
+     */
+    status?: TChatConversationStatus;
+    /**
+     * Options
+     */
+    options?: TChatConversationOptions;
+    /**
+     * Error message when status is error
+     */
+    error?: string;
+    /**
+     * ChatMessages in conversation
+     */
+    messages?: IChatMessage[] | null;
+    /**
+     * The last operation when interrupted
+     */
+    operation?: TSensitiveOperation;
+    /**
+     * Conversation source / user type
+     */
+    from: TChatFrom;
+    /**
+     * End anonymous user
+     */
+    fromEndUserId?: string;
+    /**
+     * Internal user matched by fromEndUserId when available
+     */
+    fromEndUser?: IUser;
+    /**
+     * Chat with Xpert
+     */
+    xpert?: IXpert;
+    xpertId?: string | null;
+    project?: IXpertProject;
+    projectId?: string | null;
+    task?: IXpertTask;
+    taskId?: string | null;
+    executions?: IXpertAgentExecution[];
+    /**
+     * Files
+     */
+    attachments?: IStorageFile[];
+}
+export type TChatConversationLog = IChatConversation & {
+    messageCount: number;
+};
+export type ChatMessage = {
+    conversationId: string;
+    id: string;
+    content: string;
+};
+export type ChatUserMessage = ChatMessage & {
+    language: string;
+};
+/**
+ * @deprecated use ChatMessageEventTypeEnum
+ */
+export declare enum ChatGatewayEvent {
+    ACK = "ack",// acknowledgment for received message
+    ConversationCreated = "conversation_created",
+    Message = "message",
+    MessageStream = "message_stream",
+    StepStart = "step_start",
+    StepEnd = "step_end",
+    ToolStart = "tool_start",
+    ToolEnd = "tool_end",
+    ChainStart = "chain_start",
+    ChainEnd = "chain_end",
+    CancelChain = "cancel_chain",
+    ChainAborted = "chain_aborted",
+    Error = "error",
+    Agent = "agent"
+}
+/**
+ * @deprecated use ChatMessageEventTypeEnum
+ */
+export type ChatGatewayMessage = {
+    organizationId?: string;
+    xpert?: {
+        id: string;
+        knowledgebases?: string[];
+        toolsets: string[] | null;
+    };
+} & ({
+    event: ChatGatewayEvent.CancelChain;
+    data: {
+        conversationId: string;
+    };
+} | {
+    event: ChatGatewayEvent.ChainAborted;
+    data: {
+        conversationId: string;
+        id?: string;
+    };
+} | {
+    event: ChatGatewayEvent.ConversationCreated;
+    data: IChatConversation;
+} | {
+    event: ChatGatewayEvent.MessageStream;
+    data: ChatUserMessage;
+} | {
+    event: ChatGatewayEvent.ToolStart | ChatGatewayEvent.ToolEnd;
+    data: CopilotMessageGroup | CopilotMessageGroup[];
+} | {
+    event: ChatGatewayEvent.ChainStart | ChatGatewayEvent.ChainEnd;
+    data: {
+        id: string;
+    };
+} | {
+    event: ChatGatewayEvent.StepStart | ChatGatewayEvent.StepEnd;
+    data: CopilotChatMessage;
+} | {
+    event: ChatGatewayEvent.Message | ChatGatewayEvent.Error;
+    data: CopilotChatMessage;
+} | {
+    event: ChatGatewayEvent.Agent;
+    data: {
+        id: string;
+        message: CopilotChatMessage;
+    };
+});

package/src/ai/copilot-checkpoint.model.d.ts

@@ -0,0 +1,23 @@
+import { IBasePerTenantAndOrganizationEntityModel } from '../base-entity.model';
+/**
+ * Checkpoints for copilot, for langgraph framework
+ */
+export interface ICopilotCheckpoint extends IBasePerTenantAndOrganizationEntityModel {
+    thread_id: string;
+    checkpoint_ns: string;
+    checkpoint_id: string;
+    parent_id?: string;
+    type?: string;
+    checkpoint: Uint8Array;
+    metadata: Uint8Array;
+}
+export interface ICopilotCheckpointWrites extends IBasePerTenantAndOrganizationEntityModel {
+    thread_id: string;
+    checkpoint_ns: string;
+    checkpoint_id: string;
+    task_id?: string;
+    idx?: number;
+    channel?: string;
+    type?: string;
+    value: Uint8Array;
+}

package/src/ai/copilot-example.model.d.ts

@@ -0,0 +1,19 @@
+import { IBasePerTenantAndOrganizationEntityModel } from '../base-entity.model';
+import { AiProvider } from './ai.model';
+import { IXpert } from './xpert.model';
+/**
+ * Examples for copilot, which is used to few shot user question
+ */
+export interface ICopilotKnowledge extends IBasePerTenantAndOrganizationEntityModel {
+    provider?: AiProvider | string;
+    /**
+     * The name of xpert (copilot type)
+     */
+    role?: string;
+    command?: string;
+    input?: string;
+    output?: string;
+    vector?: boolean;
+    xpert?: IXpert;
+    xpertId?: string;
+}

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

@@ -0,0 +1,30 @@
+import { AiModelTypeEnum } from '../agent';
+import { IBasePerTenantAndOrganizationEntityModel } from '../base-entity.model';
+import { ICopilot } from './copilot.model';
+export interface ICopilotModel extends TCopilotModel, IBasePerTenantAndOrganizationEntityModel {
+}
+export type TCopilotModel = {
+    /**
+     * Use a separate copilot
+     */
+    copilot?: ICopilot;
+    copilotId?: string;
+    /**
+     * Referenced copilot model if not using a separate copilot
+     */
+    referencedModel?: ICopilotModel;
+    referencedId?: string;
+    modelType?: AiModelTypeEnum;
+    model?: string;
+    /**
+     * Details config for ai model
+     */
+    options?: TCopilotModelOptions;
+};
+export type TCopilotModelOptions = {
+    /**
+     * Max input context size of selected model
+     */
+    context_size?: number;
+    [key: string]: any;
+};

package/src/ai/copilot-organization.model.d.ts

@@ -0,0 +1,17 @@
+import { IBasePerTenantEntityModel } from '../base-entity.model';
+import { IOrganization } from '../organization.model';
+import { AiProvider } from './ai.model';
+import { ICopilot, TCopilotTokenUsage } from './copilot.model';
+/**
+ * Organization token usage of global copilot
+ */
+export interface ICopilotOrganization extends IBasePerTenantEntityModel, TCopilotTokenUsage {
+    organizationId?: string;
+    organization?: IOrganization;
+    copilotId?: string;
+    copilot?: ICopilot;
+    provider?: AiProvider | string;
+    model?: string;
+    tokenTotalUsed?: number;
+    priceTotalUsed?: number;
+}

package/src/ai/copilot-provider.model.d.ts

@@ -0,0 +1,31 @@
+import { AiModelTypeEnum } from '../agent';
+import { IBasePerTenantAndOrganizationEntityModel } from '../base-entity.model';
+import { IAiProviderEntity } from './ai-model.model';
+import { ICopilot } from './copilot.model';
+export interface ICopilotProvider extends IBasePerTenantAndOrganizationEntityModel {
+    providerName?: string;
+    providerType?: string;
+    credentials?: Record<string, any>;
+    isValid?: boolean;
+    lastUsed?: Date;
+    quotaType?: string;
+    quotaLimit?: number;
+    quotaUsed?: number;
+    /**
+     */
+    options?: any;
+    copilot?: ICopilot;
+    copilotId?: string;
+    models?: ICopilotProviderModel[];
+    provider?: IAiProviderEntity;
+}
+export interface ICopilotProviderModel extends IBasePerTenantAndOrganizationEntityModel {
+    providerName?: string;
+    modelName?: string;
+    modelType?: AiModelTypeEnum;
+    modelProperties?: Record<string, any>;
+    isValid?: boolean;
+    provider?: ICopilotProvider;
+    providerId?: string;
+}
+export type TCopilotProviderPublicDto = Omit<ICopilotProvider, 'credentials'>;

package/src/ai/copilot-role.model.d.ts

@@ -0,0 +1,43 @@
+import { IBasePerTenantAndOrganizationEntityModel } from '../base-entity.model';
+import { IXpertToolset } from './xpert-toolset.model';
+import { IKnowledgebase } from './knowledgebase.model';
+/**
+ * @deprecated use Xpert
+ *
+ * Copilot role, business role for the copilot
+ */
+export interface ICopilotRole extends IBasePerTenantAndOrganizationEntityModel {
+    name: string;
+    title?: string;
+    titleCN?: string;
+    description?: string;
+    /**
+     * 系统提示语
+     */
+    prompt?: string;
+    /**
+     * 对话开场白
+     */
+    starters?: string[];
+    active?: boolean;
+    avatar?: string;
+    toolsets?: IXpertToolset[];
+    /**
+     * More configuration
+     */
+    options?: TCopilotRoleOptions;
+    knowledgebases?: IKnowledgebase[];
+}
+/**
+ * @deprecated use XpertRole
+ */
+export type TCopilotRoleOptions = {
+    context?: Record<string, any>;
+    toolsets: {
+        [id: string]: {
+            [tool: string]: {
+                defaultArgs: Record<string, any>;
+            };
+        };
+    };
+};

package/src/ai/copilot-store.model.d.ts

@@ -0,0 +1,29 @@
+import { IBasePerTenantAndOrganizationEntityModel } from '../base-entity.model';
+export interface ICopilotStore extends TCopilotStore, IBasePerTenantAndOrganizationEntityModel {
+}
+export interface ICopilotStoreVector extends TCopilotStoreVector, IBasePerTenantAndOrganizationEntityModel {
+}
+export type TCopilotStore = {
+    prefix: string;
+    key?: string;
+    value: any;
+};
+export type TCopilotStoreVector = {
+    prefix: string;
+    key: string;
+    field_name: any;
+    embedding: number[];
+};
+export declare const MEMORY_QA_PROMPT = "Summarize the experience of the above conversation and output a short question and answer.";
+export declare const MEMORY_PROFILE_PROMPT = "Extract new user profile information from the above conversation in one short sentence. If no new information is available, return nothing.";
+export type TMemory = {
+    memoryId?: string;
+};
+export type TMemoryUserProfile = TMemory & {
+    profile: string;
+    context?: string;
+};
+export type TMemoryQA = TMemory & {
+    question: string;
+    answer: string;
+};

package/src/ai/copilot-user.model.d.ts

@@ -0,0 +1,27 @@
+import { IBasePerTenantAndOrganizationEntityModel } from '../base-entity.model';
+import { IOrganization } from '../organization.model';
+import { IUser } from '../user.model';
+import { AiProvider } from './ai.model';
+import { ICopilot, TCopilotTokenUsage } from './copilot.model';
+export declare const USAGE_HOUR_FORMAT = "yyyy-MM-dd HH";
+/**
+ *
+ */
+export interface ICopilotUser extends IBasePerTenantAndOrganizationEntityModel, TCopilotTokenUsage {
+    orgId?: string;
+    org?: IOrganization;
+    copilotId?: string;
+    copilot?: ICopilot;
+    userId?: string;
+    user?: IUser;
+    xpertId?: string;
+    /**
+     * Usage hour in format 'yyyy-MM-dd HH' {@link USAGE_HOUR_FORMAT}
+     */
+    usageHour: string;
+    threadId: string;
+    provider?: AiProvider | string;
+    model?: string;
+    tokenTotalUsed?: number;
+    priceTotalUsed?: number;
+}

package/src/ai/copilot.model.d.ts

@@ -0,0 +1,36 @@
+import { IBasePerTenantAndOrganizationEntityModel } from '../base-entity.model';
+import { ICopilotModel } from './copilot-model.model';
+import { ICopilotProvider } from './copilot-provider.model';
+export interface ICopilot extends IBasePerTenantAndOrganizationEntityModel {
+    name?: string;
+    role: AiProviderRole;
+    enabled?: boolean;
+    showTokenizer?: boolean;
+    /**
+     * Balance of Token
+     */
+    tokenBalance?: number;
+    /**
+     * Details config for openai api
+     */
+    options?: any;
+    modelProvider?: ICopilotProvider;
+    copilotModel?: ICopilotModel;
+    usage?: TCopilotTokenUsage;
+}
+/**
+ * The order of priority is: `Embedding`, `Secondary`, `Primary`
+ */
+export declare enum AiProviderRole {
+    Primary = "primary",
+    Secondary = "secondary",
+    Embedding = "embedding",
+    Reasoning = "reasoning"
+}
+export type TCopilotTokenUsage = {
+    tokenLimit?: number;
+    priceLimit?: number;
+    tokenUsed?: number;
+    priceUsed?: number;
+    currency?: string;
+};

package/src/ai/environment.model.d.ts

@@ -0,0 +1,16 @@
+import { IBasePerWorkspaceEntityModel } from "./xpert-workspace.model";
+export type TEnvironmentVariable = {
+    name: string;
+    value: string;
+    type: 'default' | 'secret';
+    /**
+     * Has owner, private variable
+     */
+    owner?: string;
+};
+export interface IEnvironment extends IBasePerWorkspaceEntityModel {
+    name: string;
+    isDefault?: boolean;
+    isArchived?: boolean;
+    variables: TEnvironmentVariable[];
+}