@readymadeit/mcp 0.0.0-stage → 0.1.0

package/bundle/hkp-python/src/hkp/services/nested_pipeline.py

@@ -0,0 +1,278 @@
+from __future__ import annotations
+
+"""A pipeline of services hosted inside a service.
+
+SubService owns one of these; Tracks owns one per track; an http endpoint owns
+one per entry point. Everything a nested runtime cannot do for itself lives
+here: it has no notification targets, no route to the board's log, no vault and
+no cells, so the service hosting it has to carry all of them in. Getting any of
+them wrong is quiet rather than loud, which is why it is one implementation and
+not one per host.
+"""
+
+from typing import Any, Callable
+
+from ..address import join_address
+from ..runtime import HostedRuntime, child_run
+from ..types import (
+    JsonRecord,
+    RuntimeHost,
+    ServiceConfiguration,
+    ServiceCreator,
+    SlotStore,
+)
+from .sub_service import (
+    _make_runtime_config,
+    _normalize_pipeline_array,
+    _normalize_pipeline_entry,
+)
+
+
+class NestedPipeline:
+    """One nested pipeline, with everything a nested runtime cannot do itself.
+
+    It has no notification target, no route to the board's log, no vault and no
+    cells of its own, so the service hosting it carries all of them in. Tracks
+    owns one of these per track and one for the reducer; an http endpoint owns
+    one per entry point.
+    """
+
+    def __init__(
+        self,
+        label: str,
+        create_service: ServiceCreator,
+        owner: str = "SubService",
+        owner_uuid: str = "",
+    ) -> None:
+        """
+        :param owner:      What the nested runtime is called in logs.
+        :param owner_uuid: The uuid a service inside this pipeline is addressed
+                           under. Separate from ``owner``, which is a name for
+                           a person reading a log rather than one for dialling.
+        """
+        self._label = label
+        self._owner = owner
+        self._owner_uuid = owner_uuid
+        self._create_service = create_service
+        #: See share_slots. None means the surrounding runtime's cells.
+        self._shared: SlotStore | None = None
+        self._config: list[ServiceConfiguration] = []
+        self._runtime: HostedRuntime | None = None
+        self._release_notifications: Callable[[], None] | None = None
+        self._release_logs: Callable[[], None] | None = None
+        self._host: RuntimeHost | None = None
+
+    def attach(self, host: RuntimeHost) -> None:
+        self._host = host
+        self._apply_log_settings()
+        self._apply_secrets()
+        self._apply_assets()
+        self._apply_slots()
+        self._apply_mounts()
+
+    def share_slots(self, store: SlotStore) -> None:
+        """Hold values here rather than in the surrounding runtime's cells.
+
+        Set by a service with more than one pipeline that has to hold something
+        between them.
+        """
+        self._shared = store
+        self._apply_slots()
+
+    def find(self, instance_id: str) -> Any | None:
+        """One of the services here, by the name it carries — for an address."""
+        return self._runtime.get_service(instance_id) if self._runtime else None
+
+    def is_empty(self) -> bool:
+        return not self._runtime or not self._runtime.list_services()
+
+    def set_pipeline(self, value: Any) -> None:
+        if not isinstance(value, list):
+            raise ValueError(f"Invalid pipeline format for '{self._label}'")
+        nxt = _normalize_pipeline_array(value)
+        if nxt is None:
+            raise ValueError(f"Invalid pipeline format for '{self._label}'")
+        # A pipeline it already is, is not a change. Rebuilding destroys what is
+        # running inside it, and the commonest configure a service gets is the
+        # board handing back the state it just read.
+        if self._matches_live(nxt):
+            return
+        self._config = nxt
+        self._rebuild()
+
+    def append(self, entry: Any) -> None:
+        appended = _normalize_pipeline_entry(entry)
+        if not appended:
+            raise ValueError(f"Invalid appendService payload for '{self._label}'")
+        self._sync_states()
+        self._config.append(appended)
+        self._rebuild()
+
+    def remove(self, uuid: str) -> None:
+        self._sync_states()
+        self._config = [e for e in self._config if e.uuid != uuid]
+        self._rebuild()
+
+    def configure_service(self, instance_id: str, state: JsonRecord) -> None:
+        if not self._runtime:
+            return
+        self._runtime.configure_service(instance_id, state)
+        self._sync_states()
+
+    def process(self, input: Any, parent: Any) -> Any:
+        if not self._runtime or self.is_empty():
+            return input
+        # The callback is a no-op: the nested runtime already fans notifications
+        # out to the target registered in _rebuild.
+        return self._runtime.process(input, lambda _n: None, child_run(parent))
+
+    def state(self) -> list[dict[str, Any]]:
+        if not self._runtime:
+            return [
+                {"serviceId": e.service_id, "instanceId": e.uuid, "state": e.state or {}}
+                for e in self._config
+            ]
+        return [
+            {"serviceId": svc.service_id, "instanceId": svc.uuid, "state": svc.state}
+            for svc in self._runtime.list_services()
+        ]
+
+    def services(self) -> list[Any]:
+        return self._runtime.list_services() if self._runtime else []
+
+    def destroy(self) -> None:
+        self._release()
+        if self._runtime:
+            self._runtime.destroy()
+            self._runtime = None
+
+    # ── Private ────────────────────────────────────────────────────────────────
+
+    def _matches_live(self, nxt: list[ServiceConfiguration]) -> bool:
+        if not self._runtime:
+            return False
+        live = self.state()
+        if len(live) != len(nxt):
+            return False
+        return all(
+            current["serviceId"] == entry.service_id
+            and current["instanceId"] == entry.uuid
+            and current["state"] == (entry.state or {})
+            for current, entry in zip(live, nxt)
+        )
+
+    def _rebuild(self) -> None:
+        self._release()
+        if self._runtime:
+            self._runtime.destroy()
+
+        self._runtime = HostedRuntime(
+            _make_runtime_config(self._label, self._owner, self._config),
+            self._create_service,
+        )
+        # Under a scoped address, not the bare instanceId: an instanceId is
+        # unique only inside its own pipeline, so each boundary prefixes its
+        # owner on the way out. See address.py.
+        self._release_notifications = self._runtime.register_notification_target(
+            # With the run it was reported in, which only the nested runtime
+            # knows when its pipeline was entered directly rather than through
+            # this service's own call.
+            lambda n: self._host.notify(
+                n.payload, join_address(self._owner_uuid, n.instance_id), n.context
+            )
+            if self._host
+            else None
+        )
+        self._release_logs = self._runtime.register_log_target(
+            lambda entry: self._host.forward_log(entry) if self._host else None
+        )
+        self._apply_log_settings()
+        self._apply_secrets()
+        self._apply_assets()
+        self._apply_slots()
+        self._apply_mounts()
+
+    def _release(self) -> None:
+        if self._release_notifications:
+            self._release_notifications()
+            self._release_notifications = None
+        if self._release_logs:
+            self._release_logs()
+            self._release_logs = None
+
+    def _apply_secrets(self) -> None:
+        if self._runtime:
+            self._runtime.delegate_secrets(
+                lambda: self._host.secrets() if self._host else None
+            )
+
+    def _apply_assets(self) -> None:
+        """Points the nested runtime at the surrounding runtime's assets, for the
+        same reason as secrets: nothing provisions it, so it asks outward on each
+        lookup and sees an asset edited while the board runs."""
+        if self._runtime is not None:
+            self._runtime.delegate_assets(
+                lambda: self._host.assets() if self._host and hasattr(self._host, "assets") else None
+            )
+
+    def _apply_slots(self) -> None:
+        """Points the nested runtime at the cells its values are held in.
+
+        A store the owning service provided is what two of its pipelines share;
+        with none, the surrounding runtime's is used, so a slot named inside a
+        pipeline means what the same name means outside it. Read on each lookup,
+        for the same reason secrets are: the pipeline is attached before the
+        host is necessarily able to answer.
+        """
+        if not self._runtime:
+            return
+        self._runtime.delegate_slots(
+            lambda: self._shared
+            if self._shared is not None
+            else (self._host.slots() if self._host else None)
+        )
+
+    def _apply_mounts(self) -> None:
+        """Lets the services inside claim an endpoint on the runtime outside.
+
+        Same reason as slots and secrets: a nested runtime has no server of its
+        own. The name falls back to the scoped address, so two containers
+        holding a pipeline that names no mount do not derive one address
+        between them.
+        """
+        if not self._runtime:
+            return
+        self._runtime.delegate_mounts(
+            lambda service_uuid, handler, mount_name: (
+                self._host.mount(
+                    service_uuid,
+                    handler,
+                    mount_name or join_address(self._owner_uuid, service_uuid),
+                )
+                if self._host
+                else None
+            )
+        )
+
+    def _apply_log_settings(self) -> None:
+        if not self._host or not self._runtime:
+            return
+        settings = self._host.log_settings()
+        self._runtime.set_logging(settings["logging"])
+        self._runtime.set_log_data(settings["log_data"])
+        self._runtime.set_log_level(settings["log_level"])
+
+    def _sync_states(self) -> None:
+        if not self._runtime:
+            return
+        by_id = {svc.uuid: svc.state for svc in self._runtime.list_services()}
+        self._config = [
+            ServiceConfiguration(
+                service_id=e.service_id,
+                uuid=e.uuid,
+                name=e.name,
+                service_name=e.service_name,
+                state=by_id.get(e.uuid, e.state),
+            )
+            for e in self._config
+        ]

