@dxos/assistant-toolkit 0.8.4-main.bc674ce → 0.8.4-main.c351d160a8

package/src/blueprints/database/blueprint.test.ts

@@ -0,0 +1,341 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { describe, expect, it } from '@effect/vitest';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+
+import { AiContextService, AiConversationService } from '@dxos/assistant';
+import { AssistantTestLayer } from '@dxos/assistant/testing';
+import { Blueprint } from '@dxos/blueprints';
+import { Database, Entity, Obj, Query, Ref, Relation, Tag } from '@dxos/echo';
+import { TestHelpers } from '@dxos/effect/testing';
+import { ObjectId } from '@dxos/keys';
+import { Employer, Organization, Person } from '@dxos/types';
+
+import DatabaseBlueprint from './blueprint';
+import { DatabaseFunctions } from './functions';
+
+ObjectId.dangerouslyDisableRandomness();
+
+const TestLayer = AssistantTestLayer({
+  functions: [...Object.values(DatabaseFunctions)],
+  types: [Organization.Organization, Person.Person, Employer.Employer, Tag.Tag, Blueprint.Blueprint],
+  tracing: 'pretty',
+});
+
+const provideTestLayers = Effect.provide(AiConversationService.layerNewQueue().pipe(Layer.provideMerge(TestLayer)));
+
+const addDatabaseBlueprint = Effect.fnUntraced(function* () {
+  yield* AiContextService.bindContext({
+    blueprints: [Ref.make(yield* Database.add(Obj.clone(DatabaseBlueprint.make(), { deep: true })))],
+  });
+});
+
+describe('Database Blueprint', () => {
+  //
+  // Schema
+  //
+
+  it.effect(
+    'schema-list: list available schemas',
+    Effect.fnUntraced(
+      function* (_) {
+        yield* addDatabaseBlueprint();
+        const messages = yield* AiConversationService.run({
+          prompt: 'List all available schemas. Tell me what typenames are available.',
+        });
+        const lastMessage = messages.at(-1);
+        expect(lastMessage).toBeDefined();
+      },
+      provideTestLayers,
+      TestHelpers.provideTestContext,
+    ),
+    { timeout: 60_000 },
+  );
+
+  it.effect(
+    'schema-add: add a new schema',
+    Effect.fnUntraced(
+      function* (_) {
+        yield* addDatabaseBlueprint();
+        yield* AiConversationService.run({
+          prompt:
+            'Add a new schema called "Project" with typename "com.example.type.project" and fields: name (string), description (string), and status (string).',
+        });
+        const { db } = yield* Database.Service;
+        const schemas = yield* Effect.promise(() =>
+          db.schemaRegistry.query({ typename: 'com.example.type.project', location: ['database', 'runtime'] }).run(),
+        );
+        expect(schemas.length).toBeGreaterThanOrEqual(1);
+      },
+      provideTestLayers,
+      TestHelpers.provideTestContext,
+    ),
+    { timeout: 60_000 },
+  );
+
+  //
+  // Objects
+  //
+
+  it.effect(
+    'object-create: create an object',
+    Effect.fnUntraced(
+      function* (_) {
+        yield* addDatabaseBlueprint();
+        yield* AiConversationService.run({
+          prompt: 'Create a new organization called "Cyberdyne Systems".',
+        });
+        const orgs = yield* Database.runQuery(Query.type(Organization.Organization, { name: 'Cyberdyne Systems' }));
+        expect(orgs).toHaveLength(1);
+      },
+      provideTestLayers,
+      TestHelpers.provideTestContext,
+    ),
+    { timeout: 60_000 },
+  );
+
+  it.effect(
+    'object-create: create an object with a reference',
+    Effect.fnUntraced(
+      function* (_) {
+        yield* addDatabaseBlueprint();
+        yield* AiConversationService.run({
+          prompt: 'Create a preson fullName="John Doe" with a reference to the organization "Cyberdyne Systems".',
+        });
+        const orgs = yield* Database.runQuery(Query.type(Organization.Organization, { name: 'Cyberdyne Systems' }));
+        const persons = yield* Database.runQuery(Query.type(Person.Person, { fullName: 'John Doe' }));
+        expect(orgs).toHaveLength(1);
+        expect(persons).toHaveLength(1);
+        expect(persons[0].organization.target).toBe(orgs[0]);
+      },
+      provideTestLayers,
+      TestHelpers.provideTestContext,
+    ),
+    { timeout: 60_000 },
+  );
+
+  it.effect(
+    'object-delete: delete an object',
+    Effect.fnUntraced(
+      function* (_) {
+        yield* addDatabaseBlueprint();
+        const org = yield* Database.add(Obj.make(Organization.Organization, { name: 'Obsolete Corp' }));
+        yield* AiConversationService.run({
+          prompt: `Delete the organization "Obsolete Corp".`,
+        });
+        expect(Obj.isDeleted(org)).toBe(true);
+      },
+      provideTestLayers,
+      TestHelpers.provideTestContext,
+    ),
+    { timeout: 60_000 },
+  );
+
+  it.effect(
+    'object-update: update an object',
+    Effect.fnUntraced(
+      function* (_) {
+        yield* addDatabaseBlueprint();
+        const org = yield* Database.add(Obj.make(Organization.Organization, { name: 'Old Name Inc' }));
+        yield* AiConversationService.run({
+          prompt: `Update the organization "Old Name Inc" and change its name to "New Name Corp".`,
+        });
+        expect(org.name).toBe('New Name Corp');
+      },
+      provideTestLayers,
+      TestHelpers.provideTestContext,
+    ),
+    { timeout: 60_000 },
+  );
+
+  //
+  // Query & Load
+  //
+
+  it.effect(
+    'query: search for objects',
+    Effect.fnUntraced(
+      function* (_) {
+        yield* addDatabaseBlueprint();
+        yield* Database.add(Obj.make(Organization.Organization, { name: 'Acme Corp' }));
+        yield* Database.add(Obj.make(Organization.Organization, { name: 'Globex Industries' }));
+        const messages = yield* AiConversationService.run({
+          prompt: 'Search for all organizations. How many are there?',
+        });
+        const lastMessage = messages.at(-1);
+        expect(lastMessage).toBeDefined();
+      },
+      provideTestLayers,
+      TestHelpers.provideTestContext,
+    ),
+    { timeout: 60_000 },
+  );
+
+  it.effect(
+    'load: load object details',
+    Effect.fnUntraced(
+      function* (_) {
+        yield* addDatabaseBlueprint();
+        const org = yield* Database.add(
+          Obj.make(Organization.Organization, { name: 'Detail Corp', description: 'A detailed organization.' }),
+        );
+        const dxn = Obj.getDXN(org).toString();
+        const messages = yield* AiConversationService.run({
+          prompt: `Load the full details of object ${dxn}. What is its description?`,
+        });
+        const lastMessage = messages.at(-1);
+        expect(lastMessage).toBeDefined();
+      },
+      provideTestLayers,
+      TestHelpers.provideTestContext,
+    ),
+    { timeout: 60_000 },
+  );
+
+  //
+  // Relations
+  //
+
+  it.effect(
+    'relation-create: create a relation between objects',
+    Effect.fnUntraced(
+      function* (_) {
+        yield* addDatabaseBlueprint();
+        const person = yield* Database.add(Obj.make(Person.Person, { fullName: 'John Connor' }));
+        const org = yield* Database.add(Obj.make(Organization.Organization, { name: 'Cyberdyne Systems' }));
+        yield* AiConversationService.run({
+          prompt: `Create an Employer relation from person "John Connor" to organization "Cyberdyne Systems" with role "Engineer". List schemas first to find the relation typename.`,
+        });
+        const relations = yield* Database.runQuery(Query.type(Employer.Employer));
+        expect(relations.length).toBeGreaterThanOrEqual(1);
+      },
+      provideTestLayers,
+      TestHelpers.provideTestContext,
+    ),
+    { timeout: 60_000 },
+  );
+
+  it.effect(
+    'relation-delete: delete a relation',
+    Effect.fnUntraced(
+      function* (_) {
+        yield* addDatabaseBlueprint();
+        const person = yield* Database.add(Obj.make(Person.Person, { fullName: 'Sarah Connor' }));
+        const org = yield* Database.add(Obj.make(Organization.Organization, { name: 'Cyberdyne Systems' }));
+        const relation = yield* Database.add(
+          Relation.make(Employer.Employer, {
+            [Relation.Source]: person,
+            [Relation.Target]: org,
+            role: 'Director',
+          }),
+        );
+        const relationDxn = Relation.getDXN(relation).toString();
+        yield* AiConversationService.run({
+          prompt: `Delete the relation ${relationDxn}.`,
+        });
+        expect(Relation.isDeleted(relation)).toBe(true);
+      },
+      provideTestLayers,
+      TestHelpers.provideTestContext,
+    ),
+    { timeout: 60_000 },
+  );
+
+  //
+  // Tags
+  //
+
+  it.effect(
+    'tag-add: add a tag to an object',
+    Effect.fnUntraced(
+      function* (_) {
+        yield* addDatabaseBlueprint();
+        const org = yield* Database.add(Obj.make(Organization.Organization, { name: 'Tagged Corp' }));
+        const tag = yield* Database.add(Tag.make({ label: 'important' }));
+        yield* AiConversationService.run({
+          prompt: `Add tag "important" to the organization "Tagged Corp".`,
+        });
+        const tags = Obj.getMeta(org).tags ?? [];
+        // TODO(dmaretskyi): matcher doesnt work with echo proxies.
+        expect([...tags]).toContain(Obj.getDXN(tag).toString());
+      },
+      provideTestLayers,
+      TestHelpers.provideTestContext,
+    ),
+    { timeout: 60_000 },
+  );
+
+  it.effect(
+    'tag-remove: remove a tag from an object',
+    Effect.fnUntraced(
+      function* (_) {
+        yield* addDatabaseBlueprint();
+        const org = yield* Database.add(Obj.make(Organization.Organization, { name: 'Untagged Corp' }));
+        const tag = yield* Database.add(Tag.make({ label: 'obsolete' }));
+        const tagDxn = Obj.getDXN(tag).toString();
+        Entity.change(org, (obj) => Entity.addTag(obj, tagDxn));
+        expect(Obj.getMeta(org).tags ?? []).toContain(tagDxn);
+        yield* AiConversationService.run({
+          prompt: `Remove tag "obsolete" from the organization "Untagged Corp".`,
+        });
+        const tags = Obj.getMeta(org).tags ?? [];
+        // TODO(dmaretskyi): matcher doesnt work with echo proxies.
+        expect([...tags]).not.toContain(tagDxn);
+      },
+      provideTestLayers,
+      TestHelpers.provideTestContext,
+    ),
+    { timeout: 60_000 },
+  );
+
+  //
+  // Context
+  //
+
+  it.effect(
+    'context-add: add object to chat context',
+    Effect.fnUntraced(
+      function* (_) {
+        yield* addDatabaseBlueprint();
+        const org = yield* Database.add(Obj.make(Organization.Organization, { name: 'Context Corp' }));
+        yield* AiConversationService.run({
+          prompt: `Add the organization "Context Corp" to the chat context.`,
+        });
+        const conversation = yield* AiConversationService;
+        const objects = conversation.context.getObjects();
+        expect(objects.length).toBeGreaterThanOrEqual(1);
+      },
+      provideTestLayers,
+      TestHelpers.provideTestContext,
+    ),
+    { timeout: 60_000 },
+  );
+
+  it.effect(
+    'context-remove: remove object from chat context',
+    Effect.fnUntraced(
+      function* (_) {
+        yield* addDatabaseBlueprint();
+        const org = yield* Database.add(Obj.make(Organization.Organization, { name: 'Remove Context Corp' }));
+        const { db } = yield* Database.Service;
+        const ref = db.makeRef(Obj.getDXN(org)) as Ref.Ref<any>;
+        const { binder } = yield* AiContextService;
+        yield* Effect.promise(() => binder.bind({ blueprints: [], objects: [ref] }));
+        const dxn = Obj.getDXN(org).toString();
+        yield* AiConversationService.run({
+          prompt: `Remove the organization "Remove Context Corp" from the chat context.`,
+        });
+        const conversation = yield* AiConversationService;
+        const objects = conversation.context.getObjects();
+        const found = objects.find((obj) => Obj.getDXN(obj).toString() === dxn);
+        expect(found).toBeUndefined();
+      },
+      provideTestLayers,
+      TestHelpers.provideTestContext,
+    ),
+    { timeout: 60_000 },
+  );
+});

