Gazetteer Matcher

An English-language, constraint-driven intent recognizer for Home Assistant voice commands. It complements Home Assistant's built-in sentence grammars by handling home-specific names, fuzzy wording, compound requests, and explicit conversation references while rejecting interpretations that do not fit the upstream intent schema.

Features

Flexible and fuzzy target matching for entities, areas, floors, domains, and actions: turn on the bedrom lamp resolves to Bedroom Lamp.
Location-aware disambiguation from spoken qualifiers and voice-satellite context: bedroom TV selects the TV assigned to the bedroom.
Compound commands with multiple targets, intents, or properties: turn off the kitchen lights and open the bedroom blinds.
Multiple actions on one target: turn on the hallway light and set its brightness to 40%.
Explicit conversational follow-ups: turn on the kitchen lights followed by turn them off, or is the front door locked? followed by lock it.
Conservative, schema-backed validation with structured error categories and concise responses for ambiguous, unsupported, and out-of-range requests.

Install

pip install gazetteer-matcher

Runtime dependencies are home-assistant-intents, unicode-rbnf, and PyYAML. A source install also attempts to build a self-contained C++17 fuzzy scorer. Installation still succeeds without a compiler and uses the behaviorally equivalent Python implementation instead.

For development:

pip install 'gazetteer-matcher[dev]'
pytest

Quick start

from gazetteer_matcher import GazetteerMatcher

matcher = GazetteerMatcher(
    home={
        "areas": {
            "kitchen": {"name": "Kitchen", "floor": "ground"},
        },
        "floors": {
            "ground": {"name": "Ground Floor"},
        },
        "entities": {},
    }
)

result = matcher.interpret("flick on the kichen lights")
assert result.accepted

frame = result.frames[0]
assert frame.intent == "HassTurnOn"
assert frame.slots == {"area": "kitchen", "domain": "light"}
assert frame.response_key == "lights_area"

Pass the voice satellite's location when a command omits it:

result = matcher.interpret("turn off the lights", context_area="Kitchen")
assert result.frames[0].slots == {"domain": "light", "area": "kitchen"}

Interpretations can contain several ordered frames:

result = matcher.interpret(
    "turn off the kitchen lights and open the bedroom blinds"
)

assert [frame.intent for frame in result.frames] == [
    "HassTurnOff",
    "HassTurnOn",
]

Rejected requests carry an integration-facing category, a diagnostic reason, and an optional ready-to-use response:

result = matcher.interpret("set bedroom TV volume to 1000%")

assert not result.accepted
assert result.rejection_code == "invalid_percentage"
assert result.response == (
    "Sorry, the volume value must be a whole-number percentage "
    "between 0% and 100%."
)

Core API

GazetteerMatcher.interpret() accepts:

the utterance;
optional context_area and context_floor values;
optional previous_targets exported by a prior accepted interpretation.

An accepted Interpretation exposes ordered frames and reusable targets. Each frame contains the Home Assistant intent, slot combination, resolved slot values, response key, and selection diagnostics. Rejected interpretations expose rejection_code, reason, response, and refusal_target; their targets collection is always empty.

The matcher itself is stateless. The caller decides whether a prior target is recent enough to pass back:

previous = matcher.interpret("open the bedroom blinds")
result = matcher.interpret(
    "close them",
    previous_targets=previous.targets,
)

Call matcher.set_home(...) to replace the entity/area/floor gazetteer without rebuilding the language vocabulary, intent catalog, or shared number trie.

Documentation

Usage guide — context, compound commands, state questions, follow-ups, response keys, and rejection handling
Configuration — the home gazetteer, vocabulary, response wording, and runtime updates
Development — CLI diagnostics, fixture tests, rejection tests, and upstream coverage measurement
Internals — tagging, intent constraints, number words, fuzzy scoring, coordination, scope, and candidate selection

CLI

gazetteer-match match 'turn on the kitchen and hallway lights' \
  --home my-home.yaml
