@orkestrel/interpret 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Orkestrel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,84 @@
+# @orkestrel/interpret
+
+A zero-dependency, synchronous, deterministic bidirectional bridge between
+natural language and the [`@orkestrel/reason`](https://github.com/orkestrel/reason)
+engine. FORWARD: raw text is normalized, classified into an intent, matched
+against a registered `Template`, mined for numeric entities, clarified
+(carry-over / defaults / computed fields), formatted into a refined prompt,
+then generated into a `Subject` + `Definition` pair ready for
+`Reason.reason`. REVERSE: a `Definition` / `Subject` / `ReasonResult`
+renders to display-neutral prose through a lexicon-driven `Narrator`.
+Nothing here is an LLM, provider, or agent. Environment-agnostic — no I/O,
+no browser or server assumptions. Part of the `@orkestrel` line.
+
+## Install
+
+```sh
+npm install @orkestrel/interpret
+```
+
+## Requirements
+
+- Node.js >= 24
+- ESM-only (no CommonJS build)
+- Runtime dependencies: [`@orkestrel/reason`](https://github.com/orkestrel/reason),
+  [`@orkestrel/contract`](https://github.com/orkestrel/contract),
+  [`@orkestrel/emitter`](https://github.com/orkestrel/emitter)
+
+## Usage
+
+```ts
+import { createInterpret } from '@orkestrel/interpret'
+import { factorGroup, fieldFactor, quantitativeDefinition } from '@orkestrel/reason'
+
+const interpret = createInterpret({
+	extractor: {
+		extract: () => ({
+			intent: { action: 'calculate', domain: 'arithmetic', confidence: 1 },
+			numbers: [42],
+			complete: true,
+		}),
+	},
+	templates: [
+		{
+			id: 't1',
+			name: 'Arithmetic',
+			domain: 'arithmetic',
+			intents: ['calculate'],
+			mappings: [{ entity: 'value', aliases: [], field: 'value' }],
+			defaults: [],
+			computations: [],
+			definition: quantitativeDefinition('t1', 'Arithmetic', [
+				factorGroup('total', 'sum', [fieldFactor('value', 'value')]),
+			]),
+		},
+	],
+})
+
+const result = interpret.interpret('calculate arithmetic 42')
+result.subject // { value: 42 }
+
+interpret.destroy()
+```
+
+`interpret()` is genuinely synchronous and runs the fixed five-stage
+pipeline `[normalize, extract, clarify, format, generate]`. A `NO_TEMPLATE`
+/ `LOW_CONFIDENCE` non-match, or a thrown stage, both yield a visible
+INCOMPLETE result rather than an arbitrary fallback.
+
+## Guide
+
+For the full surface — the `Interpret` orchestrator, the five pipeline
+stages, the template/subject/definition managers, the cross-turn context,
+the lexicon-driven `Narrator`, helpers, validators, factories, errors, and
+the observation surface — see
+[`guides/src/interpret.md`](guides/src/interpret.md).
+
+## Package
+
+Published as a single typed entry point per the `exports` field in
+`package.json`.
+
+## License
+
+MIT © [Orkestrel](https://github.com/orkestrel) — see [LICENSE](./LICENSE).