@dxos/blueprints 0.8.4-main.1068cf700f

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@dxos/blueprints",
+  "version": "0.8.4-main.1068cf700f",
+  "description": "Blueprint definitions.",
+  "homepage": "https://dxos.org",
+  "bugs": "https://github.com/dxos/dxos/issues",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dxos/dxos"
+  },
+  "license": "MIT",
+  "author": "DXOS.org",
+  "type": "module",
+  "exports": {
+    ".": {
+      "source": "./src/index.ts",
+      "types": "./dist/types/src/index.d.ts",
+      "default": "./dist/lib/neutral/index.mjs"
+    }
+  },
+  "types": "dist/types/src/index.d.ts",
+  "files": [
+    "dist",
+    "src"
+  ],
+  "dependencies": {
+    "effect": "3.19.16",
+    "handlebars": "4.7.8",
+    "@dxos/ai": "0.8.4-main.1068cf700f",
+    "@dxos/functions": "0.8.4-main.1068cf700f",
+    "@dxos/keys": "0.8.4-main.1068cf700f",
+    "@dxos/invariant": "0.8.4-main.1068cf700f",
+    "@dxos/echo": "0.8.4-main.1068cf700f",
+    "@dxos/schema": "0.8.4-main.1068cf700f",
+    "@dxos/log": "0.8.4-main.1068cf700f",
+    "@dxos/util": "0.8.4-main.1068cf700f"
+  },
+  "devDependencies": {},
+  "peerDependencies": {
+    "effect": "3.19.16"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/blueprint/blueprint.ts

@@ -0,0 +1,91 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+
+import { ToolId } from '@dxos/ai';
+import { Annotation, Obj, Type } from '@dxos/echo';
+import { type FunctionDefinition } from '@dxos/functions';
+
+import * as 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.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.object({
+    // TODO(burdon): Is this a DXN? Need to create a Format type for these IDs.
+    typename: 'dxos.org/type/Blueprint',
+    version: '0.1.0',
+  }),
+  Annotation.LabelAnnotation.set(['name']),
+);
+
+/**
+ * TypeScript type for Blueprint.
+ */
+export interface Blueprint extends Schema.Schema.Type<typeof Blueprint> {}
+
+type MakeProps = Pick<Blueprint, 'key' | 'name'> & Partial<Blueprint>;
+
+/**
+ * Create a new Blueprint.
+ */
+export const make = ({ tools = [], instructions = Template.make(), ...props }: MakeProps) =>
+  Obj.make(Blueprint, {
+    tools,
+    instructions,
+    ...props,
+  });
+
+/**
+ * Util to create tool definitions for a blueprint.
+ */
+export const toolDefinitions = ({
+  tools = [],
+  functions = [],
+}: {
+  tools?: string[];
+  functions?: FunctionDefinition[];
+}) => [...functions.map((fn) => ToolId.make(fn.key)), ...tools.map((tool) => ToolId.make(tool))];

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,40 @@
+//
+// 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));
+  }
+
+  get blueprints(): Blueprint[] {
+    return this._blueprints;
+  }
+
+  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 * as Blueprint from './blueprint';
+export * as Template from './template';
+export * as Prompt from './prompt';

package/src/prompt/index.ts

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

package/src/prompt/prompt.ts

