@dxos/plugin-assistant 0.8.2-main.f11618f → 0.8.2-staging.42af850

package/src/testing/blueprint.ts

@@ -0,0 +1,47 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type ExecutableTool } from '@dxos/ai';
+import { EXA_API_KEY } from '@dxos/ai/testing';
+import { type BlueprintParser, createExaTool, createGraphWriterTool, createLocalSearchTool } from '@dxos/assistant';
+import { type Space } from '@dxos/client/echo';
+import { type DXN } from '@dxos/keys';
+import { DataTypes } from '@dxos/schema';
+import { isNonNullable } from '@dxos/util';
+
+// TODO(dmaretskyi): make db available through services (same as function executor).
+// TODO(burdon): Can tools implement "aspects" so that variants can be used rather than an explicit reference?
+export const createTools = (space: Space, queueDxn?: DXN): ExecutableTool[] => {
+  return [
+    createExaTool({ apiKey: EXA_API_KEY }),
+    createLocalSearchTool(space.db),
+    queueDxn &&
+      createGraphWriterTool({
+        db: space.db,
+        schemaTypes: DataTypes,
+        onDone: async (objects) => {
+          const queue = space.queues.get(queueDxn);
+          queue.append(objects);
+        },
+      }),
+  ].filter(isNonNullable);
+};
+
+export const RESEARCH_BLUEPRINT: BlueprintParser.DSL = {
+  steps: [
+    {
+      instructions: 'Research information and entities related to the selected objects.',
+      tools: ['search/web_search'],
+    },
+    {
+      instructions:
+        'Based on your research find matching entires that are already in the graph. Do exaustive research.',
+      tools: ['search/local_search'],
+    },
+    {
+      instructions: 'Add researched data to the graph. Make connections to existing objects.',
+      tools: ['search/local_search', 'graph/writer'],
+    },
+  ],
+};

package/src/testing/index.ts

@@ -2,5 +2,6 @@
 // Copyright 2024 DXOS.org
 //
 
+export * from './blueprint';
 export * from './test-functions';
 export * from './test-services';

package/src/testing/test-functions.ts

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

package/src/tools/function.ts

@@ -2,33 +2,31 @@
 // Copyright 2025 DXOS.org
 //
 
-import { defineTool, ToolResult } from '@dxos/artifact';
-import type { Tool } from '@dxos/artifact';
+import { createTool, type ExecutableTool, ToolResult } from '@dxos/ai';
 import { toEffectSchema } from '@dxos/echo-schema';
-import { getInvocationUrl, getUserFunctionUrlInMetadata } from '@dxos/functions/types';
-import type { FunctionType } from '@dxos/functions/types';
+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 { type SpaceId } from '@dxos/react-client/echo';
 import { getMeta } from '@dxos/react-client/echo';
 
-export const covertFunctionToTool = (
+// TODO(burdon): Move to @dxos/ai.
+export const convertFunctionToTool = (
   fn: FunctionType,
   edgeUrl: string,
   spaceId?: SpaceId | undefined,
-): Tool | undefined => {
+): ExecutableTool | 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', {
+  const url = getInvocationUrl(existingFunctionUrl, edgeUrl, { spaceId });
+
+  return createTool('user-function', {
     name: fn.name,
     description: fn.description,
     schema: toEffectSchema(fn.inputSchema),
@@ -41,6 +39,7 @@ export const covertFunctionToTool = (
         },
         body: JSON.stringify(input),
       });
+
       return ToolResult.Success(await response.text());
     },
   });

package/src/tools/openapi.test.ts

@@ -4,8 +4,8 @@
 
 import { describe, expect, test } from 'vitest';
 
-import { AIServiceEdgeClient } from '@dxos/assistant';
-import { AI_SERVICE_ENDPOINT } from '@dxos/assistant/testing';
+import { AIServiceEdgeClient } from '@dxos/ai';
+import { AI_SERVICE_ENDPOINT } from '@dxos/ai/testing';
 import { log } from '@dxos/log';
 
 import { createToolsFromApi, resolveAuthorization } from './openapi';
@@ -43,12 +43,14 @@ describe.skip('openapi', () => {
   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',
-      });
+      const result = await tools[0].execute(
+        {
+          keyword: 'William Vale Brooklyn',
+          subType: ['HOTEL_LEISURE', 'HOTEL_GDS'],
+          countryCode: 'US',
+        },
+        {},
+      );
 
       log.info('result', { result });
     });
