@dxos/assistant-toolkit 0.8.4-main.1068cf700f

package/src/toolkits/AssistantToolkit.ts

@@ -0,0 +1,70 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Tool from '@effect/ai/Tool';
+import * as Toolkit from '@effect/ai/Toolkit';
+import * as Effect from 'effect/Effect';
+import * as Record from 'effect/Record';
+import * as Schema from 'effect/Schema';
+
+import { AiContextService, ArtifactId } from '@dxos/assistant';
+import { Database, type Ref } from '@dxos/echo';
+import { trim } from '@dxos/util';
+
+export const AssistantToolkit = Toolkit.make(
+  Tool.make('context-add', {
+    description: trim`
+      Adds the object to the chat context.
+    `,
+    parameters: {
+      id: ArtifactId.annotations({
+        description: 'The ID of the document to add.',
+      }),
+    },
+    success: Schema.Void,
+    failure: Schema.Never,
+    dependencies: [AiContextService, Database.Service],
+  }),
+  Tool.make('context-remove', {
+    description: trim`
+      Removes the object from the chat context.
+    `,
+    parameters: {
+      id: ArtifactId.annotations({
+        description: 'The ID of the document to remove.',
+      }),
+    },
+    success: Schema.Void,
+    failure: Schema.Never,
+    dependencies: [AiContextService, Database.Service],
+  }),
+);
+
+export const tools = Record.keys(AssistantToolkit.tools);
+
+export const layer = () =>
+  AssistantToolkit.toLayer({
+    ['context-add' as const]: Effect.fnUntraced(function* ({ id }) {
+      const { binder } = yield* AiContextService;
+      const { db } = yield* Database.Service;
+      const ref = db.makeRef(ArtifactId.toDXN(id, db.spaceId)) as Ref.Ref<any>;
+      yield* Effect.promise(() =>
+        binder.bind({
+          blueprints: [],
+          objects: [ref],
+        }),
+      );
+    }),
+    ['context-remove' as const]: Effect.fnUntraced(function* ({ id }) {
+      const { binder } = yield* AiContextService;
+      const { db } = yield* Database.Service;
+      const ref = db.makeRef(ArtifactId.toDXN(id, db.spaceId)) as Ref.Ref<any>;
+      yield* Effect.promise(() =>
+        binder.unbind({
+          blueprints: [],
+          objects: [ref],
+        }),
+      );
+    }),
+  });

package/src/toolkits/SystemToolkit.ts

