@dxos/assistant-toolkit 0.8.4-main.ae835ea → 0.8.4-main.bcb3aa67d6

package/src/blueprints/project-wizard/functions/project-rules.ts

@@ -0,0 +1,76 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { Operation } from '@dxos/operation';
+import { trim } from '@dxos/util';
+
+import { ProjectRules } from './definitions';
+
+export default ProjectRules.pipe(
+  Operation.withHandler(
+    Effect.fnUntraced(function* () {
+      return trim`
+        You can ask the user for qualifying questions about the projects.
+        If projects should actively read incoming emails, query for mailboxes and add a subscription to them.
+        Use [query-blueprints] from the Blueprint Manager to query for available blueprints and their keys.
+        Use [create-project] function to create a new project.
+        After creating a project, explicitly remind the user to enable local triggers so the project can be driven autonomously.
+
+        Notable blueprints (query to get their keys):
+
+        - Database -- CRUD on objects in the ECHO database.
+        - Markdown -- Create and edit markdown documents.
+        - Websearch -- Search the web for information.
+        - Browser -- Virtual browser via playwright when simple WebSearch is not enough.
+        - Memory -- Memory to store and retrieve information.
+
+        Experimental blueprints that are discoraged:
+
+        - Research
+        - Design
+        - Project (not wizard) -- those are project internals, they are auto-added to every new project.
+
+        <example_project>
+          ## CRM from your inbox
+
+          Blueprints: database, websearch, browser
+
+          Subscribe to your inboxes.
+          Spec says that on every email we should extract People and Organizations and save them to the database, but first query the database for existing people and organizations to avoid duplicates.
+          Also run a quick research on the web to find more information about the person or organization and save it to the database.
+        </example_project>
+
+        <example_project>
+          ## Parcel tracking
+
+          Blueprints: database
+
+          Based on emails from vendors (amazon, fedex, etc.) track the status of the parcels ordered online and keep a table of orders.
+
+          Before creating a project, use the Database blueprint to create an Order schema:
+            - seller
+            - name
+            - price
+            - status (enum of: pending, shipped, waiting for pickup, delivered, cancelled, returned)
+            - tracking numbers/notes
+            - date of delivery
+            - shipping address
+        </example_project>
+
+        <example_project>
+          ## Comms assistant
+
+          Blueprints: database, markdown, inbox
+
+          Helps user maintain comms with external parites via email.
+          Ask user specifically who they want to communicate with and on what topic.
+          Project should keep a markdown document in artifacts outlining the current state of the comms.
+          Project should propose drafts to follow up on the comms. Only propose sensible drafts, do not propose drafts that are not relevant or actionable.
+        </example_project>
+      `;
+    }),
+  ),
+);

package/src/blueprints/project-wizard/index.ts

@@ -0,0 +1,6 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export { default as ProjectWizardBlueprint } from './blueprint';
+export { ProjectRules, CreateProject, ProjectWizardHandlers } from './functions';

package/src/blueprints/research/blueprint.ts

@@ -0,0 +1,61 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type AppCapabilities } from '@dxos/app-toolkit';
+import { Blueprint } from '@dxos/blueprints';
+import { Ref } from '@dxos/echo';
+import { Text } from '@dxos/schema';
+import { trim } from '@dxos/util';
+
+import { Research, DocumentCreate } from './functions';
+
+const BLUEPRINT_KEY = 'org.dxos.blueprint.research';
+
+/**
+ * Agent prompt instructions for managing hierarchical task lists.
+ */
+const instructions = trim`
+  {{! Research }}
+
+  You are an analyst that does research tasks using tools that scrape the web and create structured data.
+  Structured data extraction is an experimental feature -- only enable it if the user explicitly requests it in the prompt.
+  Prefer updating existing notes instead of creating new ones.
+
+  <structured_mode>
+    When you are done, reply with the created objects.
+    Do not print the data, instead reply with inline references to the created objects.
+    Those will be later substituted with the pills representing the created objects.
+    Print the rest of the created objects as block references after the main note.
+
+    <example>
+      Based on my research, Google was founded by @dxn:queue:data:B6INSIBY3CBEF4M5VZRYBCMAHQMPYK5AJ:01K24XMVHSZHS97SG1VTVQDM5Z:01K24XPK464FSCKVQJAB2H662M and @dxn:queue:data:B6INSIBY3CBEF4M5VZRYBCMAHQMPYK5AJ:01K24XMVHSZHS97SG1VTVQDM5Z:01K24XPK46K31DDW62PBW9H2ZQ
+
+      <object><dxn>dxn:queue:data:B6INSIBY3CBEF4M5VZRYBCMAHQMPYK5AJ:01K24XMVHSZHS97SG1VTVQDM5Z:01K24XPK464FSCKVQJAB2H662M</dxn></object>
+      <object><dxn>dxn:queue:data:B6INSIBY3CBEF4M5VZRYBCMAHQMPYK5AJ:01K24XMVHSZHS97SG1VTVQDM5Z:01K24XPK46K31DDW62PBW9H2ZQ</dxn></object>
+      <object><dxn>dxn:queue:data:B6INSIBY3CBEF4M5VZRYBCMAHQMPYK5AJ:01K24XMVHSZHS97SG1VTVQDM5Z:01K24XPK46K31DDW62PBW92333</dxn></object>
+    </example>
+  </structured_mode>
+
+  <unstructured_mode>
+    Reply normally with the text mode of the result of your research.
+  </unstructured_mode>
+`;
+
+const make = () =>
+  Blueprint.make({
+    key: BLUEPRINT_KEY,
+    name: 'Research',
+    description: 'Researches the web and creates structured data.',
+    instructions: {
+      source: Ref.make(Text.make(instructions)),
+    },
+    tools: Blueprint.toolDefinitions({ operations: [DocumentCreate, Research] }),
+  });
+
+const blueprint: AppCapabilities.BlueprintDefinition = {
+  key: BLUEPRINT_KEY,
+  make,
+};
+
+export default blueprint;

