@metad/contracts 3.6.2 → 3.6.7

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,40 @@
+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'

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

@@ -0,0 +1,123 @@
+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
+
+  // tokens
+  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 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
+}