@dxos/plugin-assistant 0.7.5-labs.a8b535d

package/src/hooks/useChatProcessor.tsx

@@ -0,0 +1,80 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { useEffect, useMemo, useState } from 'react';
+
+import { Capabilities, useCapabilities, useCapability, useIntentDispatcher } from '@dxos/app-framework';
+import { createSystemPrompt, type Tool } from '@dxos/artifact';
+import { DEFAULT_LLM_MODEL } from '@dxos/assistant';
+import { FunctionType } from '@dxos/functions';
+import { log } from '@dxos/log';
+import { useConfig } from '@dxos/react-client';
+import { Filter, type Space, useQuery } from '@dxos/react-client/echo';
+import { isNonNullable } from '@dxos/util';
+
+import { AssistantCapabilities } from '../capabilities';
+import { ChatProcessor } from '../hooks';
+import { covertFunctionToTool, createToolsFromService } from '../tools';
+import { type AssistantSettingsProps, ServiceType } from '../types';
+
+/**
+ * Configure and create ChatProcessor.
+ */
+export const useChatProcessor = (space?: Space, settings?: AssistantSettingsProps): ChatProcessor => {
+  const aiClient = useCapability(AssistantCapabilities.AiClient);
+  const globalTools = useCapabilities(Capabilities.Tools);
+  const artifactDefinitions = useCapabilities(Capabilities.ArtifactDefinition);
+  const { dispatchPromise: dispatch } = useIntentDispatcher();
+
+  // Services.
+  const services = useQuery(space, Filter.schema(ServiceType));
+  const [serviceTools, setServiceTools] = useState<Tool[]>([]);
+  useEffect(() => {
+    log('creating service tools...');
+    queueMicrotask(async () => {
+      const tools = await Promise.all(services.map((service) => createToolsFromService(service)));
+      setServiceTools(tools.flat());
+    });
+  }, [services]);
+
+  // Tools and context.
+  const config = useConfig();
+  const functions = useQuery(space, Filter.schema(FunctionType));
+  const [tools, extensions] = useMemo(() => {
+    log('creating tools...');
+    const tools = [
+      ...globalTools.flat(),
+      ...artifactDefinitions.flatMap((definition) => definition.tools),
+      ...serviceTools,
+      ...functions
+        .map((fn) => covertFunctionToTool(fn, config.values.runtime?.services?.edge?.url ?? '', space?.id))
+        .filter(isNonNullable),
+    ];
+    const extensions = { space, dispatch };
+    return [tools, extensions];
+  }, [dispatch, globalTools, artifactDefinitions, space, serviceTools, functions]);
+
+  // Prompt.
+  const systemPrompt = useMemo(
+    () =>
+      createSystemPrompt({
+        artifacts: artifactDefinitions.map((definition) => definition.instructions),
+      }),
+    [artifactDefinitions],
+  );
+
+  // Create processor.
+  // TODO(burdon): Updated on each query update above. Should just update current processor.
+  const processor = useMemo(() => {
+    log('creating processor...', { settings });
+    return new ChatProcessor(aiClient, tools, extensions, {
+      // TODO(burdon): Remove defualt (let backend decide if not specified).
+      model: settings?.llmModel ?? DEFAULT_LLM_MODEL,
+      // TOOD(burdon): Query.
+      systemPrompt,
+    });
+  }, [aiClient, tools, extensions, systemPrompt, settings?.llmModel]);
+
+  return processor;
+};

package/src/hooks/useLocalTriggerManager.ts

