@dxos/blueprints 0.8.4-main.28f8d3d

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@dxos/blueprints",
+  "version": "0.8.4-main.28f8d3d",
+  "description": "Blueprint definitions.",
+  "homepage": "https://dxos.org",
+  "bugs": "https://github.com/dxos/dxos/issues",
+  "license": "MIT",
+  "author": "DXOS.org",
+  "type": "module",
+  "exports": {
+    ".": {
+      "source": "./src/index.ts",
+      "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.7",
+    "handlebars": "4.7.8",
+    "lodash.defaultsdeep": "^4.6.1",
+    "@dxos/ai": "0.8.4-main.28f8d3d",
+    "@dxos/echo": "0.8.4-main.28f8d3d",
+    "@dxos/invariant": "0.8.4-main.28f8d3d",
+    "@dxos/keys": "0.8.4-main.28f8d3d",
+    "@dxos/schema": "0.8.4-main.28f8d3d",
+    "@dxos/echo-schema": "0.8.4-main.28f8d3d",
+    "@dxos/util": "0.8.4-main.28f8d3d",
+    "@dxos/log": "0.8.4-main.28f8d3d"
+  },
+  "devDependencies": {
+    "@types/lodash.defaultsdeep": "^4.6.6"
+  },
+  "peerDependencies": {
+    "effect": "^3.13.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/blueprint/blueprint.ts

@@ -0,0 +1,76 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { Schema } from 'effect';
+
+import { ToolId } from '@dxos/ai';
+import { Obj, 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: 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> {}
+
+/**
+ * Create a new Blueprint.
+ */
+export const make = ({ tools = [], ...props }: Pick<Blueprint, 'key' | 'name' | 'instructions'> & Partial<Blueprint>) =>
+  Obj.make(Blueprint, { tools, ...props });

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,36 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { log } from '@dxos/log';
+
+import { type Blueprint } from './blueprint';
+
+/**
+ * Blueprint registry.
+ */
+export class Registry {
+  private readonly _blueprints: Blueprint[] = [];
+
+  constructor(blueprints: Blueprint[]) {
+    const seen = new Set<string>();
+    blueprints.forEach((blueprint) => {
+      if (seen.has(blueprint.key)) {
+        log.warn('duplicate blueprint', { key: blueprint.key });
+      } else {
+        seen.add(blueprint.key);
+        this._blueprints.push(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,6 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+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 { process } 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 = process(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,21 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import handlebars from 'handlebars';
+import defaultsDeep from 'lodash.defaultsdeep';
+
+import { invariant } from '@dxos/invariant';
+
+/**
+ * Process Handlebars template.
+ */
+export const process = <Options extends {}>(source: string, options: Options = {} as Options): string => {
+  invariant(source);
+  let section = 0;
+  handlebars.registerHelper('section', () => String(++section));
+  const template = handlebars.compile(source.trim());
+  return template(defaultsDeep({}, options, { suggestions: true }))
+    .trim()
+    .replace(/(\n\s*){3,}/g, '\n\n');
+};

package/src/template/template.ts

@@ -0,0 +1,53 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { Schema } from 'effect';
+
+import { Ref, Type } from '@dxos/echo';
+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({
+  source: Type.Ref(DataType.Text).annotations({ description: 'Handlebars template source' }),
+  inputs: Schema.optional(Schema.mutable(Schema.Array(Input))),
+}).pipe(Schema.mutable);
+
+export interface Template extends Schema.Schema.Type<typeof Template> {}
+
+export const make = ({ source, inputs = [] }: { source: string; inputs?: Input[] }): Template => ({
+  source: Ref.make(DataType.makeText(source)),
+  inputs,
+});

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;
+}