From da7528954b1a9a63999bbe87351b55c95499be3d Mon Sep 17 00:00:00 2001 From: JarbasAi Date: Sat, 4 Jul 2026 14:01:05 +0100 Subject: [PATCH] =?UTF-8?q?docs:=20INTENT-3=20consistency=20review=20?= =?UTF-8?q?=E2=80=94=20dual-method=20registrations,=20method-keyed=20repla?= =?UTF-8?q?cement,=20required-slot=20semantics?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - An intent is defined by one or both methods; each individual registration uses exactly one, one registration per method (aligned with OVOS-INTENT-4 §3.2) (§2). - Replacement keyed on (skill id, intent name, language, method); the other method's registration is untouched (§6.1). - Required-slot failure: the engine MUST treat the intent as unmatched for that utterance; it MAY consider other templates of the same intent first (§5.3). - Slot map wording normalized; typing deferral restated as a timeless out-of-scope statement. Co-Authored-By: Claude Opus 4.8 --- CHANGELOG.md | 12 ++++++++++++ intent-3.md | 44 ++++++++++++++++++++++++++------------------ 2 files changed, 38 insertions(+), 18 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index ad47b45..991aeee 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -164,6 +164,18 @@ version 2: its `{{ … }}` sequences become substitution points, and its and §5.5 (the `.blacklist` suppression) renumber accordingly. - §7.1 — a handler MAY rely on `required_slots` being populated; all other slots remain optional and must be defended against. +- Consistency review, aligned with OVOS-INTENT-4 §3.2: §2 — an intent is + defined by one or both methods; each individual registration uses + exactly one, and an intent MAY carry one registration per method (two + training-data representations of the same handler). §6.1 — + registration replacement keyed on the + `(skill id, intent name, language, method)` quadruple; the + other-method registration for the same triple is untouched. §5.3 — + required-slot failure specified precisely: the engine MUST treat the + intent as unmatched for that utterance, and MAY consider other + templates of the same intent before concluding so. "Slot map" wording + normalized throughout; typing deferral restated as out of scope with + OVOS-INTENT-1 §5.3. ## OVOS-MSG-1 — Bus Message diff --git a/intent-3.md b/intent-3.md index 7dff006..6f5681e 100644 --- a/intent-3.md +++ b/intent-3.md @@ -16,7 +16,7 @@ It builds on the two companion specifications: The specifications are numbered in dependency order: read OVOS-INTENT-1 first, then OVOS-INTENT-2, then this document. Each builds on the ones before it, and -this one — the last — assumes both. +this one assumes both. The key words **MUST**, **MUST NOT**, **SHOULD**, and **MAY** are used as in RFC 2119. @@ -62,7 +62,7 @@ implementation concern (§6). ## 2. The two definition methods -An intent is defined by exactly **one** of two methods: +An intent is defined by one or both of two methods: - a **keyword intent** — defined by keyword constraints over vocabularies (§4); - a **template intent** — defined by sentence templates (§5). @@ -81,8 +81,10 @@ The two methods are **complementary**. They describe a command in fundamentally different shapes — a keyword intent by *which words must be present*, a template intent by *what whole sentences sound like* — and each suits triggers the other does not. A skill **MAY** define some of its intents as keyword intents and -others as template intents. Each **individual** intent, however, uses exactly -one method; the two definition shapes are never mixed within one intent. +others as template intents. Each **individual** registration uses exactly one +method; the two definition shapes are never mixed within one registration. An +intent **MAY** carry one registration per method — two training-data +representations of the same handler (OVOS-INTENT-4 §3.2). A developer chooses the method **per intent**, by what best describes that command, and by which engines the target assistant runs (§6). @@ -278,8 +280,10 @@ always a refinement, never a requirement. A template intent MAY declare **required slots**: a list of slot names that the engine **MUST** extract for a match to be valid. If any required slot is -absent from the match result, the engine treats the match as if it had not -occurred — the intent does not fire. +absent from the match result, the engine **MUST** treat the intent as +unmatched for that utterance — the intent does not fire. The engine **MAY** +internally consider other templates of the same intent before concluding +that the intent is unmatched. Required slots are an **optional** opt-in guarantee for the handler. When present, the handler MAY rely on those slots being populated; when absent, @@ -350,9 +354,12 @@ retained by the **orchestrator** — the intent system that owns the engines — invoked with the match result (§7) when the engine reports a match. An engine never invokes a handler directly; it reports matches, and the orchestrator routes. -Registering an intent whose `(skill id, intent name, language)` triple (§3) -matches an existing registration **replaces** it: the previous definition and -handler binding are discarded and wholly superseded by the new one. +Registering an intent whose `(skill id, intent name, language, method)` +quadruple (§2, §3) matches an existing registration **replaces** it: the +previous definition and handler binding for that method are discarded and +wholly superseded by the new one. A registration under the other method for +the same `(skill id, intent name, language)` triple is untouched +(OVOS-INTENT-4 §3.2). **Deregistration** ("detach") removes an intent: its definition is withdrawn from the engine and its handler reference is released by the orchestrator. Definition @@ -416,20 +423,20 @@ Whichever method defined an intent, a successful match yields one uniform - the **qualified intent name** `skill_id:intent_name` (§3) — identifying which intent, and therefore which skill and which handler; -- a **slots map** — a mapping of names to extracted text values. For a keyword +- a **slot map** — a mapping of names to extracted text values. For a keyword intent the keys are vocabulary names (§4.3); for a template intent the keys - are slot names (§5.2). A slots map **MAY** be empty. + are slot names (§5.2). A slot map **MAY** be empty. Slot values are **opaque sequences of words**, returned as text. This specification defines **no** value typing or coercion — consistent with -OVOS-INTENT-1 §5.2–§5.3, which defers typing to a future text-normalization -specification. +OVOS-INTENT-1 §5.2–§5.3, which places slot typing out of scope alongside +the text normalization it depends on. -In classifier terms the qualified intent name is the **label** and the slots +In classifier terms the qualified intent name is the **label** and the slot map is the **payload**: the label selects which handler runs, the payload is the data that handler is given. The orchestrator routes the result to the **one handler** bound to that intent at registration, and to nothing else. The handler always receives -the slots map — a set of key-value pairs, possibly empty — and that is the +the slot map — a set of key-value pairs, possibly empty — and that is the only data it receives from the intent layer. Running that handler is the whole purpose of the intent: it is the point at which a recognized natural-language command becomes the execution of the developer's code. @@ -454,7 +461,7 @@ responsibility. A handler **SHOULD** prompt the user for data it needs but did not receive, and **MAY** decline — treating the call as a misclassification — when the slot values do not make sense for it. This recovery behaviour is skill logic and is out of scope for this specification; what the specification -requires is only that a handler not assume a complete slots map. +requires is only that a handler not assume a complete slot map. --- @@ -462,13 +469,14 @@ requires is only that a handler not assume a complete slots map. **A skill** that defines intents **MUST**, for each intent: -- define it by exactly one method — keyword (§4) or template (§5), never both; +- define each of its registrations by exactly one method — keyword (§4) or + template (§5) — with at most one registration per method per intent (§2); - give it an intent name unique within the skill — the skill itself having an assistant-unique skill id (§3) — a language, and a handler; - ensure the definition conforms to §4 or §5 and to OVOS-INTENT-1 and OVOS-INTENT-2; - register the definition and the handler together as one unit (§6.1); -- write the handler so it copes with a missing or partial slots map (§7.1). +- write the handler so it copes with a missing or partial slot map (§7.1). **An intent engine** **MUST**: