@dxos/assistant 0.8.2-main.fbd8ed0 → 0.8.2-staging.4d6ad0f

package/src/research/research.test.ts

@@ -0,0 +1,189 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { inspect } from 'node:util';
+import { beforeAll, describe, test } from 'vitest';
+
+import { AIServiceEdgeClient, OllamaClient, structuredOutputParser } from '@dxos/ai';
+import { AI_SERVICE_ENDPOINT, EXA_API_KEY } from '@dxos/ai/testing';
+import { type EchoDatabase } from '@dxos/echo-db';
+import { EchoTestBuilder } from '@dxos/echo-db/testing';
+import { getSchemaDXN } from '@dxos/echo-schema';
+import { ConfiguredCredentialsService, FunctionExecutor, ServiceContainer, TracingService } from '@dxos/functions';
+import { live } from '@dxos/live-object';
+import { DataType, DataTypes } from '@dxos/schema';
+
+import { createExtractionSchema, getSanitizedSchemaName } from './graph';
+import { researchFn } from './research';
+
+const REMOTE_AI = true;
+const MOCK_SEARCH = false;
+
+describe('Research', () => {
+  let builder: EchoTestBuilder;
+  let db: EchoDatabase;
+  let executor: FunctionExecutor;
+
+  beforeAll(async () => {
+    // TODO(dmaretskyi): Helper to scaffold this from a config.
+    builder = await new EchoTestBuilder().open();
+    const { db: db1 } = await builder.createDatabase({ indexing: { vector: true } });
+    db = db1;
+    db.graph.schemaRegistry.addSchema(DataTypes);
+    executor = new FunctionExecutor(
+      new ServiceContainer().setServices({
+        ai: {
+          client: REMOTE_AI
+            ? new AIServiceEdgeClient({
+                endpoint: AI_SERVICE_ENDPOINT.REMOTE,
+                defaultGenerationOptions: {
+                  // model: '@anthropic/claude-sonnet-4-20250514',
+                  model: '@anthropic/claude-3-5-sonnet-20241022',
+                },
+              })
+            : new OllamaClient({
+                overrides: {
+                  model: 'llama3.1:8b',
+                },
+              }),
+        },
+        credentials: new ConfiguredCredentialsService([{ service: 'exa.ai', apiKey: EXA_API_KEY }]),
+        database: { db },
+        tracing: TracingService.console,
+      }),
+    );
+  });
+
+  test('should generate a research report', { timeout: 300_000 }, async () => {
+    db.add(
+      live(DataType.Organization, {
+        name: 'Notion',
+        website: 'https://www.notion.com',
+      }),
+    );
+    await db.flush({ indexes: true });
+
+    const result = await executor.invoke(researchFn, {
+      query: 'Who are the founders of Notion?',
+      mockSearch: MOCK_SEARCH,
+    });
+
+    console.log(inspect(result, { depth: null, colors: true }));
+    console.log(JSON.stringify(result, null, 2));
+  });
+});
+
+describe('misc', () => {
+  test('createExtractionSchema', () => {
+    const _schema = createExtractionSchema(DataTypes);
+    // log.info('schema', { schema });
+  });
+
+  test('extract schema json schema', () => {
+    const schema = createExtractionSchema(DataTypes);
+    const _parser = structuredOutputParser(schema);
+    // log.info('schema', { json: parser.tool.parameters });
+  });
+
+  test('getSanitizedSchemaName', () => {
+    const _names = DataTypes.map(getSanitizedSchemaName);
+    // log.info('names', { names });
+  });
+
+  test('getTypeAnnotation', () => {
+    for (const schema of DataTypes) {
+      const _dxn = getSchemaDXN(schema);
+      // log.info('dxn', { schema, dxn });
+    }
+  });
+
+  test.skip('sanitizeObjects', () => {
+    const _TEST_DATA = {
+      objects_dxos_org_type_Project: [
+        {
+          name: 'Reor',
+          description:
+            'A private & local AI personal knowledge management app focused on high entropy thinkers. Features include Q&A chat with full context of notes, automatic connection of ideas, semantic search, and local-first architecture with LLMs and vector databases.',
+          image: 'https://reorhomepage-2-cwy0zagzg-reor-team.vercel.app/opengraph-image.jpg',
+          id: 'reor-project-01',
+        },
+        {
+          name: 'Personal AI',
+          description:
+            'A platform for creating personal AI models with unlimited memory capabilities. Features include memory stacking, data uploads, and personalized language models that can be trained on individual knowledge bases.',
+          image: 'https://cdn.prod.website-files.com/5ff65c460ce39f5ec5681c6a/663d12aab1b425e1ad40d3a6_Memory-min.jpg',
+          id: 'personal-ai-project-01',
+        },
+        {
+          name: 'IKI AI',
+          description:
+            'An AI-native workspace for research, strategy, and creative work. Offers features like AI summarization, content analysis, and team knowledge sharing capabilities.',
+          image: 'https://framerusercontent.com/assets/cI6Uo7x4q0W3uxzOt2preXjv6aE.jpg',
+          id: 'iki-ai-project-01',
+        },
+        {
+          name: 'Forethink',
+          description:
+            'A privacy-first, on-device AI system that proactively links current activities to relevant knowledge. Features real-time learning across teams and local data processing.',
+          image: 'https://framerusercontent.com/assets/XDhN6tICnlElB134JWcWXOuXc.jpeg',
+          id: 'forethink-project-01',
+        },
+        {
+          name: 'Amurex',
+          description:
+            'An invisible AI companion that handles tasks, remembers important information, and supports workflow. Includes features for meeting automation, email categorization, and cross-platform search.',
+          image: 'https://amurex.ai/ogimages/og_amurex.jpg',
+          id: 'amurex-project-01',
+        },
+      ],
+      objects_dxos_org_type_Organization: [
+        {
+          name: 'Reor',
+          description:
+            'A technology company focused on developing local-first AI solutions for personal knowledge management.',
+          status: 'active',
+          website: 'https://www.reorproject.org',
+          id: 'reor-org-01',
+        },
+        {
+          name: 'Personal.ai',
+          description: 'A company specializing in personal AI development and memory management solutions.',
+          status: 'active',
+          website: 'https://www.personal.ai',
+          id: 'personal-ai-org-01',
+        },
+        {
+          name: 'IKI AI',
+          description: 'A startup backed by 500 Global, developing AI-native workspaces for knowledge workers.',
+          status: 'active',
+          website: 'https://iki.ai',
+          id: 'iki-ai-org-01',
+        },
+        {
+          name: 'Forethink.ai',
+          description:
+            'A company focused on privacy-first AI solutions for knowledge management and team collaboration.',
+          status: 'active',
+          website: 'https://www.forethink.ai',
+          id: 'forethink-org-01',
+        },
+      ],
+      objects_dxos_org_type_Text: [
+        {
+          content:
+            'Current trends in AI-powered Personal Knowledge Management (PKM) systems include: 1) Shift from document-based to graph-based systems for better knowledge connection, 2) Integration of large language models for enhanced content understanding and retrieval, 3) Focus on privacy-first and local-first architectures, 4) Emphasis on automatic knowledge connection and discovery, 5) Implementation of semantic search capabilities.',
+          id: 'pkm-trends-text-01',
+        },
+        {
+          content:
+            'Key features emerging across modern PKM tools include: automated content categorization, semantic analysis and linking, personalized AI models that learn from user interaction, integration with existing workflows, and robust privacy protection. These tools are increasingly focusing on proactive knowledge surfacing rather than passive storage.',
+          id: 'pkm-features-text-01',
+        },
+      ],
+    };
+
+    // const data = await sanitizeObjects(TYPES, TEST_DATA, db);
+    // log.info('data', { data });
+  });
+});