gazetteer-match match 'flick on the kichen lights' \
  --home my-home.yaml --debug
gazetteer-match match 'open the bedroom blinds' \
  --home my-home.yaml --debug --json
gazetteer-match spans 'flik the bedroom lights on'
gazetteer-match support

match requires either --home PATH or an explicit --empty-home. The latter is useful for generic timers, date/time, weather, and state questions that need no home-specific names. spans keeps --home optional, while support does not use a home gazetteer. Supply --vocabulary or --responses to override the language data. Location context is available through --context-area and --context-floor. See the development guide for the complete debugging and coverage workflow.

Design principle

Fuzzy similarity is evidence, not permission. A close spelling match cannot outweigh incompatible Home Assistant slots, contradictory scope, unexplained semantic content, or an equally good competing interpretation. When the matcher cannot choose one valid meaning, it rejects the request rather than guessing.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

gazetteer_matcher-1.0.0.tar.gz (88.2 kB view details)

Uploaded Aug 25, 2026 Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

gazetteer_matcher-1.0.0-cp314-cp314-win_arm64.whl (449.3 kB view details)

Uploaded Aug 25, 2026 CPython 3.14Windows ARM64

gazetteer_matcher-1.0.0-cp314-cp314-win_amd64.whl (271.4 kB view details)

Uploaded Aug 25, 2026 CPython 3.14Windows x86-64

gazetteer_matcher-1.0.0-cp314-cp314-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl (212.1 kB view details)

Uploaded Aug 25, 2026 CPython 3.14manylinux: glibc 2.24+ x86-64manylinux: glibc 2.28+ x86-64

gazetteer_matcher-1.0.0-cp314-cp314-manylinux_2_24_aarch64.manylinux_2_28_aarch64.whl (211.4 kB view details)

Uploaded Aug 25, 2026 CPython 3.14manylinux: glibc 2.24+ ARM64manylinux: glibc 2.28+ ARM64

gazetteer_matcher-1.0.0-cp314-cp314-macosx_11_0_arm64.whl (72.9 kB view details)

Uploaded Aug 25, 2026 CPython 3.14macOS 11.0+ ARM64

gazetteer_matcher-1.0.0-cp314-cp314-macosx_10_15_x86_64.whl (73.8 kB view details)

Uploaded Aug 25, 2026 CPython 3.14macOS 10.15+ x86-64

gazetteer_matcher-1.0.0-cp313-cp313-win_arm64.whl (435.6 kB view details)

Uploaded Aug 25, 2026 CPython 3.13Windows ARM64

gazetteer_matcher-1.0.0-cp313-cp313-win_amd64.whl (264.4 kB view details)

Uploaded Aug 25, 2026 CPython 3.13Windows x86-64

gazetteer_matcher-1.0.0-cp313-cp313-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl (211.9 kB view details)

Uploaded Aug 25, 2026 CPython 3.13manylinux: glibc 2.24+ x86-64manylinux: glibc 2.28+ x86-64

gazetteer_matcher-1.0.0-cp313-cp313-manylinux_2_24_aarch64.manylinux_2_28_aarch64.whl (211.2 kB view details)

Uploaded Aug 25, 2026 CPython 3.13manylinux: glibc 2.24+ ARM64manylinux: glibc 2.28+ ARM64

gazetteer_matcher-1.0.0-cp313-cp313-macosx_11_0_arm64.whl (72.9 kB view details)

Uploaded Aug 25, 2026 CPython 3.13macOS 11.0+ ARM64

gazetteer_matcher-1.0.0-cp313-cp313-macosx_10_13_x86_64.whl (73.7 kB view details)

Uploaded Aug 25, 2026 CPython 3.13macOS 10.13+ x86-64

gazetteer_matcher-1.0.0-cp312-cp312-win_arm64.whl (435.6 kB view details)

Uploaded Aug 25, 2026 CPython 3.12Windows ARM64

gazetteer_matcher-1.0.0-cp312-cp312-win_amd64.whl (264.4 kB view details)

