@xpert-ai/contracts 3.9.0-beta.1

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

@@ -0,0 +1,10 @@
+export declare enum AiFeatureEnum {
+    FEATURE_COPILOT = "FEATURE_COPILOT",
+    FEATURE_COPILOT_KNOWLEDGEBASE = "FEATURE_COPILOT_KNOWLEDGEBASE",
+    FEATURE_COPILOT_CHAT = "FEATURE_COPILOT_CHAT",
+    FEATURE_XPERT = "FEATURE_XPERT",
+    FEATURE_XPERT_CHATBI = "FEATURE_XPERT_CHATBI",
+    FEATURE_XPERT_CLAWXPERT = "FEATURE_XPERT_CLAWXPERT",
+    FEATURE_XPERT_CODEXPERT = "FEATURE_XPERT_CODEXPERT",
+    FEATURE_XPERT_DEEP_RESEARCH = "FEATURE_XPERT_DEEP_RESEARCH"
+}

package/src/ai/index.d.ts

@@ -0,0 +1,84 @@
+export declare const STATE_VARIABLE_HUMAN = "human";
+export declare enum ChatMessageTypeEnum {
+    MESSAGE = "message",
+    EVENT = "event"
+}
+export declare enum ChatMessageEventTypeEnum {
+    ON_CONVERSATION_START = "on_conversation_start",
+    ON_CONVERSATION_END = "on_conversation_end",
+    ON_MESSAGE_START = "on_message_start",
+    ON_MESSAGE_END = "on_message_end",
+    ON_TOOL_START = "on_tool_start",
+    ON_TOOL_END = "on_tool_end",
+    ON_TOOL_ERROR = "on_tool_error",
+    ON_TOOL_MESSAGE = "on_tool_message",
+    ON_AGENT_START = "on_agent_start",
+    ON_AGENT_END = "on_agent_end",
+    ON_RETRIEVER_START = "on_retriever_start",
+    ON_RETRIEVER_END = "on_retriever_end",
+    ON_RETRIEVER_ERROR = "on_retriever_error",
+    ON_INTERRUPT = "on_interrupt",
+    ON_ERROR = "on_error",
+    ON_CHAT_EVENT = "on_chat_event",
+    ON_CLIENT_EFFECT = "on_client_effect"
+}
+export declare enum ChatMessageStepCategory {
+    List = "list",
+    WebSearch = "web_search",
+    Files = "files",
+    File = "file",
+    Program = "program",
+    Iframe = "iframe",
+    Memory = "memory",
+    Tasks = "tasks",
+    Knowledges = "knowledges"
+}
+export type * from '@xpert-ai/chatkit-types';
+export type { TChatRequest } from './xpert-chat.model';
+export * from './assistant-binding.model';
+export * from './ai-model.model';
+export * from './ai.model';
+export * from './chat-event.model';
+export * from './chat.model';
+export * from './chat-message.model';
+export * from './chat-message-feedback.model';
+export * from './copilot-checkpoint.model';
+export * from './copilot-example.model';
+export * from './copilot-model.model';
+export * from './copilot-organization.model';
+export * from './copilot-provider.model';
+export * from './copilot-store.model';
+export * from './copilot-user.model';
+export * from './copilot.model';
+export * from './feature.model';
+export * from './rag';
+export * from './rag-web';
+export * from './knowledgebase.model';
+export * from './knowledge-doc.model';
+export * from './knowledge-doc-page.model';
+export * from './role-permissions';
+export * from './xpert-agent-execution.model';
+export * from './xpert-agent.model';
+export * from './xpert-chat.model';
+export * from './xpert-tool.model';
+export * from './xpert-toolset.model';
+export * from './xpert-workspace.model';
+export * from './xpert-table.model';
+export * from './xpert.model';
+export * from './xpert.utils';
+export * from './types';
+export * from './xpert-template.model';
+export * from './xpert-task.model';
+export * from './xpert-workflow.model';
+export * from './xpert-workflow-task.prompt';
+export * from './xpert-tool-mcp.model';
+export * from './xpert-project.model';
+export * from './environment.model';
+export * from './knowledgebase-task.model';
+export * from './knowledge-pipeline';
+export * from './knowledge-retrieval-log.model';
+export * from './knowledge-doc-chunk.model';
+export * from './skill.model';
+export * from './middleware.model';
+export * from './sandbox';
+export * from './message-content.utils';