package/src/blueprints/research/functions/definitions.ts

@@ -0,0 +1,87 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+
+import { AiService } from '@dxos/ai';
+import { Database, Obj, Ref } from '@dxos/echo';
+import { FunctionInvocationService, TracingService } from '@dxos/functions';
+import { Operation } from '@dxos/operation';
+import { trim } from '@dxos/util';
+
+export const Research = Operation.make({
+  meta: {
+    key: 'org.dxos.function.research',
+    name: 'Research',
+    description: trim`
+      Search the web to research information about the given subject.
+      Inserts structured data into the research graph. 
+      Creates a research summary and returns the objects created.
+    `,
+  },
+  input: Schema.Struct({
+    query: Schema.String.annotations({
+      description: trim`
+        The search query.
+        If doing research on an object then load it first and pass it as JSON.
+      `,
+    }),
+    instructions: Schema.optional(Schema.String).annotations({
+      description: trim`
+        The instructions for the research agent. 
+      `,
+    }),
+    // TOOD(burdon): Move to context.
+    mockSearch: Schema.optional(Schema.Boolean).annotations({
+      description: 'Whether to use the mock search tool.',
+      default: false,
+    }),
+    entityExtraction: Schema.optional(Schema.Boolean).annotations({
+      description: trim`
+        Whether to extract structured entities from the research. 
+        Experimental feature only enable if user explicitly requests it.
+      `,
+      default: false,
+    }),
+  }),
+  output: Schema.Struct({
+    document: Schema.optional(Schema.String).annotations({
+      description: 'The generated research document.',
+    }),
+    objects: Schema.Array(Schema.Unknown).annotations({
+      description: 'Structured objects created during the research process.',
+    }),
+  }),
+  services: [AiService.AiService, Database.Service, TracingService, FunctionInvocationService],
+});
+
+export const DocumentCreate = Operation.make({
+  meta: {
+    key: 'org.dxos.function.research.document-create',
+    name: 'Create research document',
+    description: 'Creates a note summarizing the research.',
+  },
+  input: Schema.Struct({
+    subject: Ref.Ref(Obj.Unknown).annotations({
+      description: trim`
+        ID of the object (organization, contact, etc.) for which the research was performed. 
+      `,
+    }),
+    name: Schema.String.annotations({
+      description: 'Name of the document.',
+    }),
+    content: Schema.String.annotations({
+      description: trim`
+        Content of the note. 
+        Supports (and are prefered) references to research objects using @ syntax and <object> tags (refer to research blueprint instructions).
+      `,
+    }),
+  }),
+  output: Schema.Struct({
+    document: Schema.String.annotations({
+      description: 'DXN of the created document.',
+    }),
+  }),
+  services: [Database.Service, TracingService],
+});

package/src/blueprints/research/functions/document-create.ts

@@ -0,0 +1,50 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { Database, Obj, Relation } from '@dxos/echo';
+import { TracingService } from '@dxos/functions';
+import { log } from '@dxos/log';
+import { Operation } from '@dxos/operation';
+import { Markdown } from '@dxos/plugin-markdown/types';
+import { HasSubject } from '@dxos/types';
+
+import { DocumentCreate } from './definitions';
+
+export default DocumentCreate.pipe(
+  Operation.withHandler(
+    Effect.fnUntraced(function* ({ subject, name, content }) {
+      log.info('Creating research document', { subject, name, content });
+
+      // TODO(burdon): Auto flush before and after calling function?
+      yield* Database.flush();
+      yield* TracingService.emitStatus({ message: 'Creating research document...' });
+
+      const target = yield* Database.load(subject);
+
+      const object = yield* Database.add(
+        Markdown.make({
+          name,
+          content,
+        }),
+      );
+
+      yield* Database.add(
+        Relation.make(HasSubject.HasSubject, {
+          [Relation.Source]: object,
+          [Relation.Target]: target,
+          completedAt: new Date().toISOString(),
+        }),
+      );
+
+      yield* Database.flush();
+      log.info('Created research document', { subject, object });
+
+      return {
+        document: Obj.getDXN(object).toString(),
+      };
+    }),
+  ),
+);