package/src/blueprints/database/blueprint.ts

@@ -0,0 +1,39 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type AppCapabilities } from '@dxos/app-toolkit';
+import { Blueprint } from '@dxos/blueprints';
+import { Ref } from '@dxos/echo';
+import { Text } from '@dxos/schema';
+import { trim } from '@dxos/util';
+
+import { DatabaseFunctions } from './functions';
+
+const BLUEPRINT_KEY = 'org.dxos.blueprint.database';
+
+const instructions = trim`
+  You can query, create, update, and delete objects in ECHO.
+  You can manage schemas, relations, tags, and add objects to the chat context.
+`;
+
+const functions = Object.values(DatabaseFunctions);
+
+const make = () =>
+  Blueprint.make({
+    key: BLUEPRINT_KEY,
+    name: 'Database',
+    description: 'Query and manipulate objects in the ECHO database.',
+    instructions: {
+      source: Ref.make(Text.make(instructions)),
+    },
+    tools: Blueprint.toolDefinitions({ functions }),
+  });
+
+const blueprint: AppCapabilities.BlueprintDefinition = {
+  key: BLUEPRINT_KEY,
+  functions,
+  make,
+};
+
+export default blueprint;

package/src/blueprints/database/functions/context-add.ts

@@ -0,0 +1,35 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+import * as Schema from 'effect/Schema';
+
+import { AiContextService } from '@dxos/assistant';
+import { Obj, Ref } from '@dxos/echo';
+import { defineFunction } from '@dxos/functions';
+import { trim } from '@dxos/util';
+
+export default defineFunction({
+  key: 'org.dxos.function.database.context-add',
+  name: 'Add to context',
+  description: trim`
+    Adds the object to the chat context.
+    Use this it for objects that are useful long-term for the conversation.
+  `,
+  inputSchema: Schema.Struct({
+    obj: Ref.Ref(Obj.Unknown).annotations({
+      description: 'Object to add to the chat context.',
+    }),
+  }),
+  outputSchema: Schema.Void,
+  handler: Effect.fn(function* ({ data: { obj } }) {
+    const { binder } = yield* AiContextService;
+    yield* Effect.promise(() =>
+      binder.bind({
+        blueprints: [],
+        objects: [obj],
+      }),
+    );
+  }, AiContextService.fixFunctionHandlerType),
+});

