@dxos/assistant 0.8.4-main.fd6878d → 0.8.4-staging.60fe92afc8

package/src/session/session.ts

@@ -1,279 +0,0 @@
-//
-// Copyright 2025 DXOS.org
-//
-
-import { type AiError, AiLanguageModel, type AiResponse, type AiTool, AiToolkit } from '@effect/ai';
-import { Chunk, type Context, Effect, Function, Option, Queue, type Schema, Stream } from 'effect';
-
-import {
-  type AiInputPreprocessingError,
-  AiParser,
-  AiPreprocessor,
-  type AiToolNotFoundError,
-  type ConsolePrinter,
-  ToolExecutionService,
-  ToolResolverService,
-  callTools,
-  getToolCalls,
-} from '@dxos/ai';
-import { type Blueprint } from '@dxos/blueprints';
-import { todo } from '@dxos/debug';
-import { Obj } from '@dxos/echo';
-import { log } from '@dxos/log';
-import { type ContentBlock, DataType } from '@dxos/schema';
-import { isNotFalsy } from '@dxos/util';
-
-import { type AiAssistantError } from '../errors';
-
-import { formatSystemPrompt, formatUserPrompt } from './format';
-
-export type AiSessionOptions = {};
-
-/**
- * Live observer of the generation process.
- */
-export interface GenerationObserver {
-  /**
-   * Unparsed content block parts from the model.
-   */
-  onPart: (part: AiResponse.Part) => Effect.Effect<void>;
-
-  /**
-   * Parsed content blocks from the model.
-   * NOTE: Use block.pending to determine if the block was completed.
-   * For each block this will be called 0..n times with a pending block and then once with the final state of the block.
-   *
-   * Example:
-   *  1. { pending: true, text: "Hello"}
-   *  2. { pending: true, text: "Hello, I am a"}
-   *  3. { pending: false, text: "Hello, I am a helpful assistant!"}
-   */
-  onBlock: (block: ContentBlock.Any) => Effect.Effect<void>;
-
-  /**
-   * Complete messages fired during the session, both from the model and from the user.
-   * This message will contain all message blocks emitted through the `onBlock` callback.
-   */
-  onMessage: (message: DataType.Message) => Effect.Effect<void>;
-}
-
-export const GenerationObserver = Object.freeze({
-  make: ({
-    onPart = Function.constant(Effect.void),
-    onBlock = Function.constant(Effect.void),
-    onMessage = Function.constant(Effect.void),
-  }: Partial<GenerationObserver> = {}): GenerationObserver => ({
-    onPart,
-    onBlock,
-    onMessage,
-  }),
-
-  noop: () => GenerationObserver.make(),
-
-  /**
-   * Debug printer to be used in unit-tests and browser devtools.
-   */
-  fromPrinter: (printer: ConsolePrinter) =>
-    GenerationObserver.make({
-      onBlock: (block) =>
-        Effect.sync(() => {
-          if (block.pending) {
-            return; // Only prints full blocks (better for unit-tests and browser devtools).
-          }
-          printer.printContentBlock(block);
-        }),
-      onMessage: (message) =>
-        Effect.sync(() => {
-          if (message.sender.role === 'assistant') {
-            return; // Skip assistant messages since they are printed in the `onBlock` callback.
-          }
-          printer.printMessage(message);
-        }),
-    }),
-});
-
-export type SessionRunParams<Tools extends AiTool.Any> = {
-  prompt: string;
-  system?: string;
-  history?: DataType.Message[];
-  objects?: Obj.Any[]; // TODO(burdon): Meta only (typename and id -- write to binder).
-  blueprints?: Blueprint.Blueprint[];
-  toolkit?: AiToolkit.AiToolkit<Tools>;
-  observer?: GenerationObserver;
-};
-
-/**
- * Contains message history, tools, current context.
- * Current context means the state of the app, time of day, and other contextual information.
- * It makes requests to the model, its a state machine.
- * It keeps track of the current goal.
- * It manages the context window.
- * Tracks the success criteria of reaching the goal, exposing metrics (stretch).
- * Could be run locally in the app or remotely.
- * Could be personal or shared.
- */
-export class AiSession {
-  /** Complete messages fired during the session, both from the model and from the user. */
-  public readonly messageQueue = Effect.runSync(Queue.unbounded<DataType.Message>());
-
-  // TODO(dmaretskyi): Remove the queues and convert everything to observer.
-
-  /**
-   * Blocks streaming from the model during the session.
-   * @deprecated Use `observer.onBlock` instead.
-   */
-  public readonly blockQueue = Effect.runSync(Queue.unbounded<Option.Option<ContentBlock.Any>>());
-
-  /** Unparsed events from the underlying generation stream. */
-  public readonly eventQueue = Effect.runSync(Queue.unbounded<AiResponse.Part>());
-
-  /** Prevents concurrent execution of session. */
-  private readonly _semaphore = Effect.runSync(Effect.makeSemaphore(1));
-
-  /** Pending messages (incl. the current user request). */
-  private _pending: DataType.Message[] = [];
-
-  /** Prior history from queue. */
-  private _history: DataType.Message[] = [];
-
-  constructor(private readonly _options: AiSessionOptions = {}) {}
-
-  /**
-   * Runs the AI model loop interacting with tools and artifacts.
-   * @returns The messages generated by the session, including the user's prompt.
-   */
-  // TODO(dmaretskyi): Toolkit context doesn't get added to the effect type.
-  run = <Tools extends AiTool.Any>(
-    params: SessionRunParams<Tools>,
-  ): Effect.Effect<
-    DataType.Message[],
-    AiAssistantError | AiInputPreprocessingError | AiToolNotFoundError | AiError.AiError,
-    AiLanguageModel.AiLanguageModel | ToolResolverService | ToolExecutionService | AiTool.ToHandler<Tools>
-  > =>
-    Effect.gen(this, function* () {
-      const observer = params.observer ?? GenerationObserver.noop();
-
-      // Create toolkit.
-      const toolkit: AiToolkit.ToHandler<Tools> = yield* createToolkit(params);
-
-      // Generate system prompt.
-      // TODO(budon): Dynamically resolve template variables.
-      const system = yield* formatSystemPrompt(params);
-      console.log(system);
-
-      // Generate user prompt.
-      const promptMessages = yield* formatUserPrompt(params);
-      yield* this.messageQueue.offer(promptMessages);
-      yield* observer.onMessage(promptMessages);
-
-      this._history = [...(params.history ?? [])];
-      this._pending = [promptMessages];
-
-      // Potential tool-use loop.
-      do {
-        log.info('request', {
-          prompt: promptMessages,
-          system: { snippet: [system.slice(0, 32), '...', system.slice(-32)].join(''), length: system.length },
-          pending: this._pending.length,
-          history: this._history.length,
-          objects: params.objects?.length ?? 0,
-          blueprints: params.blueprints?.length ?? 0,
-          toolkit: Object.values(toolkit.tools).map((tool: AiTool.Any) => tool.name),
-        });
-
-        // Generate the prompt and make request.
-        const prompt = yield* AiPreprocessor.preprocessAiInput([...this._history, ...this._pending]);
-        const blocks = yield* AiLanguageModel.streamText({
-          prompt,
-          system,
-          toolkit,
-          // TODO(burdon): Despite this flag, the model still calls tools.
-          //  Flag is only used in generateText (not streamText); patch and submit bug.
-          //  https://github.com/Effect-TS/effect/blob/main/packages/ai/ai/src/AiLanguageModel.ts#L401
-          disableToolCallResolution: true,
-        }).pipe(
-          AiParser.parseResponse({
-            onBlock: (block) =>
-              Effect.all([this.blockQueue.offer(Option.some(block)), observer.onBlock(block)], { discard: true }),
-            onPart: (part) => Effect.all([this.eventQueue.offer(part), observer.onPart(part)], { discard: true }),
-          }),
-          Stream.runCollect,
-          Effect.map(Chunk.toArray),
-        );
-
-        // Signal to stream consumers that message blocks are complete.
-        // Allows for coordination between the block and message queues
-        //   to prevent the streaming blocks from being rendered twice when the message is produced.
-        // TODO(wittjosiah): The block queue should probably be drained at this point in the case that there is no consumer.
-        yield* this.blockQueue.offer(Option.none());
-
-        // Create response message.
-        const response = Obj.make(DataType.Message, {
-          created: new Date().toISOString(),
-          sender: { role: 'assistant' },
-          blocks,
-        });
-        this._pending.push(response);
-        yield* this.messageQueue.offer(response);
-        yield* observer.onMessage(response);
-
-        // Parse response for tool calls.
-        const toolCalls = getToolCalls(response);
-        if (toolCalls.length === 0) {
-          break;
-        }
-
-        // TODO(burdon): Report errors to user; with proposed actions.
-        const toolResults = yield* callTools(toolkit, toolCalls);
-        const toolResultsMessage = Obj.make(DataType.Message, {
-          created: new Date().toISOString(),
-          sender: { role: 'user' },
-          blocks: toolResults,
-        });
-
-        this._pending.push(toolResultsMessage);
-        yield* this.messageQueue.offer(toolResultsMessage);
-        yield* observer.onMessage(toolResultsMessage);
-      } while (true);
-
-      // Signals to stream consumers that the session has completed and no more messages are coming.
-      yield* Queue.shutdown(this.messageQueue);
-      yield* Queue.shutdown(this.blockQueue);
-      yield* Queue.shutdown(this.eventQueue);
-
-      log('done', { pending: this._pending.length });
-      return this._pending;
-    }).pipe(this._semaphore.withPermits(1), Effect.withSpan('AiSession.run'));
-
-  // TODO(burdon): Implement.
-  async runStructured<S extends Schema.Schema.AnyNoContext>(
-    _schema: S,
-    _options: SessionRunParams<AiTool.Any>,
-  ): Promise<Schema.Schema.Type<S>> {
-    return todo();
-    // const parser = structuredOutputParser(schema);
-    // const result = await this.run({
-    //   ...options,
-    //   executableTools: [...(options.executableTools ?? []), parser.tool],
-    // });
-    // return parser.getResult(result);
-  }
-}
-
-/**
- * Build a combined toolkit from the blueprint tools and the provided toolkit.
- */
-const createToolkit = <Tools extends AiTool.Any>({
-  toolkit,
-  blueprints = [],
-}: Pick<SessionRunParams<Tools>, 'toolkit' | 'blueprints'>) =>
-  Effect.gen(function* () {
-    const blueprintToolkit = yield* ToolResolverService.resolveToolkit(blueprints.flatMap(({ tools }) => tools));
-    const blueprintToolkitHandler: Context.Context<AiTool.ToHandler<AiTool.Any>> = yield* blueprintToolkit.toContext(
-      ToolExecutionService.handlersFor(blueprintToolkit),
-    );
-
-    return yield* AiToolkit.merge(...[toolkit, blueprintToolkit].filter(isNotFalsy)).pipe(
-      Effect.provide(blueprintToolkitHandler),
-    ) as Effect.Effect<AiToolkit.ToHandler<any>, never, AiTool.ToHandler<Tools>>;
-  });