@@ -0,0 +1,82 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { useEffect, useState } from 'react';
+
+import { Mutex } from '@dxos/async';
+import { Context } from '@dxos/context';
+import { createSubscriptionTrigger, type TriggerFactory } from '@dxos/functions';
+import { FunctionTrigger } from '@dxos/functions';
+import { invariant } from '@dxos/invariant';
+import { log } from '@dxos/log';
+import { useClient } from '@dxos/react-client';
+import { Filter, type Space, useQuery } from '@dxos/react-client/echo';
+
+import { invokeFunction } from './invocation-handler';
+
+const registerTriggersMutex = new Mutex();
+
+export const useLocalTriggerManager = (space: Space) => {
+  const client = useClient();
+
+  // TODO(burdon): Factor out, creating context for plugin (runs outside of component).
+  const [registry] = useState(new Map<string, Context>());
+  const triggers = useQuery(space, Filter.schema(FunctionTrigger));
+  useEffect(() => {
+    setTimeout(async () => {
+      // Mark-and-sweep removing disabled triggers.
+      await registerTriggersMutex.executeSynchronized(async () => {
+        const deprecated = new Set(Array.from(registry.keys()));
+        log('triggers', {
+          deprecated,
+          all: triggers.map((t) => t.id),
+          enabled: triggers.filter((t) => t.enabled).map((t) => t.id),
+        });
+
+        for (const trigger of triggers) {
+          if (trigger.enabled) {
+            if (registry.has(trigger.id)) {
+              deprecated.delete(trigger.id);
+              continue;
+            }
+            log.info('activating trigger', trigger.id);
+
+            const ctx = new Context();
+            registry.set(trigger.id, ctx);
+            const triggerSpec = trigger.spec;
+            invariant(triggerSpec);
+
+            let triggerFactory: TriggerFactory<any>;
+            if (triggerSpec.type === 'subscription') {
+              triggerFactory = createSubscriptionTrigger;
+            } else {
+              log.info('unsupported trigger', { type: triggerSpec.type });
+              continue;
+            }
+
+            await triggerFactory(ctx, space, trigger.spec, (data: any) => {
+              return invokeFunction(client, space, trigger, data);
+            });
+          }
+        }
+
+        for (const id of deprecated) {
+          const ctx = registry.get(id);
+          if (ctx) {
+            await ctx.dispose();
+            registry.delete(id);
+          }
+        }
+      });
+    });
+  }, [JSON.stringify(triggers)]);
+
+  useEffect(() => {
+    return () => {
+      for (const ctx of registry.values()) {
+        void ctx.dispose();
+      }
+    };
+  }, []);
+};

package/src/hooks/useMessageQueue.ts

@@ -0,0 +1,23 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { useMemo } from 'react';
+
+import { type Message } from '@dxos/artifact';
+import { DXN, QueueSubspaceTags } from '@dxos/keys';
+import { getSpace } from '@dxos/react-client/echo';
+import { useEdgeClient, useQueue } from '@dxos/react-edge-client';
+
+import { type AIChatType } from '../types';
+
+export const useMessageQueue = (chat?: AIChatType) => {
+  const space = getSpace(chat);
+  const queueDxn = useMemo(() => {
+    const dxn = space && chat?.queue.dxn;
+    return dxn ? new DXN(DXN.kind.QUEUE, [QueueSubspaceTags.DATA, space.id, dxn.parts.at(-1)!]) : undefined;
+  }, [space, chat?.queue.dxn]);
+
+  const edgeClient = useEdgeClient();
+  return useQueue<Message>(edgeClient, queueDxn);
+};

package/src/hooks/useServices.ts

@@ -0,0 +1,28 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { useEffect, useMemo, useState } from 'react';
+
+import { type Space } from '@dxos/client/echo';
+
+import { MockServiceRegistry } from '../testing';
+import { type ServiceType, type ServiceQuery } from '../types';
+
+/**
+ * Retrieves matching services from the registry.
+ */
+export const useServices = (space: Space, query?: ServiceQuery): ServiceType[] => {
+  const registry = useMemo(() => new MockServiceRegistry(), []);
+  const [services, setServices] = useState<ServiceType[]>([]);
+  useEffect(() => {
+    const t = setTimeout(async () => {
+      const services = await registry.queryServices(query);
+      setServices(services);
+    });
+
+    return () => clearTimeout(t);
+  }, [query, registry]);
+
+  return services;
+};

package/src/hooks/useTextInputEvents.ts

