@xpert-ai/plugin-sdk 3.6.0 → 3.6.2

package/src/lib/data/datasource/strategy.interface.d.ts

@@ -0,0 +1,19 @@
+import { AdapterBaseOptions, DBQueryRunner, DBQueryRunnerType } from "./types";
+export interface IDataSourceStrategy<TOptions extends AdapterBaseOptions = AdapterBaseOptions> {
+    readonly type: string;
+    readonly name: string;
+    readonly description?: string;
+    /**
+     * Create a query runner for the given data source options.
+     */
+    create(options: TOptions): Promise<DBQueryRunner> | DBQueryRunner;
+    /**
+     * Optional configuration schema description for UI generation.
+     */
+    configurationSchema?(): Promise<Record<string, unknown>> | Record<string, unknown>;
+    /**
+     * Cleanup hook invoked when a runner is no longer needed.
+     */
+    teardown?(runner: DBQueryRunner): Promise<void> | void;
+    getClassType(): DBQueryRunnerType;
+}

package/src/lib/data/datasource/strategy.registry.d.ts

@@ -0,0 +1,7 @@
+import { DiscoveryService, Reflector } from '@nestjs/core';
+import { BaseStrategyRegistry } from '../../strategy';
+import { IDataSourceStrategy } from './strategy.interface';
+import { AdapterBaseOptions } from './types';
+export declare class DataSourceStrategyRegistry<TOptions extends AdapterBaseOptions = any> extends BaseStrategyRegistry<IDataSourceStrategy<TOptions>> {
+    constructor(discoveryService: DiscoveryService, reflector: Reflector);
+}

package/src/lib/data/datasource/types.d.ts

