snips-skill 0.1.29__py3-none-any.whl

snips_skill/__init__.py

@@ -0,0 +1,59 @@
+from .exceptions import SnipsClarificationError, SnipsError
+from .i18n import CONFIRMATIONS, get_translations
+from .log import LoggingMixin
+from .mqtt import CommandLineClient, MqttClient, topic
+from .multi_room import ROOMS, MultiRoomConfig, room_with_article, room_with_preposition
+from .skill import PARDON, Skill, intent, min_confidence, require_slot
+from .snips import (
+    SnipsClient,
+    debug_json,
+    on_continue_session,
+    on_end_session,
+    on_hotword_detected,
+    on_intent,
+    on_play_finished,
+    on_session_ended,
+    on_session_started,
+    on_start_session,
+)
+from .state import StateAwareMixin, conditional, when
+from .tasks import Scheduler, cron, delay, now
+
+__version__ = "0.1.29"
+
+__all__ = (
+    "CommandLineClient",
+    "conditional",
+    "CONFIRMATIONS",
+    "cron",
+    "debug_json",
+    "delay",
+    "get_translations",
+    "intent",
+    "LoggingMixin",
+    "min_confidence",
+    "MqttClient",
+    "MultiRoomConfig",
+    "now",
+    "on_continue_session",
+    "on_end_session",
+    "on_hotword_detected",
+    "on_intent",
+    "on_play_finished",
+    "on_session_ended",
+    "on_session_started",
+    "on_start_session",
+    "PARDON",
+    "require_slot",
+    "room_with_article",
+    "room_with_preposition",
+    "ROOMS",
+    "Scheduler",
+    "Skill",
+    "SnipsClarificationError",
+    "SnipsClient",
+    "SnipsError",
+    "StateAwareMixin",
+    "topic",
+    "when",
+)

snips_skill/__main__.py

@@ -0,0 +1,28 @@
+import logging
+
+from basecmd import BaseCmd
+
+from .intent import IntentPayload
+from .log import LoggingMixin
+from .snips import SnipsClient, on_continue_session, on_end_session, on_intent
+
+
+class Logger(BaseCmd, LoggingMixin, SnipsClient):
+    @on_intent("#")
+    # Do not use @intent here because it ends the session,
+    # and thus interferes with other intent handlers
+    def intent_logger(self, userdata, msg):
+        self.log_intent(IntentPayload.model_validate(msg.payload), level=logging.INFO)
+
+    @on_end_session()
+    @on_continue_session()
+    def response_logger(self, userdata, msg):
+        self.log_response(msg.payload.get("text"), level=logging.INFO)
+
+
+def main():
+    Logger().run()
+
+
+if __name__ == "__main__":  # demo code
+    main()

snips_skill/dialogue.py

@@ -0,0 +1,60 @@
+from typing import Literal
+
+from pydantic import BaseModel, Field
+from pydantic.alias_generators import to_camel
+
+
+class ActionInit(
+    BaseModel, alias_generator=to_camel, serialize_by_alias=True, validate_by_name=True
+):
+    "Start a session with an action"
+
+    # See: https://docs.snips.ai/reference/dialogue#session-initialization-action
+    type: Literal["action"] = "action"
+    text: str | None = None
+    intent_filter: list[str] | None = None
+    can_be_enqueued: bool = True
+    send_intent_not_recognized: bool = False
+
+
+class NotififationInit(BaseModel):
+    "Start a session with a notification"
+
+    # See: https://docs.snips.ai/reference/dialogue#session-initialization-notification
+    type: Literal["notification"] = "notification"
+    text: str
+
+
+class StartSession(
+    BaseModel, alias_generator=to_camel, serialize_by_alias=True, validate_by_name=True
+):
+    "Start a session with an optional message"
+
+    # See: https://docs.snips.ai/reference/dialogue#start-session
+    site_id: str
+    init: ActionInit | NotififationInit = Field(discriminator="type")
+    custom_data: str | None = None
+
+
+class EndSession(
+    BaseModel, alias_generator=to_camel, serialize_by_alias=True, validate_by_name=True
+):
+    "End the session with an optional message"
+
+    # See: https://docs.snips.ai/reference/dialogue#end-session
+    session_id: str
+    text: str | None = None
+
+
+class ContinueSession(
+    BaseModel, alias_generator=to_camel, serialize_by_alias=True, validate_by_name=True
+):
+    "Continue the session with a question"
+
+    # See: https://docs.snips.ai/reference/dialogue#continue-session
+    session_id: str
+    text: str
+    intent_filter: list[str] | None = None
+    slot: str | None = None
+    send_intent_not_recognized: bool = False
+    custom_data: str | None = None