package/src/research/research.ts

@@ -0,0 +1,89 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { Schema } from 'effect';
+
+import { AgentStatusReport, ConsolePrinter } from '@dxos/ai';
+import { create } from '@dxos/echo-schema';
+import { AiService, CredentialsService, DatabaseService, defineFunction, TracingService } from '@dxos/functions';
+import { log } from '@dxos/log';
+import { DataTypes } from '@dxos/schema';
+
+import { createExaTool, createMockExaTool } from './exa';
+import { createGraphWriterTool } from './graph';
+// TODO(dmaretskyi): Vite build bug with instruction files with the same filename getting mixed-up
+import PROMPT from './instructions-research.tpl?raw';
+import { AISession } from '../session';
+
+/**
+ * Exec external service and return the results as a Subgraph.
+ */
+// TODO(burdon): Rename.
+export const researchFn = defineFunction({
+  description: 'Research the web for information',
+  inputSchema: Schema.Struct({
+    query: Schema.String.annotations({
+      description: 'The query to search for.',
+    }),
+
+    // TOOD(burdon): Move to context.
+    mockSearch: Schema.optional(Schema.Boolean).annotations({
+      description: 'Whether to use the mock search tool.',
+      default: false,
+    }),
+  }),
+  outputSchema: Schema.Struct({
+    // result: Schema.String,
+    result: Schema.Any,
+  }),
+  handler: async ({ data: { query, mockSearch }, context }) => {
+    const ai = context.getService(AiService);
+    const credentials = context.getService(CredentialsService);
+    const { db } = context.getService(DatabaseService);
+    // const queues = context.getService(QueuesService);
+    const tracing = context.getService(TracingService);
+
+    tracing.write(create(AgentStatusReport, { message: 'Researching...' }));
+
+    const exaCredential = await credentials.getCredential({ service: 'exa.ai' });
+    const searchTool = mockSearch ? createMockExaTool() : createExaTool({ apiKey: exaCredential.apiKey! });
+
+    const printer = new ConsolePrinter();
+    const session = new AISession({ operationModel: 'configured' });
+    session.message.on((message) => printer.printMessage(message));
+    session.userMessage.on((message) => printer.printMessage(message));
+    session.block.on((block) => printer.printContentBlock(block));
+    session.statusReport.on((status) => {
+      log.info('[agent] status', { status });
+      tracing.write(status);
+    });
+    session.streamEvent.on((event) => log('stream', { event }));
+
+    const graphWriteTool = createGraphWriterTool({ db, schemaTypes: DataTypes });
+    log.info('graphWriteTool', { schema: graphWriteTool.parameters });
+
+    // TODO(dmaretskyi): Consider adding this pattern as the "Graph" output mode for the session.
+    const result = await session.run({
+      client: ai.client,
+      systemPrompt: PROMPT,
+      artifacts: [],
+      tools: [searchTool, graphWriteTool],
+      history: [],
+      prompt: query,
+    });
+
+    return {
+      result: result as any,
+    };
+
+    // queues.contextQueue!.append(data);
+
+    // return {
+    //   result: `
+    //   The research results are placed in the following objects:
+    //     ${data.map((object, id) => `[obj_${id}][dxn:echo:@:${object.id}]`).join('\n')}
+    //   `,
+    // };
+  },
+});

