# 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 <yaml_file_or_directory> [<yaml_file_or_directory> ...]
```
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 <area>)`
* 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
* `<rule_name>`
* 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: "<language code>"
intents:
<intent name>:
data:
# List of sentences/slots/etc.
- sentences:
- "<sentence template>"
- "<sentence template>"
# Optional
slots:
# Fixed slots for the recognized intent
<name>: <value>
requires_context:
# Must be present in match context
<name>: # Any provided value is good
excludes_context:
# Must NOT be present in match context
<name>: <value or list>
expansion_rules:
# Expansion rules which only apply to the intent, referenced as <rule_name>
<rule_name>: <sentence template>
lists:
# Lists which apply only to the current set of sentences, referenced as {list_name} or {list_name:slot_name}
<list name>:
values:
# See below for other possible types
- "items"
- "in list"
metadata:
# Arbitrary key/value pairs that will be available in the result
<key>: <value>
# Optional lists of items that become alternatives in sentence templates
lists:
# Referenced as {list_name} or {list_name:slot_name}
<list name>:
values:
- "items"
- "in list"
- in: "text in"
out: <value for slot>
# Optional
context:
<name>: <value>
metadata:
# Arbitrary key/value pairs that will be available in the result
<key>: <value>
<range_name>
range:
type: "number"
from: 0
to: 100 # inclusive
multiplier: 1.0 # multiply to get final value
<wildcard_name>
wildcard: true
# Optional rules that are expanded in sentence templates
expansion_rules:
# Referenced as <rule_name>
<rule_name>: "<sentence template>"
# Optional words that the intent recognizer can skip during recognition
skip_words:
- "<word>"
```
Raw data
{
"_id": null,
"home_page": "http://github.com/home-assistant/hassil",
"name": "hassil",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "home assistant intent recognition",
"author": "Michael Hansen",
"author_email": "mike@rhasspy.org",
"download_url": null,
"platform": null,
"description": "# HassIL\n\nThe Home Assistant Intent Language (HassIL) parser for [intents](https://github.com/home-assistant/intents).\n\n\n## Dependencies\n\n* PyYAML\n\n\n## Installation\n\nRun the `script/setup` script to automatically create a virtual environment and install the requirements.\n\n\n# Running\n\n``` sh\npython3 -m hassil <yaml_file_or_directory> [<yaml_file_or_directory> ...]\n```\n\nOnce loaded, you may type in a sentence and see what intent it matches.\nFor example:\n\n``` sh\npython3 -m hassil examples/en.yaml --areas 'living room'\nwhat is the temperature in the living room\n{'intent': 'HassClimateGetTemperature', 'area': 'living room', 'domain': 'climate'}\n```\n\nMake sure to provide area names with `--areas`. Device or entity names can be provided with `--names`.\n\n``` sh\npython3 -m hassil examples/en.yaml --areas office --names trapdoor\nopen the trapdoor in the office\n{'intent': 'HassOpenCover', 'name': 'trapdoor', 'area': 'office'}\n```\n\n\n### Sampling Sentences\n\nSentences for each intent can be sampled from the intent YAML files:\n\n``` sh\npython3 -m hassil.sample examples/en.yaml -n 1\n{\"intent\": \"HassTurnOn\", \"text\": \"turn on the entity\"}\n{\"intent\": \"HassTurnOff\", \"text\": \"turn off the entity\"}\n{\"intent\": \"HassOpenCover\", \"text\": \"open the entity in the area\"}\n{\"intent\": \"HassCloseCover\", \"text\": \"close the entity in the area\"}\n{\"intent\": \"HassLightsSet\", \"text\": \"set the entity color to red\"}\n{\"intent\": \"HassClimateSetTemperature\", \"text\": \"set temperature to 0 degrees in the area\"}\n{\"intent\": \"HassClimateGetTemperature\", \"text\": \"what is the temperature in the area\"}\n```\n\nThe `--areas` and `--names` arguments are the same from `python3 -m hassil`, but default to generic \"area\" and \"entity\" terms.\n\nExclude the `-n` argument to sample all possible sentences.\n\n\n## Sentence Templates\n\nUses a custom parser written in Python.\n\n* Alternative words or phrases\n * `(red | green | blue)`\n * `turn(s | ed | ing)`\n* Optional words or phrases\n * `[the]`\n * `[this | that]`\n * `light[s]`\n* Permutations of words or phrases\n * `(patience; you must have) my young Padawan`\n * `is [the] light (on; in <area>)`\n* Slot Lists\n * `{list_name}`\n * `{list_name:slot_name}`\n * Refers to a pre-defined list of values in YAML (`lists`), either global or local (particular to the intent to which the sentence refers)\n* Expansion Rules\n * `<rule_name>`\n * Refers to a pre-defined expansion rule in YAML (`expansion_rules`), either global or local (particular to the intent to which the sentence refers)\n\n\n## YAML Format\n\n``` yaml\nlanguage: \"<language code>\"\nintents:\n <intent name>:\n data:\n # List of sentences/slots/etc.\n - sentences:\n - \"<sentence template>\"\n - \"<sentence template>\"\n # Optional\n slots:\n # Fixed slots for the recognized intent\n <name>: <value>\n requires_context:\n # Must be present in match context\n <name>: # Any provided value is good\n excludes_context:\n # Must NOT be present in match context\n <name>: <value or list>\n expansion_rules:\n # Expansion rules which only apply to the intent, referenced as <rule_name>\n <rule_name>: <sentence template>\n lists:\n # Lists which apply only to the current set of sentences, referenced as {list_name} or {list_name:slot_name}\n <list name>:\n values:\n # See below for other possible types\n - \"items\"\n - \"in list\"\n metadata:\n # Arbitrary key/value pairs that will be available in the result\n <key>: <value>\n\n# Optional lists of items that become alternatives in sentence templates\nlists:\n # Referenced as {list_name} or {list_name:slot_name}\n <list name>:\n values:\n - \"items\"\n - \"in list\"\n - in: \"text in\"\n out: <value for slot>\n # Optional\n context:\n <name>: <value>\n metadata:\n # Arbitrary key/value pairs that will be available in the result\n <key>: <value>\n <range_name>\n range:\n type: \"number\"\n from: 0\n to: 100 # inclusive\n multiplier: 1.0 # multiply to get final value\n <wildcard_name>\n wildcard: true\n\n# Optional rules that are expanded in sentence templates\nexpansion_rules:\n # Referenced as <rule_name>\n <rule_name>: \"<sentence template>\"\n\n# Optional words that the intent recognizer can skip during recognition\nskip_words:\n - \"<word>\"\n```\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "The Home Assistant Intent Language parser",
"version": "1.7.0",
"project_urls": {
"Homepage": "http://github.com/home-assistant/hassil"
},
"split_keywords": [
"home",
"assistant",
"intent",
"recognition"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "7611321fcec69d1fb16645507fb7d3e0c29e4eeba58e4fc1531e0e15e4890a95",
"md5": "199213f4f1dc79fe4f593e6ddfe3ed38",
"sha256": "cf9775d3b31dda2b1f4b145366a6c4448913655e008420ab805ce908f6aeb474"
},
"downloads": -1,
"filename": "hassil-1.7.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "199213f4f1dc79fe4f593e6ddfe3ed38",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 32540,
"upload_time": "2024-03-27T16:36:38",
"upload_time_iso_8601": "2024-03-27T16:36:38.733480Z",
"url": "https://files.pythonhosted.org/packages/76/11/321fcec69d1fb16645507fb7d3e0c29e4eeba58e4fc1531e0e15e4890a95/hassil-1.7.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-03-27 16:36:38",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "home-assistant",
"github_project": "hassil",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "PyYAML",
"specs": [
[
">=",
"6.0"
],
[
"<",
"7"
]
]
},
{
"name": "unicode-rbnf",
"specs": [
[
"==",
"1.1.0"
]
]
}
],
"tox": true,
"lcname": "hassil"
}
JSON
