@dxos/assistant 0.8.3 → 0.8.4-main.f9ba587

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dxos/assistant",
-  "version": "0.8.3",
+  "version": "0.8.4-main.f9ba587",
   "description": "Natural language interface to DXOS",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
@@ -25,37 +25,28 @@
     "@xenova/transformers": "^2.17.2",
     "chalk": "^4.1.0",
     "exa-js": "^1.5.12",
-    "@dxos/ai": "0.8.3",
-    "@dxos/artifact": "0.8.3",
-    "@dxos/context": "0.8.3",
-    "@dxos/async": "0.8.3",
-    "@dxos/debug": "0.8.3",
-    "@dxos/echo": "0.8.3",
-    "@dxos/echo-db": "0.8.3",
-    "@dxos/echo-protocol": "0.8.3",
-    "@dxos/echo-schema": "0.8.3",
-    "@dxos/functions": "0.8.3",
-    "@dxos/graph": "0.8.3",
-    "@dxos/effect": "0.8.3",
-    "@dxos/keys": "0.8.3",
-    "@dxos/invariant": "0.8.3",
-    "@dxos/live-object": "0.8.3",
-    "@dxos/log": "0.8.3",
-    "@dxos/node-std": "0.8.3",
-    "@dxos/util": "0.8.3",
-    "@dxos/schema": "0.8.3"
+    "@dxos/ai": "0.8.4-main.f9ba587",
+    "@dxos/artifact": "0.8.4-main.f9ba587",
+    "@dxos/async": "0.8.4-main.f9ba587",
+    "@dxos/context": "0.8.4-main.f9ba587",
+    "@dxos/debug": "0.8.4-main.f9ba587",
+    "@dxos/echo-db": "0.8.4-main.f9ba587",
+    "@dxos/echo-protocol": "0.8.4-main.f9ba587",
+    "@dxos/echo-schema": "0.8.4-main.f9ba587",
+    "@dxos/effect": "0.8.4-main.f9ba587",
+    "@dxos/graph": "0.8.4-main.f9ba587",
+    "@dxos/functions": "0.8.4-main.f9ba587",
+    "@dxos/echo": "0.8.4-main.f9ba587",
+    "@dxos/invariant": "0.8.4-main.f9ba587",
+    "@dxos/live-object": "0.8.4-main.f9ba587",
+    "@dxos/keys": "0.8.4-main.f9ba587",
+    "@dxos/log": "0.8.4-main.f9ba587",
+    "@dxos/schema": "0.8.4-main.f9ba587",
+    "@dxos/node-std": "0.8.4-main.f9ba587",
+    "@dxos/util": "0.8.4-main.f9ba587"
   },
   "devDependencies": {
-    "@effect/ai": "^0.19.4",
-    "@effect/ai-anthropic": "^0.9.5",
-    "@effect/ai-openai": "^0.22.4",
-    "@effect/cluster": "^0.39.4",
-    "@effect/experimental": "^0.49.2",
-    "@effect/platform": "^0.85.2",
-    "@effect/platform-node": "^0.86.4",
-    "@effect/rpc": "^0.62.4",
-    "@effect/sql": "^0.38.2",
-    "effect": "3.14.21",
+    "effect": "3.16.13",
     "inquirer": "^12.0.0"
   },
   "peerDependencies": {

package/src/blueprint/blueprint.ts

@@ -4,72 +4,72 @@
 
 import { Schema } from 'effect';
 
-import { Key, Obj, Type } from '@dxos/echo';
+import { ToolId } from '@dxos/ai';
+import { Type } from '@dxos/echo';
+import { LabelAnnotation } from '@dxos/echo-schema';
 
-export const BlueprintStep = Schema.Struct({
-  id: Key.ObjectId,
-  instructions: Schema.String,
-  tools: Schema.optional(Schema.Array(Schema.String)),
-});
-export interface BlueprintStep extends Schema.Schema.Type<typeof BlueprintStep> {}
+/**
+ * Blueprint schema defines the structure for AI assistant blueprints.
+ * Blueprints contain instructions, tools, and artifacts that guide the AI's behavior.
+ */
+export const Blueprint = Schema.Struct({
+  /**
+   * Global registry ID.
+   * NOTE: Once a blueprint has been cloned from the registry, its stored definition may converge,
+   * but the `key` property refers to the original registry entry.
+   */
+  // TODO(burdon): Create Format type.
+  key: Schema.String.annotations({
+    description: 'Unique registration key for the blueprint',
+  }),
 
-export const BlueprintDefinition = Schema.Struct({
-  steps: Schema.Array(BlueprintStep.pipe(Schema.omit('id'))),
-});
-export interface BlueprintDefinition extends Schema.Schema.Type<typeof BlueprintDefinition> {}
+  /**
+   * Human-readable name of the blueprint.
+   */
+  name: Schema.String.annotations({
+    description: 'Human-readable name of the blueprint',
+  }),
 
-export const Blueprint = Schema.Struct({
-  name: Schema.optional(Schema.String),
-  steps: Schema.Array(BlueprintStep),
+  /**
+   * Description of the blueprint's purpose and functionality.
+   */
+  description: Schema.optional(Schema.String).annotations({
+    description: "Description of the blueprint's purpose and functionality",
+  }),
+
+  /**
+   * Instructions that guide the AI assistant's behavior and responses.
+   * These are system prompts or guidelines that the AI should follow.
+   */
+  instructions: Schema.String.annotations({
+    description: "Instructions that guide the AI assistant's behavior and responses",
+  }),
+
+  /**
+   * Array of tools that the AI assistant can use when this blueprint is active.
+   */
+  tools: Schema.Array(ToolId).annotations({
+    description: 'Array of tools that the AI assistant can use when this blueprint is active',
+  }),
+
+  /**
+   * Array of artifacts that the AI assistant can create or modify.
+   */
+  artifacts: Schema.Array(Schema.String).annotations({
+    description: 'Ids of artifact definitions that should be pulled into the blueprint',
+  }),
 }).pipe(
   Type.Obj({
+    // TODO(burdon): Is this a DXN? Need to create a Format type for these IDs.
     typename: 'dxos.org/type/Blueprint',
     version: '0.1.0',
   }),
-);
-export interface Blueprint extends Schema.Schema.Type<typeof Blueprint> {}
-
-/**
- * Blueprint builder API.
- */
-export namespace BlueprintBuilder {
-  export const create = () => new Builder();
-
-  class Builder {
-    private readonly _steps: BlueprintStep[] = [];
 
-    step(instructions: string, options?: { tools?: string[] }): Builder {
-      this._steps.push({
-        id: Key.ObjectId.random(),
-        instructions,
-        tools: options?.tools ?? [],
-      });
-
-      return this;
-    }
-
-    build(): Blueprint {
-      return Obj.make(Blueprint, { steps: this._steps });
-    }
-  }
-}
+  // TODO(burdon): Move to main API.
+  LabelAnnotation.set(['name']),
+);
 
 /**
- * Blueprint parser API.
+ * TypeScript type for Blueprint.
  */
-export namespace BlueprintParser {
-  export const create = () => new Parser();
-
-  class Parser {
-    parse({ steps }: BlueprintDefinition): Blueprint {
-      const builder = BlueprintBuilder.create();
-      for (const step of steps) {
-        builder.step(step.instructions, {
-          tools: (step.tools ?? []) as string[],
-        });
-      }
-
-      return builder.build();
-    }
-  }
-}
+export interface Blueprint extends Schema.Schema.Type<typeof Blueprint> {}

package/src/blueprint/index.ts

@@ -3,5 +3,4 @@
 //
 
 export * from './blueprint';
-export * from './machine';
-export * from './logger';
+export * from './registry';

package/src/blueprint/registry.ts

@@ -0,0 +1,15 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type Blueprint } from './blueprint';
+
+export class BlueprintRegistry {
+  constructor(private readonly _blueprints: Blueprint[]) {
+    this._blueprints.sort(({ name: a }, { name: b }) => a.localeCompare(b));
+  }
+
+  query(): Blueprint[] {
+    return this._blueprints;
+  }
+}

package/src/context/binder.ts

@@ -0,0 +1,101 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { computed, type ReadonlySignal } from '@preact/signals-core';
+import { Array, pipe } from 'effect';
+
+import { Obj, type Type, type Ref, type Relation } from '@dxos/echo';
+import { type Queue } from '@dxos/echo-db';
+import { ComplexSet } from '@dxos/util';
+
+import { ContextBinding } from './binding';
+import { type Blueprint } from '../blueprint';
+
+/**
+ * Manages bindings of blueprints and objects to a conversation.
+ */
+export class ContextBinder {
+  constructor(private readonly _queue: Queue) {}
+
+  /**
+   * Reactive query of all bindings.
+   */
+  // TODO(burdon): Cache value?
+  readonly bindings: ReadonlySignal<Bindings> = computed(() => this._reduce(this._queue.objects));
+
+  // TODO(burdon): load refs?
+  readonly blueprints: ReadonlySignal<Ref.Ref<Blueprint>[]> = computed(() => [...this.bindings.value.blueprints]);
+  readonly objects: ReadonlySignal<Ref.Ref<Type.Expando>[]> = computed(() => [...this.bindings.value.objects]);
+
+  /**
+   * Asynchronous query of all bindings.
+   */
+  async query(): Promise<Bindings> {
+    const queueItems = await this._queue.queryObjects();
+    return this._reduce(queueItems);
+  }
+
+  // TODO(burdon): Pass in Blueprint obj (from registry?) and create reference.
+  async bind(props: BindingProps): Promise<void> {
+    if (!props.blueprints?.length && !props.objects?.length) {
+      return;
+    }
+
+    await this._queue.append([
+      Obj.make(ContextBinding, {
+        blueprints: {
+          added: props.blueprints ?? [],
+          removed: [],
+        },
+        objects: {
+          added: props.objects ?? [],
+          removed: [],
+        },
+      }),
+    ]);
+  }
+
+  async unbind(props: BindingProps): Promise<void> {
+    if (!props.blueprints?.length && !props.objects?.length) {
+      return;
+    }
+
+    await this._queue.append([
+      Obj.make(ContextBinding, {
+        blueprints: {
+          added: [],
+          removed: props.blueprints ?? [],
+        },
+        objects: {
+          added: [],
+          removed: props.objects ?? [],
+        },
+      }),
+    ]);
+  }
+
+  private _reduce(items: (Obj.Any | Relation.Any)[]): Bindings {
+    return pipe(
+      items,
+      Array.filter(Obj.instanceOf(ContextBinding)),
+      Array.reduce(new Bindings(), (context, item) => {
+        item.blueprints.removed.forEach((item) => context.blueprints.delete(item));
+        item.blueprints.added.forEach((item) => context.blueprints.add(item));
+        item.objects.removed.forEach((item) => context.objects.delete(item));
+        item.objects.added.forEach((item) => context.objects.add(item));
+        return context;
+      }),
+    );
+  }
+}
+
+export type BindingProps = Partial<{
+  blueprints: Ref.Ref<Blueprint>[];
+  objects: Ref.Ref<Type.Expando>[];
+}>;
+
+export class Bindings {
+  blueprints = new ComplexSet<Ref.Ref<Blueprint>>((ref) => ref.dxn.toString());
+  objects = new ComplexSet<Ref.Ref<Type.Expando>>((ref) => ref.dxn.toString());
+}

package/src/context/binding.ts

@@ -0,0 +1,31 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { Schema } from 'effect';
+
+import { Type } from '@dxos/echo';
+
+import { Blueprint } from '../blueprint';
+/**
+ * Thread message that binds or unbinds contextual objects to a conversation.
+ */
+export const ContextBinding = Schema.Struct({
+  blueprints: Schema.Struct({
+    added: Schema.Array(Type.Ref(Blueprint)),
+    removed: Schema.Array(Type.Ref(Blueprint)),
+  }),
+
+  // TODO(burdon): Type.Expando => Type.Obj (or Obj.Any?)
+  objects: Schema.Struct({
+    added: Schema.Array(Type.Ref(Type.Expando)),
+    removed: Schema.Array(Type.Ref(Type.Expando)),
+  }),
+}).pipe(
+  Type.Obj({
+    typename: 'dxos.org/type/ContextBinding',
+    version: '0.1.0',
+  }),
+);
+
+export interface ContextBinding extends Schema.Schema.Type<typeof ContextBinding> {}

package/src/context/index.ts

@@ -0,0 +1,6 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export * from './binder';
+export * from './binding';

package/src/conversation/conversation.ts

@@ -0,0 +1,103 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { Message, type ExecutableTool } from '@dxos/ai';
+import { type ArtifactDefinition } from '@dxos/artifact';
+import { Event } from '@dxos/async';
+import { Obj, Ref } from '@dxos/echo';
+import { type Queue } from '@dxos/echo-db';
+import { AiService, ToolResolverService, type ServiceContainer } from '@dxos/functions';
+import { log } from '@dxos/log';
+import { isNonNullable } from '@dxos/util';
+
+import { ContextBinder, type ContextBinding } from '../context';
+import { AISession, type SessionRunOptions } from '../session';
+
+export interface ConversationRunOptions {
+  systemPrompt?: string;
+  prompt: string;
+
+  tools?: ExecutableTool[];
+  artifacts?: ArtifactDefinition[];
+  extensions?: ToolContextExtensions;
+  generationOptions?: SessionRunOptions['generationOptions'];
+
+  /** @depreacated Should be managed by the conversation. */
+  requiredArtifactIds?: string[];
+
+  // TODO(dmaretskyi): Move into conversation.
+  artifactDiffResolver?: SessionRunOptions['artifactDiffResolver'];
+}
+
+export type ConversationOptions = {
+  serviceContainer: ServiceContainer;
+  queue: Queue<Message | ContextBinding>;
+};
+
+/**
+ * Persistent conversation state.
+ * Context + history + artifacts.
+ * Backed by a Queue.
+ */
+export class Conversation {
+  private readonly _serviceContainer: ServiceContainer;
+  private readonly _queue: Queue<Message | ContextBinding>;
+
+  /**
+   * Fired when the execution loop begins.
+   * This is called before the first message is sent.
+   */
+  public readonly onBegin = new Event<AISession>();
+
+  /**
+   * Blueprints bound to the conversation.
+   */
+  public readonly context: ContextBinder;
+
+  constructor(options: ConversationOptions) {
+    this._serviceContainer = options.serviceContainer;
+    this._queue = options.queue;
+    this.context = new ContextBinder(this._queue);
+  }
+
+  async run(options: ConversationRunOptions): Promise<Message[]> {
+    const session = new AISession({ operationModel: 'configured' });
+    this.onBegin.emit(session);
+
+    const history = await this.getHistory();
+    const context = await this.context.query();
+    const blueprints = (await Ref.Array.loadAll([...context.blueprints])).filter(isNonNullable);
+    if (blueprints.length > 1) {
+      log.warn('multiple blueprints are not yet supported');
+    }
+
+    const messages = await session.run({
+      history,
+      prompt: options.prompt,
+      systemPrompt: (options.systemPrompt ?? '') + (blueprints.at(0)?.instructions ?? ''),
+
+      // TODO(dmaretskyi): Artifacts come from the blueprint?
+      artifacts: options.artifacts ?? [],
+      tools: blueprints.at(0)?.tools ?? [],
+      executableTools: options.tools,
+      requiredArtifactIds: options.requiredArtifactIds,
+      client: this._serviceContainer.getService(AiService).client,
+      toolResolver: this._serviceContainer.getService(ToolResolverService).toolResolver,
+      extensions: {
+        serviceContainer: this._serviceContainer,
+        ...options.extensions,
+      },
+      generationOptions: options.generationOptions,
+    });
+
+    await this._queue.append(messages);
+
+    return messages;
+  }
+
+  async getHistory(): Promise<Message[]> {
+    const queueItems = await this._queue.queryObjects();
+    return queueItems.filter(Obj.instanceOf(Message));
+  }
+}

package/src/conversation/index.ts

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

package/src/extraction/extraction-llm-function/extraction-llm-function.ts

@@ -2,7 +2,7 @@
 // Copyright 2025 DXOS.org
 //
 
-import { Message } from '@dxos/ai';
+import { Message, ToolRegistry } from '@dxos/ai';
 import { Obj } from '@dxos/echo';
 import { create } from '@dxos/echo-schema';
 import { AiService, defineFunction, type FunctionDefinition } from '@dxos/functions';
@@ -45,6 +45,7 @@ export const extractionAnthropicFn: FunctionDefinition<ExtractionInput, Extracti
       artifacts: [],
       prompt: '',
       tools: [],
+      toolResolver: new ToolRegistry([]),
     });
 
     return {

package/src/index.ts

@@ -2,8 +2,11 @@
 // Copyright 2024 DXOS.org
 //
 
+export * from './blueprint';
+export * from './context';
+export * from './conversation';
 export * from './extraction';
 export * from './research';
 export * from './session';
 export * from './types';
-export * from './blueprint';
+export * from './conversation';

package/src/research/research.ts

@@ -4,7 +4,7 @@
 
 import { Schema } from 'effect';
 
-import { AgentStatusReport, ConsolePrinter } from '@dxos/ai';
+import { AgentStatusReport, ConsolePrinter, ToolRegistry } from '@dxos/ai';
 import { create } from '@dxos/echo-schema';
 import { AiService, CredentialsService, DatabaseService, defineFunction, TracingService } from '@dxos/functions';
 import { log } from '@dxos/log';
@@ -68,9 +68,10 @@ export const researchFn = defineFunction({
       client: ai.client,
       systemPrompt: PROMPT,
       artifacts: [],
-      tools: [searchTool, graphWriteTool],
+      tools: [searchTool.id, graphWriteTool.id],
       history: [],
       prompt: query,
+      toolResolver: new ToolRegistry([searchTool, graphWriteTool]),
     });
 
     return {

package/src/session/session.test.ts

@@ -5,7 +5,7 @@
 import { Schema } from 'effect';
 import { describe, test } from 'vitest';
 
-import { EdgeAiServiceClient, ConsolePrinter, createTool, ToolResult } from '@dxos/ai';
+import { EdgeAiServiceClient, ConsolePrinter, createTool, ToolResult, ToolRegistry } from '@dxos/ai';
 import { AI_SERVICE_ENDPOINT } from '@dxos/ai/testing';
 import { ArtifactId, defineArtifact } from '@dxos/artifact';
 import { Type, Obj } from '@dxos/echo';
@@ -31,7 +31,52 @@ const CalendarEventSchema = Schema.Struct({
 type CalendarEvent = Schema.Schema.Type<typeof CalendarEventSchema>;
 
 // TODO(burdon): Flaky.
-describe.skip('AISession with Ollama', () => {
+describe.runIf(process.env.DX_RUN_SLOW_TESTS === '1')('AISession with Ollama', () => {
+  test('tool', async () => {
+    const aiClient = new EdgeAiServiceClient({ endpoint: AI_SERVICE_ENDPOINT.REMOTE });
+    // const aiClient = new OllamaAiServiceClient({
+    //   overrides: { model: 'llama3.1:8b' },
+    // });
+    const session = new AISession({ operationModel: 'configured' });
+
+    const printer = new ConsolePrinter();
+    session.message.on((message) => printer.printMessage(message));
+    session.userMessage.on((message) => printer.printMessage(message));
+    session.block.on((block) => printer.printContentBlock(block));
+
+    // session.update.on((update) => {
+    //   log('update', { update });
+    // });
+
+    const calculatorTool = createTool('test', {
+      name: 'calculator',
+      description: 'Adds to numbers',
+      schema: Schema.Struct({
+        operand1: Schema.Number,
+        operand2: Schema.Number,
+      }),
+      execute: async ({ operand1, operand2 }) => {
+        return ToolResult.Success(operand1 + operand2);
+      },
+    });
+
+    // Test creating an itinerary
+    const response = await session.run({
+      client: aiClient,
+      tools: [calculatorTool.id],
+      artifacts: [],
+      requiredArtifactIds: [],
+      history: [],
+      generationOptions: {
+        model: '@anthropic/claude-3-5-haiku-20241022',
+      },
+      prompt: 'What is 10 + 20?',
+      toolResolver: new ToolRegistry([calculatorTool]),
+    });
+
+    log('result', { response });
+  });
+
   test('create calendar itinerary', { timeout: 60_000 }, async () => {
     const aiClient = new EdgeAiServiceClient({ endpoint: AI_SERVICE_ENDPOINT.REMOTE });
     // const aiClient = new OllamaAiServiceClient({
@@ -145,6 +190,7 @@ describe.skip('AISession with Ollama', () => {
         model: '@anthropic/claude-3-5-haiku-20241022',
       },
       prompt: 'create a table and map for a travel itinerary based on events in my calendar',
+      toolResolver: new ToolRegistry([]),
     });
 
     log('result', {