package/src/session/index.ts

@@ -4,4 +4,3 @@
 
 export * from './session';
 export * from './version-pin';
-export * from './tools';

package/src/session/session.test.ts

@@ -5,15 +5,15 @@
 import { Schema } from 'effect';
 import { describe, test } from 'vitest';
 
-import { ArtifactId, defineArtifact, defineTool, ToolResult } from '@dxos/artifact';
-import { AIServiceEdgeClient } from '@dxos/assistant';
+import { AIServiceEdgeClient, ConsolePrinter, createTool, ToolResult } from '@dxos/ai';
+import { AI_SERVICE_ENDPOINT } from '@dxos/ai/testing';
+import { ArtifactId, defineArtifact } from '@dxos/artifact';
 import { Type } from '@dxos/echo';
 import { create, ObjectId } from '@dxos/echo-schema';
 import { DXN } from '@dxos/keys';
 import { log } from '@dxos/log';
 
 import { AISession } from './session';
-import { AI_SERVICE_ENDPOINT, ConsolePrinter } from '../testing';
 
 // Define a calendar event artifact schema.
 const CalendarEventSchema = Schema.Struct({
@@ -22,7 +22,7 @@ const CalendarEventSchema = Schema.Struct({
   endTime: Schema.String,
   description: Schema.String,
 }).pipe(
-  Type.def({
+  Type.Obj({
     typename: 'example.com/type/CalendarEvent',
     version: '0.1.0',
   }),
@@ -48,7 +48,7 @@ describe.skip('AISession with Ollama', () => {
       instructions: 'Use this to create and query calendar events.',
       schema: CalendarEventSchema,
       tools: [
-        defineTool('calendar', {
+        createTool('calendar', {
           name: 'query',
           description: 'Query the calendar for events',
           schema: Schema.Struct({}),
@@ -65,7 +65,7 @@ describe.skip('AISession with Ollama', () => {
       instructions: 'Use this to create and manage tables. Each table has a unique id.',
       schema: Schema.Struct({}),
       tools: [
-        defineTool('table', {
+        createTool('table', {
           name: 'create',
           description: 'Create a table',
           schema: Schema.Struct({
@@ -89,7 +89,7 @@ describe.skip('AISession with Ollama', () => {
         'Use this to create and manage maps. Maps source data from tables. Table id is required to create a map.',
       schema: Schema.Struct({}),
       tools: [
-        defineTool('map', {
+        createTool('map', {
           name: 'create',
           description: 'Create a map',
           schema: Schema.Struct({

package/src/session/session.ts

@@ -5,23 +5,29 @@
 import { Option, Schema } from 'effect';
 
 import {
-  defineTool,
-  Message,
+  AgentStatusReport,
+  isToolUse,
+  runTools,
+  type AgentStatus,
   structuredOutputParser,
-  ToolResult,
-  type ArtifactDefinition,
+  type AIServiceClient,
+  type GenerationStream,
+  type GenerateRequest,
+  Message,
   type MessageContentBlock,
-  type Tool,
-} from '@dxos/artifact';
+  MixedStreamParser,
+  ToolResult,
+  createTool,
+  type ExecutableTool,
+} from '@dxos/ai';
+import { type ArtifactDefinition } from '@dxos/artifact';
 import { Event, synchronized } from '@dxos/async';
 import { ObjectVersion } from '@dxos/echo-db';
 import { create, type ObjectId } from '@dxos/echo-schema';
 import { invariant } from '@dxos/invariant';
 import { log } from '@dxos/log';
 
-import { isToolUse, runTools } from './tools';
 import { VersionPin } from './version-pin';
-import { MixedStreamParser, type AIServiceClient, type GenerateRequest, type GenerationStream } from '../ai-service';
 
 /**
  * Contains message history, tools, current context.
@@ -58,7 +64,7 @@ export type SessionRunOptions = {
   /**
    * Non-artifact specific tools.
    */
-  tools: Tool[];
+  tools: ExecutableTool[];
 
   history: Message[];
 
@@ -129,16 +135,28 @@ export class AISession {
    */
   public readonly userMessage = new Event<Message>();
 
+  /**
+   * Agent self-reporting its status.
+   */
+  public readonly statusReport = new Event<AgentStatus>();
+
+  public readonly toolStatusReport = new Event<{ message: Message; status: AgentStatus }>();
+
   constructor(private readonly _options: AiSessionOptions) {
     // Message complete.
     this._parser.message.on((message) => {
       this._pending.push(message);
     });
+    this._parser.block.on((block) => {
+      if (block.type === 'text' && block.disposition === 'status') {
+        this.statusReport.emit(create(AgentStatusReport, { message: block.text }));
+      }
+    });
   }
 
   @synchronized
   async run(options: SessionRunOptions): Promise<Message[]> {
-    const systemTools: Tool[] = [];
+    const systemTools: ExecutableTool[] = [];
     switch (this._options.operationModel) {
       case 'planning':
         systemTools.push(this._createQueryArtifactsTool(options.artifacts), this._createPlanningTool(options));
@@ -164,13 +182,14 @@ export class AISession {
     this._pending = [await this._formatUserPrompt(options.artifactDiffResolver, options.prompt, options.history)];
     this.userMessage.emit(this._pending.at(-1)!);
     this._stream = undefined;
+
     let error: Error | undefined;
 
     const requiredArtifactIds = new Set<string>(options.requiredArtifactIds ?? []);
     try {
       let more = false;
       do {
-        const tools = [
+        const tools: ExecutableTool[] = [
           ...systemTools,
           ...options.tools,
           ...options.artifacts
@@ -215,6 +234,7 @@ export class AISession {
             message: this._pending.at(-1)!,
             tools,
             extensions: options.extensions ?? {},
+            reportStatus: (status) => this._onToolStatusReport(message, status),
           });
 
           log('tool response', { response });
@@ -246,7 +266,10 @@ export class AISession {
     return this._pending;
   }
 
-  async runStructured<S extends Schema.Schema.AnyNoContext>(schema: S, options: SessionRunOptions) {
+  async runStructured<S extends Schema.Schema.AnyNoContext>(
+    schema: S,
+    options: SessionRunOptions,
+  ): Promise<Schema.Schema.Type<S>> {
     const parser = structuredOutputParser(schema);
     const result = await this.run({
       ...options,
@@ -293,8 +316,8 @@ export class AISession {
     });
   }
 
-  private _createQueryArtifactsTool(artifacts: ArtifactDefinition[]) {
-    return defineTool('system', {
+  private _createQueryArtifactsTool(artifacts: ArtifactDefinition[]): ExecutableTool {
+    return createTool('system', {
       name: 'query_artifact_definitions',
       description: 'Query the available artifact definitions',
       schema: Schema.Struct({}),
@@ -313,8 +336,8 @@ export class AISession {
   private _createRequireTool(
     artifacts: ArtifactDefinition[],
     onRequire: (artifactDefinitionIds: readonly string[]) => void,
-  ) {
-    return defineTool('system', {
+  ): ExecutableTool {
+    return createTool('system', {
       name: 'require_artifact_definitions',
       description:
         'Require the use of specific artifact definitions. This will allow the model to interact with artifact definitions and use their tools.',
@@ -341,8 +364,8 @@ export class AISession {
     });
   }
 
-  private _createPlanningTool(options: SessionRunOptions) {
-    return defineTool('system', {
+  private _createPlanningTool(options: SessionRunOptions): ExecutableTool {
+    return createTool('system', {
       name: 'create_plan',
       description:
         'Create a plan. Make sure that each step is independent and can be executed solely on the data returned by the previous step. The steps only share the data that is specified in the plan.',
@@ -425,7 +448,11 @@ export class AISession {
     });
   }
 
-  abort() {
+  private _onToolStatusReport(message: Message, status: AgentStatus): void {
+    this.toolStatusReport.emit({ message, status });
+  }
+
+  abort(): void {
     this._stream?.abort();
   }
 }

package/src/session/version-pin.ts

@@ -4,8 +4,8 @@
 
 import { Schema } from 'effect';
 
-import type { MessageContentBlock } from '@dxos/artifact';
-import type { ObjectVersion } from '@dxos/echo-db';
+import { type MessageContentBlock } from '@dxos/ai';
+import { type ObjectVersion } from '@dxos/echo-db';
 import { getVersion } from '@dxos/echo-db';
 import { ObjectId, type BaseEchoObject } from '@dxos/echo-schema';
 
@@ -21,7 +21,6 @@ const VersionPinSchema = Schema.Struct({
 
 /**
  * Used to pin a specific version of an object during the course of a conversation.
- *
  * This allows us to detect when the object changes during the course of the conversation.
  */
 export interface VersionPin extends Schema.Schema.Type<typeof VersionPinSchema> {}