@dxos/brain 0.12.0 → 0.14.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/dist/lib/Builtins.mjs +10 -2
- package/dist/lib/Builtins.mjs.map +1 -1
- package/dist/lib/Encoding.mjs +12 -2
- package/dist/lib/Encoding.mjs.map +1 -1
- package/dist/lib/Evaluator.mjs +144 -0
- package/dist/lib/Evaluator.mjs.map +1 -0
- package/dist/lib/GoalRules.mjs +153 -11
- package/dist/lib/GoalRules.mjs.map +1 -1
- package/dist/lib/Oracle.mjs +169 -0
- package/dist/lib/Oracle.mjs.map +1 -0
- package/dist/lib/index.mjs +3 -1
- package/dist/types/src/Builtins.d.ts +6 -0
- package/dist/types/src/Builtins.d.ts.map +1 -1
- package/dist/types/src/Encoding.d.ts +4 -0
- package/dist/types/src/Encoding.d.ts.map +1 -1
- package/dist/types/src/Encoding.test.d.ts +2 -0
- package/dist/types/src/Encoding.test.d.ts.map +1 -0
- package/dist/types/src/Evaluator.d.ts +77 -0
- package/dist/types/src/Evaluator.d.ts.map +1 -0
- package/dist/types/src/Evaluator.test.d.ts +2 -0
- package/dist/types/src/Evaluator.test.d.ts.map +1 -0
- package/dist/types/src/GoalRules.d.ts +66 -1
- package/dist/types/src/GoalRules.d.ts.map +1 -1
- package/dist/types/src/Oracle.d.ts +126 -0
- package/dist/types/src/Oracle.d.ts.map +1 -0
- package/dist/types/src/Oracle.test.d.ts +2 -0
- package/dist/types/src/Oracle.test.d.ts.map +1 -0
- package/dist/types/src/index.d.ts +2 -0
- package/dist/types/src/index.d.ts.map +1 -1
- package/dist/types/tsconfig.tsbuildinfo +1 -1
- package/package.json +15 -5
- package/src/Builtins.ts +12 -1
- package/src/Encoding.test.ts +93 -0
- package/src/Encoding.ts +9 -0
- package/src/Evaluator.test.ts +158 -0
- package/src/Evaluator.ts +186 -0
- package/src/GoalRules.test.ts +98 -0
- package/src/GoalRules.ts +212 -10
- package/src/Oracle.test.ts +71 -0
- package/src/Oracle.ts +182 -0
- package/src/index.ts +2 -0
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,24 @@ 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
|
-
|
|
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;
|
|
110
|
+
readonly #createdAt: number;
|
|
78
111
|
#now: number;
|
|
79
112
|
#previous: number;
|
|
80
113
|
#achieved = false;
|
|
114
|
+
#sequence = 0;
|
|
81
115
|
|
|
82
116
|
/** @throws Compiler.CompileError if the rules do not compile. */
|
|
83
117
|
constructor(options: Options) {
|
|
118
|
+
this.#createdAt = options.createdAt;
|
|
84
119
|
this.#now = options.createdAt;
|
|
85
120
|
this.#previous = options.createdAt;
|
|
121
|
+
this.#maxFacts = options.maxFacts ?? MAX_FACTS;
|
|
122
|
+
this.#maxSubgoals = options.maxSubgoals ?? MAX_SUBGOALS;
|
|
86
123
|
this.#vocabulary = options.vocabulary ?? Compiler.defaultVocabulary();
|
|
87
124
|
this.#text = options.text ?? new Builtins.KeywordIndex();
|
|
88
125
|
this.#entities = options.entities ?? new Builtins.MemoryEntityIndex();
|
|
@@ -92,7 +129,7 @@ export class GoalRules {
|
|
|
92
129
|
now: () => this.#now,
|
|
93
130
|
previous: () => this.#previous,
|
|
94
131
|
createdAt: options.createdAt,
|
|
95
|
-
saidAt: (factId) => this.#
|
|
132
|
+
saidAt: (factId) => this.#facts.get(factId)?.saidAt,
|
|
96
133
|
},
|
|
97
134
|
text: this.#text,
|
|
98
135
|
entities: this.#entities,
|
|
@@ -110,17 +147,47 @@ export class GoalRules {
|
|
|
110
147
|
return this.#engine.has('holds', ['goal']);
|
|
111
148
|
}
|
|
112
149
|
|
|
113
|
-
/**
|
|
150
|
+
/**
|
|
151
|
+
* Adds facts and sub-goal status at time `at`, retiring facts past the working-memory window
|
|
152
|
+
* (see {@link Options.maxFacts}); returns the wakes and the goal's state.
|
|
153
|
+
* @throws CapacityError if the input would exceed the sub-goal cap; nothing is applied.
|
|
154
|
+
*/
|
|
114
155
|
update({ at, facts = [], subgoals = {} }: Input): Evaluation {
|
|
156
|
+
this.#checkSubgoals(subgoals);
|
|
115
157
|
this.#previous = this.#now;
|
|
116
158
|
this.#now = at;
|
|
159
|
+
|
|
160
|
+
const arrived = new Map<string, { fact: RDF.Fact; admitted: Admitted }>();
|
|
161
|
+
for (const fact of facts) {
|
|
162
|
+
if (!this.#facts.has(fact.id) && !arrived.has(fact.id)) {
|
|
163
|
+
arrived.set(fact.id, { fact, admitted: this.#admit(fact) });
|
|
164
|
+
}
|
|
165
|
+
}
|
|
166
|
+
const retired = this.#retire([...arrived.values()].map(({ admitted }) => admitted));
|
|
167
|
+
const retiring: Engine.Entry[] = [];
|
|
168
|
+
for (const id of retired) {
|
|
169
|
+
const admitted = this.#facts.get(id);
|
|
170
|
+
if (admitted) {
|
|
171
|
+
retiring.push(...admitted.entries);
|
|
172
|
+
this.#facts.delete(id);
|
|
173
|
+
this.#text.remove(id);
|
|
174
|
+
this.#entities.remove(id);
|
|
175
|
+
}
|
|
176
|
+
}
|
|
177
|
+
if (retiring.length > 0) {
|
|
178
|
+
// A separate pass whose changes are discarded, so retirement never wakes the goal.
|
|
179
|
+
this.#engine.update({ retract: retiring });
|
|
180
|
+
}
|
|
181
|
+
|
|
117
182
|
const insert: Engine.Entry[] = [];
|
|
118
183
|
const retract: Engine.Entry[] = [];
|
|
119
|
-
for (const fact of
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
184
|
+
for (const { fact, admitted } of arrived.values()) {
|
|
185
|
+
if (!retired.has(fact.id)) {
|
|
186
|
+
this.#facts.set(fact.id, admitted);
|
|
187
|
+
this.#text.add(fact.id, factText(fact));
|
|
188
|
+
this.#entities.add(fact.id, this.#concerns(fact));
|
|
189
|
+
insert.push(...admitted.entries);
|
|
190
|
+
}
|
|
124
191
|
}
|
|
125
192
|
|
|
126
193
|
const wakes: Wake[] = [];
|
|
@@ -139,7 +206,16 @@ export class GoalRules {
|
|
|
139
206
|
this.#subgoals.set(subgoal, status);
|
|
140
207
|
}
|
|
141
208
|
|
|
142
|
-
const
|
|
209
|
+
const refresh = this.#now !== this.#previous;
|
|
210
|
+
if (refresh) {
|
|
211
|
+
// Re-evaluate at the previous time with no period boundary crossed, discarding the changes: otherwise a
|
|
212
|
+
// binding `every` held at the previous evaluation is still present, and the next boundary adds nothing new.
|
|
213
|
+
const now = this.#now;
|
|
214
|
+
this.#now = this.#previous;
|
|
215
|
+
this.#engine.update({ refresh: true });
|
|
216
|
+
this.#now = now;
|
|
217
|
+
}
|
|
218
|
+
const changes = this.#engine.update({ insert, retract, refresh });
|
|
143
219
|
for (const [relation, label] of this.compilation.wakes) {
|
|
144
220
|
for (const tuple of changes.added.get(relation) ?? []) {
|
|
145
221
|
wakes.push({ label, cause: 'rule', facts: Encoding.factIds(this.#engine.provenance(relation, tuple)) });
|
|
@@ -158,6 +234,115 @@ export class GoalRules {
|
|
|
158
234
|
return { at, wakes, achieved, holds: this.holds };
|
|
159
235
|
}
|
|
160
236
|
|
|
237
|
+
#checkSubgoals(subgoals: Readonly<Record<string, string>>): void {
|
|
238
|
+
const requested = this.#subgoals.size + Object.keys(subgoals).filter((id) => !this.#subgoals.has(id)).length;
|
|
239
|
+
if (requested > this.#maxSubgoals) {
|
|
240
|
+
throw new CapacityError({ max: this.#maxSubgoals, requested });
|
|
241
|
+
}
|
|
242
|
+
}
|
|
243
|
+
|
|
244
|
+
#admit(fact: RDF.Fact): Admitted {
|
|
245
|
+
const validTo = fact.assertion.validTo === undefined ? undefined : Date.parse(fact.assertion.validTo);
|
|
246
|
+
return {
|
|
247
|
+
id: fact.id,
|
|
248
|
+
sequence: this.#sequence++,
|
|
249
|
+
saidAt: Date.parse(fact.attribution.generatedAtTime),
|
|
250
|
+
validTo: validTo === undefined || Number.isNaN(validTo) ? undefined : validTo,
|
|
251
|
+
entries: Encoding.encode(fact, this.#vocabulary),
|
|
252
|
+
};
|
|
253
|
+
}
|
|
254
|
+
|
|
255
|
+
/** Ids to retire from working memory plus the arriving facts: expired first, then oldest past the cap. */
|
|
256
|
+
#retire(arriving: ReadonlyArray<Admitted>): Set<string> {
|
|
257
|
+
const pinned = new Set(this.achieved ? Encoding.factIds(this.#engine.provenance('achieved', ['goal'])) : []);
|
|
258
|
+
const retired = new Set<string>();
|
|
259
|
+
const kept: Admitted[] = [];
|
|
260
|
+
for (const admitted of [...this.#facts.values(), ...arriving]) {
|
|
261
|
+
if (!pinned.has(admitted.id) && admitted.validTo !== undefined && admitted.validTo < this.#now) {
|
|
262
|
+
retired.add(admitted.id);
|
|
263
|
+
} else {
|
|
264
|
+
kept.push(admitted);
|
|
265
|
+
}
|
|
266
|
+
}
|
|
267
|
+
let excess = kept.length - this.#maxFacts;
|
|
268
|
+
if (excess > 0) {
|
|
269
|
+
const oldest = kept
|
|
270
|
+
.filter(({ id }) => !pinned.has(id))
|
|
271
|
+
.sort((a, b) => age(a.saidAt) - age(b.saidAt) || a.sequence - b.sequence);
|
|
272
|
+
for (const { id } of oldest) {
|
|
273
|
+
if (excess-- <= 0) {
|
|
274
|
+
break;
|
|
275
|
+
}
|
|
276
|
+
retired.add(id);
|
|
277
|
+
}
|
|
278
|
+
}
|
|
279
|
+
return retired;
|
|
280
|
+
}
|
|
281
|
+
|
|
282
|
+
/**
|
|
283
|
+
* The earliest time after the last evaluation at which a time built-in can change its answer
|
|
284
|
+
* (`elapsed`, `every`, `due`), so a host schedules its next {@link update} rather than polling;
|
|
285
|
+
* `undefined` when the rules read no clock.
|
|
286
|
+
*/
|
|
287
|
+
nextDueAt(): number | undefined {
|
|
288
|
+
const candidates: number[] = [];
|
|
289
|
+
const after = (time: number | undefined) => {
|
|
290
|
+
if (time !== undefined && time > this.#now) {
|
|
291
|
+
candidates.push(time);
|
|
292
|
+
}
|
|
293
|
+
};
|
|
294
|
+
const constant = (term: Ast.Term | undefined): Ast.Value | undefined =>
|
|
295
|
+
term?.type === 'constant' ? term.value : undefined;
|
|
296
|
+
const visit = (literal: Ast.Literal): void => {
|
|
297
|
+
if (literal.type === 'aggregate') {
|
|
298
|
+
literal.body.forEach(visit);
|
|
299
|
+
return;
|
|
300
|
+
}
|
|
301
|
+
if (literal.type !== 'atom') {
|
|
302
|
+
return;
|
|
303
|
+
}
|
|
304
|
+
const [first, second] = literal.atom.terms;
|
|
305
|
+
switch (literal.atom.predicate) {
|
|
306
|
+
case 'elapsed': {
|
|
307
|
+
const length = Builtins.parseDuration(constant(second) ?? '');
|
|
308
|
+
if (length === undefined) {
|
|
309
|
+
return;
|
|
310
|
+
}
|
|
311
|
+
const ref = constant(first);
|
|
312
|
+
if (ref === undefined) {
|
|
313
|
+
// `elapsed(F, …)` over facts: each fact in working memory starts its own clock.
|
|
314
|
+
for (const { saidAt } of this.#facts.values()) {
|
|
315
|
+
after(saidAt + length);
|
|
316
|
+
}
|
|
317
|
+
} else if (ref === 'goal') {
|
|
318
|
+
after(this.#createdAt + length);
|
|
319
|
+
} else {
|
|
320
|
+
const start = this.#facts.get(String(ref))?.saidAt ?? Builtins.parseTime(ref);
|
|
321
|
+
after(start === undefined ? undefined : start + length);
|
|
322
|
+
}
|
|
323
|
+
return;
|
|
324
|
+
}
|
|
325
|
+
case 'every': {
|
|
326
|
+
const period = Builtins.parseDuration(constant(first) ?? '');
|
|
327
|
+
if (period !== undefined && period > 0) {
|
|
328
|
+
after(this.#createdAt + (Math.floor((this.#now - this.#createdAt) / period) + 1) * period);
|
|
329
|
+
}
|
|
330
|
+
return;
|
|
331
|
+
}
|
|
332
|
+
case 'due': {
|
|
333
|
+
const deadline = Builtins.parseTime(constant(first) ?? '');
|
|
334
|
+
const lead = Builtins.parseDuration(constant(second) ?? '');
|
|
335
|
+
after(deadline === undefined || lead === undefined ? undefined : deadline - lead);
|
|
336
|
+
return;
|
|
337
|
+
}
|
|
338
|
+
}
|
|
339
|
+
};
|
|
340
|
+
for (const rule of this.compilation.program.rules) {
|
|
341
|
+
rule.body.forEach(visit);
|
|
342
|
+
}
|
|
343
|
+
return candidates.length === 0 ? undefined : Math.min(...candidates);
|
|
344
|
+
}
|
|
345
|
+
|
|
161
346
|
/** Evaluates the `blocks` rules for a proposed action without keeping it. */
|
|
162
347
|
checkAction(action: Action): ActionCheck {
|
|
163
348
|
const entries: Engine.Entry[] = [
|
|
@@ -173,9 +358,26 @@ export class GoalRules {
|
|
|
173
358
|
}
|
|
174
359
|
}
|
|
175
360
|
|
|
361
|
+
/** A fact in working memory, with what retirement needs to order and retract it. */
|
|
362
|
+
type Admitted = {
|
|
363
|
+
readonly id: string;
|
|
364
|
+
/** Arrival order, the tie-break between facts said at the same time. */
|
|
365
|
+
readonly sequence: number;
|
|
366
|
+
readonly saidAt: number;
|
|
367
|
+
readonly validTo?: number;
|
|
368
|
+
readonly entries: ReadonlyArray<Engine.Entry>;
|
|
369
|
+
};
|
|
370
|
+
|
|
371
|
+
/** An unparseable `generatedAtTime` sorts as oldest. */
|
|
372
|
+
const age = (saidAt: number): number => (Number.isNaN(saidAt) ? Number.NEGATIVE_INFINITY : saidAt);
|
|
373
|
+
|
|
176
374
|
/** Creates a goal evaluator. */
|
|
177
375
|
export const make = (options: Options): GoalRules => new GoalRules(options);
|
|
178
376
|
|
|
377
|
+
/** A term's id and, for an entity known by an opaque id (a DID), its label, so `about` matches the name. */
|
|
378
|
+
const termText = (term: RDF.Term): string =>
|
|
379
|
+
term.kind === 'entity' && term.label !== undefined ? `${term.entity} ${term.label}` : RDF.termValue(term);
|
|
380
|
+
|
|
179
381
|
/** The text `about` matches: what was said plus the triple. */
|
|
180
382
|
const factText = ({ assertion }: RDF.Fact): string =>
|
|
181
|
-
[assertion.quote ?? '',
|
|
383
|
+
[assertion.quote ?? '', termText(assertion.subject), assertion.predicate, termText(assertion.object)].join(' ');
|
|
@@ -0,0 +1,71 @@
|
|
|
1
|
+
//
|
|
2
|
+
// Copyright 2026 DXOS.org
|
|
3
|
+
//
|
|
4
|
+
|
|
5
|
+
import { describe, test } from 'vitest';
|
|
6
|
+
|
|
7
|
+
import * as Oracle from './Oracle.ts';
|
|
8
|
+
import { REFERENCE } from './testing/index.ts';
|
|
9
|
+
|
|
10
|
+
const CREATED = Date.parse('2027-01-04T09:00:00Z');
|
|
11
|
+
|
|
12
|
+
/** A timeline for goal 1 ("keep me informed about what Dima is working on"), as an oracle might write it. */
|
|
13
|
+
const TIMELINE = JSON.stringify({
|
|
14
|
+
steps: [
|
|
15
|
+
{
|
|
16
|
+
after: '10m',
|
|
17
|
+
says: [
|
|
18
|
+
{
|
|
19
|
+
speaker: 'rich',
|
|
20
|
+
quote: 'Lunch?',
|
|
21
|
+
subject: 'rich',
|
|
22
|
+
predicate: 'suggests',
|
|
23
|
+
object: 'lunch',
|
|
24
|
+
force: 'directive',
|
|
25
|
+
},
|
|
26
|
+
],
|
|
27
|
+
wake: false,
|
|
28
|
+
note: 'unrelated, and not Dima',
|
|
29
|
+
},
|
|
30
|
+
{
|
|
31
|
+
after: '1h',
|
|
32
|
+
says: [
|
|
33
|
+
{ speaker: 'dima', quote: 'I am on the indexer.', subject: 'dima', predicate: 'works on', object: 'indexer' },
|
|
34
|
+
],
|
|
35
|
+
wake: true,
|
|
36
|
+
},
|
|
37
|
+
],
|
|
38
|
+
});
|
|
39
|
+
|
|
40
|
+
describe('Oracle', () => {
|
|
41
|
+
test('parses a timeline, also inside a code fence', ({ expect }) => {
|
|
42
|
+
const reply = Oracle.parseReply(`Here it is:\n\`\`\`json\n${TIMELINE}\n\`\`\``);
|
|
43
|
+
expect(reply.steps.map(({ wake }) => wake)).toEqual([false, true]);
|
|
44
|
+
expect(() => Oracle.parseReply('no json')).toThrow(Oracle.ReplyError);
|
|
45
|
+
expect(() => Oracle.parseReply('{"steps":[]}')).toThrow(Oracle.ReplyError);
|
|
46
|
+
});
|
|
47
|
+
|
|
48
|
+
test('passes a compilation that replays the timeline and fails one that does not', ({ expect }) => {
|
|
49
|
+
const { steps } = Oracle.parseReply(TIMELINE);
|
|
50
|
+
expect(Oracle.replay(REFERENCE[1], { createdAt: CREATED, steps })).toEqual({ ok: true, failures: [] });
|
|
51
|
+
|
|
52
|
+
// Waking on anyone at all wakes on the near miss.
|
|
53
|
+
const loose = Oracle.replay('wake(any) :- fact(F, _, _, _).', { createdAt: CREATED, steps });
|
|
54
|
+
expect(loose.ok).toBe(false);
|
|
55
|
+
expect(loose.failures).toEqual([
|
|
56
|
+
expect.stringContaining('step 1 (unrelated, and not Dima): wake=true, expected false'),
|
|
57
|
+
]);
|
|
58
|
+
|
|
59
|
+
// Rules that do not compile fail the gate rather than throw.
|
|
60
|
+
expect(Oracle.replay('wake(x) :- nonsense(', { createdAt: CREATED, steps }).ok).toBe(false);
|
|
61
|
+
});
|
|
62
|
+
|
|
63
|
+
test('tells the oracle the ids people go by', ({ expect }) => {
|
|
64
|
+
const message = Oracle.userMessage({
|
|
65
|
+
goal: 'Keep me posted on Bob',
|
|
66
|
+
owner: 'did:halo:ALICE',
|
|
67
|
+
people: [{ name: 'Bob', id: 'did:halo:BOB' }],
|
|
68
|
+
});
|
|
69
|
+
expect(message).toContain('Bob = did:halo:BOB');
|
|
70
|
+
});
|
|
71
|
+
});
|
package/src/Oracle.ts
ADDED
|
@@ -0,0 +1,182 @@
|
|
|
1
|
+
//
|
|
2
|
+
// Copyright 2026 DXOS.org
|
|
3
|
+
//
|
|
4
|
+
|
|
5
|
+
// @import-as-namespace
|
|
6
|
+
|
|
7
|
+
import * as Schema from 'effect/Schema';
|
|
8
|
+
|
|
9
|
+
import { BaseError } from '@dxos/errors';
|
|
10
|
+
import { type RDF } from '@dxos/pipeline-rdf';
|
|
11
|
+
import { trim } from '@dxos/util';
|
|
12
|
+
|
|
13
|
+
import * as Builtins from './Builtins.ts';
|
|
14
|
+
import * as Compiler from './Compiler.ts';
|
|
15
|
+
import * as GoalRules from './GoalRules.ts';
|
|
16
|
+
|
|
17
|
+
/**
|
|
18
|
+
* The replay gate's oracle (BRAIN.md, "Compilation"): a model call that sees only the goal's text and
|
|
19
|
+
* writes a short timeline of statements with what each should do to the goal. A compilation goes active
|
|
20
|
+
* only if it replays that timeline correctly; the oracle never sees the rules, so it cannot share the
|
|
21
|
+
* compiler's misreading of the goal.
|
|
22
|
+
*/
|
|
23
|
+
|
|
24
|
+
/** One statement in a test timeline; people and things are named by the ids the goal was given. */
|
|
25
|
+
export const Statement = Schema.Struct({
|
|
26
|
+
speaker: Schema.String,
|
|
27
|
+
quote: Schema.String,
|
|
28
|
+
subject: Schema.String,
|
|
29
|
+
predicate: Schema.String,
|
|
30
|
+
object: Schema.String,
|
|
31
|
+
force: Schema.optional(Schema.Literals(['assertive', 'directive', 'commissive', 'expressive'])),
|
|
32
|
+
polarity: Schema.optional(Schema.Literals(['+', '-'])),
|
|
33
|
+
});
|
|
34
|
+
export interface Statement extends Schema.Schema.Type<typeof Statement> {}
|
|
35
|
+
|
|
36
|
+
/** A step of the timeline: when it happens after the goal is set, what is said, and what should follow. */
|
|
37
|
+
export const Step = Schema.Struct({
|
|
38
|
+
/** A duration after the goal was set, e.g. `10m`, `1h`, `3d`. */
|
|
39
|
+
after: Schema.String,
|
|
40
|
+
says: Schema.Array(Statement),
|
|
41
|
+
/** Whether the goal should wake (be judged) at this step. */
|
|
42
|
+
wake: Schema.Boolean,
|
|
43
|
+
/** Whether the goal should be achieved after this step; absent when either is acceptable. */
|
|
44
|
+
achieved: Schema.optional(Schema.Boolean),
|
|
45
|
+
note: Schema.optional(Schema.String),
|
|
46
|
+
});
|
|
47
|
+
export interface Step extends Schema.Schema.Type<typeof Step> {}
|
|
48
|
+
|
|
49
|
+
export const Reply = Schema.Struct({ steps: Schema.Array(Step) });
|
|
50
|
+
export interface Reply extends Schema.Schema.Type<typeof Reply> {}
|
|
51
|
+
|
|
52
|
+
export type Person = { readonly name: string; readonly id: string };
|
|
53
|
+
|
|
54
|
+
export type Goal = {
|
|
55
|
+
readonly goal: string;
|
|
56
|
+
readonly instructions?: string;
|
|
57
|
+
/** Id of the goal's owner. */
|
|
58
|
+
readonly owner: string;
|
|
59
|
+
/** People the goal may concern, with the ids statements must use for them. */
|
|
60
|
+
readonly people?: ReadonlyArray<Person>;
|
|
61
|
+
};
|
|
62
|
+
|
|
63
|
+
/** Thrown by {@link parseReply} when the reply is not a timeline. */
|
|
64
|
+
export class ReplyError extends BaseError.extend('OracleReplyError', 'Oracle reply is not a timeline') {}
|
|
65
|
+
|
|
66
|
+
/** The oracle's instructions. */
|
|
67
|
+
export const SYSTEM_PROMPT = trim`
|
|
68
|
+
You write acceptance tests for an agent's goal. A goal is a plain-text directive; a runtime will decide,
|
|
69
|
+
after every statement anyone makes, whether the goal should WAKE (the agent looks at it again because
|
|
70
|
+
something relevant happened) and whether it is ACHIEVED (its outcome happened). You do not see how the
|
|
71
|
+
runtime decides; you only describe what a careful person would expect.
|
|
72
|
+
|
|
73
|
+
Write a short timeline of 3 to 6 steps after the goal is set. Include at least one step that should
|
|
74
|
+
wake the goal and at least one near miss that should not (the wrong person, an unrelated topic, a
|
|
75
|
+
refusal or a question instead of a statement). Say only what is needed; each step usually has one
|
|
76
|
+
statement.
|
|
77
|
+
|
|
78
|
+
Each statement is one fact as an extractor would record it: who said it (speaker), the words as said
|
|
79
|
+
(quote), and a subject–predicate–object triple. Name people by the ids given with the goal, exactly as
|
|
80
|
+
given (e.g. "did:halo:…"); name other things with lowercase hyphenated words ("indexer-migration").
|
|
81
|
+
force is assertive (states), directive (asks), commissive (promises or agrees) or expressive; polarity
|
|
82
|
+
is "+" (affirmed) or "-" (denied, refused).
|
|
83
|
+
|
|
84
|
+
Reply with JSON only:
|
|
85
|
+
{"steps":[{"after":"10m","says":[{"speaker":"…","quote":"…","subject":"…","predicate":"…","object":"…","force":"assertive","polarity":"+"}],"wake":true,"achieved":false,"note":"why"}]}
|
|
86
|
+
"after" is a duration since the goal was set (10m, 2h, 3d) and must increase from step to step.
|
|
87
|
+
Leave "achieved" out when either answer would be acceptable.
|
|
88
|
+
`;
|
|
89
|
+
|
|
90
|
+
/** The user message for one goal. */
|
|
91
|
+
export const userMessage = ({ goal, instructions, owner, people = [] }: Goal): string =>
|
|
92
|
+
[
|
|
93
|
+
`Goal: "${goal}"`,
|
|
94
|
+
`Owner: ${owner}`,
|
|
95
|
+
instructions?.trim() ? `Instructions: ${instructions.trim()}` : undefined,
|
|
96
|
+
people.length > 0
|
|
97
|
+
? `People (use these ids): ${people.map(({ name, id }) => `${name} = ${id}`).join('; ')}`
|
|
98
|
+
: undefined,
|
|
99
|
+
]
|
|
100
|
+
.filter((line) => line !== undefined)
|
|
101
|
+
.join('\n');
|
|
102
|
+
|
|
103
|
+
const decode = Schema.decodeUnknownSync(Reply);
|
|
104
|
+
|
|
105
|
+
/**
|
|
106
|
+
* Extracts the timeline from the oracle's reply; tolerates a code fence or prose around the JSON.
|
|
107
|
+
* @throws ReplyError if there is no valid timeline.
|
|
108
|
+
*/
|
|
109
|
+
export const parseReply = (text: string): Reply => {
|
|
110
|
+
const start = text.indexOf('{');
|
|
111
|
+
const end = text.lastIndexOf('}');
|
|
112
|
+
if (start < 0 || end <= start) {
|
|
113
|
+
throw new ReplyError({ message: 'the reply has no JSON object' });
|
|
114
|
+
}
|
|
115
|
+
try {
|
|
116
|
+
const reply = decode(JSON.parse(text.slice(start, end + 1)));
|
|
117
|
+
if (reply.steps.length === 0) {
|
|
118
|
+
throw new ReplyError({ message: 'the timeline is empty' });
|
|
119
|
+
}
|
|
120
|
+
return reply;
|
|
121
|
+
} catch (error) {
|
|
122
|
+
throw error instanceof ReplyError
|
|
123
|
+
? error
|
|
124
|
+
: new ReplyError({ message: error instanceof Error ? error.message : String(error) });
|
|
125
|
+
}
|
|
126
|
+
};
|
|
127
|
+
|
|
128
|
+
/** A statement as the fact the extractor would record. */
|
|
129
|
+
const toFact = (statement: Statement, id: string, saidAt: string): RDF.Fact => ({
|
|
130
|
+
id,
|
|
131
|
+
assertion: {
|
|
132
|
+
subject: { kind: 'entity', entity: statement.subject },
|
|
133
|
+
predicate: statement.predicate,
|
|
134
|
+
object: { kind: 'entity', entity: statement.object },
|
|
135
|
+
quote: statement.quote,
|
|
136
|
+
},
|
|
137
|
+
factuality: { value: statement.polarity === '-' ? 'CT-' : 'CT+', polarity: statement.polarity ?? '+' },
|
|
138
|
+
illocution: { force: statement.force ?? 'assertive' },
|
|
139
|
+
attribution: { agent: statement.speaker, source: 'oracle', generatedAtTime: saidAt },
|
|
140
|
+
recordedAt: saidAt,
|
|
141
|
+
extractor: { id: 'oracle', model: 'none', version: '1' },
|
|
142
|
+
sourceHash: id,
|
|
143
|
+
});
|
|
144
|
+
|
|
145
|
+
export type Result = {
|
|
146
|
+
readonly ok: boolean;
|
|
147
|
+
/** One line per expectation the rules violate. */
|
|
148
|
+
readonly failures: ReadonlyArray<string>;
|
|
149
|
+
};
|
|
150
|
+
|
|
151
|
+
/** Replays the oracle's timeline against compiled rules; a compile error is a failure. */
|
|
152
|
+
export const replay = (
|
|
153
|
+
source: string,
|
|
154
|
+
{ createdAt, steps }: { createdAt: number; steps: ReadonlyArray<Step> },
|
|
155
|
+
): Result => {
|
|
156
|
+
let rules: GoalRules.GoalRules;
|
|
157
|
+
try {
|
|
158
|
+
rules = GoalRules.make({ source, createdAt });
|
|
159
|
+
} catch (error) {
|
|
160
|
+
if (error instanceof Compiler.CompileError) {
|
|
161
|
+
return { ok: false, failures: error.diagnostics.map(Compiler.formatDiagnostic) };
|
|
162
|
+
}
|
|
163
|
+
throw error;
|
|
164
|
+
}
|
|
165
|
+
const failures: string[] = [];
|
|
166
|
+
steps.forEach((step, index) => {
|
|
167
|
+
const offset = Builtins.parseDuration(step.after) ?? 0;
|
|
168
|
+
const saidAt = new Date(createdAt + offset).toISOString();
|
|
169
|
+
const { wakes, achieved } = rules.update({
|
|
170
|
+
at: createdAt + offset,
|
|
171
|
+
facts: step.says.map((statement, position) => toFact(statement, `oracle-${index}-${position}`, saidAt)),
|
|
172
|
+
});
|
|
173
|
+
const label = `step ${index + 1} (${step.note ?? step.says.map(({ quote }) => quote).join(' / ')})`;
|
|
174
|
+
if (wakes.length > 0 !== step.wake) {
|
|
175
|
+
failures.push(`${label}: wake=${wakes.length > 0}, expected ${step.wake}`);
|
|
176
|
+
}
|
|
177
|
+
if (step.achieved !== undefined && achieved !== step.achieved) {
|
|
178
|
+
failures.push(`${label}: achieved=${achieved}, expected ${step.achieved}`);
|
|
179
|
+
}
|
|
180
|
+
});
|
|
181
|
+
return { ok: failures.length === 0, failures };
|
|
182
|
+
};
|
package/src/index.ts
CHANGED
|
@@ -6,5 +6,7 @@ export * as Builtins from './Builtins.ts';
|
|
|
6
6
|
export * as CompilePrompt from './CompilePrompt.ts';
|
|
7
7
|
export * as Compiler from './Compiler.ts';
|
|
8
8
|
export * as Encoding from './Encoding.ts';
|
|
9
|
+
export * as Evaluator from './Evaluator.ts';
|
|
9
10
|
export * as GoalRules from './GoalRules.ts';
|
|
11
|
+
export * as Oracle from './Oracle.ts';
|
|
10
12
|
export * as Vocabulary from './Vocabulary.ts';
|