@@ -0,0 +1,299 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Tool from '@effect/ai/Tool';
+import * as Toolkit from '@effect/ai/Toolkit';
+import * as Effect from 'effect/Effect';
+import type * as Layer from 'effect/Layer';
+import * as Record from 'effect/Record';
+import * as Schema from 'effect/Schema';
+
+import { ArtifactId } from '@dxos/assistant';
+import { DXN, Database, Entity, Filter, Obj, Relation, Tag, Type } from '@dxos/echo';
+import { invariant } from '@dxos/invariant';
+import { trim } from '@dxos/util';
+
+export const SystemToolkit = Toolkit.make(
+  //
+  // Schema
+  //
+
+  Tool.make('schema-list', {
+    description: trim`
+      Lists schemas definitions.
+    `,
+    parameters: {
+      // TODO(wittjosiah): Remove this once parameter-less tools are fixed.
+      limit: Schema.Number,
+    },
+    // TODO(dmaretskyi): Effect returns ({ result, encodedResult })
+    success: Schema.Any,
+    failure: Schema.Never,
+    dependencies: [Database.Service],
+  }),
+
+  Tool.make('schema-add', {
+    description: trim`
+      Adds a schema to the space.
+      The name will be used when displayed to the user.
+      The typename must be in the format of "example.com/type/Type".
+    `,
+    parameters: {
+      name: Schema.String,
+      typename: Schema.String,
+      jsonSchema: Schema.Any,
+    },
+    success: Schema.Any,
+    failure: Schema.Never,
+    dependencies: [Database.Service],
+  }),
+
+  //
+  // Query
+  //
+
+  Tool.make('query', {
+    description: trim`
+      Queries objects in the space.
+      Get the typename from the schema-list tool.
+    `,
+    parameters: {
+      typename: Schema.String,
+    },
+    success: Schema.Any,
+    failure: Schema.Never,
+    dependencies: [Database.Service],
+  }),
+
+  //
+  // Objects
+  //
+
+  Tool.make('object-create', {
+    description: trim`
+      Creates a new object and adds it to the current space.
+      Get the schema from the schema-list tool and ensure that the data matches the corresponding schema.
+    `,
+    parameters: {
+      typename: Schema.String,
+      data: Schema.Any,
+    },
+    success: Schema.Any,
+    failure: Schema.Never, // TODO(burdon): Error handing?
+    dependencies: [Database.Service],
+  }),
+
+  Tool.make('object-delete', {
+    description: trim`
+      Deletes the object.
+    `,
+    parameters: {
+      id: ArtifactId.annotations({
+        description: 'The ID of the object.',
+      }),
+    },
+    success: Schema.Any,
+    failure: Schema.Never,
+    dependencies: [Database.Service],
+  }),
+
+  Tool.make('object-update', {
+    description: trim`
+      Updates the object properties.
+    `,
+    parameters: {
+      id: ArtifactId.annotations({
+        description: 'The ID of the object.',
+      }),
+      properties: Schema.Record({ key: Schema.String, value: Schema.Any }),
+    },
+    success: Schema.Any,
+    failure: Schema.Never,
+    dependencies: [Database.Service],
+  }),
+
+  //
+  // Relations
+  //
+
+  Tool.make('relation-create', {
+    description: trim`
+      Creates a new relation and adds it to the current space.
+      Get the schema from the schema-list tool and ensure that the data matches the corresponding schema.
+    `,
+    parameters: {
+      typename: Schema.String,
+      source: ArtifactId.annotations({
+        description: 'The ID of the source object.',
+      }),
+      target: ArtifactId.annotations({
+        description: 'The ID of the target object.',
+      }),
+      data: Schema.Any.annotations({
+        description: 'The data to be stored in the relation.',
+      }),
+    },
+    success: Schema.Any,
+    failure: Schema.Never,
+    dependencies: [Database.Service],
+  }),
+
+  Tool.make('relation-delete', {
+    description: trim`
+      Deletes the relation.
+    `,
+    parameters: {
+      id: ArtifactId.annotations({
+        description: 'The ID of the relation.',
+      }),
+    },
+    success: Schema.Any,
+    failure: Schema.Never,
+    dependencies: [Database.Service],
+  }),
+
+  //
+  // Tags
+  //
+
+  Tool.make('tag-add', {
+    description: trim`
+      Adds a tag to an object.
+      Tags are objects of type ${Tag.Tag.typename}.
+    `,
+    parameters: {
+      tagId: ArtifactId.annotations({
+        description: 'The ID of the tag.',
+      }),
+      objectId: ArtifactId.annotations({
+        description: 'The ID of the object.',
+      }),
+    },
+    success: Schema.Any,
+    failure: Schema.Never,
+    dependencies: [Database.Service],
+  }),
+
+  Tool.make('tag-remove', {
+    description: trim`
+      Removes a tag from an object.
+      Tags are objects of type ${Tag.Tag.typename}.
+    `,
+    parameters: {
+      tagId: ArtifactId.annotations({
+        description: 'The ID of the tag.',
+      }),
+      objectId: ArtifactId.annotations({
+        description: 'The ID of the object.',
+      }),
+    },
+    success: Schema.Any,
+    failure: Schema.Never,
+    dependencies: [Database.Service],
+  }),
+);
+
+export const tools = Record.keys(SystemToolkit.tools);
+
+export const layer = (): Layer.Layer<Tool.Handler<any>, never, never> =>
+  SystemToolkit.toLayer({
+    ['schema-list' as const]: Effect.fnUntraced(function* () {
+      const { db } = yield* Database.Service;
+      const schema = yield* Effect.promise(() => db.schemaRegistry.query({ location: ['database', 'runtime'] }).run());
+      return schema.map((schema) => {
+        const meta = Type.getMeta(schema);
+        return {
+          typename: Type.getTypename(schema),
+          jsonSchema: Type.toJsonSchema(schema),
+          kind: meta?.sourceSchema ? 'relation' : 'record',
+        };
+      });
+    }),
+
+    ['schema-add' as const]: Effect.fnUntraced(function* ({ name, typename, jsonSchema }) {
+      const { db } = yield* Database.Service;
+      yield* Effect.promise(() =>
+        db.schemaRegistry.register([
+          {
+            typename,
+            version: '0.1.0',
+            jsonSchema,
+            name,
+          },
+        ]),
+      );
+    }),
+
+    ['query' as const]: Effect.fnUntraced(function* ({ typename }) {
+      const objects = yield* Database.runQuery(Filter.typename(typename));
+      return objects;
+    }),
+
+    ['object-create' as const]: Effect.fnUntraced(function* ({ typename, data }) {
+      const { db } = yield* Database.Service;
+      const schema = yield* Effect.promise(() =>
+        db.schemaRegistry.query({ typename, location: ['database', 'runtime'] }).first(),
+      );
+      invariant(Type.isObjectSchema(schema), 'Schema is not an object schema');
+
+      // TODO(dmaretskyi): How to add object to a collection?
+      const object = db.add(Obj.make(schema, data));
+      return object;
+    }),
+
+    ['object-delete' as const]: Effect.fnUntraced(function* ({ id }) {
+      const { db } = yield* Database.Service;
+      const object = yield* Database.resolve(DXN.parse(id));
+      db.remove(object);
+      return object;
+    }),
+
+    ['object-update' as const]: Effect.fnUntraced(function* ({ id, properties }) {
+      const object = yield* Database.resolve(DXN.parse(id));
+      Entity.change(object as Entity.Any, (obj) => {
+        for (const [key, value] of Object.entries(properties)) {
+          obj[key] = value;
+        }
+      });
+      return object;
+    }),
+
+    ['relation-create' as const]: Effect.fnUntraced(function* ({ typename, source, target, data }) {
+      const { db } = yield* Database.Service;
+      const schema = yield* Effect.promise(() =>
+        db.schemaRegistry.query({ typename, location: ['database', 'runtime'] }).first(),
+      );
+      invariant(Type.isRelationSchema(schema), 'Schema is not a relation schema');
+
+      const sourceObj = yield* Database.resolve(DXN.parse(source));
+      const targetObj = yield* Database.resolve(DXN.parse(target));
+      const relation = db.add(
+        Relation.make(schema, {
+          [Relation.Source]: sourceObj,
+          [Relation.Target]: targetObj,
+          ...data,
+        }),
+      );
+      return relation;
+    }),
+
+    ['relation-delete' as const]: Effect.fnUntraced(function* ({ id }) {
+      const { db } = yield* Database.Service;
+      const relation = yield* Database.resolve(DXN.parse(id));
+      db.remove(relation);
+      return relation;
+    }),
+
+    ['tag-add' as const]: Effect.fnUntraced(function* ({ tagId, objectId }) {
+      const object = yield* Database.resolve(DXN.parse(objectId));
+      Entity.change(object, (obj) => Entity.addTag(obj, DXN.parse(tagId).toString()));
+      return object;
+    }),
+
+    ['tag-remove' as const]: Effect.fnUntraced(function* ({ tagId, objectId }) {
+      const object = yield* Database.resolve(DXN.parse(objectId));
+      Entity.change(object, (obj) => Entity.removeTag(obj, DXN.parse(tagId).toString()));
+      return object;
+    }),
+  });

