@dxos/assistant 0.8.4-main.f9ba587 → 0.8.4-main.fd6878d

package/src/research/graph.ts

@@ -1,337 +0,0 @@
-//
-// Copyright 2025 DXOS.org
-//
-
-import { Schema, identity, Option, SchemaAST } from 'effect';
-
-import { createTool, ToolResult } from '@dxos/ai';
-import type { Obj, Relation } from '@dxos/echo';
-import { Query, Filter } from '@dxos/echo';
-import { type EchoDatabase, type Queue } from '@dxos/echo-db';
-import { isEncodedReference } from '@dxos/echo-protocol';
-import {
-  EntityKind,
-  getSchemaTypename,
-  getTypeAnnotation,
-  getTypeIdentifierAnnotation,
-  create,
-  getEntityKind,
-  getSchemaDXN,
-  ObjectId,
-  ReferenceAnnotationId,
-  type BaseObject,
-  RelationSourceDXNId,
-  RelationTargetDXNId,
-  RelationSourceId,
-  RelationTargetId,
-} from '@dxos/echo-schema';
-import { mapAst } from '@dxos/effect';
-import { DXN } from '@dxos/keys';
-import { log } from '@dxos/log';
-import { deepMapValues, isNonNullable } 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.
- */
-export const createLocalSearchTool = (db: EchoDatabase, queue?: Queue) => {
-  return createTool('search', {
-    name: 'local_search',
-    description: 'Search the local database for information using a vector index',
-    schema: Schema.Struct({
-      query: Schema.String.annotations({
-        description: 'The query to search for. Could be a question or a topic or a set of keywords.',
-      }),
-    }),
-    execute: async ({ query }) => {
-      const { objects } = await db.query(Query.select(Filter.text(query, { type: 'vector' }))).run();
-      const results = [...objects];
-      if (queue) {
-        const queueObjects = await queue.queryObjects();
-        // TODO(dmaretskyi): Text search on the queue.
-        results.push(...queueObjects);
-      }
-
-      return ToolResult.Success(`
-        <local_context>
-          ${JSON.stringify(results, null, 2)}
-        </local_context>
-        `);
-    },
-  });
-};
-
-/**
- * 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<BaseObject[]> => {
-  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): SchemaAST.AST => {
-    if (SchemaAST.getAnnotation(ast, ReferenceAnnotationId).pipe(Option.isSome)) {
-      return SoftRef.ast;
-    }
-
-    return mapAst(ast, go);
-  };
-
-  return Schema.make<any, any, never>(mapAst(schema.ast, go)).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.',
-            }),
-          }),
-        )
-      : identity<Schema.Schema.AnyNoContext>,
-  );
-};
-
-export const createGraphWriterTool = ({
-  db,
-  queue,
-  schema,
-  onDone = async (x) => x,
-}: {
-  db: EchoDatabase;
-  queue?: Queue;
-  schema: Schema.Schema.AnyNoContext[];
-  onDone?: (data: Obj.Any[]) => Promise<any>;
-}) => {
-  return createTool('graph', {
-    name: 'writer',
-    description: 'Write to the local graph database',
-    schema: createExtractionSchema(schema),
-    execute: async (input) => {
-      const data = await sanitizeObjects(schema, input as any, db, queue);
-      return ToolResult.Success(await onDone(data as Obj.Any[]));
-    },
-  });
-};

package/src/research/index.ts

@@ -1,7 +0,0 @@
-//
-// Copyright 2025 DXOS.org
-//
-
-export * from './exa';
-export * from './research';
-export * from './graph';

package/src/research/instructions-research.tpl

@@ -1,97 +0,0 @@
-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 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/research/research.test.ts

@@ -1,190 +0,0 @@
-//
-// Copyright 2025 DXOS.org
-//
-
-import { inspect } from 'node:util';
-import { beforeAll, describe, test } from 'vitest';
-
-import { EdgeAiServiceClient, OllamaAiServiceClient, structuredOutputParser } from '@dxos/ai';
-import { AI_SERVICE_ENDPOINT, EXA_API_KEY } from '@dxos/ai/testing';
-import { Obj } from '@dxos/echo';
-import { type EchoDatabase } from '@dxos/echo-db';
-import { EchoTestBuilder } from '@dxos/echo-db/testing';
-import { getSchemaDXN } from '@dxos/echo-schema';
-import { ConfiguredCredentialsService, FunctionExecutor, ServiceContainer, TracingService } from '@dxos/functions';
-import { DataType, DataTypes } from '@dxos/schema';
-
-import { createExtractionSchema, getSanitizedSchemaName } from './graph';
-import { researchFn } from './research';
-
-const REMOTE_AI = true;
-const MOCK_SEARCH = false;
-
-describe.skip('Research', () => {
-  let builder: EchoTestBuilder;
-  let db: EchoDatabase;
-  let executor: FunctionExecutor;
-
-  beforeAll(async () => {
-    // TODO(dmaretskyi): Helper to scaffold this from a config.
-    builder = await new EchoTestBuilder().open();
-
-    db = (await builder.createDatabase({ indexing: { vector: true } })).db;
-    db.graph.schemaRegistry.addSchema(DataTypes);
-
-    executor = new FunctionExecutor(
-      new ServiceContainer().setServices({
-        ai: {
-          client: REMOTE_AI
-            ? new EdgeAiServiceClient({
-                endpoint: AI_SERVICE_ENDPOINT.REMOTE,
-                defaultGenerationOptions: {
-                  // model: '@anthropic/claude-sonnet-4-20250514',
-                  model: '@anthropic/claude-3-5-sonnet-20241022',
-                },
-              })
-            : new OllamaAiServiceClient({
-                overrides: {
-                  model: 'llama3.1:8b',
-                },
-              }),
-        },
-        credentials: new ConfiguredCredentialsService([{ service: 'exa.ai', apiKey: EXA_API_KEY }]),
-        database: { db },
-        tracing: TracingService.console,
-      }),
-    );
-  });
-
-  test('should generate a research report', { timeout: 300_000 }, async () => {
-    db.add(
-      Obj.make(DataType.Organization, {
-        name: 'Notion',
-        website: 'https://www.notion.com',
-      }),
-    );
-    await db.flush({ indexes: true });
-
-    const result = await executor.invoke(researchFn, {
-      query: 'Who are the founders of Notion?',
-      mockSearch: MOCK_SEARCH,
-    });
-
-    console.log(inspect(result, { depth: null, colors: true }));
-    console.log(JSON.stringify(result, null, 2));
-  });
-});
-
-describe('misc', () => {
-  test('createExtractionSchema', () => {
-    const _schema = createExtractionSchema(DataTypes);
-    // log.info('schema', { schema });
-  });
-
-  test('extract schema json schema', () => {
-    const schema = createExtractionSchema(DataTypes);
-    const _parser = structuredOutputParser(schema);
-    // log.info('schema', { json: parser.tool.parameters });
-  });
-
-  test('getSanitizedSchemaName', () => {
-    const _names = DataTypes.map(getSanitizedSchemaName);
-    // log.info('names', { names });
-  });
-
-  test('getTypeAnnotation', () => {
-    for (const schema of DataTypes) {
-      const _dxn = getSchemaDXN(schema);
-      // log.info('dxn', { schema, dxn });
-    }
-  });
-
-  test.skip('sanitizeObjects', () => {
-    const _TEST_DATA = {
-      objects_dxos_org_type_Project: [
-        {
-          name: 'Reor',
-          description:
-            'A private & local AI personal knowledge management app focused on high entropy thinkers. Features include Q&A chat with full context of notes, automatic connection of ideas, semantic search, and local-first architecture with LLMs and vector databases.',
-          image: 'https://reorhomepage-2-cwy0zagzg-reor-team.vercel.app/opengraph-image.jpg',
-          id: 'reor-project-01',
-        },
-        {
-          name: 'Personal AI',
-          description:
-            'A platform for creating personal AI models with unlimited memory capabilities. Features include memory stacking, data uploads, and personalized language models that can be trained on individual knowledge bases.',
-          image: 'https://cdn.prod.website-files.com/5ff65c460ce39f5ec5681c6a/663d12aab1b425e1ad40d3a6_Memory-min.jpg',
-          id: 'personal-ai-project-01',
-        },
-        {
-          name: 'IKI AI',
-          description:
-            'An AI-native workspace for research, strategy, and creative work. Offers features like AI summarization, content analysis, and team knowledge sharing capabilities.',
-          image: 'https://framerusercontent.com/assets/cI6Uo7x4q0W3uxzOt2preXjv6aE.jpg',
-          id: 'iki-ai-project-01',
-        },
-        {
-          name: 'Forethink',
-          description:
-            'A privacy-first, on-device AI system that proactively links current activities to relevant knowledge. Features real-time learning across teams and local data processing.',
-          image: 'https://framerusercontent.com/assets/XDhN6tICnlElB134JWcWXOuXc.jpeg',
-          id: 'forethink-project-01',
-        },
-        {
-          name: 'Amurex',
-          description:
-            'An invisible AI companion that handles tasks, remembers important information, and supports workflow. Includes features for meeting automation, email categorization, and cross-platform search.',
-          image: 'https://amurex.ai/ogimages/og_amurex.jpg',
-          id: 'amurex-project-01',
-        },
-      ],
-      objects_dxos_org_type_Organization: [
-        {
-          name: 'Reor',
-          description:
-            'A technology company focused on developing local-first AI solutions for personal knowledge management.',
-          status: 'active',
-          website: 'https://www.reorproject.org',
-          id: 'reor-org-01',
-        },
-        {
-          name: 'Personal.ai',
-          description: 'A company specializing in personal AI development and memory management solutions.',
-          status: 'active',
-          website: 'https://www.personal.ai',
-          id: 'personal-ai-org-01',
-        },
-        {
-          name: 'IKI AI',
-          description: 'A startup backed by 500 Global, developing AI-native workspaces for knowledge workers.',
-          status: 'active',
-          website: 'https://iki.ai',
-          id: 'iki-ai-org-01',
-        },
-        {
-          name: 'Forethink.ai',
-          description:
-            'A company focused on privacy-first AI solutions for knowledge management and team collaboration.',
-          status: 'active',
-          website: 'https://www.forethink.ai',
-          id: 'forethink-org-01',
-        },
-      ],
-      objects_dxos_org_type_Text: [
-        {
-          content:
-            'Current trends in AI-powered Personal Knowledge Management (PKM) systems include: 1) Shift from document-based to graph-based systems for better knowledge connection, 2) Integration of large language models for enhanced content understanding and retrieval, 3) Focus on privacy-first and local-first architectures, 4) Emphasis on automatic knowledge connection and discovery, 5) Implementation of semantic search capabilities.',
-          id: 'pkm-trends-text-01',
-        },
-        {
-          content:
-            'Key features emerging across modern PKM tools include: automated content categorization, semantic analysis and linking, personalized AI models that learn from user interaction, integration with existing workflows, and robust privacy protection. These tools are increasingly focusing on proactive knowledge surfacing rather than passive storage.',
-          id: 'pkm-features-text-01',
-        },
-      ],
-    };
-
-    // const data = await sanitizeObjects(TYPES, TEST_DATA, db);
-    // log.info('data', { data });
-  });
-});