@dxos/assistant 0.7.4-df37807 → 0.7.5-feature-compute.4d9d99a

package/src/conversation/types.ts

@@ -4,12 +4,11 @@
 
 import { Schema as S } from '@effect/schema';
 
-import { toJsonSchema } from '@dxos/echo-schema';
-import { JsonSchemaType } from '@dxos/echo-schema';
+import { toJsonSchema, JsonSchemaType, ObjectId } from '@dxos/echo-schema';
 import type { SpaceId } from '@dxos/keys';
 import { log } from '@dxos/log';
 
-import { ObjectId, type Message } from '../ai-service';
+import { type Message, type MessageContentBlock } from '../ai-service';
 
 export const createUserMessage = (spaceId: SpaceId, threadId: ObjectId, text: string): Message => ({
   id: ObjectId.random(),
@@ -19,6 +18,9 @@ export const createUserMessage = (spaceId: SpaceId, threadId: ObjectId, text: st
   content: [{ type: 'text', text }],
 });
 
+/**
+ * @deprecated Use {@link LLMTool} instead.
+ */
 export const LLMToolDefinition = S.Struct({
   name: S.String,
   description: S.String,
@@ -26,6 +28,9 @@ export const LLMToolDefinition = S.Struct({
   execute: S.Any,
 });
 
+/**
+ * @deprecated Use {@link LLMTool} instead.
+ */
 export type LLMToolDefinition = {
   name: string;
   description: string;
@@ -33,10 +38,34 @@ export type LLMToolDefinition = {
   execute: (params: unknown, context: ToolExecutionContext) => Promise<LLMToolResult>;
 };
 
-export type ToolExecutionContext = {};
+declare global {
+  /**
+   * Extensions to the tool execution context.
+   *
+   * Different modules can extend this definition to add their own properties.
+   *
+   * @example
+   * ```ts
+   * declare global {
+   *   interface LLMToolContextExtensions {
+   *     chess: {
+   *       board: string;
+   *     };
+   *   }
+   * }
+   * ```
+   *
+   * @see https://www.typescriptlang.org/docs/handbook/declaration-merging.html#global-augmentation
+   */
+  interface LLMToolContextExtensions {}
+}
+
+export type ToolExecutionContext = {
+  extensions: LLMToolContextExtensions;
+};
 
 export type LLMToolResult =
-  | { kind: 'success'; result: unknown }
+  | { kind: 'success'; result: unknown; extractContentBlocks?: MessageContentBlock[] }
   | { kind: 'error'; message: string }
   | { kind: 'break'; result: unknown };
 
@@ -45,9 +74,14 @@ export const LLMToolResult = Object.freeze({
    * The tool execution was successful.
    * Gives the result back to the LLM.
    */
-  Success: (result: unknown): LLMToolResult => ({ kind: 'success', result }),
+  Success: (result: unknown, extractContentBlocks?: MessageContentBlock[]): LLMToolResult => ({
+    kind: 'success',
+    result,
+    extractContentBlocks,
+  }),
 
   Error: (message: string): LLMToolResult => ({ kind: 'error', message }),
+
   /**
    * Stop the conversation and return the result.
    */
@@ -78,9 +112,16 @@ export const defineTool = <Params extends S.Schema.AnyNoContext>({
   };
 };
 
+/**
+ * Adapts schems to be able to pass to AI providers.
+ */
 const toFunctionParameterSchema = (schema: S.Schema.All) => {
   const jsonSchema = toJsonSchema(schema);
   log('tool schema', { jsonSchema });
+  delete jsonSchema.anyOf;
+  delete jsonSchema.$id;
+  jsonSchema.type = 'object';
+  jsonSchema.properties ??= {};
   for (const key in jsonSchema.properties) {
     if (typeof jsonSchema.properties![key].description !== 'string') {
       throw new Error(`Property missing description: ${key}`);

package/src/cypher/combinators.test.ts

@@ -58,13 +58,13 @@ describe('Cypher Combinators', () => {
     const parser = or(node)(relation);
     const input = '[a:b]';
     const result = parser.parse(input);
-    log.info('', { result });
+    log('result', { result });
   });
 
   test('properties', ({ expect }) => {
     const input = "{name: 'John'}";
     const result = properties.parse(input);
-    log.info('', { result });
+    log('result', { result });
     expect(result).toMatchObject({ isOk: true });
   });
 
@@ -92,7 +92,7 @@ describe('Cypher Combinators', () => {
     const cases = ['RETURN n, m'];
     for (const input of cases) {
       const result = returnClause.parse(input);
-      log.info('', { result });
+      log('result', { result });
       expect(result).toMatchObject({ isOk: true });
     }
   });

package/src/cypher/combinators.ts

@@ -21,7 +21,6 @@ import type {
   StringLiteral,
   WhereClause,
 } from './ast';
-
 import { Parjser, parjs, parjsCombinators } from './parjs';
 
 // Helper parsers

package/src/cypher/execution-plan.test.ts

@@ -9,10 +9,12 @@ import { log } from '@dxos/log';
 import { createExecutionPlan } from './execution-plan';
 import { parseCypherQuery } from './parser';
 
+// log.config({ filter: 'debug' });
+
 describe('Execution Plan', () => {
   test('trivial', ({ expect }) => {
     const plan = createExecutionPlan(parseCypherQuery('MATCH (n:Person) RETURN n'));
-    log.info('', { plan });
+    log('', { plan });
     expect(plan.steps.map((step) => step.type)).toEqual(['NodeScan', 'ProduceResults']);
   });
 
@@ -22,9 +24,9 @@ describe('Execution Plan', () => {
         "MATCH (org:Org {name: 'DXOS'})-[:ORG_EMPLOYEES]->(c:Contact)<-[:TASK_ASSIGNEE]-(:Task)-[:TASK_PROJECT]->(p:Project {name: 'Composer'}) RETURN c.name",
       ),
     );
-    log.info('', { plan });
+    log('', { plan });
     for (const step of plan.steps) {
-      log.info('', { step });
+      log('step', { step });
     }
     expect(plan.steps.map((step) => step.type)).toEqual([
       'NodeScan',

package/src/cypher/parjs-shims.d.ts

@@ -1,3 +1,7 @@
+//
+// Copyright 2025 DXOS.org
+//
+
 declare module '#parjs' {
   import * as parjs from 'parjs';
   import * as parjsCombinators from 'parjs/combinators';

package/src/cypher/parjs.ts

@@ -3,8 +3,8 @@
 //
 
 // Workaround for https://github.com/vitest-dev/vitest/issues/7174.
-import { parjsCombinators, parjs } from '#parjs';
-
 import type { Parjser } from 'parjs';
 
+import { parjsCombinators, parjs } from '#parjs';
+
 export { type Parjser, parjsCombinators, parjs };

package/src/cypher/query-executor.test.ts

@@ -9,7 +9,7 @@ import { log } from '@dxos/log';
 import { executeQuery } from './query-executor';
 import { createTestData } from '../testing';
 
-test('run', async ({ expect }) => {
+test.skip('run', async ({ expect }) => {
   const dataSource = createTestData();
   // for (const node of dataSource.nodes) {
   //   log.info('node', { id: node.id, label: node.label, name: node.properties.name });

package/src/cypher/schema.ts

@@ -4,7 +4,6 @@
 
 import { raise } from '@dxos/debug';
 import { JSON_SCHEMA_ECHO_REF_ID, type JsonSchemaType } from '@dxos/echo-schema';
-import { DXN } from '@dxos/keys';
 
 import { trim } from '../util';
 

package/src/index.ts

@@ -4,4 +4,4 @@
 
 export * from './ai-service';
 export * from './cypher';
-export * from './conversation';
+export * from './conversation';

package/src/testing/artifacts.test.ts

@@ -0,0 +1,182 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+/*
+import { Schema as S } from '@effect/schema';
+import { describe, test } from 'vitest';
+
+import { ObjectId, toJsonSchema } from '@dxos/echo-schema';
+import { invariant } from '@dxos/invariant';
+import { SpaceId } from '@dxos/keys';
+import { log } from '@dxos/log';
+
+import { AIServiceClientImpl, LLMTool } from '../ai-service';
+import { defineTool, LLMToolResult } from '../conversation';
+
+// TODO(dmaretskyi): Effect schema.
+const ArtifactDef = S.Struct({
+  typename: S.String,
+  description: S.String,
+  schema: S.Any,
+  actions: S.Array(LLMTool),
+}).pipe(S.mutable);
+
+type ArtifactDef = S.Schema.Type<typeof ArtifactDef>;
+
+const ListItem = S.Struct({
+  name: S.String,
+});
+
+const ListSchema = S.Struct({
+  id: ObjectId,
+  title: S.String,
+  items: S.Array(ListItem).pipe(S.mutable),
+}).pipe(S.mutable);
+
+type ListSchema = S.Schema.Type<typeof ListSchema>;
+
+const list: ArtifactDef = {
+  typename: 'example.com/type/List',
+  description: 'Ordered set of text items.',
+  schema: ListSchema,
+  actions: [
+    defineTool({
+      name: 'list.query',
+      description: 'Query all lists',
+      schema: S.Struct({}),
+      execute: async ({}, context) => {
+        return LLMToolResult.Success(LISTS[id]);
+      },
+    }),
+    defineTool({
+      name: 'list.inspect',
+      description: 'Get contents of the list',
+      schema: S.Struct({
+        id: ObjectId.annotations({ description: 'The list to inspect' }),
+      }),
+      execute: async ({ id }, context) => {
+        return LLMToolResult.Success(LISTS[id]);
+      },
+    }),
+    defineTool({
+      name: 'list.add',
+      description: 'Add one or more items to an existing list',
+      schema: S.Struct({
+        id: ObjectId.annotations({ description: 'The list to add items to' }),
+        items: S.Array(ListItem).annotations({ description: 'The items to add to the list' }),
+      }),
+      execute: async ({ id, items }, context) => {
+        LISTS[id].items.push(...items);
+        return LLMToolResult.Success(LISTS[id]);
+      },
+    }),
+  ],
+};
+
+const LISTS: Record<ObjectId, ListSchema> = {};
+
+const artifacts = [list];
+
+const getArtifactDefinitions = defineTool({
+  name: 'getArtifactDefinitions',
+  description: 'Queries the definitions and metadata of artifacts defined in the system',
+  schema: S.Any,
+  execute: async (_, context) => {
+    return LLMToolResult.Success(
+      artifacts.map((artifact) => ({
+        typename: artifact.typename,
+        description: artifact.description,
+        schema: toJsonSchema(artifact.schema),
+        actions: artifact.actions.map((action) => ({
+          name: action.name,
+          description: action.description,
+        })),
+      })),
+    );
+  },
+});
+
+const ARTIFACT_INSTRUCTIONS = `
+You have ability to interact with artifacts.
+Artifacts are persistent structured objects that have actions associated with them.
+
+Before replying to the user you should first query the artifact definitions and metadata.
+If there's
+
+`;
+
+describe('Artifacts', () => {
+  test('shopping list', async () => {
+    const client = new AIServiceClientImpl({
+      endpoint: ENDPOINT,
+    });
+
+    const custodian: LLMTool = {
+      name: 'custodian',
+      description: 'Custodian can tell you the password if you say the magic word',
+      parameters: toJsonSchema(
+        S.Struct({
+          magicWord: S.String.annotations({ description: 'The magic word. Should be exactly "pretty please"' }),
+        }),
+      ),
+    };
+
+    const spaceId = SpaceId.random();
+    const threadId = ObjectId.random();
+
+    await client.appendMessages([
+      {
+        id: ObjectId.random(),
+        spaceId,
+        threadId,
+        role: 'user',
+        content: [{ type: 'text', text: 'What is the password? Ask the custodian' }],
+      },
+    ]);
+
+    const stream = await client.generate({
+      model: '@anthropic/claude-3-5-haiku-20241022',
+      spaceId,
+      threadId,
+      systemPrompt: 'You are a helpful assistant.',
+      tools: [custodian],
+    });
+    for await (const event of stream) {
+      log.info('event', event);
+    }
+    const [message] = await stream.complete();
+    log.info('full message', {
+      message,
+    });
+    await client.appendMessages([message]);
+
+    const toolUse = message.content.find(({ type }) => type === 'tool_use')!;
+    invariant(toolUse.type === 'tool_use');
+    await client.appendMessages([
+      {
+        id: ObjectId.random(),
+        spaceId,
+        threadId,
+        role: 'user',
+        content: [{ type: 'tool_result', toolUseId: toolUse.id, content: 'password="The sky is gray"' }],
+      },
+    ]);
+
+    const stream2 = await client.generate({
+      model: '@anthropic/claude-3-5-haiku-20241022',
+      spaceId,
+      threadId,
+      systemPrompt: 'You are a helpful assistant.',
+      tools: [custodian],
+    });
+    for await (const event of stream2) {
+      log.info('event', event);
+    }
+    const [message2] = await stream2.complete();
+    log.info('full message', {
+      message: message2,
+    });
+  });
+});
+*/

package/src/testing/data.ts

@@ -0,0 +1,13 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export const DATA_MESSAGES = [
+  `
+  <cot>
+  ${Array.from({ length: 5 })
+    .map((_, i) => `${i + 1}. Step`)
+    .join('\n')}
+  </cot>
+  `,
+];

package/src/testing/defs.ts

@@ -0,0 +1,8 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export const AI_SERVICE_ENDPOINT = {
+  LOCAL: 'http://localhost:8788',
+  REMOTE: 'https://ai-service.dxos.workers.dev',
+};

package/src/testing/index.ts

@@ -2,6 +2,7 @@
 // Copyright 2024 DXOS.org
 //
 
+export * from './defs';
 export * from './logger';
 export * from './query-promts';
 export * from './test-data';

package/src/testing/query.test.ts

@@ -4,22 +4,22 @@
 
 import { test } from 'vitest';
 
+import { EchoTestBuilder } from '@dxos/echo-db/testing';
+import { ObjectId } from '@dxos/echo-schema';
 import { SpaceId } from '@dxos/keys';
 import { log } from '@dxos/log';
-import { EchoTestBuilder } from '@dxos/echo-db/testing';
 
+import { AI_SERVICE_ENDPOINT } from './defs';
 import { createLogger } from './logger';
 import { createCypherTool, createSystemPrompt } from './query-promts';
 import { createTestData, seedTestData } from './test-data';
 import { Contact, Org, Project, Task } from './test-schema';
-import { AIServiceClientImpl, ObjectId } from '../ai-service';
+import { AIServiceClientImpl } from '../ai-service';
 import { runLLM, createUserMessage } from '../conversation';
-import { EchoDataSource } from '../cypher/echo-data-source';
-
-const ENDPOINT = 'http://localhost:8787';
+import { EchoDataSource } from '../cypher';
 
 const client = new AIServiceClientImpl({
-  endpoint: ENDPOINT,
+  endpoint: AI_SERVICE_ENDPOINT.LOCAL,
 });
 
 test.skip('cypher query', async () => {
@@ -31,7 +31,7 @@ test.skip('cypher query', async () => {
   const spaceId = SpaceId.random();
   const threadId = ObjectId.random();
 
-  await client.insertMessages([
+  await client.appendMessages([
     createUserMessage(
       spaceId,
       threadId,
@@ -52,7 +52,7 @@ test.skip('cypher query', async () => {
   log.info('DONE', { result: result.result });
 });
 
-test.only('query ECHO', async () => {
+test.skip('query ECHO', async () => {
   await using builder = await new EchoTestBuilder().open();
   const { db, graph } = await builder.createDatabase();
 
@@ -68,7 +68,7 @@ test.only('query ECHO', async () => {
   const spaceId = SpaceId.random();
   const threadId = ObjectId.random();
 
-  await client.insertMessages([
+  await client.appendMessages([
     createUserMessage(
       spaceId,
       threadId,

package/src/testing/test-data.ts

@@ -5,6 +5,7 @@
 import { type Schema as S } from '@effect/schema';
 
 import { raise } from '@dxos/debug';
+import type { EchoDatabase } from '@dxos/echo-db';
 import { JSON_SCHEMA_ECHO_REF_ID, ObjectId, toJsonSchema, type JsonSchemaType, type Ref } from '@dxos/echo-schema';
 import { invariant } from '@dxos/invariant';
 import { create, makeRef } from '@dxos/live-object';
@@ -17,7 +18,6 @@ import {
   formatNodeLabel,
 } from '../cypher';
 import { Contact, Org, Project, Task } from '../testing';
-import type { EchoDatabase } from '@dxos/echo-db';
 
 export const seedTestData = (db: EchoDatabase) => {
   const contactRich = db.add(

package/vendor/parjs-browser.mjs

@@ -0,0 +1,4 @@
+import * as parjs from 'parjs';
+import * as parjsCombinators from 'parjs/combinators';
+
+export { parjsCombinators, parjs };

package/vendor/parjs-default.mjs

@@ -0,0 +1,8 @@
+import { createRequire } from 'node:module';
+
+// TODO(dmaretskyi): Must be like this or it breaks vitest.
+const require = createRequire(import.meta.url);
+const parjs = require('parjs');
+const parjsCombinators = require('parjs/combinators');
+
+export { parjsCombinators, parjs };