package/src/ai/knowledge-doc-chunk.model.d.ts

@@ -0,0 +1,61 @@
+import { DocumentInterface } from '@langchain/core/documents';
+import { IBasePerTenantAndOrganizationEntityModel } from '../base-entity.model';
+import { IKnowledgeDocument } from './knowledge-doc.model';
+import { IKnowledgebase } from './knowledgebase.model';
+export type TDocumentAsset = {
+    type: 'image' | 'video' | 'audio' | 'file';
+    url: string;
+    filePath: string;
+};
+export interface IDocChunkMetadata {
+    chunkId: string;
+    parentId?: string | null;
+    children?: DocumentInterface<IDocChunkMetadata>[];
+    knowledgeId?: string;
+    chunkIndex?: number;
+    enabled?: boolean;
+    /**
+     * Default to 'text'. Indicates the original media type of the chunk.
+     * @default text
+     */
+    mediaType?: 'text' | 'image' | 'video' | 'audio';
+    /**
+     * Associated assets like images, videos, etc.
+     */
+    assets?: TDocumentAsset[];
+    /**
+     * Whether the chunk is represented as a vector in the vector store
+     */
+    isVector?: boolean;
+    score?: number;
+    relevanceScore?: number;
+    tokens?: number;
+    [key: string]: any;
+}
+/**
+ * Segmented chunk of a knowledge document
+ */
+export interface IKnowledgeDocumentChunk<Metadata extends IDocChunkMetadata = any> extends DocumentInterface<Metadata>, IBasePerTenantAndOrganizationEntityModel {
+    documentId?: string;
+    document?: IKnowledgeDocument;
+    knowledgebaseId?: string;
+    knowledgebase?: IKnowledgebase;
+    parent?: IKnowledgeDocumentChunk<Metadata>;
+    children?: IKnowledgeDocumentChunk<Metadata>[];
+}
+/**
+ * Build a hierarchical tree structure from a flat list of DocumentInterface objects,
+ * and
+ *
+ * @template Metadata - Type of metadata, defaults to IDocChunkMetadata
+ * @param documents - A flat array of DocumentInterface objects
+ * @returns the hierarchical tree (root-level DocumentInterface[])
+ */
+export declare function buildChunkTree<Metadata extends IDocChunkMetadata = IDocChunkMetadata>(documents: DocumentInterface<Metadata>[]): DocumentInterface<Metadata>[];
+/**
+ * Find all leaf nodes (nodes without children).
+ *
+ * @param roots
+ * @returns
+ */
+export declare function collectTreeLeaves(roots: IKnowledgeDocumentChunk[]): IKnowledgeDocumentChunk<any>[];

package/src/ai/knowledge-doc-page.model.d.ts

@@ -0,0 +1,15 @@
+import { Document } from '@langchain/core/documents';
+import { IBasePerTenantAndOrganizationEntityModel } from '../base-entity.model';
+import { IKnowledgeDocument } from './knowledge-doc.model';
+import { DocumentMetadata, IKnowledgebase } from './knowledgebase.model';
+/**
+ * Segmented page of a knowledge document
+ */
+export interface IKnowledgeDocumentPage<Metadata extends DocumentMetadata = DocumentMetadata> extends Document, IBasePerTenantAndOrganizationEntityModel {
+    documentId?: string;
+    document?: IKnowledgeDocument;
+    knowledgebaseId?: string;
+    knowledgebase?: IKnowledgebase;
+    metadata: Metadata;
+    pageContent: string;
+}

package/src/ai/knowledge-doc.model.d.ts

