@xpert-ai/contracts 3.9.0-beta.1

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/message-content.utils.d.ts

@@ -0,0 +1,58 @@
+import type { TMessageContent, TMessageContentComplex } from '@xpert-ai/chatkit-types';
+import { CopilotChatMessage } from './chat-message.model';
+export type TMessageJoinHint = 'none' | 'space' | 'line' | 'paragraph';
+export type TMessageAppendContext = {
+    source?: string;
+    streamId?: string;
+    joinHint?: TMessageJoinHint;
+};
+export type TAppendMessageContentOptions = TMessageAppendContext & {
+    previous?: TMessageAppendContext | null;
+};
+export type TResolveMessageAppendContextOptions = {
+    previous?: TMessageAppendContext | null;
+    incoming: string | TMessageContentComplex;
+    fallbackSource?: string;
+    fallbackStreamId?: string;
+};
+export type TResolvedMessageAppendContext = {
+    appendContext: TMessageAppendContext;
+    messageContext: TMessageAppendContext;
+};
+export type TMessageAppendContextTracker = {
+    resolve: (options: Omit<TResolveMessageAppendContextOptions, 'previous'>) => TResolvedMessageAppendContext;
+    reset: () => void;
+    current: () => TMessageAppendContext | null;
+};
+export declare function inferMessageAppendContext(content: string | TMessageContentComplex, fallbackSource?: string): TMessageAppendContext;
+export declare function resolveMessageAppendContext(options: TResolveMessageAppendContextOptions): TResolvedMessageAppendContext;
+/**
+ * Stateful helper for streaming append.
+ *
+ * It keeps the previous append context and resolves the current one, so callers
+ * can avoid passing `previous` manually for every chunk and still get stable
+ * join behavior (for example, same source + same stream -> `joinHint: 'none'`).
+ *
+ * Call `reset()` at turn/session boundaries to prevent cross-turn contamination.
+ */
+export declare function createMessageAppendContextTracker(initial?: TMessageAppendContext | null): TMessageAppendContextTracker;
+/**
+ * Append one incoming chunk into a chat message in place.
+ *
+ * Behavior:
+ * - Keeps `aiMessage` object reference stable (caller may hold this object).
+ * - Updates message properties with new references (`content`/`reasoning` arrays)
+ *   so UI change detection that relies on reference changes can react reliably.
+ * - Applies context-aware merge rules for text/reasoning/component chunks.
+ * - `previous` must be supplied by caller when same-stream join inference is needed.
+ */
+export declare function appendMessageContent(aiMessage: CopilotChatMessage, incoming: string | TMessageContentComplex, context?: TAppendMessageContentOptions): void;
+export declare function appendMessagePlainText(accumulator: string, incoming: string | TMessageContentComplex, context?: TMessageAppendContext): string;
+/**
+ * Creates a display-only content view that reassembles text chunks belonging to
+ * the same stream id. This preserves markdown continuity without changing the
+ * underlying stored/streamed message structure.
+ */
+export declare function mergeMessageContentForDisplay(content: TMessageContent | TMessageContentComplex | null | undefined): TMessageContentComplex[] | null;
+export declare function stringifyMessageContent(content: TMessageContent | TMessageContentComplex): string;
+export declare function filterMessageText(content: TMessageContent | TMessageContentComplex): string;

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

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

package/src/ai/rag-web.d.ts

@@ -0,0 +1,26 @@
+import { IntegrationEnum } from "../integration.model";
+import { TParameter, TSelectOption } from "../types";
+import { IKnowledgeDocumentPage } from "./knowledge-doc-page.model";
+export declare enum KDocumentWebTypeEnum {
+    Playwright = "playwright",
+    FireCrawl = "firecrawl",
+    Notion = "notion"
+}
+export type TRagWebOptions = {
+    url: string;
+    params?: Record<string, unknown>;
+};
+export type TKDocumentWebSchema = {
+    type: KDocumentWebTypeEnum;
+    helpUrl: string;
+    options: TParameter[];
+    /**
+     * Need to provide integration of provider
+     */
+    integrationProvider?: IntegrationEnum;
+};
+export type TRagWebResult = {
+    docs: IKnowledgeDocumentPage[];
+    duration: number;
+};
+export declare const KDocumentWebTypeOptions: TSelectOption<KDocumentWebTypeEnum>[];

