https://github.com/home-assistant/hassil
Intent parsing for Home Assistant
https://github.com/home-assistant/hassil
Last synced: 7 days ago
JSON representation
Intent parsing for Home Assistant
- Host: GitHub
- URL: https://github.com/home-assistant/hassil
- Owner: home-assistant
- License: apache-2.0
- Created: 2022-12-19T19:20:08.000Z (about 2 years ago)
- Default Branch: main
- Last Pushed: 2025-02-04T17:37:34.000Z (17 days ago)
- Last Synced: 2025-02-07T22:09:22.227Z (14 days ago)
- Language: Python
- Size: 433 KB
- Stars: 88
- Watchers: 23
- Forks: 19
- Open Issues: 10
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE.md
- Codeowners: CODEOWNERS
Awesome Lists containing this project
README
# HassIL
The Home Assistant Intent Language (HassIL) parser for [intents](https://github.com/home-assistant/intents).
## Dependencies
* PyYAML
## Installation
Run the `script/setup` script to automatically create a virtual environment and install the requirements.
# Running
``` sh
python3 -m hassil [ ...]
```
Once loaded, you may type in a sentence and see what intent it matches.
For example:
``` sh
python3 -m hassil examples/en.yaml --areas 'living room'
what is the temperature in the living room
{'intent': 'HassClimateGetTemperature', 'area': 'living room', 'domain': 'climate'}
```
Make sure to provide area names with `--areas`. Device or entity names can be provided with `--names`.
``` sh
python3 -m hassil examples/en.yaml --areas office --names trapdoor
open the trapdoor in the office
{'intent': 'HassOpenCover', 'name': 'trapdoor', 'area': 'office'}
```
### Sampling Sentences
Sentences for each intent can be sampled from the intent YAML files:
``` sh
python3 -m hassil.sample examples/en.yaml -n 1
{"intent": "HassTurnOn", "text": "turn on the entity"}
{"intent": "HassTurnOff", "text": "turn off the entity"}
{"intent": "HassOpenCover", "text": "open the entity in the area"}
{"intent": "HassCloseCover", "text": "close the entity in the area"}
{"intent": "HassLightsSet", "text": "set the entity color to red"}
{"intent": "HassClimateSetTemperature", "text": "set temperature to 0 degrees in the area"}
{"intent": "HassClimateGetTemperature", "text": "what is the temperature in the area"}
```
The `--areas` and `--names` arguments are the same from `python3 -m hassil`, but default to generic "area" and "entity" terms.
Exclude the `-n` argument to sample all possible sentences.
## Sentence Templates
Uses a custom parser written in Python.
* Alternative words or phrases
* `(red|green|blue)`
* `turn(s|ed|ing)`
* Optional words or phrases
* `[the]`
* `[this|that]`
* `light[s]`
* Permutations of words or phrases
* `(patience; you must have) my young Padawan`
* `is [the] light (on; in )`
* Slot Lists
* `{list_name}`
* `{list_name:slot_name}`
* Refers to a pre-defined list of values in YAML (`lists`), either global or local (particular to the intent to which the sentence refers)
* Expansion Rules
* ``
* Refers to a pre-defined expansion rule in YAML (`expansion_rules`), either global or local (particular to the intent to which the sentence refers)
## YAML Format
``` yaml
language: ""
intents:
:
data:
# List of sentences/slots/etc.
- sentences:
- ""
- ""
# Optional
slots:
# Fixed slots for the recognized intent
:
requires_context:
# Must be present in match context
: # Any provided value is good
excludes_context:
# Must NOT be present in match context
:
expansion_rules:
# Expansion rules which only apply to the intent, referenced as
:
lists:
# Lists which apply only to the current set of sentences, referenced as {list_name} or {list_name:slot_name}
:
values:
# See below for other possible types
- "items"
- "in list"
metadata:
# Arbitrary key/value pairs that will be available in the result
:
# Optional lists of items that become alternatives in sentence templates
lists:
# Referenced as {list_name} or {list_name:slot_name}
:
values:
- "items"
- "in list"
- in: "text in"
out:
# Optional
context:
:
metadata:
# Arbitrary key/value pairs that will be available in the result
:
range:
type: "number"
from: 0
to: 100 # inclusive
multiplier: 1.0 # multiply to get final value
wildcard: true
# Optional rules that are expanded in sentence templates
expansion_rules:
# Referenced as
: ""
# Optional words that the intent recognizer can skip during recognition
skip_words:
- ""
```