@dxos/plugin-assistant 0.7.5-main.5ae2ba8

package/src/tools/openapi.test.ts

@@ -0,0 +1,224 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { describe, expect, test } from 'vitest';
+
+import { AIServiceClientImpl } from '@dxos/assistant';
+import { AI_SERVICE_ENDPOINT } from '@dxos/assistant/testing';
+import { log } from '@dxos/log';
+
+import { createToolsFromApi, resolveAuthorization } from './openapi';
+import { ChatProcessor } from '../hooks';
+import type { ApiAuthorization } from '../types';
+
+describe.skip('openapi', () => {
+  describe.skip('mapping', () => {
+    test('amadeus flight availabilities', async () => {
+      const tools = await createToolsFromApi(FLIGHT_SEARCH_API);
+
+      log.info('tools', { tools });
+      // for (const tool of tools) {
+      //   const schema = tool.parameters;
+      //   // log.info('schema', { schema });
+      // }
+    });
+
+    test('amadeus hotel search', async () => {
+      const tools = await createToolsFromApi(HOTEL_SEARCH_API);
+      log.info('tools', { tools });
+    });
+
+    test('amadeus hotel name autocomplete', async () => {
+      const tools = await createToolsFromApi(HOTEL_NAME_AUTOCOMPLETE_API);
+      log.info('tools', { tools });
+    });
+
+    test('weather', async () => {
+      const tools = await createToolsFromApi(WEATHER_API, { authorization: VISUAL_CROSSING_CREDENTIALS });
+      log.info('tools', { tools });
+    });
+  });
+
+  describe.skip('invoke tools', () => {
+    test('amadeus hotel name autocomplete', async () => {
+      const tools = await createToolsFromApi(HOTEL_NAME_AUTOCOMPLETE_API, { authorization: AMADEUS_AUTH });
+
+      const result = await tools[0].execute!({
+        keyword: 'William Vale Brooklyn',
+        subType: ['HOTEL_LEISURE', 'HOTEL_GDS'],
+        countryCode: 'US',
+      });
+
+      log.info('result', { result });
+    });
+
+    test('weather API', async () => {
+      const tools = await createToolsFromApi(WEATHER_API, { authorization: VISUAL_CROSSING_CREDENTIALS });
+      const forecastTool = tools.find((t) => t.name.includes('forecast'));
+
+      const result = await forecastTool?.execute!({
+        locations: 'Brooklyn, NY',
+        aggregateHours: '24',
+      });
+
+      log.info('result', { result });
+    });
+  });
+
+  describe.skip('AI uses tools', () => {
+    test('amadeus flight availabilities', { timeout: 60_000 }, async () => {
+      const tools = await createToolsFromApi(FLIGHT_SEARCH_API, {
+        authorization: AMADEUS_AUTH,
+      });
+
+      const client = new AIServiceClientImpl({
+        endpoint: AI_SERVICE_ENDPOINT.LOCAL,
+      });
+      const processor = new ChatProcessor(client, tools);
+      const reply = await processor.request(
+        `What is the cheapest flight from New York to Paris? going on ${new Date().toISOString()} and returning after a week. 1 adult traveler`,
+      );
+
+      log.info('reply', { reply });
+    });
+
+    // TODO(dmaretskyi): Doesn't work.
+    test('amadeus hotel name autocomplete', { timeout: 60_000 }, async () => {
+      const tools = await createToolsFromApi(HOTEL_NAME_AUTOCOMPLETE_API, { authorization: AMADEUS_AUTH });
+
+      const client = new AIServiceClientImpl({
+        endpoint: AI_SERVICE_ENDPOINT.LOCAL,
+      });
+      const processor = new ChatProcessor(client, tools);
+      const reply = await processor.request('Find me the William Wale in Brooklyn New York');
+
+      log.info('reply', { reply });
+    });
+
+    test.only('weather forecast', { timeout: 60_000 }, async () => {
+      const tools = await createToolsFromApi(WEATHER_API, {
+        authorization: VISUAL_CROSSING_CREDENTIALS,
+        instructions: WEATHER_INSTRUCTIONS,
+      });
+
+      const client = new AIServiceClientImpl({
+        endpoint: AI_SERVICE_ENDPOINT.LOCAL,
+      });
+      const processor = new ChatProcessor(client, tools);
+      const reply = await processor.request(
+        `Today's date is ${new Date().toISOString().split('T')[0]}. Give me weather forecast for Warsaw for next 5 days.`,
+      );
+
+      log.info('reply', { reply });
+    });
+  });
+
+  describe.skip('invoke api directly', { timeout: 10_000 }, () => {
+    test('amadeus flight availabilities', async () => {
+      const response = await fetch('https://test.api.amadeus.com/v1/shopping/availability/flight-availabilities', {
+        method: 'POST',
+        headers: {
+          accept: 'application/vnd.amadeus+json',
+          'X-HTTP-Method-Override': 'GET',
+          'Content-Type': 'application/vnd.amadeus+json',
+          Authorization: await resolveAuthorization(AMADEUS_AUTH),
+        },
+        body: JSON.stringify({
+          originDestinations: [
+            {
+              departureDateTime: {
+                date: new Date().toISOString().split('T')[0],
+                time: new Date().toTimeString().split(' ')[0],
+              },
+              destinationLocationCode: 'MAD',
+              id: '1',
+              originLocationCode: 'BOS',
+            },
+          ],
+          sources: ['GDS'],
+          travelers: [
+            {
+              id: '1',
+              travelerType: 'ADULT',
+            },
+          ],
+        }),
+      });
+
+      log.info('response', { status: response.status, body: await response.json() });
+      expect(response.status).toBe(200);
+    });
+
+    test.only('amadeus hotel name autocomplete', async () => {
+      const response = await fetch(
+        'https://test.api.amadeus.com/v1/reference-data/locations/hotel?keyword=PARI&subtype=HOTEL_LEISURE,HOTEL_GDS',
+        {
+          method: 'GET',
+          headers: {
+            // accept: 'application/vnd.amadeus+json',
+            // 'X-HTTP-Method-Override': 'GET',
+            Authorization: await resolveAuthorization(AMADEUS_AUTH),
+          },
+        },
+      );
+
+      log.info('response', { status: response.status, body: await response.json() });
+      expect(response.status).toBe(200);
+    });
+  });
+
+  describe.skip('rapidapi', () => {
+    test('amadeus flight availabilities', async () => {
+      const departureDate = new Date().toISOString().split('T')[0];
+      const arrivalDate = new Date(new Date().getTime() + 7 * 24 * 60 * 60 * 1000).toISOString().split('T')[0];
+
+      const url = `https://amadeus-api2.p.rapidapi.com/serpapi-flight-search?departure_id=PEK&arrival_id=AUS&outbound_date=${departureDate}&return_date=${arrivalDate}&currency=USD&hl=en`;
+      const options = {
+        method: 'GET',
+        headers: {
+          'x-rapidapi-key': RAPID_API_CREDENTIALS.key,
+          'x-rapidapi-host': 'amadeus-api2.p.rapidapi.com',
+        },
+      };
+
+      const response = await fetch(url, options);
+      log.info('response', { status: response.status, body: await response.json() });
+      expect(response.status).toBe(200);
+    });
+  });
+});
+
+const FLIGHT_SEARCH_API =
+  'https://api.apis.guru/v2/specs/amadeus.com/amadeus-flight-availabilities-search/1.0.2/swagger.json';
+const HOTEL_SEARCH_API = 'https://api.apis.guru/v2/specs/amadeus.com/amadeus-hotel-search/3.0.8/swagger.json';
+const HOTEL_NAME_AUTOCOMPLETE_API =
+  'https://api.apis.guru/v2/specs/amadeus.com/amadeus-hotel-name-autocomplete/1.0.3/swagger.json';
+const WEATHER_API = 'https://api.apis.guru/v2/specs/visualcrossing.com/weather/4.6/openapi.json';
+
+const WEATHER_INSTRUCTIONS = `
+  If the user doesn't provide a date, use today's date.
+  Make sure to provide the start and end dates when possible to reduce the amount of data returned.
+  Use the tool that accepts the date parameters.
+`;
+
+const AMADEUS_AUTH: ApiAuthorization = {
+  type: 'oauth',
+  clientId: 'BOEnpLd1sMyKjAPGKYeAPFFy60u53QEG',
+  clientSecret: 'n4qldSN7usvD57gm',
+  tokenUrl: 'https://test.api.amadeus.com/v1/security/oauth2/token',
+  grantType: 'client_credentials',
+};
+
+const VISUAL_CROSSING_CREDENTIALS: ApiAuthorization = {
+  type: 'api-key',
+  key: 'FDPRVS953KB4GQQLD25GRT975',
+  placement: {
+    type: 'query',
+    name: 'key',
+  },
+};
+
+const RAPID_API_CREDENTIALS = {
+  key: '92271b6740msh32fd821d70f050dp16665bjsna69195c9e838',
+};

