@dxos/assistant 0.8.4-main.5acf9ea → 0.8.4-main.5ea62a8

package/src/session/session.ts

@@ -2,44 +2,52 @@
 // Copyright 2025 DXOS.org
 //
 
-import { AiLanguageModel, AiToolkit, type AiError, type AiResponse, type AiTool } from '@effect/ai';
-import { Chunk, Context, Effect, Option, pipe, Stream, type Schema } from 'effect';
-import { Array, String } from 'effect';
+import { type AiError, AiLanguageModel, type AiTool, type AiToolkit } from '@effect/ai';
+import { Chunk, Effect, type Schema, Stream } from 'effect';
 
 import {
+  type AiInputPreprocessingError,
   AiParser,
   AiPreprocessor,
-  getToolCalls,
-  runTool,
-  ToolExecutionService,
-  ToolResolverService,
-  type AgentStatus,
-  type AiInputPreprocessingError,
   type AiToolNotFoundError,
-  type GenerationStream,
+  type ToolExecutionService,
+  type ToolResolverService,
+  callTool,
+  getToolCalls,
 } from '@dxos/ai';
-import { Event } from '@dxos/async';
 import { type Blueprint } from '@dxos/blueprints';
 import { todo } from '@dxos/debug';
 import { Obj } from '@dxos/echo';
-import { ObjectVersion } from '@dxos/echo-db';
-import { type ObjectId } from '@dxos/echo-schema';
-import { DatabaseService } from '@dxos/functions';
+import { TracingService } from '@dxos/functions';
 import { log } from '@dxos/log';
-import { DataType, type ContentBlock } from '@dxos/schema';
+import { DataType } from '@dxos/schema';
 
-import { AiAssistantError } from '../errors';
+import { type AiAssistantError } from '../errors';
 
-export type AiSessionOptions = {};
+import { mapAiError } from './error-handling';
+import { formatSystemPrompt, formatUserPrompt } from './format';
+import { GenerationObserver } from './observer';
+
+export type AiSessionRunError = AiError.AiError | AiInputPreprocessingError | AiToolNotFoundError | AiAssistantError;
 