@@ -0,0 +1,255 @@
+/// <reference types="node" />
+/// <reference types="node" />
+/// <reference types="node" />
+import * as _axios from 'axios';
+import { Readable } from 'stream';
+import { IColumnDef, IDSSchema, IDSTable } from '@metad/contracts';
+export { IColumnDef, IDSSchema, IDSTable } from '@metad/contracts';
+/**
+ * The base options for DB adapters
+ */
+export interface AdapterBaseOptions {
+    /**
+     * Ref to debug in `createConnection` of `mysql`
+     */
+    debug?: boolean;
+    /**
+     * Ref to trace in `createConnection` of `mysql`
+     */
+    trace?: boolean;
+    host: string;
+    port: number;
+    username: string;
+    password: string;
+}
+export declare enum DBSyntaxEnum {
+    SQL = "sql",
+    MDX = "mdx"
+}
+export declare enum DBProtocolEnum {
+    SQL = "sql",
+    XMLA = "xmla"
+}
+/**
+ * Options of single query
+ */
+export interface QueryOptions {
+    catalog?: string;
+    headers?: Record<string, string>;
+}
+export interface QueryResult<T = unknown> {
+    status: 'OK' | 'ERROR';
+    data?: Array<T>;
+    columns?: Array<IColumnDef>;
+    stats?: any;
+    error?: string;
+}
+/**
+ * Duties:
+ * - Convert error messages into a unified format
+ * - Connect different types of data sources
+ */
+export interface DBQueryRunner {
+    type: string;
+    name: string;
+    syntax: DBSyntaxEnum;
+    protocol: DBProtocolEnum;
+    host: string;
+    port: number | string;
+    jdbcDriver: string;
+    configurationSchema: Record<string, unknown>;
+    jdbcUrl(schema?: string): string;
+    /**
+     * Execute a sql query
+     *
+     * @param sql
+     */
+    run(sql: string): Promise<any>;
+    /**
+     * Execute a sql query with options
+     *
+     * @param query
+     * @param options
+     */
+    runQuery(query: string, options?: QueryOptions): Promise<QueryResult | any>;
+    /**
+     * Get catalog (schema or database) list in data source
+     */
+    getCatalogs(): Promise<IDSSchema[]>;
+    /**
+     * Get schema of table in catalog (schema or database)
+     *
+     * @param catalog
+     * @param tableName
+     */
+    getSchema(catalog?: string, tableName?: string): Promise<IDSSchema[]>;
+    /**
+     * Describe a sql query result schema
+     *
+     * @param catalog
+     * @param statement
+     */
+    describe(catalog: string, statement: string): Promise<{
+        columns?: IDSTable['columns'];
+    }>;
+    /**
+     * Ping the db
+     */
+    ping(): Promise<void>;
+    /**
+     * Create a new catalog (schema) in database
+     *
+     * @param catalog
+     */
+    createCatalog?(catalog: string): Promise<void>;
+    /**
+     * Create or append table data
+     *
+     * @param params
+     * @param options
+     */
+    import(params: CreationTable, options?: QueryOptions): Promise<any>;
+    /**
+     * Drop a table
+     *
+     * @param name Table name
+     * @param options
+     */
+    dropTable(name: string, options?: QueryOptions): Promise<void>;
+    /**
+     * Teardown all resources:
+     * - close connection
+     *
+     */
+    teardown(): Promise<void>;
+}
+export type DBQueryRunnerType = new (options?: AdapterBaseOptions, ...args: unknown[]) => DBQueryRunner;
+export interface ColumnDef {
+    /**
+     * Key of data object
+     */
+    name: string;
+    /**
+     * Name of table column
+     */
+    fieldName: string;
+    /**
+     * Object value type, convert to db type
+     */
+    type: string;
+    /**
+     * Is primary key column
+     */
+    isKey: boolean;
+    /**
+     * length of type for column: varchar, decimal ...
+     */
+    length?: number;
+    /**
+     * fraction of type for decimal
+     */
+    fraction?: number;
+}
+export interface CreationTable {
+    catalog?: string;
+    table?: string;
+    name: string;
+    columns: ColumnDef[];
+    data?: any[];
+    file?: File;
+    mergeType?: 'APPEND' | 'DELETE' | 'MERGE';
+    format?: 'csv' | 'json' | 'parquet' | 'orc' | 'data';
+    columnSeparator?: string;
+    withHeader?: number;
+}
+export declare abstract class BaseQueryRunner<T extends AdapterBaseOptions = AdapterBaseOptions> implements DBQueryRunner {
+    type: string;
+    name: string;
+    syntax: DBSyntaxEnum;
+    protocol: DBProtocolEnum;
+    jdbcDriver: string;
+    abstract get host(): string;
+    abstract get port(): number | string;
+    options: T;
+    jdbcUrl(schema?: string): string;
+    get configurationSchema(): any;
+    constructor(options?: T);
+    run(sql: string): Promise<any>;
+    abstract runQuery(query: string, options?: QueryOptions): Promise<QueryResult>;
+    abstract getCatalogs(): Promise<IDSSchema[]>;
+    abstract getSchema(catalog?: string, tableName?: string): Promise<IDSSchema[]>;
+    describe(catalog: string, statement: string): Promise<{
+        columns?: IDSTable['columns'];
+    }>;
+    abstract ping(): Promise<void>;
+    import({ name, columns, data }: {
+        name: any;
+        columns: any;
+        data: any;
+    }, options?: {
+        catalog?: string;
+    }): Promise<void>;
+    dropTable(name: string, options?: any): Promise<void>;
+    abstract teardown(): Promise<void>;
+}
+export interface HttpAdapterOptions extends AdapterBaseOptions {
+    url?: string;
+}
+export declare abstract class BaseHTTPQueryRunner<T extends HttpAdapterOptions = HttpAdapterOptions> extends BaseQueryRunner<T> {
+    get url(): string;
+    get host(): string;
+    get port(): number | string;
+    get configurationSchema(): {};
+    get(): Promise<_axios.AxiosResponse<any, any>>;
+    post(data: any, options?: any): Promise<_axios.AxiosResponse<any, any>>;
+}
+/**
+ * Adapter options for sql db
+ */
+export interface SQLAdapterOptions extends AdapterBaseOptions {
+    url?: string;
+    /**
+     * Database name, used as catalog
+     */
+    catalog?: string;
+    use_ssl?: boolean;
+    ssl_cacert?: string;
+    version?: number;
+}
+export declare abstract class BaseSQLQueryRunner<T extends SQLAdapterOptions = SQLAdapterOptions> extends BaseQueryRunner<T> {
+    syntax: DBSyntaxEnum;
+    protocol: DBProtocolEnum;
+    get host(): string;
+    get port(): string | number;
+    abstract createCatalog?(catalog: string): Promise<void>;
+    ping(): Promise<void>;
+}
+export interface File {
+    /** Name of the form field associated with this file. */
+    fieldname: string;
+    /** Name of the file on the uploader's computer. */
+    originalname: string;
+    /**
+     * Value of the `Content-Transfer-Encoding` header for this file.
+     * @deprecated since July 2015
+     * @see RFC 7578, Section 4.7
+     */
+    encoding: string;
+    /** Value of the `Content-Type` header for this file. */
+    mimetype: string;
+    /** Size of the file in bytes. */
+    size: number;
+    /**
+     * A readable stream of this file. Only available to the `_handleFile`
+     * callback for custom `StorageEngine`s.
+     */
+    stream: Readable;
+    /** `DiskStorage` only: Directory to which this file has been uploaded. */
+    destination: string;
+    /** `DiskStorage` only: Name of this file within `destination`. */
+    filename: string;
+    /** `DiskStorage` only: Full path to the uploaded file. */
+    path: string;
+    /** `MemoryStorage` only: A Buffer containing the entire file. */
+    buffer: Buffer;
+}

