@nocobase/ai 2.0.0

package/src/loader/tools.ts

@@ -0,0 +1,135 @@
+/**
+ * This file is part of the NocoBase (R) project.
+ * Copyright (c) 2020-2024 NocoBase Co., Ltd.
+ * Authors: NocoBase Team.
+ *
+ * This project is dual-licensed under AGPL-3.0 and NocoBase Commercial License.
+ * For more information, please refer to: https://www.nocobase.com/agreement.
+ */
+
+import { importModule } from '@nocobase/utils';
+import { ToolsOptions } from '../tools-manager';
+import { DirectoryScanner, DirectoryScannerOptions, FileDescriptor } from './scanner';
+import { readFile } from 'fs/promises';
+import _ from 'lodash';
+import { existsSync } from 'fs';
+import { AIManager } from '../ai-manager';
+import { LoadAndRegister } from './types';
+import { Logger } from '@nocobase/logger';
+import { isNonEmptyObject } from './utils';
+
+export type ToolsLoaderOptions = { scan: DirectoryScannerOptions; log?: Logger };
+export class ToolsLoader extends LoadAndRegister<ToolsLoaderOptions> {
+  protected readonly scanner: DirectoryScanner;
+
+  protected files: FileDescriptor[] = [];
+  protected toolsDescriptors: ToolsDescriptor[] = [];
+  protected log: Logger;
+
+  constructor(
+    protected readonly ai: AIManager,
+    protected readonly options: ToolsLoaderOptions,
+  ) {
+    super(ai, options);
+    this.log = options.log;
+    this.scanner = new DirectoryScanner(this.options.scan);
+  }
+
+  protected async scan(): Promise<void> {
+    this.files = await this.scanner.scan();
+  }
+
+  protected async import(): Promise<void> {
+    if (!this.files.length) {
+      return;
+    }
+    const grouped = new Map<string, FileDescriptor[]>();
+    for (const fd of this.files) {
+      const key =
+        fd.basename === 'index.ts' || fd.basename === 'index.js' || fd.basename === 'description.md'
+          ? fd.directory
+          : fd.name;
+      if (!grouped.has(key)) {
+        grouped.set(key, []);
+      }
+      grouped.get(key).push(fd);
+    }
+
+    this.toolsDescriptors = (
+      await Promise.all(
+        Array.from(grouped.entries()).map(async ([name, fds]) => {
+          const tsFile = fds.find((fd) => fd.extname === '.ts' || fd.extname === '.js');
+          const descFile = fds.find((fd) => fd.basename === 'description.md');
+          const entry: ToolsDescriptor = { name, tsFile, descFile };
+          if (!tsFile || !existsSync(tsFile.path)) {
+            this.log?.error(`tools [${name}] ignored: can not find .ts file`);
+            return null;
+          }
+          try {
+            const module = await importModule(tsFile.path);
+            if (isNonEmptyObject(module)) {
+              entry.toolsOptions = typeof module === 'function' ? module() : module;
+            } else {
+              entry.toolsOptions = undefined;
+            }
+          } catch (e) {
+            this.log?.error(`tools [${name}] load fail: error occur when import ${tsFile.path}`, e);
+            return null;
+          }
+          if (descFile && existsSync(descFile.path)) {
+            try {
+              entry.description = await readFile(descFile.path, 'utf-8');
+            } catch (e) {
+              this.log?.error(
+                `tools [${name}] load fail: error occur when reading description.md at ${descFile.path}`,
+                e,
+              );
+              return null;
+            }
+          }
+          return entry;
+        }),
+      )
+    ).filter((t) => t != null);
+  }
+
+  protected async register(): Promise<void> {
+    if (!this.toolsDescriptors.length) {
+      return;
+    }
+    const { toolsManager } = this.ai;
+    for (const descriptor of this.toolsDescriptors) {
+      if (!descriptor.toolsOptions) {
+        this.log?.warn(
+          `tools [${descriptor.name}] register ignored: ToolsOptions not export as default at ${descriptor.tsFile.path}`,
+        );
+        continue;
+      }
+      const { name, toolsOptions, description } = descriptor;
+      if (await toolsManager.getTools(name)) {
+        this.log?.warn(`tools [${descriptor.name}] register ignored: duplicate register for tools`);
+        continue;
+      }
+      if (toolsOptions.definition) {
+        toolsOptions.definition.name = name;
+        if (!_.isEmpty(description)) {
+          toolsOptions.definition.description = description;
+        }
+      }
+      try {
+        toolsManager.registerTools(toolsOptions);
+      } catch (e) {
+        this.log?.error(`tools [${descriptor.name}] register ignored: error occur when invoke registerTools`, e);
+        continue;
+      }
+    }
+  }
+}
+
+export type ToolsDescriptor = {
+  name: string;
+  tsFile?: FileDescriptor;
+  descFile?: FileDescriptor;
+  toolsOptions?: ToolsOptions;
+  description?: string;
+};

package/src/loader/types.ts

@@ -0,0 +1,25 @@
+/**
+ * This file is part of the NocoBase (R) project.
+ * Copyright (c) 2020-2024 NocoBase Co., Ltd.
+ * Authors: NocoBase Team.
+ *
+ * This project is dual-licensed under AGPL-3.0 and NocoBase Commercial License.
+ * For more information, please refer to: https://www.nocobase.com/agreement.
+ */
+
+import { AIManager } from '../ai-manager';
+
+export abstract class LoadAndRegister<TOptions> {
+  constructor(
+    protected readonly ai: AIManager,
+    protected readonly options: TOptions,
+  ) {}
+  protected abstract scan(): Promise<void>;
+  protected abstract import(): Promise<void>;
+  protected abstract register(): Promise<void>;
+  async load(): Promise<void> {
+    await this.scan();
+    await this.import();
+    await this.register();
+  }
+}

