@dxos/assistant 0.8.2 → 0.8.3-main.7f5a14c

package/src/blueprint/ai.test.ts

@@ -0,0 +1,156 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { AiChat, AiInput, AiLanguageModel, AiTool, AiToolkit } from '@effect/ai';
+import { AnthropicClient, AnthropicLanguageModel } from '@effect/ai-anthropic';
+import { OpenAiClient, OpenAiLanguageModel } from '@effect/ai-openai';
+import { NodeHttpClient } from '@effect/platform-node';
+import { Config, Console, Effect, Layer, pipe, Schedule, Schema } from 'effect';
+import { describe, it } from 'vitest';
+
+import { log } from '@dxos/log';
+
+// https://effect.website/docs/ai/tool-use/#5-bring-it-all-together
+// https://github.com/Effect-TS/effect/blob/main/packages/ai/ai/CHANGELOG.md
+// https://discord.com/channels/795981131316985866/1338871274398679130
+
+/**
+ * Rationale:
+ * - Separation of concerns: config, execution pipline, error handling/retry, tool dispatch, async.
+ * - Uncouple tool definitions from tool implementation (late binding, composition).
+ * - Affinity with effect schema.
+ * - Leverage existing effect based conductor pipline.
+ * - Simple API for plugins/artifacts.
+ * - Ecosystem and design partner.
+ */
+describe.runIf(!process.env.CI)('AiLanguageModel', () => {
+  it.runIf(process.env.OPENAI_API_KEY)('Debug: Verify API configuration', async ({ expect }) => {
+    const program = Effect.gen(function* () {
+      yield* Console.log('Testing API connectivity...');
+      const response = yield* AiLanguageModel.generateText({ prompt: 'Hello, respond with "API is working"' });
+      yield* Console.log('API Response received:', response.text);
+      return response.text;
+    }).pipe(
+      Effect.provide(OpenAiLanguageModel.model('gpt-4o')),
+      Effect.timeout('10 seconds'),
+      Effect.retry({ times: 1 }),
+    );
+
+    const result = await program.pipe(
+      Effect.provide([
+        OpenAiClient.layerConfig({
+          apiKey: Config.redacted('OPENAI_API_KEY'),
+        }).pipe(Layer.provide(NodeHttpClient.layerUndici)),
+      ]),
+      Effect.runPromise,
+    );
+
+    expect(result).to.contain('working');
+  });
+
+  // Tool definitions.
+  class Toolkit extends AiToolkit.make(
+    AiTool.make('Calculator', {
+      description: 'Test tool',
+      parameters: {
+        input: Schema.String.annotations({
+          description: 'The calculation to perform.',
+        }),
+      },
+      success: Schema.Struct({
+        result: Schema.Number,
+      }),
+      failure: Schema.Never,
+    }),
+  ) {}
+
+  // Tool handlers.
+  const ToolkitLayer = Toolkit.toLayer({
+    Calculator: ({ input }) =>
+      Effect.gen(function* () {
+        const result = (() => {
+          // Only allow basic arithmetic operations for safety.
+          const sanitizedInput = input.replace(/[^0-9+\-*/().\s]/g, '');
+          // eslint-disable-next-line no-new-func
+          return Function(`"use strict"; return (${sanitizedInput})`)();
+        })();
+
+        yield* Console.log(`Executing calculation: ${input} = ${result}`);
+        return { result };
+      }),
+  });
+
+  // Providers.
+  const OpenAiLayer = OpenAiClient.layerConfig({
+    apiKey: Config.redacted('OPENAI_API_KEY'),
+  }).pipe(Layer.provide(NodeHttpClient.layerUndici));
+
+  const AnthropicLayer = AnthropicClient.layerConfig({
+    apiKey: Config.redacted('ANTHROPIC_API_KEY'),
+  }).pipe(Layer.provide(NodeHttpClient.layerUndici));
+
+  it.runIf(process.env.OPENAI_API_KEY)('should make a tool call', async ({ expect }) => {
+    const createProgram = (prompt: string) =>
+      AiLanguageModel.generateText({
+        toolkit: Toolkit,
+        prompt,
+      }).pipe(
+        Effect.tap((response) => Console.log(response)),
+        Effect.provide(OpenAiLanguageModel.model('gpt-4o')),
+        Effect.retry(pipe(Schedule.exponential('1 second'), Schedule.intersect(Schedule.recurs(2)))),
+        Effect.timeout('30 seconds'),
+      );
+
+    const program = createProgram('What is six times seven? Use appropriate tools and just answer with the number.');
+    const result = await program.pipe(Effect.provide([ToolkitLayer, OpenAiLayer]), Effect.runPromise);
+    expect(result).toBeDefined();
+  });
+
+  // TODO(burdon): Is thisthe effectful way to do this?
+  const createChat = (prompt: string) =>
+    Effect.gen(function* () {
+      const chat = yield* AiChat.empty;
+      const toolkit = yield* Toolkit;
+
+      // Initial request.
+      let response = yield* chat.generateText({ toolkit, prompt });
+
+      // Agentic loop.
+      while (response.results.size > 0) {
+        response = yield* chat.generateText({ toolkit, prompt: AiInput.empty });
+      }
+
+      // Done.
+      return response.text;
+    });
+
+  it.runIf(process.env.OPENAI_API_KEY)('should process an agentic loop using OpenAI', async ({ expect }) => {
+    const chat = createChat('What is six times seven?');
+    const result = await chat.pipe(
+      Effect.provide(OpenAiLanguageModel.model('gpt-4o')),
+      Effect.provide(OpenAiLayer),
+      Effect.provide(ToolkitLayer),
+      Effect.runPromise,
+    );
+
+    log.info('result', { result });
+    expect(result).toContain('42');
+  });
+
+  // TODO(burdon): Fix Anthropic.
+  it.runIf(process.env.ANTHROPIC_API_KEY).skip('should process an agentic loop using Anthropic', async ({ expect }) => {
+    const chat = createChat('What is six times seven?');
+    const result = await chat.pipe(
+      Effect.provide(AnthropicLanguageModel.model('claude-3-5-sonnet-latest')),
+      Effect.provide(AnthropicLayer),
+      Effect.provide(ToolkitLayer),
+      Effect.runPromise,
+    );
+
+    log.info('result', { result });
+    expect(result).toContain('42');
+  });
+
+  // TODO(burdon): Implement MCP server for ECHO on CF.
+});