snips_skill/exceptions.py

@@ -0,0 +1,34 @@
+class SnipsError(Exception):
+    "Signal that an intent cannot be handled"
+
+    def __str__(self):
+        return str(self.args[0])
+
+
+class SnipsClarificationError(SnipsError):
+    "Signal that some clarification is needed from the user."
+
+    def __init__(self, msg, intent=None, slot=None, custom_data=None):
+        """
+        Create a clarification request.
+        :param msg: Question for the user
+        :param intent: Optional expected intent
+        :param slot: Optional slot name
+        See: https://docs.snips.ai/reference/dialogue#continue-session
+        """
+        super().__init__(msg, intent, slot, custom_data)
+
+    def __str__(self):
+        return str(self.args[0])
+
+    @property
+    def intent(self):
+        return self.args[1]
+
+    @property
+    def slot(self):
+        return self.args[2]
+
+    @property
+    def custom_data(self):
+        return self.args[3]

snips_skill/expr.py

@@ -0,0 +1,172 @@
+import re
+from collections import namedtuple
+
+import ply.lex as lex
+import ply.yacc as yacc
+
+
+class Parser:
+    "Parse very simple expressions into callable boolean conditions"
+
+    class Expr(namedtuple("Expr", "keys expr")):
+        """
+        Container for a callable boolean predicate
+        along with the topic names being evaluated
+        """
+
+        last_state = None
+
+        def __call__(self, *args, **kw):
+            "Syntactic sugar"
+            self.last_state = self.expr(*args, **kw)
+            return self.last_state
+
+        def __hash__(self):
+            return hash(self.expr)
+
+    tokens = (
+        "AND",
+        "EQUAL",
+        "GREATER_EQUAL",
+        "GREATER",
+        "LESS_EQUAL",
+        "LESS",
+        "LPAREN",
+        "NOT_EQUAL",
+        "NOT",
+        "NUMBER",
+        "OR",
+        "REGEX_MATCH",
+        "RPAREN",
+        "STRING",
+        "TOPIC",
+    )
+
+    t_AND = r"and"
+    t_EQUAL = r"=="
+    t_GREATER = r">"
+    t_GREATER_EQUAL = r">="
+    t_LESS = r"<"
+    t_LESS_EQUAL = r"<="
+    t_LPAREN = r"\("
+    t_NOT = r"not"
+    t_NOT_EQUAL = r"!="
+    t_OR = r"or"
+    t_REGEX_MATCH = r"~="
+    t_RPAREN = r"\)"
+    t_TOPIC = r"[\w_-]+(/[\w_-]+)+"
+
+    # Ignored characters
+    t_ignore = " \t\r\n"
+
+    def t_NUMBER(self, t):
+        r"(\+|-)?\d+(\.\d+)?"
+        t.value = float(t.value)
+        return t
+
+    def t_STRING(self, t):
+        r"'[^']*'"
+        t.value = t.value[1:-1]
+        return t
+
+    # Track line numbers
+    def t_newline(self, t):
+        r"\n+"
+        t.lexer.lineno += len(t.value)
+
+    def t_error(self, t):
+        assert False, f"Illegal character '{t.value[0]}'"
+
+    # -#-# Grammar rules below #-#-#
+
+    precedence = (
+        ("left", "OR"),
+        ("left", "AND"),
+        ("right", "NOT"),
+        (
+            "left",
+            "GREATER",
+            "LESS",
+            "GREATER_EQUAL",
+            "LESS_EQUAL",
+            "EQUAL",
+            "NOT_EQUAL",
+            "REGEX_MATCH",
+        ),
+    )
+
+    def p_expr_term(self, p):
+        "expr : term"
+        p[0] = p[1]
+
+    def p_expr_and(self, p):
+        "expr : expr AND expr"
+        lhs, rhs = p[1], p[3]
+        p[0] = self.Expr(lhs.keys | rhs.keys, lambda s: lhs(s) and rhs(s))
+
+    def p_expr_or(self, p):
+        "expr : expr OR expr"
+        lhs, rhs = p[1], p[3]
+        p[0] = self.Expr(lhs.keys | rhs.keys, lambda s: lhs(s) or rhs(s))
+
+    def p_expr_not(self, p):
+        "expr : NOT expr"
+        cond = p[2]
+        p[0] = self.Expr(cond.keys, lambda s: not cond(s))
+
+    def p_expr_parenthesis(self, p):
+        "expr : LPAREN expr RPAREN"
+        p[0] = p[2]
+
+    def p_term_topic_less_number(self, p):
+        "term : TOPIC LESS NUMBER"
+        lhs, rhs = p[1], p[3]
+        p[0] = self.Expr(set([lhs]), lambda s: float(s[lhs]) < rhs)
+
+    def p_term_topic_less_equal_number(self, p):
+        "term : TOPIC LESS_EQUAL NUMBER"
+        lhs, rhs = p[1], p[3]
+        p[0] = self.Expr(set([lhs]), lambda s: float(s[lhs]) <= rhs)
+
+    def p_term_topic_greater_equal_number(self, p):
+        "term : TOPIC GREATER_EQUAL NUMBER"
+        lhs, rhs = p[1], p[3]
+        p[0] = self.Expr(set([lhs]), lambda s: float(s[lhs]) >= rhs)
+
+    def p_term_topic_greater_number(self, p):
+        "term : TOPIC GREATER NUMBER"
+        lhs, rhs = p[1], p[3]
+        p[0] = self.Expr(set([lhs]), lambda s: float(s[lhs]) > rhs)
+
+    def p_term_topic_equal_literal(self, p):
+        "term : TOPIC EQUAL literal"
+        lhs, rhs = p[1], p[3]
+        cast = type(rhs)
+        p[0] = self.Expr(set([lhs]), lambda s: cast(s[lhs]) == rhs)
+
+    def p_term_topic_not_equal_literal(self, p):
+        "term : TOPIC NOT_EQUAL literal"
+        lhs, rhs = p[1], p[3]
+        cast = type(rhs)
+        p[0] = self.Expr(set([lhs]), lambda s: cast(s[lhs]) != rhs)
+
+    def p_term_topic_regex_match_string(self, p):
+        "term : TOPIC REGEX_MATCH STRING"
+        lhs, rhs = p[1], p[3]
+        pattern = re.compile(rhs)
+        p[0] = self.Expr(set([lhs]), lambda s: pattern.search(str(s[lhs])) is not None)
+
+    def p_literal(self, p):
+        """literal : NUMBER
+        | STRING"""
+        p[0] = p[1]
+
+    def p_error(self, p):
+        assert False, "Syntax error at: %s" % (p or "EOF")
+
+    def __init__(self, **kwargs):
+        self.lexer = lex.lex(module=self)
+        self.parser = yacc.yacc(module=self, **kwargs)
+
+    def parse(self, text: str, **kwargs):
+        return self.parser.parse(text, lexer=self.lexer, **kwargs)

