@metad/contracts 3.6.0 → 3.6.1

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

@@ -0,0 +1,24 @@
+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 interface ICopilotUser extends IBasePerTenantAndOrganizationEntityModel, TCopilotTokenUsage {
+  orgId?: string
+  org?: IOrganization
+  copilotId?: string
+  copilot?: ICopilot
+  userId?: string
+  user?: IUser
+  // Associated AI Model provider
+  provider?: AiProvider | string
+  model?: string
+
+  // Total tokens used historically
+  tokenTotalUsed?: number
+  priceTotalUsed?: number
+}

package/src/ai/copilot.model.ts

@@ -0,0 +1,47 @@
+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
+
+  // Temporary properties
+  usage?: TCopilotTokenUsage
+}
+
+/**
+ * The order of priority is: `Embedding`, `Secondary`, `Primary`
+ */
+export enum AiProviderRole {
+  Primary = 'primary',
+  Secondary = 'secondary',
+  Embedding = 'embedding',
+  Reasoning = 'reasoning'
+}
+
+export type TCopilotTokenUsage = {
+  // Token limit for the current period
+  tokenLimit?: number
+  priceLimit?: number
+  // Tokens used in the current period
+  tokenUsed?: number
+  priceUsed?: number
+
+  currency?: string
+}

package/src/ai/{environment.model.d.ts → environment.model.ts}

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

package/src/ai/feature.model.ts

@@ -0,0 +1,6 @@
+export enum AiFeatureEnum {
+  FEATURE_COPILOT = 'FEATURE_COPILOT',
+  FEATURE_COPILOT_KNOWLEDGEBASE = 'FEATURE_COPILOT_KNOWLEDGEBASE',
+  FEATURE_COPILOT_CHAT = 'FEATURE_COPILOT_CHAT',
+  FEATURE_XPERT = 'FEATURE_XPERT',
+}

package/src/ai/index.ts

@@ -0,0 +1,39 @@
+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.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'

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

