plm-skill-kernel 1.1.0__tar.gz → 1.2.0__tar.gz

{plm_skill_kernel-1.1.0 → plm_skill_kernel-1.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plm-skill-kernel
-Version: 1.1.0
+Version: 1.2.0
 Summary: TracePulse PLM Skill Kernel — Wave 2 Conv A. Decorator-based Skill SDK + V1 in-process dispatcher + Kernel HTTP server stub matching CR.10 §7.bis (POST /v1/skills/{id}/invoke). Ships 3 starter skills (cleansing.normalise, cleansing.dedupe, bpmn.generate). Sibling of plm-engine-core; the two communicate over the V1.1 HTTP loopback (SKILL_KERNEL_LOOPBACK=on) — no Python-level coupling at the dispatch boundary.
 Author: TracePulse
 License: Proprietary

{plm_skill_kernel-1.1.0 → plm_skill_kernel-1.2.0}/plm_skill_kernel/__init__.py

@@ -14,7 +14,7 @@ sanctioned interaction is the V1.1 HTTP loopback (env-flagged on
 ``SKILL_KERNEL_LOOPBACK``); any Python-level reach-in is forbidden by
 the import-linter contract in ``pyproject.toml``.
 """
-__version__ = "1.1.0"
+__version__ = "1.2.0"
 
 # The decorator + sdk surface is the public authoring API. Re-exported
 # here so callers write ``from plm_skill_kernel import skill`` rather

plm_skill_kernel-1.2.0/plm_skill_kernel/executor/__init__.py

@@ -0,0 +1,47 @@
+"""MVP skill-executor package — ordered-task execution over the V1 kernel.
+
+This package is a **net-new, demo-scoped** layer built for the Runnable
+Skill-Kernel MVP (backlog **FTR-2231** / story **FTR-2232 / E1**). It sits
+*on top of* the existing V1 primitives without changing any of them:
+
+* it reuses :class:`plm_skill_kernel.dispatcher.InProcessDispatcher` to run
+  each task (the dispatcher still invokes exactly one callable per call);
+* it does **not** touch the frozen wire shapes
+  (:mod:`plm_skill_kernel.sdk.types`) or the frozen
+  :class:`plm_skill_kernel.sdk.context.SkillContext`;
+* foundation knowledge is threaded through the inter-task *payload*
+  envelope (a reserved ``foundation`` key), never by mutating the governed
+  context model — so the whole layer is additive and reversible.
+
+The demo thesis this enables: *an agent delegates a request to a
+well-known, certified, controlled skill composed of an ordered set of
+tasks, instead of solving the request itself.* The multi-task skill is the
+deliberate highlight; see the MVP plan in ``.claude/thoughts``.
+
+Nothing here is on the governed ``POST /v1/skills/{id}/invoke`` critical
+path; the executor is driven by the demo entrypoint + tests.
+"""
+from __future__ import annotations
+
+from .binding import BindingNotFound, resolve_binding
+from .executor import SkillExecutor, TaskFailure
+from .knowledge import EchoKnowledgeProvider, KnowledgeProvider, NullKnowledgeProvider
+from .plan import SkillPlan, TaskStep
+from .request import REQUEST_TEXT_KEY, parse_request
+from .selector import UnroutableRequest, select_skill
+
+__all__ = [
+    "BindingNotFound",
+    "EchoKnowledgeProvider",
+    "KnowledgeProvider",
+    "NullKnowledgeProvider",
+    "REQUEST_TEXT_KEY",
+    "SkillExecutor",
+    "SkillPlan",
+    "TaskFailure",
+    "TaskStep",
+    "UnroutableRequest",
+    "parse_request",
+    "resolve_binding",
+    "select_skill",
+]

plm_skill_kernel-1.2.0/plm_skill_kernel/executor/_catalog_fixture.py

@@ -0,0 +1,80 @@
+"""Demo catalog fixture (FTR-2232 / E1).
+
+# MOCK(MVP-DEMO): this is a demo-scoped skill *catalog*, not the governed
+# skill registry or the ``manifest-profile/1.0`` authoring surface. It maps a
+# composite skill id to its ordered :class:`SkillPlan`. The concrete,
+# *certified* demo skill package is story FTR-2235 / E4 — it replaces /
+# extends this fixture with a data-dependent, human-signed-off plan. E1 ships
+# only a structurally-valid, resolvable entry so ``resolve_binding`` has
+# something to resolve and the seam is exercised end to end.
+
+The demo plan below composes two already-registered V1 knowledge skills into
+one ordered, two-task composite skill and threads a foundation-knowledge
+lookup into the first task — enough to demonstrate the executor mechanism.
+The ``certified`` / ``controlled`` flags are advisory demo values (present,
+unenforced); they must never be read as real ratifications.
+"""
+from __future__ import annotations
+
+from typing import Dict, Tuple
+
+from .plan import SkillPlan, TaskStep
+
+# A demo corpus id understood by the in-process knowledge seed corpus.
+_DEMO_CORPUS = "foundation"
+
+DEMO_SKILL_ID = "demo.knowledge_lookup"
+DEMO_SKILL_VERSION = "0.1.0"
+
+_DEMO_PLAN = SkillPlan(
+    skill_id=DEMO_SKILL_ID,
+    version=DEMO_SKILL_VERSION,
+    description=(
+        "Demo composite skill: search the foundation corpus, then fetch a "
+        "record — an ordered two-task skill the agent delegates to."
+    ),
+    # MOCK(MVP-DEMO): fixture governance flags — not real certification.
+    certified=True,
+    controlled=True,
+    tasks=(
+        TaskStep(
+            task_id="search",
+            skill_id="knowledge.search",
+            version="1.0.0",
+            description="Ordered task 1 — semantic search over the corpus.",
+            static_payload={"corpus_id": _DEMO_CORPUS, "top_k": 5},
+            input_keys=("query",),
+            knowledge_query="foundation overview",
+            output_key="search_result",
+        ),
+        TaskStep(
+            task_id="get_record",
+            skill_id="knowledge.get_record",
+            version="1.0.0",
+            description="Ordered task 2 — fetch a specific record by id.",
+            static_payload={"corpus_id": _DEMO_CORPUS},
+            input_keys=("record_id",),
+            output_key="record_result",
+        ),
+    ),
+)
+
+
+# Catalog is keyed by (skill_id, version); a None-version lookup resolves to
+# the sole registered version for that id (demo convenience).
+DEMO_CATALOG: Dict[Tuple[str, str], SkillPlan] = {
+    (DEMO_SKILL_ID, DEMO_SKILL_VERSION): _DEMO_PLAN,
+}
+
+
+def build_demo_catalog() -> Dict[Tuple[str, str], SkillPlan]:
+    """Return a fresh copy of the demo catalog (callers may extend it)."""
+    return dict(DEMO_CATALOG)
+
+
+__all__ = [
+    "DEMO_CATALOG",
+    "DEMO_SKILL_ID",
+    "DEMO_SKILL_VERSION",
+    "build_demo_catalog",
+]

plm_skill_kernel-1.2.0/plm_skill_kernel/executor/binding.py

@@ -0,0 +1,64 @@
+"""``resolve_binding`` — resolve a composite skill id to its ordered plan.
+
+FTR-2232 / E1. The V1 SDK registry only maps ``(skill_id, version)`` to a
+single callable (``_Registry.resolve``); there is no notion of resolving a
+skill to a *plan of tasks*. ``resolve_binding`` is that thin missing lookup,
+kept deliberately separate from the callable registry: it resolves against a
+**catalog** of :class:`SkillPlan` fixtures (see :mod:`._catalog_fixture`).
+
+It is intentionally minimal — a dict lookup with a None-version convenience —
+so it can later be backed by a real catalog service behind the same
+signature without touching callers.
+"""
+from __future__ import annotations
+
+from typing import Dict, Mapping, Optional, Tuple
+
+from .plan import SkillPlan
+
+
+class BindingNotFound(LookupError):
+    """Raised when no catalog plan matches ``(skill_id, version)``."""
+
+
+def resolve_binding(
+    skill_id: str,
+    version: Optional[str] = None,
+    *,
+    catalog: Mapping[Tuple[str, str], SkillPlan],
+) -> SkillPlan:
+    """Resolve ``skill_id`` (+ optional ``version``) to a :class:`SkillPlan`.
+
+    Args:
+        skill_id: composite skill id the agent delegates to.
+        version: exact version to resolve. When ``None``, the sole plan
+            registered under ``skill_id`` is returned; ambiguity (more than
+            one version) is an error so the caller is forced to be explicit.
+        catalog: mapping of ``(skill_id, version)`` → plan (the fixture).
+
+    Raises:
+        BindingNotFound: no plan for that id (and version, if given), or a
+            ``None`` version with multiple candidates.
+    """
+    if version is not None:
+        plan = catalog.get((skill_id, version))
+        if plan is None:
+            raise BindingNotFound(
+                f"no plan bound for skill_id={skill_id!r} version={version!r}"
+            )
+        return plan
+
+    candidates: Dict[str, SkillPlan] = {
+        v: p for (sid, v), p in catalog.items() if sid == skill_id
+    }
+    if not candidates:
+        raise BindingNotFound(f"no plan bound for skill_id={skill_id!r}")
+    if len(candidates) > 1:
+        raise BindingNotFound(
+            f"skill_id={skill_id!r} has {len(candidates)} versions "
+            f"({sorted(candidates)}); specify one"
+        )
+    return next(iter(candidates.values()))
+
+
+__all__ = ["BindingNotFound", "resolve_binding"]

plm_skill_kernel-1.2.0/plm_skill_kernel/executor/executor.py

@@ -0,0 +1,173 @@
+"""Thin ordered-task executor (FTR-2232 / E1).
+
+The V1 kernel dispatcher invokes exactly one callable per call. This
+executor is the missing layer above it: it runs a :class:`SkillPlan`'s tasks
+**in order**, threading a running ``state`` dict and foundation knowledge
+between them, and reusing :class:`InProcessDispatcher` for every task. It
+adds no new dispatch path — each task is an ordinary registered skill
+resolved through the SDK registry.
+
+Contract discipline:
+
+* the frozen wire shapes (:mod:`plm_skill_kernel.sdk.types`) and
+  :class:`SkillContext` are used **unchanged**;
+* foundation knowledge is injected into a task's payload under the reserved
+  ``foundation`` key (see :mod:`.knowledge`), never onto the context;
+* a task that fails (dispatcher returns ``ok=False``) stops the chain and
+  the executor returns that task's error envelope verbatim, annotated with
+  the failing ``task_id`` — the composite skill fails closed.
+"""
+from __future__ import annotations
+
+import logging
+from typing import Any, Dict, Optional
+
+from ..dispatcher import InProcessDispatcher
+from ..sdk.context import SkillContext
+from ..sdk.types import SkillErrorEnvelope, SkillInvokeRequest, SkillInvokeResult
+from .knowledge import KnowledgeProvider, NullKnowledgeProvider
+from .plan import SkillPlan, TaskStep
+
+logger = logging.getLogger(__name__)
+
+# Reserved payload key under which foundation snippets are threaded.
+FOUNDATION_KEY = "foundation"
+
+# Error code for an executor-level plan failure (a task returned ok=False).
+# Reuses the KERNEL_* namespace convention; demo-scoped.
+EXECUTOR_TASK_FAILED = "EXECUTOR_TASK_FAILED"
+
+
+class TaskFailure(Exception):
+    """Raised internally when a task returns ``ok=False``; converted to a
+    :class:`SkillInvokeResult` at the executor boundary.
+    """
+
+    def __init__(self, task_id: str, error: Optional[SkillErrorEnvelope]) -> None:
+        self.task_id = task_id
+        self.error = error
+        super().__init__(f"task {task_id!r} failed")
+
+
+class SkillExecutor:
+    """Runs a :class:`SkillPlan`'s ordered tasks over the V1 dispatcher.
+
+    Construct with an explicit dispatcher + knowledge provider so tests can
+    isolate registration state and assert knowledge threading. Both default
+    to safe production-ish values (the module registry dispatcher, and a
+    no-op knowledge provider).
+    """
+
+    def __init__(
+        self,
+        dispatcher: Optional[InProcessDispatcher] = None,
+        knowledge: Optional[KnowledgeProvider] = None,
+    ) -> None:
+        self._dispatcher = dispatcher if dispatcher is not None else InProcessDispatcher()
+        self._knowledge = knowledge if knowledge is not None else NullKnowledgeProvider()
+
+    async def run(
+        self,
+        plan: SkillPlan,
+        initial_state: Optional[Dict[str, Any]] = None,
+        *,
+        context: SkillContext,
+    ) -> SkillInvokeResult:
+        """Execute ``plan`` end-to-end.
+
+        Returns a :class:`SkillInvokeResult`. On success ``result`` is the
+        final running state plus a ``_trace`` list recording each task's id,
+        skill, and whether knowledge was injected — so the demo can *show*
+        that the agent delegated to a multi-task skill. On the first task
+        failure the executor stops and surfaces that task's error.
+        """
+        state: Dict[str, Any] = dict(initial_state or {})
+        trace: list[Dict[str, Any]] = []
+
+        try:
+            for step in plan.tasks:
+                state = await self._run_task(step, state, context, trace)
+        except TaskFailure as tf:
+            return SkillInvokeResult(
+                ok=False,
+                error=tf.error
+                or SkillErrorEnvelope(
+                    error_code=EXECUTOR_TASK_FAILED,
+                    message=f"task {tf.task_id!r} failed without an error envelope",
+                    detail={"task_id": tf.task_id},
+                ),
+            )
+
+        state["_trace"] = trace
+        return SkillInvokeResult(ok=True, result=state)
+
+    async def _run_task(
+        self,
+        step: TaskStep,
+        state: Dict[str, Any],
+        context: SkillContext,
+        trace: list[Dict[str, Any]],
+    ) -> Dict[str, Any]:
+        payload = self._build_payload(step, state)
+
+        injected = False
+        if step.knowledge_query:
+            snippets = self._knowledge.fetch(step.knowledge_query)
+            # Inject even when empty so tasks can rely on the key existing.
+            payload[FOUNDATION_KEY] = snippets
+            injected = bool(snippets)
+
+        request = SkillInvokeRequest(
+            payload=payload,
+            version=step.version,
+            autonomy_hint=context.autonomy_level,
+        )
+        # Per-task context mirrors the composite context but names the task's
+        # own skill id/version (the frozen model is rebuilt, never mutated).
+        task_ctx = context.model_copy(
+            update={"skill_id": step.skill_id, "skill_version": step.version}
+        )
+
+        result = await self._dispatcher.dispatch(
+            step.skill_id, request, context=task_ctx
+        )
+
+        trace.append(
+            {
+                "task_id": step.task_id,
+                "skill_id": step.skill_id,
+                "version": step.version,
+                "knowledge_injected": injected,
+                "ok": result.ok,
+            }
+        )
+
+        if not result.ok:
+            raise TaskFailure(step.task_id, result.error)
+
+        return self._merge_result(step, state, result.result or {})
+
+    @staticmethod
+    def _build_payload(step: TaskStep, state: Dict[str, Any]) -> Dict[str, Any]:
+        if step.input_keys:
+            payload = {k: state[k] for k in step.input_keys if k in state}
+        else:
+            payload = dict(state)
+        # Never leak the executor's own trace into a task payload.
+        payload.pop("_trace", None)
+        payload.update(step.static_payload)
+        return payload
+
+    @staticmethod
+    def _merge_result(
+        step: TaskStep, state: Dict[str, Any], result: Dict[str, Any]
+    ) -> Dict[str, Any]:
+        new_state = dict(state)
+        if step.output_key:
+            new_state[step.output_key] = result
+        else:
+            new_state.update(result)
+        return new_state
+
+
+__all__ = ["EXECUTOR_TASK_FAILED", "FOUNDATION_KEY", "SkillExecutor", "TaskFailure"]

plm_skill_kernel-1.2.0/plm_skill_kernel/executor/knowledge.py

@@ -0,0 +1,64 @@
+"""Foundation-knowledge seam for the MVP executor (FTR-2232 / E1).
+
+E1 delivers **the seam and the threading**, not the data. The concrete
+"simple-fake" foundation dataset is story **FTR-2233 / E2** and plugs in
+behind :class:`KnowledgeProvider` without touching the executor.
+
+Design choice (reversible): knowledge is threaded into each task through the
+inter-task **payload** envelope under the reserved ``foundation`` key — the
+executor calls ``provider.fetch(query)`` and injects the result. This keeps
+the frozen :class:`plm_skill_kernel.sdk.context.SkillContext` untouched. When
+the real ``plm-knowledge`` corpus is wired later, only the provider
+implementation changes; the executor and the demo skill's tasks do not.
+"""
+from __future__ import annotations
+
+from typing import Any, Dict, List, Protocol, runtime_checkable
+
+
+@runtime_checkable
+class KnowledgeProvider(Protocol):
+    """Minimal foundation-knowledge lookup surface.
+
+    A provider maps a free-text ``query`` to an ordered list of foundation
+    snippets (most relevant first). Each snippet is a plain JSON-able dict so
+    it threads cleanly through the task payload; the demo skill decides how
+    to read it. Implementations MUST be side-effect free and deterministic
+    for a given query (the demo must be reproducible).
+    """
+
+    def fetch(self, query: str) -> List[Dict[str, Any]]:
+        """Return foundation snippets relevant to ``query`` (may be empty)."""
+        ...
+
+
+class NullKnowledgeProvider:
+    """Provider that always returns no snippets.
+
+    The executor's default when no knowledge is wired — a plan whose tasks
+    set no ``knowledge_query`` runs identically with or without it.
+    """
+
+    def fetch(self, query: str) -> List[Dict[str, Any]]:  # noqa: D401
+        return []
+
+
+class EchoKnowledgeProvider:
+    """Trivial deterministic provider used only to prove the seam in E1.
+
+    Echoes the query back as a single snippet so E1 tests can assert that a
+    task actually received ``payload['foundation']``. **Not** the demo
+    dataset — E2 replaces this with the simple-fake foundation corpus.
+    """
+
+    def fetch(self, query: str) -> List[Dict[str, Any]]:
+        if not query:
+            return []
+        return [{"id": "echo-0", "query": query, "snippet": f"[echo] {query}"}]
+
+
+__all__ = [
+    "EchoKnowledgeProvider",
+    "KnowledgeProvider",
+    "NullKnowledgeProvider",
+]

plm_skill_kernel-1.2.0/plm_skill_kernel/executor/plan.py

@@ -0,0 +1,110 @@
+"""MVP task-list descriptor — "one skill → N ordered tasks".
+
+**Net-new for the MVP (FTR-2232 / E1).** This is deliberately *not* a
+change to :class:`plm_skill_kernel.sdk.types` (the frozen wire contract) nor
+to the manifest / ``manifest-profile/1.0`` authoring surface — the V1 skill
+manifest cannot express an ordered set of tasks, and adding that to the
+governed profile is out of scope for the demo. Instead, a :class:`SkillPlan`
+is a thin executor-side descriptor: it names, in order, the registered
+kernel skills that make up one composite skill, plus (optionally) the
+foundation-knowledge lookup to thread into each task.
+
+A :class:`SkillPlan` therefore composes existing single-callable skills into
+the multi-task skill the demo highlights. Each :class:`TaskStep` points at a
+skill already in the SDK registry (``skill_id`` + ``version``); the executor
+resolves and runs them through the ordinary dispatcher.
+
+Both models are ``frozen`` + ``extra="forbid"`` to mirror the discipline of
+the surrounding V1 contracts, but they live entirely in the demo layer.
+"""
+from __future__ import annotations
+
+from typing import Any, Dict, Optional, Tuple
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class TaskStep(BaseModel):
+    """One ordered task inside a :class:`SkillPlan`.
+
+    A task is a *reference* to a registered kernel skill; the executor runs
+    it via :class:`plm_skill_kernel.dispatcher.InProcessDispatcher`. Tasks
+    are chained by a running ``state`` dict (see :class:`SkillExecutor`):
+
+    * ``input_keys`` selects which keys of the running state are handed to
+      the task as its payload. Empty tuple ⇒ the whole running state is
+      passed (convenient default for short demo chains).
+    * ``static_payload`` is merged into the task payload verbatim (constants
+      the task needs that are not produced by an earlier task).
+    * ``knowledge_query`` — when set, the executor asks the knowledge
+      provider for foundation snippets and injects them into the task
+      payload under the reserved ``foundation`` key *before* dispatch.
+    * ``output_key`` — when set, the task's whole result dict is nested
+      under this key in the running state; otherwise the result is shallow
+      merged into the running state.
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    task_id: str = Field(min_length=1, description="Stable id, unique within the plan.")
+    skill_id: str = Field(min_length=1, description="Registered skill to invoke.")
+    version: str = Field(min_length=1, description="Registered skill version.")
+    description: Optional[str] = None
+    input_keys: Tuple[str, ...] = Field(
+        default=(),
+        description=(
+            "Running-state keys to pass as this task's payload. Empty ⇒ pass "
+            "the entire running state."
+        ),
+    )
+    static_payload: Dict[str, Any] = Field(
+        default_factory=dict,
+        description="Constant payload fields merged into the task input.",
+    )
+    knowledge_query: Optional[str] = Field(
+        default=None,
+        description=(
+            "Foundation-knowledge lookup to thread into this task. When set, "
+            "the executor injects results under payload['foundation']."
+        ),
+    )
+    output_key: Optional[str] = Field(
+        default=None,
+        description=(
+            "Nest the task result under this state key. Unset ⇒ shallow-merge "
+            "the result into the running state."
+        ),
+    )
+
+
+class SkillPlan(BaseModel):
+    """An ordered set of tasks that together form one composite skill.
+
+    ``skill_id`` / ``version`` identify the *composite* skill as the agent
+    knows it (the thing it delegates to); ``tasks`` is the ordered
+    decomposition the executor runs. ``certified`` / ``controlled`` are
+    demo-fixture governance flags — they are advisory here and MUST NOT be
+    treated as real ratifications (see the governance firewall in the MVP
+    plan; enforcement is intentionally absent — V0 fields-present-unenforced).
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    skill_id: str = Field(min_length=1)
+    version: str = Field(min_length=1)
+    description: Optional[str] = None
+    tasks: Tuple[TaskStep, ...] = Field(
+        min_length=1,
+        description="Ordered tasks; executed front-to-back.",
+    )
+    # MOCK(MVP-DEMO): demo-fixture governance flags. Real certification /
+    # control status requires human sign-off and lives in the FTR-2034
+    # register + published profile, never here. Present-but-unenforced.
+    certified: bool = False
+    controlled: bool = False
+
+    def task_ids(self) -> Tuple[str, ...]:
+        return tuple(t.task_id for t in self.tasks)
+
+
+__all__ = ["SkillPlan", "TaskStep"]

plm_skill_kernel-1.2.0/plm_skill_kernel/executor/request.py

@@ -0,0 +1,79 @@
+"""Request text → executor initial state (FTR-2232 / E1).
+
+The demo's agent request path has two halves:
+
+* :func:`plm_skill_kernel.executor.select_skill` decides *which* composite
+  skill to delegate to (a fixed keyword mapping — see :mod:`.selector`);
+* :func:`parse_request` decides *what starting data* that skill runs against,
+  by turning the raw request text into the executor's initial running state.
+
+Before this seam the request text only drove selection; every task input was
+hardcoded, so the demo ran the same regardless of what was asked. This makes
+the request text actually feed :meth:`SkillExecutor.run`'s ``initial_state``.
+
+# MOCK(MVP-DEMO): real natural-language understanding (entity extraction,
+# intent slots) is Core's job and is **not** wired here. This is a
+# deliberately trivial, deterministic parse — the whole request becomes the
+# ``query``, and an id-like token is lifted into ``record_id`` when the
+# request names one. It is legible and swappable for real parsing later
+# behind the same signature, exactly like :func:`select_skill`.
+"""
+from __future__ import annotations
+
+import re
+from typing import Any, Dict, Optional
+
+# Reserved state key holding the verbatim request text, for traceability in
+# the executor trace and for tasks that want the original wording.
+REQUEST_TEXT_KEY = "request_text"
+
+# MOCK(MVP-DEMO): lift an id-like token when the request explicitly names a
+# record/part/id, e.g. "get record R-100", "part PN-4523", "id: ABC_42".
+# First match wins; absence simply leaves ``record_id`` unset (the demo's
+# get_record task then relies on its own static defaults / upstream output).
+_RECORD_ID_RE = re.compile(
+    r"(?:record[_ ]?id|record|part(?:[_ ]?number)?|id)\s*[:#=]?\s*"
+    r"(?P<id>[A-Za-z]*[-_]?\d[A-Za-z0-9._-]*)",
+    re.IGNORECASE,
+)
+
+
+def parse_request(
+    request_text: str,
+    *,
+    extra: Optional[Dict[str, Any]] = None,
+) -> Dict[str, Any]:
+    """Turn ``request_text`` into the executor's initial running state.
+
+    Args:
+        request_text: the raw inbound request the agent received.
+        extra: optional pre-known state to merge in last (wins over parsed
+            values) — e.g. ids the caller already resolved out of band.
+
+    Returns:
+        A plain, JSON-able ``initial_state`` dict suitable as
+        :meth:`SkillExecutor.run`'s ``initial_state``. Always contains
+        ``request_text`` and ``query``; contains ``record_id`` only when the
+        request named one (or ``extra`` supplied it).
+    """
+    cleaned = (request_text or "").strip()
+
+    state: Dict[str, Any] = {
+        REQUEST_TEXT_KEY: cleaned,
+        # The search task consumes ``query`` (input_keys=("query",)); using the
+        # whole request keeps the demo honest — different requests search for
+        # different things.
+        "query": cleaned,
+    }
+
+    match = _RECORD_ID_RE.search(cleaned)
+    if match:
+        state["record_id"] = match.group("id")
+
+    if extra:
+        state.update(extra)
+
+    return state
+
+
+__all__ = ["REQUEST_TEXT_KEY", "parse_request"]