Uploaded Aug 25, 2026 CPython 3.12Windows x86-64

gazetteer_matcher-1.0.0-cp312-cp312-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl (212.0 kB view details)

Uploaded Aug 25, 2026 CPython 3.12manylinux: glibc 2.24+ x86-64manylinux: glibc 2.28+ x86-64

gazetteer_matcher-1.0.0-cp312-cp312-manylinux_2_24_aarch64.manylinux_2_28_aarch64.whl (211.2 kB view details)

Uploaded Aug 25, 2026 CPython 3.12manylinux: glibc 2.24+ ARM64manylinux: glibc 2.28+ ARM64

gazetteer_matcher-1.0.0-cp312-cp312-macosx_11_0_arm64.whl (72.9 kB view details)

Uploaded Aug 25, 2026 CPython 3.12macOS 11.0+ ARM64

gazetteer_matcher-1.0.0-cp312-cp312-macosx_10_13_x86_64.whl (73.7 kB view details)

Uploaded Aug 25, 2026 CPython 3.12macOS 10.13+ x86-64

gazetteer_matcher-1.0.0-cp311-cp311-win_arm64.whl (435.6 kB view details)

Uploaded Aug 25, 2026 CPython 3.11Windows ARM64

gazetteer_matcher-1.0.0-cp311-cp311-win_amd64.whl (264.3 kB view details)

Uploaded Aug 25, 2026 CPython 3.11Windows x86-64

gazetteer_matcher-1.0.0-cp311-cp311-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl (211.9 kB view details)

Uploaded Aug 25, 2026 CPython 3.11manylinux: glibc 2.24+ x86-64manylinux: glibc 2.28+ x86-64

gazetteer_matcher-1.0.0-cp311-cp311-manylinux_2_24_aarch64.manylinux_2_28_aarch64.whl (211.2 kB view details)

Uploaded Aug 25, 2026 CPython 3.11manylinux: glibc 2.24+ ARM64manylinux: glibc 2.28+ ARM64

gazetteer_matcher-1.0.0-cp311-cp311-macosx_11_0_arm64.whl (73.0 kB view details)

Uploaded Aug 25, 2026 CPython 3.11macOS 11.0+ ARM64

gazetteer_matcher-1.0.0-cp311-cp311-macosx_10_9_x86_64.whl (73.7 kB view details)

Uploaded Aug 25, 2026 CPython 3.11macOS 10.9+ x86-64

File details

Details for the file gazetteer_matcher-1.0.0.tar.gz.

File metadata

Download URL: gazetteer_matcher-1.0.0.tar.gz
Upload date: Aug 25, 2026
Size: 88.2 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for gazetteer_matcher-1.0.0.tar.gz
Algorithm	Hash digest
SHA256	`1af983380c26ad72a26797efe45eb555e655d939754fb5f45bb8ca4bcbe8519d`
MD5	`a6d8a9f59b912599436a8393f765ea04`
BLAKE2b-256	`c906b8a1a6c691866a80cfb89908babfcc1a35036917fa48e529dc7a483551ef`

Algorithm	Hash digest
SHA256	`6839d355c1c22a791900a250fed081af4b4d6915d135a4047ecfc975b47c741b`
MD5	`08a5aabe4932bfe4cfe0603d4a281037`
BLAKE2b-256	`5e51928de83eabd5b4daf90c8f5ea27b84952dec4efc014152784ec4417509ee`

Algorithm	Hash digest
SHA256	`5569035228cc2e3cb91cf4c1240ae1ccc703114f07d8b6f0ba1f61c2aaf915b5`
MD5	`e6d4aaa8a60a380fd47b0b416470e08f`
BLAKE2b-256	`c2366406a1952fe9aa024fbd468a748a269d1b1927f3ecca610a8df589de6b47`

Algorithm	Hash digest
SHA256	`b3430c51c7c6a4f4b46dce48e6129bedd9514b11a307bc2955db694b1f886787`
MD5	`440b9b4805a2635d11c49794bb62599c`
BLAKE2b-256	`1311d7e359357850405ee30df971dc6d4571b21f6e456e65d6bde20f6fd4201c`

