@dxos/brain 0.12.0 → 0.13.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@dxos/brain",
3
- "version": "0.12.0",
3
+ "version": "0.13.0",
4
4
  "description": "Agent brain: pipeline-rdf facts encoded as Datalog relations, a canonical predicate vocabulary, goal built-ins and an incremental goal-rule evaluator.",
5
5
  "homepage": "https://dxos.org",
6
6
  "bugs": "https://github.com/dxos/dxos/issues",
@@ -61,10 +61,10 @@
61
61
  "src"
62
62
  ],
63
63
  "dependencies": {
64
- "@dxos/pipeline-rdf": "0.12.0",
65
- "@dxos/datalog": "0.12.0",
66
- "@dxos/errors": "0.12.0",
67
- "@dxos/util": "0.12.0"
64
+ "@dxos/datalog": "0.13.0",
65
+ "@dxos/errors": "0.13.0",
66
+ "@dxos/pipeline-rdf": "0.13.0",
67
+ "@dxos/util": "0.13.0"
68
68
  },
69
69
  "devDependencies": {
70
70
  "effect": "4.0.0",
package/src/Builtins.ts CHANGED
@@ -9,6 +9,7 @@ import * as Builtin from '@dxos/datalog/Builtin';
9
9
  /** Finds facts about a topic; a semantic index replaces the keyword one without touching rules. */
10
10
  export interface TextIndex {
11
11
  add(factId: string, text: string): void;
12
+ remove(factId: string): void;
12
13
  /** True if the fact is about `query`. */
13
14
  matches(factId: string, query: string): boolean;
14
15
  /** Every fact about `query`. */
@@ -18,6 +19,7 @@ export interface TextIndex {
18
19
  /** The entities each fact concerns (entity resolution), for scoping possessive goals. */
19
20
  export interface EntityIndex {
20
21
  add(factId: string, entities: ReadonlyArray<string>): void;
22
+ remove(factId: string): void;
21
23
  concerns(factId: string): ReadonlyArray<string>;
22
24
  facts(entity: string): Iterable<string>;
23
25
  }
@@ -109,6 +111,10 @@ export class KeywordIndex implements TextIndex {
109
111
  this.#texts.set(factId, text);
110
112
  }
111
113
 
114
+ remove(factId: string): void {
115
+ this.#texts.delete(factId);
116
+ }
117
+
112
118
  matches(factId: string, query: string): boolean {
113
119
  return keywordMatch(this.#texts.get(factId) ?? '', query);
114
120
  }
@@ -130,6 +136,10 @@ export class MemoryEntityIndex implements EntityIndex {
130
136
  this.#byFact.set(factId, entities);
131
137
  }
132
138
 
139
+ remove(factId: string): void {
140
+ this.#byFact.delete(factId);
141
+ }
142
+
133
143
  concerns(factId: string): ReadonlyArray<string> {
134
144
  return this.#byFact.get(factId) ?? [];
135
145
  }
@@ -0,0 +1,79 @@
1
+ //
2
+ // Copyright 2026 DXOS.org
3
+ //
4
+
5
+ import { describe, test } from 'vitest';
6
+
7
+ import { type RDF } from '@dxos/pipeline-rdf';
8
+
9
+ import * as Encoding from './Encoding.ts';
10
+ import * as Vocabulary from './Vocabulary.ts';
11
+
12
+ const REFUSAL: RDF.Fact = {
13
+ id: 'fact-1',
14
+ assertion: {
15
+ subject: { kind: 'entity', entity: 'dima', label: 'Dima' },
16
+ predicate: 'will-work-on',
17
+ object: { kind: 'literal', literal: 'agent plugin' },
18
+ validFrom: '2027-01-05',
19
+ validTo: '2027-01-12',
20
+ quote: "I'm busy this week, can't help with the agent plugin",
21
+ },
22
+ factuality: { value: 'CT-', polarity: '-', confidence: 0.8, nature: 'epistemic' },
23
+ illocution: { force: 'commissive', mood: 'declarative', addressee: 'rich' },
24
+ attribution: {
25
+ agent: 'dima',
26
+ source: 'dxn:queue:chat:msg-1',
27
+ generatedAtTime: '2027-01-05T10:00:00.000Z',
28
+ wasDerivedFrom: ['fact-0'],
29
+ span: { start: 0, end: 52 },
30
+ },
31
+ recordedAt: '2027-01-05T10:00:05.000Z',
32
+ extractor: { id: 'default', model: 'test', version: '1' },
33
+ sourceHash: 'abc',
34
+ pass: 'pass-1',
35
+ };
36
+
37
+ const MINIMAL: RDF.Fact = {
38
+ id: 'fact-2',
39
+ assertion: {
40
+ subject: { kind: 'entity', entity: 'release' },
41
+ predicate: 'shipped',
42
+ object: { kind: 'literal', literal: 'npm' },
43
+ },
44
+ factuality: { value: 'CT+', polarity: '+' },
45
+ attribution: { source: 'dxn:queue:chat:msg-2', generatedAtTime: '2027-01-07T16:00:00.000Z' },
46
+ recordedAt: '2027-01-07T16:00:01.000Z',
47
+ extractor: { id: 'default', model: 'test', version: '1' },
48
+ sourceHash: 'def',
49
+ };
50
+
51
+ const byRelation = (entries: ReadonlyArray<{ relation: string; tuple: ReadonlyArray<unknown> }>) =>
52
+ Object.fromEntries(entries.map(({ relation, tuple }) => [relation, tuple]));
53
+
54
+ describe('Encoding', () => {
55
+ test('encodes fact and metadata relations keyed by the fact id', ({ expect }) => {
56
+ const entries = Encoding.encode(REFUSAL, Vocabulary.make(Vocabulary.DEFAULT_ENTRIES));
57
+ const relations = byRelation(entries);
58
+ expect(relations.fact).toEqual(['fact-1', 'dima', 'works_on', 'agent plugin']);
59
+ expect(relations.surface).toEqual(['fact-1', 'will-work-on']);
60
+ expect(relations.speaker).toEqual(['fact-1', 'dima']);
61
+ expect(relations.saidAt).toEqual(['fact-1', '2027-01-05T10:00:00.000Z']);
62
+ expect(relations.force).toEqual(['fact-1', 'commissive']);
63
+ expect(relations.addressee).toEqual(['fact-1', 'rich']);
64
+ expect(relations.polarity).toEqual(['fact-1', '-']);
65
+ expect(relations.confidence).toEqual(['fact-1', 0.8]);
66
+ expect(relations.supersedes).toEqual(['fact-1', 'fact-0']);
67
+ expect(relations.pass).toEqual(['fact-1', 'pass-1']);
68
+ expect(entries.every(({ relation, tuple }) => Encoding.RELATIONS[relation] === tuple.length)).toBe(true);
69
+ expect(Encoding.factIds(entries)).toEqual(['fact-1']);
70
+ });
71
+
72
+ test('a fact without an illocution is assertive and omits absent fields', ({ expect }) => {
73
+ const relations = byRelation(Encoding.encode(MINIMAL));
74
+ expect(relations.force).toEqual(['fact-2', 'assertive']);
75
+ expect(Object.keys(relations).sort()).toEqual(
76
+ ['fact', 'factuality', 'force', 'polarity', 'recordedAt', 'saidAt', 'source', 'surface'].sort(),
77
+ );
78
+ });
79
+ });
@@ -4,6 +4,8 @@
4
4
 
5
5
  import { describe, test } from 'vitest';
6
6
 
7
+ import { type RDF } from '@dxos/pipeline-rdf';
8
+
7
9
  import * as GoalRules from './GoalRules.ts';
8
10
  import { REFERENCE, SCENARIOS, WRONG, simulate, toFact } from './testing/index.ts';
9
11
 
@@ -93,4 +95,92 @@ describe('GoalRules', () => {
93
95
  expect(rules.checkAction({ ...friday, id: 'a2', args: { start: '2027-01-05T10:00:00Z' } }).blocked).toBe(false);
94
96
  expect(rules.checkAction(friday).blocked).toBe(true);
95
97
  });
98
+
99
+ describe('working memory', () => {
100
+ const DAY = 86_400_000;
101
+ const said = (id: string, object: string, day: number, validTo?: string): RDF.Fact => {
102
+ const fact = toFact(
103
+ {
104
+ id,
105
+ speaker: 'dima',
106
+ quote: object,
107
+ s: 'dima',
108
+ p: 'says',
109
+ o: object,
110
+ force: 'assertive',
111
+ polarity: '+',
112
+ mood: 'declarative',
113
+ source: 'chat',
114
+ factuality: 'CT+',
115
+ },
116
+ new Date(day * DAY).toISOString(),
117
+ );
118
+ return validTo === undefined ? fact : { ...fact, assertion: { ...fact.assertion, validTo } };
119
+ };
120
+
121
+ test('retires the oldest facts past the cap instead of rejecting them', ({ expect }) => {
122
+ const rules = GoalRules.make({ source: 'holds(goal) :- fact(_, dima, says, a).', createdAt: 0, maxFacts: 2 });
123
+ expect(rules.update({ at: 1 * DAY, facts: [said('f1', 'a', 1)] }).holds).toBe(true);
124
+ expect(rules.update({ at: 2 * DAY, facts: [said('f2', 'b', 2)] }).holds).toBe(true);
125
+ // A re-sent fact is already in working memory and does not count again.
126
+ expect(rules.update({ at: 3 * DAY, facts: [said('f1', 'a', 1)] }).holds).toBe(true);
127
+ expect(rules.update({ at: 4 * DAY, facts: [said('f3', 'c', 4)] }).holds).toBe(false);
128
+ // A late arrival said before everything kept is itself the oldest, so it retires at once.
129
+ expect(rules.update({ at: 5 * DAY, facts: [said('f4', 'a', 0)] }).holds).toBe(false);
130
+ });
131
+
132
+ test('retires facts once the clock passes their validTo', ({ expect }) => {
133
+ const rules = GoalRules.make({ source: 'holds(goal) :- fact(_, dima, says, a).', createdAt: 0 });
134
+ const validTo = new Date(3 * DAY).toISOString();
135
+ const first = rules.update({ at: 1 * DAY, facts: [said('f1', 'a', 1, validTo)] });
136
+ expect(first.holds).toBe(true);
137
+ expect(rules.update({ at: 2 * DAY }).holds).toBe(true);
138
+ expect(rules.update({ at: 4 * DAY })).toEqual({ at: 4 * DAY, wakes: [], achieved: false, holds: false });
139
+ expect(rules.update({ at: 5 * DAY, facts: [said('f2', 'a', 5, validTo)] }).holds).toBe(false);
140
+ });
141
+
142
+ test('retiring a fact does not wake the goal', ({ expect }) => {
143
+ const rules = GoalRules.make({
144
+ source: 'wake(gap) :- not seen.\nseen :- fact(_, dima, says, b).',
145
+ createdAt: 0,
146
+ maxFacts: 1,
147
+ });
148
+ rules.update({ at: 1 * DAY, facts: [said('f1', 'b', 1)] });
149
+ expect(rules.update({ at: 2 * DAY, facts: [said('f2', 'c', 2)] }).wakes).toEqual([]);
150
+ expect(rules.update({ at: 3 * DAY }).wakes).toEqual([]);
151
+ });
152
+
153
+ test('keeps the facts behind achieved, so retirement never un-achieves the goal', ({ expect }) => {
154
+ const rules = GoalRules.make({
155
+ source: 'achieved(goal) :- fact(_, dima, says, a).',
156
+ createdAt: 0,
157
+ maxFacts: 1,
158
+ });
159
+ const validTo = new Date(2 * DAY).toISOString();
160
+ expect(rules.update({ at: 1 * DAY, facts: [said('f1', 'a', 1, validTo)] }).wakes).toEqual([
161
+ { label: 'achieved', cause: 'achieved', facts: ['f1'] },
162
+ ]);
163
+ expect(rules.update({ at: 3 * DAY, facts: [said('f2', 'b', 3)] })).toEqual({
164
+ at: 3 * DAY,
165
+ wakes: [],
166
+ achieved: true,
167
+ holds: false,
168
+ });
169
+ });
170
+
171
+ test('rejects sub-goals past the cap without applying them', ({ expect }) => {
172
+ const rules = GoalRules.make({
173
+ source:
174
+ 'achieved(goal) :- subgoal(goal, G), status(G, done), not open.\nopen :- subgoal(goal, G), status(G, active).',
175
+ createdAt: 0,
176
+ maxSubgoals: 1,
177
+ });
178
+ rules.update({ at: 1, subgoals: { first: 'active' } });
179
+ expect(() => rules.update({ at: 2, subgoals: { second: 'active' } })).toThrow(GoalRules.CapacityError);
180
+ expect(rules.update({ at: 3, subgoals: { first: 'done' } }).wakes).toEqual([
181
+ { label: 'first', cause: 'subgoal', facts: [] },
182
+ { label: 'achieved', cause: 'achieved', facts: [] },
183
+ ]);
184
+ });
185
+ });
96
186
  });
package/src/GoalRules.ts CHANGED
@@ -6,6 +6,7 @@
6
6
 
7
7
  import type * as Ast from '@dxos/datalog/Ast';
8
8
  import * as Engine from '@dxos/datalog/Engine';
9
+ import { BaseError } from '@dxos/errors';
9
10
  import { RDF } from '@dxos/pipeline-rdf';
10
11
 
11
12
  import * as Builtins from './Builtins.ts';
@@ -13,6 +14,22 @@ import * as Compiler from './Compiler.ts';
13
14
  import * as Encoding from './Encoding.ts';
14
15
  import type * as Vocabulary from './Vocabulary.ts';
15
16
 
17
+ /**
18
+ * Size of the evaluator's working memory: past it the oldest facts retire, so a goal that runs
19
+ * indefinitely keeps a bounded engine, text and entity index (and bounded queries over them).
20
+ */
21
+ export const MAX_FACTS = 10_000;
22
+
23
+ /** Most sub-goals one evaluator tracks; sub-goals are structural, so exceeding it is an error. */
24
+ export const MAX_SUBGOALS = 256;
25
+
26
+ /** Thrown by `GoalRules.update` when an input would take the evaluator past {@link MAX_SUBGOALS}. */
27
+ export class CapacityError extends BaseError.extend('CapacityError', 'Goal evaluator capacity exceeded') {
28
+ constructor(context: { readonly max: number; readonly requested: number }) {
29
+ super({ message: `Goal evaluator would hold ${context.requested} sub-goals; the cap is ${context.max}.`, context });
30
+ }
31
+ }
32
+
16
33
  /** A reason to run judgment on the goal. */
17
34
  export type Wake = {
18
35
  /** The wake rule's label, `achieved`, or the sub-goal whose status changed. */
@@ -51,6 +68,18 @@ export type Options = {
51
68
  readonly entities?: Builtins.EntityIndex;
52
69
  /** Entities a fact concerns; defaults to its subject. */
53
70
  readonly concerns?: (fact: RDF.Fact) => ReadonlyArray<string>;
71
+ /**
72
+ * Working-memory size; defaults to {@link MAX_FACTS}. Each `update` first retires facts whose
73
+ * `assertion.validTo` is before the clock, then the oldest (by `generatedAtTime`, then arrival)
74
+ * until at most `maxFacts` remain. Retiring drops a fact from the evaluator only; the feed and any
75
+ * external index keep it, and a re-sent fact with a retired id is admitted again as new.
76
+ * Retirement never wakes the goal, and the facts behind the current `achieved` derivation are
77
+ * never retired, so a goal stays achieved once it is; `holds` and wake bindings may lapse as
78
+ * their facts retire, and a lapsed binding wakes again when new facts restore it.
79
+ */
80
+ readonly maxFacts?: number;
81
+ /** Overrides {@link MAX_SUBGOALS}. */
82
+ readonly maxSubgoals?: number;
54
83
  };
55
84
 
56
85
  export type Input = {
@@ -73,16 +102,22 @@ export class GoalRules {
73
102
  readonly #text: Builtins.TextIndex;
74
103
  readonly #entities: Builtins.EntityIndex;
75
104
  readonly #concerns: (fact: RDF.Fact) => ReadonlyArray<string>;
76
- readonly #saidAt = new Map<string, number>();
105
+ /** Working memory in arrival order. */
106
+ readonly #facts = new Map<string, Admitted>();
77
107
  readonly #subgoals = new Map<string, string>();
108
+ readonly #maxFacts: number;
109
+ readonly #maxSubgoals: number;
78
110
  #now: number;
79
111
  #previous: number;
80
112
  #achieved = false;
113
+ #sequence = 0;
81
114
 
82
115
  /** @throws Compiler.CompileError if the rules do not compile. */
83
116
  constructor(options: Options) {
84
117
  this.#now = options.createdAt;
85
118
  this.#previous = options.createdAt;
119
+ this.#maxFacts = options.maxFacts ?? MAX_FACTS;
120
+ this.#maxSubgoals = options.maxSubgoals ?? MAX_SUBGOALS;
86
121
  this.#vocabulary = options.vocabulary ?? Compiler.defaultVocabulary();
87
122
  this.#text = options.text ?? new Builtins.KeywordIndex();
88
123
  this.#entities = options.entities ?? new Builtins.MemoryEntityIndex();
@@ -92,7 +127,7 @@ export class GoalRules {
92
127
  now: () => this.#now,
93
128
  previous: () => this.#previous,
94
129
  createdAt: options.createdAt,
95
- saidAt: (factId) => this.#saidAt.get(factId),
130
+ saidAt: (factId) => this.#facts.get(factId)?.saidAt,
96
131
  },
97
132
  text: this.#text,
98
133
  entities: this.#entities,
@@ -110,17 +145,47 @@ export class GoalRules {
110
145
  return this.#engine.has('holds', ['goal']);
111
146
  }
112
147
 
113
- /** Adds facts and sub-goal status at time `at`; returns the wakes and the goal's state. */
148
+ /**
149
+ * Adds facts and sub-goal status at time `at`, retiring facts past the working-memory window
150
+ * (see {@link Options.maxFacts}); returns the wakes and the goal's state.
151
+ * @throws CapacityError if the input would exceed the sub-goal cap; nothing is applied.
152
+ */
114
153
  update({ at, facts = [], subgoals = {} }: Input): Evaluation {
154
+ this.#checkSubgoals(subgoals);
115
155
  this.#previous = this.#now;
116
156
  this.#now = at;
157
+
158
+ const arrived = new Map<string, { fact: RDF.Fact; admitted: Admitted }>();
159
+ for (const fact of facts) {
160
+ if (!this.#facts.has(fact.id) && !arrived.has(fact.id)) {
161
+ arrived.set(fact.id, { fact, admitted: this.#admit(fact) });
162
+ }
163
+ }
164
+ const retired = this.#retire([...arrived.values()].map(({ admitted }) => admitted));
165
+ const retiring: Engine.Entry[] = [];
166
+ for (const id of retired) {
167
+ const admitted = this.#facts.get(id);
168
+ if (admitted) {
169
+ retiring.push(...admitted.entries);
170
+ this.#facts.delete(id);
171
+ this.#text.remove(id);
172
+ this.#entities.remove(id);
173
+ }
174
+ }
175
+ if (retiring.length > 0) {
176
+ // A separate pass whose changes are discarded, so retirement never wakes the goal.
177
+ this.#engine.update({ retract: retiring });
178
+ }
179
+
117
180
  const insert: Engine.Entry[] = [];
118
181
  const retract: Engine.Entry[] = [];
119
- for (const fact of facts) {
120
- this.#saidAt.set(fact.id, Date.parse(fact.attribution.generatedAtTime));
121
- this.#text.add(fact.id, factText(fact));
122
- this.#entities.add(fact.id, this.#concerns(fact));
123
- insert.push(...Encoding.encode(fact, this.#vocabulary));
182
+ for (const { fact, admitted } of arrived.values()) {
183
+ if (!retired.has(fact.id)) {
184
+ this.#facts.set(fact.id, admitted);
185
+ this.#text.add(fact.id, factText(fact));
186
+ this.#entities.add(fact.id, this.#concerns(fact));
187
+ insert.push(...admitted.entries);
188
+ }
124
189
  }
125
190
 
126
191
  const wakes: Wake[] = [];
@@ -158,6 +223,51 @@ export class GoalRules {
158
223
  return { at, wakes, achieved, holds: this.holds };
159
224
  }
160
225
 
226
+ #checkSubgoals(subgoals: Readonly<Record<string, string>>): void {
227
+ const requested = this.#subgoals.size + Object.keys(subgoals).filter((id) => !this.#subgoals.has(id)).length;
228
+ if (requested > this.#maxSubgoals) {
229
+ throw new CapacityError({ max: this.#maxSubgoals, requested });
230
+ }
231
+ }
232
+
233
+ #admit(fact: RDF.Fact): Admitted {
234
+ const validTo = fact.assertion.validTo === undefined ? undefined : Date.parse(fact.assertion.validTo);
235
+ return {
236
+ id: fact.id,
237
+ sequence: this.#sequence++,
238
+ saidAt: Date.parse(fact.attribution.generatedAtTime),
239
+ validTo: validTo === undefined || Number.isNaN(validTo) ? undefined : validTo,
240
+ entries: Encoding.encode(fact, this.#vocabulary),
241
+ };
242
+ }
243
+
244
+ /** Ids to retire from working memory plus the arriving facts: expired first, then oldest past the cap. */
245
+ #retire(arriving: ReadonlyArray<Admitted>): Set<string> {
246
+ const pinned = new Set(this.achieved ? Encoding.factIds(this.#engine.provenance('achieved', ['goal'])) : []);
247
+ const retired = new Set<string>();
248
+ const kept: Admitted[] = [];
249
+ for (const admitted of [...this.#facts.values(), ...arriving]) {
250
+ if (!pinned.has(admitted.id) && admitted.validTo !== undefined && admitted.validTo < this.#now) {
251
+ retired.add(admitted.id);
252
+ } else {
253
+ kept.push(admitted);
254
+ }
255
+ }
256
+ let excess = kept.length - this.#maxFacts;
257
+ if (excess > 0) {
258
+ const oldest = kept
259
+ .filter(({ id }) => !pinned.has(id))
260
+ .sort((a, b) => age(a.saidAt) - age(b.saidAt) || a.sequence - b.sequence);
261
+ for (const { id } of oldest) {
262
+ if (excess-- <= 0) {
263
+ break;
264
+ }
265
+ retired.add(id);
266
+ }
267
+ }
268
+ return retired;
269
+ }
270
+
161
271
  /** Evaluates the `blocks` rules for a proposed action without keeping it. */
162
272
  checkAction(action: Action): ActionCheck {
163
273
  const entries: Engine.Entry[] = [
@@ -173,9 +283,24 @@ export class GoalRules {
173
283
  }
174
284
  }
175
285
 
286
+ /** A fact in working memory, with what retirement needs to order and retract it. */
287
+ type Admitted = {
288
+ readonly id: string;
289
+ /** Arrival order, the tie-break between facts said at the same time. */
290
+ readonly sequence: number;
291
+ readonly saidAt: number;
292
+ readonly validTo?: number;
293
+ readonly entries: ReadonlyArray<Engine.Entry>;
294
+ };
295
+
296
+ /** An unparseable `generatedAtTime` sorts as oldest. */
297
+ const age = (saidAt: number): number => (Number.isNaN(saidAt) ? Number.NEGATIVE_INFINITY : saidAt);
298
+
176
299
  /** Creates a goal evaluator. */
177
300
  export const make = (options: Options): GoalRules => new GoalRules(options);
178
301
 
179
302
  /** The text `about` matches: what was said plus the triple. */
180
303
  const factText = ({ assertion }: RDF.Fact): string =>
181
- [assertion.quote ?? '', RDF.termValue(assertion.subject), assertion.predicate, RDF.termValue(assertion.object)].join(' ');
304
+ [assertion.quote ?? '', RDF.termValue(assertion.subject), assertion.predicate, RDF.termValue(assertion.object)].join(
305
+ ' ',
306
+ );