@metad/contracts 3.6.7 → 3.7.0

package/src/ai/index.d.ts

@@ -0,0 +1,42 @@
+export * from './ai-model.model';
+export * from './ai.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-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';

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;
+}

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

@@ -0,0 +1,174 @@
+import { ICopilotModel } from './copilot-model.model';
+import { I18nObject, TAvatar } from '../types';
+import { IBasePerWorkspaceEntityModel } from './xpert-workspace.model';
+import { IKnowledgeDocument } from './knowledge-doc.model';
+import { IXpert } from './xpert.model';
+import { IIntegration } from '../integration.model';
+import { IDocChunkMetadata } from './knowledge-doc-chunk.model';
+/**
+ * Non-internal types should remain the same as IntegrationEnum.
+ */
+export declare enum KnowledgeProviderEnum {
+    Internal = "internal"
+}
+export declare enum KnowledgebaseTypeEnum {
+    Standard = "standard",
+    External = "external"
+}
+export declare enum KnowledgeStructureEnum {
+    General = "general",
+    ParentChild = "parent-child",
+    QA = "qa"
+}
+export type KnowledgebaseParserConfig = {
+    pages?: number[][];
+    embeddingBatchSize?: number;
+    chunkSize: number | null;
+    chunkOverlap: number | null;
+    delimiter: string | null;
+};
+/**
+ * Type of rag knowledgebase
+ */
+export type TKnowledgebase = {
+    /**
+     * KB name
+     */
+    name: string;
+    /**
+     * Type of KB
+     */
+    type: KnowledgebaseTypeEnum;
+    /**
+     * English | Chinese
+     */
+    language?: 'Chinese' | 'English' | null;
+    /**
+     * Avatar object
+     */
+    avatar?: TAvatar;
+    /**
+     * KB description
+     */
+    description?: string;
+    /**
+     * Public in tenant or in organization or private
+     * @default private
+     */
+    permission?: KnowledgebasePermission;
+    /**
+     * Copilot model for knowledgebase
+     */
+    copilotModel?: ICopilotModel;
+    copilotModelId?: string;
+    rerankModel?: ICopilotModel;
+    rerankModelId?: string;
+    visionModel?: ICopilotModel;
+    visionModelId?: string;
+    documentNum?: number | null;
+    tokenNum?: number | null;
+    chunkNum?: number | null;
+    /**
+     *@deprecated use `recall`
+     */
+    similarityThreshold?: number;
+    vectorSimilarityWeight?: number;
+    /**
+     * @deprecated
+     * default parser ID
+     */
+    parserId?: string;
+    parserConfig?: KnowledgebaseParserConfig;
+    /**
+     * Index structure determines how the knowledge base organizes and indexes your document content.
+     * @deprecated
+     */
+    structure?: KnowledgeStructureEnum;
+    /**
+     * Recall params for kb chunks
+     */
+    recall?: TKBRecallParams;
+    status?: string;
+    /**
+     * Metadata custom field definition array
+     */
+    metadataSchema?: KBMetadataFieldDef[];
+    /**
+     * API service enabled
+     */
+    apiEnabled?: boolean;
+    documents?: IKnowledgeDocument[];
+    integrationId?: string;
+    extKnowledgebaseId?: string;
+    pipelineId?: string;
+};
+/**
+ * Knowledgebase Entity
+ */
+export interface IKnowledgebase extends TKnowledgebase, IBasePerWorkspaceEntityModel {
+    xperts?: IXpert[];
+    integration?: IIntegration;
+    pipeline?: IXpert;
+}
+/**
+ * Knowledgebase permission levels
+ */
+export declare enum KnowledgebasePermission {
+    /**
+     * Only visible to you
+     * @default
+     */
+    Private = "private",
+    /**
+     * Visible to all members in the organization
+     */
+    Organization = "organization",
+    /**
+     * Visible to all members in the tenant
+     */
+    Public = "public"
+}
+/**
+ * Recall parameters
+ */
+export type TKBRecallParams = {
+    /**
+     * Top K of result chunks
+     */
+    topK?: number;
+    /**
+     * At least the similarity threshold
+     */
+    score?: number;
+    /**
+     * Weight in EnsembleRetriever
+     */
+    weight?: number;
+};
+export type DocumentMetadata = IDocChunkMetadata & {
+    score?: number;
+    relevanceScore?: number;
+} & Record<string, any>;
+export type MetadataFieldType = 'string' | 'number' | 'boolean' | 'enum' | 'datetime' | 'string[]' | 'number[]' | 'object';
+export type KBMetadataFieldDef = {
+    key: string;
+    label?: I18nObject;
+    type: MetadataFieldType;
+    enumValues?: string[];
+    description?: string;
+};
+/**
+ * Channel name for knowledgebase pipeline
+ */
+export declare const KnowledgebaseChannel: string;
+/**
+ * Task ID of a knowledgebase run
+ */
+export declare const KnowledgeTask = "task_id";
+/**
+ * Specify the data source to run
+ */
+export declare const KNOWLEDGE_SOURCES_NAME = "sources";
+export declare const KNOWLEDGE_DOCUMENTS_NAME = "documents";
+export declare const KNOWLEDGE_FOLDER_ID_NAME = "folder_id";
+export declare const KNOWLEDGE_STAGE_NAME = "stage";

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

@@ -0,0 +1,18 @@
+import { IWorkflowNode, WorkflowNodeTypeEnum } from "./xpert-workflow.model";
+import { I18nObject, IconDefinition } from "../types";
+import { TXpertGraph, TXpertTeamNode } from "./xpert.model";
+import { JsonSchemaObjectType } from "./types";
+export interface IWFNMiddleware extends IWorkflowNode {
+    type: WorkflowNodeTypeEnum.MIDDLEWARE;
+    provider: string;
+    options?: Record<string, any>;
+}
+export declare function genXpertMiddlewareKey(): string;
+export type TAgentMiddlewareMeta = {
+    name: string;
+    label: I18nObject;
+    icon?: IconDefinition;
+    description?: I18nObject;
+    configSchema?: JsonSchemaObjectType;
+};
+export declare function getAgentMiddlewareNodes(graph: TXpertGraph, agentKey: string): TXpertTeamNode[];