snips_skill/i18n.py

@@ -0,0 +1,83 @@
+import gettext
+import locale
+import os
+from collections import namedtuple
+
+__all__ = (
+    "_",
+    "ALL_ROOMS",
+    "CONFIRMATIONS",
+    "DEFAULT_ROOM_NAMES",
+    "ROOMS",
+    "get_translations",
+    "ngettext",
+    "room_with_article",
+    "room_with_preposition",
+)
+
+
+def get_translations(path: str, domain: str = "messages"):
+    "Install translations"
+    language, encoding = locale.getlocale()
+    assert type(language) is str, "Unsupported locale: %s" % locale.getlocale()
+    locale.setlocale(locale.LC_ALL, (language, encoding))
+    translation = gettext.translation(
+        domain,
+        localedir=os.path.join(os.path.dirname(path), "locale"),
+        languages=[language],
+        fallback=True,
+    )
+    return translation.gettext, translation.ngettext
+
+
+_, ngettext = get_translations(__file__, "snips_skill")
+
+RoomName = namedtuple("RoomName", "with_article, with_preposition")
+
+CONFIRMATIONS = (
+    _("done"),
+    _("here you are"),
+    _("OK"),
+    _("yes"),
+    _("finished"),
+    _("alright"),
+    _("at your service"),
+)
+
+DEFAULT_ROOM_NAMES = (
+    _("here"),
+    _("this room"),
+)
+
+ALL_ROOMS = (
+    _("all"),
+    _("everywhere"),
+    _("everything"),
+)
+
+ROOMS = {
+    # Map translated room names to room names with articles and prepositions
+    # for languages that use genders for room names, e.g. German
+    _("bathroom").lower(): RoomName(_("the bathroom"), _("in the bathroom")),
+    _("bedroom").lower(): RoomName(_("the bedroom"), _("in the bedroom")),
+    _("dining room").lower(): RoomName(_("the dining room"), _("in the dining room")),
+    _("livingroom").lower(): RoomName(_("the livingroom"), _("in the livingroom")),
+    _("kid's room").lower(): RoomName(_("the kid's room"), _("in the kid's room")),
+    _("kitchen").lower(): RoomName(_("the kitchen"), _("in the kitchen")),
+    _("office").lower(): RoomName(_("the office"), _("in the office")),
+    _("hall").lower(): RoomName(_("the hall"), _("in the hall")),
+    _("garden").lower(): RoomName(_("the garden"), _("in the garden")),
+    _("unknown room").lower(): RoomName(_("an unknown room"), _("in an unknown room")),
+}
+
+
+def room_with_article(room_name: str) -> str:
+    "Get the spoken room name with the definite article"
+    room = ROOMS.get(room_name.lower())
+    return room.with_article if room else _("the {room}").format(room=room_name)
+
+
+def room_with_preposition(room_name: str) -> str:
+    'Get the spoken room name with "in" preposition'
+    room = ROOMS.get(room_name.lower())
+    return room.with_preposition if room else _("in the {room}").format(room=room_name)

