@orkestrel/scaffold 0.0.123 → 0.0.125
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/agents/skills/orkestrel-publish/scripts/steps.js +523 -0
- package/dist/agents/skills/orkestrel-publish/scripts/wave.js +70 -11
- package/dist/bin/main.js +18 -18
- package/dist/bin/main.js.map +1 -1
- package/dist/host/agents/orchestration.md +5 -1
- package/dist/host/agents/platforms/windows.md +9 -1
- package/dist/host/agents/skills/orkestrel-dispatch/SKILL.md +1 -1
- package/dist/host/agents/skills/orkestrel-falsify/references/brief.md +1 -0
- package/dist/host/agents/skills/orkestrel-harden/references/methods.md +30 -2
- package/dist/host/agents/skills/orkestrel-parallel/SKILL.md +1 -0
- package/dist/host/agents/skills/orkestrel-parallel/references/t3.md +5 -1
- package/dist/host/agents/skills/orkestrel-publish/SKILL.md +1 -0
- package/dist/host/agents/skills/orkestrel-publish/references/release.md +2 -2
- package/dist/host/agents/skills/orkestrel-publish/references/wave.md +23 -6
- package/dist/host/agents/skills/orkestrel-publish/scripts/steps.ts +654 -0
- package/dist/host/agents/skills/orkestrel-publish/scripts/wave.ts +79 -14
- package/dist/host/claude/agents/orkestrel.md +45 -45
- package/dist/host/claude/rules/patterns.md +1 -1
- package/dist/host/claude/rules/portability.md +2 -0
- package/dist/host/claude/rules/quality.md +3 -1
- package/dist/host/claude/rules/tests.md +3 -1
- package/dist/host/guides/agent.md +349 -244
- package/dist/host/guides/brief.md +52 -48
- package/dist/host/guides/browser.md +2 -2
- package/dist/host/guides/contract.md +226 -104
- package/dist/host/guides/database.md +12 -12
- package/dist/host/guides/interpret.md +531 -155
- package/dist/host/guides/mcp.md +183 -61
- package/dist/host/guides/ndjson.md +47 -34
- package/dist/host/guides/ollama.md +123 -66
- package/dist/host/guides/program.md +117 -39
- package/dist/host/guides/qualifier.md +110 -59
- package/dist/host/guides/rater.md +85 -32
- package/dist/host/guides/reason.md +377 -114
- package/dist/host/guides/scaffold.md +20 -12
- package/dist/host/guides/study.md +580 -483
- package/dist/host/guides/tool.md +163 -58
- package/dist/host/guides/toolbox.md +159 -80
- package/dist/host/guides/workflow.md +44 -25
- package/dist/host/manifest.json +41 -35
- package/dist/src/core/index.cjs +17 -17
- package/dist/src/core/index.cjs.map +1 -1
- package/dist/src/core/index.js +17 -17
- package/dist/src/core/index.js.map +1 -1
- package/dist/src/server/index.cjs +23 -11
- package/dist/src/server/index.cjs.map +1 -1
- package/dist/src/server/index.d.cts +10 -6
- package/dist/src/server/index.d.ts +10 -6
- package/dist/src/server/index.js +23 -11
- package/dist/src/server/index.js.map +1 -1
- package/package.json +17 -17
|
@@ -11,8 +11,12 @@ Nothing here is an LLM, a provider, or an agent: the `prompt` a result carries i
|
|
|
11
11
|
an external model and is never consumed internally, and the reverse direction complements the
|
|
12
12
|
raters' `describe*` family rather than duplicating it. `normalize` applies contraction,
|
|
13
13
|
abbreviation, and correction substitutions; `extract` classifies intent without ever seeing a
|
|
14
|
-
recipe and
|
|
15
|
-
|
|
14
|
+
recipe and reads exact numeric values; `clarify` resolves same-domain carry-over and
|
|
15
|
+
dependency-ordered computed fields, then admits the subject they build through the recipe's
|
|
16
|
+
`shape`, which says what is required, what is optional, and what an optional field defaults
|
|
17
|
+
to. A subject the door refuses is no subject: `subject` stays absent and each refusal is an
|
|
18
|
+
`Ambiguity` carrying its fault, with the question from the shape's `description`. Every
|
|
19
|
+
discriminant names its axis rather
|
|
16
20
|
than `kind` or `type`: `stage` splits the pipeline phases, `category` splits provenance, and
|
|
17
21
|
`code` splits coded errors. Source: [`src/core`](../src/core). Surfaced through the
|
|
18
22
|
`@src/core` barrel.
|
|
@@ -25,6 +29,7 @@ Add a recipe, interpret text through the normalize, extract, clarify, format, an
|
|
|
25
29
|
pipeline, then render the result back to prose:
|
|
26
30
|
|
|
27
31
|
```ts
|
|
32
|
+
import { numberShape, objectShape } from '@orkestrel/contract'
|
|
28
33
|
import { createExtractor, createInterpret } from '@orkestrel/interpret'
|
|
29
34
|
import {
|
|
30
35
|
createFactorGroup,
|
|
@@ -44,7 +49,7 @@ const interpret = createInterpret({
|
|
|
44
49
|
domain: 'arithmetic',
|
|
45
50
|
intents: ['calculate'],
|
|
46
51
|
mappings: [{ entity: 'value', aliases: [], field: 'value' }],
|
|
47
|
-
|
|
52
|
+
shape: objectShape({ value: numberShape() }),
|
|
48
53
|
computations: [],
|
|
49
54
|
definition: createQuantitativeDefinition('t1', 'Arithmetic', [
|
|
50
55
|
createFactorGroup('total', 'sum', [createFieldFactor('value', 'value')]),
|
|
@@ -53,7 +58,7 @@ const interpret = createInterpret({
|
|
|
53
58
|
],
|
|
54
59
|
})
|
|
55
60
|
|
|
56
|
-
const result = interpret.interpret('calculate arithmetic 42')
|
|
61
|
+
const result = interpret.interpret('calculate arithmetic value 42')
|
|
57
62
|
result.subject // { value: 42 }
|
|
58
63
|
result.ambiguities // []
|
|
59
64
|
result.failures // []
|
|
@@ -69,89 +74,391 @@ non-match, and a thrown stage, each yield a visible incomplete `Interpretation`
|
|
|
69
74
|
throwing, and never an arbitrary fallback recipe. An interpretation is complete when
|
|
70
75
|
`ambiguities` and `failures` are both empty; no stored flag repeats that fact.
|
|
71
76
|
|
|
77
|
+
### Reading a recipe's shape
|
|
78
|
+
|
|
79
|
+
`Recipe.shape` is the generated subject's shape, read at the door after clarify and
|
|
80
|
+
computations. A required field absent is a question; an optional field with a default is
|
|
81
|
+
filled, and `defaulted` lists what the door filled; a lossless repair, a number on a string
|
|
82
|
+
field for one, is accepted and listed in `repairs`; anything else the door refuses is a
|
|
83
|
+
question too, and it blocks whether or not the field is required. A question carries the
|
|
84
|
+
`fault` it came from.
|
|
85
|
+
|
|
86
|
+
```ts
|
|
87
|
+
import { numberShape, objectShape, optionalShape } from '@orkestrel/contract'
|
|
88
|
+
import { createExtractor, createInterpret } from '@orkestrel/interpret'
|
|
89
|
+
import { createLogicalDefinition } from '@orkestrel/reason'
|
|
90
|
+
|
|
91
|
+
const interpret = createInterpret({
|
|
92
|
+
extractor: createExtractor({
|
|
93
|
+
actions: { check: 'check' },
|
|
94
|
+
domains: { loans: ['loan'] },
|
|
95
|
+
}),
|
|
96
|
+
recipes: [
|
|
97
|
+
{
|
|
98
|
+
id: 'r',
|
|
99
|
+
name: 'Loan',
|
|
100
|
+
domain: 'loans',
|
|
101
|
+
intents: ['check'],
|
|
102
|
+
mappings: [{ entity: 'age', aliases: [], field: 'age' }],
|
|
103
|
+
computations: [],
|
|
104
|
+
definition: createLogicalDefinition('r', 'Loan', []),
|
|
105
|
+
shape: objectShape({
|
|
106
|
+
age: numberShape({ description: 'How old are you?' }),
|
|
107
|
+
term: optionalShape(numberShape(), { default: 12 }),
|
|
108
|
+
}),
|
|
109
|
+
},
|
|
110
|
+
],
|
|
111
|
+
})
|
|
112
|
+
|
|
113
|
+
const asked = interpret.interpret('check loan')
|
|
114
|
+
asked.subject // undefined
|
|
115
|
+
asked.ambiguities[0]?.question // 'How old are you?'
|
|
116
|
+
asked.ambiguities[0]?.fault // { reason: 'missing', path: ['age'], expected: 'number' }
|
|
117
|
+
|
|
118
|
+
const read = interpret.interpret('check loan age 30')
|
|
119
|
+
read.subject // { age: 30, term: 12 }
|
|
120
|
+
read.defaulted // [['term']]
|
|
121
|
+
interpret.destroy()
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
A computation may read a default, and a computed value stands over one. A computed field is
|
|
125
|
+
trusted no more than the least of what it read.
|
|
126
|
+
|
|
127
|
+
Choosing a recipe asks rather than picks: a text naming two domains or two actions names
|
|
128
|
+
neither, a recipe needs its own domain named, because an action alone names no recipe, and a tie
|
|
129
|
+
for the best score matches nothing. Each of these reaches the `NO_RECIPE` question. A result names
|
|
130
|
+
the recipe it matched in `recipe` and `version`.
|
|
131
|
+
|
|
132
|
+
A number fills a field only through an anchor: the mapping's entity name or an alias, matched
|
|
133
|
+
exactly against a token or an in-order sequence of tokens in the same clause. Fuzzy aliases claim nothing.
|
|
134
|
+
For single-value assignment, conflict detection groups all mappings by their target field.
|
|
135
|
+
Each mapping's selected anchor always counts as a mention. Among overlapping entity and alias
|
|
136
|
+
spans, it keeps the later start, then the longer span at equal starts. If the kept span links
|
|
137
|
+
no number, the overlapping span it displaced speaks instead; a silent span hides nothing.
|
|
138
|
+
A span wholly inside another field's longer declared anchor contributes no mention unless
|
|
139
|
+
it is a selected anchor. That ownership applies only when the longer anchor lies within one
|
|
140
|
+
clause. A declared phrase owns its words: `training hours` does not contribute an `hours`
|
|
141
|
+
mention to another field when that field selects the later `hours` in `training hours 30. hours 40`.
|
|
142
|
+
Every nearest linked number is a candidate, including every number in a tie. A negated clause
|
|
143
|
+
or an unlinked span contributes none. Each numeric occurrence counts once, even when several
|
|
144
|
+
spans reach it. Equal readable values count as one value; an occurrence without a value
|
|
145
|
+
differs from every other occurrence, never from itself.
|
|
146
|
+
Distinct values withhold every mapping on that field and record `anchor-conflict` with the field.
|
|
147
|
+
First-reason-wins still applies: an earlier refusal keeps its reason, and correction-marked
|
|
148
|
+
candidates keep `correction` under an explicit correction cue. Otherwise the last anchor
|
|
149
|
+
remains selected, even when it has no number; an earlier occurrence supplies no fallback.
|
|
150
|
+
A lone array mapping is exempt even without a claim. A non-lone array mapping still receives
|
|
151
|
+
one anchored value and participates in conflict detection. Another field can claim a refused
|
|
152
|
+
candidate through its own anchor; the withheld mapping still participates in rivalry.
|
|
153
|
+
This deliberately costs a question on a revision such as `hours 30. now hours 40`, which
|
|
154
|
+
supplies no value instead of choosing the revision. Only whitespace,
|
|
155
|
+
`is`, `of`, `at`, `to`, `=`, and `:` may link the spans; an article also links when the number
|
|
156
|
+
follows the anchor. A preceding `$125,000 a year` therefore supplies no value for `year`.
|
|
157
|
+
Negation anywhere in the clause blocks its claims. No other number may sit as close, and no
|
|
158
|
+
other anchor may sit closer. Other intervening words and distance across clauses are guesses, so
|
|
159
|
+
they fill nothing. A value read below the floor asks, whether or not the field is required,
|
|
160
|
+
because it is evidence a value was stated. A mapped field left to a default or a prior turn
|
|
161
|
+
asks too while a number nobody claimed could be its value, with those numbers as `candidates`.
|
|
162
|
+
A number `scanNumbers` marks foreign still participates in anchor-conflict detection; excluding
|
|
163
|
+
it would guess its intended role. The clarifier otherwise sets unclaimed foreign numbers aside.
|
|
164
|
+
A host may supply an entity with provenance `proposed` after checking a reader's proposal.
|
|
165
|
+
The clarifier treats it as stated, like `extracted` and `computed`, so an unclaimed number
|
|
166
|
+
does not by itself cast doubt on that field. Confidence and shape checks still apply.
|
|
167
|
+
A `default` value still asks when an unclaimed number could be its value. This package
|
|
168
|
+
does not produce `proposed` entities itself.
|
|
169
|
+
Every one of these blocks the subject, and what a blocked turn read stays in `entities`, so the
|
|
170
|
+
next turn can carry it when history is enabled: only what was stated carries, because a computed or defaulted value is
|
|
171
|
+
worked out again, and only within one recipe. Only a mapping whose field's shape is an array collects many numbers, and collection requires
|
|
172
|
+
an anchor. An unreadable occurrence asks instead of supplying digit fragments or an empty array.
|
|
173
|
+
|
|
174
|
+
A tied anchor still contests both adjacent numbers, so another anchor cannot take one
|
|
175
|
+
merely because the tied anchor could not choose. A number's next neighbor must be the end
|
|
176
|
+
of the text, an attached sentence end (`.`, `!`, `?`, or `;`), a whole declared anchor, or a
|
|
177
|
+
conditional link. Sentence punctuation must touch the number and precede whitespace or the
|
|
178
|
+
text's end: `years 3.` and `years 3. Next` claim, while `amount 3 . 000 . 000` asks.
|
|
179
|
+
A newline alone does not end a sentence. Every other neighbor asks, including words in any script, punctuation,
|
|
180
|
+
and adjacent numbers. This applies to scalar claims and array collection.
|
|
181
|
+
The links `is`, `of`, `at`, `to`, `a`, `an`, `the`, `and`, and `with` all require a declared
|
|
182
|
+
anchor next, allowing one article (`a`, `an`, or `the`) between. An alias must match its
|
|
183
|
+
whole token sequence: `monthly payments` does not stand for `monthly income`. A token also matches
|
|
184
|
+
a declared word with its trailing periods removed, for a field's anchor and for an intent's action or
|
|
185
|
+
domain keyword: `for 2 nights.` binds nights, and `I need a table.` names the domain `table` names.
|
|
186
|
+
A word declared with its own period, such as `st.`, still matches itself, and `St.` ties a domain
|
|
187
|
+
holding `st.` with one holding `st`. This admits a word and leaves sentences as written, so
|
|
188
|
+
`for 2 nights. 3 people` binds both, where `for 2 nights 3 people` ties. A numeric target asks,
|
|
189
|
+
whether written in digits or words: `amount 5 of 3000000`, `amount 3 and 5`,
|
|
190
|
+
`amount 50000 and 60000`, `years 3 and 6 months`, and `amount 50000 with a 20000 deposit`
|
|
191
|
+
hold no value for that field. `3 and a half` remains one numeric form, so it meets no link check.
|
|
192
|
+
Array collection follows the same rule: `value 10 and 20 and 30` asks, while
|
|
193
|
+
`value 10 and value 20 and value 30` collects when `value` is the declared array anchor.
|
|
194
|
+
Thus `amount 50000 and income 120000` holds both fields, while `amount 50000 and up`
|
|
195
|
+
asks for amount and retains no amount value. `amount 50000 income 120000` asks for both
|
|
196
|
+
fields with no entity: the unchanged tie rule records `anchor-tie` for each occurrence.
|
|
197
|
+
|
|
198
|
+
Both sides are read when a number precedes its anchor. A preceding lone punctuation token,
|
|
199
|
+
another number, or the reader's existing `hedged` flag refuses that backward claim with
|
|
200
|
+
`preceding-word` and the immediate predecessor in `word`. Thus `1 – 3 years`, `150 90000 amount`,
|
|
201
|
+
and `under 2 years` ask without holding a value for that field. The preceding-number check
|
|
202
|
+
stops at trailing sentence punctuation: `income 120000, 3 years` keeps years 3.
|
|
203
|
+
`3 years`, `for 3 years`, and `have 3 years` also keep 3. No hedge vocabulary is added.
|
|
204
|
+
An anchor's trailing colon permits only a forward claim. Consequently
|
|
205
|
+
`amount: 50000 income: 120000 years: 3` holds those three values, including when written
|
|
206
|
+
on separate lines before normalization. Its comma-separated form reads the same.
|
|
207
|
+
The glued `amount:50000` remains an undeclared numeric token.
|
|
208
|
+
|
|
209
|
+
A comma admits unless a number follows it: `value 25, now` and
|
|
210
|
+
`amount 50000, income 120000` still claim, whereas `amount 3, 000, 000` asks.
|
|
211
|
+
Known limits retained by the comma admission: `years 3, months` holds 3 and
|
|
212
|
+
`amount 50000, and up` holds 50000.
|
|
213
|
+
|
|
214
|
+
Every maximal nonspace run holding a digit, less trailing sentence punctuation, must match
|
|
215
|
+
a declared numeric form whole. The forms are unsigned digits or comma groups, optionally
|
|
216
|
+
with a decimal fraction, or a leading-dot decimal; an optional dollar prefix (`$`, `US$`,
|
|
217
|
+
or `USD`, allowing one space); and an optional `%`, `k`, `mil`, `mill`, `million`, `thousand`,
|
|
218
|
+
`grand`, or `ish` suffix. With a dollar prefix, `m`, `mm`, `b`, and `bn` also admit.
|
|
219
|
+
Letters match without case. A currency prefix can include its one separating space.
|
|
220
|
+
That prefix must pass the same admission even inside an earlier token: `amount:€ 50000`
|
|
221
|
+
and `amount=€ 50000` refuse the currency-prefixed number.
|
|
222
|
+
Other digit-holding forms, including `3_000_000`, `3+`, `~3`, ordinals, numeric dates,
|
|
223
|
+
times, and hyphenated phone numbers, carry `unreadable: 'undeclared'` with no `value`.
|
|
224
|
+
Their span and `raw` cover the whole rejected token. `401k` is the declared `k` suffix and
|
|
225
|
+
reads 401000; the reader no longer exempts that token as a plan number.
|
|
226
|
+
|
|
227
|
+
Whole-token admission precedes exact reading: ambiguous grouping such as `3.000` and
|
|
228
|
+
space-grouped `3 000 000`, ranges, and inexact arithmetic still refuse. Word forms retain
|
|
229
|
+
their existing grammar, including separated scales such as `3 mn`. An unsupported scale
|
|
230
|
+
word is left after the numeric span and refuses assignment by neighbor admission; it needs
|
|
231
|
+
no scale refusal list. `WHOLE_NUMBER_FORMS` in `tests/setup.ts` pins exact readings and
|
|
232
|
+
refusals, beside seeded tables of admitted tokens, undeclared tokens, and neighbors.
|
|
233
|
+
`3 and a half` reads exactly 3.5, and `six and a half` reads exactly 6.5.
|
|
234
|
+
A fraction joins only a plain number. `3 million and a half`, `$3m and a half`,
|
|
235
|
+
`three million and a half`, `3 million and a quarter`, and `3k and a half` are unreadable.
|
|
236
|
+
The numeric phrase in `3 and a half months` still reads 3.5. In `years 3 and a half months`,
|
|
237
|
+
the following-word test refuses the assignment because `months` is neither an anchor nor a link.
|
|
238
|
+
|
|
239
|
+
An explicit correction in the text makes occurrences marked `suspect` or `changed` ask:
|
|
240
|
+
`sorry` (except `sorry to/for`), `hang on`, `used to be`, `was/were going to be`, and `wait` (except `wait to`).
|
|
241
|
+
Assignment never substitutes a rival value. Ordinary `now` statements do not trigger this
|
|
242
|
+
correction refusal; they can still trigger `anchor-conflict` when the same field names distinct
|
|
243
|
+
values. An array collection refuses when any occurrence meets the correction rule.
|
|
244
|
+
|
|
245
|
+
`add` and the `recipes` option refuse with `InterpretError('DEFINITION')` a recipe that is malformed,
|
|
246
|
+
whose shape does not compile, stand, or declare a field it maps or computes, with a required field
|
|
247
|
+
nothing fills, or with a computation reading a variable nothing fills.
|
|
248
|
+
|
|
249
|
+
An `Interpretation` crosses a boundary as `projectInterpretation`, which
|
|
250
|
+
`interpretationContract` admits. A recipe crosses on `createRecipeContract().is`, never `parse`. `is` reads a nested `shape` as any
|
|
251
|
+
JSON value and the guard reads it as a shape, so `shape: 42` passes `is` and `isRecipe` refuses it:
|
|
252
|
+
a recipe crossing a boundary goes through the guard as well.
|
|
253
|
+
|
|
254
|
+
### Reading numbers
|
|
255
|
+
|
|
256
|
+
`scanNumbers` reads every number in a text exactly, or says why it cannot, with its span and what
|
|
257
|
+
the words around it say. `extractNumbers` reads digits only; this also reads shorthand and word
|
|
258
|
+
forms. It never assigns a number to a field, so read it beside a recipe, for a check that a
|
|
259
|
+
proposed value appears in the text, or to set aside a number that belongs to no quantity.
|
|
260
|
+
|
|
261
|
+
```ts
|
|
262
|
+
import { scanNumbers } from '@orkestrel/interpret'
|
|
263
|
+
|
|
264
|
+
scanNumbers('$75k at 6%').map((number) => number.value) // [75000, 6]
|
|
265
|
+
scanNumbers('three hundred thousand dollars')[0]?.money // true
|
|
266
|
+
scanNumbers('twelve fifty')[0]?.unreadable // 'spoken'
|
|
267
|
+
scanNumbers('12 to 18')[0]?.unreadable // 'range'
|
|
268
|
+
scanNumbers('call 555-0142')[0]?.unreadable // 'undeclared'
|
|
269
|
+
scanNumbers('in 2019')[0]?.foreign // 'year'
|
|
270
|
+
scanNumbers('about 40 hours')[0]?.hedged // true
|
|
271
|
+
scanNumbers('about 40 hours')[0]?.unit // 'hour'
|
|
272
|
+
```
|
|
273
|
+
|
|
274
|
+
A value is present when the digits or words read to a number. Read it with `unreadable`, which
|
|
275
|
+
says the reading is not exact, and `foreign`, which says it is no quantity. A value past what a
|
|
276
|
+
number holds exactly reads as `unreadable: 'overflow'`, with no value. `readNumbersContract` is
|
|
277
|
+
the contract of what it returns. Exponent notation is unreadable shorthand, unsupported scale
|
|
278
|
+
compositions are unreadable joins, and a scaled value changed by six-decimal rounding carries
|
|
279
|
+
`unreadable: 'precision'`. Scaling retains its unrounded product.
|
|
280
|
+
|
|
281
|
+
### Refusal evidence
|
|
282
|
+
|
|
283
|
+
`compileEntities` is the composition entry for assignment with evidence. `assignEntities`
|
|
284
|
+
returns only its entities. `Interpretation.refusals` carries the same optional record:
|
|
285
|
+
at most `NUMBER_REFUSAL_LIMIT` (32) items, with the remaining count in `omitted`.
|
|
286
|
+
It is absent when no occurrence was refused. Records follow occurrence order, retain
|
|
287
|
+
the first decision for each occurrence, and exclude every occurrence eventually claimed.
|
|
288
|
+
Only retained records render their `text` and following `word` through the contract's
|
|
289
|
+
bounded `preview`; strings therefore include quotes.
|
|
290
|
+
|
|
291
|
+
Positions are UTF-16 offsets into `Interpretation.normalized`, start inclusive and end
|
|
292
|
+
exclusive. Stage compositions obtain that text from `createNormalizer().normalize(text).text`
|
|
293
|
+
and pass it to both `scanNumbers` and `compileEntities`. No original-input offset map is
|
|
294
|
+
provided. The compiler produces ordered spans. The shape and guard validate nonnegative
|
|
295
|
+
integer positions structurally and accept reversed pairs.
|
|
296
|
+
|
|
297
|
+
The reasons record existing decisions: `preceding-word` for a backward claim refused by
|
|
298
|
+
preceding punctuation, another number, or a hedge flag; `following-word` for a failed following-word
|
|
299
|
+
anchor/link check; `unreadable` for a selected occurrence without an exact value or with
|
|
300
|
+
an unreadable mark; `anchor-tie` for equally near numbers or competing nearest anchors;
|
|
301
|
+
`anchor-conflict` for distinct values linked to a field's retained anchor spans, ties included;
|
|
302
|
+
`correction` for a suspect or changed occurrence under an explicit correction cue;
|
|
303
|
+
`negation` for occurrences in a negated anchor clause; `unanchored` when compilation
|
|
304
|
+
ends with neither a claim nor an earlier refusal; and `collection` for the other members
|
|
305
|
+
of a sole array mapping withheld after one member fails. The unreadable check carries
|
|
306
|
+
its existing `unreadable` detail; both neighbor checks carry `word`.
|
|
307
|
+
A decision carries `field` only when its mapping is available. Competing anchors and
|
|
308
|
+
unanchored occurrences have no unique field. No intended field or deeper linguistic
|
|
309
|
+
explanation is inferred.
|
|
310
|
+
|
|
311
|
+
Refusals do not change entities, questions, subjects, or the digest. The digest excludes
|
|
312
|
+
the record, so two results may share a digest while their refusal records differ.
|
|
313
|
+
The extraction stage now returns exact reader values, including word forms, and omits
|
|
314
|
+
unreadable occurrences: `3 000 000` contributes no fragments. This also changes direct
|
|
315
|
+
`Extractor.extract` callers. The separately published `extractNumbers` remains digit-only.
|
|
316
|
+
|
|
317
|
+
| Name | Kind | Signature | Summary |
|
|
318
|
+
| ------------------------ | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
|
|
319
|
+
| `NumberRefusalReason` | type | `'preceding-word' \| 'following-word' \| 'unreadable' \| 'anchor-tie' \| 'anchor-conflict' \| 'correction' \| 'negation' \| 'unanchored' \| 'collection'` | Names the decision that first prevented a numeric occurrence from being assigned. |
|
|
320
|
+
| `NumberRefusal` | interface | `{ text, reason, unreadable?, word?, field? }` | Represents one refused numeric occurrence, its normalized position, and its first decision. |
|
|
321
|
+
| `NumberRefusals` | interface | `{ items, omitted }` | Represents bounded refusal records and the count omitted after the published cap. |
|
|
322
|
+
| `EntityCompilation` | interface | `{ entities, refusals? }` | Represents assigned entities and any bounded evidence of refused numeric occurrences. |
|
|
323
|
+
| `NumberRefusalDecision` | interface | `{ reason, word?, field? }` | Represents the first refusal decision retained before bounded record construction. |
|
|
324
|
+
| `AnchorRefusalHandler` | type | `(index: number, reason: 'negation' \| 'anchor-tie') => void` | Observes the input occurrence index and the refusal decided by an anchor check. |
|
|
325
|
+
| `NUMBER_REFUSAL_LIMIT` | const | `32` | Limits the refusal records carried by one compilation or interpretation to 32. |
|
|
326
|
+
| `NUMBER_REFUSAL_REASONS` | const | `readonly NumberRefusalReason[]` | Lists the frozen vocabulary of first refusal decisions described by `NumberRefusalReason`. |
|
|
327
|
+
| `compileEntities` | function | `(numbers: readonly ReadNumber[], mappings: readonly EntityMapping[], text: string, shape: ContractShape) => EntityCompilation` | Compiles exact reader occurrences into entities and bounded refusal evidence. |
|
|
328
|
+
| `isNumberRefusal` | function | `(value: unknown) => value is NumberRefusal` | Determines whether a value is a structurally valid refusal record. |
|
|
329
|
+
| `isNumberRefusals` | function | `(value: unknown) => value is NumberRefusals` | Determines whether a value holds bounded refusal items and a valid omitted count. |
|
|
330
|
+
| `numberRefusalShape` | const | `ContractShape` | Describes one refusal record with structurally valid, unordered nonnegative integer positions. |
|
|
331
|
+
| `numberRefusalsShape` | const | `ContractShape` | Describes bounded refusal items and a nonnegative integer omitted count. |
|
|
332
|
+
|
|
333
|
+
```ts
|
|
334
|
+
import { numberShape, objectShape } from '@orkestrel/contract'
|
|
335
|
+
import { compileEntities, createNormalizer, scanNumbers } from '@orkestrel/interpret'
|
|
336
|
+
|
|
337
|
+
const text = createNormalizer().normalize('years 3 months').text
|
|
338
|
+
const result = compileEntities(
|
|
339
|
+
scanNumbers(text),
|
|
340
|
+
[{ entity: 'years', aliases: [], field: 'years' }],
|
|
341
|
+
text,
|
|
342
|
+
objectShape({ years: numberShape() }),
|
|
343
|
+
)
|
|
344
|
+
result.entities // []
|
|
345
|
+
result.refusals?.items[0]?.reason // 'following-word'
|
|
346
|
+
result.refusals?.items[0]?.start // 6
|
|
347
|
+
|
|
348
|
+
const range = '1 – 3 years'
|
|
349
|
+
const refused = compileEntities(
|
|
350
|
+
scanNumbers(range),
|
|
351
|
+
[{ entity: 'years', aliases: [], field: 'years' }],
|
|
352
|
+
range,
|
|
353
|
+
objectShape({ years: numberShape() }),
|
|
354
|
+
)
|
|
355
|
+
refused.entities // []
|
|
356
|
+
refused.refusals?.items[1]?.reason // 'preceding-word'
|
|
357
|
+
refused.refusals?.items[1]?.word // '"–"'
|
|
358
|
+
```
|
|
359
|
+
|
|
72
360
|
### Types
|
|
73
361
|
|
|
74
|
-
| Name | Kind | Signature
|
|
75
|
-
| ---------------------------- | --------- |
|
|
76
|
-
| `
|
|
77
|
-
| `
|
|
78
|
-
| `
|
|
79
|
-
| `
|
|
80
|
-
| `
|
|
81
|
-
| `
|
|
82
|
-
| `
|
|
83
|
-
| `
|
|
84
|
-
| `
|
|
85
|
-
| `
|
|
86
|
-
| `
|
|
87
|
-
| `
|
|
88
|
-
| `
|
|
89
|
-
| `
|
|
90
|
-
| `
|
|
91
|
-
| `
|
|
92
|
-
| `
|
|
93
|
-
| `
|
|
94
|
-
| `
|
|
95
|
-
| `
|
|
96
|
-
| `
|
|
97
|
-
| `
|
|
98
|
-
| `
|
|
99
|
-
| `
|
|
100
|
-
| `
|
|
101
|
-
| `
|
|
102
|
-
| `
|
|
103
|
-
| `
|
|
104
|
-
| `
|
|
105
|
-
| `
|
|
106
|
-
| `
|
|
107
|
-
| `
|
|
108
|
-
| `
|
|
109
|
-
| `
|
|
110
|
-
| `
|
|
111
|
-
| `
|
|
112
|
-
| `
|
|
113
|
-
| `
|
|
114
|
-
| `
|
|
115
|
-
| `
|
|
116
|
-
| `
|
|
117
|
-
| `
|
|
118
|
-
| `
|
|
119
|
-
| `
|
|
120
|
-
| `
|
|
121
|
-
| `
|
|
122
|
-
| `
|
|
123
|
-
| `
|
|
124
|
-
| `
|
|
125
|
-
| `
|
|
126
|
-
| `
|
|
127
|
-
| `
|
|
128
|
-
| `
|
|
129
|
-
| `
|
|
130
|
-
| `
|
|
131
|
-
| `
|
|
132
|
-
| `
|
|
133
|
-
| `
|
|
362
|
+
| Name | Kind | Signature | Summary |
|
|
363
|
+
| ---------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
364
|
+
| `ReaderTokenInterface` | interface | `{ form, raw, lower, canon, start, marks, mark() }` | Declares one scanned token the number reader's passes mark as they walk a sentence. |
|
|
365
|
+
| `WordNumberResult` | interface | `{ token, next }` | Represents a written-out number, as the token it reads to and where the walk resumes. |
|
|
366
|
+
| `CardinalResult` | interface | `{ value, part, next, last, unreadable?, money }` | Represents a written-out cardinal as far as it has been read. |
|
|
367
|
+
| `ReaderMarks` | interface | `{ index, glued? }` | Represents what the number reader's passes have marked on one token so far. |
|
|
368
|
+
| `ReaderTokenForm` | type | `'number' \| 'word' \| 'mark'` | Names what one scanned token is to `NumberReader`: a number, a word, or a mark. |
|
|
369
|
+
| `ReadNumber` | interface | `{ raw, value?, unreadable?, foreign?, money?, percent?, scaled?, word?, hedged?, suspect?, changed?, composite?, loose?, magnitude?, weak?, tail?, yearish?, phone?, reference?, unit?, sentence, segment }` | Represents one number read from a text, with its span and what the words around it say. |
|
|
370
|
+
| `NumberForeign` | type | `'plan' \| 'phone' \| 'date' \| 'time' \| 'identifier' \| 'ordinal' \| 'list' \| 'age' \| 'past' \| 'period' \| 'reference' \| 'zip' \| 'address' \| 'year'` | Names what a number that belongs to no quantity is: a year, a date, a time, a reference, and so on. |
|
|
371
|
+
| `NumberUnreadable` | type | `'undeclared' \| 'fraction' \| 'foreign currency' \| 'grouping' \| 'signed' \| 'shorthand' \| 'spoken' \| 'joined' \| 'frequency' \| 'loose' \| 'range' \| 'dimensions' \| 'overflow' \| 'precision'` | Names why a number's value cannot be read exactly. |
|
|
372
|
+
| `TextSpan` | interface | `{ start, end }` | Represents where something sits in a text: `start` inclusive, `end` exclusive. |
|
|
373
|
+
| `AnchorPosition` | interface | `{ index }` | Represents a numeric span's input position in a prepared anchor lookup. |
|
|
374
|
+
| `AnchorCandidate` | interface | `{ index, gap }` | Represents a linked number and its distance from an anchor. |
|
|
375
|
+
| `AnchorLookup` | interface | `{ text, numbers, starts, ends, breaks, negations }` | Holds clause boundaries and ordered numeric spans for one compilation. |
|
|
376
|
+
| `AnchorProbe` | interface | `{ clause, negated, candidates }` | Represents a span's clause and nearest linked candidates, including ties. |
|
|
377
|
+
| `EntityAnchor` | interface | `{ mapping, position, end, confidence, detail, anchors }` | Holds a mapping's occurrences and its selected assignment anchor. |
|
|
378
|
+
| `ShapeDefault` | interface | `{ field, value }` | Represents one default a `Recipe`'s `shape` holds, by the field it fills. |
|
|
379
|
+
| `ProvenanceCategory` | type | `'extracted' \| 'proposed' \| 'carried' \| 'default' \| 'computed' \| 'subject'` | Names how one `FieldMapping` or `Entity` value was obtained. |
|
|
380
|
+
| `InterpretStage` | type | `'normalize' \| 'extract' \| 'clarify' \| 'format' \| 'generate'` | Names the fixed pipeline phases an `InterpretInterface#interpret` run produces one `StageRecord` for, in order. |
|
|
381
|
+
| `InterpretErrorCode` | type | `'TEXT_LIMIT' \| 'NORMALIZE_FAILED' \| 'EXTRACT_FAILED' \| 'CLARIFY_FAILED' \| 'FORMAT_FAILED' \| 'GENERATE_FAILED' \| 'NO_RECIPE' \| 'LOW_CONFIDENCE' \| 'DEFINITION' \| 'DESTROYED'` | Names the coded misuse or failure conditions thrown as an `InterpretError` or carried on a `StageFailure`. |
|
|
382
|
+
| `EntityMapping` | interface | `{ entity, aliases, field }` | Represents one entity-extraction rule inside a `Recipe`: which literal aliases identify a value, and which subject field it lands on. |
|
|
383
|
+
| `ComputedField` | interface | `{ field, expression }` | Represents a declaratively computed field: evaluate `expression` against the entities already resolved for this interpretation, and land the result on `field`. |
|
|
384
|
+
| `Recipe` | interface | `{ id, name, domain, intents, mappings, computations, definition, shape }` | Represents a named, versionable interpretation recipe: which intents it answers, how to mine entities for it, its computed fields, the shape of what it produces, and the reasons `Definition` it ultimately produces a `Subject` for. |
|
|
385
|
+
| `Provenance` | interface | `{ category, detail? }` | Describes how one value landed — its origin category plus an optional strategy detail. |
|
|
386
|
+
| `Intent` | interface | `{ action?, domain?, confidence }` | Represents the classified action + domain for one interpretation, with a combined confidence. |
|
|
387
|
+
| `Entity` | interface | `{ name, field?, value, provenance, confidence }` | Represents one value assigned to a recipe's entity mapping, with its provenance and confidence. |
|
|
388
|
+
| `Ambiguity` | interface | `{ field, question, candidates, required, fault? }` | Represents an unresolved field surfaced as a human-readable question, never bare prose. |
|
|
389
|
+
| `FieldMapping` | interface | `{ field, entity?, value, provenance, confidence }` | Represents one audited field of the built subject — its resolved value, provenance, and confidence. |
|
|
390
|
+
| `TextChange` | interface | `{ from, to }` | Represents one normalization substitution applied to the raw text. |
|
|
391
|
+
| `StageRecord` | interface | `{ stage, input, output, failed, error? }` | Represents a structured input/output snapshot of one pipeline phase. |
|
|
392
|
+
| `StageFailure` | interface | `{ stage, code, message }` | Represents a visible marker for a stage that threw, carrying its coded reason. |
|
|
393
|
+
| `NormalizeResult` | interface | `{ text, changes }` | Represents the `Normalizer` stage's output: the cleaned text plus every substitution applied. |
|
|
394
|
+
| `ExtractResult` | interface | `{ intent, numbers }` | Represents the `Extractor` stage's output: intent classification plus exact reader values. |
|
|
395
|
+
| `ClarifyResult` | interface | `{ entities, ambiguities, repairs, defaulted }` | Represents the `Clarifier` stage's output: resolved entities plus any remaining ambiguities. |
|
|
396
|
+
| `FormatResult` | interface | `{ prompt }` | Represents the `Formatter` stage's output: the refined natural-language prompt. |
|
|
397
|
+
| `GenerateResult` | interface | `{ subject, definition, mappings, confidence }` | Represents the `Generator` stage's output: the built subject/definition pair plus its full field audit. |
|
|
398
|
+
| `Interpretation` | interface | `{ refusals?, text, normalized, intent, recipe?, version?, entities, subject?, definition?, mappings, ambiguities, repairs, defaulted, prompt, stages, failures, confidence, digest }` | Represents the full, replayable outcome of one `interpret()` call. |
|
|
399
|
+
| `RecipeRecord` | interface | `{ id, recipe, version, hash }` | Represents a versioned, content-hashed `Recipe` as held by a `RecipeManagerInterface`. |
|
|
400
|
+
| `SubjectRecord` | interface | `{ id, subject, version, hash }` | Represents a versioned, content-hashed `Subject` as held by a `SubjectManagerInterface`. |
|
|
401
|
+
| `DefinitionRecord` | interface | `{ id, definition, version, hash }` | Represents a versioned, content-hashed `Definition` as held by a `DefinitionManagerInterface`. |
|
|
402
|
+
| `InterpretEventMap` | type | `{ readonly interpret: readonly [result: Interpretation]; readonly add: readonly [recipeId: string]; readonly error: readonly [error: unknown]; readonly destroy: readonly []; }` | Represents the push observation surface of an `InterpretInterface`. |
|
|
403
|
+
| `RecordEventMap` | type | `{ readonly add: readonly [id: string]; readonly remove: readonly [id: string]; readonly destroy: readonly []; }` | Represents the push observation surface shared by every record registry — an id-keyed collection, so `add` and `remove` are the events (never ordered-list `append`/`prepend`). |
|
|
404
|
+
| `RecipeManagerEventMap` | type | `RecordEventMap` | Represents the push observation surface of a `RecipeManagerInterface`. |
|
|
405
|
+
| `SubjectManagerEventMap` | type | `RecordEventMap` | Represents the push observation surface of a `SubjectManagerInterface`, whose `add` carries the own-minted record id. |
|
|
406
|
+
| `DefinitionManagerEventMap` | type | `RecordEventMap` | Represents the push observation surface of a `DefinitionManagerInterface`. |
|
|
407
|
+
| `InterpretContextEventMap` | type | `{ readonly add: readonly [digest: string]; readonly clear: readonly []; readonly destroy: readonly []; }` | Represents the push observation surface of an `InterpretContextInterface`. |
|
|
408
|
+
| `NarratorFormatter` | type | `(value: unknown) => string` | Represents a pure formatting function for one lexicon `value()` unit. |
|
|
409
|
+
| `Lexicon` | interface | `{ phrases?, labels?, templates? }` | Represents caller-injected wording data for the reverse direction — mechanism, never policy. Every phrase, label, and template string a `Narrator` renders is data supplied here, never a core literal. |
|
|
410
|
+
| `NarratorOptions` | interface | `{ lexicon?, formatters? }` | Represents the options for `createNarrator` and the `Narrator` constructor. |
|
|
411
|
+
| `NormalizerOptions` | interface | `{ contractions?, abbreviations?, corrections? }` | Represents the options for `createNormalizer` and the `Normalizer` constructor. |
|
|
412
|
+
| `ExtractorOptions` | interface | `{ actions?, domains? }` | Represents the options for `createExtractor` and the `Extractor` constructor. |
|
|
413
|
+
| `ClarifierOptions` | interface | `{ floor?, narrator? }` | Represents the options for `createClarifier` and the `Clarifier` constructor. |
|
|
414
|
+
| `FormatterOptions` | interface | `{ verbs?, narrator? }` | Represents the options for `createFormatter` and the `Formatter` constructor. |
|
|
415
|
+
| `RecipeManagerOptions` | interface | `{ recipes?, on?, error? }` | Represents the options for `createRecipeManager` and the `RecipeManager` constructor — the initial seed collection. |
|
|
416
|
+
| `SubjectManagerOptions` | interface | `{ subjects?, on?, error? }` | Represents the options for `createSubjectManager` and the `SubjectManager` constructor — the initial seed collection. |
|
|
417
|
+
| `DefinitionManagerOptions` | interface | `{ definitions?, on?, error? }` | Represents the options for `createDefinitionManager` and the `DefinitionManager` constructor — the initial seed collection. |
|
|
418
|
+
| `RecordStamp` | interface | `{ id, version, hash }` | Represents the identity, version, and content hash a `RecordManagerInterface` derives for one record before its concrete shape is built. |
|
|
419
|
+
| `RecordFunction` | type | `(stamp: RecordStamp, value: TValue) => TRecord` | Builds one concrete record from the `RecordStamp` its registry derived and the value that record holds. |
|
|
420
|
+
| `RecordManagerOptions` | interface | `{ entity, on?, error? }` | Represents the options for the `RecordManager` constructor. |
|
|
421
|
+
| `RecordManagerInterface` | interface | `{ emitter, count, has(), record(), records(), add(), remove(), destroy() }` | Represents the shared registry engine every record manager composes — the `Map`, the content-hash and version rule, the batch `remove` overloads, and teardown. |
|
|
422
|
+
| `RecordOptions` | interface | `{ id? }` | Represents the per-call options for the record a manager's `add` mints. |
|
|
423
|
+
| `InterpretContextOptions` | interface | `{ session?, history?, on?, error? }` | Represents the options for `createInterpretContext` and the `InterpretContext` constructor. |
|
|
424
|
+
| `InterpretOptions` | interface | `{ recipes?, context?, normalizer?, extractor?, clarifier?, formatter?, generator?, floor?, history?, narrator?, on?, error? }` | Represents the options for `createInterpret` and the `Interpret` constructor. |
|
|
425
|
+
| `NormalizerInterface` | interface | `{ normalize() }` | Represents the `Normalizer` stage contract: raw text in, cleaned text + applied changes out. |
|
|
426
|
+
| `ExtractorInterface` | interface | `{ extract() }` | Represents the `Extractor` stage contract: recipe-agnostic intent classification and exact reader values. |
|
|
427
|
+
| `ClarifierInterface` | interface | `{ clarify() }` | Represents the `Clarifier` stage contract: resolve carry-over and computed fields against a set of already-assigned entities, surfacing ambiguities for anything required that stays unresolved. |
|
|
428
|
+
| `FormatterInterface` | interface | `{ format() }` | Represents the `Formatter` stage contract: render the refined natural-language prompt for a matched recipe. |
|
|
429
|
+
| `GeneratorInterface` | interface | `{ generate() }` | Represents the `Generator` stage contract: build the final subject/definition pair plus its field audit. |
|
|
430
|
+
| `NarratorInterface` | interface | `{ phrase(), label(), line(), value(), describe(), narrate() }` | Represents the `Narrator` contract — a stateless, total, lexicon-driven rendering engine for the reverse direction. |
|
|
431
|
+
| `RecipeManagerInterface` | interface | `{ emitter, count, has(), recipe(), recipes(), add(), remove(), destroy() }` | Represents the recipe registry — a self-owning, versioned/hashed record-holder with the singular/plural accessor pair and the batch `remove` overloads. |
|
|
432
|
+
| `SubjectManagerInterface` | interface | `{ emitter, count, has(), subject(), subjects(), add(), remove(), destroy() }` | Represents the subject registry — a self-owning, versioned/hashed record-holder that mints its own record ids (a `Subject` carries none). |
|
|
433
|
+
| `DefinitionManagerInterface` | interface | `{ emitter, count, has(), definition(), definitions(), add(), remove(), destroy() }` | Represents the definition registry — a self-owning, versioned/hashed record-holder. |
|
|
434
|
+
| `InterpretContextInterface` | interface | `{ emitter, session, subjects, definitions, previous(), entities(), add(), clear(), destroy() }` | Represents the cross-turn interpretation context: a capped, replayable history plus the subject/definition registries carry-over reads from. |
|
|
435
|
+
| `InterpretInterface` | interface | `{ emitter, interpret(), add(), remove(), recipe(), recipes(), describe(), narrate(), destroy() }` | Represents the interpretation orchestrator — the sole public entry point, mirroring `reasons`' `Reason` orchestrator shape. |
|
|
134
436
|
|
|
135
437
|
### Constants
|
|
136
438
|
|
|
137
|
-
| Name
|
|
138
|
-
|
|
|
139
|
-
| `
|
|
140
|
-
| `
|
|
141
|
-
| `
|
|
142
|
-
| `
|
|
143
|
-
| `
|
|
144
|
-
| `
|
|
145
|
-
| `
|
|
146
|
-
| `
|
|
147
|
-
| `
|
|
148
|
-
| `
|
|
149
|
-
| `
|
|
150
|
-
| `
|
|
151
|
-
| `
|
|
152
|
-
| `
|
|
153
|
-
| `
|
|
154
|
-
| `
|
|
439
|
+
| Name | Kind | Signature | Summary |
|
|
440
|
+
| --------------------------- | ----- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
441
|
+
| `NUMBER_FOREIGN_KINDS` | const | `readonly NumberForeign[]` | Lists every `NumberForeign` kind, frozen, for the shape that describes a read number. |
|
|
442
|
+
| `NUMBER_UNREADABLE_REASONS` | const | `readonly NumberUnreadable[]` | Lists every `NumberUnreadable` reason, frozen, for the shape that describes a read number. |
|
|
443
|
+
| `READER_WORDS` | const | `Readonly<{ synonyms: Readonly<Record<string, string>>; per: Readonly<Set<string>>; months: Readonly<Set<string>>; yearCues: Readonly<Set<string>>; references: Readonly<Set<string>>; referenceLinks: Readonly<Set<string>>; streets: Readonly<Set<string>>; generalUnits: Readonly<Set<string>>; timeUnits: Readonly<Set<string>>; calendarPeriods: Readonly<Set<string>>; countedOver: Readonly<Set<string>>; foreignCurrency: Readonly<Set<string>>; dollars: Readonly<Set<string>>; hedgesBefore: Readonly<Set<string>>; hedgesNear: Readonly<Set<string>>; hedgePairs: Readonly<Set<string>>; doubtPairs: Readonly<Set<string>>; hedgesAfter: Readonly<Set<string>>; hedgeAfterPairs: Readonly<Set<string>>; corrections: Readonly<Set<string>>; correctionPairs: Readonly<Set<string>>; suspectBefore: Readonly<Set<string>>; offsetBefore: Readonly<Set<string>>; verbLastBefore: Readonly<Set<string>>; putInBefore: Readonly<Set<string>>; changes: Readonly<Set<string>>; compositeCues: Readonly<Set<string>>; loose: Readonly<Set<string>>; magnitudes: Readonly<Set<string>>; gluedScales: Readonly<Set<string>>; functions: Readonly<Set<string>>; abbreviations: Readonly<Set<string>>; notOneBefore: Readonly<Set<string>>; notOneAfter: Readonly<Set<string>>; workOut: Readonly<Set<string>>; dimensions: Readonly<Set<string>>; alternatives: Readonly<Set<string>>; sentenceEnds: Readonly<Set<string>>; segmentMarks: Readonly<Set<string>>; ageBefore: Readonly<Set<string>>; }>` | Holds the word lists `NumberReader` reads a number's surroundings by. |
|
|
444
|
+
| `READER_SCALES` | const | `Readonly<{ digit: Readonly<Record<string, number>>; word: Readonly<Record<string, number>>; units: Readonly<Record<string, number>>; tens: Readonly<Record<string, number>>; }>` | Holds the values number words and scale words read to. |
|
|
445
|
+
| `READER_SHAPES` | const | `Readonly<{ admitted: RegExp; currency: RegExp; digit: RegExp; word: RegExp; }>` | Holds the shapes `NumberReader` recognizes a number by. |
|
|
446
|
+
| `CLAUSE_BREAK_PATTERN` | const | `RegExp` | Holds what ends a clause: closing punctuation, a comma or dot no digit follows, a newline, and a joining word. A colon stays inside, because "rate: 6" says one thing. |
|
|
447
|
+
| `DEFAULT_INTERPRET_FLOOR` | const | `0.3` | Names the default `floor` for `createInterpret` and `matchRecipe`, 0.3 — the minimum intent confidence a recipe match, or the classified intent itself, must clear. |
|
|
448
|
+
| `DEFAULT_INTERPRET_HISTORY` | const | `0` | Names the default `history` cap for an `InterpretContext`'s `previous()` ring buffer, 0 (carry is opt-in). |
|
|
449
|
+
| `PROVENANCE_CATEGORIES` | const | `readonly ProvenanceCategory[]` | Lists every `ProvenanceCategory` literal, frozen — the one home the result guards check the union from, so a new category added to `types.ts` is added here rather than silently rejected by `isProvenance`. |
|
|
450
|
+
| `INTERPRET_STAGES` | const | `readonly InterpretStage[]` | Lists every `InterpretStage` literal in pipeline order, frozen — the one home the result guards check the union from. |
|
|
451
|
+
| `INTERPRET_TEXT_LIMIT` | const | `65536` | Caps text accepted by the built-in normalizer and number reader at 65,536 UTF-16 units. |
|
|
452
|
+
| `INTERPRET_ERROR_CODES` | const | `readonly InterpretErrorCode[]` | Lists every `InterpretErrorCode` literal, frozen — the one home the result guards check the union from. |
|
|
453
|
+
| `CONFIDENCE_EXACT` | const | `1` | Names the confidence assigned to an exact keyword-proximity entity match, 1. |
|
|
454
|
+
| `CONFIDENCE_ALIAS` | const | `0.9` | Names the confidence assigned to an exact alias-phrase entity match, 0.9. |
|
|
455
|
+
| `CONFIDENCE_COLLECT` | const | `0.9` | Names the confidence assigned when a single entity mapping collects every extracted number, 0.9. |
|
|
456
|
+
| `CONFIDENCE_CARRIED` | const | `0.7` | Names the confidence assigned to a same-domain carried-over field, 0.7. |
|
|
457
|
+
| `CONFIDENCE_DEFAULT` | const | `1` | Names the confidence assigned to a default the door filled, 1. |
|
|
458
|
+
| `CONFIDENCE_COMPUTED` | const | `0.9` | Names the most a computed field may be trusted, 0.9: its inputs can only lower it. |
|
|
459
|
+
| `NUMBER_PATTERN` | const | `RegExp` | Holds the digit-only pattern for `extractNumbers`: an optional currency prefix, grouped digits, an optional decimal fraction, and an optional trailing `%`. |
|
|
460
|
+
| `DEFAULT_CONTRACTIONS` | const | `Readonly<Record<string, string>>` | Holds the neutral built-in contraction expansions for `Normalizer` — small on purpose; callers merge their own map over this one. |
|
|
461
|
+
| `DEFAULT_LEXICON` | const | `Lexicon` | Holds the neutral default `Lexicon` a `Narrator` merges caller data over. |
|
|
155
462
|
|
|
156
463
|
```ts
|
|
157
464
|
import {
|
|
@@ -161,22 +468,18 @@ import {
|
|
|
161
468
|
CONFIDENCE_COMPUTED,
|
|
162
469
|
CONFIDENCE_DEFAULT,
|
|
163
470
|
CONFIDENCE_EXACT,
|
|
164
|
-
CONFIDENCE_POSITIONAL,
|
|
165
471
|
DEFAULT_CONTRACTIONS,
|
|
166
472
|
DEFAULT_INTERPRET_FLOOR,
|
|
167
473
|
DEFAULT_INTERPRET_HISTORY,
|
|
168
|
-
DEFAULT_INTERPRET_SIMILARITY,
|
|
169
474
|
DEFAULT_LEXICON,
|
|
170
475
|
NUMBER_PATTERN,
|
|
171
476
|
} from '@orkestrel/interpret'
|
|
172
477
|
|
|
173
|
-
DEFAULT_INTERPRET_SIMILARITY // 0.8
|
|
174
478
|
DEFAULT_INTERPRET_FLOOR // 0.3
|
|
175
|
-
DEFAULT_INTERPRET_HISTORY //
|
|
479
|
+
DEFAULT_INTERPRET_HISTORY // 0
|
|
176
480
|
CONFIDENCE_EXACT // 1
|
|
177
481
|
CONFIDENCE_ALIAS // 0.9
|
|
178
482
|
CONFIDENCE_COLLECT // 0.9
|
|
179
|
-
CONFIDENCE_POSITIONAL // 0.7
|
|
180
483
|
CONFIDENCE_CARRIED // 0.7
|
|
181
484
|
CONFIDENCE_DEFAULT // 1
|
|
182
485
|
CONFIDENCE_COMPUTED // 0.9
|
|
@@ -220,7 +523,6 @@ published member conforms, because a foreign engine's return is not this package
|
|
|
220
523
|
| Name | Kind | Signature | Summary |
|
|
221
524
|
| ------------------ | -------- | --------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
222
525
|
| `isEntityMapping` | function | `(value: unknown) => value is EntityMapping` | Determines whether a value is an exact `EntityMapping` input record — a literal alias-phrase extraction rule pointing at a subject field. |
|
|
223
|
-
| `isFieldDefault` | function | `(value: unknown) => value is FieldDefault` | Determines whether a value is an exact `FieldDefault` input record — a fallback value a `Recipe` fills onto an unresolved field. |
|
|
224
526
|
| `isComputedField` | function | `(value: unknown) => value is ComputedField` | Determines whether a value is an exact `ComputedField` input record — a declaratively computed field carrying a reasons `SymbolicExpression` tree. |
|
|
225
527
|
| `isRecipe` | function | `(value: unknown) => value is Recipe` | Determines whether a value is an exact `Recipe` input record — a named, versionable interpretation recipe. |
|
|
226
528
|
| `isProvenance` | function | `(value: unknown) => value is Provenance` | Determines whether a value is an open `Provenance` result record. |
|
|
@@ -233,13 +535,13 @@ published member conforms, because a foreign engine's return is not this package
|
|
|
233
535
|
| `isInterpretation` | function | `(value: unknown) => value is Interpretation` | Determines whether a value is an open `Interpretation` result record. |
|
|
234
536
|
|
|
235
537
|
```ts
|
|
538
|
+
import { objectShape } from '@orkestrel/contract'
|
|
236
539
|
import {
|
|
237
540
|
createInterpret,
|
|
238
541
|
isAmbiguity,
|
|
239
542
|
isComputedField,
|
|
240
543
|
isEntity,
|
|
241
544
|
isEntityMapping,
|
|
242
|
-
isFieldDefault,
|
|
243
545
|
isFieldMapping,
|
|
244
546
|
isIntent,
|
|
245
547
|
isInterpretation,
|
|
@@ -255,7 +557,6 @@ import {
|
|
|
255
557
|
} from '@orkestrel/reason'
|
|
256
558
|
|
|
257
559
|
isEntityMapping({ entity: 'age', aliases: ['years old'], field: 'age' }) // true
|
|
258
|
-
isFieldDefault({ field: 'term', value: 12 }) // true
|
|
259
560
|
isComputedField({
|
|
260
561
|
field: 'monthly',
|
|
261
562
|
expression: {
|
|
@@ -271,7 +572,7 @@ isRecipe({
|
|
|
271
572
|
domain: 'arithmetic',
|
|
272
573
|
intents: ['calculate'],
|
|
273
574
|
mappings: [],
|
|
274
|
-
|
|
575
|
+
shape: objectShape({}),
|
|
275
576
|
computations: [],
|
|
276
577
|
definition: createQuantitativeDefinition('t1', 'Arithmetic', [
|
|
277
578
|
createFactorGroup('total', 'sum', [createFieldFactor('value', 'value')]),
|
|
@@ -295,25 +596,39 @@ guardEngine.destroy()
|
|
|
295
596
|
Pure, exported utility functions — the referentially-transparent leaves
|
|
296
597
|
behind the `Interpret` orchestrator and its stages.
|
|
297
598
|
|
|
298
|
-
| Name
|
|
299
|
-
|
|
|
300
|
-
| `
|
|
301
|
-
| `
|
|
302
|
-
| `
|
|
303
|
-
| `
|
|
304
|
-
| `
|
|
305
|
-
| `
|
|
306
|
-
| `
|
|
307
|
-
| `
|
|
308
|
-
| `
|
|
309
|
-
| `
|
|
310
|
-
| `
|
|
311
|
-
| `
|
|
312
|
-
| `
|
|
313
|
-
| `
|
|
314
|
-
| `
|
|
315
|
-
| `
|
|
316
|
-
| `
|
|
599
|
+
| Name | Kind | Signature | Summary |
|
|
600
|
+
| ----------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------- |
|
|
601
|
+
| `matchesFilledField` | function | `(field: string, filled: readonly string[]) => boolean` | Determines whether a field is filled by one of the given fields: itself, one above it, or one inside it. |
|
|
602
|
+
| `collectRequiredFields` | function | `(shape: ContractShape, path?: readonly string[]) => readonly string[]` | Lists the fields a shape requires, each as its dot-joined path. |
|
|
603
|
+
| `scanNumbers` | function | `(text: string) => readonly ReadNumber[]` | Reads every number in a text exactly, or says why it cannot. |
|
|
604
|
+
| `findUnclaimedNumbers` | function | `(numbers: readonly ReadNumber[], entities: readonly Entity[]) => ReadonlyArray<number \| string>` | Finds the numbers no entity claimed. |
|
|
605
|
+
| `findAnchoredNumber` | function | `(text: string, anchor: TextSpan, numbers: readonly TextSpan[], refused?: AnchorRefusalHandler) => { readonly index: number; readonly gap: number; } \| undefined` | Finds the nearest directly linked number in an unnegated clause, refusing ties. |
|
|
606
|
+
| `findSpanOffset` | function | `(spans: readonly TextSpan[], position: number, edge?: 'start' \| 'end', lower?: number, upper?: number) => number` | Finds the first span whose selected edge is at or beyond a position. |
|
|
607
|
+
| `findLinkedNumbers` | function | `(text: string, anchor: TextSpan, numbers: readonly TextSpan[], clause: TextSpan) => readonly AnchorCandidate[]` | Finds directly linked numeric spans ordered by distance within a supplied clause. |
|
|
608
|
+
| `projectInterpretation` | function | `(result: Interpretation) => JSONValue \| undefined` | Projects an interpretation to JSON, so it can cross a boundary. |
|
|
609
|
+
| `assertRecipe` | function | `(recipe: unknown) => asserts recipe is Recipe` | Asserts a value is a recipe that stands. |
|
|
610
|
+
| `scanRecipeShape` | function | `(recipe: Recipe) => readonly string[]` | Describes what is wrong with a recipe's shape, against the recipe itself. |
|
|
611
|
+
| `settleEntities` | function | `(entities: readonly Entity[], mappings: readonly EntityMapping[], admission: SubjectAdmission) => readonly Entity[]` | Settles entities against what the door admitted. |
|
|
612
|
+
| `collectShapeDefaults` | function | `(shape: ContractShape, subject?: unknown, path?: readonly string[]) => readonly ShapeDefault[]` | Collects each default a shape holds, keyed by its field. |
|
|
613
|
+
| `findFieldDescription` | function | `(shape: ContractShape, field: FieldPath) => string \| undefined` | Finds the description a shape gives a field, which words the question for it. |
|
|
614
|
+
| `matchesArrayField` | function | `(shape: ContractShape, field: FieldPath) => boolean` | Determines whether a shape's field holds an array, so a mapping onto it collects many. |
|
|
615
|
+
| `buildSubject` | function | `(entities: readonly Entity[], mappings: readonly EntityMapping[]) => Subject` | Builds a subject from entities, each on the field it lands on. |
|
|
616
|
+
| `findEntityField` | function | `(entity: Entity, mappings: readonly EntityMapping[]) => FieldPath` | Finds the field an entity lands on. |
|
|
617
|
+
| `setField` | function | `(subject: Subject, field: FieldPath, value: unknown) => Subject` | Writes a value at a (possibly nested) field path on a subject, copy-on-write. |
|
|
618
|
+
| `applyReplacements` | function | `(text: string, map: Readonly<Record<string, string>>) => string` | Replaces every whole-word occurrence of a map's keys with their values. |
|
|
619
|
+
| `collapseWhitespace` | function | `(text: string) => string` | Collapses every run of whitespace to a single space and trims the ends. |
|
|
620
|
+
| `tokenize` | function | `(text: string) => readonly string[]` | Splits text into lowercase tokens, stripping punctuation outside a small numeric/currency-safe allowlist. |
|
|
621
|
+
| `extractNumbers` | function | `(text: string) => readonly number[]` | Mines every numeric literal from text — optional leading `$`, thousands commas, an optional decimal fraction, an optional trailing `%`. |
|
|
622
|
+
| `assignEntities` | function | `(numbers: readonly ReadNumber[], mappings: readonly EntityMapping[], text: string, shape: ContractShape) => readonly Entity[]` | Assigns exact reader occurrences to a matched recipe's entity mappings. |
|
|
623
|
+
| `classifyIntent` | function | `(text: string, actions: Readonly<Record<string, string>>, domains: Readonly<Record<string, readonly string[]>>) => Intent` | Classifies the action + domain intent of a text against caller-supplied vocabularies. |
|
|
624
|
+
| `canonicalize` | function | `(value: unknown) => string` | Renders a value into a canonical, key-order-stable string — the pre-image of `digestValue`. |
|
|
625
|
+
| `canonicalizeNode` | function | `(value: unknown, ancestors: ReadonlySet<object>) => string` | Renders one node of a value into its canonical, key-order-stable string, against the object ancestors already on the recursion path. |
|
|
626
|
+
| `digestValue` | function | `(value: unknown) => string` | Computes a canonical structural digest of a pure-JSON value — a key-order-stable FNV-1a hash rendered as an 8-hex-digit string. |
|
|
627
|
+
| `scoreRecipe` | function | `(intent: Intent, recipe: Recipe) => number` | Scores how well a classified intent matches one recipe's domain + action. |
|
|
628
|
+
| `matchRecipe` | function | `(intent: Intent, recipes: readonly Recipe[], floor: number) => Recipe \| undefined` | Finds the best-scoring added recipe for a classified intent, gated by a confidence floor. |
|
|
629
|
+
| `variablesOf` | function | `(expression: SymbolicExpression) => readonly string[]` | Collects every variable name referenced by a symbolic expression tree, in first-occurrence order. |
|
|
630
|
+
| `resolveExpression` | function | `(expression: SymbolicExpression, bindings: Readonly<Record<string, number>>) => number \| undefined` | Evaluates a symbolic expression tree against resolved bindings. |
|
|
631
|
+
| `renderSubject` | function | `(subject: Subject, narrator: NarratorInterface) => string` | Renders a one-line, display-neutral description of a reasons `Subject`, through an injected `Narrator`. |
|
|
317
632
|
|
|
318
633
|
```ts
|
|
319
634
|
import { applyReplacements, collapseWhitespace, setField, tokenize } from '@orkestrel/interpret'
|
|
@@ -325,33 +640,29 @@ collapseWhitespace(' a b\t c ') // 'a b c'
|
|
|
325
640
|
tokenize('The rate is 85%.') // ['the', 'rate', 'is', '85%.']
|
|
326
641
|
```
|
|
327
642
|
|
|
328
|
-
Extraction, classification, and
|
|
643
|
+
Extraction, classification, and assignment — the leaves behind
|
|
329
644
|
`Extractor#extract` and recipe entity assignment:
|
|
330
645
|
|
|
331
646
|
```ts
|
|
332
|
-
import {
|
|
333
|
-
|
|
334
|
-
classifyIntent,
|
|
335
|
-
extractNumbers,
|
|
336
|
-
matchAlias,
|
|
337
|
-
scoreSimilarity,
|
|
338
|
-
} from '@orkestrel/interpret'
|
|
647
|
+
import { numberShape, objectShape } from '@orkestrel/contract'
|
|
648
|
+
import { assignEntities, classifyIntent, extractNumbers, scanNumbers } from '@orkestrel/interpret'
|
|
339
649
|
|
|
340
650
|
extractNumbers('income was $50,000, age 25') // [50000, 25]
|
|
341
651
|
const mappings = [
|
|
342
652
|
{ entity: 'age', aliases: ['years old'], field: 'age' },
|
|
343
653
|
{ entity: 'score', aliases: ['credit score'], field: 'score' },
|
|
344
654
|
]
|
|
345
|
-
|
|
655
|
+
const shape = objectShape({ age: numberShape(), score: numberShape() })
|
|
656
|
+
assignEntities(scanNumbers('age 25 with score 720'), mappings, 'age 25 with score 720', shape)
|
|
657
|
+
// Both values are assigned; `with` keeps age because the declared score anchor follows it.
|
|
346
658
|
classifyIntent('calculate my rate', { calculate: 'compute' }, { rating: ['rate'] })
|
|
347
|
-
scoreSimilarity('rate', 'rate') // 1
|
|
348
|
-
matchAlias('valu', ['value', 'amount'], 0.6) // ~0.86 — fuzzy hit on 'value'
|
|
349
659
|
```
|
|
350
660
|
|
|
351
661
|
Digest, recipe matching, computed-field resolution, and the reverse
|
|
352
662
|
direction:
|
|
353
663
|
|
|
354
664
|
```ts
|
|
665
|
+
import { objectShape } from '@orkestrel/contract'
|
|
355
666
|
import type { Recipe } from '@orkestrel/interpret'
|
|
356
667
|
import {
|
|
357
668
|
canonicalize,
|
|
@@ -393,7 +704,7 @@ const recipe: Recipe = {
|
|
|
393
704
|
domain: 'rating',
|
|
394
705
|
intents: ['compute'],
|
|
395
706
|
mappings: [],
|
|
396
|
-
|
|
707
|
+
shape: objectShape({}),
|
|
397
708
|
computations: [],
|
|
398
709
|
definition: { reasoning: 'symbolic', id: 't1', name: 'T', equations: [], variables: {} },
|
|
399
710
|
}
|
|
@@ -418,21 +729,22 @@ parseRecipe('not json') // undefined
|
|
|
418
729
|
|
|
419
730
|
### Factories
|
|
420
731
|
|
|
421
|
-
| Name | Kind | Signature | Summary
|
|
422
|
-
| ------------------------- | -------- | -------------------------------------------------------------------- |
|
|
423
|
-
| `createInterpret` | function | `(options?: InterpretOptions) => InterpretInterface` | Creates an interpretation orchestrator, returning an `InterpretInterface` seeded from `InterpretOptions`.
|
|
424
|
-
| `createNormalizer` | function | `(options?: NormalizerOptions) => NormalizerInterface` | Creates a text normalizer, returning a stateless `NormalizerInterface`.
|
|
425
|
-
| `createExtractor` | function | `(options?: ExtractorOptions) => ExtractorInterface` | Creates a recipe-agnostic intent classifier and number extractor, returning a stateless `ExtractorInterface`.
|
|
426
|
-
| `createClarifier` | function | `(options?: ClarifierOptions) => ClarifierInterface` | Creates a clarifier — carry-over,
|
|
427
|
-
| `createFormatter` | function | `(options?: FormatterOptions) => FormatterInterface` | Creates a prompt formatter, returning a stateless `FormatterInterface`.
|
|
428
|
-
| `createGenerator` | function | `() => GeneratorInterface` | Creates a subject and definition generator, returning a stateless `GeneratorInterface`.
|
|
429
|
-
| `createRecipeManager` | function | `(options?: RecipeManagerOptions) => RecipeManagerInterface` | Creates a recipe registry, returning a working `RecipeManagerInterface`.
|
|
430
|
-
| `createSubjectManager` | function | `(options?: SubjectManagerOptions) => SubjectManagerInterface` | Creates a subject registry, returning a working `SubjectManagerInterface`.
|
|
431
|
-
| `createDefinitionManager` | function | `(options?: DefinitionManagerOptions) => DefinitionManagerInterface` | Creates a definition registry, returning a working `DefinitionManagerInterface`.
|
|
432
|
-
| `createInterpretContext` | function | `(options?: InterpretContextOptions) => InterpretContextInterface` | Creates a cross-turn interpretation context, returning a working `InterpretContextInterface`.
|
|
433
|
-
| `createNarrator` | function | `(options?: NarratorOptions) => NarratorInterface` | Creates a lexicon-driven reverse-direction rendering engine, returning a stateless `NarratorInterface`.
|
|
732
|
+
| Name | Kind | Signature | Summary |
|
|
733
|
+
| ------------------------- | -------- | -------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
734
|
+
| `createInterpret` | function | `(options?: InterpretOptions) => InterpretInterface` | Creates an interpretation orchestrator, returning an `InterpretInterface` seeded from `InterpretOptions`. |
|
|
735
|
+
| `createNormalizer` | function | `(options?: NormalizerOptions) => NormalizerInterface` | Creates a text normalizer, returning a stateless `NormalizerInterface`. |
|
|
736
|
+
| `createExtractor` | function | `(options?: ExtractorOptions) => ExtractorInterface` | Creates a recipe-agnostic intent classifier and number extractor, returning a stateless `ExtractorInterface`. |
|
|
737
|
+
| `createClarifier` | function | `(options?: ClarifierOptions) => ClarifierInterface` | Creates a clarifier — carry-over, computed-field resolution, and the door's reading of the recipe's shape against an assigned entity set — returning a `ClarifierInterface`. |
|
|
738
|
+
| `createFormatter` | function | `(options?: FormatterOptions) => FormatterInterface` | Creates a prompt formatter, returning a stateless `FormatterInterface`. |
|
|
739
|
+
| `createGenerator` | function | `() => GeneratorInterface` | Creates a subject and definition generator, returning a stateless `GeneratorInterface`. |
|
|
740
|
+
| `createRecipeManager` | function | `(options?: RecipeManagerOptions) => RecipeManagerInterface` | Creates a recipe registry, returning a working `RecipeManagerInterface`. |
|
|
741
|
+
| `createSubjectManager` | function | `(options?: SubjectManagerOptions) => SubjectManagerInterface` | Creates a subject registry, returning a working `SubjectManagerInterface`. |
|
|
742
|
+
| `createDefinitionManager` | function | `(options?: DefinitionManagerOptions) => DefinitionManagerInterface` | Creates a definition registry, returning a working `DefinitionManagerInterface`. |
|
|
743
|
+
| `createInterpretContext` | function | `(options?: InterpretContextOptions) => InterpretContextInterface` | Creates a cross-turn interpretation context, returning a working `InterpretContextInterface`. |
|
|
744
|
+
| `createNarrator` | function | `(options?: NarratorOptions) => NarratorInterface` | Creates a lexicon-driven reverse-direction rendering engine, returning a stateless `NarratorInterface`. |
|
|
434
745
|
|
|
435
746
|
```ts
|
|
747
|
+
import { numberShape, objectShape } from '@orkestrel/contract'
|
|
436
748
|
import {
|
|
437
749
|
createClarifier,
|
|
438
750
|
createDefinitionManager,
|
|
@@ -471,7 +783,7 @@ const recipes = createRecipeManager({
|
|
|
471
783
|
domain: 'arithmetic',
|
|
472
784
|
intents: ['calculate'],
|
|
473
785
|
mappings: [{ entity: 'value', aliases: [], field: 'value' }],
|
|
474
|
-
|
|
786
|
+
shape: objectShape({ value: numberShape() }),
|
|
475
787
|
computations: [],
|
|
476
788
|
definition: createQuantitativeDefinition('t1', 'Arithmetic', [
|
|
477
789
|
createFactorGroup('total', 'sum', [createFieldFactor('value', 'value')]),
|
|
@@ -492,6 +804,34 @@ createDefinitionManager({
|
|
|
492
804
|
}).count // 1
|
|
493
805
|
```
|
|
494
806
|
|
|
807
|
+
### Shapes
|
|
808
|
+
|
|
809
|
+
The definition and result as `ContractShape` values.
|
|
810
|
+
|
|
811
|
+
| Name | Kind | Signature | Summary |
|
|
812
|
+
| --------------------- | -------- | --------------------- | ----------------------------------------------------- |
|
|
813
|
+
| `readNumberShape` | const | `ContractShape` | Describes a number `scanNumbers` read. |
|
|
814
|
+
| `interpretationShape` | const | `ContractShape` | Describes an `Interpretation` in its JSON projection. |
|
|
815
|
+
| `stageFailureShape` | const | `ContractShape` | Describes a `StageFailure`. |
|
|
816
|
+
| `stageRecordShape` | const | `ContractShape` | Describes a `StageRecord` in its JSON projection. |
|
|
817
|
+
| `fieldMappingShape` | const | `ContractShape` | Describes a `FieldMapping` in its JSON projection. |
|
|
818
|
+
| `ambiguityShape` | const | `ContractShape` | Describes an `Ambiguity`. |
|
|
819
|
+
| `entityShape` | const | `ContractShape` | Describes an `Entity` in its JSON projection. |
|
|
820
|
+
| `intentShape` | const | `ContractShape` | Describes an `Intent`. |
|
|
821
|
+
| `provenanceShape` | const | `ContractShape` | Describes a `Provenance`. |
|
|
822
|
+
| `createRecipeShape` | function | `() => ContractShape` | Creates the shape of a `Recipe`. |
|
|
823
|
+
| `entityMappingShape` | const | `ContractShape` | Describes an `EntityMapping`. |
|
|
824
|
+
|
|
825
|
+
### Contracts
|
|
826
|
+
|
|
827
|
+
The compiled contract of what is flat enough to compile at import.
|
|
828
|
+
|
|
829
|
+
| Name | Kind | Signature | Summary |
|
|
830
|
+
| ------------------------ | -------- | ---------------------------------- | ---------------------------------------------------------------------------------------------------- |
|
|
831
|
+
| `readNumbersContract` | const | `ContractInterface<unknown>` | Publishes what `scanNumbers` returns as a contract. |
|
|
832
|
+
| `interpretationContract` | const | `ContractInterface<unknown>` | Publishes an `Interpretation`'s JSON projection as a contract, read through `projectInterpretation`. |
|
|
833
|
+
| `createRecipeContract` | function | `() => ContractInterface<unknown>` | Creates a `Recipe` as a contract. Cross it on `is`, never `parse`. |
|
|
834
|
+
|
|
495
835
|
### Classes
|
|
496
836
|
|
|
497
837
|
| Name | Kind | Signature | Summary |
|
|
@@ -499,8 +839,8 @@ createDefinitionManager({
|
|
|
499
839
|
| `Interpret` | class | `new (options?: InterpretOptions) => InterpretInterface` | Implements the interpretation orchestrator — the sole public entry point of the `interprets` module, mirroring the reasons `Reason` orchestrator shape: it runs the `[normalize, extract, clarify, format, generate]` pipeline, owns the recipe registry and the context, and exposes the reverse direction. |
|
|
500
840
|
| `Narrator` | class | `new (options?: NarratorOptions) => NarratorInterface` | Implements a stateless, total, lexicon-driven rendering engine for the reverse direction — the reverse-direction mirror of the forward `Formatter`'s `verbs` seam, supplying mechanism rather than wording policy. |
|
|
501
841
|
| `Normalizer` | class | `new (options?: NormalizerOptions) => NormalizerInterface` | Implements the normalize stage: applies contraction, abbreviation, and correction substitutions in order, then collapses whitespace. |
|
|
502
|
-
| `Extractor` | class | `new (options?: ExtractorOptions) => ExtractorInterface` | Implements the extract stage: recipe-agnostic intent classification plus
|
|
503
|
-
| `Clarifier` | class | `new (options?: ClarifierOptions) => ClarifierInterface` | Implements the clarify stage: resolves same-domain carry-over
|
|
842
|
+
| `Extractor` | class | `new (options?: ExtractorOptions) => ExtractorInterface` | Implements the extract stage: recipe-agnostic intent classification plus exact reader values. |
|
|
843
|
+
| `Clarifier` | class | `new (options?: ClarifierOptions) => ClarifierInterface` | Implements the clarify stage: resolves same-domain carry-over and declaratively computed fields against an already-assigned entity set, admits the subject they build through the recipe's shape, and surfaces an `Ambiguity` for everything the door refused. |
|
|
504
844
|
| `Formatter` | class | `new (options?: FormatterOptions) => FormatterInterface` | Implements the format stage: renders the refined natural-language prompt for a matched recipe. |
|
|
505
845
|
| `Generator` | class | `new () => GeneratorInterface` | Implements the generate stage: builds the final `Subject` from a fully resolved entity set, plus its complete field audit. |
|
|
506
846
|
| `RecordManager` | class | `new <TValue, TRecord extends RecordStamp>(options: RecordManagerOptions) => RecordManagerInterface<TValue, TRecord>` | Implements the shared registry engine behind every record manager in this module — it owns the `Map`, the content-hash and version rule, the batch `remove` overloads, and teardown. |
|
|
@@ -534,9 +874,9 @@ normalizer.normalize("can't stop") // { text: 'cannot stop', changes: [{ from:
|
|
|
534
874
|
|
|
535
875
|
#### `ExtractorInterface`
|
|
536
876
|
|
|
537
|
-
| Method | Returns | Summary
|
|
538
|
-
| --------- | --------------- |
|
|
539
|
-
| `extract` | `ExtractResult` | Classifies the intent and
|
|
877
|
+
| Method | Returns | Summary |
|
|
878
|
+
| --------- | --------------- | ---------------------------------------------------------------------- |
|
|
879
|
+
| `extract` | `ExtractResult` | Classifies the intent and returns exact values from the number reader. |
|
|
540
880
|
|
|
541
881
|
```ts
|
|
542
882
|
import { createExtractor } from '@orkestrel/interpret'
|
|
@@ -551,11 +891,12 @@ extractor.extract('calculate my rate at 85')
|
|
|
551
891
|
|
|
552
892
|
#### `ClarifierInterface`
|
|
553
893
|
|
|
554
|
-
| Method | Returns | Summary
|
|
555
|
-
| --------- | --------------- |
|
|
556
|
-
| `clarify` | `ClarifyResult` | Resolves carry-over
|
|
894
|
+
| Method | Returns | Summary |
|
|
895
|
+
| --------- | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
896
|
+
| `clarify` | `ClarifyResult` | Resolves carry-over and computed fields, admits the result through the recipe's shape, and surfaces an `Ambiguity` for everything the door refused, every value read below the floor, and every mapped field left to a default or a prior turn while a number nobody claimed could be its value, with its question from the shape's `description` or the narrator's `ambiguity.entity` line. |
|
|
557
897
|
|
|
558
898
|
```ts
|
|
899
|
+
import { numberShape, objectShape } from '@orkestrel/contract'
|
|
559
900
|
import { createClarifier } from '@orkestrel/interpret'
|
|
560
901
|
|
|
561
902
|
const clarifier = createClarifier({ floor: 0.3 })
|
|
@@ -566,8 +907,8 @@ clarifier.clarify(
|
|
|
566
907
|
name: 'Arithmetic',
|
|
567
908
|
domain: 'arithmetic',
|
|
568
909
|
intents: ['calculate'],
|
|
569
|
-
mappings: [{ entity: 'value', aliases: [], field: 'value'
|
|
570
|
-
|
|
910
|
+
mappings: [{ entity: 'value', aliases: [], field: 'value' }],
|
|
911
|
+
shape: objectShape({ value: numberShape() }),
|
|
571
912
|
computations: [],
|
|
572
913
|
definition: {
|
|
573
914
|
reasoning: 'symbolic',
|
|
@@ -587,6 +928,7 @@ A computation addresses one numeric element of an array-valued field as
|
|
|
587
928
|
aggregate over it:
|
|
588
929
|
|
|
589
930
|
```ts
|
|
931
|
+
import { arrayShape, numberShape, objectShape } from '@orkestrel/contract'
|
|
590
932
|
import { createClarifier } from '@orkestrel/interpret'
|
|
591
933
|
import { createOperation, createVariable } from '@orkestrel/reason'
|
|
592
934
|
|
|
@@ -604,7 +946,7 @@ clarifier.clarify(
|
|
|
604
946
|
domain: 'arithmetic',
|
|
605
947
|
intents: ['calculate'],
|
|
606
948
|
mappings: [{ entity: 'value', aliases: [], field: 'value' }],
|
|
607
|
-
|
|
949
|
+
shape: objectShape({ value: arrayShape(numberShape()), total: numberShape() }),
|
|
608
950
|
computations: [
|
|
609
951
|
{
|
|
610
952
|
field: 'total',
|
|
@@ -626,11 +968,16 @@ clarifier.clarify(
|
|
|
626
968
|
|
|
627
969
|
#### `FormatterInterface`
|
|
628
970
|
|
|
971
|
+
Primitive strings retain their text. Other values use the contract package's total
|
|
972
|
+
`preview` renderer. Objects and arrays, including the door's null-prototype defaults,
|
|
973
|
+
render as `object` and `array` without coercion or traversal.
|
|
974
|
+
|
|
629
975
|
| Method | Returns | Summary |
|
|
630
976
|
| -------- | -------------- | --------------------------------------------------------------------------------------------------------------------------- |
|
|
631
977
|
| `format` | `FormatResult` | Renders the refined natural-language prompt for a matched recipe, clause by clause through the narrator's `prompt.*` lines. |
|
|
632
978
|
|
|
633
979
|
```ts
|
|
980
|
+
import { objectShape } from '@orkestrel/contract'
|
|
634
981
|
import { createFormatter } from '@orkestrel/interpret'
|
|
635
982
|
|
|
636
983
|
const formatter = createFormatter({ verbs: { calculate: 'Calculate' } })
|
|
@@ -642,7 +989,7 @@ formatter.format(
|
|
|
642
989
|
domain: 'arithmetic',
|
|
643
990
|
intents: ['calculate'],
|
|
644
991
|
mappings: [],
|
|
645
|
-
|
|
992
|
+
shape: objectShape({}),
|
|
646
993
|
computations: [],
|
|
647
994
|
definition: {
|
|
648
995
|
reasoning: 'symbolic',
|
|
@@ -664,6 +1011,7 @@ formatter.format(
|
|
|
664
1011
|
| `generate` | `GenerateResult` | Builds the final subject and definition pair plus its complete field audit, deriving no field the recipe did not declare. |
|
|
665
1012
|
|
|
666
1013
|
```ts
|
|
1014
|
+
import { numberShape, objectShape } from '@orkestrel/contract'
|
|
667
1015
|
import { createGenerator } from '@orkestrel/interpret'
|
|
668
1016
|
|
|
669
1017
|
const generator = createGenerator()
|
|
@@ -682,7 +1030,7 @@ generator.generate(
|
|
|
682
1030
|
domain: 'arithmetic',
|
|
683
1031
|
intents: ['calculate'],
|
|
684
1032
|
mappings: [{ entity: 'value', aliases: [], field: 'value' }],
|
|
685
|
-
|
|
1033
|
+
shape: objectShape({ value: numberShape() }),
|
|
686
1034
|
computations: [],
|
|
687
1035
|
definition: {
|
|
688
1036
|
reasoning: 'symbolic',
|
|
@@ -793,6 +1141,7 @@ all-or-nothing. A call after `destroy()` throws `InterpretError('DESTROYED', …
|
|
|
793
1141
|
| `destroy` | `void` | Tears the recipe registry down idempotently — clears the collection, emits `destroy`, then destroys the emitter last. |
|
|
794
1142
|
|
|
795
1143
|
```ts
|
|
1144
|
+
import { objectShape } from '@orkestrel/contract'
|
|
796
1145
|
import { createRecipeManager } from '@orkestrel/interpret'
|
|
797
1146
|
import {
|
|
798
1147
|
createFactorGroup,
|
|
@@ -807,7 +1156,7 @@ const record = recipes.add({
|
|
|
807
1156
|
domain: 'arithmetic',
|
|
808
1157
|
intents: ['calculate'],
|
|
809
1158
|
mappings: [],
|
|
810
|
-
|
|
1159
|
+
shape: objectShape({}),
|
|
811
1160
|
computations: [],
|
|
812
1161
|
definition: createQuantitativeDefinition('t1', 'Arithmetic', [
|
|
813
1162
|
createFactorGroup('total', 'sum', [createFieldFactor('value', 'value')]),
|
|
@@ -889,7 +1238,7 @@ definitions.destroy()
|
|
|
889
1238
|
#### `InterpretContextInterface`
|
|
890
1239
|
|
|
891
1240
|
`previous()` returns the ring buffer newest-last, capped at the configured
|
|
892
|
-
`history
|
|
1241
|
+
`history` (default 0). `entities()` flattens every entity across the buffered history,
|
|
893
1242
|
most recent last. `clear()` resets the history, the subject registry, and the
|
|
894
1243
|
definition registry without tearing the context down.
|
|
895
1244
|
|
|
@@ -948,6 +1297,7 @@ subscribes to its emitter.
|
|
|
948
1297
|
| `destroy` | `void` | Tears the orchestrator down idempotently — the recipe registry, the context it constructed itself, then the emitter last. |
|
|
949
1298
|
|
|
950
1299
|
```ts
|
|
1300
|
+
import { numberShape, objectShape } from '@orkestrel/contract'
|
|
951
1301
|
import { createExtractor, createInterpret } from '@orkestrel/interpret'
|
|
952
1302
|
import {
|
|
953
1303
|
createFactorGroup,
|
|
@@ -967,13 +1317,13 @@ interpret.add({
|
|
|
967
1317
|
domain: 'arithmetic',
|
|
968
1318
|
intents: ['calculate'],
|
|
969
1319
|
mappings: [{ entity: 'value', aliases: [], field: 'value' }],
|
|
970
|
-
|
|
1320
|
+
shape: objectShape({ value: numberShape() }),
|
|
971
1321
|
computations: [],
|
|
972
1322
|
definition: createQuantitativeDefinition('t1', 'Arithmetic', [
|
|
973
1323
|
createFactorGroup('total', 'sum', [createFieldFactor('value', 'value')]),
|
|
974
1324
|
]),
|
|
975
1325
|
})
|
|
976
|
-
const result = interpret.interpret('calculate arithmetic 42')
|
|
1326
|
+
const result = interpret.interpret('calculate arithmetic value 42')
|
|
977
1327
|
result.subject // { value: 42 }
|
|
978
1328
|
interpret.recipe('t1') // the plain Recipe data
|
|
979
1329
|
interpret.recipes() // every added recipe
|
|
@@ -990,6 +1340,32 @@ interpret.remove('t1') // true
|
|
|
990
1340
|
interpret.destroy()
|
|
991
1341
|
```
|
|
992
1342
|
|
|
1343
|
+
## Migration: text length is bounded
|
|
1344
|
+
|
|
1345
|
+
`INTERPRET_TEXT_LIMIT` is 65,536 UTF-16 units, measured by the raw string's `length`.
|
|
1346
|
+
The built-in `Normalizer.normalize` throws `InterpretError('TEXT_LIMIT')` above that
|
|
1347
|
+
limit, before substitutions or whitespace cleanup. `scanNumbers` and direct
|
|
1348
|
+
`Extractor.extract` calls meet the same limit. There is no option to raise it.
|
|
1349
|
+
Custom normalizer implementations must honor the same input bound.
|
|
1350
|
+
|
|
1351
|
+
`Interpret.interpret` captures this refusal as a `TEXT_LIMIT` stage failure, emits the
|
|
1352
|
+
original error, and returns an incomplete interpretation with no subject. A direct stage
|
|
1353
|
+
caller catches the coded error. Callers that previously sent larger messages must shorten
|
|
1354
|
+
them or divide them into independently meaningful requests before calling the reader.
|
|
1355
|
+
|
|
1356
|
+
## Migration: carrying is opt-in
|
|
1357
|
+
|
|
1358
|
+
A reused `Interpret` no longer carries values between messages by default.
|
|
1359
|
+
`DEFAULT_INTERPRET_HISTORY` is 0. This prevents one person's unstated fields
|
|
1360
|
+
from being filled by another person's earlier request.
|
|
1361
|
+
|
|
1362
|
+
For turns belonging to one person, set `history: 16` on `createInterpret` or
|
|
1363
|
+
`Interpret` to retain the previous window. When supplying a shared `context`,
|
|
1364
|
+
set `history` on that context instead. Any positive cap enables history;
|
|
1365
|
+
there is no minimum of three. With the default, `previous()` and `entities()`
|
|
1366
|
+
are empty even after a result is added. Subject and definition registries
|
|
1367
|
+
remain separate and are still populated for generated results.
|
|
1368
|
+
|
|
993
1369
|
## Tests
|
|
994
1370
|
|
|
995
1371
|
- [`tests/guides.test.ts`](../tests/guides.test.ts) — the `## Surface` ↔ `src/core` bijection (value and type exports), each behavioral interface ↔ its implementing class method bijection, and the equality gate: every `Summary` cell against its declaration's description paragraph, the titled `Interpret text against an added recipe` fence against the `@example` block of that title (pinned so the titled pair cannot be retired silently), and the README pitch against this guide's tagline. It also runs the flagship fences and asserts the values their comments claim.
|
|
@@ -997,12 +1373,12 @@ interpret.destroy()
|
|
|
997
1373
|
- [`tests/src/core/InterpretContext.test.ts`](../tests/src/core/InterpretContext.test.ts) — the capped ring buffer, the flattened entity read carry-over consults, `clear` against `destroy`, and the emitted events.
|
|
998
1374
|
- [`tests/src/core/Narrator.test.ts`](../tests/src/core/Narrator.test.ts) — every lookup total against an adversarial key, the documented fallback of each primitive, and the composed `describe` and `narrate` renderings.
|
|
999
1375
|
- [`tests/src/core/factories.test.ts`](../tests/src/core/factories.test.ts) — each factory returns a working entity, and honors the options it declares.
|
|
1000
|
-
- [`tests/src/core/helpers.test.ts`](../tests/src/core/helpers.test.ts) — the pure leaves: escaping, copy-on-write field writes and their prototype-pollution refusal, replacement and whitespace collapse, tokenizing, numeric mining, entity assignment, intent classification,
|
|
1376
|
+
- [`tests/src/core/helpers.test.ts`](../tests/src/core/helpers.test.ts) — the pure leaves: escaping, copy-on-write field writes and their prototype-pollution refusal, replacement and whitespace collapse, tokenizing, numeric mining, entity assignment, intent classification, canonicalization and digesting, recipe scoring and matching, expression variables and resolution, and subject rendering.
|
|
1001
1377
|
- [`tests/src/core/parsers.test.ts`](../tests/src/core/parsers.test.ts) — `parseRecipe` returns a recipe, or `undefined` on invalid JSON and on a shape that fails `isRecipe`.
|
|
1002
1378
|
- [`tests/src/core/validators.test.ts`](../tests/src/core/validators.test.ts) — every guard stays total against junk, cycles, and hostile prototypes, with the exact posture for an input record and the open posture for a result record.
|
|
1003
1379
|
- [`tests/src/core/stages/Normalizer.test.ts`](../tests/src/core/stages/Normalizer.test.ts) — the substitution order, the recorded changes, and the final whitespace collapse.
|
|
1004
1380
|
- [`tests/src/core/stages/Extractor.test.ts`](../tests/src/core/stages/Extractor.test.ts) — intent classification against caller vocabularies, and numeric mining, with no recipe in sight.
|
|
1005
|
-
- [`tests/src/core/stages/Clarifier.test.ts`](../tests/src/core/stages/Clarifier.test.ts) — resolution order across fresh entities, same-domain carry-over,
|
|
1381
|
+
- [`tests/src/core/stages/Clarifier.test.ts`](../tests/src/core/stages/Clarifier.test.ts) — resolution order across fresh entities, same-domain carry-over, what the door fills, repairs, and refuses, and dependency-ordered computed fields, plus the ambiguity every refusal and every below-floor required mapping raises.
|
|
1006
1382
|
- [`tests/src/core/stages/Formatter.test.ts`](../tests/src/core/stages/Formatter.test.ts) — the clause assembly through the narrator's `prompt.*` lines, and the verb fallback.
|
|
1007
1383
|
- [`tests/src/core/stages/Generator.test.ts`](../tests/src/core/stages/Generator.test.ts) — the entity-to-field rule, the single-element unwrap, the mean confidence, and the field audit.
|
|
1008
1384
|
- [`tests/src/core/managers/RecordManager.test.ts`](../tests/src/core/managers/RecordManager.test.ts) — the content hash and version rule, the all-or-nothing batch `remove`, the emitted events, and idempotent teardown.
|