@@ -0,0 +1,49 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { useState, useCallback, type KeyboardEventHandler, type ChangeEventHandler } from 'react';
+
+/**
+ * Hook that handles text input events.
+ */
+// TODO(burdon): Factor out.
+export const useTextInputEvents = ({
+  onEnter,
+  onEscape,
+}: {
+  onEnter?: (text: string) => boolean | void;
+  onEscape?: () => void;
+}) => {
+  const [value, setValue] = useState('');
+
+  const onKeyDown = useCallback<KeyboardEventHandler<HTMLInputElement>>(
+    (ev) => {
+      switch (ev.key) {
+        case 'Escape': {
+          onEscape?.();
+          setValue('');
+          break;
+        }
+
+        case 'Enter': {
+          const value = (ev.target as HTMLInputElement).value.trim();
+          if (value.length > 0) {
+            const reset = onEnter?.(value);
+            if (reset) {
+              setValue('');
+            }
+          }
+          break;
+        }
+      }
+    },
+    [onEnter, onEscape],
+  );
+
+  const onChange = useCallback<ChangeEventHandler<HTMLInputElement>>((ev) => {
+    setValue(ev.target.value);
+  }, []);
+
+  return [{ value, onKeyDown, onChange }, setValue];
+};

package/src/index.ts

@@ -0,0 +1,9 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+export * from './components';
+export * from './meta';
+export * from './types';
+
+export * from './AssistantPlugin';

package/src/meta.ts

@@ -0,0 +1,18 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import { type PluginMeta } from '@dxos/app-framework';
+
+export const ASSISTANT_PLUGIN = 'dxos.org/plugin/assistant';
+
+export const ASSISTANT_DIALOG = `${ASSISTANT_PLUGIN}/assistant/dialog`;
+
+export const meta = {
+  id: ASSISTANT_PLUGIN,
+  name: 'Assistant',
+  description: 'The Assistant tab allows you to chat with your spaces inside of Composer.',
+  icon: 'ph--atom--regular',
+  source: 'https://github.com/dxos/dxos/tree/main/packages/plugins/experimental/plugin-assistant',
+  tags: ['experimental'],
+} satisfies PluginMeta;

package/src/testing/index.ts

@@ -0,0 +1,6 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+export * from './test-functions';
+export * from './test-services';

package/src/testing/test-functions.ts

@@ -0,0 +1,11 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { createSystemPrompt } from '@dxos/artifact';
+import { DEFAULT_LLM_MODEL, type GenerateRequest } from '@dxos/assistant';
+
+export const createProcessorOptions = (artifacts: string[]): Pick<GenerateRequest, 'model' | 'systemPrompt'> => ({
+  model: DEFAULT_LLM_MODEL,
+  systemPrompt: createSystemPrompt({ artifacts }),
+});

package/src/testing/test-services.ts

