hunch-engine 0.2.0__tar.gz

hunch_engine-0.2.0/.gitignore

@@ -0,0 +1,10 @@
+.env
+.venv/
+__pycache__/
+*.pyc
+.pytest_cache/
+.ruff_cache/
+dist/
+*.egg-info/
+.superpowers/
+golden/homes/

hunch_engine-0.2.0/PKG-INFO

@@ -0,0 +1,9 @@
+Metadata-Version: 2.5
+Name: hunch-engine
+Version: 0.2.0
+Summary: Typed-decision fast path for Home Assistant requests, powered by Jev
+Project-URL: Homepage, https://github.com/pujux/hass-hunch
+Project-URL: Repository, https://github.com/pujux/hass-hunch
+Project-URL: Issues, https://github.com/pujux/hass-hunch/issues
+Requires-Python: >=3.13
+Requires-Dist: typesafe-sdk<0.8,>=0.7

hunch_engine-0.2.0/pyproject.toml

@@ -0,0 +1,18 @@
+[project]
+name = "hunch-engine"
+version = "0.2.0"
+description = "Typed-decision fast path for Home Assistant requests, powered by Jev"
+requires-python = ">=3.13"
+dependencies = ["typesafe-sdk>=0.7,<0.8"]
+
+[project.urls]
+Homepage = "https://github.com/pujux/hass-hunch"
+Repository = "https://github.com/pujux/hass-hunch"
+Issues = "https://github.com/pujux/hass-hunch/issues"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/hunch"]

hunch_engine-0.2.0/src/hunch/__init__.py

@@ -0,0 +1,90 @@
+"""Hunch: code calculates, Jev judges."""
+
+from hunch.client import (
+    DecisionBackendError,
+    DecisionClient,
+    FakeDecisionClient,
+    TypeSafeDecisionClient,
+)
+from hunch.config import EngineConfig, Thresholds
+from hunch.engine import Engine
+from hunch.loaders import home_from_export
+from hunch.model import Area, Entity, Floor, HomeModel
+from hunch.phrasing import DE, EN, PHRASEBOOKS, Phrasebook
+from hunch.questions import (
+    JSON,
+    Answer,
+    Answers,
+    ChoiceA,
+    ChoiceQ,
+    NoulA,
+    NoulQ,
+    Question,
+    ScoreA,
+    ScoreQ,
+)
+from hunch.resolution import (
+    Action,
+    Condition,
+    Escalate,
+    NeedsClarification,
+    NeedsConfirmation,
+    Resolution,
+    Resolved,
+    Trace,
+)
+from hunch.vocabulary import (
+    DEFAULT_VOCABULARY,
+    ChoiceSpec,
+    Risk,
+    ScoreSpec,
+    Verb,
+    Vocabulary,
+    verbs_for_domain,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "DE",
+    "EN",
+    "JSON",
+    "PHRASEBOOKS",
+    "Phrasebook",
+    "Action",
+    "Answer",
+    "Answers",
+    "Area",
+    "ChoiceA",
+    "ChoiceQ",
+    "ChoiceSpec",
+    "Condition",
+    "DEFAULT_VOCABULARY",
+    "DecisionBackendError",
+    "DecisionClient",
+    "Engine",
+    "EngineConfig",
+    "Entity",
+    "Escalate",
+    "FakeDecisionClient",
+    "Floor",
+    "HomeModel",
+    "NeedsClarification",
+    "NeedsConfirmation",
+    "NoulA",
+    "NoulQ",
+    "Question",
+    "Resolution",
+    "Resolved",
+    "Risk",
+    "ScoreA",
+    "ScoreQ",
+    "ScoreSpec",
+    "Thresholds",
+    "Trace",
+    "TypeSafeDecisionClient",
+    "Verb",
+    "Vocabulary",
+    "home_from_export",
+    "verbs_for_domain",
+]

hunch_engine-0.2.0/src/hunch/client.py

