@dxos/assistant-toolkit 0.8.4-main.ae835ea

package/src/functions/research/graph.test.ts

@@ -0,0 +1,69 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as AnthropicClient from '@effect/ai-anthropic/AnthropicClient';
+import * as FetchHttpClient from '@effect/platform/FetchHttpClient';
+import { describe, it } from '@effect/vitest';
+import * as Config from 'effect/Config';
+import * as Effect from 'effect/Effect';
+import * as Function from 'effect/Function';
+import * as Layer from 'effect/Layer';
+
+import { AiService, ToolExecutionService, ToolResolverService } from '@dxos/ai';
+import * as AiServiceRouter from '@dxos/ai/AiServiceRouter';
+import { tapHttpErrors } from '@dxos/ai/testing';
+import { AiSession } from '@dxos/assistant';
+import { TestHelpers } from '@dxos/effect';
+import { DatabaseService, TracingService } from '@dxos/functions';
+import { log } from '@dxos/log';
+import { DataType } from '@dxos/schema';
+
+import { makeGraphWriterHandler, makeGraphWriterToolkit } from './graph';
+
+// import { type EchoTestBuilder } from '@dxos/echo-db/testing';
+
+const TestLayer = Function.pipe(
+  AiService.model('@anthropic/claude-3-5-sonnet-20241022'),
+  Layer.provideMerge(DatabaseService.notAvailable),
+  Layer.provideMerge(ToolResolverService.layerEmpty),
+  Layer.provideMerge(ToolExecutionService.layerEmpty),
+  Layer.provide(AiServiceRouter.AiServiceRouter),
+  Layer.provide(
+    AnthropicClient.layerConfig({
+      apiKey: Config.redacted('ANTHROPIC_API_KEY'),
+      transformClient: tapHttpErrors,
+    }),
+  ),
+  Layer.provide(FetchHttpClient.layer),
+  Layer.provideMerge(TracingService.layerNoop),
+);
+
+describe('graph', () => {
+  // let builder: EchoTestBuilder;
+  // test('findRelatedSchema', async () => {
+  //   const db = await createEchoDatabase();
+  //   const relatedSchemas = await findRelatedSchema(db, Schema.Struct({}));
+  // });
+
+  const Toolkit = makeGraphWriterToolkit({ schema: [DataType.Project] });
+  const ToolkitLayer = makeGraphWriterHandler(Toolkit);
+
+  it.effect.skip(
+    'calculator',
+    Effect.fn(
+      function* (_) {
+        const session = new AiSession();
+        const toolkit = yield* Toolkit;
+        const response = yield* session.run({
+          toolkit,
+          prompt: 'What is 10 + 20?',
+        });
+
+        log.info('response', { response });
+      },
+      Effect.provide(Layer.mergeAll(TestLayer, ToolkitLayer)),
+      TestHelpers.runIf(process.env.ANTHROPIC_API_KEY),
+    ),
+  );
+});

package/src/functions/research/graph.ts