package/src/lib/data/index.d.ts

@@ -0,0 +1 @@
+export * from './datasource/index';

package/src/lib/integration/index.d.ts

@@ -0,0 +1,3 @@
+export * from './strategy.decorator';
+export * from './strategy.interface';
+export * from './strategy.registry';

package/src/lib/integration/strategy.decorator.d.ts

@@ -0,0 +1,2 @@
+export declare const INTEGRATION_STRATEGY = "INTEGRATION_STRATEGY";
+export declare const IntegrationStrategyKey: (provider: string) => import("@nestjs/common").CustomDecorator<string>;

package/src/lib/integration/strategy.interface.d.ts

@@ -0,0 +1,9 @@
+import { IIntegration, TIntegrationProvider } from '@metad/contracts';
+export type TIntegrationStrategyParams = {
+    query: string;
+};
+export interface IntegrationStrategy<T = unknown> {
+    meta: TIntegrationProvider;
+    execute(integration: IIntegration<T>, payload: TIntegrationStrategyParams): Promise<any>;
+    validateConfig?(config: T): Promise<void>;
+}

package/src/lib/integration/strategy.registry.d.ts

@@ -0,0 +1,6 @@
+import { DiscoveryService, Reflector } from '@nestjs/core';
+import { BaseStrategyRegistry } from '../strategy';
+import { IntegrationStrategy } from './strategy.interface';
+export declare class IntegrationStrategyRegistry extends BaseStrategyRegistry<IntegrationStrategy> {
+    constructor(discoveryService: DiscoveryService, reflector: Reflector);
+}

package/src/lib/logger.d.ts

@@ -0,0 +1,2 @@
+import type { PluginLogger } from './types';
+export declare function createPluginLogger(scope: string, baseMeta?: Record<string, any>): PluginLogger;

package/src/lib/plugin-metadata.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Metadata keys used in plugins for defining various aspects like entities, subscribers, and configurations.
+ */
+export declare const PLUGIN_METADATA: {
+    /**
+     * Key representing the entities registered within the plugin.
+     */
+    readonly ENTITIES: "entities";
+    /**
+     * Key representing event subscribers within the plugin.
+     */
+    readonly SUBSCRIBERS: "subscribers";
+};
+/**
+ * Type definition for valid plugin metadata keys.
+ */
+export type PluginMetadataKey = (typeof PLUGIN_METADATA)[keyof typeof PLUGIN_METADATA];

package/src/lib/plugin.d.ts

@@ -0,0 +1,8 @@
+import { PluginMetadata } from './plugin.interface';
+/**
+ * Decorator function for extending NestJS features with additional metadata.
+ *
+ * @param pluginMetadata Metadata to be applied to the target class.
+ * @returns Class decorator function.
+ */
+export declare function XpertServerPlugin(pluginMetadata: PluginMetadata): ClassDecorator;

package/src/lib/{plugin.hook.ts → plugin.hook.d.ts}