@@ -56,11 +58,13 @@ describe.skip('openapi', () => {
     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',
-      });
+      const result = await forecastTool?.execute(
+        {
+          locations: 'Brooklyn, NY',
+          aggregateHours: '24',
+        },
+        {},
+      );
 
       log.info('result', { result });
     });
@@ -68,10 +72,7 @@ describe.skip('openapi', () => {
 
   describe.skip('AI uses tools', () => {
     test('amadeus flight availabilities', { timeout: 60_000 }, async () => {
-      const tools = await createToolsFromApi(FLIGHT_SEARCH_API, {
-        authorization: AMADEUS_AUTH,
-      });
-
+      const tools = await createToolsFromApi(FLIGHT_SEARCH_API, { authorization: AMADEUS_AUTH });
       const client = new AIServiceEdgeClient({
         endpoint: AI_SERVICE_ENDPOINT.LOCAL,
       });
@@ -86,7 +87,6 @@ describe.skip('openapi', () => {
     // 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 AIServiceEdgeClient({
         endpoint: AI_SERVICE_ENDPOINT.LOCAL,
       });
@@ -101,7 +101,6 @@ describe.skip('openapi', () => {
         authorization: VISUAL_CROSSING_CREDENTIALS,
         instructions: WEATHER_INSTRUCTIONS,
       });
-
       const client = new AIServiceEdgeClient({
         endpoint: AI_SERVICE_ENDPOINT.LOCAL,
       });

package/src/tools/openapi.ts

@@ -2,11 +2,12 @@
 // Copyright 2025 DXOS.org
 //
 
+import { Schema } from 'effect';
 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 { type ExecutableTool, ToolResult, createRawTool } from '@dxos/ai';
+import { JsonSchemaType, normalizeSchema, toEffectSchema } from '@dxos/echo-schema';
 import { invariant } from '@dxos/invariant';
 import { log } from '@dxos/log';
 import { deepMapValues } from '@dxos/util';
@@ -18,7 +19,7 @@ export type CreateToolsFromApiOptions = {
   instructions?: string;
 };
 
-export const createToolsFromService = async (service: ServiceType): Promise<Tool[]> => {
+export const createToolsFromService = async (service: ServiceType): Promise<ExecutableTool[]> => {
   invariant(service.interfaces?.length === 1 && service.interfaces[0].kind === 'api');
   const iface = service.interfaces[0];
   invariant(iface.schemaUrl);
@@ -26,18 +27,20 @@ export const createToolsFromService = async (service: ServiceType): Promise<Tool
   return createToolsFromApi(iface.schemaUrl, { authorization: iface.authorization });
 };
 
-export const createToolsFromApi = async (url: string, options?: CreateToolsFromApiOptions): Promise<Tool[]> => {
+export const createToolsFromApi = async (
+  url: string,
+  options?: CreateToolsFromApiOptions,
+): Promise<ExecutableTool[]> => {
   const res = await fetch(url);
   const spec = (await res.json()) as OpenAPIV2.Document;
   log('spec', { spec });
 
-  const tools: Tool[] = [];
+  const tools: ExecutableTool[] = [];
   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;
@@ -49,6 +52,7 @@ export const createToolsFromApi = async (url: string, options?: CreateToolsFromA
           return resolved;
         }) ?? [];
 
+      // TODO(burdon): Reconcile with toFunctionParameterSchema.
       const inputSchema: JsonSchemaType = {
         type: 'object',
         properties: {},
@@ -82,7 +86,7 @@ export const createToolsFromApi = async (url: string, options?: CreateToolsFromA
       }
 
       log('inputSchema', { inputSchema });
-      S.validateSync(JsonSchemaType)(inputSchema);
+      Schema.validateSync(JsonSchemaType)(inputSchema);
 
       const description = methodItem.description ?? methodItem.summary;
       if (!description) {
@@ -98,15 +102,18 @@ export const createToolsFromApi = async (url: string, options?: CreateToolsFromA
         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);
-        },
-      });
+      tools.push(
+        // TODO(burdon): Namespace?
+        createRawTool('openapi', {
+          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);
+          },
+        }),
+      );
     }
   }
 
@@ -200,7 +207,7 @@ const callApiEndpoint = async (endpoint: EndpointDescriptor, input: any) => {
 
         // Client-side validation
         const effectSchema = toEffectSchema(parameter.schema);
-        S.validateSync(effectSchema)(value);
+        Schema.validateSync(effectSchema)(value);
 
         if (body) {
           throw new Error(`Duplicate body parameter: ${parameter.name}`);

package/src/translations.ts

@@ -2,13 +2,15 @@
 // Copyright 2023 DXOS.org
 //
 
+import { getSchemaTypename } from '@dxos/echo-schema';
+
 import { ASSISTANT_PLUGIN } from './meta';
 import { AIChatType, TemplateType } from './types';
 
 export default [
   {
     'en-US': {
-      [AIChatType.typename]: {
+      [getSchemaTypename(AIChatType)!]: {
         'typename label': 'Assistant',
         'object name placeholder': 'AI Chat',
       },
@@ -18,7 +20,6 @@ export default [
       },
       [ASSISTANT_PLUGIN]: {
         'templates label': 'Templates',
-
         'open ambient chat label': 'Open Assistant',
         'assistant chat label': 'Assistant',
         'plugin name': 'Assistant',
@@ -38,6 +39,7 @@ export default [
         'assistant dialog title': 'Assistant',
         'open assistant label': 'Open assistant',
 
+        'search input placeholder': 'Search...',
         'chat input placeholder': 'Ask a question...',
         'chat stop': 'Cancel request.',
 

package/src/types/chat.ts

@@ -2,9 +2,32 @@
 // Copyright 2024 DXOS.org
 //
 
-import { Expando, Ref, TypedObject } from '@dxos/echo-schema';
+import { Schema } from 'effect';
 
-export class AIChatType extends TypedObject({ typename: 'dxos.org/type/AIChat', version: '0.1.0' })({
+import { Type } from '@dxos/echo';
+import { Expando, Ref } from '@dxos/echo-schema';
+
+export const AIChatType = Schema.Struct({
+  id: Type.ObjectId,
+  name: Schema.optional(Schema.String),
   // TODO(wittjosiah): Should be a ref to a Queue.
-  assistantChatQueue: Ref(Expando),
-}) {}
+  queue: Ref(Expando),
+}).pipe(
+  Type.Obj({
+    typename: 'dxos.org/type/AIChat',
+    version: '0.2.0',
+  }),
+);
+export interface AIChatType extends Schema.Schema.Type<typeof AIChatType> {}
+
+export const CompanionTo = Schema.Struct({
+  id: Type.ObjectId,
+}).pipe(
+  Type.Relation({
+    typename: 'dxos.org/relation/CompanionTo',
+    version: '0.1.0',
+    source: AIChatType,
+    target: Expando,
+  }),
+);
+export interface CompanionTo extends Schema.Schema.Type<typeof CompanionTo> {}

package/src/types/service.ts

@@ -2,78 +2,80 @@
 // Copyright 2024 DXOS.org
 //
 
+import { Schema } from 'effect';
+
 import { ComputeGraph } from '@dxos/conductor';
-import { Ref, S, TypedObject, type Ref$ } from '@dxos/echo-schema';
-import { FunctionType } from '@dxos/functions/types';
-
-const ApiAuthorizationKey = S.Struct({
-  type: S.Literal('api-key'),
-  key: S.String,
-  placement: S.Union(
-    S.Struct({
-      type: S.Literal('authorization-header'),
+import { Ref, TypedObject, type Ref$ } from '@dxos/echo-schema';
+import { FunctionType } from '@dxos/functions';
+
+const ApiAuthorizationKey = Schema.Struct({
+  type: Schema.Literal('api-key'),
+  key: Schema.String,
+  placement: Schema.Union(
+    Schema.Struct({
+      type: Schema.Literal('authorization-header'),
     }),
-    S.Struct({
-      type: S.Literal('query'),
-      name: S.String,
+    Schema.Struct({
+      type: Schema.Literal('query'),
+      name: Schema.String,
     }),
   ),
 });
 
-const ApiAuthorizationOauth = S.Struct({
-  type: S.Literal('oauth'),
-  clientId: S.String,
-  clientSecret: S.String,
-  tokenUrl: S.String,
-  grantType: S.String,
+const ApiAuthorizationOauth = Schema.Struct({
+  type: Schema.Literal('oauth'),
+  clientId: Schema.String,
+  clientSecret: Schema.String,
+  tokenUrl: Schema.String,
+  grantType: Schema.String,
 });
 
-export const ApiAuthorization = S.Union(ApiAuthorizationKey, ApiAuthorizationOauth);
-export type ApiAuthorization = S.Schema.Type<typeof ApiAuthorization>;
+export const ApiAuthorization = Schema.Union(ApiAuthorizationKey, ApiAuthorizationOauth);
+export type ApiAuthorization = Schema.Schema.Type<typeof ApiAuthorization>;
 
-const ServiceInterfaceFunction = S.Struct({
-  kind: S.Literal('function'),
+const ServiceInterfaceFunction = Schema.Struct({
+  kind: Schema.Literal('function'),
   fn: Ref(FunctionType) as Ref$<FunctionType>,
 });
 
-const ServiceInterfaceWorkflow = S.Struct({
-  kind: S.Literal('workflow'),
+const ServiceInterfaceWorkflow = Schema.Struct({
+  kind: Schema.Literal('workflow'),
   workflow: Ref(ComputeGraph) as Ref$<ComputeGraph>,
 });
 
-const ServiceInterfaceApi = S.Struct({
-  kind: S.Literal('api'),
+const ServiceInterfaceApi = Schema.Struct({
+  kind: Schema.Literal('api'),
 
   /**
    * URL to fetch the openapi schema.
    */
-  schemaUrl: S.optional(S.String),
+  schemaUrl: Schema.optional(Schema.String),
 
   /**
    * Inlined openapi schema.
    */
-  schema: S.optional(S.Any),
+  schema: Schema.optional(Schema.Any),
 
   /**
    * Authorization configuration if required.
    */
-  authorization: S.optional(ApiAuthorization),
+  authorization: Schema.optional(ApiAuthorization),
 });
 
-const ServiceInterface = S.Union(ServiceInterfaceFunction, ServiceInterfaceWorkflow, ServiceInterfaceApi);
-export type ServiceInterface = S.Schema.Type<typeof ServiceInterface>;
+const ServiceInterface = Schema.Union(ServiceInterfaceFunction, ServiceInterfaceWorkflow, ServiceInterfaceApi);
+export type ServiceInterface = Schema.Schema.Type<typeof ServiceInterface>;
 
 export class ServiceType extends TypedObject({ typename: 'dxos.org/type/ServiceType', version: '0.1.0' })({
-  serviceId: S.String,
-  name: S.optional(S.String),
-  description: S.optional(S.String),
-  category: S.optional(S.String),
-  enabled: S.optional(S.Boolean),
+  serviceId: Schema.String,
+  name: Schema.optional(Schema.String),
+  description: Schema.optional(Schema.String),
+  category: Schema.optional(Schema.String),
+  enabled: Schema.optional(Schema.Boolean),
 
   /**
    * Entries exposed: functions, workflows, and APIs.
    */
-  interfaces: S.optional(S.Array(ServiceInterface)),
+  interfaces: Schema.optional(Schema.Array(ServiceInterface)),
 }) {}
 
 //

package/src/types/template.ts

@@ -2,9 +2,11 @@
 // Copyright 2024 DXOS.org
 //
 
-import { S, TypedObject } from '@dxos/echo-schema';
+import { Schema } from 'effect';
 
-// TODO(burdon): Change to S.Literal (and discriminated union).
+import { TypedObject } from '@dxos/echo-schema';
+
+// TODO(burdon): Change to Schema.Literal (and discriminated union).
 export enum TemplateInputType {
   VALUE = 0,
   PASS_THROUGH = 1,
@@ -16,41 +18,41 @@ export enum TemplateInputType {
   SCHEMA = 7,
 }
 
-export const TemplateInputSchema = S.mutable(
-  S.Struct({
-    name: S.String,
-    type: S.optional(S.Enums(TemplateInputType)),
-    value: S.optional(S.String),
+export const TemplateInputSchema = Schema.mutable(
+  Schema.Struct({
+    name: Schema.String,
+    type: Schema.optional(Schema.Enums(TemplateInputType)),
+    value: Schema.optional(Schema.String),
   }),
 );
 
-export type TemplateInput = S.Schema.Type<typeof TemplateInputSchema>;
+export type TemplateInput = Schema.Schema.Type<typeof TemplateInputSchema>;
 
 export const TemplateKinds = ['always', 'schema-matching', 'automatically', 'manual'] as const;
 export type TemplateKind = (typeof TemplateKinds)[number];
 
-export const TemplateKindSchema = S.Union(
-  S.Struct({
-    include: S.Literal('always'),
+export const TemplateKindSchema = Schema.Union(
+  Schema.Struct({
+    include: Schema.Literal('always'),
   }),
-  S.Struct({
-    include: S.Literal('schema-matching'),
-    typename: S.String,
+  Schema.Struct({
+    include: Schema.Literal('schema-matching'),
+    typename: Schema.String,
   }),
-  S.Struct({
-    include: S.Literal('automatically'),
-    description: S.String,
+  Schema.Struct({
+    include: Schema.Literal('automatically'),
+    description: Schema.String,
   }),
-  S.Struct({
-    include: S.Literal('manual'),
+  Schema.Struct({
+    include: Schema.Literal('manual'),
   }),
 );
 
-export type TemplateKindType = S.Schema.Type<typeof TemplateKindSchema>;
+export type TemplateKindType = Schema.Schema.Type<typeof TemplateKindSchema>;
 export class TemplateType extends TypedObject({ typename: 'dxos.org/type/Template', version: '0.1.0' })({
-  name: S.optional(S.String),
-  kind: S.mutable(TemplateKindSchema),
-  source: S.String,
-  inputs: S.optional(S.mutable(S.Array(TemplateInputSchema))),
-  command: S.optional(S.String),
+  name: Schema.optional(Schema.String),
+  kind: Schema.mutable(TemplateKindSchema),
+  source: Schema.String,
+  inputs: Schema.optional(Schema.mutable(Schema.Array(TemplateInputSchema))),
+  command: Schema.optional(Schema.String),
 }) {}

package/src/types/types.ts

@@ -2,7 +2,9 @@
 // Copyright 2025 DXOS.org
 //
 
-import { S } from '@dxos/echo-schema';
+import { Schema } from 'effect';
+
+import { SpaceSchema } from '@dxos/react-client/echo';
 
 import { AIChatType } from './chat';
 import { TemplateType } from './template';
@@ -11,21 +13,21 @@ import { ASSISTANT_PLUGIN } from '../meta';
 export namespace AssistantAction {
   const ASSISTANT_ACTION = `${ASSISTANT_PLUGIN}/action`;
 
-  export class CreateChat extends S.TaggedClass<CreateChat>()(`${ASSISTANT_ACTION}/create-chat`, {
-    input: S.Struct({
-      spaceId: S.optional(S.String),
-      name: S.optional(S.String),
+  export class CreateChat extends Schema.TaggedClass<CreateChat>()(`${ASSISTANT_ACTION}/create-chat`, {
+    input: Schema.Struct({
+      space: SpaceSchema,
+      name: Schema.optional(Schema.String),
     }),
-    output: S.Struct({
+    output: Schema.Struct({
       object: AIChatType,
     }),
   }) {}
 
-  export class CreateTemplate extends S.TaggedClass<CreateTemplate>()(`${ASSISTANT_ACTION}/create-template`, {
-    input: S.Struct({
-      name: S.optional(S.String),
+  export class CreateTemplate extends Schema.TaggedClass<CreateTemplate>()(`${ASSISTANT_ACTION}/create-template`, {
+    input: Schema.Struct({
+      name: Schema.optional(Schema.String),
     }),
-    output: S.Struct({
+    output: Schema.Struct({
       object: TemplateType,
     }),
   }) {}
@@ -33,14 +35,14 @@ export namespace AssistantAction {
 
 export const LLM_PROVIDERS = ['edge', 'ollama', 'lmstudio'] as const;
 
-export const AssistantSettingsSchema = S.mutable(
-  S.Struct({
-    llmProvider: S.optional(S.Literal(...LLM_PROVIDERS)),
-    edgeModel: S.optional(S.String),
-    ollamaModel: S.optional(S.String),
-    lmstudioModel: S.optional(S.String),
-    customPrompts: S.optional(S.Boolean),
+export const AssistantSettingsSchema = Schema.mutable(
+  Schema.Struct({
+    llmProvider: Schema.optional(Schema.Literal(...LLM_PROVIDERS)),
+    edgeModel: Schema.optional(Schema.String),
+    ollamaModel: Schema.optional(Schema.String),
+    lmstudioModel: Schema.optional(Schema.String),
+    customPrompts: Schema.optional(Schema.Boolean),
   }),
 );
 
-export type AssistantSettingsProps = S.Schema.Type<typeof AssistantSettingsSchema>;
+export type AssistantSettingsProps = Schema.Schema.Type<typeof AssistantSettingsSchema>;