package/src/blueprints/database/functions/context-remove.ts

@@ -0,0 +1,35 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+import * as Schema from 'effect/Schema';
+
+import { AiContextService } from '@dxos/assistant';
+import { Obj, Ref } from '@dxos/echo';
+import { defineFunction } from '@dxos/functions';
+import { trim } from '@dxos/util';
+
+export default defineFunction({
+  key: 'org.dxos.function.database.context-remove',
+  name: 'Remove from context',
+  description: trim`
+    Removes the object from the chat context.
+    Use this it for objects that are no longer useful for the conversation.
+  `,
+  inputSchema: Schema.Struct({
+    obj: Ref.Ref(Obj.Unknown).annotations({
+      description: 'Object to remove from the chat context.',
+    }),
+  }),
+  outputSchema: Schema.Void,
+  handler: Effect.fn(function* ({ data: { obj } }) {
+    const { binder } = yield* AiContextService;
+    yield* Effect.promise(() =>
+      binder.unbind({
+        blueprints: [],
+        objects: [obj],
+      }),
+    );
+  }, AiContextService.fixFunctionHandlerType),
+});

package/src/blueprints/database/functions/index.ts

@@ -0,0 +1,33 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { default as ContextAdd } from './context-add';
+import { default as ContextRemove } from './context-remove';
+import { default as Load } from './load';
+import { default as ObjectCreate } from './object-create';
+import { default as ObjectDelete } from './object-delete';
+import { default as ObjectUpdate } from './object-update';
+import { default as Query } from './query';
+import { default as RelationCreate } from './relation-create';
+import { default as RelationDelete } from './relation-delete';
+import { default as SchemaAdd } from './schema-add';
+import { default as SchemaList } from './schema-list';
+import { default as TagAdd } from './tag-add';
+import { default as TagRemove } from './tag-remove';
+
+export const DatabaseFunctions = {
+  ContextAdd,
+  ContextRemove,
+  Load,
+  ObjectCreate,
+  ObjectDelete,
+  ObjectUpdate,
+  Query,
+  RelationCreate,
+  RelationDelete,
+  SchemaAdd,
+  SchemaList,
+  TagAdd,
+  TagRemove,
+};