package/src/tools/openapi.ts

@@ -0,0 +1,331 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import jsonpointer from 'jsonpointer';
+import { type OpenAPIV2, type OpenAPIV3_1 } from 'openapi-types';
+
+import { ToolResult, type Tool } from '@dxos/artifact';
+import { JsonSchemaType, normalizeSchema, S, toEffectSchema } from '@dxos/echo-schema';
+import { invariant } from '@dxos/invariant';
+import { log } from '@dxos/log';
+import { deepMapValues } from '@dxos/util';
+
+import type { ApiAuthorization, ServiceType } from '../types';
+
+export type CreateToolsFromApiOptions = {
+  authorization?: ApiAuthorization;
+  instructions?: string;
+};
+
+export const createToolsFromService = async (service: ServiceType): Promise<Tool[]> => {
+  invariant(service.interfaces?.length === 1 && service.interfaces[0].kind === 'api');
+  const iface = service.interfaces[0];
+  invariant(iface.schemaUrl);
+  invariant(iface.schemaUrl);
+  return createToolsFromApi(iface.schemaUrl, { authorization: iface.authorization });
+};
+
+export const createToolsFromApi = async (url: string, options?: CreateToolsFromApiOptions): Promise<Tool[]> => {
+  const res = await fetch(url);
+  const spec = (await res.json()) as OpenAPIV2.Document;
+  log('spec', { spec });
+
+  const tools: Tool[] = [];
+  for (const [path, pathItem] of Object.entries(spec.paths)) {
+    if (typeof pathItem !== 'object') {
+      continue;
+    }
+
+    // TODO(burdon): ???
+    const { ...methods } = pathItem;
+    for (const [method, m] of Object.entries(methods)) {
+      const methodItem: OpenAPIV2.OperationObject = m as OpenAPIV2.OperationObject;
+      log('methodItem', { path, method, methodItem });
+
+      const parametersResolved: OpenAPIV2.ParameterObject[] =
+        methodItem.parameters?.map((parameter: any) => {
+          const resolved = resolveJsonSchema(parameter, spec);
+          return resolved;
+        }) ?? [];
+
+      const inputSchema: JsonSchemaType = {
+        type: 'object',
+        properties: {},
+      };
+
+      const endpointParameters: OpenAPIV2.ParameterObject[] = [];
+      for (const parameter of parametersResolved) {
+        log('parameter', { parameter });
+
+        if (
+          options?.authorization?.type === 'api-key' &&
+          options.authorization.placement.type === 'query' &&
+          parameter.in === 'query' &&
+          parameter.name === options.authorization.placement.name
+        ) {
+          continue;
+        }
+
+        endpointParameters.push(parameter);
+
+        if (parameter.schema) {
+          inputSchema.properties![parameter.name] = normalizeSchema(parameter.schema);
+        } else if (typeof parameter.type === 'string') {
+          const { name, in: _in, required, ...schema } = parameter;
+          inputSchema.properties![name] = normalizeSchema(schema);
+          if (required) {
+            inputSchema.required ??= [];
+            inputSchema.required!.push(name);
+          }
+        }
+      }
+
+      log('inputSchema', { inputSchema });
+      S.validateSync(JsonSchemaType)(inputSchema);
+
+      const description = methodItem.description ?? methodItem.summary;
+      if (!description) {
+        log.warn('no description', { path, method });
+        continue;
+      }
+
+      const endpoint: EndpointDescriptor = {
+        document: spec,
+        path,
+        method,
+        parameters: endpointParameters,
+        authorization: options?.authorization,
+      };
+
+      tools.push({
+        name: getToolName(path, method, methodItem),
+        description: options?.instructions ? `${options.instructions}\n\n${description}` : description,
+        parameters: inputSchema,
+        execute: async (input) => {
+          const response = await callApiEndpoint(endpoint, input);
+          return ToolResult.Success(response);
+        },
+      });
+    }
+  }
+
+  return tools;
+};
+
+const getToolName = (path: string, method: string, methodItem: OpenAPIV2.OperationObject) => {
+  if (methodItem.operationId) {
+    return methodItem.operationId;
+  }
+
+  // Generate a name from the path and method.
+  let name = `${method.toLowerCase()}_${path.replaceAll(/[{}/]/g, '_')}`;
+  while (name.length > MAX_TOOL_NAME_LENGTH) {
+    const lengthBefore = name.length;
+
+    for (const word of GENERIC_WORDS) {
+      if (name.includes(word)) {
+        name = name.replace(word, '');
+        break;
+      }
+    }
+    name = name.replaceAll('__', '_').replace(/_$/, '');
+
+    const lengthAfter = name.length;
+    if (lengthBefore === lengthAfter) {
+      break;
+    }
+  }
+  name = name.replaceAll('__', '_').replace(/_$/, '').replace(/^_/, '');
+
+  return name.slice(0, MAX_TOOL_NAME_LENGTH);
+};
+
+const MAX_TOOL_NAME_LENGTH = 64;
+const GENERIC_WORDS = [
+  'services',
+  'service',
+  'api',
+  'rest',
+  'endpoint',
+  'get',
+  'post',
+  'put',
+  'delete',
+  'patch',
+  'head',
+  'options',
+  'trace',
+  'service',
+  'api',
+  'endpoint',
+];
+
+type EndpointDescriptor = {
+  document: OpenAPIV3_1.Document | OpenAPIV2.Document;
+  path: string;
+  method: string;
+  parameters: OpenAPIV2.ParameterObject[];
+  authorization?: ApiAuthorization;
+};
+
+const callApiEndpoint = async (endpoint: EndpointDescriptor, input: any) => {
+  log.info('endpoint', { method: endpoint.method, name: endpoint.path, input });
+
+  let url = getEndpointUrl(endpoint);
+  const request: RequestInit = {
+    method: endpoint.method,
+    headers: {},
+  };
+  const query = new URLSearchParams();
+  let body: any;
+  for (const parameter of endpoint.parameters) {
+    if (input[parameter.name] === undefined) {
+      continue;
+    }
+
+    switch (parameter.in) {
+      case 'header': {
+        if (parameter.example) {
+          (request.headers as any)[parameter.name] = parameter.default;
+        }
+        break;
+      }
+      case 'path': {
+        url = url.replace(`{${parameter.name}}`, encodeURIComponent(input[parameter.name]));
+        break;
+      }
+      case 'body': {
+        const value = input[parameter.name];
+
+        // Client-side validation
+        const effectSchema = toEffectSchema(parameter.schema);
+        S.validateSync(effectSchema)(value);
+
+        if (body) {
+          throw new Error(`Duplicate body parameter: ${parameter.name}`);
+        }
+        body = value;
+        break;
+      }
+      case 'query': {
+        query.set(parameter.name, input[parameter.name]);
+        break;
+      }
+    }
+  }
+
+  if (
+    (endpoint.authorization?.type === 'api-key' && endpoint.authorization.placement.type === 'authorization-header') ||
+    endpoint.authorization?.type === 'oauth'
+  ) {
+    (request.headers as any).Authorization = await resolveAuthorization(endpoint.authorization);
+  } else if (endpoint.authorization?.type === 'api-key' && endpoint.authorization.placement.type === 'query') {
+    query.set(endpoint.authorization.placement.name, endpoint.authorization.key);
+  }
+
+  if (query.size > 0) {
+    url += `?${query.toString()}`;
+  }
+
+  if (body) {
+    request.body = JSON.stringify(body);
+    (request.headers as any)['Content-Type'] = 'application/json';
+  }
+
+  log.info('request', { url, request });
+  const response = await fetch(url, request);
+
+  log.info('response', { ok: response.ok, status: response.status, statusText: response.statusText });
+
+  if (response.ok) {
+    const contentType = response.headers.get('Content-Type');
+    if (contentType?.includes('application/json')) {
+      return await response.json();
+    } else {
+      return await response.text();
+    }
+  } else {
+    if (response.headers.get('Content-Type')?.includes('application/json')) {
+      const responseBody = await response.text();
+      let error: any;
+      try {
+        error = JSON.parse(responseBody);
+      } catch {
+        error = responseBody;
+      }
+      log.error('error', { error });
+      throw new Error(error.message);
+    } else {
+      const error = await response.text();
+      log.error('error', { error });
+      throw new Error(error);
+    }
+  }
+};
+
+const getEndpointUrl = (endpoint: EndpointDescriptor) => {
+  let url = '';
+  if (isV3_1(endpoint.document) && endpoint.document.servers && endpoint.document.servers.length > 0) {
+    url = endpoint.document.servers[0].url;
+  } else {
+    invariant(!isV3_1(endpoint.document));
+    url = `${endpoint.document.schemes?.[0] ?? 'https'}://${endpoint.document.host}`;
+  }
+
+  if (!isV3_1(endpoint.document) && endpoint.document.basePath) {
+    url += endpoint.document.basePath;
+  }
+
+  url += endpoint.path;
+
+  return url;
+};
+
+export const resolveAuthorization = async (authorization: ApiAuthorization): Promise<string> => {
+  switch (authorization.type) {
+    case 'api-key': {
+      invariant(authorization.placement.type === 'authorization-header');
+      return `Bearer ${authorization.key}`;
+    }
+    case 'oauth': {
+      const response = await fetch(authorization.tokenUrl, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/x-www-form-urlencoded',
+        },
+        body: `grant_type=${authorization.grantType}&client_id=${authorization.clientId}&client_secret=${authorization.clientSecret}`,
+      });
+      const data = await response.json();
+      return `Bearer ${data.access_token}`;
+    }
+    default: {
+      throw new Error(`Unknown authorization type: ${(authorization as any).type}`);
+    }
+  }
+};
+
+/**
+ * Resolves all $ref properties in a JSON schema.
+ * Doesn't assume the structure of the schema.
+ * The function looks from $ref properties in the schema and resolves them to their values in the base object.
+ */
+const resolveJsonSchema = (schema: any, base: any) => {
+  return deepMapValues(schema, (value, recurse) => {
+    if (typeof value === 'object' && value !== null && '$ref' in value && typeof value.$ref === 'string') {
+      if (value.$ref.startsWith('#')) {
+        const resolved = jsonpointer.get(base, value.$ref.slice(1));
+        if (resolved) {
+          return recurse(resolved);
+        } else {
+          log.warn('unresolved', { ref: value.$ref, base });
+        }
+      }
+    }
+    return recurse(value);
+  });
+};
+
+const isV3_1 = (document: OpenAPIV3_1.Document | OpenAPIV2.Document): document is OpenAPIV3_1.Document => {
+  return (document as any).openapi === '3.0.1';
+};