package/src/session/version-pin.test.ts

@@ -1,7 +0,0 @@
-//
-// Copyright 2025 DXOS.org
-//
-
-import { describe } from 'vitest';
-
-describe('VersionPin', () => {});

package/src/summarization/summarization.test.ts

@@ -1,197 +0,0 @@
-//
-// Copyright 2025 DXOS.org
-//
-
-// ISSUE(burdon): defineFunction
-// @ts-nocheck
-
-import { Schema, pipe } from 'effect';
-import { beforeAll, describe, test } from 'vitest';
-
-import { AiService, MixedStreamParser } from '@dxos/ai';
-import { Obj } from '@dxos/echo';
-import { type EchoDatabase } from '@dxos/echo-db';
-import { EchoTestBuilder } from '@dxos/echo-db/testing';
-import { FunctionExecutor, ServiceContainer, defineFunction } from '@dxos/functions';
-import { type ContentBlock, DataType } from '@dxos/schema';
-import { createTestData } from '@dxos/schema/testing';
-import { trim } from '@dxos/util';
-
-const summarizationFn = defineFunction({
-  description: 'Summarize a document',
-  inputSchema: Schema.Struct({
-    document: Schema.optional(DataType.Text),
-    transcript: Schema.Array(DataType.Message),
-  }),
-  outputSchema: DataType.Text,
-  handler: async ({ data: { document, transcript }, context }) => {
-    const ai = context.getService(AiService.AiService);
-    const result = await new MixedStreamParser().parse(
-      await ai.client.execStream({
-        model: '@anthropic/claude-3-5-haiku-20241022',
-        // TODO(burdon): Factor out and test prompts.
-        systemPrompt: trim`
-          Your job is to summarize a meeting transcript.
-          Transcript Summarizer updates an existing summary within <summary> tags with a new transcript that is placed in <transcript> tags.
-          Transcript Summarizer updates only the relevant parts of the summary.
-          If there's no summary, create a new one.
-          Transcript Summarizer outputs only the summary texts and nothing else.
-          Transcript Summarizer keeps the original summary structure.
-          Transcript Summarizer keeps the unrelated parts of the summary untouched.
-          The Transcript Summarizer errs on the side of being too verbose.
-          The Transcript Summarizer outputs the entire update summary.
-          The summary is formatted as hierarchical markdown bullet points with no headings.
-          The hierarchical structure is deeply nested.
-          The Transcript Summarizer formats the bullets with "-" symbol as prefix and two spaces indentation.
-          The Transcript Summarizer knows that the content of transcript will be updated solely by its output.
-          The Transcript Summarizer outputs only the summary text.
-        `,
-        history: [
-          Obj.make(DataType.Message, {
-            created: new Date().toISOString(),
-            sender: { role: 'user' },
-            blocks: [
-              {
-                _tag: 'text',
-                text: trim`
-                  <transcript>
-                    ${JSON.stringify(transcript, null, 2)}
-                  </transcript>
-                `,
-              },
-              ...(document != null && document.content.length > 0
-                ? [
-                    {
-                      _tag: 'text',
-                      text: trim`
-                        <summary>
-                          ${document.content}
-                        </summary>
-                      `,
-                    } satisfies ContentBlock.Text,
-                  ]
-                : []),
-            ],
-          }),
-        ],
-      }),
-    );
-
-    return DataType.makeText(pipe(result[0]?.blocks[0], (c) => (c?._tag === 'text' ? c.text : '')));
-  },
-});
-
-const refinementFn = defineFunction({
-  description: 'Refine a summary',
-  inputSchema: Schema.Struct({
-    summaries: Schema.Array(DataType.Text),
-  }),
-  outputSchema: Schema.Struct({
-    summary: DataType.Text,
-  }),
-  handler: async ({ data: { summaries }, context }) => {
-    const ai = context.getService(AiService.AiService);
-    const result = await new MixedStreamParser().parse(
-      await ai.client.execStream({
-        model: '@anthropic/claude-3-5-haiku-20241022',
-        // TODO(burdon): Factor out and test prompts.
-        systemPrompt: trim`
-          You are a Transcript Summary Refiner.
-          Transcript Summary Refiner works on a history of evolving summaries that were generated based on the transcript.
-          The summaries are presented starting from the oldest to the newest.
-          Each iteration of the summary contains a new part of the transcript.
-          The Transcript Summary Refiner refines the summary based on the history of summaries.
-          The Transcript Summary Refiner identifies any potential data lost between the iterations and adds its back to the output.
-          The Transcript Summary Refiner updates the summary to be more structured.
-          The Transcript Summary Refiner errs on the side of being too verbose.
-          The Transcript Summary Refiner errs on keeping the original summary structure.
-          The Transcript Summary Refiner outputs the entire update summary.
-          The Transcript Summary is formatted as hierarchical markdown bullet points with no headings.
-          The hierarchical structure is deeply nested.
-          The Transcript Summary Refiner formats the bullets with "-" symbol as prefix and two spaces indentation.
-          The Transcript Summary Refiner knows that the content of transcript will be updated solely by its output.
-          The Transcript Summary Refiner outputs only the summary text.
-        `,
-        history: [
-          Obj.make(DataType.Message, {
-            created: new Date().toISOString(),
-            sender: { role: 'user' },
-            blocks: summaries.map(
-              (summary) =>
-                ({
-                  _tag: 'text',
-                  text: trim`
-                    <summary>
-                      ${summary.content}
-                    </summary>
-                  `,
-                }) satisfies ContentBlock.Text,
-            ),
-          }),
-        ],
-      }),
-    );
-    return {
-      summary: DataType.makeText(pipe(result[0]?.blocks[0], (c) => (c?._tag === 'text' ? c.text : ''))),
-    };
-  },
-});
-
-describe.skip('Summarization', () => {
-  let builder: EchoTestBuilder;
-  let db: EchoDatabase;
-  let executor: FunctionExecutor;
-
-  // TODO(burdon): Rewrite test.
-  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;
-    executor = new FunctionExecutor(
-      new ServiceContainer().setServices({
-        ai: todo(),
-        database: {
-          db,
-        },
-      }),
-    );
-  });
-
-  test('keeps transcript outline', { timeout: 1000_000 }, async () => {
-    const { transcriptMessages } = createTestData();
-
-    const summary = DataType.makeText();
-
-    const summaries = [];
-
-    for (let i = 0; i < transcriptMessages.length; i++) {
-      const blocks = transcriptMessages.slice(Math.max(0, i - 2), i + 1);
-      const result = await executor.invoke(summarizationFn, {
-        document: summary,
-        transcript: blocks,
-      });
-      summary.content = result.content;
-      summaries.push(DataType.makeText(result.content));
-
-      console.log(blocks.at(-1));
-      console.log();
-      console.log(summary.content);
-      console.log();
-
-      if (i % 3 === 0 && i > 0) {
-        const history: any = summaries.slice(-5);
-        const result = await executor.invoke(refinementFn, {
-          summaries: history,
-        });
-        summary.content = result.summary.content;
-        summaries.push(DataType.makeText(result.summary.content));
-
-        console.log('REFINED');
-        console.log();
-        console.log(summary.content);
-        console.log();
-      }
-    }
-  });
-});

