@dxos/blueprints 0.8.4-main.3f58842

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@dxos/blueprints",
+  "version": "0.8.4-main.3f58842",
+  "description": "Blueprint definitions.",
+  "homepage": "https://dxos.org",
+  "bugs": "https://github.com/dxos/dxos/issues",
+  "license": "MIT",
+  "author": "DXOS.org",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/types/src/index.d.ts",
+      "browser": "./dist/lib/browser/index.mjs",
+      "node": "./dist/lib/node-esm/index.mjs"
+    }
+  },
+  "types": "dist/types/src/index.d.ts",
+  "files": [
+    "dist",
+    "src"
+  ],
+  "dependencies": {
+    "effect": "3.17.0",
+    "handlebars": "4.7.8",
+    "lodash.defaultsdeep": "^4.6.1",
+    "@dxos/ai": "0.8.4-main.3f58842",
+    "@dxos/echo": "0.8.4-main.3f58842",
+    "@dxos/keys": "0.8.4-main.3f58842",
+    "@dxos/echo-schema": "0.8.4-main.3f58842",
+    "@dxos/log": "0.8.4-main.3f58842",
+    "@dxos/schema": "0.8.4-main.3f58842",
+    "@dxos/invariant": "0.8.4-main.3f58842",
+    "@dxos/util": "0.8.4-main.3f58842"
+  },
+  "devDependencies": {
+    "@types/lodash.defaultsdeep": "^4.6.6"
+  },
+  "peerDependencies": {
+    "effect": "^3.13.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/artifacts.ts

@@ -0,0 +1,60 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type Schema } from 'effect';
+
+import { type ExecutableTool } from '@dxos/ai';
+import { type SpaceId } from '@dxos/keys';
+
+/**
+ * @deprecated
+ */
+// TODO(burdon): Replace with Ref.
+export type AssociatedArtifact = {
+  spaceId: SpaceId;
+  typename: string;
+  id: string;
+};
+
+/**
+ * Static artifact definition.
+ * @deprecated
+ */
+// TODO(burdon): Convert to effect schema.
+export type ArtifactDefinition = {
+  // TODO(wittjosiah): Is this actually an ObjectId or should it be a uri?
+  // TODO(burdon): Plugin id?
+  id: string;
+
+  /**
+   * Name.
+   */
+  name: string;
+
+  /**
+   * Description.
+   */
+  description?: string;
+
+  /**
+   * Instructions for how to use the artifact.
+   */
+  // TODO(burdon): Reference template object.
+  instructions: string;
+
+  /**
+   * Schema that describes the shape of data which matches the artifact.
+   */
+  schema: Schema.Schema.AnyNoContext;
+
+  /**
+   * Tools that can be used to act on data which matches the artifact.
+   */
+  tools: ExecutableTool[];
+
+  // TODO(wittjosiah): Add `component` field for rendering data which matches the artifact?
+  //  NOTE(burdon): I think that could just be provided separately by the plugin (since there might be multiple surface types).
+};
+
+export const defineArtifact = (definition: ArtifactDefinition): ArtifactDefinition => definition;

package/src/blueprint/blueprint.ts