@@ -0,0 +1,222 @@
+import { IBasePerTenantAndOrganizationEntityModel } from '../base-entity.model';
+import { IIntegration } from '../integration.model';
+import { IStorageFile } from '../storage-file.model';
+import { IKnowledgeDocumentPage } from './knowledge-doc-page.model';
+import { IKnowledgebaseTask } from './knowledgebase-task.model';
+import { IKnowledgebase, KBMetadataFieldDef } from './knowledgebase.model';
+import { TRagWebOptions } from './rag-web';
+import { IKnowledgeDocumentChunk } from './knowledge-doc-chunk.model';
+import { DocumentSourceProviderCategoryEnum } from './knowledge-pipeline';
+import { TCopilotModel } from './copilot-model.model';
+import { I18nObject } from '../types';
+export type DocumentParserConfig = {
+    pages?: number[][];
+    replaceWhitespace?: boolean;
+    removeSensitive?: boolean;
+    textSplitterType?: string;
+    textSplitter?: {
+        [key: string]: unknown;
+    };
+    transformerType?: string;
+    transformerIntegration?: string;
+    transformer?: {
+        [key: string]: unknown;
+    };
+    imageUnderstandingType?: string;
+    imageUnderstandingIntegration?: string;
+    imageUnderstanding?: {
+        [key: string]: unknown;
+    };
+    imageUnderstandingModel?: TCopilotModel;
+};
+export type DocumentTextParserConfig = DocumentParserConfig & {
+    delimiter?: string;
+    chunkSize?: number | null;
+    chunkOverlap?: number | null;
+};
+export type DocumentSheetParserConfig = DocumentParserConfig & {
+    fields?: string[];
+    indexedFields?: string[];
+};
+/**
+ * Import Type:
+ * - file: local file
+ * - web: web document
+ * ...
+ */
+export declare enum DocumentTypeEnum {
+    /**
+     * Folder, parent of other documents
+     */
+    FOLDER = "folder",
+    /**
+     * Local files
+     * @deprecated use DocumentSourceProviderCategoryEnum local file type instead
+     */
+    FILE = "file"
+}
+export declare const KDocumentSourceType: {
+    FOLDER: DocumentTypeEnum.FOLDER;
+    FILE: DocumentTypeEnum.FILE;
+    LocalFile: DocumentSourceProviderCategoryEnum.LocalFile;
+    FileSystem: DocumentSourceProviderCategoryEnum.FileSystem;
+    OnlineDocument: DocumentSourceProviderCategoryEnum.OnlineDocument;
+    WebCrawl: DocumentSourceProviderCategoryEnum.WebCrawl;
+    Database: DocumentSourceProviderCategoryEnum.Database;
+};
+/**
+ * Document type category, determine how to process the document.
+ */
+export declare enum KBDocumentCategoryEnum {
+    Text = "text",
+    Image = "image",
+    Audio = "audio",
+    Video = "video",
+    Sheet = "sheet",
+    Other = "other"
+}
+export declare enum KBDocumentStatusEnum {
+    WAITING = "waiting",
+    VALIDATE = "validate",
+    RUNNING = "running",
+    TRANSFORMED = "transformed",
+    SPLITTED = "splitted",
+    UNDERSTOOD = "understood",
+    EMBEDDING = "embedding",
+    CANCEL = "cancel",
+    FINISH = "finish",
+    ERROR = "error"
+}
+export type TDocumentWebOptions = TRagWebOptions & {};
+export type TDocSourceConfig = {
+    key?: string;
+};
+export type TKnowledgeDocument = {
+    disabled?: boolean;
+    knowledgebaseId?: string;
+    /**
+     * @deprecated use fileUrl instead
+     */
+    storageFileId?: string;
+    /**
+     * @deprecated use fileUrl instead
+     */
+    storageFile?: IStorageFile;
+    /**
+     * thumbnail base64 string
+     */
+    thumbnail?: string;
+    /**
+     * default parser ID
+     * @deprecated unused
+     */
+    parserId: string;
+    parserConfig: DocumentTextParserConfig;
+    /**
+     * where dose this document come from
+     */
+    sourceType?: DocumentSourceProviderCategoryEnum | DocumentTypeEnum;
+    sourceConfig?: TDocSourceConfig;
+    /**
+     * document type category
+     */
+    category?: KBDocumentCategoryEnum | null;
+    /**
+     * Local file extension or Web doc provider
+     */
+    type: string;
+    /**
+     * file name or web url
+     */
+    name: string;
+    /**
+     * where does it store
+     */
+    filePath: string;
+    fileUrl?: string;
+    /**
+     * Folder path in server for this document file.
+     * Init it in creating document entity.
+     */
+    folder?: string;
+    size?: string;
+    mimeType?: string;
+    tokenNum?: number | null;
+    chunkNum?: number | null;
+    progress?: number | null;
+    /**
+     * process message
+     */
+    processMsg?: string | null;
+    processBeginAt?: Date | null;
+    processDuation?: number | null;
+    /**
+     * is it validate (0: wasted，1: validate)
+     */
+    status?: KBDocumentStatusEnum;
+    /**
+     * The background job id
+     */
+    jobId?: string;
+    options?: TDocumentWebOptions;
+    integrationId?: string;
+    integration?: IIntegration;
+    /**
+       * @deprecated use chunks instead
+       */
+    pages?: IKnowledgeDocumentPage[];
+    chunks?: IKnowledgeDocumentChunk[];
+    tasks?: IKnowledgebaseTask[];
+};
+/**
+ * Document, include file, web pages, folder, virtual, etc.
+ */
+export interface IKnowledgeDocument<T extends KnowledgeDocumentMetadata = KnowledgeDocumentMetadata> extends TKnowledgeDocument, IBasePerTenantAndOrganizationEntityModel {
+    parent?: IKnowledgeDocument | null;
+    children?: IKnowledgeDocument[];
+    knowledgebase?: IKnowledgebase;
+    draft?: TKnowledgeDocument;
+    metadata?: T;
+}
+/**
+ * System built-in standard document Metadata structure
+ */
+export interface StandardDocumentMetadata {
+    originalFileName?: string;
+    originalFileSize?: string | null;
+    uploadTime?: string;
+    lastUpdatedTime?: string;
+    source?: string;
+    segmentRule?: string;
+    segmentLength?: number;
+    averageSegmentLength?: string;
+    segmentCount?: number;
+    recallRate?: string;
+    embedTime?: string;
+    embedCost?: string | null;
+    tokens?: number;
+}
+export interface KnowledgeDocumentMetadata extends StandardDocumentMetadata {
+    [key: string]: any;
+}
+export interface IKnowledgeDocumentCreateInput extends IKnowledgeDocument, IBasePerTenantAndOrganizationEntityModel {
+}
+export interface IKnowledgeDocumentUpdateInput extends Partial<IKnowledgeDocumentCreateInput> {
+    id?: string;
+}
+export interface IKnowledgeDocumentFindInput extends IBasePerTenantAndOrganizationEntityModel, IKnowledgeDocument {
+}
+export declare function isDocumentSheet(type: string): boolean;
+export declare function isImageType(type: string): boolean;
+export declare function isVideoType(type: string): boolean;
+export declare function isAudioType(type: string): boolean;
+export declare function classificateDocumentCategory(entity: Partial<IKnowledgeDocument>): KBDocumentCategoryEnum;
+/**
+ * System standard Metadata field definition constants
+ * It can be used for rendering, validation, sorting, displaying descriptions, etc.
+ */
+export declare const STANDARD_METADATA_FIELDS: {
+    group: I18nObject;
+    fields: KBMetadataFieldDef[];
+}[];
+export type StandardMetadataFieldKey = typeof STANDARD_METADATA_FIELDS[number]['fields'][number]['key'];