@@ -0,0 +1,128 @@
+"""Backend boundary. Everything network-shaped lives here and nowhere else."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping
+from typing import Any, Protocol
+
+from typesafe_sdk import (
+    AsyncTypeSafeClient,
+    Choice,
+    Noul,
+    RetryPolicy,
+    Score,
+    TypeSafeError,
+)
+
+from hunch.questions import (
+    JSON,
+    Answer,
+    Answers,
+    ChoiceA,
+    ChoiceQ,
+    NoulA,
+    NoulQ,
+    Question,
+    ScoreA,
+    ScoreQ,
+)
+
+
+class DecisionBackendError(Exception):
+    def __init__(self, reason: str, cause: BaseException | None = None) -> None:
+        super().__init__(reason)
+        self.reason = reason
+        self.__cause__ = cause
+
+
+class DecisionClient(Protocol):
+    async def ask(self, state: JSON, questions: Mapping[str, Question]) -> Answers: ...
+
+
+ScriptFn = Callable[[JSON, Mapping[str, Question]], Mapping[str, Answer]]
+
+
+class FakeDecisionClient:
+    """Scripted answers for tests.
+
+    Missing ids raise KeyError so unexpected questions fail loudly.
+    """
+
+    def __init__(self, script: Mapping[str, Answer] | ScriptFn, model: str = "fake") -> None:
+        self._script = script
+        self._model = model
+        self.calls: list[tuple[JSON, dict[str, Question]]] = []
+
+    async def ask(self, state: JSON, questions: Mapping[str, Question]) -> Answers:
+        self.calls.append((state, dict(questions)))
+        if callable(self._script):
+            answers = dict(self._script(state, questions))
+        else:
+            answers = {qid: self._script[qid] for qid in questions}
+        return Answers(model=self._model, answers=answers, input_tokens=None)
+
+
+def to_sdk_question(q: Question) -> Noul | Choice | Score:
+    if isinstance(q, NoulQ):
+        return Noul(instructions=q.instructions)
+    if isinstance(q, ChoiceQ):
+        desc = q.descriptions or {}
+        return Choice(instructions=q.instructions, criteria={o: desc.get(o) for o in q.options})
+    if isinstance(q, ScoreQ):
+        return Score(instructions=q.instructions, criteria=list(q.levels))
+    raise TypeError(type(q))
+
+
+def from_sdk_answer(a: Any) -> Answer:
+    kind = getattr(a, "type", None)
+    if kind == "noul":
+        return NoulA(float(a.noul))
+    if kind == "choice":
+        return ChoiceA(str(a.choice), float(a.confidence), dict(a.probabilities))
+    if kind == "score":
+        probabilities = {int(k): float(v) for k, v in a.probabilities.items()}
+        return ScoreA(float(a.score), float(a.confidence), probabilities)
+    raise DecisionBackendError("malformed_response")
+
+
+class TypeSafeDecisionClient:
+    def __init__(
+        self,
+        model: str,
+        *,
+        api_key: str | None = None,
+        timeout_ms: int = 1500,
+        sdk_client: Any | None = None,
+    ) -> None:
+        self._model = model
+        timeout_s = timeout_ms / 1000
+        self._sdk = sdk_client or AsyncTypeSafeClient(
+            api_key=api_key,
+            model=model,
+            timeout=timeout_s,
+            retry=RetryPolicy(max_retries=2, timeout=timeout_s),
+        )
+
+    async def ask(self, state: JSON, questions: Mapping[str, Question]) -> Answers:
+        sdk_questions = {qid: to_sdk_question(q) for qid, q in questions.items()}
+        try:
+            resp = await self._sdk.system_one(
+                state=state, questions=sdk_questions, model=self._model
+            )
+        except TypeSafeError as exc:
+            raise DecisionBackendError("decision_backend_unavailable", exc) from exc
+        if resp.model != self._model:
+            raise DecisionBackendError("model_mismatch")
+        answers = {qid: from_sdk_answer(a) for qid, a in resp.answers.items()}
+        if set(answers) != set(questions):
+            # A partial or over-full answer set would surface downstream as a KeyError deep
+            # inside interpretation; fail here so the engine can degrade cleanly instead.
+            raise DecisionBackendError("malformed_response")
+        usage = getattr(resp, "usage", None)
+        input_tokens = getattr(usage, "input_tokens", None)
+        return Answers(model=resp.model, answers=answers, input_tokens=input_tokens)
+
+    async def aclose(self) -> None:
+        aclose = getattr(self._sdk, "aclose", None)
+        if aclose:
+            await aclose()

hunch_engine-0.2.0/src/hunch/config.py

@@ -0,0 +1,57 @@
+"""Tunable thresholds and engine settings.
+
+Defaults are starting points, tuned from the golden corpus.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass(frozen=True)
+class Thresholds:
+    verb_fire: float = 0.7
+    scope_fire: float = 0.7
+    place_override: float = 0.9  # the area comparison narrows to ONE place only when this sure
+    # a Jev-only area/floor (not named verbatim) needs this to count  # floor / area / domain Nouls
+    collective: float = 0.5
+    target_choice_conf: float = 0.7
+    auto_execute: float = 0.70  # 2026-09-20: 0.75 asked on correct sweeps; set on Julian's corpus
+    confirm_band: float = 0.5  # [confirm_band, auto_execute) -> NeedsConfirmation
+    flag: float = 0.6
+    specific_device: float = 0.7  # names_specific flag: plural-looking name of ONE device
+    collective_fallback: float = (
+        0.4  # no-match target + collective >= this: all candidates, confirm
+    )
+    no_match_clarify: float = 0.6  # no-match target below this confidence: clarify, not escalate
+
+
+@dataclass(frozen=True)
+class EngineConfig:
+    # Pinned Jev model id, e.g. "jev-1.13.0". A response from any other model is rejected.
+    model: str
+    # Probability/confidence gates; see Thresholds above.
+    thresholds: Thresholds = field(default_factory=Thresholds)
+    # Budget of backend round trips per request. Round 1 always costs one; a device round
+    # and Round 2 cost one each, so device_round requires >= 3. Overrunning it escalates
+    # as "round_budget" rather than guessing.
+    max_rounds: int = 2
+    # A collective action over more entities than this always asks for confirmation.
+    max_silent_targets: int = 20
+    # Largest candidate set a Round 2 Choice may be built over. Beyond it accuracy decays
+    # (context rot), so the request falls through to a device round, clarification or
+    # escalation instead.
+    scope_cap: int = 60
+    # Spend an extra round narrowing an over-cap set by device name before giving up.
+    device_round: bool = False
+    # Whether the caller can hold the turn open to ask a follow-up question. When false,
+    # what would have been a NeedsClarification escalates instead.
+    supports_clarification: bool = True
+    clarify_max_candidates: int = 5  # candidates offered in a NeedsClarification
+    # Prompts longer than this escalate unread as "prompt_invalid".
+    max_prompt_chars: int = 500
+
+    def __post_init__(self) -> None:
+        # A device round is a round: Round 1 + device round + Round 2 needs a budget of 3.
+        if self.device_round and self.max_rounds < 3:
+            raise ValueError("device_round requires max_rounds >= 3")