package/src/blueprint/blueprint.test.ts

@@ -5,7 +5,7 @@
 import { Schema } from 'effect';
 import { describe, test } from 'vitest';
 
-import { AIServiceEdgeClient, ToolResult, createTool } from '@dxos/ai';
+import { AIServiceEdgeClient, ToolRegistry, ToolResult, createTool } from '@dxos/ai';
 import { AI_SERVICE_ENDPOINT, EXA_API_KEY } from '@dxos/ai/testing';
 import { ArtifactId } from '@dxos/artifact';
 import { EchoTestBuilder } from '@dxos/echo-db/testing';
@@ -23,7 +23,7 @@ import { createExaTool } from '../research/exa';
 
 // TODO(burdon): Don't run on CI.
 describe.skip('Blueprint', () => {
-  const aiService = new AIServiceEdgeClient({
+  const aiClient = new AIServiceEdgeClient({
     endpoint: AI_SERVICE_ENDPOINT.REMOTE,
     defaultGenerationOptions: {
       // model: '@anthropic/claude-sonnet-4-20250514',
@@ -39,9 +39,10 @@ describe.skip('Blueprint', () => {
       .step('Write a pitch deck for the product')
       .build();
 
-    const machine = new BlueprintMachine(blueprint);
+    const tools = new ToolRegistry([]);
+    const machine = new BlueprintMachine(tools, blueprint);
     setConsolePrinter(machine, true);
-    await machine.runToCompletion({ aiService });
+    await machine.runToCompletion({ aiClient });
   });
 
   test('email bot', { timeout: 60_000 }, async () => {
@@ -82,22 +83,23 @@ describe.skip('Blueprint', () => {
         'Determine if the email is introduction, question, or spam. Bail if email does not fit into one of these categories.',
       )
       .step('If the email is spam, label it as spam and do not respond.', {
-        tools: [labelTool],
+        tools: [labelTool.id],
       })
       .step(
         'If the email is an introduction, respond with a short introduction of yourself and ask for more information.',
         {
-          tools: [replyTool],
+          tools: [replyTool.id],
         },
       )
       .step('If the email is a question, respond with a short answer and ask for more information.', {
-        tools: [replyTool],
+        tools: [replyTool.id],
       })
       .build();
 
-    const machine = new BlueprintMachine(blueprint);
+    const tools = new ToolRegistry([replyTool, labelTool]);
+    const machine = new BlueprintMachine(tools, blueprint);
     setConsolePrinter(machine);
-    await machine.runToCompletion({ aiService, input: TEST_EMAILS[0] });
+    await machine.runToCompletion({ aiClient, input: TEST_EMAILS[0] });
   });
 
   test.only('research', { timeout: 120_000 }, async () => {
@@ -123,20 +125,27 @@ describe.skip('Blueprint', () => {
 
     await db.flush({ indexes: true });
 
+    const [exa, localSearch, graphWriter] = [
+      createExaTool({ apiKey: EXA_API_KEY }),
+      createLocalSearchTool(db),
+      createGraphWriterTool({ db, schema: DataTypes }),
+    ];
+
     const blueprint = BlueprintBuilder.create()
       .step('Research founders of the organization. Do deep research.', {
-        tools: [createExaTool({ apiKey: EXA_API_KEY })],
+        tools: [exa.id],
       })
       .step('Based on your research select matching entires that are already in the graph', {
-        tools: [createLocalSearchTool(db)],
+        tools: [localSearch.id],
       })
       .step('Add researched data to the graph', {
-        tools: [createLocalSearchTool(db), createGraphWriterTool({ db, schemaTypes: DataTypes })],
+        tools: [localSearch.id, graphWriter.id],
       })
       .build();
 
-    const machine = new BlueprintMachine(blueprint);
+    const tools = new ToolRegistry([exa, localSearch, graphWriter]);
+    const machine = new BlueprintMachine(tools, blueprint);
     setConsolePrinter(machine, true);
-    await machine.runToCompletion({ aiService, input: org1 });
+    await machine.runToCompletion({ aiClient, input: org1 });
   });
 });

package/src/blueprint/blueprint.ts

@@ -4,21 +4,29 @@
 
 import { Schema } from 'effect';
 
-import { type ExecutableTool, Tool } from '@dxos/ai';
-import { raise } from '@dxos/debug';
-import { ObjectId } from '@dxos/keys';
+import { Key, Obj, Type } from '@dxos/echo';
 
 export const BlueprintStep = Schema.Struct({
-  id: Schema.String,
+  id: Key.ObjectId,
   instructions: Schema.String,
-  // TODO(burdon): ExecutableTool can't be serialized.
-  tools: Schema.Array(Tool).pipe(Schema.mutable),
+  tools: Schema.optional(Schema.Array(Schema.String)),
 });
 export interface BlueprintStep extends Schema.Schema.Type<typeof BlueprintStep> {}
 
-export const Blueprint = Schema.Struct({
-  steps: Schema.Array(BlueprintStep).pipe(Schema.mutable),
+export const BlueprintDefinition = Schema.Struct({
+  steps: Schema.Array(BlueprintStep.pipe(Schema.omit('id'))),
 });
+export interface BlueprintDefinition extends Schema.Schema.Type<typeof BlueprintDefinition> {}
+
+export const Blueprint = Schema.Struct({
+  name: Schema.optional(Schema.String),
+  steps: Schema.Array(BlueprintStep),
+}).pipe(
+  Type.Obj({
+    typename: 'dxos.org/type/Blueprint',
+    version: '0.1.0',
+  }),
+);
 export interface Blueprint extends Schema.Schema.Type<typeof Blueprint> {}
 
 /**
@@ -30,9 +38,9 @@ export namespace BlueprintBuilder {
   class Builder {
     private readonly _steps: BlueprintStep[] = [];
 
-    step(instructions: string, options?: { tools?: ExecutableTool[] }): Builder {
+    step(instructions: string, options?: { tools?: string[] }): Builder {
       this._steps.push({
-        id: ObjectId.random(),
+        id: Key.ObjectId.random(),
         instructions,
         tools: options?.tools ?? [],
       });
@@ -41,9 +49,7 @@ export namespace BlueprintBuilder {
     }
 
     build(): Blueprint {
-      return {
-        steps: this._steps,
-      };
+      return Obj.make(Blueprint, { steps: this._steps });
     }
   }
 }
@@ -52,40 +58,14 @@ export namespace BlueprintBuilder {
  * Blueprint parser API.
  */
 export namespace BlueprintParser {
-  export type Step = {
-    instructions: string;
-    // TODO(burdon): Tool DXN? Additional metadata?
-    tools?: string[];
-  };
-
-  export type DSL = {
-    steps: Step[];
-  };
-
-  export const create = (tools: ExecutableTool[] = []) => new Parser(tools);
+  export const create = () => new Parser();
 
   class Parser {
-    constructor(private readonly _tools: ExecutableTool[]) {}
-
-    toJSON() {
-      return {
-        tools: this._tools.map((tool) => ({
-          name: tool.name,
-          namespace: tool.namespace,
-          type: tool.type,
-        })),
-      };
-    }
-
-    parse({ steps }: DSL): Blueprint {
+    parse({ steps }: BlueprintDefinition): Blueprint {
       const builder = BlueprintBuilder.create();
-
       for (const step of steps) {
         builder.step(step.instructions, {
-          // TODO(burdon): Tool resolution is duplicated in the session and ollama-client.
-          tools: step.tools?.map(
-            (tool) => this._tools.find(({ id }) => id === tool) ?? raise(new Error(`Tool not found: ${tool}`)),
-          ),
+          tools: (step.tools ?? []) as string[],
         });
       }
 

package/src/blueprint/logger.ts

@@ -2,41 +2,130 @@
 // Copyright 2025 DXOS.org
 //
 
+import { type ReadonlySignal, signal } from '@preact/signals-core';
 import chalk from 'chalk';
 
 import { ConsolePrinter } from '@dxos/ai';
+import { type CleanupFn, combine } from '@dxos/async';
+import { log } from '@dxos/log';
 
 import { type Blueprint } from './blueprint';
-import { type BlueprintMachine, type BlueprintMachineState } from './machine';
+import {
+  type BlueprintEvent,
+  type BlueprintLogger,
+  type BlueprintMachine,
+  type BlueprintMachineState,
+} from './machine';
 
 /* eslint-disable no-console */
 
-// Force chalk colors on for tests
+// Force chalk colors on for tests.
 chalk.level = 2;
 
-export const setConsolePrinter = (machine: BlueprintMachine, extraLogging = false) => {
+// TODO(burdon): Factor out.
+type ConsoleLogSignature = (message: string, arg?: any) => void;
+
+interface Logger {
+  log: ConsoleLogSignature;
+}
+
+const DEFAULT_LOGGER: Logger = { log: log.info };
+
+/**
+ * Reactive bufferedlogger.
+ */
+export class BufferedLogger implements Logger {
+  private _messages = signal<string[]>([]);
+
+  get messages(): ReadonlySignal<string[]> {
+    return this._messages;
+  }
+
+  clear() {
+    this._messages.value = [];
+  }
+
+  log(message: string) {
+    this._messages.value = [...this._messages.value, message];
+  }
+}
+
+// TODO(burdon): Reconcile with ConsolePrinter.
+export class BlueprintLoggerAdapter implements BlueprintLogger {
+  constructor(private readonly logger: Logger = DEFAULT_LOGGER) {}
+
+  log(event: BlueprintEvent) {
+    switch (event.type) {
+      case 'begin':
+        this.logger.log('begin');
+        break;
+      case 'end':
+        this.logger.log('end');
+        break;
+      case 'step-start':
+        this.logger.log('step-start', { step: event.step });
+        break;
+      case 'step-complete':
+        this.logger.log('step-complete', { step: event.step });
+        break;
+      case 'message':
+        this.logger.log('message', { message: event.message });
+        break;
+      case 'block':
+        this.logger.log('block', { block: event.block });
+        break;
+    }
+  }
+}
+
+export const setLogger = (machine: BlueprintMachine, logger: BufferedLogger): CleanupFn => {
+  return combine(
+    machine.begin.on(() => {
+      logger.log('Starting...');
+    }),
+    machine.stepStart.on((step) => {
+      const index = machine.blueprint.steps.indexOf(step);
+      logger.log(`Step ${index + 1} of ${machine.blueprint.steps.length}`);
+      logger.log(`Instructions: ${step.instructions}`);
+    }),
+    machine.stepComplete.on((step) => {
+      const trace = machine.state.trace.find((t) => t.stepId === step.id);
+      logger.log(`Complete: ${trace?.comment}`);
+    }),
+    machine.end.on(() => {
+      logger.log('OK');
+    }),
+  );
+};
+
+export const setConsolePrinter = (machine: BlueprintMachine, verbose = false): CleanupFn => {
   const printer = new ConsolePrinter();
-  if (extraLogging) {
+  return combine(
+    machine.begin.on(() => printTrace(machine.blueprint, machine.state)),
     machine.stepStart.on((step) =>
       console.log(
         `\n${chalk.magenta(`${chalk.bold(`STEP ${machine.blueprint.steps.indexOf(step) + 1} of ${machine.blueprint.steps.length}:`)} ${step.instructions}`)}\n`,
       ),
-    );
-    machine.message.on((msg) => printer.printMessage(msg));
-    machine.block.on((block) => printer.printContentBlock(block));
-  }
-  machine.begin.on(() => printTrace(machine.blueprint, machine.state));
-  machine.stepComplete.on(() => printTrace(machine.blueprint, machine.state));
+    ),
+    machine.stepComplete.on(() => printTrace(machine.blueprint, machine.state)),
+    machine.end.on(() => console.log('DONE')),
+    verbose
+      ? [
+          machine.message.on((msg) => printer.printMessage(msg)),
+          machine.block.on((block) => printer.printContentBlock(block)),
+        ]
+      : [],
+  );
 };
 
-const printTrace = (blueprint: Blueprint, state: BlueprintMachineState) => {
-  console.log('\n==============================================\n');
-  console.log(chalk.bold('\nThe Blueprint:'));
+const BREAK_LINE = `\n${'_'.repeat(80)}\n`;
 
-  blueprint.steps.forEach((step, index) => {
+const printTrace = (blueprint: Blueprint, state: BlueprintMachineState) => {
+  console.group(chalk.bold('\nBlueprint'));
+  blueprint.steps.forEach((step) => {
     const traceStep = state.trace.find((t) => t.stepId === step.id);
 
-    let color = chalk.gray; // Not executed
+    let color = chalk.gray; // Not executed.
     let bullet = '○';
     if (traceStep) {
       switch (traceStep.status) {
@@ -56,11 +145,11 @@ const printTrace = (blueprint: Blueprint, state: BlueprintMachineState) => {
     }
 
     console.log(color(`\n${bullet} ${step.instructions}`));
-
     if (traceStep?.comment) {
-      console.log(chalk.white(`    ↳ ${traceStep.comment}`));
+      console.log(chalk.white(`  ↳ ${traceStep.comment}`));
     }
   });
-  console.log('\n');
-  console.log('\n==============================================\n');
+
+  console.groupEnd();
+  console.log(BREAK_LINE);
 };