@dxos/assistant 0.8.4-staging.60fe92afc8 → 0.9.1-main.c7dcc2e112

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dxos/assistant",
-  "version": "0.8.4-staging.60fe92afc8",
+  "version": "0.9.1-main.c7dcc2e112",
   "description": "Natural language interface to DXOS",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
@@ -38,26 +38,26 @@
     "@effect/platform": "0.96.1",
     "@xenova/transformers": "^2.17.2",
     "lodash.defaultsdeep": "^4.6.1",
-    "@dxos/ai": "0.8.4-staging.60fe92afc8",
-    "@dxos/async": "0.8.4-staging.60fe92afc8",
-    "@dxos/compute": "0.8.4-staging.60fe92afc8",
-    "@dxos/debug": "0.8.4-staging.60fe92afc8",
-    "@dxos/context": "0.8.4-staging.60fe92afc8",
-    "@dxos/echo": "0.8.4-staging.60fe92afc8",
-    "@dxos/echo-client": "0.8.4-staging.60fe92afc8",
-    "@dxos/effect": "0.8.4-staging.60fe92afc8",
-    "@dxos/echo-protocol": "0.8.4-staging.60fe92afc8",
-    "@dxos/errors": "0.8.4-staging.60fe92afc8",
-    "@dxos/functions": "0.8.4-staging.60fe92afc8",
-    "@dxos/graph": "0.8.4-staging.60fe92afc8",
-    "@dxos/log": "0.8.4-staging.60fe92afc8",
-    "@dxos/keys": "0.8.4-staging.60fe92afc8",
-    "@dxos/mcp-client": "0.8.4-staging.60fe92afc8",
-    "@dxos/node-std": "0.8.4-staging.60fe92afc8",
-    "@dxos/types": "0.8.4-staging.60fe92afc8",
-    "@dxos/schema": "0.8.4-staging.60fe92afc8",
-    "@dxos/util": "0.8.4-staging.60fe92afc8",
-    "@dxos/invariant": "0.8.4-staging.60fe92afc8"
+    "@dxos/ai": "0.9.1-main.c7dcc2e112",
+    "@dxos/async": "0.9.1-main.c7dcc2e112",
+    "@dxos/compute": "0.9.1-main.c7dcc2e112",
+    "@dxos/context": "0.9.1-main.c7dcc2e112",
+    "@dxos/debug": "0.9.1-main.c7dcc2e112",
+    "@dxos/echo": "0.9.1-main.c7dcc2e112",
+    "@dxos/echo-client": "0.9.1-main.c7dcc2e112",
+    "@dxos/errors": "0.9.1-main.c7dcc2e112",
+    "@dxos/echo-protocol": "0.9.1-main.c7dcc2e112",
+    "@dxos/graph": "0.9.1-main.c7dcc2e112",
+    "@dxos/keys": "0.9.1-main.c7dcc2e112",
+    "@dxos/functions": "0.9.1-main.c7dcc2e112",
+    "@dxos/log": "0.9.1-main.c7dcc2e112",
+    "@dxos/mcp-client": "0.9.1-main.c7dcc2e112",
+    "@dxos/invariant": "0.9.1-main.c7dcc2e112",
+    "@dxos/node-std": "0.9.1-main.c7dcc2e112",
+    "@dxos/effect": "0.9.1-main.c7dcc2e112",
+    "@dxos/types": "0.9.1-main.c7dcc2e112",
+    "@dxos/schema": "0.9.1-main.c7dcc2e112",
+    "@dxos/util": "0.9.1-main.c7dcc2e112"
   },
   "devDependencies": {
     "@types/lodash.defaultsdeep": "^4.6.6",

package/src/extraction/extraction-llm-function/index.ts

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

package/src/extraction/extraction-llm-function/proper-noun-extraction.ts

@@ -0,0 +1,78 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as LanguageModel from '@effect/ai/LanguageModel';
+import * as Effect from 'effect/Effect';
+import * as Schema from 'effect/Schema';
+
+import { AiService } from '@dxos/ai';
+import { type Database, Obj } from '@dxos/echo';
+import { Message } from '@dxos/types';
+
+import { findReferences, insertReferences } from '../quotes';
+
+const EXTRACTION_MODEL = 'ai.claude.model.claude-haiku-4-5';
+
+/**
+ * Proper nouns extracted from transcript text.
+ */
+export const ProperNouns = Schema.Struct({
+  properNouns: Schema.Array(Schema.String).annotations({
+    description: 'Proper nouns (names of people, organizations, places, products) mentioned in the text.',
+  }),
+});
+export type ProperNouns = Schema.Schema.Type<typeof ProperNouns>;
+
+/**
+ * Extracts proper nouns from transcript text using a small LLM (Haiku). Provides the LanguageModel
+ * internally so the residual requirement is just {@link AiService.AiService}.
+ */
+export const extractProperNouns = (text: string) =>
+  Effect.gen(function* () {
+    const { value } = yield* Effect.scoped(
+      LanguageModel.generateObject({
+        schema: ProperNouns,
+        prompt: [
+          'Extract every proper noun (people, organizations, places, products) mentioned in the transcript text below.',
+          'Return only the surface strings exactly as they appear. Exclude common nouns and pronouns.',
+          '',
+          'Transcript:',
+          text,
+        ].join('\n'),
+      }),
+    );
+
+    // Drop short tokens (e.g. "IT"): insertReferences replaces case-insensitive substrings, so a
+    // short noun would match inside unrelated words ("secur[IT]y") and corrupt neighbouring links.
+    return value.properNouns.map((noun) => noun.trim()).filter((noun) => noun.length >= 3);
+  }).pipe(Effect.provide(AiService.model(EXTRACTION_MODEL)));
+
+/**
+ * Enriches a transcript message: for each transcript block, extracts proper nouns, links them to
+ * objects in the space via full-text search, and rewrites the text with `[noun](dxn)` references.
+ * Requires {@link AiService.AiService}; takes the space database handle.
+ */
+export const enrichTranscriptMessage = (message: Message.Message, { db }: { db: Database.Database }) =>
+  Effect.gen(function* () {
+    const blocks = yield* Effect.forEach(message.blocks, (block) =>
+      Effect.gen(function* () {
+        if (block._tag !== 'transcript') {
+          return block;
+        }
+
+        const nouns = yield* extractProperNouns(block.text);
+        const references = yield* Effect.promise(() => findReferences([...nouns], db));
+        return { ...block, text: insertReferences(block.text, references) };
+      }),
+    );
+
+    // Preserve the message identity and metadata; enrichment only rewrites transcript block text.
+    return Obj.make(Message.Message, {
+      id: message.id,
+      sender: message.sender,
+      created: message.created,
+      properties: message.properties,
+      blocks,
+    });
+  });

package/src/extraction/index.ts

@@ -2,6 +2,6 @@
 // Copyright 2025 DXOS.org
 //
 
-export * from './extraction';
+export * from './extraction-llm-function';
 export * from './extraction-ner-function';
 export * from './quotes';

package/src/extraction/quotes.test.ts

@@ -2,9 +2,13 @@
 // Copyright 2025 DXOS.org
 //
 
-import { describe, expect, test } from 'vitest';
+import { afterEach, beforeEach, describe, expect, test } from 'vitest';
 
-import { insertReferences } from './quotes';
+import { Obj } from '@dxos/echo';
+import { EchoTestBuilder } from '@dxos/echo-client/testing';
+import { Organization, Person } from '@dxos/types';
+
+import { findReferences, insertReferences } from './quotes';
 
 describe('insertReferences', () => {
   test('should replace quotes with DXN references', () => {
@@ -24,4 +28,65 @@ describe('insertReferences', () => {
       "And what I'd like to talk today about is Steven Wolfram's concept of a [computational irreducibility](echo:/01JTG9JW11XGWJZ32AW8ET93D1).",
     );
   });
+
+  test('does not nest links when one quote is a substring of another', () => {
+    const quotes = {
+      references: [
+        { quote: 'Sarah', id: '01JTG9JW11XGWJZ32AW8ET93D1' },
+        { quote: 'Sarah Johnson', id: '01JTG9JW11XGWJZ32AW8ET93D1' },
+      ],
+    };
+
+    // "Sarah Johnson" is linked as a whole (processed first); the standalone "Sarah" is linked
+    // separately; the "Sarah" inside the first link is left untouched (no nested `[[..](..)](..)`).
+    expect(insertReferences('Sarah Johnson spoke. Later Sarah left.', quotes)).toBe(
+      '[Sarah Johnson](echo:/01JTG9JW11XGWJZ32AW8ET93D1) spoke. Later [Sarah](echo:/01JTG9JW11XGWJZ32AW8ET93D1) left.',
+    );
+  });
+
+  test('does not re-link a repeated quote inside an already-inserted link', () => {
+    const quotes = { references: [{ quote: 'Amco', id: '01JTG9JW11XGWJZ32AW8ET93D1' }] };
+
+    expect(insertReferences('Amco and Amco again.', quotes)).toBe(
+      '[Amco](echo:/01JTG9JW11XGWJZ32AW8ET93D1) and [Amco](echo:/01JTG9JW11XGWJZ32AW8ET93D1) again.',
+    );
+  });
+});
+
+describe('findReferences', () => {
+  let builder: EchoTestBuilder;
+
+  beforeEach(async () => {
+    builder = await new EchoTestBuilder().open();
+  });
+
+  afterEach(async () => {
+    await builder.close();
+  });
+
+  test('links nouns to objects via full-text search, including first-name tokens', async () => {
+    const { db } = await builder.createDatabase({ types: [Organization.Organization, Person.Person] });
+    const amco = db.add(Obj.make(Organization.Organization, { name: 'Amco' }));
+    const sarah = db.add(Obj.make(Person.Person, { fullName: 'Sarah Johnson' }));
+    await db.flush({ indexes: true });
+
+    const { references } = await findReferences(['Amco', 'Sarah', 'Nonexistent'], db);
+    const byQuote = new Map(references.map((reference) => [reference.quote, reference.id]));
+
+    expect(byQuote.get('Amco')).toEqual(amco.id);
+    // Full-text matches a single token within a multi-word field, so first-name mentions link to
+    // the full-name object — this is also what makes the overlap case in `insertReferences` real.
+    expect(byQuote.get('Sarah')).toEqual(sarah.id);
+    expect(byQuote.has('Nonexistent')).toBe(false);
+  });
+
+  test('deduplicates and trims nouns before lookup', async () => {
+    const { db } = await builder.createDatabase({ types: [Organization.Organization] });
+    db.add(Obj.make(Organization.Organization, { name: 'Amco' }));
+    await db.flush({ indexes: true });
+
+    const { references } = await findReferences(['Amco', 'Amco', '  Amco  ', ''], db);
+
+    expect(references.filter((reference) => reference.quote === 'Amco')).toHaveLength(1);
+  });
 });

package/src/extraction/quotes.ts

@@ -6,7 +6,6 @@ import * as Schema from 'effect/Schema';
 
 import { type Database, Filter, Query } from '@dxos/echo';
 import { EID, EntityId } from '@dxos/keys';
-import { log } from '@dxos/log';
 
 export const ReferencedQuotes = Schema.Struct({
   references: Schema.Array(
@@ -26,12 +25,30 @@ export const ReferencedQuotes = Schema.Struct({
 });
 export type ReferencedQuotes = Schema.Schema.Type<typeof ReferencedQuotes>;
 
-export const findQuotes = async (quotes: string[], db: Database.Database): Promise<ReferencedQuotes> => {
+export type FindReferencesOptions = {
+  /** Search backend. Full-text matches proper nouns precisely; vector matches semantically. */
+  searchKind?: 'full-text' | 'vector';
+};
+
+/**
+ * Finds the best-matching context object for each noun and returns it as a reference.
+ */
+export const findReferences = async (
+  nouns: string[],
+  db: Database.Database,
+  { searchKind = 'full-text' }: FindReferencesOptions = {},
+): Promise<ReferencedQuotes> => {
+  // Deduplicate and process longer nouns first: `insertReferences` rewrites case-insensitive
+  // substrings, so a repeated or shorter overlapping noun would re-replace already-linked text and
+  // produce nested/broken markdown links.
+  const normalizedNouns = Array.from(new Set(nouns.map((noun) => noun.trim()).filter((noun) => noun.length > 0))).sort(
+    (leftNoun, rightNoun) => rightNoun.length - leftNoun.length,
+  );
+
   const references = await Promise.all(
-    quotes.map(async (quote) => {
-      const objects = await db.query(Query.select(Filter.text(quote, { type: 'vector' }))).run();
-      log.info('found quotes in vector index', { objects, quote });
-      return objects.length > 0 ? [{ id: objects[0].id.toString(), quote }] : [];
+    normalizedNouns.map(async (noun) => {
+      const objects = await db.query(Query.select(Filter.text(noun, { type: searchKind }))).run();
+      return objects.length > 0 ? [{ id: objects[0].id.toString(), quote: noun }] : [];
     }),
   );
   return { references: references.flat() };
@@ -41,16 +58,33 @@ export const findQuotes = async (quotes: string[], db: Database.Database): Promi
  * Finds and replaces all quotes with DXNs references.
  */
 // TODO(dmaretskyi): Lookup and verifiy ids from provided context.
-export const insertReferences = (text: string, quotes: ReferencedQuotes) => {
-  for (const quote of quotes.references) {
-    if (!EntityId.isValid(quote.id)) {
-      continue;
-    }
+export const insertReferences = (text: string, quotes: ReferencedQuotes): string => {
+  // Process longer quotes first so e.g. "Sarah Johnson" is linked before "Sarah". Combined with the
+  // link-aware replacement below this stops a shorter or overlapping quote from rewriting text that
+  // is already part of an inserted link (which would produce nested `[[..](..)](..)` markdown).
+  const references = quotes.references
+    .filter((quote) => EntityId.isValid(quote.id))
+    .sort((left, right) => right.quote.length - left.quote.length);
 
-    // Use a case-insensitive regular expression to replace the quote.
+  for (const quote of references) {
+    // Case-insensitive match of the (regex-escaped) quote.
     const regex = new RegExp(quote.quote.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'), 'gi');
-    text = text.replace(regex, `[${quote.quote}](${EID.make({ entityId: quote.id })})`);
+    text = replaceOutsideLinks(text, regex, `[${quote.quote}](${EID.make({ entityId: quote.id })})`);
   }
 
   return text;
 };
+
+const MARKDOWN_LINK = /\[[^\]]*\]\([^)]*\)/g;
+
+/** Applies a replacement to every span of `text` that is not already inside a `[label](url)` link. */
+const replaceOutsideLinks = (text: string, regex: RegExp, replacement: string): string => {
+  let result = '';
+  let plainStart = 0;
+  for (const link of text.matchAll(MARKDOWN_LINK)) {
+    const index = link.index ?? 0;
+    result += text.slice(plainStart, index).replace(regex, replacement) + link[0];
+    plainStart = index + link[0].length;
+  }
+  return result + text.slice(plainStart).replace(regex, replacement);
+};

package/src/request/AiRequest.ts

@@ -60,6 +60,13 @@ export type Options = {
    * This is useful for streaming the output to a queue.
    */
   onOutput?: (message: Message.Message) => Effect.Effect<void, never, never>;
+
+  /**
+   * When false, turn messages are not appended to the feed or written as persisted trace blocks.
+   *
+   * @default true
+   */
+  persist?: boolean;
 };
 
 export type RunProps<R = never> = {
@@ -139,6 +146,9 @@ export class Request {
     Effect.gen(this, function* () {
       this._pending.push(message);
       yield* this._observer.onMessage(message);
+      if (this._options.persist === false) {
+        return message;
+      }
       for (const block of message.blocks) {
         log('write complete block', {
           messageId: message.id,

package/src/session/AiSession.ts

@@ -41,6 +41,13 @@ export type RunProps<R = never> = {
    * Space-level MCP servers to connect alongside blueprint-defined ones.
    */
   mcpServers?: readonly McpServer.McpServer[];
+
+  /**
+   * When false, messages from this request are not appended to the feed or persisted to trace.
+   *
+   * @default true
+   */
+  persist?: boolean;
 };
 
 export type Options = {
@@ -145,6 +152,7 @@ export class Session extends Resource {
       const request = new AiRequest.Request({
         summarizationThreshold: SUMMARY_THRESHOLD,
         observer: params.observer,
+        persist: params.persist,
         onOutput: (message) =>
           Effect.promise(() => Runtime.runPromise(this._runtime)(Feed.append(this._feed, [message]))),
       });