hunch_engine-0.2.0/src/hunch/engine.py

@@ -0,0 +1,240 @@
+"""Orchestrates rounds. Decides; never executes."""
+
+from __future__ import annotations
+
+import dataclasses
+
+from hunch.client import DecisionBackendError, DecisionClient
+from hunch.config import EngineConfig
+from hunch.model import Entity, HomeModel
+from hunch.phrasing import EN, Phrasebook
+from hunch.questions import ChoiceQ, Question
+from hunch.resolution import Escalate, NeedsClarification, Resolution, Trace
+from hunch.resolver import resolve
+from hunch.round1 import build_round1_questions, build_round1_state, interpret_round1
+from hunch.round2 import (
+    NO_MATCH,
+    build_round2_questions,
+    build_round2_state,
+    device_options,
+    plan_round2,
+)
+from hunch.scope import (
+    Candidates,
+    Clarify,
+    DeviceRound,
+    ScopeEscalate,
+    scope_candidates,
+    verbatim_areas,
+)
+from hunch.vocabulary import Verb, Vocabulary
+
+
+class Engine:
+    def __init__(
+        self,
+        client: DecisionClient,
+        vocabulary: Vocabulary,
+        config: EngineConfig,
+        phrasebook: Phrasebook = EN,
+    ) -> None:
+        self._client = client
+        self._vocab = vocabulary
+        self._config = config
+        self._pb = phrasebook
+
+    async def decide(self, home: HomeModel, prompt: str) -> Resolution:
+        """Decide what `prompt` asks of `home`. Never executes, never raises on backend trouble.
+
+        Returns one of four `Resolution` variants:
+
+        - `Resolved(actions, condition, confidence, trace)` — execute as-is.
+        - `NeedsConfirmation(actions, condition, reason, trace)` — ask the user first.
+          `reason` is `"risk:confirm"`, `"blast_radius"` or `"confidence"`.
+        - `NeedsClarification(question_key, candidates, trace, verb, params)` — ask which one.
+          `question_key` is `"which_area"` or `"which_device"`. `verb` is the verb being
+          clarified and `params` are the params already resolved for it in Round 2, or `{}`
+          when the clarification happened before Round 2.
+        - `Escalate(reason, partial, trace)` — hand the unchanged prompt to the fallback
+          agent. `reason` is drawn from a closed set:
+
+          | reason | meaning |
+          |---|---|
+          | `prompt_invalid` | empty prompt, or longer than `max_prompt_chars` |
+          | `timing` | the request schedules, delays or sequences something |
+          | `no_intent` | no verb fired |
+          | `destructive` | a `DESTRUCTIVE` verb fired, or `is_destructive` did |
+          | `low_confidence` | actions were built but confidence is below `confirm_band` |
+          | `scope` | every fired verb resolved to no candidates |
+          | `round_budget` | Round 2 was needed but `max_rounds` was already spent |
+          | `decision_backend_unavailable` | backend error, timeout, wrong model id, bad answers |
+
+        Every variant carries the same `Trace`. `Trace` is **mutable and shared** with the
+        result: it is the live object the engine wrote to, not a copy, so callers must treat
+        it as read-only (or snapshot it with `trace.to_dict()`). `trace.input_tokens` holds
+        one entry per round in round order — the backend's reported input-token count, or
+        `None` when that response carried no usage information.
+        """
+        trace = Trace()
+        prompt = prompt.strip()
+        if not prompt or len(prompt) > self._config.max_prompt_chars:
+            return Escalate("prompt_invalid", (), trace)
+        try:
+            return await self._decide(home, prompt, trace)
+        except (DecisionBackendError, KeyError, TypeError) as exc:
+            # KeyError/TypeError mean the backend answered with a missing id or the wrong
+            # primitive; like an explicit backend error, that degrades, it never raises.
+            reason = exc.reason if isinstance(exc, DecisionBackendError) else type(exc).__name__
+            trace.note(f"backend_error:{reason}")
+            return Escalate("decision_backend_unavailable", (), trace)
+
+    async def _decide(self, home: HomeModel, prompt: str, trace: Trace) -> Resolution:
+        th = self._config.thresholds
+        rounds = 0
+
+        answers = await self._client.ask(
+            build_round1_state(home, prompt), build_round1_questions(home, self._vocab, self._pb)
+        )
+        rounds += 1
+        shape = interpret_round1(home, self._vocab, answers, th, trace)
+
+        if trace.decide("flag:has_timing", shape.flag("has_timing"), th.flag):
+            return Escalate("timing", (), trace)
+        if shape.flag("has_condition") >= th.flag and trace.decide(
+            "flag:condition_numeric", shape.flag("condition_numeric"), th.flag
+        ):
+            # "wenn es wärmer als 23 Grad ist": a comparison against a number is not a state a
+            # Condition can hold, and executing unconditionally would be wrong. Jev judged the
+            # shape; code only refuses to pretend.
+            trace.note("condition:numeric")
+            return Escalate("condition", (), trace)
+        if not shape.fired_verbs:
+            return Escalate("no_intent", (), trace)
+
+        # Scope. Jev already compared the places in Round 1 (one room, a floor, several, the
+        # whole home, or none). Code adds one lookup: a room or floor whose name or alias is in
+        # the prompt is the scope, whatever else half-fired.
+        named_areas = verbatim_areas(home, prompt)
+        if shape.whole_home and not named_areas:
+            kept: tuple[str, ...] = ()
+            trace.note("whole_home")
+        elif named_areas:
+            kept = named_areas
+            dropped = tuple(a for a in shape.scope_areas if a not in named_areas)
+            if dropped:
+                trace.note("areas_dropped:named:" + ",".join(dropped))
+            trace.note("area_match:" + ",".join(named_areas))
+        else:
+            kept = shape.scope_areas
+        if kept != shape.scope_areas:
+            shape = dataclasses.replace(shape, scope_areas=kept)
+
+        per_verb: dict[str, tuple[Entity, ...]] = {}
+        widened: set[str] = set()
+        pending_clarify: Clarify | None = None
+        pending_clarify_verb: Verb | None = None
+        for verb in shape.fired_verbs:
+            if shape.scene is not None and verb.name == "activate":
+                per_verb[verb.name] = (shape.scene,)
+                continue
+            result = scope_candidates(home, verb, shape, self._config, trace, prompt)
+            if isinstance(result, Candidates):
+                per_verb[verb.name] = result.entities
+                if result.widened:
+                    widened.add(verb.name)  # Jev is asked in Round 2 whether these were meant
+            elif isinstance(result, Clarify):
+                if verb.is_query:
+                    # "Which windows are open?" over the whole home: summarising state is the
+                    # fallback agent's strength, and "which area?" is the wrong question.
+                    trace.note(f"dropped:{verb.name}:query_over_cap")
+                    continue
+                # Ask only if no other verb has anything to act on; a co-firing verb that had
+                # to widen past the cap is noise next to one that found its targets in scope.
+                if pending_clarify is None:
+                    pending_clarify_verb = verb
+                pending_clarify = pending_clarify or result
+            elif isinstance(result, ScopeEscalate):
+                # One verb with nothing to apply to does not abort the turn; the others may
+                # still resolve. Only an empty result set overall escalates.
+                trace.note(f"dropped:{verb.name}:scope")
+            elif isinstance(result, DeviceRound):
+                if rounds >= self._config.max_rounds:
+                    return (
+                        NeedsClarification("which_device", result.entities, trace, verb)
+                        if self._config.supports_clarification
+                        else Escalate("scope", (), trace)
+                    )
+                chosen = await self._device_round(home, prompt, result.entities, trace)
+                rounds += 1
+                if chosen:
+                    per_verb[verb.name] = chosen
+                else:
+                    trace.note(f"dropped:{verb.name}:scope")
+        if not per_verb:
+            if pending_clarify is not None:
+                return NeedsClarification(
+                    pending_clarify.question_key,
+                    pending_clarify.candidates,
+                    trace,
+                    pending_clarify_verb,
+                )
+            return Escalate("scope", (), trace)
+        if pending_clarify is not None:
+            for v in shape.fired_verbs:
+                if v.name not in per_verb and f"dropped:{v.name}:scope" not in trace.notes:
+                    trace.note(f"dropped:{v.name}:scope")
+
+        plan = plan_round2(
+            home, shape, per_verb, th, self._config.scope_cap, prompt, frozenset(widened)
+        )
+        collective_queries = [
+            v.name
+            for v in shape.fired_verbs
+            if v.is_query
+            and v.name in per_verb
+            and shape.flag("collective")
+            >= th.collective  # Jev's judgment, not the planner's bucket
+        ]
+        if collective_queries:
+            # "Welche Fenster sind offen?", "Wie viele Lichter sind an?": Jev says the question is
+            # about a set. Reading and summarising many states is the fallback agent's strength;
+            # a device-level answer or a "confirm reading 26 lights?" would be wrong here.
+            for name in collective_queries:
+                trace.note(f"query_collective:{name}")
+            return Escalate("query_collective", (), trace)
+        if shape.flag("has_condition") >= th.flag and not plan.condition_candidates:
+            # The request carried a condition but nothing in scope can express it.
+            trace.note("condition:unresolvable")
+        questions: dict[str, Question] = build_round2_questions(shape, plan, home, self._pb)
+        round2 = None
+        if questions:
+            if rounds >= self._config.max_rounds:
+                trace.note("max_rounds_reached_before_round2")
+                return Escalate("round_budget", (), trace)
+            round2 = await self._client.ask(
+                build_round2_state(prompt, plan, home, shape), questions
+            )
+            rounds += 1
+        return resolve(shape, plan, round2, self._config, trace, self._pb)
+
+    async def _device_round(
+        self, home: HomeModel, prompt: str, entities: tuple[Entity, ...], trace: Trace
+    ) -> tuple[Entity, ...]:
+        opts = device_options(entities, {a.area_id: a.name for a in home.areas})
+        q = ChoiceQ(
+            self._pb.device_question,
+            tuple(o.label for o in opts) + (NO_MATCH,),
+        )
+        answers = await self._client.ask(
+            {"request": prompt, "devices": [o.label for o in opts]}, {"device_round": q}
+        )
+        trace.record(2, answers)
+        c = answers.choice("device_round")
+        if c.choice == NO_MATCH:
+            trace.note("no_match:device_round")
+            return ()
+        th = self._config.thresholds.target_choice_conf
+        if not trace.decide("device_round", c.confidence, th):
+            return ()
+        opt = next((o for o in opts if o.label == c.choice), None)
+        return opt.entities if opt else ()