package/src/blueprints/database/functions/load.ts

@@ -0,0 +1,31 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Array from 'effect/Array';
+import * as Effect from 'effect/Effect';
+import * as Schema from 'effect/Schema';
+
+import { Database, Entity, Obj, Ref } from '@dxos/echo';
+import { defineFunction } from '@dxos/functions';
+import { trim } from '@dxos/util';
+
+export default defineFunction({
+  key: 'org.dxos.function.database.load',
+  name: 'Load object',
+  description: trim`
+    Loads the object or relation content.
+    Can load multiple objects at at time.
+    Use the to read the data when you have a DXN.
+    Call this tool with an array of one or more DXNs or object IDs.
+    When use see a reference ({ '/': 'dxn:...' }), you can call this function to load the object.
+    Note that returned data is only a snapshot in time, and might have changed since the object was last loaded.
+  `,
+  inputSchema: Schema.Struct({
+    refs: Schema.Array(Ref.Ref(Obj.Unknown)),
+  }),
+  outputSchema: Schema.Unknown,
+  handler: Effect.fn(function* ({ data: { refs } }) {
+    return yield* Effect.forEach(refs, Database.load).pipe(Effect.map(Array.map(Entity.toJSON)));
+  }),
+});

package/src/blueprints/database/functions/object-create.ts