package/src/ai/rag.d.ts

@@ -0,0 +1,24 @@
+export declare enum VectorTypeEnum {
+    ANALYTICDB = "analyticdb",
+    CHROMA = "chroma",
+    MILVUS = "milvus",
+    MYSCALE = "myscale",
+    PGVECTOR = "pgvector",
+    PGVECTO_RS = "pgvecto-rs",
+    QDRANT = "qdrant",
+    RELYT = "relyt",
+    TIDB_VECTOR = "tidb_vector",
+    WEAVIATE = "weaviate",
+    OPENSEARCH = "opensearch",
+    TENCENT = "tencent",
+    ORACLE = "oracle",
+    ELASTICSEARCH = "elasticsearch",
+    ELASTICSEARCH_JA = "elasticsearch-ja",
+    LINDORM = "lindorm",
+    COUCHBASE = "couchbase",
+    BAIDU = "baidu",
+    VIKINGDB = "vikingdb",
+    UPSTASH = "upstash",
+    TIDB_ON_QDRANT = "tidb_on_qdrant",
+    OCEANBASE = "oceanbase"
+}

package/src/ai/role-permissions.d.ts

@@ -0,0 +1,13 @@
+export declare enum AIPermissionsEnum {
+    /**
+     * Create or edit Knowledgebase in organization.
+     */
+    KNOWLEDGEBASE_EDIT = "KNOWLEDGEBASE_EDIT",
+    COPILOT_VIEW = "COPILOT_VIEW",
+    COPILOT_EDIT = "COPILOT_EDIT",
+    /**
+     * Create or edit Xperts in organization.
+     */
+    XPERT_EDIT = "XPERT_EDIT",
+    CHAT_VIEW = "CHAT_VIEW"
+}

package/src/ai/sandbox.d.ts

@@ -0,0 +1,8 @@
+import { I18nObject, IconDefinition } from '../types';
+export type TSandboxProviderMeta = {
+    name: I18nObject;
+    description?: I18nObject;
+    icon: IconDefinition;
+};
+export declare const SANDBOX_WORK_FOR_TYPES: readonly ["user", "project", "environment"];
+export type TSandboxWorkForType = (typeof SANDBOX_WORK_FOR_TYPES)[number];

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