@@ -0,0 +1,120 @@
+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 // remote url
+  filePath: string // local path
+}
+
+export interface IDocChunkMetadata {
+  chunkId: string
+  parentId?: string | null
+  children?: DocumentInterface<IDocChunkMetadata>[]
+
+  knowledgeId?: string
+  chunkIndex?: number // Index within the document or parent chunk
+  enabled?: boolean
+
+  /**
+   * Default to 'text'. Indicates the original media type of the chunk.
+   * @default text
+   */
+  mediaType?: 'text' | 'image' | 'video' | 'audio' // Media type of the chunk
+  /**
+   * 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
+
+  [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 function buildChunkTree<Metadata extends IDocChunkMetadata = IDocChunkMetadata>(
+  documents: DocumentInterface<Metadata>[]
+): DocumentInterface<Metadata>[] {
+  if (!documents || documents.length === 0) return []
+  
+  // Step 1. Build a lookup map for quick access by chunkId
+  const map = new Map<string, DocumentInterface<Metadata>>()
+  for (const doc of documents) {
+    if (doc.metadata?.chunkId) {
+      map.set(doc.metadata.chunkId, { ...doc, metadata: { ...doc.metadata, children: [] } })
+    }
+  }
+
+  // Step 2. Organize nodes into tree
+  const roots: DocumentInterface<Metadata>[] = []
+
+  for (const doc of map.values()) {
+    const parentId = doc.metadata.parentId
+    if (parentId && map.has(parentId)) {
+      const parent = map.get(parentId)
+      parent.metadata.children = parent.metadata.children || []
+      parent.metadata.children.push(doc)
+    } else {
+      roots.push(doc)
+    }
+  }
+  
+  return roots
+}
+
+/**
+ * Find all leaf nodes (nodes without children).
+ * 
+ * @param roots 
+ * @returns 
+ */
+export function collectTreeLeaves(roots: IKnowledgeDocumentChunk[]) {
+  const leaves: IKnowledgeDocumentChunk[] = []
+
+  const collectLeaves = (node: IKnowledgeDocumentChunk) => {
+    const children = node.metadata.children
+    if (!children || children.length === 0) {
+      leaves.push(node)
+    } else {
+      for (const child of children) {
+        collectLeaves(child as IKnowledgeDocumentChunk)
+      }
+    }
+  }
+
+  for (const root of roots) {
+    collectLeaves(root)
+  }
+
+  return leaves
+}

package/src/ai/knowledge-doc-chunk.spec.ts

@@ -0,0 +1,47 @@
+import { DocumentInterface } from "@langchain/core/documents"
+import { buildChunkTree, IDocChunkMetadata } from "./knowledge-doc-chunk.model"
+
+describe("buildChunkTree", () => {
+  function makeDoc(
+    chunkId: string,
+    parentId?: string,
+    extra?: Partial<IDocChunkMetadata>
+  ): DocumentInterface<IDocChunkMetadata> {
+    return {
+      pageContent: `Content ${chunkId}`,
+      metadata: {
+        chunkId,
+        parentId,
+        ...extra,
+      } as IDocChunkMetadata,
+    }
+  }
+
+  it("does not mutate input documents", () => {
+    const chunks: DocumentInterface<IDocChunkMetadata>[] = [
+      {
+        pageContent: 'Parent chunk',
+        metadata: { chunkId: '1' },
+      },
+      {
+        pageContent: 'Parent chunk',
+        metadata: { chunkId: '2' },
+      },
+      {
+        pageContent: 'Child 1',
+        metadata: { chunkId: '1-1', parentId: '1', type: 'child' },
+      },
+      {
+        pageContent: 'Child 2',
+        metadata: { chunkId: '1-2', parentId: '1', type: 'child' },
+      },
+      {
+        pageContent: 'Grandchild of 1-2',
+        metadata: { chunkId: '1-2-1', parentId: '1-2', type: 'child' },
+      },
+    ]
+
+    const tree = buildChunkTree(chunks)
+    console.log('Tree:', JSON.stringify(tree, null, 2))
+  })
+})

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

@@ -0,0 +1,20 @@
+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.ts

@@ -0,0 +1,252 @@
+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 } 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'
+
+
+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 enum DocumentTypeEnum {
+  /**
+   * Folder, parent of other documents
+   */
+  FOLDER = 'folder',
+
+  /**
+   * Local files
+   * @deprecated use DocumentSourceProviderCategoryEnum local file type instead
+   */
+  FILE = 'file'
+}
+export const KDocumentSourceType = {
+  ...DocumentSourceProviderCategoryEnum,
+  ...DocumentTypeEnum
+}
+
+/**
+ * Document type category, determine how to process the document.
+ */
+export enum KBDocumentCategoryEnum {
+  Text = 'text',
+  Image = 'image',
+  Audio = 'audio',
+  Video = 'video',
+  Sheet = 'sheet',
+  Other = 'other'
+}
+
+export 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 = Metadata> extends TKnowledgeDocument, IBasePerTenantAndOrganizationEntityModel {
+  parent?: IKnowledgeDocument | null
+  children?: IKnowledgeDocument[]
+  knowledgebase?: IKnowledgebase
+
+  draft?: TKnowledgeDocument
+  
+  metadata?: T
+}
+
+// export interface IDocumentChunk<Metadata = DocumentMetadata> {
+//   id: string
+//   pageContent: string
+//   metadata: Metadata & {
+//     knowledgeId?: string
+//   }
+//   collection_id: string
+// }
+
+export type Metadata = any
+
+export interface IKnowledgeDocumentCreateInput
+	extends IKnowledgeDocument, IBasePerTenantAndOrganizationEntityModel {}
+
+export interface IKnowledgeDocumentUpdateInput
+	extends Partial<IKnowledgeDocumentCreateInput> {
+	id?: string;
+}
+
+export interface IKnowledgeDocumentFindInput
+	extends IBasePerTenantAndOrganizationEntityModel,
+		IKnowledgeDocument {}
+
+
+export function isDocumentSheet(type: string): boolean {
+  return ['csv', 'xls', 'xlsx', 'ods', 'vnd.openxmlformats-officedocument.spreadsheetml.sheet'].includes(type)
+}
+
+export function isImageType(type: string): boolean {
+  return ['jpg', 'jpeg', 'png', 'gif', 'bmp', 'tiff', 'svg', 'webp'].includes(type)
+}
+
+export function isVideoType(type: string): boolean {
+  return ['mp4', 'avi', 'mov', 'wmv', 'flv', 'mkv', 'webm'].includes(type)
+}
+
+export function isAudioType(type: string): boolean {
+  return ['mp3', 'wav', 'aac', 'flac', 'ogg', 'm4a'].includes(type)
+}
+
+export function classificateDocumentCategory(entity: Partial<IKnowledgeDocument>): KBDocumentCategoryEnum {
+  return isDocumentSheet(entity.type) ? KBDocumentCategoryEnum.Sheet : 
+									isImageType(entity.type) ? KBDocumentCategoryEnum.Image : 
+									isVideoType(entity.type) ? KBDocumentCategoryEnum.Video :
+									isAudioType(entity.type) ? KBDocumentCategoryEnum.Audio :
+									KBDocumentCategoryEnum.Text
+}