@@ -0,0 +1,131 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { createStatic } from '@dxos/echo-schema';
+
+import {
+  type ApiAuthorization,
+  type BaseServiceRegistry,
+  type ServiceQuery,
+  ServiceType,
+  categoryIcons,
+} from '../types';
+
+export class MockServiceRegistry implements BaseServiceRegistry {
+  async queryServices(query?: ServiceQuery): Promise<ServiceType[]> {
+    return TEST_SERVICES;
+  }
+}
+
+// TODO(burdon): Can we generalize credentials?
+
+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',
+  },
+};
+
+// Registries:
+//  - https://apis.guru
+//  - https://rapidapi.com
+//  - https://github.com/konfig-sdks/openapi-examples
+//  - https://publicapis.io/?utm_source=chatgpt.com
+
+// Examples:
+//  - https://petstore.swagger.io/v2/swagger.json (testing)
+//  - https://lichess.org/api
+//  - https://github.com/konfig-sdks/openapi-examples/tree/main/xkcd
+//  - https://api.coindesk.com/v1/bpi/currentprice.json
+//  - https://www.coingecko.com/en/api/documentation
+
+// TODO(burdon): Support yaml endpoints.
+//  - e.g., https://github.com/konfig-sdks/openapi-examples/blob/main/xkcd/openapi.yaml
+
+const TEST_SERVICES: ServiceType[] = [
+  createStatic(ServiceType, {
+    serviceId: 'amadeus.com/service/FlightSearch',
+    name: 'Amadeus Flight Search',
+    description: 'Search for local and international flights.',
+    category: 'travel',
+    interfaces: [
+      {
+        kind: 'api',
+        schemaUrl: 'https://api.apis.guru/v2/specs/amadeus.com/amadeus-flight-availabilities-search/1.0.2/swagger.json',
+        authorization: AMADEUS_AUTH,
+      },
+    ],
+  }),
+
+  createStatic(ServiceType, {
+    serviceId: 'amadeus.com/service/HotelSearch',
+    name: 'Amadeus Hotel Search',
+    description: 'Search for local and international hotels.',
+    category: 'travel',
+    interfaces: [
+      {
+        kind: 'api',
+        schemaUrl: 'https://api.apis.guru/v2/specs/amadeus.com/amadeus-hotel-search/3.0.8/swagger.json',
+        authorization: AMADEUS_AUTH,
+      },
+    ],
+  }),
+
+  createStatic(ServiceType, {
+    serviceId: 'visualcrossing.com/service/Weather',
+    name: 'Visual Crossing Weather',
+    description: 'Search for global weather forecasts.',
+    category: 'weather',
+    interfaces: [
+      {
+        kind: 'api',
+        schemaUrl: 'https://api.apis.guru/v2/specs/visualcrossing.com/weather/4.6/openapi.json',
+        authorization: VISUAL_CROSSING_CREDENTIALS,
+      },
+    ],
+  }),
+
+  // TODO(burdon): Needs auth.
+  createStatic(ServiceType, {
+    serviceId: 'abstractapi.com/service/GeoLocation',
+    name: 'Abstract GeoLocation',
+    description: 'Get the location of any IP address.',
+    category: 'geolocation',
+    interfaces: [
+      {
+        kind: 'api',
+        schemaUrl: 'https://api.apis.guru/v2/specs/abstractapi.com/geolocation/1.0.0/openapi.json',
+      },
+    ],
+  }),
+
+  //
+  // Testing
+  //
+
+  ...Array.from({ length: 20 }, (_, i) =>
+    createStatic(ServiceType, {
+      serviceId: `example.com/service/test-${i}`,
+      name: `Test ${i}`,
+      description: `Test ${i}`,
+      category: Object.keys(categoryIcons)[Math.floor(Math.random() * Object.keys(categoryIcons).length)],
+      interfaces: [
+        {
+          kind: 'api',
+          schemaUrl: 'https://petstore.swagger.io/v2/swagger.json',
+        },
+      ],
+    }),
+  ),
+] as const;

package/src/tools/function.ts

@@ -0,0 +1,47 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { defineTool, ToolResult } from '@dxos/artifact';
+import type { Tool } from '@dxos/artifact';
+import { toEffectSchema } from '@dxos/echo-schema';
+import { getInvocationUrl, getUserFunctionUrlInMetadata } from '@dxos/functions';
+import type { FunctionType } from '@dxos/functions';
+import { log } from '@dxos/log';
+import type { SpaceId } from '@dxos/react-client/echo';
+import { getMeta } from '@dxos/react-client/echo';
+
+export const covertFunctionToTool = (
+  fn: FunctionType,
+  edgeUrl: string,
+  spaceId?: SpaceId | undefined,
+): Tool | undefined => {
+  if (!fn.description || !fn.inputSchema) {
+    return undefined;
+  }
+
+  const existingFunctionUrl = getUserFunctionUrlInMetadata(getMeta(fn));
+  if (!existingFunctionUrl) {
+    return undefined;
+  }
+  const url = getInvocationUrl(existingFunctionUrl, edgeUrl, {
+    spaceId,
+  });
+
+  return defineTool('user-function', {
+    name: fn.name,
+    description: fn.description,
+    schema: toEffectSchema(fn.inputSchema),
+    execute: async (input) => {
+      log.info('execute function tool', { name: fn.name, url, input });
+      const response = await fetch(url, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+        },
+        body: JSON.stringify(input),
+      });
+      return ToolResult.Success(await response.text());
+    },
+  });
+};

package/src/tools/index.ts

@@ -0,0 +1,6 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export * from './function';
+export * from './openapi';