package/src/blueprints/research/functions/index.ts

@@ -0,0 +1,12 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { OperationHandlerSet } from '@dxos/operation';
+
+export * from './definitions';
+
+export const ResearchHandlers = OperationHandlerSet.lazy(
+  () => import('./document-create'),
+  () => import('./research'),
+);

package/src/{functions/research/instructions-research.tpl → blueprints/research/functions/research-instructions.tpl}

@@ -6,10 +6,11 @@ The Research Agent outputs results in a structured format matching the schema pr
 The Research Agent is equipped with the ability to:
 
 - Generate precise and effective search queries 
-- Request web pages by query (through a `web_search` tool)
-- Read the full content of retrieved pages
+- Request web pages by query.
 - Synthesize accurate, clear, and structured answers using reliable information from the retrieved content
+{{#if entityExtraction}}
 - Search the local database for information using a vector index (through a `local_search` tool)
+{{/if}}
 
 The Research Agent always follows these principles:
 
@@ -19,6 +20,7 @@ The Research Agent always follows these principles:
 - Transparency: The Research Agent mentions which sources were used and explains how it arrived at conclusions.
 - Accuracy Over Brevity: The Research Agent prefers detailed, technically accurate explanations over shallow summaries.
 - The Research Agent admits uncertainty rather than misleading.
+{{#if entityExtraction}}
 - The Research Agent picks the most concrete schema types for extracted information.
 - The Research Agent fills schema fields completely with information it is confident about, and omits fields it is not confident about.
 - When outputting results, the Research Agent adds extra data that fits the schema even if not directly related to the user's question.
@@ -26,6 +28,7 @@ The Research Agent always follows these principles:
 - The Research Agent does not create objects that are already in the database.
 - The Research Agent re-uses existing object IDs as references when enriching existing objects.
 - The Research Agent ALWAYS calls the `graph_writer` at the end to save the data. This conversation will be deleted, so only the data written to the graph will be preserved.
+{{/if}}
 
 The Research Agent may be asked for:
 
@@ -41,8 +44,6 @@ The Research Agent breaks it into sub-questions (if applicable).
 
 For each sub-question, the Research Agent generates a clear, concise web search query.
 
-The Research Agent uses `web_search`(query) to retrieve information.
-
 The Research Agent extracts and synthesizes relevant answers.
 
 The Research Agent's output includes:
@@ -58,23 +59,27 @@ Here's how the Research Agent operates:
 2. The Research Agent performs a web search for each topic.
 3. The Research Agent reads and analyzes results, cross references information from multiple sources, and represents conflicting information as ranges of possible values.
 
+{{#if entityExtraction}}
 4. The Research Agent searches the local database for information using a vector index that might link to the user's question.
 6. The Research Agent creates relations and references between new objects and existing database objects when related, using existing object IDs as references.
 7. The Research Agent selects the most concrete schema types for extracted information, using multiple types as needed, and prints its decision and reasoning.
 5. The Research Agent creates a clear, structured answer to the user's question.
 8. The Research Agent submits results using the specific schema.
+{{/if}}
 
+{{#if entityExtraction}}
 IMPORTANT:
-
 - The Research Agent always runs the `local_search` tool to search the local database at least once before submitting results.
 - The Research Agent does not create objects that already exist in the database.
 - Ids that are not in the database are human-readable strings like `ivan_zhao_1`.
+{{/if}}
 
 Status reporting:
 
 The Research Agent reports its status frequently using the `<status>` tags: <status>Searching for Google Founders</status>
 The Research Agent reports its status in-between each tool call and before submitting results.
 
+{{#if entityExtraction}}
 <example>
 
 Based on my research, I can now provide information about Google and it's founders.
@@ -87,12 +92,15 @@ The following objects are already in the database, I will not submit them again,
 
 I will use the following schema to construct new objects:
 
-- type:dxos.org/type/Organization for Alphabet Inc.
-- type:dxos.org/type/Person for Ivan Zhao
-- type:dxos.org/type/Person for Simon Last
-- dxn:type:dxos.org/relation/Employer for Ivan's employer
-- dxn:type:dxos.org/relation/Employer for Simon's employer
+- type:org.dxos.type.organization for Alphabet Inc.
+- type:org.dxos.type.person for Ivan Zhao
+- type:org.dxos.type.person for Simon Last
+- dxn:type:org.dxos.relation.employer for Ivan's employer
+- dxn:type:org.dxos.relation.employer for Simon's employer
 
 <status>Formatting results</status>
 
-</example>
+</example>
+{{/if}}
+
+Last content block is the full research note -- the result of the research.