tolpo 0.1.0 → 0.2.0

package/src/tolpo/areas/__init__.py

@@ -0,0 +1,187 @@
+"""Area modules: one file per part of what the Tapo app does (lights, plugs, cameras, ...).
+
+Adding an area means adding a file here. Nothing else is edited, so many people can work at once. A module may define:
+
+    METHODS = [policy.method(name, tier, kinds, summary), ...]   # every device method it sends, with its level
+    def tools(ctx): ...                                           # register MCP tools with @ctx.tool
+    def routes(ctx): ...                                          # register HTTP routes with @ctx.route
+
+The module that defines MCP tools must not use `from __future__ import annotations`, because the SDK reads the
+signatures at runtime. See docs/areas/README.md for the rules and a template.
+"""
+
+import importlib
+import json
+import logging
+import pkgutil
+from dataclasses import dataclass, field
+from pathlib import Path
+from types import ModuleType
+from typing import Any, Awaitable, Callable
+
+from mcp.types import ToolAnnotations
+
+from .. import policy
+from ..config import Config
+from ..registry import Registry
+
+log = logging.getLogger(__name__)
+
+READ = ToolAnnotations(read_only_hint=True, open_world_hint=False)
+WRITE = ToolAnnotations(read_only_hint=False, destructive_hint=False, idempotent_hint=False, open_world_hint=False)
+RISKY = ToolAnnotations(read_only_hint=False, destructive_hint=True, idempotent_hint=False, open_world_hint=False)
+
+
+def annotations_for(tier: policy.Tier) -> ToolAnnotations:
+    """MCP clients use these hints to decide when to ask the person first."""
+    if tier <= policy.Tier.READ:
+        return READ
+    return WRITE if tier <= policy.Tier.SETTING else RISKY
+
+
+@dataclass
+class AreaContext:
+    registry: Registry
+    caller: Any  # a calls.DeviceCaller
+    server: Any = None  # the MCPServer, when tools are being registered
+    api: Any = None  # the FastAPI app, when routes are being registered
+    auth: list = field(default_factory=list)  # FastAPI dependencies that every route must carry
+    ready_for: Callable[[list[str]], Awaitable[None]] | None = None  # waits until the named devices are known
+    translated: Callable[[], Any] | None = None  # context manager: registry errors become tool errors
+    catalog: dict = field(default_factory=dict)  # area name -> {"enabled", "summary", "tools"}, filled by load()
+    current: str = ""  # the area being loaded
+    _names: dict = field(default_factory=dict)
+
+    @property
+    def cfg(self) -> Config:
+        return self.registry.cfg
+
+    def tool(self, *, title: str, tier: policy.Tier = policy.Tier.READ, **options: Any):
+        """Register an MCP tool. Its docstring is what the agent reads. Does nothing when no server is being built."""
+
+        def decorate(fn):
+            if self.server is not None:
+                self.server.tool(title=title, annotations=annotations_for(tier), **options)(fn)
+                self._names.setdefault(self.current, []).append(options.get("name") or fn.__name__)
+            return fn
+
+        return decorate
+
+    def route(self, path: str, *, method: str = "get", **options: Any):
+        """Register an HTTP route behind the same token check as the others. Does nothing when no app is being built."""
+
+        def decorate(fn):
+            if self.api is not None:
+                getattr(self.api, method)(path, dependencies=self.auth, **options)(fn)
+            return fn
+
+        return decorate
+
+
+def modules() -> list[ModuleType]:
+    """Every area module. One that fails to import is logged and skipped, so one bad area cannot take the rest down."""
+    found = []
+    for info in pkgutil.iter_modules(__path__):
+        if info.name.startswith("_"):
+            continue
+        try:
+            found.append(importlib.import_module(f"{__name__}.{info.name}"))
+        except Exception:
+            log.exception("area %s could not be imported; the rest of tolpo keeps working", info.name)
+    return found
+
+
+def declare_methods() -> None:
+    """Put every area's declared device methods in the policy catalog. Safe to call again."""
+    for module in modules():
+        policy.register_methods(getattr(module, "METHODS", ()))
+
+
+def area_name(module: ModuleType) -> str:
+    return module.__name__.rsplit(".", 1)[-1]
+
+
+# An area tied to a kind of device is on by default only if the owner has such a device. Areas not listed here
+# (automation, network, pairing, device admin and so on) are always on. The owner can override all of this with `areas`.
+AREA_KINDS: dict[str, set[str]] = {
+    "lights": {"light"},
+    "plugs": {"plug", "switch"},
+    "hub": {"hub"},
+    "doorbell": {"hub", "doorbell", "camera"},
+    "camera_detection": {"camera"},
+    "camera_system": {"camera"},
+    "camera_media": {"camera"},
+    "vacuum": {"vacuum"},
+    "lock": {"lock"},
+}
+ALWAYS_ON = {"overview"}
+# What a hub brings with it: its sensors, valves, chimes, doorbells and cameras are not hosts of their own, so they are not
+# remembered. A camera paired to a hub is its child, and the camera areas must stay on for it.
+HUB_BRINGS = {"sensor", "valve", "thermostat", "chime", "doorbell", "camera"}
+
+
+def kind_of_model(model: str) -> str | None:
+    """A rough kind from a Tapo model name (L530 -> light). None when the name is not recognized."""
+    m = model.upper().strip()
+    for prefix, kind in (("RV", "vacuum"), ("DL", "lock"), ("KE", "valve"), ("TC", "camera"), ("C", "camera"), ("D", "doorbell"),
+                         ("H", "hub"), ("L", "light"), ("P", "plug"), ("S", "switch"), ("T", "sensor")):
+        if m.startswith(prefix):
+            return kind
+    return None
+
+
+def kinds_present(cfg: Config) -> set[str] | None:
+    """The kinds of devices known from earlier runs, or None when nothing is remembered (then every area is on)."""
+    if not cfg.cache_file:
+        return None
+    try:
+        hosts = json.loads(Path(cfg.cache_file).expanduser().read_text()).get("hosts", {})
+    except (OSError, ValueError, AttributeError):
+        return None
+    models = [str(info.get("model") or "") for info in hosts.values() if isinstance(info, dict)]
+    kinds = {kind_of_model(m) for m in models if m}
+    if not models or None in kinds:  # nothing known, or a model we do not recognize: do not hide anything
+        return None
+    return kinds | (HUB_BRINGS if "hub" in kinds else set())
+
+
+def enabled_areas(names: list[str], cfg: Config) -> dict[str, tuple[bool, str]]:
+    """For each area: is it on, and why. `areas` in the config wins; otherwise the devices the owner has decide."""
+    wanted = set(cfg.areas)
+    present = None if wanted else kinds_present(cfg)
+    out = {}
+    for name in names:
+        if name in ALWAYS_ON:
+            out[name] = (True, "always on")
+        elif wanted:
+            out[name] = (name in wanted or "all" in wanted, "chosen in the config")
+        elif present is None or name not in AREA_KINDS:
+            out[name] = (True, "on by default")
+        else:
+            needed = AREA_KINDS[name]
+            out[name] = (bool(needed & present), f"on because a {sorted(needed & present)[0]} is known" if needed & present else f"off: no {'/'.join(sorted(needed))} known")
+    return out
+
+
+def load(ctx: AreaContext, *, strict: bool = False) -> None:
+    """Register the tools and routes of the enabled areas (all of them unless `areas` is set in the config).
+    `strict` re-raises, which the tests use. The result is kept in `ctx.catalog`."""
+    declare_methods()
+    found = modules()
+    decisions = enabled_areas([area_name(m) for m in found], ctx.cfg)
+    for module in found:
+        name = area_name(module)
+        enabled, why = decisions[name]
+        ctx.current = name
+        try:
+            if enabled and ctx.server is not None and hasattr(module, "tools"):
+                module.tools(ctx)
+            if enabled and ctx.api is not None and hasattr(module, "routes"):
+                module.routes(ctx)
+        except Exception:
+            if strict:
+                raise
+            log.exception("area %s could not be loaded; the rest of tolpo keeps working", module.__name__)
+        summary = (module.__doc__ or "").strip().splitlines()[0] if module.__doc__ else ""
+        ctx.catalog[name] = {"enabled": enabled, "why": why, "summary": summary, "tools": list(ctx._names.get(name, []))}
+    ctx.current = ""