@@ -0,0 +1,241 @@
+import { IBasePerTenantAndOrganizationEntityModel } from "../base-entity.model";
+import { I18nObject, IconDefinition } from "../types";
+import { JsonSchemaObjectType } from "./types";
+import { IWorkflowNode, WorkflowNodeTypeEnum } from "./xpert-workflow.model";
+import { IBasePerWorkspaceEntityModel } from "./xpert-workspace.model";
+export type SkillId = string;
+export declare const WORKSPACE_PUBLIC_SKILL_SOURCE_PROVIDER = "workspace-public";
+export declare const WORKSPACE_PUBLIC_SKILL_REPOSITORY_NAME = "Workspace Shared Skills";
+export interface ISkillRepositoryIndexStats {
+    comments?: number;
+    downloads?: number;
+    installsAllTime?: number;
+    installsCurrent?: number;
+    stars?: number;
+    versions?: number;
+}
+export interface ISkillRepositoryIndexPublisher {
+    handle?: string;
+    displayName?: string;
+    name?: string;
+    image?: string;
+    kind?: string;
+}
+export interface IShareSkillPackageInput {
+    displayName: string;
+    description: string;
+    tags?: string[];
+    license?: string;
+    version?: string;
+}
+export interface SkillMetadata {
+    name: string;
+    displayName?: I18nObject;
+    version: string;
+    summary?: I18nObject;
+    description?: I18nObject;
+    icon?: IconDefinition;
+    tags?: string[];
+    author?: {
+        name: string;
+        email?: string;
+        org?: string;
+    };
+    license?: string;
+    visibility: 'private' | 'team' | 'tenant' | 'public';
+    categories?: string[];
+    runtime?: {
+        entry?: string;
+        language?: 'js' | 'py' | 'bash';
+        permissions?: string[];
+        tools?: string[];
+    };
+    mcp?: {
+        servers?: string[];
+    };
+}
+export interface SkillResourcesIndex {
+    files: Array<{
+        path: string;
+        kind: 'script' | 'template' | 'doc' | 'asset';
+        hash: string;
+        size: number;
+    }>;
+    chunks?: Array<{
+        id: string;
+        path: string;
+        summary: string;
+        tokens: number;
+    }>;
+}
+export interface TSkillPackage {
+    metadata: SkillMetadata;
+    instructions: {
+        system?: string;
+        developer?: string;
+        examples?: Array<{
+            user: string;
+            assistant: string;
+        }>;
+        guidelines?: string[];
+    };
+    resources?: SkillResourcesIndex;
+    abac?: {
+        owners: string[];
+        readers: string[];
+        writers: string[];
+        policies?: Record<string, unknown>;
+    };
+    signatures?: string[];
+    provenance?: Record<string, unknown>;
+}
+/**
+ * Represents a repository (e.g. anthropics/skills)
+ */
+export interface ISkillRepository<O = Record<string, unknown>, C = Record<string, unknown>> extends IBasePerTenantAndOrganizationEntityModel {
+    name: string;
+    provider: string;
+    /**
+     * Provider credentials such as GitHub tokens
+     */
+    credentials?: C;
+    /**
+     * Options configured using the strategy's configSchema
+     */
+    options?: O;
+    lastSyncAt?: Date;
+    deletedAt?: Date;
+}
+/**
+ * Skill index produced by repository sync scan (one per skill directory)
+ */
+export interface ISkillRepositoryIndex extends IBasePerTenantAndOrganizationEntityModel {
+    repositoryId: string;
+    repository?: ISkillRepository;
+    skillPath: string;
+    skillId: string;
+    name?: string;
+    link?: string;
+    publisher?: ISkillRepositoryIndexPublisher;
+    description?: string;
+    license?: string;
+    tags?: string[];
+    version?: string;
+    stats?: ISkillRepositoryIndexStats;
+    resources?: Array<Record<string, unknown>>;
+    deletedAt?: Date;
+}
+export interface ISkillMarketFilterOption {
+    value: string;
+    label: string;
+    description?: string;
+}
+export interface ISkillMarketFilterGroup {
+    label: string;
+    options: ISkillMarketFilterOption[];
+}
+export interface ISkillMarketFilterGroups {
+    roles: ISkillMarketFilterGroup;
+    appTypes: ISkillMarketFilterGroup;
+    hot: ISkillMarketFilterGroup;
+}
+export interface ISkillMarketFeaturedRef {
+    provider: string;
+    repositoryName: string;
+    skillId: string;
+    badge?: string;
+    title?: string;
+    description?: string;
+    avatar?: IconDefinition;
+}
+export interface ISkillMarketFeaturedSkill extends ISkillMarketFeaturedRef {
+    skill: ISkillRepositoryIndex;
+}
+export interface ISkillMarketConfig {
+    featured: ISkillMarketFeaturedSkill[];
+    filters: ISkillMarketFilterGroups;
+}
+/**
+ * Installed skill package record (skill.yaml)
+ */
+export interface ISkillPackage extends IBasePerWorkspaceEntityModel, TSkillPackage {
+    skillIndexId?: SkillId;
+    skillIndex?: ISkillRepositoryIndex;
+    name?: string;
+    visibility: 'private' | 'team' | 'tenant';
+    packagePath?: string;
+    sharedSkillId?: string;
+    sharedPackagePath?: string;
+}
+/**
+ * Skill version (multiple versions can coexist per skill)
+ */
+export interface ISkillVersion extends IBasePerWorkspaceEntityModel {
+    packageId: string;
+    version: string;
+    metadata: SkillMetadata;
+    instructions: TSkillPackage['instructions'];
+    installedAt?: string;
+}
+/**
+ * Skill resource file record (scripts/templates/assets)
+ */
+export interface ISkillResource extends IBasePerWorkspaceEntityModel {
+    versionId: string;
+    path: string;
+    type: 'script' | 'template' | 'asset' | 'doc';
+    hash?: string;
+    size?: number;
+    meta?: Record<string, unknown>;
+}
+/**
+ * Tenant/organization/team/user installation record
+ */
+export interface ISkillInstallation extends IBasePerTenantAndOrganizationEntityModel {
+    versionId: string;
+    installedBy: string;
+    visibility: 'private' | 'team' | 'tenant';
+    targetScope?: string;
+    status: 'pending' | 'installed' | 'failed';
+}
+/**
+ * Detailed logs during skill installation
+ */
+export interface ISkillInstallLog extends IBasePerTenantAndOrganizationEntityModel {
+    installationId: string;
+    level: 'info' | 'warn' | 'error';
+    message: string;
+    timestamp: string;
+}
+/**
+ * Runtime audit log for skills
+ */
+export interface ISkillAuditLog extends IBasePerTenantAndOrganizationEntityModel {
+    skillId: string;
+    versionId: string;
+    sessionId: string;
+    eventType: string;
+    metadata: Record<string, unknown>;
+}
+export type TSkillSourceMeta = {
+    /**
+     * Provider name, e.g. github / git / zip / marketplace
+     */
+    name: string;
+    label: I18nObject;
+    icon?: IconDefinition;
+    description?: I18nObject;
+    /**
+     * Optional configuration schema for frontend forms
+     */
+    configSchema?: JsonSchemaObjectType;
+    /**
+     * Credential schema for source authentication
+     */
+    credentialSchema?: JsonSchemaObjectType;
+};
+export interface IWFNSkill extends IWorkflowNode {
+    type: WorkflowNodeTypeEnum.SKILL;
+    skills?: string[];
+}
+export declare function genXpertSkillKey(): string;