Algorithm	Hash digest
SHA256	`089df131bb60e642470ebb697e84808722cc885b0736fc72e7cf222ec34aa20c`
MD5	`19204564d935504bb8c92a200bdf45e2`
BLAKE2b-256	`d8fff16156fcffca8b06cf50eabf324b6e01e9777d8f777199e5209d3749a0bf`

Algorithm	Hash digest
SHA256	`8bed69a930385d5aede26dc476c2f2dcc2c4450d21e595c694dce5ad4275b204`
MD5	`f73bd786f862b52133a52cdee4b5fa49`
BLAKE2b-256	`ba070a62587de5d006e7ae158a530a8bbc11b8886d749fba10beda869aa76946`

Algorithm	Hash digest
SHA256	`edf29d09efc1aad734823b438a107afb336e39f3ddd64758ed5dc91ee584386f`
MD5	`2c45f57a22222d8c15c108966abc3ee9`
BLAKE2b-256	`4cb7e925455c4a2177d0868190fa8fe927267ddeaa020f7cba6024a863c2992f`

Algorithm	Hash digest
SHA256	`631d4a19e317aea174333fc313937779f4ee2f2333fcd525bf494d78da06bdb2`
MD5	`e8356c5553eaf125f5492bd777253746`
BLAKE2b-256	`37a300ff152598cac4535b6f231995a4815e769d0be463d4026e5c2c9183dc00`

Algorithm	Hash digest
SHA256	`8b39edad5cb933c82b1198142257fc3263f7806c54ea54081fc9d91ae1ad2822`
MD5	`bd0f134f5c0a4b1d71f7233b2f49c4f9`
BLAKE2b-256	`cdb21dcb0c2c859a110854040db9f95c0e5a67e4d4bbbc55fad1c2a28ee46890`

Algorithm	Hash digest
SHA256	`0a3702441be25d0403320be4e45d3b44917a99783923e7e828ec47e5f458dde0`
MD5	`37ea39e41c41bdfce4f866267f37d19a`
BLAKE2b-256	`c30e443c521bc185754be817c1f22aef421bd29030348252bbae4a43f6beec92`

Algorithm	Hash digest
SHA256	`198789f4f0283c646ec3ff897cbb9ba0273d6977f9da0b8661a58cff22a7406b`
MD5	`c2f70e3b80eca05ed520228e2fa2aa47`
BLAKE2b-256	`b494fbd57089a4de1f3f3ac42a16414f428789cdbfea838d00c536a241486e5b`

Algorithm	Hash digest
SHA256	`16daf16188a8fb19916713b632157c71ca63756a4fa9a1435b803e1b35fb85d7`
MD5	`d6dc655b2d7b7b0dd64e242582f22025`
BLAKE2b-256	`388734b9aee0a8f467326e29de4937c4c3b5f4f821d12ad203b29555d20411a6`

Algorithm	Hash digest
SHA256	`92d1301327be320a70d561f75fd53eb0c8f7705eb718fd57b6a4a2fefbecf72d`
MD5	`88728731843f332b24536fe18ccc6e34`
BLAKE2b-256	`ea635099c7b406ea4418e5bba381abecd6b34f4db24119595eb51705f1911adf`

Algorithm	Hash digest
SHA256	`f19d617d21314bc35835de7ef52f33a68a28b74fa056dcf7a7ff4baf877c9b04`
MD5	`15c9de0de1ac126ae0effbbeb8ffa965`
BLAKE2b-256	`2448a5cf2dd413b275d0925c4866baef47a2291760f19c9b95c55b9c219bee9c`

Algorithm	Hash digest
SHA256	`ec1107672d537e8b04292bb4e76588434d9845153f8e4c12b310ab70e0c34bbc`
MD5	`7405726403083176a77cb957ca233715`
BLAKE2b-256	`74a0cdefb0be7c0056d2e79791739ec9e2853d258bc2e4e3056b3b830673c7bb`

