@dxos/brain 0.13.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.
Files changed (39) hide show
  1. package/dist/lib/Builtins.mjs +4 -2
  2. package/dist/lib/Builtins.mjs.map +1 -1
  3. package/dist/lib/Encoding.mjs +12 -2
  4. package/dist/lib/Encoding.mjs.map +1 -1
  5. package/dist/lib/Evaluator.mjs +144 -0
  6. package/dist/lib/Evaluator.mjs.map +1 -0
  7. package/dist/lib/GoalRules.mjs +62 -4
  8. package/dist/lib/GoalRules.mjs.map +1 -1
  9. package/dist/lib/Oracle.mjs +169 -0
  10. package/dist/lib/Oracle.mjs.map +1 -0
  11. package/dist/lib/index.mjs +3 -1
  12. package/dist/types/src/Builtins.d.ts +2 -0
  13. package/dist/types/src/Builtins.d.ts.map +1 -1
  14. package/dist/types/src/Encoding.d.ts +4 -0
  15. package/dist/types/src/Encoding.d.ts.map +1 -1
  16. package/dist/types/src/Evaluator.d.ts +77 -0
  17. package/dist/types/src/Evaluator.d.ts.map +1 -0
  18. package/dist/types/src/Evaluator.test.d.ts +2 -0
  19. package/dist/types/src/Evaluator.test.d.ts.map +1 -0
  20. package/dist/types/src/GoalRules.d.ts +6 -0
  21. package/dist/types/src/GoalRules.d.ts.map +1 -1
  22. package/dist/types/src/Oracle.d.ts +126 -0
  23. package/dist/types/src/Oracle.d.ts.map +1 -0
  24. package/dist/types/src/Oracle.test.d.ts +2 -0
  25. package/dist/types/src/Oracle.test.d.ts.map +1 -0
  26. package/dist/types/src/index.d.ts +2 -0
  27. package/dist/types/src/index.d.ts.map +1 -1
  28. package/dist/types/tsconfig.tsbuildinfo +1 -1
  29. package/package.json +15 -5
  30. package/src/Builtins.ts +2 -1
  31. package/src/Encoding.test.ts +14 -0
  32. package/src/Encoding.ts +9 -0
  33. package/src/Evaluator.test.ts +158 -0
  34. package/src/Evaluator.ts +186 -0
  35. package/src/GoalRules.test.ts +8 -0
  36. package/src/GoalRules.ts +81 -4
  37. package/src/Oracle.test.ts +71 -0
  38. package/src/Oracle.ts +182 -0
  39. package/src/index.ts +2 -0
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';