@@ -8,7 +8,6 @@ export interface IOnPluginBootstrap {
      */
     onPluginBootstrap(): void | Promise<void>;
 }
-
 /**
  * Interface for plugins with a destroy lifecycle method.
  */
@@ -19,7 +18,6 @@ export interface IOnPluginDestroy {
      */
     onPluginDestroy(): void | Promise<void>;
 }
-
 /**
  * Interface for plugins supporting basic seed operations.
  */
@@ -30,7 +28,6 @@ export interface IOnPluginWithBasicSeed {
      */
     onPluginBasicSeed(): void | Promise<void>;
 }
-
 /**
  * Interface for plugins supporting default seed operations.
  */
@@ -41,7 +38,6 @@ export interface IOnPluginWithDefaultSeed {
      */
     onPluginDefaultSeed(): void | Promise<void>;
 }
-
 /**
  * Interface for plugins supporting random seed operations.
  */

package/src/lib/plugin.interface.d.ts

@@ -0,0 +1,59 @@
+import { ModuleMetadata, Type } from '@nestjs/common';
+/**
+ * Metadata definition for a plugin in NestJS.
+ */
+export interface PluginMetadata extends ModuleMetadata {
+    /**
+     * List of entities injected by the plugin.
+     */
+    entities?: Array<Type<any>> | (() => Array<Type<any>>);
+    /**
+     * List of subscribers injected by the plugin.
+     */
+    subscribers?: Array<Type<any>> | (() => Array<Type<any>>);
+}
+/**
+ * Interface for plugins with a bootstrap lifecycle method.
+ */
+export interface IOnPluginBootstrap {
+    /**
+     * Called when the plugin is being initialized.
+     * @returns A void or a Promise representing the completion of the operation.
+     */
+    onPluginBootstrap(): void | Promise<void>;
+}
+/**
+ * Interface for plugins with a destroy lifecycle method.
+ */
+export interface IOnPluginDestroy {
+    /**
+     * Called when the plugin is being destroyed.
+     * @returns A void or a Promise representing the completion of the operation.
+     */
+    onPluginDestroy(): void | Promise<void>;
+}
+/**
+ * Interface for plugins supporting various seed operations.
+ */
+export interface IOnPluginSeedable {
+    /**
+     * Invoked when seeding basic plugin data.
+     * @returns A void or a Promise representing the completion of the operation.
+     */
+    onPluginBasicSeed?(): void | Promise<void>;
+    /**
+     * Invoked when seeding default plugin data.
+     * @returns A void or a Promise representing the completion of the operation.
+     */
+    onPluginDefaultSeed?(): void | Promise<void>;
+    /**
+     * Invoked when seeding random plugin data.
+     * @returns A void or a Promise representing the completion of the operation.
+     */
+    onPluginRandomSeed?(): void | Promise<void>;
+}
+/**
+ * Represents the combined lifecycle methods for a plugin.
+ * This type combines interfaces for initializing and destroying a plugin.
+ */
+export type PluginLifecycleMethods = IOnPluginBootstrap & IOnPluginDestroy & IOnPluginSeedable;

package/src/lib/rag/image/index.d.ts

@@ -0,0 +1,3 @@
+export * from './strategy.decorator';
+export * from './strategy.interface';
+export * from './strategy.registry';

package/src/lib/rag/image/strategy.decorator.d.ts

@@ -0,0 +1,5 @@
+export declare const IMAGE_UNDERSTANDING_STRATEGY = "IMAGE_UNDERSTANDING_STRATEGY";
+/**
+ * Decorator to mark a provider as an Image Understanding Strategy
+ */
+export declare const ImageUnderstandingStrategy: (provider: string) => import("@nestjs/common").CustomDecorator<string>;

package/src/lib/rag/image/strategy.interface.d.ts