package/src/templates/system.tpl

@@ -1,47 +0,0 @@
-{{! System Prompt }}
-
-You are a helpful assistant called Kai. 
-Your name is Kai and you are powered by different language models.
-You were created by DXOS and operate in Composer and on the DXOS EDGE network.
-In your initial greeting state your name and make some suggestions based on the current context objects.
-
-You are an advanced AI assistant capable of creating and managing artifacts from provided data and tools.
-Your task is to process user commands and questions and decide how best to respond.
-In general be concise and direct.
-
-Follow these guidelines carefully:
-
-Include the following steps:
-
-- Analyze the structure and type of the content in the user's message.
-- Determine if you complete the task using the available blueprint definitions?
-- If you can't complete the task using the available blueprint definitions, query the list of available blueprint definitions using the appropriate tool.
-- Identify which blueprint definitions are relevant to the user's request.
-- Evaluate the potential benefits of creating an artifact vs. normal processing for each identified element.
-- Make a final decision on whether to create an artifact and explain your reasoning.
-- Are the required blueprint definitions already available?
-- If not, select which blueprint definition(s) will be the most relevant and require them using the require_artifact_definitions tool.
-- The require'd artifact tools will be available for use after require.
-- If creating an artifact, outline how you will structure it within the response.
-- Decide if the artifact needs to be shown to the user.
-- Call the show tool to show the artifact to the user.
-- Your reasoning must include: whether to use artifacts or not, to create one or query, whether to show the artifact to the user, and how to structure the response.
-
-# Blueprints
-
-- Determine if the interaction involves an artifact. Prefer artifacts for tables, lists, spreadsheets, kanbans, games, images, and other structured data.
-- Determine if the user is explicitly talking about creating a new artifact, or wants to use an existing artifact.
-- If it is ambiguous, query for existing artifacts first and then decide.
-- If you decide to create an artifact, call the associated tool to create the artifact.
-- Artifacts are stored in the database. Tools are used to create and query artifacts.
-- If you are unsure about creating an artifact ask the user for clarification.
-
-- Artifacts are mutable objects that can change over the course of the conversation.
-- Always re-query the artifact using the tool (like query or inspect) to get the latest state of the artifact before answering the user.
-- You must never generate the id of the artifact; only recall the ids that are already in the history.
-- Artifacts are created by requiring the specific artifact using the require_artifact tool and creating it by calling the associated tool.
-
-- You can add suggested actions at the end of your response.
-- Suggested actions should be very concise and start with a verb and be phrased as a command to an agent -- not a question to the user.
-- Suggested actions must be in the form of a user instruction that you can follow.
-- Suggested actions could include actions that create artifacts.