package/src/translations.ts

@@ -0,0 +1,49 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import { ASSISTANT_PLUGIN } from './meta';
+import { AIChatType, TemplateType } from './types';
+
+export default [
+  {
+    'en-US': {
+      [AIChatType.typename]: {
+        'typename label': 'AI Chat',
+      },
+      [TemplateType.typename]: {
+        'typename label': 'Template',
+      },
+      [ASSISTANT_PLUGIN]: {
+        'chat title placeholder': 'AI Chat',
+        'template title placeholder': 'Template',
+
+        'open ambient chat label': 'Open AI chat',
+        'plugin name': 'Assistant',
+        'object placeholder': 'New prompt',
+        'create object label': 'Create prompt',
+        'create trigger label': 'Create trigger',
+        'create stack section label': 'Create prompt',
+        'command placeholder': 'Enter slash command...',
+        'template placeholder': 'Enter template...',
+        'value placeholder': 'Enter value...',
+        'select preset template placeholder': 'Select preset',
+        'service registry label': 'Service Registry',
+
+        'assistant dialog title': 'Assistant',
+        'open assistant label': 'Open assistant',
+
+        'chat input placeholder': 'Ask a question...',
+        'chat stop': 'Cancel request.',
+
+        'prompt placeholder': 'Ask a question...',
+        'microphone button': 'Click to speak',
+        'cancel processing button': 'Stop processing',
+
+        'settings custom prompts label': 'Custom prompts',
+        'settings llm model label': 'LLM model',
+        'settings default llm model label': 'Default Model',
+      },
+    },
+  },
+];

package/src/types/chat.ts

@@ -0,0 +1,11 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { Expando, Ref, S, TypedObject } from '@dxos/echo-schema';
+
+export class AIChatType extends TypedObject({ typename: 'dxos.org/type/AIChat', version: '0.1.0' })({
+  name: S.optional(S.String),
+  // TODO(wittjosiah): Should be a ref to a Queue.
+  queue: Ref(Expando),
+}) {}

package/src/types/index.ts

@@ -0,0 +1,8 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+export * from './chat';
+export * from './service';
+export * from './template';
+export * from './types';