@@ -0,0 +1,70 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { Schema } from 'effect';
+
+import { ToolId } from '@dxos/ai';
+import { Type } from '@dxos/echo';
+import { LabelAnnotation } from '@dxos/echo-schema';
+
+import { Template } from '../template';
+
+/**
+ * Blueprint schema defines the structure for AI assistant blueprints.
+ * Blueprints contain instructions, tools, and artifacts that guide the AI's behavior.
+ * Blueprints may use tools to create and read artifacts, which are managed by the assistant.
+ */
+export const Blueprint = Schema.Struct({
+  /**
+   * Global registry ID.
+   * NOTE: The `key` property refers to the original registry entry.
+   */
+  // TODO(burdon): Create Format type for DXN-like ids, such as this and schema type.
+  key: Schema.String.annotations({
+    description: 'Unique registration key for the blueprint',
+  }),
+
+  /**
+   * Human-readable name of the blueprint.
+   */
+  name: Schema.String.annotations({
+    description: 'Human-readable name of the blueprint',
+  }),
+
+  /**
+   * 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: Type.Ref(Template).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',
+  }),
+}).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',
+  }),
+
+  // TODO(burdon): Move to Type.Obj def?
+  LabelAnnotation.set(['name']),
+);
+
+/**
+ * TypeScript type for Blueprint.
+ */
+export interface Blueprint extends Schema.Schema.Type<typeof Blueprint> {}

package/src/blueprint/index.ts

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

package/src/blueprint/registry.ts

@@ -0,0 +1,22 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type Blueprint } from './blueprint';
+
+/**
+ * Blueprint registry.
+ */
+export class Registry {
+  constructor(private readonly _blueprints: Blueprint[]) {
+    this._blueprints.sort(({ name: a }, { name: b }) => a.localeCompare(b));
+  }
+
+  getByKey(key: string): Blueprint | undefined {
+    return this._blueprints.find((blueprint) => blueprint.key === key);
+  }
+
+  query(): Blueprint[] {
+    return this._blueprints;
+  }
+}

package/src/index.ts

@@ -0,0 +1,7 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export * from './artifacts';
+export * as Blueprint from './blueprint';
+export * as Template from './template';

package/src/template/index.ts

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

package/src/template/prompt.test.ts

@@ -0,0 +1,44 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { describe, test } from 'vitest';
+
+import { log } from '@dxos/log';
+import { trim } from '@dxos/util';
+
+import { createPrompt } from './prompt';
+
+const TEMPLATE = trim`
+  You are a useful assistant.
+
+  ## {{section}}. Rules
+
+  Use blueprints to create artifacts.
+
+  ## {{section}}. Blueprints
+
+  {{#each blueprints}}
+  - {{this}}
+  {{/each}}
+`;
+
+const BLUEPRINTS = [
+  // prettier-ignore
+  'Create a map.',
+  'Create a kanban.',
+  'Create a spreadsheet.',
+  'Create a task list.',
+];
+
+describe('prompt', () => {
+  test('should process template variables correctly', ({ expect }) => {
+    const prompt = createPrompt(TEMPLATE, {
+      blueprints: BLUEPRINTS,
+      suggestions: true,
+    });
+    log(prompt);
+    expect(prompt).to.include('## 2. Blueprints');
+    expect(prompt).to.include(BLUEPRINTS[0]);
+  });
+});

package/src/template/prompt.ts

@@ -0,0 +1,19 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import handlebars from 'handlebars';
+import defaultsDeep from 'lodash.defaultsdeep';
+
+import { invariant } from '@dxos/invariant';
+
+/**
+ * Process Handlebars template.
+ */
+export const createPrompt = <Options extends {}>(source: string, options: Options = {} as Options): string => {
+  invariant(source);
+  let section = 0;
+  handlebars.registerHelper('section', () => String(++section));
+  const template = handlebars.compile(source);
+  return template(defaultsDeep({}, options, { suggestions: true })).trim();
+};

package/src/template/template.ts

@@ -0,0 +1,66 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { Schema } from 'effect';
+
+import { Obj, Ref, Type } from '@dxos/echo';
+import { LabelAnnotation } from '@dxos/echo-schema';
+import { DataType } from '@dxos/schema';
+
+/**
+ * Template input kind determines how template variables are resolved.
+ */
+export const InputKind = Schema.Literal(
+  'value', // Literal value.
+  'pass-through',
+  'retriever',
+  'function',
+  'query',
+  'resolver',
+  'context',
+  'schema',
+);
+
+export type InputKind = Schema.Schema.Type<typeof InputKind>;
+
+/**
+ * Template input variable.
+ * E.g., {{foo}}
+ */
+export const Input = Schema.mutable(
+  Schema.Struct({
+    name: Schema.String,
+    kind: Schema.optional(InputKind),
+    default: Schema.optional(Schema.Any),
+  }),
+);
+
+export type Input = Schema.Schema.Type<typeof Input>;
+
+/**
+ * Template type.
+ */
+export const Template = Schema.Struct({
+  name: Schema.optional(Schema.String),
+  source: Type.Ref(DataType.Text).annotations({ description: 'Handlebars template source' }),
+  inputs: Schema.optional(Schema.mutable(Schema.Array(Input))),
+}).pipe(
+  Type.Obj({
+    typename: 'dxos.org/type/Template',
+    version: '0.1.0',
+  }),
+  LabelAnnotation.set(['name']),
+);
+
+export interface Template extends Schema.Schema.Type<typeof Template> {}
+
+/**
+ * Creates a template.
+ */
+export const make = ({ source = '', ...props }: Partial<Omit<Template, 'source'> & { source: string }>) => {
+  return Obj.make(Template, {
+    source: Ref.make(Obj.make(DataType.Text, { content: source })),
+    ...props,
+  });
+};

package/src/vite-env.d.ts

@@ -0,0 +1,20 @@
+/// <reference types="vite/client" />
+
+//
+// Copyright 2025 DXOS.org
+//
+
+declare module '*.txt?raw' {
+  const content: string;
+  export default content;
+}
+
+declare module '*.md?raw' {
+  const content: string;
+  export default content;
+}
+
+declare module '*?raw' {
+  const content: string;
+  export default content;
+}