package/src/types.ts

@@ -1,52 +0,0 @@
-//
-// Copyright 2025 DXOS.org
-//
-
-import { Schema } from 'effect';
-
-import { type ObjectId } from '@dxos/echo-schema';
-import { DXN, LOCAL_SPACE_TAG, type SpaceId } from '@dxos/keys';
-import { trim } from '@dxos/util';
-
-/**
- * @deprecated
- */
-export const createArtifactElement = (id: ObjectId) => `<artifact id=${id} />`;
-
-/**
- * A model-friendly way to reference an object.
- * Supports vairous formats that will be normalized to a DXN.
- */
-// TODO(burdon): Rename ObjectReference?
-export const ArtifactId: Schema.Schema<string> & {
-  toDXN: (reference: ArtifactId, owningSpaceId?: SpaceId) => DXN;
-} = class extends Schema.String.annotations({
-  description: trim`
-    The ID of the referenced object. Formats accepted:
-    - DXN (dxn:echo:@:XXXXX). DXNs can be prepended with an @ symbol for compatibility with in-text references.
-    - space ID, object ID tuple (spaceID:objectID)
-    - Only object ID that is assumed to be in the current space (XXXXX)
-  `,
-  examples: ['dxn:echo:@:XXXXX', '@dxn:echo:@:XXXXX', 'spaceID:objectID', 'XXXXX'],
-}) {
-  static toDXN(reference: ArtifactId, owningSpaceId?: SpaceId): DXN {
-    // Allow @dxn: prefix for compatibility with in-text references.
-    if (reference.startsWith('@dxn:')) {
-      return DXN.parse(reference.slice(1));
-    } else if (reference.startsWith('dxn:')) {
-      return DXN.parse(reference);
-    } else if (/^[A-Z0-9]+:[A-Z0-9]+$/.test(reference)) {
-      const [spaceId, objectId] = reference.split(':');
-      // This is a workaround because the current Filter API doesn't work with fully qualified Echo DXNs.
-      // We check if the space ID is the same as the owning space and then use LOCAL_SPACE_TAG for local references.
-      // TODO(dmaretskyi): Fix this in the Echo and Filter API to properly handle fully qualified DXNs.
-      return new DXN(DXN.kind.ECHO, [spaceId === owningSpaceId ? LOCAL_SPACE_TAG : spaceId, objectId]);
-    } else if (/^[A-Z0-9]+$/.test(reference)) {
-      return DXN.fromLocalObjectId(reference);
-    } else {
-      throw new Error(`Unable to parse object reference: ${reference}`);
-    }
-  }
-};
-
-export type ArtifactId = Schema.Schema.Type<typeof ArtifactId>;