@@ -0,0 +1,388 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Tool from '@effect/ai/Tool';
+import * as Toolkit from '@effect/ai/Toolkit';
+import * as Context from 'effect/Context';
+import * as Effect from 'effect/Effect';
+import * as Function from 'effect/Function';
+import * as Option from 'effect/Option';
+import * as Schema from 'effect/Schema';
+import * as SchemaAST from 'effect/SchemaAST';
+
+import { Obj, type Relation } from '@dxos/echo';
+import { Filter, Query } from '@dxos/echo';
+import {
+  EntityKind,
+  ObjectId,
+  ReferenceAnnotationId,
+  RelationSourceDXNId,
+  RelationSourceId,
+  RelationTargetDXNId,
+  RelationTargetId,
+  create,
+  getEntityKind,
+  getSchemaDXN,
+  getSchemaTypename,
+  getTypeAnnotation,
+  getTypeIdentifierAnnotation,
+} from '@dxos/echo/internal';
+import { type EchoDatabase, type Queue } from '@dxos/echo-db';
+import { isEncodedReference } from '@dxos/echo-protocol';
+import { mapAst } from '@dxos/effect';
+import { ContextQueueService, DatabaseService } from '@dxos/functions';
+import { DXN } from '@dxos/keys';
+import { log } from '@dxos/log';
+import { deepMapValues, isNonNullable, trim } from '@dxos/util';
+
+// TODO(burdon): Unify with the graph schema.
+export const Subgraph = Schema.Struct({
+  /** Objects and relations. */
+  objects: Schema.Array(Schema.Any),
+});
+
+export interface Subgraph extends Schema.Schema.Type<typeof Subgraph> {}
+
+export type RelatedSchema = {
+  schema: Schema.Schema.AnyNoContext;
+  kind: 'reference' | 'relation';
+};
+
+/**
+ * Find all schemas that are related to the given schema.
+ *
+ * @param db
+ * @param schema
+ * @returns
+ */
+export const findRelatedSchema = async (
+  db: EchoDatabase,
+  anchor: Schema.Schema.AnyNoContext,
+): Promise<RelatedSchema[]> => {
+  // TODO(dmaretskyi): Query stored schemas.
+  const allSchemas = [...db.graph.schemaRegistry.schemas];
+
+  // TODO(dmaretskyi): Also do references.
+  return allSchemas
+    .filter((schema) => {
+      if (getTypeAnnotation(schema)?.kind !== EntityKind.Relation) {
+        return false;
+      }
+
+      return (
+        isSchemaAddressableByDxn(anchor, DXN.parse(getTypeAnnotation(schema)!.sourceSchema!)) ||
+        isSchemaAddressableByDxn(anchor, DXN.parse(getTypeAnnotation(schema)!.targetSchema!))
+      );
+    })
+    .map(
+      (schema): RelatedSchema => ({
+        schema,
+        kind: 'relation',
+      }),
+    );
+};
+
+/**
+ * Non-strict DXN comparison.
+ * Returns true if the DXN could be resolved to the schema.
+ */
+const isSchemaAddressableByDxn = (schema: Schema.Schema.AnyNoContext, dxn: DXN): boolean => {
+  if (getTypeIdentifierAnnotation(schema) === dxn.toString()) {
+    return true;
+  }
+
+  const t = dxn.asTypeDXN();
+  if (t) {
+    return t.type === getSchemaTypename(schema);
+  }
+
+  return false;
+};
+
+/**
+ * Perform vector search in the local database.
+ */
+// TODO(dmaretskyi): Rename `GraphReadToolkit`.
+export const LocalSearchToolkit = Toolkit.make(
+  Tool.make('search_local_search', {
+    description: 'Search the local database for information using a vector index',
+    parameters: {
+      query: Schema.String.annotations({
+        description: 'The query to search for. Could be a question or a topic or a set of keywords.',
+      }),
+    },
+    success: Schema.Unknown,
+    failure: Schema.Never,
+    dependencies: [DatabaseService],
+  }),
+);
+
+export const LocalSearchHandler = LocalSearchToolkit.toLayer({
+  search_local_search: Effect.fn(function* ({ query }) {
+    const { objects } = yield* DatabaseService.runQuery(Query.select(Filter.text(query, { type: 'vector' })));
+    const results = [...objects];
+
+    const option = yield* Effect.serviceOption(ContextQueueService);
+    if (Option.isSome(option)) {
+      const queueObjects = yield* Effect.promise(() => option.value.queue.queryObjects());
+      // TODO(dmaretskyi): Text search on the queue.
+      results.push(...queueObjects);
+    }
+
+    return trim`
+      <local_context>
+        ${JSON.stringify(results, null, 2)}
+      </local_context>
+    `;
+  }),
+});
+
+/**
+ * Attached as an annotation to the writer tool.
+ */
+class GraphWriterSchema extends Context.Tag('@dxos/assistant/GraphWriterSchema')<
+  GraphWriterSchema,
+  {
+    schema: Schema.Schema.AnyNoContext[];
+  }
+>() {}
+
+/**
+ * Forms typed objects that can be written to the graph database.
+ */
+export const makeGraphWriterToolkit = ({ schema }: { schema: Schema.Schema.AnyNoContext[] }) => {
+  return Toolkit.make(
+    Tool.make('graph_writer', {
+      description: 'Write to the local graph database',
+      parameters: createExtractionSchema(schema).fields,
+      success: Schema.Unknown,
+      failure: Schema.Never,
+      dependencies: [DatabaseService, ContextQueueService],
+    }).annotateContext(Context.make(GraphWriterSchema, { schema })),
+  );
+};
+
+export const makeGraphWriterHandler = (
+  toolkit: ReturnType<typeof makeGraphWriterToolkit>,
+  {
+    onAppend,
+  }: {
+    onAppend?: (object: DXN[]) => void;
+  } = {},
+) => {
+  const { schema } = Context.get(
+    toolkit.tools.graph_writer.annotations as Context.Context<GraphWriterSchema>,
+    GraphWriterSchema,
+  );
+
+  return toolkit.toLayer({
+    graph_writer: Effect.fn(function* (input) {
+      const { db } = yield* DatabaseService;
+      const { queue } = yield* ContextQueueService;
+      const data = yield* Effect.promise(() => sanitizeObjects(schema, input as any, db, queue));
+      yield* Effect.promise(() => queue.append(data as Obj.Any[]));
+
+      const dxns = data.map((obj) => Obj.getDXN(obj));
+      onAppend?.(dxns);
+      return dxns;
+    }),
+  });
+};
+
+/**
+ * Create a schema for structured data extraction.
+ */
+export const createExtractionSchema = (types: Schema.Schema.AnyNoContext[]) => {
+  return Schema.Struct({
+    ...Object.fromEntries(
+      types.map(preprocessSchema).map((schema, index) => [
+        `objects_${getSanitizedSchemaName(types[index])}`,
+        Schema.optional(Schema.Array(schema)).annotations({
+          description: `The objects of type: ${getSchemaDXN(types[index])?.asTypeDXN()!.type}. ${SchemaAST.getDescriptionAnnotation(types[index].ast).pipe(Option.getOrElse(() => ''))}`,
+        }),
+      ]),
+    ),
+  });
+};
+
+export const getSanitizedSchemaName = (schema: Schema.Schema.AnyNoContext) => {
+  return getSchemaDXN(schema)!
+    .asTypeDXN()!
+    .type.replaceAll(/[^a-zA-Z0-9]+/g, '_');
+};
+
+export const sanitizeObjects = async (
+  types: Schema.Schema.AnyNoContext[],
+  data: Record<string, readonly unknown[]>,
+  db: EchoDatabase,
+  queue?: Queue,
+): Promise<Obj.Any[]> => {
+  const entries = types
+    .map(
+      (type) =>
+        data[`objects_${getSanitizedSchemaName(type)}`]?.map((object: any) => ({
+          data: object,
+          schema: type,
+        })) ?? [],
+    )
+    .flat();
+
+  const idMap = new Map<string, string>();
+  const existingIds = new Set<ObjectId>();
+  const enitties = new Map<ObjectId, Obj.Any | Relation.Any>();
+
+  const resolveId = (id: string): DXN | undefined => {
+    if (ObjectId.isValid(id)) {
+      existingIds.add(id);
+      return DXN.fromLocalObjectId(id);
+    }
+
+    const mappedId = idMap.get(id);
+    if (mappedId) {
+      return DXN.fromLocalObjectId(mappedId);
+    }
+
+    return undefined;
+  };
+
+  const res = entries
+    .map((entry) => {
+      // This entry mutates existing object.
+      if (ObjectId.isValid(entry.data.id)) {
+        return entry;
+      }
+
+      idMap.set(entry.data.id, ObjectId.random());
+      entry.data.id = idMap.get(entry.data.id);
+      return entry;
+    })
+    .map((entry) => {
+      const data = deepMapValues(entry.data, (value, recurse) => {
+        if (isEncodedReference(value)) {
+          const ref = value['/'];
+          const id = resolveId(ref);
+
+          if (id) {
+            // Link to an existing object.
+            return { '/': id.toString() };
+          } else {
+            // Search URIs?
+            return { '/': `search:?q=${encodeURIComponent(ref)}` };
+          }
+        }
+
+        return recurse(value);
+      });
+
+      if (getEntityKind(entry.schema) === 'relation') {
+        const sourceDxn = resolveId(data.source);
+        if (!sourceDxn) {
+          log.warn('source not found', { source: data.source });
+        }
+        const targetDxn = resolveId(data.target);
+        if (!targetDxn) {
+          log.warn('target not found', { target: data.target });
+        }
+        delete data.source;
+        delete data.target;
+        data[RelationSourceDXNId] = sourceDxn;
+        data[RelationTargetDXNId] = targetDxn;
+      }
+
+      return {
+        data,
+        schema: entry.schema,
+      };
+    })
+    .filter((object) => !existingIds.has(object.data.id)); // TODO(dmaretskyi): This dissallows updating existing objects.
+
+  // TODO(dmaretskyi): Use ref resolver.
+  const { objects: dbObjects } = await db.query(Query.select(Filter.ids(...existingIds))).run();
+  const queueObjects = (await queue?.getObjectsById([...existingIds])) ?? [];
+  const objects = [...dbObjects, ...queueObjects].filter(isNonNullable);
+
+  // TODO(dmaretskyi): Returns everything if IDs are empty!
+  log.info('objects', { dbObjects, queueObjects, existingIds });
+  const missing = Array.from(existingIds).filter((id) => !objects.some((object) => object.id === id));
+  if (missing.length > 0) {
+    throw new Error(`Object IDs do not point to existing objects: ${missing.join(', ')}`);
+  }
+
+  return res.flatMap(({ data, schema }) => {
+    let skip = false;
+    if (RelationSourceDXNId in data) {
+      const id = (data[RelationSourceDXNId] as DXN).asEchoDXN()?.echoId;
+      const obj = objects.find((object) => object.id === id) ?? enitties.get(id!);
+      if (obj) {
+        delete data[RelationSourceDXNId];
+        data[RelationSourceId] = obj;
+      } else {
+        skip = true;
+      }
+    }
+    if (RelationTargetDXNId in data) {
+      const id = (data[RelationTargetDXNId] as DXN).asEchoDXN()?.echoId;
+      const obj = objects.find((object) => object.id === id) ?? enitties.get(id!);
+      if (obj) {
+        delete data[RelationTargetDXNId];
+        data[RelationTargetId] = obj;
+      } else {
+        skip = true;
+      }
+    }
+    if (!skip) {
+      const obj = create(schema, data);
+      enitties.set(obj.id, obj);
+      return [obj];
+    }
+    return [];
+  });
+};
+
+const SoftRef = Schema.Struct({
+  '/': Schema.String,
+}).annotations({
+  description: 'Reference to another object.',
+});
+
+const preprocessSchema = (schema: Schema.Schema.AnyNoContext) => {
+  const isRelationSchema = getEntityKind(schema) === 'relation';
+
+  const go = (ast: SchemaAST.AST, visited = new Set<SchemaAST.AST>()): SchemaAST.AST => {
+    if (visited.has(ast)) {
+      // Already visited this node, prevent infinite recursion.
+      return ast;
+    }
+    visited.add(ast);
+
+    if (SchemaAST.getAnnotation(ast, ReferenceAnnotationId).pipe(Option.isSome)) {
+      return SoftRef.ast;
+    }
+
+    return mapAst(ast, (child) => go(child, visited));
+  };
+
+  return Schema.make<any, any, never>(mapAst(schema.ast, (ast) => go(ast))).pipe(
+    Schema.omit('id'),
+    Schema.extend(
+      Schema.Struct({
+        id: Schema.String.annotations({
+          description: 'The id of this object. Come up with a unique id based on your judgement.',
+        }),
+      }),
+    ),
+    isRelationSchema
+      ? Schema.extend(
+          Schema.Struct({
+            source: Schema.String.annotations({
+              description: 'The id of the source object for this relation.',
+            }),
+            target: Schema.String.annotations({
+              description: 'The id of the target object for this relation.',
+            }),
+          }),
+        )
+      : Function.identity<Schema.Schema.AnyNoContext>,
+  );
+};