-export type SessionRunOptions<Tools extends AiTool.Any> = {
+export type AiSessionRunRequirements =
+  | AiLanguageModel.AiLanguageModel
+  | ToolExecutionService
+  | ToolResolverService
+  | TracingService;
+
+export type AiSessionRunParams<Tools extends AiTool.Any> = {
   prompt: string;
-  history: DataType.Message[];
-  systemPrompt?: string;
-  toolkit?: AiToolkit.AiToolkit<Tools>;
+  system?: string;
+  history?: DataType.Message[];
+  objects?: Obj.Any[];
   blueprints?: Blueprint.Blueprint[];
+  toolkit?: AiToolkit.ToHandler<Tools>;
+  observer?: GenerationObserver;
 };
 
+export type AiSessionOptions = {};
+
 /**
  * Contains message history, tools, current context.
  * Current context means the state of the app, time of day, and other contextual information.
@@ -51,151 +59,114 @@ export type SessionRunOptions<Tools extends AiTool.Any> = {
  * Could be personal or shared.
  */
 export class AiSession {
-  // TODO(burdon): Move to conversation.
+  /** Prevents concurrent execution of session. */
   private readonly _semaphore = Effect.runSync(Effect.makeSemaphore(1));
 
-  /** Pending messages (incl. the current user request). */
-  private _pending: DataType.Message[] = [];
-
-  /** Current streaming response. */
-  private _stream: GenerationStream | undefined;
-
-  /** Prior history from queue. */
+  /** Message history from queue. */
+  // TODO(burdon): Evolve into supporting a git-like graph of messages.
   private _history: DataType.Message[] = [];
 
-  /**
-   * New message.
-   */
-  public readonly message = new Event<DataType.Message>();
-
-  /**
-   * Complete block added to Message.
-   */
-  public readonly block = new Event<ContentBlock.Any>();
-
-  /**
-   * Update partial block (while streaming).
-   */
-  public readonly update = new Event<ContentBlock.Any>();
-
-  /**
-   * Unparsed events from the underlying generation stream.
-   */
-  public readonly streamEvent = new Event<AiResponse.Part>();
-
-  /**
-   * User prompt or tool result.
-   */
-  public readonly userMessage = new Event<DataType.Message>();
-
-  /**
-   * Agent self-reporting its status.
-   * Triggered by the model.
-   */
-  public readonly statusReport = new Event<AgentStatus>();
-
-  /**
-   * Emits when the session is done.
-   */
-  public readonly done = new Event<void>();
+  /** Pending messages for this session (incl. the current prompt). */
+  private _pending: DataType.Message[] = [];
 
   constructor(private readonly _options: AiSessionOptions = {}) {}
 
-  /**
-   * Runs the AI model loop interacting with tools and artifacts.
-   * @param options - The session options.
-   * @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>(
-    options: SessionRunOptions<Tools>,
-  ): Effect.Effect<
-    DataType.Message[],
-    AiAssistantError | AiInputPreprocessingError | AiToolNotFoundError | AiError.AiError,
-    AiLanguageModel.AiLanguageModel | ToolResolverService | ToolExecutionService | AiTool.ToHandler<Tools>
-  > =>
+  run = <Tools extends AiTool.Any>({
+    prompt,
+    system: systemTemplate,
+    history = [],
+    objects = [],
+    blueprints = [],
+    toolkit,
+    observer = GenerationObserver.noop(),
+  }: AiSessionRunParams<Tools>): Effect.Effect<DataType.Message[], AiSessionRunError, AiSessionRunRequirements> =>
     Effect.gen(this, function* () {
-      this._history = [...options.history];
+      this._history = [...history];
+      this._pending = [];
+      const pending = this._pending;
+
+      const submitMessage = Effect.fnUntraced(function* (message: DataType.Message) {
+        pending.push(message);
+        yield* observer.onMessage(message);
+        yield* TracingService.emitConverationMessage(message);
+        return message;
+      });
 
-      const promptMessages = yield* this._formatUserPrompt(options.prompt, options.history);
-      this._pending = [promptMessages];
-      this.userMessage.emit(promptMessages);
+      // Submit the prompt.
+      // TODO(burdon): Remove if cancelled?
+      const promptMessage = yield* submitMessage(yield* formatUserPrompt({ prompt, history }));
 
-      // Potential tool use loop.
+      // Generate system and prompt messages.
+      const system = yield* formatSystemPrompt({ system: systemTemplate, blueprints, objects });
+
+      // Tool call loop.
       do {
-        log('request', {
+        log.info('request', {
+          prompt: promptMessage,
+          system: { snippet: createSnippet(system), length: system.length },
           pending: this._pending.length,
           history: this._history.length,
-          tools: (Object.values(options.toolkit?.tools ?? {}) as AiTool.Any[]).map((tool: AiTool.Any) => tool.name),
+          objects: objects?.length ?? 0,
         });
 
         const prompt = yield* AiPreprocessor.preprocessAiInput([...this._history, ...this._pending]);
 
-        const blueprints = options.blueprints ?? [];
-
-        // Build system prompt from blueprint templates.
-        // TODO(dmaretskyi): Loading BP from the Database should be done at the higher level. We need a type for the resolved blueprint.
-        const systemPrompt = yield* pipe(
-          blueprints,
-          Effect.forEach((blueprint) => Effect.succeed(blueprint.instructions)),
-          Effect.flatMap(Effect.forEach((template) => DatabaseService.loadRef(template.source))),
-          Effect.map(Array.map((template) => `\n\n<blueprint>${template.content}</blueprint>`)),
-          Effect.map(Array.reduce(options.systemPrompt ?? '', String.concat)),
-        );
-
-        // Build a combined toolkit from the blueprint tools and the provided toolkit.
-        const blueprintToolkit = yield* ToolResolverService.resolveToolkit(blueprints.flatMap((bp) => bp.tools));
-        const blueprintToolkitHandler: Context.Context<AiTool.ToHandler<AiTool.Any>> =
-          yield* blueprintToolkit.toContext(yield* ToolExecutionService.handlersFor(blueprintToolkit));
-        const toolkit = options.toolkit != null ? AiToolkit.merge(options.toolkit, blueprintToolkit) : blueprintToolkit;
-        const toolkitWithBlueprintHandlers = yield* toolkit.pipe(
-          Effect.provide(blueprintToolkitHandler) as any,
-        ) as Effect.Effect<AiToolkit.ToHandler<any>, never, AiTool.ToHandler<Tools>>;
-
-        log.info('run', {
-          systemPrompt: [systemPrompt.slice(0, 32), '...', systemPrompt.slice(-32), systemPrompt.length].join(' '),
-          tools: Object.keys(blueprintToolkit.tools),
-        });
-
+        // Execute the stream request.
         const blocks = yield* AiLanguageModel.streamText({
           prompt,
-          system: systemPrompt,
-          toolkit: toolkitWithBlueprintHandlers,
+          system,
+          toolkit,
           disableToolCallResolution: true,
         }).pipe(
-          AiParser.parseGptStream({
-            onBlock: (block) =>
-              Effect.gen(this, function* () {
-                if (block.pending) {
-                  this.update.emit(block);
-                } else {
-                  this.block.emit(block);
-                }
-              }),
-            onPart: (part) =>
-              Effect.gen(this, function* () {
-                this.streamEvent.emit(part);
-              }),
+          Stream.catchTag(
+            'AiError',
+            Effect.fnUntraced(function* (err) {
+              return yield* Effect.fail(yield* mapAiError(err));
+            }),
+          ),
+          AiParser.parseResponse({
+            onBegin: () => observer.onBegin(),
+            onBlock: (block) => observer.onBlock(block),
+            onPart: (part) => observer.onPart(part),
+            onEnd: (summary) => observer.onEnd(summary),
           }),
           Stream.runCollect,
           Effect.map(Chunk.toArray),
         );
 
-        const response = Obj.make(DataType.Message, {
-          created: new Date().toISOString(),
-          sender: { role: 'assistant' },
-          blocks,
-        });
-        this._pending.push(response);
-        this.message.emit(response);
+        // Create the response message.
+        const response = yield* submitMessage(
+          Obj.make(DataType.Message, {
+            created: new Date().toISOString(),
+            sender: { role: 'assistant' },
+            blocks,
+          }),
+        );
 
+        // Parse the response for tool calls.
         const toolCalls = getToolCalls(response);
         if (toolCalls.length === 0) {
           break;
+        } else if (!toolkit) {
+          throw new Error('No toolkit provided'); // TODO(burdon): Throw user error?
         }
 
-        const toolResults = yield* runTools(toolCalls, toolkitWithBlueprintHandlers as any);
-        this._pending.push(
+        // Execute the tool calls.
+        // TODO(burdon): Retry errors? Write result when each completes individually?
+        const toolResults = yield* Effect.forEach(toolCalls, (toolCall) => {
+          return callTool(toolkit, toolCall).pipe(
+            Effect.provide(
+              TracingService.layerSubframe((context) => ({
+                ...context,
+                parentMessage: response.id,
+                toolCallId: toolCall.toolCallId,
+              })),
+            ),
+          );
+        });
+
+        // Add to queue and continue loop.
+        yield* submitMessage(
           Obj.make(DataType.Message, {
             created: new Date().toISOString(),
             sender: { role: 'user' },
@@ -204,12 +175,17 @@ export class AiSession {
         );
       } while (true);
 
+      log('done', { pending: this._pending.length });
       return this._pending;
     }).pipe(this._semaphore.withPermits(1), Effect.withSpan('AiSession.run'));
 
+  /**
+   * @deprecated
+   */
+  // TODO(burdon): Implement or remove.
   async runStructured<S extends Schema.Schema.AnyNoContext>(
-    schema: S,
-    options: SessionRunOptions<AiTool.Any>,
+    _schema: S,
+    _options: AiSessionRunParams<AiTool.Any>,
   ): Promise<Schema.Schema.Type<S>> {
     return todo();
     // const parser = structuredOutputParser(schema);
@@ -219,118 +195,7 @@ export class AiSession {
     // });
     // return parser.getResult(result);
   }
-
-  private _formatUserPrompt = (prompt: string, history: DataType.Message[]) =>
-    Effect.gen(function* () {
-      const prelude: ContentBlock.Any[] = [];
-
-      // TODO(dmaretskyi): Evaluate other approaches as `serviceOption` isn't represented in the type system.
-      const artifactDiffResolver = yield* Effect.serviceOption(ArtifactDiffResolver);
-      if (Option.isSome(artifactDiffResolver)) {
-        const versions = gatherObjectVersions(history);
-
-        const artifactDiff = yield* Effect.tryPromise({
-          try: () =>
-            artifactDiffResolver.value.resolve(
-              [...versions.entries()].map(([id, version]) => ({ id, lastVersion: version })),
-            ),
-          catch: AiAssistantError.wrap('Artifact diff resolution error'),
-        });
-
-        log.info('vision', {
-          artifactDiff,
-          versions,
-        });
-
-        for (const [id, { version }] of [...artifactDiff.entries()]) {
-          if (ObjectVersion.equals(version, versions.get(id)!)) {
-            artifactDiff.delete(id);
-            continue;
-          }
-
-          prelude.push({ _tag: 'anchor', objectId: id, version });
-        }
-        if (artifactDiff.size > 0) {
-          prelude.push(createArtifactUpdateBlock(artifactDiff));
-        }
-      }
-
-      return Obj.make(DataType.Message, {
-        created: new Date().toISOString(),
-        sender: { role: 'user' },
-        blocks: [...prelude, { _tag: 'text', text: prompt }],
-      });
-    });
-
-  abort(): void {
-    this._stream?.abort();
-  }
-}
-
-const gatherObjectVersions = (messages: DataType.Message[]): Map<ObjectId, ObjectVersion> => {
-  const artifactIds = new Map<ObjectId, ObjectVersion>();
-  for (const message of messages) {
-    for (const block of message.blocks) {
-      if (block._tag === 'anchor') {
-        artifactIds.set(block.objectId, block.version as ObjectVersion);
-      }
-    }
-  }
-
-  return artifactIds;
-};
-
-const createArtifactUpdateBlock = (
-  artifactDiff: Map<ObjectId, { version: ObjectVersion; diff?: string }>,
-): ContentBlock.Any => {
-  return {
-    _tag: 'text',
-    // TODO(dmaretskyi): Does this need to be a special content-block?
-    disposition: 'artifact-update',
-    text: `
-      The following artifacts have been updated since the last message:
-      ${[...artifactDiff.entries()]
-        .map(([id, { diff }]) => `<changed-artifact id="${id}">${diff ? `\n${diff}` : ''}</changed-artifact>`)
-        .join('\n')}
-    `,
-  };
-};
-
-/**
- * Resolves artifact ids to their versions.
- * Used to give the model a sense of the changes to the artifacts made by users during the conversation.
- * The artifacts versions are pinned in the history, and whenever the artifact changes in-between assistant's steps,
- * a diff is inserted into the conversation.
- *
- * Can be optionally provided to the session run call.
- */
-// TODO(dmaretskyi): Convert to Context.Reference
-export class ArtifactDiffResolver extends Context.Tag('@dxos/assistant/ArtifactDiffResolver')<
-  ArtifactDiffResolver,
-  ArtifactDiffResolver.Service
->() {}
-
-export namespace ArtifactDiffResolver {
-  export type Service = {
-    resolve: (artifacts: { id: ObjectId; lastVersion: ObjectVersion }[]) => Promise<
-      Map<
-        ObjectId,
-        {
-          version: ObjectVersion;
-          diff?: string;
-        }
-      >
-    >;
-  };
 }
 
-const runTools: <Tools extends AiTool.Any>(
-  toolCalls: ContentBlock.ToolCall[],
-  toolkit: AiToolkit.AiToolkit<Tools>,
-) => Effect.Effect<ContentBlock.ToolResult[], AiError.AiError, AiTool.ToHandler<Tools>> = Effect.fn('runTools')(
-  function* (toolCalls, toolkit) {
-    const toolkitWithHandlers = Effect.isEffect(toolkit) ? yield* toolkit : toolkit;
-
-    return yield* Effect.forEach(toolCalls, (toolCall) => runTool(toolkitWithHandlers, toolCall));
-  },
-);
+const createSnippet = (text: string, len = 32) =>
+  text.length <= len * 2 ? text : [text.slice(0, len), '...', text.slice(-len)].join('');

package/src/session/toolkit.ts

@@ -0,0 +1,42 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type AiTool, AiToolkit } from '@effect/ai';
+import { type Context, Effect } from 'effect';
+
+import { ToolExecutionService, type ToolId, ToolResolverService } from '@dxos/ai';
+import { type Blueprint } from '@dxos/blueprints';
+import { isNotFalsy } from '@dxos/util';
+
+export type ToolkitParams<Tools extends AiTool.Any> = {
+  toolkit?: AiToolkit.AiToolkit<Tools>;
+  toolIds?: ToolId[];
+  blueprints?: Blueprint.Blueprint[];
+};
+
+/**
+ * Build a combined toolkit from the blueprint tools and the provided toolkit.
+ */
+export const createToolkit = <Tools extends AiTool.Any>({
+  toolkit: toolkitParam,
+  toolIds = [],
+  blueprints = [],
+}: ToolkitParams<Tools>) =>
+  Effect.gen(function* () {
+    const blueprintToolkit = yield* ToolResolverService.resolveToolkit([
+      ...blueprints.flatMap(({ tools }) => tools),
+      ...toolIds,
+    ]);
+
+    const blueprintToolkitHandler: Context.Context<AiTool.ToHandler<AiTool.Any>> = yield* blueprintToolkit.toContext(
+      ToolExecutionService.handlersFor(blueprintToolkit),
+    );
+
+    const toolkit = AiToolkit.merge(...[toolkitParam, blueprintToolkit].filter(isNotFalsy));
+    return yield* toolkit.pipe(Effect.provide(blueprintToolkitHandler)) as Effect.Effect<
+      AiToolkit.ToHandler<any>,
+      never,
+      AiTool.ToHandler<Tools>
+    >;
+  });

package/src/session/version-pin.ts

@@ -6,7 +6,7 @@ import { Schema } from 'effect';
 
 import { type ObjectVersion } from '@dxos/echo-db';
 import { getVersion } from '@dxos/echo-db';
-import { ObjectId, type BaseEchoObject } from '@dxos/echo-schema';
+import { type AnyEchoObject, ObjectId } from '@dxos/echo-schema';
 import { type ContentBlock } from '@dxos/schema';
 
 // TODO(dmaretskyi): Extract.
@@ -15,7 +15,7 @@ const ObjectVersionSchema = Schema.Unknown as Schema.Schema<ObjectVersion>;
 const VersionPinSchema = Schema.Struct({
   // TODO(dmaretskyi): Use Ref when those support encoding.
   objectId: ObjectId,
-  // TODO(dmaretskyi): Could be opaque
+  // TODO(dmaretskyi): Could be opaque.
   version: ObjectVersionSchema,
 });
 
@@ -27,11 +27,11 @@ export interface VersionPin extends Schema.Schema.Type<typeof VersionPinSchema>
 
 export const VersionPin: typeof VersionPinSchema & {
   DISPOSITION: 'version-pin';
-  fromObject: (object: BaseEchoObject) => VersionPin;
+  fromObject: (object: AnyEchoObject) => VersionPin;
   createBlock: (pin: VersionPin) => ContentBlock.Any;
 } = class extends VersionPinSchema {
   static readonly DISPOSITION = 'version-pin';
-  static fromObject(object: BaseEchoObject): VersionPin {
+  static fromObject(object: AnyEchoObject): VersionPin {
     return VersionPin.make({
       objectId: object.id,
       version: getVersion(object),

package/src/summarization/summarization.test.ts

@@ -2,23 +2,21 @@
 // Copyright 2025 DXOS.org
 //
 
-// TODO(burdon): Fix.
+// ISSUE(burdon): defineFunction
 // @ts-nocheck
 
-import { pipe, Schema } from 'effect';
+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 { defineFunction, FunctionExecutor, ServiceContainer } from '@dxos/functions';
+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 REMOTE_AI = true;
-
 const summarizationFn = defineFunction({
   description: 'Summarize a document',
   inputSchema: Schema.Struct({
@@ -27,7 +25,7 @@ const summarizationFn = defineFunction({
   }),
   outputSchema: DataType.Text,
   handler: async ({ data: { document, transcript }, context }) => {
-    const ai = context.getService(AiService);
+    const ai = context.getService(AiService.AiService);
     const result = await new MixedStreamParser().parse(
       await ai.client.execStream({
         model: '@anthropic/claude-3-5-haiku-20241022',
@@ -92,7 +90,7 @@ const refinementFn = defineFunction({
     summary: DataType.Text,
   }),
   handler: async ({ data: { summaries }, context }) => {
-    const ai = context.getService(AiService);
+    const ai = context.getService(AiService.AiService);
     const result = await new MixedStreamParser().parse(
       await ai.client.execStream({
         model: '@anthropic/claude-3-5-haiku-20241022',

package/src/templates/format.tpl

@@ -0,0 +1,59 @@
+{{! System Core }}
+
+## Input Formats
+
+### Blueprints
+
+You may be provided with Blueprint definitions that include specific instructions and tools for a given set of tasks.
+Blue print instructions will be enclosed in a <blueprint> tag.
+
+### Context objects
+
+You may be provided with references to objects that are relevant to the current prompt.
+Objects will be in the form of a <object> tag with a <dxn> element that is the unique key of the object required by many tools.
+The <typename> element is the type of the object.
+
+<object>
+  <dxn>object-id</dxn>
+  <typename>example.com/type/TypeName</typename>
+</object>
+
+## Response Formats
+
+It is very important to respond in the correct format.
+You response must be valid Markdown.
+In some cases you should respond with well-formed XML tags along with the content.
+
+{{#if cot}}
+Before responding, explain your reasoning and include your detailed chain-of-thought enclosed in a <cot> tag.
+The <cot> tag should be the first thing in your response.
+{{/if}}
+
+## Block references
+
+You can reply with a block reference for objects if you have the DXN. For example:
+
+<object>
+  <dxn>dxn:queue:data:B6INSIBY3CBEF4M5VZRYBCMAHQMPYK5AJ:01K24XMVHSZHS97SG1VTVQDM5Z:01K24XPK464FSCKVQJAB2H662M</dxn>
+</object>
+<object>
+  <dxn>dxn:echo:@:01K24XPK464FSCKVQJAB2H662M</dxn>
+</object>
+
+### Suggestions
+
+Each suggestion must in the form of a proposed action enclosed in a <suggest> tag.
+Example: <suggest>Show on a map</suggest>
+
+### Multiple choice questions
+
+You may ask multiple choice questions by wrapping consise options inside <option> tags inside a well formed <select> tag.
+Example: <select><option>Yes</option><option>No</option></select>
+
+## Toolkit
+
+If the user asks for a list of tools, then just emit a single self-closing <toolkit/> tag instead of listing the tools.
+
+## Context
+
+The current date and time is {{DATETIME}}.

package/src/templates/index.ts

@@ -2,4 +2,4 @@
 // Copyright 2025 DXOS.org
 //
 
-export * from './prompt';
+export * from './system';

package/src/templates/system.tpl

@@ -0,0 +1,50 @@
+{{! 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 instructions 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.
+- After creating an artifact use a tool to add it to the chat context.
+
+## Context
+
+Today is {{DATETIME}}.