@@ -0,0 +1,31 @@
+import { DocumentInterface } from '@langchain/core/documents';
+import { BaseChatModel } from '@langchain/core/language_models/chat_models';
+import { IDocumentUnderstandingProvider, IKnowledgeDocument } from '@metad/contracts';
+import { Permissions, XpFileSystem } from '../../core/index';
+import { ChunkMetadata } from '../types';
+export type TImageUnderstandingConfig = {
+    stage: 'test' | 'prod';
+    visionModel: BaseChatModel;
+    permissions?: {
+        fileSystem?: XpFileSystem;
+    };
+};
+export type TImageUnderstandingResult = {
+    chunks: DocumentInterface<Partial<ChunkMetadata>>[];
+    metadata: any;
+};
+export interface IImageUnderstandingStrategy<TConfig extends TImageUnderstandingConfig = TImageUnderstandingConfig> {
+    readonly permissions: Permissions;
+    /**
+     * Metadata about this strategy
+     */
+    readonly meta: IDocumentUnderstandingProvider;
+    /**
+     * Validate the configuration
+     */
+    validateConfig(config: TConfig): Promise<void>;
+    /**
+     * Understand image files (e.g., OCR, VLM, Chart Parsing)
+     */
+    understandImages(doc: IKnowledgeDocument<ChunkMetadata>, config: TConfig): Promise<TImageUnderstandingResult>;
+}

package/src/lib/rag/image/strategy.registry.d.ts

@@ -0,0 +1,6 @@
+import { DiscoveryService, Reflector } from '@nestjs/core';
+import { BaseStrategyRegistry } from '../../strategy';
+import { IImageUnderstandingStrategy, TImageUnderstandingConfig } from './strategy.interface';
+export declare class ImageUnderstandingRegistry<TConfig extends TImageUnderstandingConfig = TImageUnderstandingConfig> extends BaseStrategyRegistry<IImageUnderstandingStrategy<TConfig>> {
+    constructor(discoveryService: DiscoveryService, reflector: Reflector);
+}

package/src/lib/rag/index.d.ts

@@ -0,0 +1,7 @@
+export * from './textsplitter/index';
+export * from './source/index';
+export * from './transformer/index';
+export * from './retriever/index';
+export * from './types';
+export * from './image/index';
+export * from './knowledge/index';

package/src/lib/rag/knowledge/index.d.ts

@@ -0,0 +1,3 @@
+export * from './knowledge-strategy.decorator';
+export * from './knowledge-strategy.interface';
+export * from './knowledge-strategy.registry';

package/src/lib/rag/knowledge/knowledge-strategy.decorator.d.ts

@@ -0,0 +1,2 @@
+export declare const KNOWLEDGE_STRATEGY = "KNOWLEDGE_STRATEGY";
+export declare const KnowledgeStrategyKey: (provider: string) => import("@nestjs/common").CustomDecorator<string>;

package/src/lib/rag/knowledge/knowledge-strategy.interface.d.ts

@@ -0,0 +1,15 @@
+import { IIntegration } from '@metad/contracts';
+import { Document } from '@langchain/core/documents';
+export type TKnowledgeStrategyParams = {
+    query: string;
+    k: number;
+    filter: Record<string, any>;
+    options: {
+        knowledgebaseId: string;
+    };
+};
+export interface KnowledgeStrategy {
+    execute(integration: IIntegration, payload: TKnowledgeStrategyParams): Promise<{
+        chunks: [Document, number][];
+    }>;
+}

package/src/lib/rag/knowledge/knowledge-strategy.registry.d.ts

@@ -0,0 +1,6 @@
+import { DiscoveryService, Reflector } from '@nestjs/core';
+import { BaseStrategyRegistry } from '../../strategy';
+import { KnowledgeStrategy } from './knowledge-strategy.interface';
+export declare class KnowledgeStrategyRegistry extends BaseStrategyRegistry<KnowledgeStrategy> {
+    constructor(discoveryService: DiscoveryService, reflector: Reflector);
+}

package/src/lib/rag/retriever/index.d.ts

@@ -0,0 +1,3 @@
+export * from './strategy.decorator';
+export * from './strategy.interface';
+export * from './strategy.registry';

package/src/lib/rag/retriever/strategy.decorator.d.ts

@@ -0,0 +1,5 @@
+export declare const RETRIEVER_STRATEGY = "RETRIEVER_STRATEGY";
+/**
+ * Decorator to mark a provider as a Retriever Strategy
+ */
+export declare const RetrieverStrategy: (provider: string) => import("@nestjs/common").CustomDecorator<string>;

package/src/lib/rag/retriever/strategy.interface.d.ts