package/src/loader/utils.ts

@@ -0,0 +1,14 @@
+/**
+ * This file is part of the NocoBase (R) project.
+ * Copyright (c) 2020-2024 NocoBase Co., Ltd.
+ * Authors: NocoBase Team.
+ *
+ * This project is dual-licensed under AGPL-3.0 and NocoBase Commercial License.
+ * For more information, please refer to: https://www.nocobase.com/agreement.
+ */
+
+import _ from 'lodash';
+
+export function isNonEmptyObject(val: any) {
+  return _.isPlainObject(val) && !_.isEmpty(val);
+}

package/src/tools-manager/index.ts

@@ -0,0 +1,97 @@
+/**
+ * This file is part of the NocoBase (R) project.
+ * Copyright (c) 2020-2024 NocoBase Co., Ltd.
+ * Authors: NocoBase Team.
+ *
+ * This project is dual-licensed under AGPL-3.0 and NocoBase Commercial License.
+ * For more information, please refer to: https://www.nocobase.com/agreement.
+ */
+
+import { Registry } from '@nocobase/utils';
+import { DynamicToolsProvider, ToolsEntry, ToolsFilter, ToolsManager, ToolsOptions } from './types';
+import _ from 'lodash';
+
+export class DefaultToolsManager implements ToolsManager {
+  constructor(
+    private readonly tools = new Registry<ToolsEntry>(),
+    private readonly dynamicTools: DynamicToolsProvider[] = [],
+  ) {}
+
+  async getTools(toolName: string): Promise<ToolsEntry> {
+    const target = this.tools.get(toolName);
+    if (target) {
+      return target;
+    }
+    const dynamicTools = await this.syncDynamicTools();
+    return dynamicTools.find((x) => x.definition.name === toolName);
+  }
+
+  async listTools(filter?: ToolsFilter): Promise<ToolsEntry[]> {
+    const toolsList = await this.getToolsList();
+    return toolsList.filter((x) => {
+      if (!filter) {
+        return true;
+      }
+
+      let result = true;
+      if (filter.scope) {
+        result &&= filter.scope === x.scope;
+      }
+
+      if (filter.defaultPermission) {
+        result &&= filter.defaultPermission === x.defaultPermission;
+      }
+
+      if (filter.silence != null && filter.silence !== undefined) {
+        result &&= filter.silence === x.silence;
+      }
+
+      return result;
+    });
+  }
+
+  registerTools(options: ToolsOptions | ToolsOptions[]): void {
+    const list = _.isArray(options) ? options : [options];
+    for (const item of list) {
+      const toolsEntry = { ...item } as ToolsEntry;
+      if (!toolsEntry.execution) {
+        toolsEntry.execution = 'backend';
+      }
+      if (!toolsEntry.defaultPermission) {
+        toolsEntry.defaultPermission = 'ASK';
+      }
+      toolsEntry.silence = toolsEntry.silence === true;
+      if (!toolsEntry.introduction) {
+        toolsEntry.introduction = {
+          title: toolsEntry.definition.name,
+        };
+      }
+      this.tools.register(item.definition.name, toolsEntry);
+    }
+  }
+
+  registerDynamicTools(provider: DynamicToolsProvider): void {
+    this.dynamicTools.push(provider);
+  }
+
+  private async getToolsList(): Promise<ToolsEntry[]> {
+    const dynamicTools = await this.syncDynamicTools();
+    return [...this.tools.getValues(), ...dynamicTools];
+  }
+
+  private async syncDynamicTools(): Promise<ToolsEntry[]> {
+    if (this.dynamicTools.length === 0) {
+      return [];
+    }
+    const registry = new Registry<ToolsEntry>();
+    const ephemeral = new DefaultToolsManager(registry);
+    await Promise.all(this.dynamicTools.map((register) => register(ephemeral)));
+    return [...registry.getValues()];
+  }
+}
+
+export function defineTools(options: ToolsOptions) {
+  return options;
+}
+
+export * from './types';

package/src/tools-manager/types.ts

@@ -0,0 +1,50 @@
+/**
+ * This file is part of the NocoBase (R) project.
+ * Copyright (c) 2020-2024 NocoBase Co., Ltd.
+ * Authors: NocoBase Team.
+ *
+ * This project is dual-licensed under AGPL-3.0 and NocoBase Commercial License.
+ * For more information, please refer to: https://www.nocobase.com/agreement.
+ */
+
+import type { Context } from '@nocobase/actions';
+
+export interface ToolsManager extends ToolsRegistration {
+  getTools(toolName: string): Promise<ToolsEntry>;
+  listTools(filter?: ToolsFilter): Promise<ToolsEntry[]>;
+}
+
+export interface ToolsRegistration {
+  registerTools(options: ToolsOptions | ToolsOptions[]): void;
+  registerDynamicTools(provider: (register: ToolsRegistration) => Promise<void>): void;
+}
+
+export type ToolsOptions = {
+  scope: Scope;
+  execution?: 'frontend' | 'backend';
+  defaultPermission?: Permission;
+  silence?: boolean;
+  introduction?: {
+    title: string;
+    about?: string;
+  };
+  definition: {
+    name: string;
+    description: string;
+    schema?: any;
+  };
+  invoke: (ctx: Context, args: any, id: string) => Promise<any>;
+};
+
+export type ToolsEntry = ToolsOptions;
+
+export type Scope = 'SPECIFIED' | 'GENERAL' | 'CUSTOM';
+export type Permission = 'ASK' | 'ALLOW';
+
+export type DynamicToolsProvider = (register: ToolsRegistration) => Promise<void>;
+
+export type ToolsFilter = {
+  scope?: Scope;
+  defaultPermission?: Permission;
+  silence?: boolean;
+};