package/src/tolpo/areas/automation.py

@@ -0,0 +1,227 @@
+"""MCP tools for local Smart Actions. No cloud calls."""
+import copy
+import logging
+from typing import Annotated, Any
+
+from mcp.server.mcpserver.exceptions import ToolError
+from pydantic import BeforeValidator, Field, ValidationError
+
+from tolpo import policy
+from tolpo.automation import Engine, Rule, Settings
+from tolpo.calls import NeedsConfirmation
+from tolpo.registry import Forbidden, RegistryError
+from tolpo.views import clean
+from tolpo.automation.engine import public_rule
+from tolpo.automation.tools import MCPToolExecutor
+from tolpo.policy import Tier
+
+log = logging.getLogger(__name__)
+
+RESUME_PHRASE = "automation_resume"
+
+METHODS = [
+    # T110, T300 and T310 sensors behind an H200 answer {"start_id": 0} with {"logs": [], "start_id": 0, "sum": 0}
+    # (fixtures). The H200 hub itself refuses the method, so it is not declared for hubs.
+    # UNVERIFIED: the event row shape (id, eventId, event, timestamp) is from python-kasa; every real log was empty.
+    # UNVERIFIED: button switches (S200) behind a hub.
+    policy.method("get_trigger_logs", Tier.READ, ["sensor", "switch"], "Read the local sensor or button trigger log."),
+]
+
+
+def engine_for(ctx):
+    """One engine per registry; lifecycle hooks live entirely in this area."""
+    if not hasattr(ctx.registry, "_automation_engine"):
+        ctx.registry._automation_engine = Engine(
+            ctx.registry, ctx.caller, tool_executor=getattr(ctx.registry, "_automation_tools", None))
+    return ctx.registry._automation_engine
+
+
+def install_lifecycle(ctx):
+    registry = ctx.registry
+    if getattr(registry, "_automation_lifecycle", False):
+        return
+    registry._automation_lifecycle = True
+    original_start, original_stop = registry.start, registry.stop
+
+    async def start(*args, **kwargs):
+        await original_start(*args, **kwargs)
+        try:
+            engine = engine_for(ctx)
+        except Exception as exc:
+            log.error("automation store could not be loaded: %s", type(exc).__name__)
+            return
+        engine.closed = False
+        engine.start()
+
+    async def stop():
+        engine = getattr(registry, "_automation_engine", None)
+        if engine is not None:
+            await engine.stop()
+        await original_stop()
+
+    registry.start, registry.stop = start, stop
+
+
+def rule_input(value):
+    try:
+        return Rule.model_validate(value)
+    except Exception:
+        raise ToolError("invalid automation rule") from None
+
+
+def settings_input(value):
+    try:
+        return Settings.model_validate(value)
+    except Exception:
+        raise ToolError("invalid automation settings") from None
+
+
+def tools(ctx):
+    if ctx.server is not None:
+        adapter = MCPToolExecutor(ctx)
+        ctx.registry._automation_tools = adapter
+        original_tool = ctx.tool
+
+        def register(*, title, tier=Tier.READ, **options):
+            decorate = original_tool(title=title, tier=tier, **options)
+            def record(fn):
+                adapter.record(options.get("name", fn.__name__), tier)
+                return decorate(fn)
+            return record
+
+        ctx.tool = register
+    install_lifecycle(ctx)
+
+    def owner_allows(level, tool):
+        """Rules act while nobody watches, so making or changing them is a level 2 action (a schedule). The owner can
+        also name the single tool in `allow_methods`."""
+        cfg = ctx.registry.cfg
+        if cfg.tier < level and tool not in cfg.allow_methods:
+            raise Forbidden(f"{tool} is a level {level} action (it sets up actions that run without anyone asking) and the owner's policy blocks it")
+
+    async def pin_devices(rule):
+        """Replace every device name in the rule by the device's own short id, so that a rename in the Tapo app, or another
+        device taking the same name, cannot send the rule's actions to a different device."""
+        refs = sorted(rule.device_refs())
+        await ctx.ready_for(refs)
+        names = {}
+        for ref in refs:
+            try:
+                names[ref] = ctx.registry.resolve_one(ref).slug
+            except RegistryError:
+                raise ToolError(f"automation change refused: no single device matches {clean(ref)!r}") from None
+        return rule.with_devices(names)
+
+    def engine():
+        try:
+            return engine_for(ctx)
+        except Exception as exc:
+            raise ToolError(f"automation store could not be loaded: {type(exc).__name__}") from None
+
+    async def change(fn):
+        eng = engine()
+        async with eng.lock:
+            before = copy.deepcopy(eng.state)
+            try:
+                return fn(eng)
+            except (ValueError, ValidationError):
+                eng.state = before
+                # Validation errors may echo private input values. Do not return them.
+                raise ToolError("automation change refused: invalid rule, settings, id or cycle") from None
+            except OSError:
+                eng.state = before
+                raise ToolError("automation state could not be written") from None
+
+    @ctx.tool(title="Create local automation", tier=Tier.SETTING)
+    async def automation_create(rule: Annotated[Rule, BeforeValidator(rule_input), Field(description="Local rule with unique id, triggers, conditions and ordered actions. Disabled by default.")]) -> dict[str, Any]:
+        """Create a local rule. Actions use the owner's current policy at every execution. Device names in the rule are
+        stored as the devices' short ids, and the rule refuses to run on a device that is gone."""
+        with ctx.translated():
+            owner_allows(2, "automation_create")
+        pinned = await pin_devices(rule)
+        return await change(lambda eng: eng.create(pinned))
+
+    @ctx.tool(title="List local automations")
+    async def automation_list() -> dict[str, Any]:
+        """List compact local rule summaries and the kill switch state."""
+        eng = engine()
+        async with eng.lock:
+            return {"rules": [public_rule(r) for r in eng.state.rules], "killed": eng.state.settings.killed}
+
+    @ctx.tool(title="Show local automation")
+    async def automation_show(rule_id: Annotated[str, Field(description="Local rule id")]) -> dict[str, Any]:
+        """Show a compact rule summary. Private action parameters are omitted."""
+        return await change(lambda eng: public_rule(eng.rule(rule_id)))
+
+    @ctx.tool(title="Enable local automation", tier=Tier.SETTING)
+    async def automation_enable(rule_id: Annotated[str, Field(description="Local rule id")]) -> dict[str, Any]:
+        """Enable a rule and lazily start local evaluation while the server runs."""
+        with ctx.translated():
+            owner_allows(2, "automation_enable")
+        return await change(lambda eng: eng.enabled(rule_id, True))
+
+    @ctx.tool(title="Disable local automation", tier=Tier.SETTING)
+    async def automation_disable(rule_id: Annotated[str, Field(description="Local rule id")]) -> dict[str, Any]:
+        """Disable a rule and cancel its queued delayed actions."""
+        return await change(lambda eng: eng.enabled(rule_id, False))
+
+    @ctx.tool(title="Delete local automation", tier=Tier.SETTING)
+    async def automation_delete(rule_id: Annotated[str, Field(description="Local rule id")]) -> dict[str, Any]:
+        """Delete a local rule and its queued actions."""
+        with ctx.translated():
+            owner_allows(2, "automation_delete")
+        return await change(lambda eng: eng.delete(rule_id))
+
+    @ctx.tool(title="Preview local automations")
+    async def automation_dry_run() -> dict[str, Any]:
+        """Read current observations and say what would fire now without actions or state changes."""
+        return await engine().tick(dry_run=True)
+
+    @ctx.tool(title="Evaluate local automations", tier=Tier.CONTROL)
+    async def automation_tick(confirm: Annotated[str | None, Field(description="Optional per-call confirmation phrase for an immediate security or lifecycle action. Never saved.")] = None) -> dict[str, Any]:
+        """Evaluate once, run due actions through policy, and report individual failures."""
+        return await engine().tick(confirm=confirm)
+
+    @ctx.tool(title="Read local automation alerts", tier=Tier.CONTROL)
+    async def automation_alerts(clear: Annotated[bool, Field(description="Clear only the returned outbox records after reading them")] = False,
+                                limit: Annotated[int, Field(ge=1, le=1000, description="Maximum records to return")] = 100) -> dict[str, Any]:
+        """Read the owner's JSONL alert outbox. Quiet records should be delivered after quiet hours."""
+        eng = engine()
+        async with eng.lock:
+            return {"alerts": eng.store.alerts(clear=clear, limit=limit)}
+
+    @ctx.tool(title="Configure local automation", tier=Tier.SETTING)
+    async def automation_settings(settings: Annotated[Settings, BeforeValidator(settings_input), Field(description="Complete local settings: IANA timezone, coordinates, poll interval, quiet hours and killed switch")],
+                                  confirm: Annotated[str | None, Field(description=f"Only to switch automation back on after it was stopped: the exact phrase {RESUME_PHRASE}")] = None) -> dict[str, Any]:
+        """Replace engine settings. Killing stops a running evaluation at once, cancels pending runs and blocks
+        ticks until cleared. Stopping is always allowed. Switching rules back on after a stop is a level 3 action
+        that needs the confirmation phrase, and the owner can also do it from the terminal with `tolpo automation resume`."""
+        eng = engine()
+        if settings.killed:
+            # Do not wait for a running tick: stop the loop first, then record the switch.
+            await eng.halt()
+        else:
+            with ctx.translated():
+                owner_allows(2, "automation_settings")
+                if eng.state.settings.killed or eng.store.killed_on_disk():  # also a stop the owner made from a terminal
+                    owner_allows(3, "automation_resume")
+                    if confirm != RESUME_PHRASE:
+                        raise NeedsConfirmation(f"automation_resume is a level 3 action: it lets stopped rules act again. To go ahead, call again with confirm={RESUME_PHRASE!r}")
+
+        def update(eng):
+            eng.state.settings = settings
+            if settings.killed:
+                eng.kill()
+            else:
+                eng.halted = False
+            eng.save(resuming=not settings.killed)
+            eng.start()
+            return {"settings": settings.model_dump(exclude_none=True)}
+
+        try:
+            return await change(update)
+        except ToolError:
+            if settings.killed:
+                # The switch could not be saved. Keep this process stopped anyway.
+                eng.kill()
+            raise