package/bundle/hkp-python/src/hkp/services/skill_router.py

@@ -0,0 +1,388 @@
+from __future__ import annotations
+
+# Service Documentation
+# Service ID: skill-router
+# Service Name: Skill Router
+# Runtime: hkp-python
+# Modes: route (one LLM call, strict JSON output), via one of two backends
+#        selected by the `backend` state — server (default, OpenAI-compatible
+#        HTTP) or local (in-process GGUF via llama-cpp-python), exactly as in
+#        the text-generation service
+# Key Config: skills (array of {action, board, payload}), backend,
+#             serverUrl, model (server backend),
+#             modelPath, contextSize, gpuLayers (local backend),
+#             temperature, maxTokens, timeoutSec,
+#             stream (default true — consume the model output token by token,
+#             notifying the growing text as {streamText} so the service UI's
+#             process view can show the routing decision being generated; the
+#             pipeline output is unaffected and still emitted once, at the end)
+# IO: in=String/TextData (the request) or JSON ({text} | {prompt})
+#     -> out=JSON { board, payload } for the matched skill, or None (stop)
+# Arrays: n/a
+# Binary: not supported; non-text inputs yield an error JSON
+# MixedData: not supported
+#
+# Matches free-form text (e.g. a voice transcript) against a configured set of
+# skills and extracts the payload parameters, using the same local
+# LLM backends as the text-generation service. On a match the
+# routing decision is final: the result is early-returned (ControlFlowData),
+# skipping any services after the router in the same runtime. The noMatch
+# config decides the other branch: "stop" (default) ends the pipeline,
+# "forward" passes the original input to the remaining services — e.g. a
+# text-generation fallback that answers requests no skill covers.
+# A skill looks like:
+#
+#   { "action": "send notification", "board": "send ntfy",
+#     "payload": { "topic": "the ntfy topic", "message": "the message text" } }
+#
+# The payload template's keys are the parameter names; its values describe to
+# the model what to extract. On a match the service emits
+# { "board": <skill.board>, "payload": { ...extracted values... } } — a browser
+# Board-Service in "input" board-source mode then plays that saved board with
+# the payload. No match (or unparseable model output) returns None, which
+# stops the pipeline. Backend errors return an error JSON so they stay visible
+# on monitors.
+
+import json
+import time
+import urllib.error
+from typing import Any
+
+from ..data import ControlFlowData, TextData
+from ..types import JsonRecord, NotifyCallback, ServiceConfiguration, ServiceRegistryEntry
+from .text_generation import (
+    _BACKENDS,
+    INSTALL_HINT,
+    THINK_CLOSE,
+    THINK_OPEN,
+    LocalLlm,
+    _consume_stream,
+    _post_json,
+    _post_json_stream,
+    server_hint,
+)
+
+SKILL_ROUTER_DESCRIPTOR = ServiceRegistryEntry(
+    service_id="skill-router",
+    service_name="Skill Router",
+)
+
+DEFAULT_SERVER_URL = "http://127.0.0.1:8081"
+# Routing wants determinism, not creativity.
+DEFAULT_TEMPERATURE = 0.1
+DEFAULT_MAX_TOKENS = 256
+DEFAULT_TIMEOUT_SEC = 120.0
+
+SYSTEM_PROMPT = (
+    "You route user requests to skills. You are given a list of skills, each "
+    "with an \"action\" describing what it does and a \"payload\" object whose "
+    "keys are parameter names and whose values describe what to extract from "
+    "the request.\n"
+    "Reply with ONLY a JSON object, no other text:\n"
+    '- If one skill matches: {"action": "<the matched skill\'s action>", '
+    '"payload": {<parameter name>: <extracted value>, ...}}\n'
+    '- If no skill matches: {"action": null}\n'
+    "Extract payload values verbatim from the request where possible. Omit "
+    "parameters the request does not mention."
+)
+
+
+def _is_skill(entry: Any) -> bool:
+    return (
+        isinstance(entry, dict)
+        and isinstance(entry.get("action"), str)
+        and bool(entry["action"])
+        and isinstance(entry.get("board"), str)
+        and bool(entry["board"])
+        and isinstance(entry.get("payload"), dict)
+    )
+
+
+def _strip_thinking(message: JsonRecord) -> str:
+    """Thinking models put reasoning in reasoning_content or inline
+    <think> tags; routing only cares about the answer."""
+    content = message.get("content") or ""
+    if THINK_CLOSE in content:
+        _, _, content = content.partition(THINK_CLOSE)
+    return content.replace(THINK_OPEN, "").strip()
+
+
+def _extract_json_object(text: str) -> JsonRecord | None:
+    try:
+        parsed = json.loads(text)
+        return parsed if isinstance(parsed, dict) else None
+    except json.JSONDecodeError:
+        pass
+    start = text.find("{")
+    end = text.rfind("}")
+    if start == -1 or end <= start:
+        return None
+    try:
+        parsed = json.loads(text[start : end + 1])
+        return parsed if isinstance(parsed, dict) else None
+    except json.JSONDecodeError:
+        return None
+
+
+class SkillRouterService:
+    service_id = SKILL_ROUTER_DESCRIPTOR.service_id
+    service_name = SKILL_ROUTER_DESCRIPTOR.service_name
+    version: str | None = None
+    capabilities: list[str] | None = None
+
+    def __init__(self, config: ServiceConfiguration, _create_service: Any = None) -> None:
+        self.uuid = config.uuid
+        self._backend = "server"
+        self._server_url = DEFAULT_SERVER_URL
+        self._model = ""
+        self._local = LocalLlm()
+        self._skills: list[JsonRecord] = []
+        self._temperature = DEFAULT_TEMPERATURE
+        self._max_tokens = DEFAULT_MAX_TOKENS
+        self._timeout_sec = DEFAULT_TIMEOUT_SEC
+        self._no_match: str = "stop"
+        self._stream = True
+        self._status = "idle"
+        # The most recent LLM call — request text, composed messages, raw model
+        # output, and the routing decision — inspectable in the UI to debug
+        # prompt composition and the model's routing behavior.
+        self._last_prompt: list[JsonRecord] = []
+        self._last_request = ""
+        self._last_output = ""
+        self._last_match: JsonRecord | None = None
+
+        if config.state:
+            self.configure(config.state)
+
+    def configure(self, config: JsonRecord) -> JsonRecord:
+        if config.get("backend") in _BACKENDS:
+            self._backend = config["backend"]
+        if isinstance(config.get("serverUrl"), str) and config["serverUrl"]:
+            self._server_url = config["serverUrl"].rstrip("/")
+        if isinstance(config.get("model"), str):
+            self._model = config["model"]
+        self._local.configure(config)
+        if isinstance(config.get("skills"), list):
+            self._skills = [s for s in config["skills"] if _is_skill(s)]
+        if isinstance(config.get("temperature"), (int, float)) and not isinstance(
+            config.get("temperature"), bool
+        ):
+            self._temperature = float(config["temperature"])
+        if (
+            isinstance(config.get("maxTokens"), (int, float))
+            and not isinstance(config.get("maxTokens"), bool)
+            and config["maxTokens"] > 0
+        ):
+            self._max_tokens = int(config["maxTokens"])
+        if (
+            isinstance(config.get("timeoutSec"), (int, float))
+            and not isinstance(config.get("timeoutSec"), bool)
+            and config["timeoutSec"] > 0
+        ):
+            self._timeout_sec = float(config["timeoutSec"])
+        if config.get("noMatch") in ("stop", "forward"):
+            self._no_match = config["noMatch"]
+        if isinstance(config.get("stream"), bool):
+            self._stream = config["stream"]
+        return self.get_state()
+
+    def get_state(self) -> JsonRecord:
+        return {
+            "backend": self._backend,
+            "serverUrl": self._server_url,
+            "model": self._model,
+            **self._local.state(),
+            "skills": self._skills,
+            "temperature": self._temperature,
+            "maxTokens": self._max_tokens,
+            "timeoutSec": self._timeout_sec,
+            "noMatch": self._no_match,
+            "stream": self._stream,
+            "status": self._status,
+            "lastRequest": self._last_request,
+            "lastPrompt": self._last_prompt,
+            "lastOutput": self._last_output,
+            "lastMatch": self._last_match,
+        }
+
+    def process(self, input: Any, notify: NotifyCallback) -> Any:
+        if input is None:
+            return None
+
+        text = self._to_text(input)
+        if text is None:
+            return self._error(
+                notify, "skill-router expects String input or JSON with 'text' or 'prompt'"
+            )
+        if not self._skills:
+            self._set_status(notify, "idle")
+            notify({"matched": None, "reason": "no skills configured"})
+            return input if self._no_match == "forward" else None
+
+        # Routing output must not be eaten by an invisible thinking budget.
+        # The server backend disables thinking via chat_template_kwargs below;
+        # the local backend has no such switch, so use the Qwen-style prompt
+        # marker instead (harmless for non-thinking models).
+        system_prompt = SYSTEM_PROMPT + (" /no_think" if self._backend == "local" else "")
+        messages: list[JsonRecord] = [
+            {"role": "system", "content": system_prompt},
+            {
+                "role": "user",
+                "content": "Skills:\n"
+                + json.dumps(
+                    [{"action": s["action"], "payload": s["payload"]} for s in self._skills]
+                )
+                + "\n\nRequest:\n"
+                + text,
+            },
+        ]
+
+        self._last_request = text
+        self._last_prompt = messages
+        notify({"lastRequest": text, "lastPrompt": self._last_prompt})
+
+        if self._backend == "local":
+            if not self._local.model_path:
+                return self._error(
+                    notify, "local backend needs a modelPath pointing to a .gguf file"
+                )
+            try:
+                llama = self._local.ensure(
+                    lambda detail: self._set_status(notify, "loading", detail=detail)
+                )
+            except ImportError:
+                return self._error(notify, INSTALL_HINT)
+            except Exception as exc:
+                return self._error(
+                    notify, f"failed to load model '{self._local.model_path}': {exc}"
+                )
+
+            self._set_status(notify, "routing")
+            started = time.monotonic()
+            try:
+                if self._stream:
+                    chunks = llama.create_chat_completion(
+                        messages=messages,
+                        temperature=self._temperature,
+                        max_tokens=self._max_tokens,
+                        stream=True,
+                    )
+                    response = _consume_stream(chunks, notify)
+                else:
+                    response = llama.create_chat_completion(
+                        messages=messages,
+                        temperature=self._temperature,
+                        max_tokens=self._max_tokens,
+                    )
+            except Exception as exc:
+                return self._error(notify, f"routing failed: {exc}")
+        else:
+            payload: JsonRecord = {
+                "messages": messages,
+                "temperature": self._temperature,
+                "max_tokens": self._max_tokens,
+                "stream": self._stream,
+                # llama-server extension; harmless elsewhere.
+                "chat_template_kwargs": {"enable_thinking": False},
+            }
+            if self._model:
+                payload["model"] = self._model
+
+            self._set_status(notify, "routing")
+            started = time.monotonic()
+            try:
+                if self._stream:
+                    chunks = _post_json_stream(
+                        f"{self._server_url}/v1/chat/completions", payload, self._timeout_sec
+                    )
+                    response = _consume_stream(chunks, notify)
+                else:
+                    response = _post_json(
+                        f"{self._server_url}/v1/chat/completions", payload, self._timeout_sec
+                    )
+            except urllib.error.HTTPError as exc:
+                detail = exc.read().decode("utf-8", errors="replace")[:200]
+                return self._error(notify, f"server returned HTTP {exc.code}: {detail}")
+            except (urllib.error.URLError, OSError):
+                return self._error(notify, server_hint(self._server_url))
+
+        try:
+            message = response["choices"][0]["message"]
+        except (KeyError, IndexError, TypeError):
+            return self._error(notify, f"unexpected response shape: {str(response)[:200]}")
+
+        raw_output = _strip_thinking(message)
+        self._last_output = raw_output
+        notify({"lastOutput": raw_output})
+
+        decision = _extract_json_object(raw_output)
+        duration_ms = int((time.monotonic() - started) * 1000)
+        self._set_status(notify, "idle")
+
+        skill = self._find_skill(decision)
+        if skill is None:
+            # No match, unknown action, or unparseable output — all mean
+            # "nothing to dispatch": stop the pipeline, or forward the
+            # original input to the services after the router.
+            self._last_match = {"matched": None, "durationMs": duration_ms}
+            notify(dict(self._last_match))
+            return input if self._no_match == "forward" else None
+
+        extracted = decision.get("payload") if isinstance(decision, dict) else None
+        extracted = extracted if isinstance(extracted, dict) else {}
+        # Only parameters the skill declares; the model must not smuggle in
+        # extra fields.
+        result_payload = {k: extracted[k] for k in skill["payload"] if k in extracted}
+
+        result = {"board": skill["board"], "payload": result_payload}
+        self._last_match = {"matched": skill["action"], "durationMs": duration_ms, **result}
+        notify(dict(self._last_match))
+        # The routing decision is final — skip any services after the router
+        # (e.g. a text-generation fallback) and emit the dispatch payload.
+        return ControlFlowData(result)
+
+    def set_host(self, host: Any) -> None:
+        pass
+
+    def destroy(self) -> None:
+        self._local.release()
+
+    # ── Internals ──────────────────────────────────────────────────────────────
+
+    @staticmethod
+    def _to_text(input: Any) -> str | None:
+        text: str | None = None
+        if isinstance(input, str):
+            text = input
+        elif isinstance(input, TextData):
+            text = input.text
+        elif isinstance(input, dict):
+            for key in ("text", "prompt"):
+                if isinstance(input.get(key), str) and input[key]:
+                    text = input[key]
+                    break
+        if text is None or not text.strip():
+            return None
+        return text.strip()
+
+    def _find_skill(self, decision: JsonRecord | None) -> JsonRecord | None:
+        if not isinstance(decision, dict) or not isinstance(decision.get("action"), str):
+            return None
+        action = decision["action"].strip().lower()
+        for skill in self._skills:
+            if skill["action"].strip().lower() == action:
+                return skill
+        return None
+
+    def _set_status(self, notify: NotifyCallback, status: str, detail: str | None = None) -> None:
+        self._status = status
+        payload: JsonRecord = {"status": status}
+        if detail is not None:
+            payload["detail"] = detail
+        notify(payload)
+
+    def _error(self, notify: NotifyCallback, message: str) -> JsonRecord:
+        self._set_status(notify, "error")
+        result = {"error": message}
+        notify(result)
+        return result