feat(agent): addAi customization with OpenAI support (#1420)

Author: Scra3

packages/_example/package.json

@@ -5,7 +5,7 @@
   "private": true,
   "dependencies": {
     "@faker-js/faker": "^7.6.0",
-    "@forestadmin/agent": "1.70.9",
+    "@forestadmin/agent": "1.70.10",
     "@forestadmin/datasource-dummy": "1.1.60",
     "@forestadmin/datasource-mongo": "1.6.1",
     "@forestadmin/datasource-mongoose": "1.12.5",

packages/agent/package.json

@@ -13,6 +13,7 @@
   },
   "dependencies": {
     "@fast-csv/format": "^4.3.5",
+    "@forestadmin/ai-proxy": "1.0.1",
     "@forestadmin/datasource-customizer": "1.67.2",
     "@forestadmin/datasource-toolkit": "1.50.1",
     "@forestadmin/forestadmin-client": "1.37.4",

packages/agent/src/agent.ts

@@ -1,6 +1,11 @@
 /* eslint-disable @typescript-eslint/no-explicit-any */
 import type { ForestAdminHttpDriverServices } from './services';
-import type { AgentOptions, AgentOptionsWithDefaults, HttpCallback } from './types';
+import type {
+  AgentOptions,
+  AgentOptionsWithDefaults,
+  AiConfiguration,
+  HttpCallback,
+} from './types';
 import type {
   CollectionCustomizer,
   DataSourceChartDefinition,
@@ -12,6 +17,7 @@ import type {
 import type { DataSource, DataSourceFactory } from '@forestadmin/datasource-toolkit';
 import type { ForestSchema } from '@forestadmin/forestadmin-client';
 
+import { isModelSupportingTools } from '@forestadmin/ai-proxy';
 import { DataSourceCustomizer } from '@forestadmin/datasource-customizer';
 import bodyParser from '@koa/bodyparser';
 import cors from '@koa/cors';
@@ -42,6 +48,7 @@ export default class Agent<S extends TSchema = TSchema> extends FrameworkMounter
   protected nocodeCustomizer: DataSourceCustomizer<S>;
   protected customizationService: CustomizationService;
   protected schemaGenerator: SchemaGenerator;
+  protected aiConfigurations: AiConfiguration[] = [];
 
   /** Whether MCP server should be mounted */
   private mcpEnabled = false;
@@ -210,8 +217,55 @@ export default class Agent<S extends TSchema = TSchema> extends FrameworkMounter
     return this;
   }
 
+  /**
+   * Enable AI features for your Forest Admin panel.
+   *
+   * All AI requests from Forest Admin are forwarded to your agent and processed locally.
+   * Your data and API keys never transit through Forest Admin servers, ensuring full privacy.
+   *
+   * @param configuration - The AI provider configuration
+   * @param configuration.name - A unique name to identify this AI configuration
+   * @param configuration.provider - The AI provider to use ('openai')
+   * @param configuration.apiKey - Your API key for the chosen provider
+   * @param configuration.model - The model to use (e.g., 'gpt-4o')
+   * @returns The agent instance for chaining
+   * @throws Error if addAi is called more than once
+   *
+   * @example
+   * agent.addAi({
+   *   name: 'assistant',
+   *   provider: 'openai',
+   *   apiKey: process.env.OPENAI_API_KEY,
+   *   model: 'gpt-4o',
+   * });
+   */
+  addAi(configuration: AiConfiguration): this {
+    if (this.aiConfigurations.length > 0) {
+      throw new Error(
+        'addAi can only be called once. Multiple AI configurations are not supported yet.',
+      );
+    }
+
+    if (!isModelSupportingTools(configuration.model)) {
+      throw new Error(
+        `Model '${configuration.model}' does not support function calling (tools). ` +
+          'Please use a compatible model like gpt-4o, gpt-4o-mini, or gpt-4-turbo.',
+      );
+    }
+
+    this.options.logger(
+      'Warn',
+      `AI configuration added with model '${configuration.model}'. ` +
+        'Make sure to test Forest Admin AI features thoroughly to ensure compatibility.',
+    );
+
+    this.aiConfigurations.push(configuration);
+
+    return this;
+  }
+
   protected getRoutes(dataSource: DataSource, services: ForestAdminHttpDriverServices) {
-    return makeRoutes(dataSource, this.options, services);
+    return makeRoutes(dataSource, this.options, services, this.aiConfigurations);
   }
 
   /**
@@ -333,7 +387,11 @@ export default class Agent<S extends TSchema = TSchema> extends FrameworkMounter
     // Either load the schema from the file system or build it
     let schema: Pick<ForestSchema, 'collections'>;
 
-    const { meta } = SchemaGenerator.buildMetadata(this.customizationService.buildFeatures());
+    // Get the AI configurations for schema metadata
+    const { meta } = SchemaGenerator.buildMetadata(
+      this.customizationService.buildFeatures(),
+      this.aiConfigurations,
+    );
 
     // When using experimental no-code features even in production we need to build a new schema
     if (!experimental?.webhookCustomActions && isProduction) {

packages/agent/src/routes/ai/ai-proxy.ts

@@ -0,0 +1,62 @@
+import type { ForestAdminHttpDriverServices } from '../../services';
+import type { AgentOptionsWithDefaults, AiConfiguration } from '../../types';
+import type KoaRouter from '@koa/router';
+import type { Context } from 'koa';
+
+import {
+  AIBadRequestError,
+  AIError,
+  AINotFoundError,
+  Router as AiProxyRouter,
+} from '@forestadmin/ai-proxy';
+import {
+  BadRequestError,
+  NotFoundError,
+  UnprocessableError,
+} from '@forestadmin/datasource-toolkit';
+
+import { HttpCode, RouteType } from '../../types';
+import BaseRoute from '../base-route';
+
+export default class AiProxyRoute extends BaseRoute {
+  readonly type = RouteType.PrivateRoute;
+  private readonly aiProxyRouter: AiProxyRouter;
+
+  constructor(
+    services: ForestAdminHttpDriverServices,
+    options: AgentOptionsWithDefaults,
+    aiConfigurations: AiConfiguration[],
+  ) {
+    super(services, options);
+    this.aiProxyRouter = new AiProxyRouter({
+      aiConfigurations,
+      logger: this.options.logger,
+    });
+  }
+
+  setupRoutes(router: KoaRouter): void {
+    router.post('/_internal/ai-proxy/:route', this.handleAiProxy.bind(this));
+  }
+
+  private async handleAiProxy(context: Context): Promise<void> {
+    try {
+      context.response.body = await this.aiProxyRouter.route({
+        route: context.params.route,
+        body: context.request.body,
+        query: context.query,
+        mcpConfigs: await this.options.forestAdminClient.mcpServerConfigService.getConfiguration(),
+      });
+      context.response.status = HttpCode.Ok;
+    } catch (error) {
+      if (error instanceof AIError) {
+        this.options.logger('Error', `AI proxy error: ${error.message}`, error);
+
+        if (error instanceof AIBadRequestError) throw new BadRequestError(error.message);
+        if (error instanceof AINotFoundError) throw new NotFoundError(error.message);
+        throw new UnprocessableError(error.message);
+      }
+
+      throw error;
+    }
+  }
+}

packages/agent/src/routes/index.ts

@@ -1,5 +1,5 @@
 import type { ForestAdminHttpDriverServices as Services } from '../services';
-import type { AgentOptionsWithDefaults as Options } from '../types';
+import type { AiConfiguration, AgentOptionsWithDefaults as Options } from '../types';
 import type BaseRoute from './base-route';
 import type { DataSource } from '@forestadmin/datasource-toolkit';
 
@@ -14,6 +14,7 @@ import Get from './access/get';
 import List from './access/list';
 import ListRelated from './access/list-related';
 import NativeQueryDatasource from './access/native-query-datasource';
+import AiProxyRoute from './ai/ai-proxy';
 import Capabilities from './capabilities';
 import ActionRoute from './modification/action/action';
 import AssociateRelated from './modification/associate-related';
@@ -164,10 +165,21 @@ function getActionRoutes(
   return routes;
 }
 
+function getAiRoutes(
+  options: Options,
+  services: Services,
+  aiConfigurations: AiConfiguration[],
+): BaseRoute[] {
+  if (aiConfigurations.length === 0) return [];
+
+  return [new AiProxyRoute(services, options, aiConfigurations)];
+}
+
 export default function makeRoutes(
   dataSource: DataSource,
   options: Options,
   services: Services,
+  aiConfigurations: AiConfiguration[] = [],
 ): BaseRoute[] {
   const routes = [
     ...getRootRoutes(options, services),
@@ -177,6 +189,7 @@ export default function makeRoutes(
     ...getApiChartRoutes(dataSource, options, services),
     ...getRelatedRoutes(dataSource, options, services),
     ...getActionRoutes(dataSource, options, services),
+    ...getAiRoutes(options, services, aiConfigurations),
   ];
 
   // Ensure routes and middlewares are loaded in the right order.

packages/agent/src/types.ts

@@ -1,7 +1,10 @@
+import type { AiConfiguration, AiProvider } from '@forestadmin/ai-proxy';
 import type { CompositeId, Logger, LoggerLevel } from '@forestadmin/datasource-toolkit';
 import type { ForestAdminClient } from '@forestadmin/forestadmin-client';
 import type { IncomingMessage, ServerResponse } from 'http';
 
+export type { AiConfiguration, AiProvider };
+
 /** Options to configure behavior of an agent's forestadmin driver */
 export type AgentOptions = {
   authSecret: string;

packages/agent/src/utils/forest-schema/generator.ts

@@ -1,4 +1,4 @@
-import type { AgentOptionsWithDefaults } from '../../types';
+import type { AgentOptionsWithDefaults, AiConfiguration } from '../../types';
 import type { DataSource } from '@forestadmin/datasource-toolkit';
 import type { ForestSchema } from '@forestadmin/forestadmin-client';
 
@@ -21,14 +21,21 @@ export default class SchemaGenerator {
     };
   }
 
-  static buildMetadata(features: Record<string, string> | null): Pick<ForestSchema, 'meta'> {
+  static buildMetadata(
+    features: Record<string, string> | null,
+    aiConfigurations: AiConfiguration[] = [],
+  ): Pick<ForestSchema, 'meta'> {
     const { version } = require('../../../package.json'); // eslint-disable-line @typescript-eslint/no-var-requires,global-require
 
     return {
       meta: {
         liana: 'forest-nodejs-agent',
         liana_version: version,
         liana_features: features,
+        ai_llms:
+          aiConfigurations.length > 0
+            ? aiConfigurations.map(c => ({ name: c.name, provider: c.provider }))
+            : null,
         stack: {
           engine: 'nodejs',
           engine_version: process.versions && process.versions.node,

packages/agent/test/agent.test.ts

@@ -128,6 +128,7 @@ describe('Agent', () => {
           liana: 'forest-nodejs-agent',
           liana_version: expect.stringMatching(/\d+\.\d+\.\d+.*/),
           liana_features: null,
+          ai_llms: null,
           stack: expect.anything(),
         },
       });
@@ -156,6 +157,7 @@ describe('Agent', () => {
           liana_features: {
             'webhook-custom-actions': expect.stringMatching(/\d+\.\d+\.\d+.*/),
           },
+          ai_llms: null,
           stack: expect.anything(),
         },
       });
@@ -398,4 +400,93 @@ describe('Agent', () => {
       );
     });
   });
+
+  describe('addAi', () => {
+    const options = factories.forestAdminHttpDriverOptions.build({
+      isProduction: false,
+      forestAdminClient: factories.forestAdminClient.build({ postSchema: mockPostSchema }),
+    });
+
+    test('should store the AI configuration', () => {
+      const agent = new Agent(options);
+      const result = agent.addAi({
+        name: 'gpt4o',
+        provider: 'openai',
+        apiKey: 'test-key',
+        model: 'gpt-4o',
+      });
+
+      expect(result).toBe(agent);
+    });
+
+    test('should throw an error when addAi is called more than once', () => {
+      const agent = new Agent(options);
+
+      agent.addAi({
+        name: 'gpt4o',
+        provider: 'openai',
+        apiKey: 'test-key',
+        model: 'gpt-4o',
+      });
+
+      expect(() =>
+        agent.addAi({
+          name: 'gpt4o-mini',
+          provider: 'openai',
+          apiKey: 'another-key',
+          model: 'gpt-4o-mini',
+        }),
+      ).toThrow('addAi can only be called once. Multiple AI configurations are not supported yet.');
+    });
+
+    test('should throw an error when model does not support tools', () => {
+      const agent = new Agent(options);
+
+      expect(() =>
+        agent.addAi({
+          name: 'gpt4-base',
+          provider: 'openai',
+          apiKey: 'test-key',
+          model: 'gpt-4',
+        }),
+      ).toThrow(
+        "Model 'gpt-4' does not support function calling (tools). " +
+          'Please use a compatible model like gpt-4o, gpt-4o-mini, or gpt-4-turbo.',
+      );
+    });
+
+    test('should include ai_llms in schema meta when AI is configured', async () => {
+      const agent = new Agent(options);
+      agent.addAi({
+        name: 'gpt4o',
+        provider: 'openai',
+        apiKey: 'test-key',
+        model: 'gpt-4o',
+      });
+
+      await agent.start();
+
+      expect(mockPostSchema).toHaveBeenCalledWith(
+        expect.objectContaining({
+          meta: expect.objectContaining({
+            ai_llms: [{ name: 'gpt4o', provider: 'openai' }],
+          }),
+        }),
+      );
+    });
+
+    test('should not include ai_llms in schema meta when AI is not configured', async () => {
+      const agent = new Agent(options);
+
+      await agent.start();
+
+      expect(mockPostSchema).toHaveBeenCalledWith(
+        expect.objectContaining({
+          meta: expect.objectContaining({
+            ai_llms: null,
+          }),
+        }),
+      );
+    });
+  });
 });