package/src/toolkits/WebToolkit.ts

@@ -0,0 +1,34 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Tool from '@effect/ai/Tool';
+import * as Toolkit from '@effect/ai/Toolkit';
+import * as AnthropicTool from '@effect/ai-anthropic/AnthropicTool';
+import * as Effect from 'effect/Effect';
+import * as Schema from 'effect/Schema';
+
+// TODO(dmaretskyi): Testing only.
+export const WebToolkit = Toolkit.make(
+  AnthropicTool.WebSearch_20250305({})
+    .pipe
+    // TODO(dmaretskyi): Effect bug -- provider-defined tools don't support annotations.
+    // ToolFormatter.assign({
+    //   debugFormatResult: (result) =>
+    //     Array.isArray(result) ? result.map(Struct.pick('title', 'type', 'url', 'page_age')) : result,
+    // }),
+    (),
+  Tool.make('WebFetch', {
+    parameters: {
+      url: Schema.String,
+    },
+    success: Schema.String,
+  }),
+);
+
+export const layer = WebToolkit.toLayer({
+  WebFetch: Effect.fnUntraced(function* ({ url }) {
+    const response = yield* Effect.promise(() => fetch(url).then((response) => response.text()));
+    return response;
+  }),
+});

package/src/toolkits/index.ts

@@ -0,0 +1,7 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export * as AssistantToolkit from './AssistantToolkit';
+export * as SystemToolkit from './SystemToolkit';
+export * as WebToolkit from './WebToolkit';

package/src/typedefs.d.ts

@@ -0,0 +1,8 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+declare module '*?raw' {
+  const content: string;
+  export default content;
+}

package/src/util/graphql.ts

@@ -0,0 +1,31 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as HttpBody from '@effect/platform/HttpBody';
+
+/**
+ * Template tag literal to get syntax highlighting for the query.
+ *
+ * @example
+ * ```ts
+ * const query = gql`
+ *   query Team($teamId: String!) {
+ *     team(id: $teamId) {
+ *       id
+ *       name
+ *     }
+ *   }
+ * `;
+ * ```
+ */
+export const gql = (query: string) => query;
+
+/**
+ * @returns JSON body for the graphql request.
+ */
+export const graphqlRequestBody = (query: string, variables: Record<string, any> = {}) =>
+  HttpBody.json({
+    query,
+    variables,
+  });

package/src/util/index.ts

@@ -0,0 +1,5 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export * from './graphql';