snips_skill/intent.py

@@ -0,0 +1,136 @@
+from datetime import datetime, timedelta
+from functools import cached_property
+from typing import Annotated, Literal
+
+from pydantic import BaseModel, Field
+from pydantic.alias_generators import to_camel
+
+__all__ = ("IntentPayload",)
+
+
+class UnknownValue(BaseModel):
+    kind: Literal["Unknown"]
+    value: str
+
+
+class NumericValue(BaseModel):
+    kind: Literal["Number"]
+    value: int | float
+
+
+# See: https://docs.snips.ai/articles/platform/dialog/slot-types#time-related-entities
+class InstantTimeValue(BaseModel):
+    kind: Literal["InstantTime"]
+    grain: str
+    precision: str
+    value: datetime
+
+
+class TimeIntervalValue(BaseModel):
+    kind: Literal["TimeInterval"]
+    t1: datetime | None = Field(alias="from", default=None)
+    t2: datetime | None = Field(alias="to", default=None)
+
+
+# See: https://docs.snips.ai/articles/platform/dialog/slot-types#duration-entities
+class DurationValue(BaseModel):
+    kind: Literal["Duration"]
+    precision: str
+    years: int = 0
+    quarters: int = 0
+    months: int = 0
+    weeks: int = 0
+    days: int = 0
+    hours: int = 0
+    minutes: int = 0
+    seconds: int = 0
+
+    def as_timedelta(self) -> timedelta:
+        # TODO: years, quarters and months are not parsed
+        return timedelta(
+            weeks=self.weeks,
+            days=self.days,
+            hours=self.hours,
+            minutes=self.minutes,
+            seconds=self.seconds,
+        )
+
+
+class TemperatureValue(BaseModel):
+    kind: Literal["Temperature"]
+    unit: str
+    value: float
+
+
+class MonetaryValue(BaseModel):
+    kind: Literal["AmountOfMoney"]
+    unit: str
+    precision: str
+    value: float
+
+
+class Range(BaseModel, alias_generator=to_camel, serialize_by_alias=True):
+    start: int
+    end: int
+    raw_start: int
+    raw_end: int
+
+
+SlotValue = Annotated[
+    UnknownValue
+    | NumericValue
+    | InstantTimeValue
+    | TimeIntervalValue
+    | DurationValue
+    | TemperatureValue
+    | MonetaryValue,
+    Field(discriminator="kind"),
+]
+
+
+# See: https://docs.snips.ai/reference/dialogue#slot
+class Slot(BaseModel, alias_generator=to_camel, serialize_by_alias=True):
+    entity: str
+    slot_name: str
+    raw_value: str
+    confidence: float
+    range: Range | None
+    value: SlotValue
+
+
+# See: https://docs.snips.ai/reference/dialogue#intent
+class Intent(BaseModel, alias_generator=to_camel, serialize_by_alias=True):
+    intent_name: str
+    confidence_score: float
+
+
+class AsrToken(BaseModel, alias_generator=to_camel, serialize_by_alias=True):
+    value: str
+    confidence: float
+    range_start: int
+    range_end: int
+    time: None
+
+
+# See: https://docs.snips.ai/reference/dialogue#intent
+class IntentPayload(BaseModel, alias_generator=to_camel, serialize_by_alias=True):
+    session_id: str
+    input: str
+    intent: Intent
+    site_id: str
+    slots: list[Slot] | None = None
+    id: str | None = None
+    session_id: str
+    custom_data: str
+    asr_tokens: list[list[AsrToken]]
+    asr_confidence: float
+    raw_input: str
+    # wakeword_id: str
+    # lang: None
+
+    @cached_property
+    def slot_values(self) -> dict[str, SlotValue]:
+        return {s.slot_name: s.value for s in self.slots or []}
+
+    def __getitem__(self, name):
+        return self.slot_values[name]