package/src/ai/knowledge-pipeline.d.ts

@@ -0,0 +1,107 @@
+import { I18nObject, IconDefinition } from '../types';
+import { ICopilotModel } from './copilot-model.model';
+import { KnowledgeStructureEnum } from './knowledgebase.model';
+import { IWorkflowNode, WorkflowNodeTypeEnum } from './xpert-workflow.model';
+import { TXpertParameter } from './xpert.model';
+export interface IDocumentNodeProvider {
+    name: string;
+    label: I18nObject;
+    icon?: IconDefinition;
+    description?: I18nObject;
+    helpUrl?: string;
+    configSchema: any;
+}
+/**
+ * Category of document source provider
+ */
+export declare enum DocumentSourceProviderCategoryEnum {
+    /**
+     * Local files uploaded directly to the system
+     */
+    LocalFile = "local-file",
+    /**
+     * Remote file systems, e.g. S3, FTP, etc.
+     */
+    FileSystem = "file-system",
+    /**
+     * Online documents, e.g. public URLs, Google Docs, etc.
+     */
+    OnlineDocument = "online-document",
+    /**
+     * Web crawling from public websites
+     */
+    WebCrawl = "web-crawl",
+    /**
+     * Database connections, e.g. MySQL, PostgreSQL, etc.
+     * @deprecated Planning
+     */
+    Database = "database"
+}
+export interface IDocumentSourceProvider extends IDocumentNodeProvider {
+    category: DocumentSourceProviderCategoryEnum;
+}
+export interface IDocumentProcessorProvider extends IDocumentNodeProvider {
+}
+export interface IDocumentChunkerProvider extends IDocumentNodeProvider {
+}
+export interface IDocumentUnderstandingProvider extends IDocumentNodeProvider {
+}
+/**
+ * Knowledge Pipeline Source Node
+ */
+export interface IWFNSource<T = any> extends IWorkflowNode {
+    type: WorkflowNodeTypeEnum.SOURCE;
+    provider: string;
+    parameters?: TXpertParameter[];
+    config: T;
+    integrationId?: string;
+}
+export interface IWFNProcessor extends IWorkflowNode {
+    type: WorkflowNodeTypeEnum.PROCESSOR;
+    provider: string;
+    config: any;
+    input: string;
+    integrationId?: string;
+}
+export interface IWFNChunker extends IWorkflowNode {
+    type: WorkflowNodeTypeEnum.CHUNKER;
+    provider: string;
+    config: any;
+    input: string;
+}
+export interface IWFNUnderstanding extends IWorkflowNode {
+    type: WorkflowNodeTypeEnum.UNDERSTANDING;
+    provider: string;
+    config: any;
+    input: string;
+    visionModel?: ICopilotModel;
+}
+export interface IWFNKnowledgeBase extends IWorkflowNode {
+    type: WorkflowNodeTypeEnum.KNOWLEDGE_BASE;
+    /**
+     * @deprecated
+     */
+    structure?: KnowledgeStructureEnum;
+    /**
+     * Documents input variables
+     */
+    inputs?: string[];
+    /**
+     * Embedding model
+     */
+    copilotModel?: ICopilotModel;
+    /**
+     * (optional) Rerank model
+     */
+    rerankModel?: ICopilotModel;
+    /**
+     * (optional) Vision model
+     */
+    visionModel?: ICopilotModel;
+    documents?: string[];
+}
+export declare function genPipelineSourceKey(): string;
+export declare function genPipelineProcessorKey(): string;
+export declare function genPipelineChunkerKey(): string;
+export declare function genPipelineUnderstandingKey(): string;
+export declare function genPipelineKnowledgeBaseKey(): string;