@@ -0,0 +1,79 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+
+import { Annotation, JsonSchema, Obj, type Ref, Type } from '@dxos/echo';
+
+import { Blueprint } from '../blueprint';
+import * as Template from '../template';
+
+/**
+ * Executable instructions, which may use Blueprints.
+ * May reference additional context.
+ */
+export const Prompt = Schema.Struct({
+  /**
+   * Name of the prompt.
+   */
+  name: Schema.optional(Schema.String),
+
+  /**
+   * Description of the prompt's purpose and functionality.
+   * Allows AI agents to execute prompts automatically as tools.
+   */
+  description: Schema.optional(Schema.String),
+
+  /**
+   * Input schema of the prompt.
+   */
+  input: JsonSchema.JsonSchema.pipe(Annotation.FormInputAnnotation.set(false)),
+
+  /**
+   * Output schema of the prompt.
+   */
+  output: JsonSchema.JsonSchema.pipe(Annotation.FormInputAnnotation.set(false)),
+
+  /**
+   * Natural language instructions for the prompt.
+   * These should provide concrete course of action for the AI to follow.
+   */
+  instructions: Template.Template.pipe(Annotation.FormInputAnnotation.set(false)),
+
+  /**
+   * Blueprints that the prompt may utilize.
+   */
+  blueprints: Schema.Array(Type.Ref(Blueprint)),
+
+  /**
+   * Additional context that the prompt may utilize.
+   */
+  context: Schema.Array(Schema.Any).pipe(Annotation.FormInputAnnotation.set(false)),
+}).pipe(
+  Type.object({
+    typename: 'dxos.org/type/Prompt',
+    version: '0.1.0',
+  }),
+);
+
+export interface Prompt extends Schema.Schema.Type<typeof Prompt> {}
+
+export const make = (params: {
+  name?: string;
+  description?: string;
+  input?: Schema.Schema.AnyNoContext;
+  output?: Schema.Schema.AnyNoContext;
+  instructions?: string;
+  blueprints?: Ref.Ref<Blueprint>[];
+  context?: any[];
+}): Prompt =>
+  Obj.make(Prompt, {
+    name: params.name,
+    description: params.description,
+    input: JsonSchema.toJsonSchema(params.input ?? Schema.Void),
+    output: JsonSchema.toJsonSchema(params.output ?? Schema.Void),
+    instructions: Template.make({ source: params.instructions }),
+    blueprints: params.blueprints ?? [],
+    context: params.context ?? [],
+  });

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,59 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+import * as Record from 'effect/Record';
+import handlebars from 'handlebars';
+
+import { Database } from '@dxos/echo';
+import type { ObjectNotFoundError } from '@dxos/echo/Err';
+import {
+  type FunctionDefinition,
+  FunctionInvocationService,
+  type FunctionNotFoundError,
+  type TracingService,
+} from '@dxos/functions';
+import { invariant } from '@dxos/invariant';
+import { log } from '@dxos/log';
+
+import type { Template } from '..';
+
+/**
+ * Process Handlebars template.
+ */
+export const process = <Options extends {}>(source: string, variables: Partial<Options> = {}): string => {
+  invariant(typeof source === 'string');
+  let section = 0;
+  handlebars.registerHelper('section', () => String(++section));
+  const template = handlebars.compile(source.trim());
+  const output = template(variables);
+  return output.trim().replace(/(\n\s*){3,}/g, '\n\n');
+};
+
+export const processTemplate = (
+  template: Template.Template,
+): Effect.Effect<string, ObjectNotFoundError | FunctionNotFoundError, FunctionInvocationService | TracingService> =>
+  Effect.gen(function* () {
+    const functionInvoker = yield* FunctionInvocationService;
+
+    const variables = yield* Effect.forEach(template.inputs ?? [], (input) =>
+      Effect.gen(function* () {
+        if (input.kind === 'function') {
+          const fn = (yield* functionInvoker.resolveFunction(input.function!)) as FunctionDefinition<
+            {},
+            unknown,
+            never
+          >;
+          const result = yield* functionInvoker.invokeFunction(fn, {});
+          return [input.name, result] as const;
+        } else {
+          return yield* Effect.dieMessage(`Unsupported input kind: ${input.kind}`);
+        }
+      }),
+    ).pipe(Effect.map(Record.fromEntries));
+
+    log('processTemplate', { variables });
+
+    return process((yield* Database.load(template.source)).content, variables);
+  });

package/src/template/template.ts

@@ -0,0 +1,61 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+
+import { Ref, Type } from '@dxos/echo';
+import { type ObjectId } from '@dxos/keys';
+import { Text } 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.Struct({
+  name: Schema.String,
+  kind: Schema.optional(InputKind),
+  default: Schema.optional(Schema.Any),
+
+  /**
+   * Function to call if the kind is 'function'.
+   */
+  function: Schema.optional(Schema.String),
+});
+
+export type Input = Schema.Schema.Type<typeof Input>;
+
+/**
+ * Template type.
+ */
+export const Template = Schema.Struct({
+  source: Type.Ref(Text.Text).annotations({ description: 'Handlebars template source' }),
+  inputs: Schema.optional(Schema.Array(Input)),
+});
+
+export interface Template extends Schema.Schema.Type<typeof Template> {}
+
+export const make = ({
+  source,
+  inputs = [],
+  id,
+}: { source?: string; inputs?: Input[]; id?: ObjectId } = {}): Template => ({
+  source: Ref.make(Text.make(source, id)),
+  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;
+}