Algorithm	Hash digest
SHA256	`4c839c90e4ea57b622b9f3d5420f770cfcb520c212972369c1df87f592eb3c9d`
MD5	`72a5323b04f0f2e6be7f47581a4491b0`
BLAKE2b-256	`8e119749a1bd39008997841e4099011e005582eff13b9bbb3216783b1a55d48b`

Algorithm	Hash digest
SHA256	`bddad01b8a8339b8744da7014478ba0087d61889566b25db0288fa2655d2e8e6`
MD5	`ec48f00a529aed26ad730d7386d6698d`
BLAKE2b-256	`cde26809497d3d2342461869538c343f621181581089d4ff4c9eb8ead14e8625`

Algorithm	Hash digest
SHA256	`bc359aeef3ccf0547089e733f3918c6d27bded8bda151fed393fb6c9f2a39d3d`
MD5	`80bbe450a13e4ef4ef54f8255e72665b`
BLAKE2b-256	`b373014c181a03b98f71a8762155690bc0b67205f26376bfb19d94f98e7abdeb`

Algorithm	Hash digest
SHA256	`52b8a7fd332c6c4565ee5b91c44c0e33681b5e0f0c639ab350f8dea24ab03ff4`
MD5	`9b4eb8a0a6ebde5dc0655cff3b83da01`
BLAKE2b-256	`595063c2e26fcfeaec4df4534f62db84d6e6b77719149755ab2c8f23c556051b`

Algorithm	Hash digest
SHA256	`c775b03738d4644325ebb0114244cad17264faaab9cc29cd4923bac3a23c9d03`
MD5	`eb7fccc401caf2ea6ea97375b78735f2`
BLAKE2b-256	`4101f6ecc8f79b363c15132f0dbf3349a8f4cac9e3bc9dea25279490724d06ef`

Algorithm	Hash digest
SHA256	`ed11020b7f6b89107d191ae0440e826760683b016635934dfbb7fa5937c3fc60`
MD5	`593203502be4e36ad4745191d3407ea6`
BLAKE2b-256	`e49eb14bf730c3db4a4d37eddbd204978eae85ee952c480c4139a027f35a65cd`

gazetteer-matcher 1.0.0

Gazetteer Matcher

Features

Install

Quick start

Core API

Documentation

CLI

Design principle

Key dates

1 maintainer

License expression

Requires

Provides Extra

Download files

Source Distribution

Built Distributions

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Algorithm	Hash digest
SHA256	`e240a9f13afc84615152088994d01ef0c351fbd9599727068deebf739e1318de`
MD5	`3af26aab673fe8ec590a8a9d25c49d8e`
BLAKE2b-256	`2dc49edccc94f8d74dd9573c4fec19c6784a415a6f3619dd818bc9889ccc3221`

Algorithm	Hash digest
SHA256	`5c4529710ab69e9ccf6e5c8b1882167b7b0a7d68f2ae836dc430c1d230e2c6c1`
MD5	`c481689e0424486b32e7315b70bee74b`
BLAKE2b-256	`265bfa00dc1b1623f3dfaed8fb8bfe532f9c07aefab9d2d64cdeaf48ff1e61a8`

Algorithm	Hash digest
SHA256	`30f1f1274bc9041fcaa85f2dfa5f13f235348500192725306b33ece65b8f4b10`
MD5	`813cddc2bd05203fb115c52763ecb06f`
BLAKE2b-256	`7730f380c18e7f4a3b3b187303355da87a292fce3d86c49e4f287e3cc2606199`

Algorithm	Hash digest
SHA256	`f02c65b5af13790d7d0591606eecb8acefa18fac58c1c94bc37fd06ee1aeb0fe`
MD5	`cba7c151212913185f7eb7160849ffbb`
BLAKE2b-256	`57b1478d35b660bd6c96b666e64cf1eb5e342856c69fae03e4428da5f262706d`