package/src/ai/knowledge-retrieval-log.model.d.ts

@@ -0,0 +1,10 @@
+import { IBasePerTenantAndOrganizationEntityModel } from "../base-entity.model";
+import { IKnowledgebase } from "./knowledgebase.model";
+export interface IKnowledgeRetrievalLog extends IBasePerTenantAndOrganizationEntityModel {
+    query: string;
+    source: string;
+    hitCount: number;
+    requestId: string;
+    knowledgebaseId?: string;
+    knowledgebase?: IKnowledgebase;
+}

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

@@ -0,0 +1,39 @@
+import { IBasePerTenantAndOrganizationEntityModel } from '../base-entity.model';
+import { IChatConversation } from './chat.model';
+import { IKnowledgeDocument } from './knowledge-doc.model';
+import { IKnowledgebase } from './knowledgebase.model';
+import { IXpertAgentExecution } from './xpert-agent-execution.model';
+/**
+ * Task executions of a knowledgebase
+ */
+export interface IKnowledgebaseTask extends IBasePerTenantAndOrganizationEntityModel {
+    knowledgebaseId?: string;
+    knowledgebase?: IKnowledgebase;
+    conversationId?: string;
+    conversation?: IChatConversation;
+    executionId?: string;
+    execution?: IXpertAgentExecution;
+    taskType: string;
+    status?: 'pending' | 'running' | 'success' | 'failed' | 'cancelled';
+    steps: TaskStep[];
+    error?: string;
+    /**
+     * Temporary content: Documents not actually processed in the task yet
+     */
+    context?: {
+        documents?: Partial<IKnowledgeDocument>[];
+    };
+    /**
+     * Many to Many of documents in task
+     */
+    documents?: IKnowledgeDocument[];
+}
+export interface TaskStep {
+    name: string;
+    status: 'pending' | 'running' | 'success' | 'failed';
+    progress: number;
+    log?: string;
+    error_message?: string;
+    started_at?: Date;
+    finished_at?: Date;
+}