@@ -0,0 +1,30 @@
+import { VectorStore } from '@langchain/core/vectorstores';
+import { I18nObject } from '@metad/contracts';
+import { Document } from '@langchain/core/documents';
+export type TRetrieverConfig = {
+    vectorStore: VectorStore;
+};
+export interface IRetrieverStrategy<TConfig extends TRetrieverConfig = TRetrieverConfig> {
+    /**
+     * Metadata about this retriever
+     */
+    readonly meta: {
+        name: string;
+        label: I18nObject;
+        configSchema: any;
+        icon: {
+            svg?: string;
+            color?: string;
+        };
+    };
+    /**
+     * Validate the configuration
+     */
+    validateConfig(config: TConfig): Promise<void>;
+    /**
+     * Retrieve relevant documents for a given query
+     */
+    retrieve(query: string, options?: TConfig): Promise<{
+        documents: Document[];
+    }>;
+}

package/src/lib/rag/retriever/strategy.registry.d.ts

@@ -0,0 +1,6 @@
+import { DiscoveryService, Reflector } from '@nestjs/core';
+import { BaseStrategyRegistry } from '../../strategy';
+import { IRetrieverStrategy } from './strategy.interface';
+export declare class RetrieverRegistry extends BaseStrategyRegistry<IRetrieverStrategy> {
+    constructor(discoveryService: DiscoveryService, reflector: Reflector);
+}

package/src/lib/rag/source/index.d.ts

@@ -0,0 +1,3 @@
+export * from './strategy.decorator';
+export * from './strategy.interface';
+export * from './strategy.registry';

package/src/lib/rag/source/strategy.decorator.d.ts

@@ -0,0 +1,5 @@
+export declare const DOCUMENT_SOURCE_STRATEGY = "DOCUMENT_SOURCE_STRATEGY";
+/**
+ * Decorator to mark a provider as a Document Source Strategy
+ */
+export declare const DocumentSourceStrategy: (provider: string) => import("@nestjs/common").CustomDecorator<string>;

package/src/lib/rag/source/strategy.interface.d.ts

@@ -0,0 +1,36 @@
+import { IDocumentSourceProvider, IIntegration } from '@metad/contracts';
+import { Document } from '@langchain/core/documents';
+import { Permissions } from '../../core';
+export interface IDocumentSourceStrategy<TConfig = any> {
+    readonly permissions: Permissions;
+    /**
+     * Metadata about this document source
+     */
+    readonly meta: IDocumentSourceProvider;
+    /**
+     * Validate the configuration
+     */
+    validateConfig(config: TConfig): Promise<void>;
+    /**
+     * Test the connection to the source
+     *
+     * @param config
+     */
+    test(config: TConfig): Promise<any>;
+    /**
+     * Load documents from the source
+     */
+    loadDocuments(config: TConfig, context?: {
+        integration?: IIntegration;
+    }): Promise<Document[]>;
+    /**
+     * Load a single document by its ID
+     *
+     * @deprecated Planning
+     * @param documentId
+     * @param context
+     */
+    loadDocument?(document: Document, context: {
+        integration?: IIntegration;
+    }): Promise<Document>;
+}

package/src/lib/rag/source/strategy.registry.d.ts

@@ -0,0 +1,6 @@
+import { DiscoveryService, Reflector } from '@nestjs/core';
+import { BaseStrategyRegistry } from '../../strategy';
+import { IDocumentSourceStrategy } from './strategy.interface';
+export declare class DocumentSourceRegistry<TConfig = any> extends BaseStrategyRegistry<IDocumentSourceStrategy<TConfig>> {
+    constructor(discoveryService: DiscoveryService, reflector: Reflector);
+}

package/src/lib/rag/textsplitter/index.d.ts

@@ -0,0 +1,3 @@
+export * from './strategy.decorator';
+export * from './strategy.interface';
+export * from './strategy.registry';

package/src/lib/rag/textsplitter/strategy.decorator.d.ts

@@ -0,0 +1,2 @@
+export declare const TEXT_SPLITTER_STRATEGY = "TEXT_SPLITTER_STRATEGY";
+export declare const TextSplitterStrategy: (provider: string) => import("@nestjs/common").CustomDecorator<string>;