package/src/functions/research/index.ts

@@ -0,0 +1,15 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { default as create$ } from './create-document';
+import { default as research$ } from './research';
+
+export * from './graph';
+export * from './research-graph';
+export * from './types';
+
+export namespace Research {
+  export const create = create$;
+  export const research = research$;
+}

package/src/functions/research/instructions-research.tpl

@@ -0,0 +1,98 @@
+You are the Research Agent.
+
+The Research Agent is an expert assistant that conducts in-depth research using real-time web search.
+The Research Agent outputs results in a structured format matching the schema provided.
+
+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
+- Synthesize accurate, clear, and structured answers using reliable information from the retrieved content
+- Search the local database for information using a vector index (through a `local_search` tool)
+
+The Research Agent always follows these principles:
+
+- Relevance First: The Research Agent only returns facts supported by content in retrieved web pages. The Research Agent never fabricates or guesses information.
+- Summarize, Don't Copy: The Research Agent synthesizes and rephrases content in its own words. The Research Agent quotes only when necessary.
+- Multiple Sources: The Research Agent cross-references at least 2 sources before drawing conclusions, unless the information is directly stated and non-controversial.
+- 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.
+- 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.
+- The Research Agent creates relations and references between new objects found and what's already in the database.
+- 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.
+
+The Research Agent may be asked for:
+
+- Technical explanations
+- Literature reviews  
+- Comparisons
+- Emerging trends
+- Implementation strategies
+
+The Research Agent begins by interpreting the user's request, then:
+
+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:
+
+- A clear, structured answer to the user's question
+- A citation list or link list of sources used
+
+Optionally, the Research Agent provides follow-up suggestions or questions for deeper inquiry.
+
+Here's how the Research Agent operates:
+
+1. The Research Agent analyzes the user's request and identifies key topics to search for (3 or more), printing them out.
+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.
+
+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.
+
+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`.
+
+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.
+
+<example>
+
+Based on my research, I can now provide information about Google and it's founders.
+
+The following objects are already in the database, I will not submit them again, but I'll re-use their IDs as references:
+
+- 01JWRDEHPB5TT2JQQQC15038BT Google
+- 01JWRDEHPA14CYW2NW9FAH6DJJ Larry Page
+- 01JWRDEHPBN0BBJP57B9S108W6 Sergey Brin
+
+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
+
+<status>Formatting results</status>
+
+</example>

package/src/functions/research/research-graph.ts

@@ -0,0 +1,47 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+import * as Schema from 'effect/Schema';
+
+import { Obj, Query, Ref, Type } from '@dxos/echo';
+import { Queue } from '@dxos/echo-db';
+import { ContextQueueService, DatabaseService, QueueService } from '@dxos/functions';
+
+/**
+ * Container for a set of ephemeral research results.
+ */
+export const ResearchGraph = Schema.Struct({
+  queue: Type.Ref(Queue),
+}).pipe(
+  Type.Obj({
+    typename: 'dxos.org/type/ResearchGraph',
+    version: '0.1.0',
+  }),
+);
+
+export interface ResearchGraph extends Schema.Schema.Type<typeof ResearchGraph> {}
+
+export const queryResearchGraph: () => Effect.Effect<ResearchGraph | undefined, never, DatabaseService> = Effect.fn(
+  'queryResearchGraph',
+)(function* () {
+  const { objects } = yield* DatabaseService.runQuery(Query.type(ResearchGraph));
+  return objects.at(0);
+});
+
+export const createResearchGraph: () => Effect.Effect<ResearchGraph, never, DatabaseService | QueueService> = Effect.fn(
+  'createResearchGraph',
+)(function* () {
+  const queue = yield* QueueService.createQueue();
+  return yield* DatabaseService.add(Obj.make(ResearchGraph, { queue: Ref.fromDXN(queue.dxn) }));
+});
+
+export const contextQueueLayerFromResearchGraph = Layer.unwrapEffect(
+  Effect.gen(function* () {
+    const researchGraph = (yield* queryResearchGraph()) ?? (yield* createResearchGraph());
+    const researchQueue = yield* DatabaseService.load(researchGraph.queue);
+    return ContextQueueService.layer(researchQueue);
+  }),
+);