package/src/ai/types.d.ts

@@ -0,0 +1,77 @@
+import { JsonSchema7TypeUnion } from "zod-to-json-schema";
+import { I18nObject, TSelectOption } from "../types";
+import { TXpertAttachmentType, XpertParameterTypeEnum } from "./xpert.model";
+export type TErrorHandling = {
+    type?: null | 'defaultValue' | 'failBranch';
+    defaultValue?: {
+        content?: string;
+    } & Record<string, any>;
+    failBranch?: string;
+};
+export declare enum ApiAuthType {
+    /**
+     * Enum class for api provider auth type.
+     */
+    NONE = "none",
+    API_KEY = "api_key",
+    BASIC = "basic"
+}
+/**
+ * Reference variable (parameter)
+ */
+export type TXpertRefParameter = {
+    type?: XpertParameterTypeEnum;
+    name: string;
+    optional?: boolean;
+    /**
+     * Referencing other variable
+     */
+    variable?: string;
+};
+/**
+ * Embedding status of an entity, such as an bi indicator or kb document.
+ */
+export declare enum EmbeddingStatusEnum {
+    PROCESSING = "processing",
+    SUCCESS = "success",
+    FAILED = "failed",
+    REQUIRED = "required"
+}
+export declare const Attachment_Type_Options: TSelectOption<string, TXpertAttachmentType>[];
+type JsonSchema7Meta = {
+    title?: I18nObject;
+    default?: any;
+    description?: I18nObject;
+    markdownDescription?: I18nObject;
+    /**
+     * UI schema extensions
+     */
+    'x-ui'?: {
+        /**
+         * UI component variant, or custom component name
+         */
+        component?: 'textarea' | 'select' | 'radio' | 'checkbox' | 'switch' | 'password' | string;
+        /**
+         * UI component display span (for grid layouts)
+         */
+        span?: number;
+        /**
+         * Additional inputs for the Custom UI component
+         */
+        inputs?: Record<string, unknown>;
+        /**
+         * Whether this component supports selecting LangGraph state variables
+         */
+        variable?: boolean;
+        enumLabels?: Record<string, I18nObject | string>;
+        styles?: Record<string, string>;
+    };
+};
+export type JsonSchemaObjectType = {
+    type: "object";
+    properties: Record<string, JsonSchema7Type>;
+    additionalProperties?: boolean | JsonSchema7Type;
+    required?: string[];
+};
+type JsonSchema7Type = (JsonSchema7TypeUnion | JsonSchemaObjectType) & JsonSchema7Meta;
+export {};