@@ -0,0 +1,48 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+import * as Schema from 'effect/Schema';
+
+import { Database, Entity, Obj, Type } from '@dxos/echo';
+import { defineFunction } from '@dxos/functions';
+import { invariant } from '@dxos/invariant';
+import { deepMapValues, trim } from '@dxos/util';
+import { EncodedReference } from '@dxos/echo-protocol';
+
+export default defineFunction({
+  key: 'org.dxos.function.database.object-create',
+  name: 'Create object',
+  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.
+    References are provided in the following format: { "/": "dxn:..." }.
+    Reference examples: { "/": "dxn:echo:@:01KG7R1ZXWFMWQ4DA1Q6TN1DG4" }, { "/": "dxn:queue:data:01KG7R1ZXWFMWQ4DA1Q6TN1DG4:01KG7R1ZXWFMWQ4DA1Q6TN1DG4" }
+  `,
+  inputSchema: Schema.Struct({
+    typename: Schema.String,
+    data: Schema.Any,
+  }),
+  outputSchema: Schema.Unknown,
+  handler: Effect.fn(function* ({ data: { 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');
+
+    const object = db.add(
+      Obj.make(
+        schema,
+        deepMapValues(data, (value, recurse) => {
+          if (EncodedReference.isEncodedReference(value)) {
+            return db.makeRef(EncodedReference.toDXN(value));
+          }
+          return recurse(value);
+        }),
+      ),
+    );
+    return Entity.toJSON(object);
+  }),
+});

package/src/blueprints/database/functions/object-delete.ts

@@ -0,0 +1,27 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+import * as Schema from 'effect/Schema';
+
+import { Database, Obj, Ref } from '@dxos/echo';
+import { defineFunction } from '@dxos/functions';
+import { trim } from '@dxos/util';
+
+export default defineFunction({
+  key: 'org.dxos.function.database.object-delete',
+  name: 'Delete object',
+  description: trim`
+    Deletes the object.
+  `,
+  inputSchema: Schema.Struct({
+    obj: Ref.Ref(Obj.Unknown),
+  }),
+  outputSchema: Schema.Void,
+  handler: Effect.fn(function* ({ data: { obj } }) {
+    const { db } = yield* Database.Service;
+    const object = yield* Database.load(obj);
+    db.remove(object);
+  }),
+});

package/src/blueprints/database/functions/object-update.ts

@@ -0,0 +1,40 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+import * as Schema from 'effect/Schema';
+
+import { Database, Entity, Obj, Ref } from '@dxos/echo';
+import { defineFunction } from '@dxos/functions';
+import { trim } from '@dxos/util';
+import { EncodedReference } from '@dxos/echo-protocol';
+
+export default defineFunction({
+  key: 'org.dxos.function.database.object-update',
+  name: 'Update object',
+  description: trim`
+    Updates the object properties.
+    References are provided in the following format: { "/": "dxn:..." }.
+    Reference examples: { "/": "dxn:echo:@:01KG7R1ZXWFMWQ4DA1Q6TN1DG4" }, { "/": "dxn:queue:data:01KG7R1ZXWFMWQ4DA1Q6TN1DG4:01KG7R1ZXWFMWQ4DA1Q6TN1DG4" }
+  `,
+  inputSchema: Schema.Struct({
+    obj: Ref.Ref(Obj.Unknown),
+    properties: Schema.Record({ key: Schema.String, value: Schema.Any }),
+  }),
+  outputSchema: Schema.Unknown,
+  handler: Effect.fn(function* ({ data: { obj, properties } }) {
+    const { db } = yield* Database.Service;
+    const object = yield* Database.load(obj);
+    Entity.change(object as Entity.Any, (obj) => {
+      for (const [key, value] of Object.entries(properties)) {
+        if (EncodedReference.isEncodedReference(value)) {
+          obj[key] = db.makeRef(EncodedReference.toDXN(value));
+        } else {
+          obj[key] = value;
+        }
+      }
+    });
+    return Entity.toJSON(object);
+  }),
+});