@orkestrel/scaffold 0.0.120 → 0.0.122
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-dispatch/scripts/brief.js +57 -9
- package/dist/agents/skills/orkestrel-dispatch/scripts/chain.js +22 -2
- package/dist/agents/skills/orkestrel-publish/scripts/pins.js +5 -5
- package/dist/agents/skills/orkestrel-publish/scripts/wave.js +67 -5
- package/dist/bin/main.js +5 -5
- package/dist/bin/main.js.map +1 -1
- package/dist/host/agents/orchestration.md +16 -11
- package/dist/host/agents/skills/orkestrel-dispatch/SKILL.md +4 -4
- package/dist/host/agents/skills/orkestrel-dispatch/references/launch.md +2 -1
- package/dist/host/agents/skills/orkestrel-dispatch/scripts/brief.ts +65 -9
- package/dist/host/agents/skills/orkestrel-dispatch/scripts/chain.ts +28 -2
- package/dist/host/agents/skills/orkestrel-falsify/references/brief.md +2 -1
- package/dist/host/agents/skills/orkestrel-harden/SKILL.md +8 -8
- package/dist/host/agents/skills/orkestrel-harden/references/hardening.md +3 -3
- package/dist/host/agents/skills/orkestrel-parallel/SKILL.md +2 -2
- package/dist/host/agents/skills/orkestrel-publish/SKILL.md +10 -8
- package/dist/host/agents/skills/orkestrel-publish/references/release.md +2 -2
- package/dist/host/agents/skills/orkestrel-publish/references/wave.md +22 -8
- package/dist/host/agents/skills/orkestrel-publish/references/window.md +5 -1
- package/dist/host/agents/skills/orkestrel-publish/scripts/pins.ts +5 -5
- package/dist/host/agents/skills/orkestrel-publish/scripts/wave.ts +86 -7
- package/dist/host/claude/AGENTS.md +1 -1
- package/dist/host/claude/agents/analyst.md +1 -1
- package/dist/host/claude/agents/opus.md +7 -6
- package/dist/host/claude/agents/orkestrel.md +26 -26
- package/dist/host/claude/agents/planner.md +3 -3
- package/dist/host/claude/agents/reviewer.md +3 -3
- package/dist/host/claude/agents/verifier.md +1 -1
- package/dist/host/claude/rules/campaign.md +3 -2
- package/dist/host/claude/rules/names.md +13 -7
- package/dist/host/claude/rules/tests.md +1 -1
- package/dist/host/claude/rules/workspace.md +9 -0
- package/dist/host/claude/skills/orkestrel-harden/SKILL.md +1 -1
- package/dist/host/codex/agents/analyst.toml +2 -5
- package/dist/host/codex/agents/opus.toml +5 -3
- package/dist/host/codex/agents/planner.toml +6 -5
- package/dist/host/codex/agents/reviewer.toml +4 -7
- package/dist/host/codex/agents/verifier.toml +2 -2
- package/dist/host/dotfiles/gitignore +1 -2
- package/dist/host/guides/agent.md +5 -5
- package/dist/host/guides/brief.md +7 -15
- package/dist/host/guides/browser.md +1 -1
- package/dist/host/guides/capture.md +2 -2
- package/dist/host/guides/console.md +4 -30
- package/dist/host/guides/guide.md +0 -1
- package/dist/host/guides/interpret.md +165 -182
- package/dist/host/guides/lsp.md +26 -51
- package/dist/host/guides/mcp.md +220 -276
- package/dist/host/guides/middleware.md +14 -22
- package/dist/host/guides/ollama.md +1 -3
- package/dist/host/guides/probe.md +71 -80
- package/dist/host/guides/program.md +26 -35
- package/dist/host/guides/qualifier.md +0 -6
- package/dist/host/guides/queue.md +0 -4
- package/dist/host/guides/rater.md +6 -12
- package/dist/host/guides/relation.md +0 -2
- package/dist/host/guides/scaffold.md +18 -9
- package/dist/host/guides/sea.md +47 -51
- package/dist/host/guides/server.md +15 -19
- package/dist/host/guides/terminal.md +0 -26
- package/dist/host/guides/toolbox.md +0 -10
- package/dist/host/guides/worker.md +57 -57
- package/dist/host/guides/workflow.md +13 -26
- package/dist/host/guides/workspace.md +15 -21
- package/dist/host/manifest.json +63 -483
- package/dist/host/tests/config.test.ts +7 -0
- package/dist/src/core/index.cjs +13 -46
- package/dist/src/core/index.cjs.map +1 -1
- package/dist/src/core/index.js +13 -46
- package/dist/src/core/index.js.map +1 -1
- package/dist/src/server/index.cjs +10 -9
- package/dist/src/server/index.cjs.map +1 -1
- package/dist/src/server/index.d.cts +12 -8
- package/dist/src/server/index.d.ts +12 -8
- package/dist/src/server/index.js +10 -9
- package/dist/src/server/index.js.map +1 -1
- package/package.json +5 -5
- /package/dist/host/agents/skills/orkestrel-parallel/references/{claude.md → claude-code.md} +0 -0
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
> A synchronous, deterministic bidirectional bridge between natural language and the
|
|
4
4
|
> `@orkestrel/reason` engine: a forward pipeline that normalizes raw text, classifies its
|
|
5
|
-
> intent, matches an added `
|
|
5
|
+
> intent, matches an added `Recipe`, clarifies the fields extraction left open, and
|
|
6
6
|
> generates a `Subject` and `Definition` pair ready for `Reason.reason`, plus a reverse
|
|
7
7
|
> direction that renders a `Definition`, a `Subject`, or a `ReasonResult` to
|
|
8
8
|
> display-neutral prose through a lexicon-driven `Narrator`.
|
|
@@ -11,7 +11,7 @@ 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
|
-
|
|
14
|
+
recipe and mines the raw numbers; `clarify` resolves same-domain carry-over, recipe
|
|
15
15
|
defaults, and dependency-ordered computed fields. Every discriminant names its axis rather
|
|
16
16
|
than `kind` or `type`: `stage` splits the pipeline phases, `category` splits provenance, and
|
|
17
17
|
`code` splits coded errors. Source: [`src/core`](../src/core). Surfaced through the
|
|
@@ -19,9 +19,9 @@ than `kind` or `type`: `stage` splits the pipeline phases, `category` splits pro
|
|
|
19
19
|
|
|
20
20
|
## Surface
|
|
21
21
|
|
|
22
|
-
### Interpret text against an added
|
|
22
|
+
### Interpret text against an added recipe
|
|
23
23
|
|
|
24
|
-
Add a
|
|
24
|
+
Add a recipe, interpret text through the normalize, extract, clarify, format, and generate
|
|
25
25
|
pipeline, then render the result back to prose:
|
|
26
26
|
|
|
27
27
|
```ts
|
|
@@ -37,7 +37,7 @@ const interpret = createInterpret({
|
|
|
37
37
|
actions: { calculate: 'calculate' },
|
|
38
38
|
domains: { arithmetic: ['arithmetic'] },
|
|
39
39
|
}),
|
|
40
|
-
|
|
40
|
+
recipes: [
|
|
41
41
|
{
|
|
42
42
|
id: 't1',
|
|
43
43
|
name: 'Arithmetic',
|
|
@@ -64,84 +64,80 @@ interpret.destroy()
|
|
|
64
64
|
```
|
|
65
65
|
|
|
66
66
|
`interpret()` is genuinely synchronous and runs the fixed pipeline
|
|
67
|
-
`[normalize, extract, clarify, format, generate]`. A `
|
|
67
|
+
`[normalize, extract, clarify, format, generate]`. A `NO_RECIPE` or `LOW_CONFIDENCE`
|
|
68
68
|
non-match, and a thrown stage, each yield a visible incomplete `Interpretation` rather than
|
|
69
|
-
throwing, and never an arbitrary fallback
|
|
69
|
+
throwing, and never an arbitrary fallback recipe. An interpretation is complete when
|
|
70
70
|
`ambiguities` and `failures` are both empty; no stored flag repeats that fact.
|
|
71
71
|
|
|
72
72
|
### Types
|
|
73
73
|
|
|
74
|
-
|
|
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
|
-
| `
|
|
134
|
-
| `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. |
|
|
135
|
-
| `InterpretInterface` | interface | `{ emitter, interpret(), add(), remove(), template(), templates(), describe(), narrate(), destroy() }` | Represents the interpretation orchestrator — the sole public entry point, mirroring `reasons`' `Reason` orchestrator shape. |
|
|
74
|
+
| Name | Kind | Signature | Summary |
|
|
75
|
+
| ---------------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
76
|
+
| `ProvenanceCategory` | type | `'extracted' \| 'carried' \| 'default' \| 'computed' \| 'subject'` | Names how one `FieldMapping` or `Entity` value was obtained. |
|
|
77
|
+
| `InterpretStage` | type | `'normalize' \| 'extract' \| 'clarify' \| 'format' \| 'generate'` | Names the fixed pipeline phases an `InterpretInterface#interpret` run produces one `StageRecord` for, in order. |
|
|
78
|
+
| `InterpretErrorCode` | type | `'NORMALIZE_FAILED' \| 'EXTRACT_FAILED' \| 'CLARIFY_FAILED' \| 'FORMAT_FAILED' \| 'GENERATE_FAILED' \| 'NO_RECIPE' \| 'LOW_CONFIDENCE' \| 'DESTROYED'` | Names the coded misuse or failure conditions thrown as an `InterpretError` or carried on a `StageFailure`. |
|
|
79
|
+
| `EntityMapping` | interface | `{ entity, aliases, field, required? }` | Represents one entity-extraction rule inside a `Recipe`: which literal alias phrases identify a value, and which subject field it lands on. |
|
|
80
|
+
| `FieldDefault` | interface | `{ field, value }` | Represents a fallback value a `Recipe` fills onto a field left unresolved by extraction. |
|
|
81
|
+
| `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`. |
|
|
82
|
+
| `Recipe` | interface | `{ id, name, domain, intents, mappings, defaults, computations, definition }` | Represents a named, versionable interpretation recipe: which intents it answers, how to mine entities for it, its fallback data, its computed fields, and the reasons `Definition` it ultimately produces a `Subject` for. |
|
|
83
|
+
| `Provenance` | interface | `{ category, detail? }` | Describes how one value landed — its origin category plus an optional strategy detail. |
|
|
84
|
+
| `Intent` | interface | `{ action?, domain?, confidence }` | Represents the classified action + domain for one interpretation, with a combined confidence. |
|
|
85
|
+
| `Entity` | interface | `{ name, value, provenance, confidence }` | Represents one value assigned to a recipe's entity mapping, with its provenance and confidence. |
|
|
86
|
+
| `Ambiguity` | interface | `{ field, question, candidates, required }` | Represents an unresolved field surfaced as a human-readable question, never bare prose. |
|
|
87
|
+
| `FieldMapping` | interface | `{ field, entity?, value, provenance, confidence }` | Represents one audited field of the built subject — its resolved value, provenance, and confidence. |
|
|
88
|
+
| `TextChange` | interface | `{ from, to }` | Represents one normalization substitution applied to the raw text. |
|
|
89
|
+
| `StageRecord` | interface | `{ stage, input, output, failed, error? }` | Represents a structured input/output snapshot of one pipeline phase. |
|
|
90
|
+
| `StageFailure` | interface | `{ stage, code, message }` | Represents a visible marker for a stage that threw, carrying its coded reason. |
|
|
91
|
+
| `NormalizeResult` | interface | `{ text, changes }` | Represents the `Normalizer` stage's output: the cleaned text plus every substitution applied. |
|
|
92
|
+
| `ExtractResult` | interface | `{ intent, numbers }` | Represents the `Extractor` stage's output: intent classification plus raw numbers. |
|
|
93
|
+
| `ClarifyResult` | interface | `{ entities, ambiguities }` | Represents the `Clarifier` stage's output: resolved entities plus any remaining ambiguities. |
|
|
94
|
+
| `FormatResult` | interface | `{ prompt }` | Represents the `Formatter` stage's output: the refined natural-language prompt. |
|
|
95
|
+
| `GenerateResult` | interface | `{ subject, definition, mappings, confidence }` | Represents the `Generator` stage's output: the built subject/definition pair plus its full field audit. |
|
|
96
|
+
| `Interpretation` | interface | `{ text, normalized, intent, entities, subject?, definition?, mappings, ambiguities, prompt, stages, failures, confidence, digest }` | Represents the full, replayable outcome of one `interpret()` call. |
|
|
97
|
+
| `RecipeRecord` | interface | `{ id, recipe, version, hash }` | Represents a versioned, content-hashed `Recipe` as held by a `RecipeManagerInterface`. |
|
|
98
|
+
| `SubjectRecord` | interface | `{ id, subject, version, hash }` | Represents a versioned, content-hashed `Subject` as held by a `SubjectManagerInterface`. |
|
|
99
|
+
| `DefinitionRecord` | interface | `{ id, definition, version, hash }` | Represents a versioned, content-hashed `Definition` as held by a `DefinitionManagerInterface`. |
|
|
100
|
+
| `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`. |
|
|
101
|
+
| `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`). |
|
|
102
|
+
| `RecipeManagerEventMap` | type | `RecordEventMap` | Represents the push observation surface of a `RecipeManagerInterface`. |
|
|
103
|
+
| `SubjectManagerEventMap` | type | `RecordEventMap` | Represents the push observation surface of a `SubjectManagerInterface`, whose `add` carries the own-minted record id. |
|
|
104
|
+
| `DefinitionManagerEventMap` | type | `RecordEventMap` | Represents the push observation surface of a `DefinitionManagerInterface`. |
|
|
105
|
+
| `InterpretContextEventMap` | type | `{ readonly add: readonly [digest: string]; readonly clear: readonly []; readonly destroy: readonly []; }` | Represents the push observation surface of an `InterpretContextInterface`. |
|
|
106
|
+
| `NarratorFormatter` | type | `(value: unknown) => string` | Represents a pure formatting function for one lexicon `value()` unit. |
|
|
107
|
+
| `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. |
|
|
108
|
+
| `NarratorOptions` | interface | `{ lexicon?, formatters? }` | Represents the options for `createNarrator` and the `Narrator` constructor. |
|
|
109
|
+
| `NormalizerOptions` | interface | `{ contractions?, abbreviations?, corrections? }` | Represents the options for `createNormalizer` and the `Normalizer` constructor. |
|
|
110
|
+
| `ExtractorOptions` | interface | `{ actions?, domains? }` | Represents the options for `createExtractor` and the `Extractor` constructor. |
|
|
111
|
+
| `ClarifierOptions` | interface | `{ floor?, narrator? }` | Represents the options for `createClarifier` and the `Clarifier` constructor. |
|
|
112
|
+
| `FormatterOptions` | interface | `{ verbs?, narrator? }` | Represents the options for `createFormatter` and the `Formatter` constructor. |
|
|
113
|
+
| `RecipeManagerOptions` | interface | `{ recipes?, on?, error? }` | Represents the options for `createRecipeManager` and the `RecipeManager` constructor — the initial seed collection. |
|
|
114
|
+
| `SubjectManagerOptions` | interface | `{ subjects?, on?, error? }` | Represents the options for `createSubjectManager` and the `SubjectManager` constructor — the initial seed collection. |
|
|
115
|
+
| `DefinitionManagerOptions` | interface | `{ definitions?, on?, error? }` | Represents the options for `createDefinitionManager` and the `DefinitionManager` constructor — the initial seed collection. |
|
|
116
|
+
| `RecordStamp` | interface | `{ id, version, hash }` | Represents the identity, version, and content hash a `RecordManagerInterface` derives for one record before its concrete shape is built. |
|
|
117
|
+
| `RecordFunction` | type | `(stamp: RecordStamp, value: TValue) => TRecord` | Builds one concrete record from the `RecordStamp` its registry derived and the value that record holds. |
|
|
118
|
+
| `RecordManagerOptions` | interface | `{ entity, on?, error? }` | Represents the options for the `RecordManager` constructor. |
|
|
119
|
+
| `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. |
|
|
120
|
+
| `RecordOptions` | interface | `{ id? }` | Represents the per-call options for the record a manager's `add` mints. |
|
|
121
|
+
| `InterpretContextOptions` | interface | `{ session?, history?, on?, error? }` | Represents the options for `createInterpretContext` and the `InterpretContext` constructor. |
|
|
122
|
+
| `InterpretOptions` | interface | `{ recipes?, context?, normalizer?, extractor?, clarifier?, formatter?, generator?, similarity?, floor?, history?, narrator?, on?, error? }` | Represents the options for `createInterpret` and the `Interpret` constructor. |
|
|
123
|
+
| `NormalizerInterface` | interface | `{ normalize() }` | Represents the `Normalizer` stage contract: raw text in, cleaned text + applied changes out. |
|
|
124
|
+
| `ExtractorInterface` | interface | `{ extract() }` | Represents the `Extractor` stage contract: recipe-agnostic intent classification + raw number mining. |
|
|
125
|
+
| `ClarifierInterface` | interface | `{ clarify() }` | Represents the `Clarifier` stage contract: resolve carry-over, defaults, and computed fields against a set of already-assigned entities, surfacing ambiguities for anything required that stays unresolved. |
|
|
126
|
+
| `FormatterInterface` | interface | `{ format() }` | Represents the `Formatter` stage contract: render the refined natural-language prompt for a matched recipe. |
|
|
127
|
+
| `GeneratorInterface` | interface | `{ generate() }` | Represents the `Generator` stage contract: build the final subject/definition pair plus its field audit. |
|
|
128
|
+
| `NarratorInterface` | interface | `{ phrase(), label(), line(), value(), describe(), narrate() }` | Represents the `Narrator` contract — a stateless, total, lexicon-driven rendering engine for the reverse direction. |
|
|
129
|
+
| `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. |
|
|
130
|
+
| `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). |
|
|
131
|
+
| `DefinitionManagerInterface` | interface | `{ emitter, count, has(), definition(), definitions(), add(), remove(), destroy() }` | Represents the definition registry — a self-owning, versioned/hashed record-holder. |
|
|
132
|
+
| `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. |
|
|
133
|
+
| `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. |
|
|
136
134
|
|
|
137
135
|
### Constants
|
|
138
136
|
|
|
139
|
-
A `Shape` cell holds the constant's declared type.
|
|
140
|
-
|
|
141
137
|
| Name | Kind | Signature | Summary |
|
|
142
138
|
| ------------------------------ | ----- | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
143
139
|
| `DEFAULT_INTERPRET_SIMILARITY` | const | `0.8` | Names the default `similarity` for `createInterpret` and `matchAlias`, 0.8 — the fuzzy alias-match score threshold, between 0 and 1. |
|
|
144
|
-
| `DEFAULT_INTERPRET_FLOOR` | const | `0.3` | Names the default `floor` for `createInterpret` and `
|
|
140
|
+
| `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. |
|
|
145
141
|
| `DEFAULT_INTERPRET_HISTORY` | const | `16` | Names the default `history` cap for an `InterpretContext`'s `previous()` ring buffer, 16. |
|
|
146
142
|
| `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`. |
|
|
147
143
|
| `INTERPRET_STAGES` | const | `readonly InterpretStage[]` | Lists every `InterpretStage` literal in pipeline order, frozen — the one home the result guards check the union from. |
|
|
@@ -151,10 +147,9 @@ A `Shape` cell holds the constant's declared type.
|
|
|
151
147
|
| `CONFIDENCE_COLLECT` | const | `0.9` | Names the confidence assigned when a single entity mapping collects every extracted number, 0.9. |
|
|
152
148
|
| `CONFIDENCE_POSITIONAL` | const | `0.7` | Names the confidence assigned to a positional (order-based) entity match fallback, 0.7. |
|
|
153
149
|
| `CONFIDENCE_CARRIED` | const | `0.7` | Names the confidence assigned to a same-domain carried-over field, 0.7. |
|
|
154
|
-
| `CONFIDENCE_DEFAULT` | const | `1` | Names the confidence assigned to a
|
|
150
|
+
| `CONFIDENCE_DEFAULT` | const | `1` | Names the confidence assigned to a recipe default fill, 1. |
|
|
155
151
|
| `CONFIDENCE_COMPUTED` | const | `0.9` | Names the confidence assigned to a successfully resolved computed field, 0.9. |
|
|
156
152
|
| `NUMBER_PATTERN` | const | `RegExp` | Holds the numeric-entity extraction pattern shared by `extractNumbers` and `assignEntities` — an optional leading `$`, thousands-comma-grouped digits, an optional decimal fraction, and an optional trailing `%`. |
|
|
157
|
-
| `UNSAFE_FIELD_SEGMENTS` | const | `readonly string[]` | Lists the prototype-pollution-unsafe field-path segments, `__proto__`, `prototype`, and `constructor` — `setField` refuses to write any path containing one, and returns its input unchanged. |
|
|
158
153
|
| `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. |
|
|
159
154
|
| `DEFAULT_LEXICON` | const | `Lexicon` | Holds the neutral default `Lexicon` a `Narrator` merges caller data over. |
|
|
160
155
|
|
|
@@ -173,7 +168,6 @@ import {
|
|
|
173
168
|
DEFAULT_INTERPRET_SIMILARITY,
|
|
174
169
|
DEFAULT_LEXICON,
|
|
175
170
|
NUMBER_PATTERN,
|
|
176
|
-
UNSAFE_FIELD_SEGMENTS,
|
|
177
171
|
} from '@orkestrel/interpret'
|
|
178
172
|
|
|
179
173
|
DEFAULT_INTERPRET_SIMILARITY // 0.8
|
|
@@ -187,7 +181,6 @@ CONFIDENCE_CARRIED // 0.7
|
|
|
187
181
|
CONFIDENCE_DEFAULT // 1
|
|
188
182
|
CONFIDENCE_COMPUTED // 0.9
|
|
189
183
|
NUMBER_PATTERN.source // the numeric-entity pattern
|
|
190
|
-
UNSAFE_FIELD_SEGMENTS // ['__proto__', 'prototype', 'constructor']
|
|
191
184
|
DEFAULT_CONTRACTIONS["can't"] // 'cannot'
|
|
192
185
|
DEFAULT_LEXICON.templates?.['subject.empty'] // 'with no fields'
|
|
193
186
|
DEFAULT_LEXICON.templates?.['prompt.base'] // '{{verb}} {{name}}'
|
|
@@ -224,14 +217,12 @@ published member conforms, because a foreign engine's return is not this package
|
|
|
224
217
|
`interpret` return with `isInterpretation` before dereferencing `intent`, `entities`, or
|
|
225
218
|
`ambiguities`. Each row's `Summary` names the posture its guard takes.
|
|
226
219
|
|
|
227
|
-
In a guard table a `Shape` cell holds the type the guard narrows to.
|
|
228
|
-
|
|
229
220
|
| Name | Kind | Signature | Summary |
|
|
230
221
|
| ------------------ | -------- | --------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
231
222
|
| `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. |
|
|
232
|
-
| `isFieldDefault` | function | `(value: unknown) => value is FieldDefault` | Determines whether a value is an exact `FieldDefault` input record — a fallback value a `
|
|
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. |
|
|
233
224
|
| `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. |
|
|
234
|
-
| `
|
|
225
|
+
| `isRecipe` | function | `(value: unknown) => value is Recipe` | Determines whether a value is an exact `Recipe` input record — a named, versionable interpretation recipe. |
|
|
235
226
|
| `isProvenance` | function | `(value: unknown) => value is Provenance` | Determines whether a value is an open `Provenance` result record. |
|
|
236
227
|
| `isIntent` | function | `(value: unknown) => value is Intent` | Determines whether a value is an open `Intent` result record. |
|
|
237
228
|
| `isEntity` | function | `(value: unknown) => value is Entity` | Determines whether a value is an open `Entity` result record. |
|
|
@@ -255,7 +246,7 @@ import {
|
|
|
255
246
|
isProvenance,
|
|
256
247
|
isStageFailure,
|
|
257
248
|
isStageRecord,
|
|
258
|
-
|
|
249
|
+
isRecipe,
|
|
259
250
|
} from '@orkestrel/interpret'
|
|
260
251
|
import {
|
|
261
252
|
createFactorGroup,
|
|
@@ -274,7 +265,7 @@ isComputedField({
|
|
|
274
265
|
right: { form: 'constant', value: 12 },
|
|
275
266
|
},
|
|
276
267
|
}) // true
|
|
277
|
-
|
|
268
|
+
isRecipe({
|
|
278
269
|
id: 't1',
|
|
279
270
|
name: 'Arithmetic',
|
|
280
271
|
domain: 'arithmetic',
|
|
@@ -306,35 +297,27 @@ behind the `Interpret` orchestrator and its stages.
|
|
|
306
297
|
|
|
307
298
|
| Name | Kind | Signature | Summary |
|
|
308
299
|
| -------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
|
|
309
|
-
| `escapeRegExp` | function | `(text: string) => string` | Escapes every regex metacharacter in `text` so it matches literally when compiled into a `RegExp`. |
|
|
310
300
|
| `setField` | function | `(subject: Subject, field: FieldPath, value: unknown) => Subject` | Writes a value at a (possibly nested) field path on a subject, copy-on-write. |
|
|
311
301
|
| `applyReplacements` | function | `(text: string, map: Readonly<Record<string, string>>) => string` | Replaces every whole-word occurrence of a map's keys with their values. |
|
|
312
302
|
| `collapseWhitespace` | function | `(text: string) => string` | Collapses every run of whitespace to a single space and trims the ends. |
|
|
313
303
|
| `tokenize` | function | `(text: string) => readonly string[]` | Splits text into lowercase tokens, stripping punctuation outside a small numeric/currency-safe allowlist. |
|
|
314
304
|
| `extractNumbers` | function | `(text: string) => readonly number[]` | Mines every numeric literal from text — optional leading `$`, thousands commas, an optional decimal fraction, an optional trailing `%`. |
|
|
315
|
-
| `assignEntities` | function | `(numbers: readonly number[], mappings: readonly EntityMapping[], text: string, similarity: number) => readonly Entity[]` | Assigns already-extracted numbers to a matched
|
|
305
|
+
| `assignEntities` | function | `(numbers: readonly number[], mappings: readonly EntityMapping[], text: string, similarity: number) => readonly Entity[]` | Assigns already-extracted numbers to a matched recipe's entity mappings. |
|
|
316
306
|
| `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. |
|
|
317
307
|
| `scoreSimilarity` | function | `(a: string, b: string) => number` | Measures bigram (Dice coefficient) string similarity, case-insensitive. |
|
|
318
308
|
| `matchAlias` | function | `(token: string, aliases: readonly string[], threshold: number) => number` | Returns the best `scoreSimilarity` a token achieves against a list of aliases, gated by a threshold. |
|
|
319
309
|
| `canonicalize` | function | `(value: unknown) => string` | Renders a value into a canonical, key-order-stable string — the pre-image of `digestValue`. |
|
|
320
310
|
| `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. |
|
|
321
311
|
| `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. |
|
|
322
|
-
| `
|
|
323
|
-
| `
|
|
312
|
+
| `scoreRecipe` | function | `(intent: Intent, recipe: Recipe) => number` | Scores how well a classified intent matches one recipe's domain + action. |
|
|
313
|
+
| `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. |
|
|
324
314
|
| `variablesOf` | function | `(expression: SymbolicExpression) => readonly string[]` | Collects every variable name referenced by a symbolic expression tree, in first-occurrence order. |
|
|
325
315
|
| `resolveExpression` | function | `(expression: SymbolicExpression, bindings: Readonly<Record<string, number>>) => number \| undefined` | Evaluates a symbolic expression tree against resolved bindings. |
|
|
326
316
|
| `renderSubject` | function | `(subject: Subject, narrator: NarratorInterface) => string` | Renders a one-line, display-neutral description of a reasons `Subject`, through an injected `Narrator`. |
|
|
327
317
|
|
|
328
318
|
```ts
|
|
329
|
-
import {
|
|
330
|
-
applyReplacements,
|
|
331
|
-
collapseWhitespace,
|
|
332
|
-
escapeRegExp,
|
|
333
|
-
setField,
|
|
334
|
-
tokenize,
|
|
335
|
-
} from '@orkestrel/interpret'
|
|
319
|
+
import { applyReplacements, collapseWhitespace, setField, tokenize } from '@orkestrel/interpret'
|
|
336
320
|
|
|
337
|
-
escapeRegExp('a.b*c') // 'a\\.b\\*c'
|
|
338
321
|
setField({ age: 25 }, 'age', 30) // { age: 30 }
|
|
339
322
|
setField({}, ['address', 'city'], 'Reno') // { address: { city: 'Reno' } }
|
|
340
323
|
applyReplacements("can't stop", { "can't": 'cannot' }) // 'cannot stop'
|
|
@@ -343,7 +326,7 @@ tokenize('The rate is 85%.') // ['the', 'rate', 'is', '85%.']
|
|
|
343
326
|
```
|
|
344
327
|
|
|
345
328
|
Extraction, classification, and fuzzy matching — the leaves behind
|
|
346
|
-
`Extractor#extract` and
|
|
329
|
+
`Extractor#extract` and recipe entity assignment:
|
|
347
330
|
|
|
348
331
|
```ts
|
|
349
332
|
import {
|
|
@@ -365,27 +348,27 @@ scoreSimilarity('rate', 'rate') // 1
|
|
|
365
348
|
matchAlias('valu', ['value', 'amount'], 0.6) // ~0.86 — fuzzy hit on 'value'
|
|
366
349
|
```
|
|
367
350
|
|
|
368
|
-
Digest,
|
|
351
|
+
Digest, recipe matching, computed-field resolution, and the reverse
|
|
369
352
|
direction:
|
|
370
353
|
|
|
371
354
|
```ts
|
|
372
|
-
import type {
|
|
355
|
+
import type { Recipe } from '@orkestrel/interpret'
|
|
373
356
|
import {
|
|
374
357
|
canonicalize,
|
|
375
358
|
canonicalizeNode,
|
|
376
359
|
createNarrator,
|
|
377
360
|
digestValue,
|
|
378
|
-
|
|
361
|
+
matchRecipe,
|
|
379
362
|
renderSubject,
|
|
380
363
|
resolveExpression,
|
|
381
|
-
|
|
364
|
+
scoreRecipe,
|
|
382
365
|
variablesOf,
|
|
383
366
|
} from '@orkestrel/interpret'
|
|
384
367
|
|
|
385
368
|
canonicalize({ b: 1, a: 2 }) === canonicalize({ a: 2, b: 1 }) // true
|
|
386
369
|
canonicalizeNode({ b: 1, a: 2 }, new Set()) // '{"a":2,"b":1}'
|
|
387
370
|
digestValue({ a: 1 }) === digestValue({ a: 1 }) // true — deterministic
|
|
388
|
-
|
|
371
|
+
matchRecipe({ confidence: 0 }, [], 0.3) // undefined — empty registry
|
|
389
372
|
variablesOf({
|
|
390
373
|
form: 'operation',
|
|
391
374
|
operator: 'divide',
|
|
@@ -404,7 +387,7 @@ resolveExpression(
|
|
|
404
387
|
renderSubject({ age: 25, income: 50000 }, createNarrator()) // 'with age: 25, income: 50000'
|
|
405
388
|
|
|
406
389
|
const gate = { action: 'compute', domain: 'rating', confidence: 1 }
|
|
407
|
-
const
|
|
390
|
+
const recipe: Recipe = {
|
|
408
391
|
id: 't1',
|
|
409
392
|
name: 'T',
|
|
410
393
|
domain: 'rating',
|
|
@@ -414,23 +397,23 @@ const template: Template = {
|
|
|
414
397
|
computations: [],
|
|
415
398
|
definition: { reasoning: 'symbolic', id: 't1', name: 'T', equations: [], variables: {} },
|
|
416
399
|
}
|
|
417
|
-
|
|
400
|
+
scoreRecipe(gate, recipe) // 1
|
|
418
401
|
```
|
|
419
402
|
|
|
420
403
|
### Parsers
|
|
421
404
|
|
|
422
405
|
Coercers — each returns its type or `undefined` off-shape, and never throws.
|
|
423
|
-
|
|
406
|
+
Recipe intake is total: an off-shape recipe returns `undefined`, and a
|
|
424
407
|
caller who wants a throw raises its own error from that `undefined`.
|
|
425
408
|
|
|
426
|
-
| Name
|
|
427
|
-
|
|
|
428
|
-
| `
|
|
409
|
+
| Name | Kind | Signature | Summary |
|
|
410
|
+
| ------------- | -------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------------ |
|
|
411
|
+
| `parseRecipe` | function | `(value: string) => Recipe \| undefined` | Parses a JSON string into a `Recipe`, or `undefined` on invalid JSON or a shape that fails `isRecipe`. |
|
|
429
412
|
|
|
430
413
|
```ts
|
|
431
|
-
import {
|
|
414
|
+
import { parseRecipe } from '@orkestrel/interpret'
|
|
432
415
|
|
|
433
|
-
|
|
416
|
+
parseRecipe('not json') // undefined
|
|
434
417
|
```
|
|
435
418
|
|
|
436
419
|
### Factories
|
|
@@ -439,11 +422,11 @@ parseTemplate('not json') // undefined
|
|
|
439
422
|
| ------------------------- | -------- | -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
440
423
|
| `createInterpret` | function | `(options?: InterpretOptions) => InterpretInterface` | Creates an interpretation orchestrator, returning an `InterpretInterface` seeded from `InterpretOptions`. |
|
|
441
424
|
| `createNormalizer` | function | `(options?: NormalizerOptions) => NormalizerInterface` | Creates a text normalizer, returning a stateless `NormalizerInterface`. |
|
|
442
|
-
| `createExtractor` | function | `(options?: ExtractorOptions) => ExtractorInterface` | Creates a
|
|
425
|
+
| `createExtractor` | function | `(options?: ExtractorOptions) => ExtractorInterface` | Creates a recipe-agnostic intent classifier and number extractor, returning a stateless `ExtractorInterface`. |
|
|
443
426
|
| `createClarifier` | function | `(options?: ClarifierOptions) => ClarifierInterface` | Creates a clarifier — carry-over, defaults, and computed-field resolution against an assigned entity set — returning a stateless `ClarifierInterface`. |
|
|
444
427
|
| `createFormatter` | function | `(options?: FormatterOptions) => FormatterInterface` | Creates a prompt formatter, returning a stateless `FormatterInterface`. |
|
|
445
428
|
| `createGenerator` | function | `() => GeneratorInterface` | Creates a subject and definition generator, returning a stateless `GeneratorInterface`. |
|
|
446
|
-
| `
|
|
429
|
+
| `createRecipeManager` | function | `(options?: RecipeManagerOptions) => RecipeManagerInterface` | Creates a recipe registry, returning a working `RecipeManagerInterface`. |
|
|
447
430
|
| `createSubjectManager` | function | `(options?: SubjectManagerOptions) => SubjectManagerInterface` | Creates a subject registry, returning a working `SubjectManagerInterface`. |
|
|
448
431
|
| `createDefinitionManager` | function | `(options?: DefinitionManagerOptions) => DefinitionManagerInterface` | Creates a definition registry, returning a working `DefinitionManagerInterface`. |
|
|
449
432
|
| `createInterpretContext` | function | `(options?: InterpretContextOptions) => InterpretContextInterface` | Creates a cross-turn interpretation context, returning a working `InterpretContextInterface`. |
|
|
@@ -461,7 +444,7 @@ import {
|
|
|
461
444
|
createNarrator,
|
|
462
445
|
createNormalizer,
|
|
463
446
|
createSubjectManager,
|
|
464
|
-
|
|
447
|
+
createRecipeManager,
|
|
465
448
|
} from '@orkestrel/interpret'
|
|
466
449
|
import {
|
|
467
450
|
createFactorGroup,
|
|
@@ -480,8 +463,8 @@ createGenerator()
|
|
|
480
463
|
createInterpretContext({ session: 'turn-1', history: 4 })
|
|
481
464
|
createNarrator({ lexicon: { templates: { 'subject.empty': 'nothing here' } } })
|
|
482
465
|
|
|
483
|
-
const
|
|
484
|
-
|
|
466
|
+
const recipes = createRecipeManager({
|
|
467
|
+
recipes: [
|
|
485
468
|
{
|
|
486
469
|
id: 't1',
|
|
487
470
|
name: 'Arithmetic',
|
|
@@ -496,8 +479,8 @@ const templates = createTemplateManager({
|
|
|
496
479
|
},
|
|
497
480
|
],
|
|
498
481
|
})
|
|
499
|
-
|
|
500
|
-
|
|
482
|
+
recipes.count // 1
|
|
483
|
+
recipes.destroy()
|
|
501
484
|
|
|
502
485
|
createSubjectManager({ subjects: [{ value: 1 }] }).count // 1
|
|
503
486
|
createDefinitionManager({
|
|
@@ -511,20 +494,20 @@ createDefinitionManager({
|
|
|
511
494
|
|
|
512
495
|
### Classes
|
|
513
496
|
|
|
514
|
-
| Name | Kind | Signature | Summary
|
|
515
|
-
| ------------------- | ----- | --------------------------------------------------------------------------------------------------------------------- |
|
|
516
|
-
| `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
|
|
517
|
-
| `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.
|
|
518
|
-
| `Normalizer` | class | `new (options?: NormalizerOptions) => NormalizerInterface` | Implements the normalize stage: applies contraction, abbreviation, and correction substitutions in order, then collapses whitespace.
|
|
519
|
-
| `Extractor` | class | `new (options?: ExtractorOptions) => ExtractorInterface` | Implements the extract stage:
|
|
520
|
-
| `Clarifier` | class | `new (options?: ClarifierOptions) => ClarifierInterface` | Implements the clarify stage: resolves same-domain carry-over,
|
|
521
|
-
| `Formatter` | class | `new (options?: FormatterOptions) => FormatterInterface` | Implements the format stage: renders the refined natural-language prompt for a matched
|
|
522
|
-
| `Generator` | class | `new () => GeneratorInterface` | Implements the generate stage: builds the final `Subject` from a fully resolved entity set, plus its complete field audit.
|
|
523
|
-
| `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.
|
|
524
|
-
| `
|
|
525
|
-
| `SubjectManager` | class | `new (options?: SubjectManagerOptions) => SubjectManagerInterface` | Implements the subject registry — a self-owning, versioned and content-hashed record-holder that mints its own record identity for every `Subject` (a `Subject` carries no `id` field of its own).
|
|
526
|
-
| `DefinitionManager` | class | `new (options?: DefinitionManagerOptions) => DefinitionManagerInterface` | Implements the definition registry — a self-owning, versioned and content-hashed record-holder for the reasons `Definition`s an interpretation produces.
|
|
527
|
-
| `InterpretContext` | class | `new (options?: InterpretContextOptions) => InterpretContextInterface` | Implements the cross-turn interpretation context — a capped, replayable history of completed `Interpretation`s plus the subject and definition registries carry-over reads from.
|
|
497
|
+
| Name | Kind | Signature | Summary |
|
|
498
|
+
| ------------------- | ----- | --------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
499
|
+
| `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
|
+
| `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
|
+
| `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 raw numeric-entity mining. |
|
|
503
|
+
| `Clarifier` | class | `new (options?: ClarifierOptions) => ClarifierInterface` | Implements the clarify stage: resolves same-domain carry-over, recipe defaults, and declaratively computed fields against an already-assigned entity set, surfacing an `Ambiguity` for every required mapping that stays unresolved. |
|
|
504
|
+
| `Formatter` | class | `new (options?: FormatterOptions) => FormatterInterface` | Implements the format stage: renders the refined natural-language prompt for a matched recipe. |
|
|
505
|
+
| `Generator` | class | `new () => GeneratorInterface` | Implements the generate stage: builds the final `Subject` from a fully resolved entity set, plus its complete field audit. |
|
|
506
|
+
| `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. |
|
|
507
|
+
| `RecipeManager` | class | `new (options?: RecipeManagerOptions) => RecipeManagerInterface` | Implements the recipe registry — a self-owning, versioned and content-hashed record-holder for the `Recipe`s an `Interpret` orchestrator matches against. |
|
|
508
|
+
| `SubjectManager` | class | `new (options?: SubjectManagerOptions) => SubjectManagerInterface` | Implements the subject registry — a self-owning, versioned and content-hashed record-holder that mints its own record identity for every `Subject` (a `Subject` carries no `id` field of its own). |
|
|
509
|
+
| `DefinitionManager` | class | `new (options?: DefinitionManagerOptions) => DefinitionManagerInterface` | Implements the definition registry — a self-owning, versioned and content-hashed record-holder for the reasons `Definition`s an interpretation produces. |
|
|
510
|
+
| `InterpretContext` | class | `new (options?: InterpretContextOptions) => InterpretContextInterface` | Implements the cross-turn interpretation context — a capped, replayable history of completed `Interpretation`s plus the subject and definition registries carry-over reads from. |
|
|
528
511
|
|
|
529
512
|
## Methods
|
|
530
513
|
|
|
@@ -568,9 +551,9 @@ extractor.extract('calculate my rate at 85')
|
|
|
568
551
|
|
|
569
552
|
#### `ClarifierInterface`
|
|
570
553
|
|
|
571
|
-
| Method | Returns | Summary
|
|
572
|
-
| --------- | --------------- |
|
|
573
|
-
| `clarify` | `ClarifyResult` | Resolves carry-over,
|
|
554
|
+
| Method | Returns | Summary |
|
|
555
|
+
| --------- | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
556
|
+
| `clarify` | `ClarifyResult` | Resolves carry-over, recipe defaults, and computed fields, and surfaces an `Ambiguity` for every unresolved required field, worded through the narrator's `ambiguity.entity` line. |
|
|
574
557
|
|
|
575
558
|
```ts
|
|
576
559
|
import { createClarifier } from '@orkestrel/interpret'
|
|
@@ -600,7 +583,7 @@ clarifier.clarify(
|
|
|
600
583
|
```
|
|
601
584
|
|
|
602
585
|
A computation addresses one numeric element of an array-valued field as
|
|
603
|
-
`{field}.{index}`, so a
|
|
586
|
+
`{field}.{index}`, so a recipe whose collection has a known length declares an
|
|
604
587
|
aggregate over it:
|
|
605
588
|
|
|
606
589
|
```ts
|
|
@@ -610,7 +593,7 @@ import { createOperation, createVariable } from '@orkestrel/reason'
|
|
|
610
593
|
// `value.0` and `value.1` name the first two elements of the array-valued
|
|
611
594
|
// `value` field. A collection whose length varies per turn has no declarable
|
|
612
595
|
// aggregate: `resolveExpression` returns `undefined` for an unbound variable,
|
|
613
|
-
// so a
|
|
596
|
+
// so a recipe naming `value.2` against a two-element array lands no `total`
|
|
614
597
|
// at all.
|
|
615
598
|
const clarifier = createClarifier({ floor: 0.3 })
|
|
616
599
|
clarifier.clarify(
|
|
@@ -643,9 +626,9 @@ clarifier.clarify(
|
|
|
643
626
|
|
|
644
627
|
#### `FormatterInterface`
|
|
645
628
|
|
|
646
|
-
| Method | Returns | Summary
|
|
647
|
-
| -------- | -------------- |
|
|
648
|
-
| `format` | `FormatResult` | Renders the refined natural-language prompt for a matched
|
|
629
|
+
| Method | Returns | Summary |
|
|
630
|
+
| -------- | -------------- | --------------------------------------------------------------------------------------------------------------------------- |
|
|
631
|
+
| `format` | `FormatResult` | Renders the refined natural-language prompt for a matched recipe, clause by clause through the narrator's `prompt.*` lines. |
|
|
649
632
|
|
|
650
633
|
```ts
|
|
651
634
|
import { createFormatter } from '@orkestrel/interpret'
|
|
@@ -676,9 +659,9 @@ formatter.format(
|
|
|
676
659
|
|
|
677
660
|
#### `GeneratorInterface`
|
|
678
661
|
|
|
679
|
-
| Method | Returns | Summary
|
|
680
|
-
| ---------- | ---------------- |
|
|
681
|
-
| `generate` | `GenerateResult` | Builds the final subject and definition pair plus its complete field audit, deriving no field the
|
|
662
|
+
| Method | Returns | Summary |
|
|
663
|
+
| ---------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------- |
|
|
664
|
+
| `generate` | `GenerateResult` | Builds the final subject and definition pair plus its complete field audit, deriving no field the recipe did not declare. |
|
|
682
665
|
|
|
683
666
|
```ts
|
|
684
667
|
import { createGenerator } from '@orkestrel/interpret'
|
|
@@ -794,31 +777,31 @@ notes.remove('n1') // true
|
|
|
794
777
|
notes.destroy()
|
|
795
778
|
```
|
|
796
779
|
|
|
797
|
-
#### `
|
|
780
|
+
#### `RecipeManagerInterface`
|
|
798
781
|
|
|
799
|
-
The self-owning, ordered registry over
|
|
800
|
-
|
|
782
|
+
The self-owning, ordered registry over recipes. `add` derives each record's `hash` from the
|
|
783
|
+
recipe's content and bumps `version` only when that hash changes. `remove`'s array form is
|
|
801
784
|
all-or-nothing. A call after `destroy()` throws `InterpretError('DESTROYED', …)`.
|
|
802
785
|
|
|
803
|
-
| Method
|
|
804
|
-
|
|
|
805
|
-
| `has`
|
|
806
|
-
| `
|
|
807
|
-
| `
|
|
808
|
-
| `add`
|
|
809
|
-
| `remove`
|
|
810
|
-
| `destroy`
|
|
786
|
+
| Method | Returns | Summary |
|
|
787
|
+
| --------- | --------------------------- | --------------------------------------------------------------------------------------------------------------------- |
|
|
788
|
+
| `has` | `boolean` | Reports whether a recipe with the given id has been added. |
|
|
789
|
+
| `recipe` | `RecipeRecord \| undefined` | Looks up one added recipe record by id — the singular accessor. |
|
|
790
|
+
| `recipes` | `readonly RecipeRecord[]` | Lists every added recipe record — the plural accessor. |
|
|
791
|
+
| `add` | `RecipeRecord` | Adds, or re-adds, one recipe from its data, and emits `add`. |
|
|
792
|
+
| `remove` | `boolean` (or `void`) | Removes the listed recipes by id, one recipe by id, or every recipe, and emits `remove` per removed id. |
|
|
793
|
+
| `destroy` | `void` | Tears the recipe registry down idempotently — clears the collection, emits `destroy`, then destroys the emitter last. |
|
|
811
794
|
|
|
812
795
|
```ts
|
|
813
|
-
import {
|
|
796
|
+
import { createRecipeManager } from '@orkestrel/interpret'
|
|
814
797
|
import {
|
|
815
798
|
createFactorGroup,
|
|
816
799
|
createFieldFactor,
|
|
817
800
|
createQuantitativeDefinition,
|
|
818
801
|
} from '@orkestrel/reason'
|
|
819
802
|
|
|
820
|
-
const
|
|
821
|
-
const record =
|
|
803
|
+
const recipes = createRecipeManager()
|
|
804
|
+
const record = recipes.add({
|
|
822
805
|
id: 't1',
|
|
823
806
|
name: 'Arithmetic',
|
|
824
807
|
domain: 'arithmetic',
|
|
@@ -831,17 +814,17 @@ const record = templates.add({
|
|
|
831
814
|
]),
|
|
832
815
|
})
|
|
833
816
|
record.version // 1
|
|
834
|
-
|
|
835
|
-
|
|
836
|
-
|
|
837
|
-
|
|
838
|
-
|
|
839
|
-
|
|
817
|
+
recipes.count // 1
|
|
818
|
+
recipes.has('t1') // true
|
|
819
|
+
recipes.recipe('t1') // the RecipeRecord, or undefined
|
|
820
|
+
recipes.recipes() // every added record
|
|
821
|
+
recipes.remove('t1') // true
|
|
822
|
+
recipes.destroy()
|
|
840
823
|
```
|
|
841
824
|
|
|
842
825
|
#### `SubjectManagerInterface`
|
|
843
826
|
|
|
844
|
-
Mirrors `
|
|
827
|
+
Mirrors `RecipeManagerInterface`, minting its own record ids (a `Subject`
|
|
845
828
|
carries no `id` field of its own) unless the caller overrides through
|
|
846
829
|
`RecordOptions.id`.
|
|
847
830
|
|
|
@@ -869,7 +852,7 @@ subjects.destroy()
|
|
|
869
852
|
|
|
870
853
|
#### `DefinitionManagerInterface`
|
|
871
854
|
|
|
872
|
-
Mirrors `
|
|
855
|
+
Mirrors `RecipeManagerInterface`, defaulting each record id to the
|
|
873
856
|
definition's own `id`.
|
|
874
857
|
|
|
875
858
|
| Method | Returns | Summary |
|
|
@@ -943,8 +926,8 @@ context.destroy()
|
|
|
943
926
|
|
|
944
927
|
#### `InterpretInterface`
|
|
945
928
|
|
|
946
|
-
`interpret` is genuinely synchronous. `add`, `remove`, `
|
|
947
|
-
same acts as the internal `
|
|
929
|
+
`interpret` is genuinely synchronous. `add`, `remove`, `recipe`, and `recipes` name the
|
|
930
|
+
same acts as the internal `RecipeManagerInterface` they delegate to, and `add` returns
|
|
948
931
|
`void` where the manager returns the record it minted. `describe` and `narrate` are the
|
|
949
932
|
reverse direction. After `destroy()` every method except the `emitter` getter and `destroy`
|
|
950
933
|
itself throws `InterpretError('DESTROYED', …)`; `destroy()` is idempotent, leaves a `context`
|
|
@@ -953,16 +936,16 @@ supplied-context half of that rule: `InterpretInterface` publishes no context ac
|
|
|
953
936
|
nothing outside reads the state of a context the orchestrator constructed itself or
|
|
954
937
|
subscribes to its emitter.
|
|
955
938
|
|
|
956
|
-
| Method | Returns
|
|
957
|
-
| ----------- |
|
|
958
|
-
| `interpret` | `Interpretation`
|
|
959
|
-
| `add` | `void`
|
|
960
|
-
| `remove` | `boolean` (or `void`)
|
|
961
|
-
| `
|
|
962
|
-
| `
|
|
963
|
-
| `describe` | `string`
|
|
964
|
-
| `narrate` | `string`
|
|
965
|
-
| `destroy` | `void`
|
|
939
|
+
| Method | Returns | Summary |
|
|
940
|
+
| ----------- | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
|
|
941
|
+
| `interpret` | `Interpretation` | Runs the `[normalize, extract, clarify, format, generate]` pipeline over raw text, returning a complete or a visibly incomplete result. |
|
|
942
|
+
| `add` | `void` | Adds one recipe, and emits `add`. |
|
|
943
|
+
| `remove` | `boolean` (or `void`) | Removes the listed recipes by id, one recipe by id, or every recipe. |
|
|
944
|
+
| `recipe` | `Recipe \| undefined` | Looks up one added recipe's plain data by id. |
|
|
945
|
+
| `recipes` | `readonly Recipe[]` | Lists every added recipe's plain data. |
|
|
946
|
+
| `describe` | `string` | Renders a reasons `Definition` to a one-line, display-neutral description. |
|
|
947
|
+
| `narrate` | `string` | Renders a reasons `ReasonResult` to a one-line, display-neutral description. |
|
|
948
|
+
| `destroy` | `void` | Tears the orchestrator down idempotently — the recipe registry, the context it constructed itself, then the emitter last. |
|
|
966
949
|
|
|
967
950
|
```ts
|
|
968
951
|
import { createExtractor, createInterpret } from '@orkestrel/interpret'
|
|
@@ -992,8 +975,8 @@ interpret.add({
|
|
|
992
975
|
})
|
|
993
976
|
const result = interpret.interpret('calculate arithmetic 42')
|
|
994
977
|
result.subject // { value: 42 }
|
|
995
|
-
interpret.
|
|
996
|
-
interpret.
|
|
978
|
+
interpret.recipe('t1') // the plain Recipe data
|
|
979
|
+
interpret.recipes() // every added recipe
|
|
997
980
|
interpret.describe(createQuantitativeDefinition('t1', 'Arithmetic', []))
|
|
998
981
|
interpret.narrate({
|
|
999
982
|
reasoning: 'symbolic',
|
|
@@ -1009,21 +992,21 @@ interpret.destroy()
|
|
|
1009
992
|
|
|
1010
993
|
## Tests
|
|
1011
994
|
|
|
1012
|
-
- [`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
|
|
1013
|
-
- [`tests/src/core/Interpret.test.ts`](../tests/src/core/Interpret.test.ts) — the orchestrator: the fixed pipeline and its per-stage records, the `
|
|
995
|
+
- [`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.
|
|
996
|
+
- [`tests/src/core/Interpret.test.ts`](../tests/src/core/Interpret.test.ts) — the orchestrator: the fixed pipeline and its per-stage records, the `NO_RECIPE` and `LOW_CONFIDENCE` incomplete results, a thrown stage marked on its record and on `failures`, the replay digest, the emitter surface, and teardown.
|
|
1014
997
|
- [`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.
|
|
1015
998
|
- [`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.
|
|
1016
999
|
- [`tests/src/core/factories.test.ts`](../tests/src/core/factories.test.ts) — each factory returns a working entity, and honors the options it declares.
|
|
1017
|
-
- [`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, similarity and alias matching, canonicalization and digesting,
|
|
1018
|
-
- [`tests/src/core/parsers.test.ts`](../tests/src/core/parsers.test.ts) — `
|
|
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, similarity and alias matching, canonicalization and digesting, recipe scoring and matching, expression variables and resolution, and subject rendering.
|
|
1001
|
+
- [`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`.
|
|
1019
1002
|
- [`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.
|
|
1020
1003
|
- [`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.
|
|
1021
|
-
- [`tests/src/core/stages/Extractor.test.ts`](../tests/src/core/stages/Extractor.test.ts) — intent classification against caller vocabularies, and numeric mining, with no
|
|
1004
|
+
- [`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.
|
|
1022
1005
|
- [`tests/src/core/stages/Clarifier.test.ts`](../tests/src/core/stages/Clarifier.test.ts) — resolution order across fresh entities, same-domain carry-over, defaults, and dependency-ordered computed fields, plus the ambiguity every unresolved required mapping raises.
|
|
1023
1006
|
- [`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.
|
|
1024
1007
|
- [`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.
|
|
1025
1008
|
- [`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.
|
|
1026
|
-
- [`tests/src/core/managers/
|
|
1009
|
+
- [`tests/src/core/managers/RecipeManager.test.ts`](../tests/src/core/managers/RecipeManager.test.ts) — the recipe accessors, the record id defaulting to `recipe.id`, and re-add versioning.
|
|
1027
1010
|
- [`tests/src/core/managers/SubjectManager.test.ts`](../tests/src/core/managers/SubjectManager.test.ts) — the minted record identity, the caller override, and the subject accessors.
|
|
1028
1011
|
- [`tests/src/core/managers/DefinitionManager.test.ts`](../tests/src/core/managers/DefinitionManager.test.ts) — the definition accessors and the record id defaulting to the definition's own `id`.
|
|
1029
1012
|
- [`tests/src/core/integration.test.ts`](../tests/src/core/integration.test.ts) — the forward and reverse directions driven together over a real corpus, through the public API.
|