hunch_engine-0.2.0/src/hunch/loaders.py

@@ -0,0 +1,80 @@
+"""Build a HomeModel from a registry export (see tools/export_home.py).
+
+This is the reference for how the integration's HomeModelBuilder should derive a home:
+only Assist-exposed entities, area inherited from the device when the entity has none,
+user-given names preferred over integration defaults, verbs from the vocabulary.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+
+from hunch.model import Area, Entity, Floor, HomeModel
+from hunch.vocabulary import DEFAULT_VOCABULARY, Vocabulary, verbs_for_domain
+
+SCENE_DOMAINS = frozenset({"scene", "script"})
+
+
+def home_from_export(
+    export: Mapping[str, Any], vocabulary: Vocabulary = DEFAULT_VOCABULARY
+) -> HomeModel:
+    areas_raw = export.get("areas", [])
+    areas = tuple(
+        Area(
+            area_id=a["area_id"],
+            name=a["name"],
+            aliases=tuple(a.get("aliases") or ()),
+            floor_id=a.get("floor_id"),
+        )
+        for a in areas_raw
+    )
+    floors = tuple(
+        Floor(
+            floor_id=f["floor_id"],
+            name=f["name"],
+            area_ids=tuple(a.area_id for a in areas if a.floor_id == f["floor_id"]),
+            aliases=tuple(f.get("aliases") or ()),
+        )
+        for f in export.get("floors", [])
+    )
+    devices = {d["id"]: d for d in export.get("devices", [])}
+    registry = {e["entity_id"]: e for e in export.get("entities", [])}
+    states = export.get("states", {})
+    exposed = list(export.get("exposed", []))
+
+    entities: list[Entity] = []
+    scenes: list[Entity] = []
+    for entity_id in exposed:
+        reg = registry.get(entity_id, {})
+        st = states.get(entity_id, {})
+        device = devices.get(reg.get("device_id") or "")
+        domain = entity_id.split(".", 1)[0]
+        device_name = None
+        if device is not None:
+            device_name = device.get("name_by_user") or device.get("name")
+        name = (
+            reg.get("name")
+            or reg.get("original_name")
+            or st.get("friendly_name")
+            or device_name
+            or entity_id
+        )
+        entity = Entity(
+            entity_id=entity_id,
+            domain=domain,
+            name=name,
+            aliases=tuple(reg.get("aliases") or ()),
+            area_id=reg.get("area_id") or (device.get("area_id") if device else None),
+            device_id=reg.get("device_id"),
+            device_name=device_name,
+            verbs=(
+                frozenset({"activate"})
+                if domain in SCENE_DOMAINS
+                else verbs_for_domain(domain, vocabulary)
+            ),
+            state=st.get("state"),
+        )
+        (scenes if domain in SCENE_DOMAINS else entities).append(entity)
+
+    return HomeModel(floors=floors, areas=areas, entities=tuple(entities), scenes=tuple(scenes))