plm-skill-kernel 1.0.0__py3-none-any.whl

plm_skill_kernel/__init__.py

@@ -0,0 +1,33 @@
+"""TracePulse PLM Skill Kernel — Wave 2 Conv A (FTR-604).
+
+Sibling of ``plm-engine-core``. Owns:
+
+* The decorator-based Skill SDK (Decision #59 — Q-W2A-1 nested layout).
+* The V1 in-process dispatcher.
+* The Kernel HTTP server stub at ``POST /v1/skills/{id}/invoke``
+  matching CR.10 §7.bis verbatim.
+* 3 starter skills harvested per Decision #60 — ``cleansing.normalise``,
+  ``cleansing.dedupe``, ``bpmn.generate``.
+
+The Kernel and the Engine Core are deployed-separable. Their only
+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__ = "0.1.0-alpha"
+
+# The decorator + sdk surface is the public authoring API. Re-exported
+# here so callers write ``from plm_skill_kernel import skill`` rather
+# than the deeper path. Skill author imports stay short + stable.
+from .sdk.decorator import skill
+from .sdk.context import SkillContext
+from .sdk.types import SkillInvokeRequest, SkillInvokeResult, SkillErrorEnvelope
+
+__all__ = [
+    "SkillContext",
+    "SkillErrorEnvelope",
+    "SkillInvokeRequest",
+    "SkillInvokeResult",
+    "__version__",
+    "skill",
+]

plm_skill_kernel/__main__.py

@@ -0,0 +1,13 @@
+"""``python -m plm_skill_kernel`` entry — delegates to :func:`server._cli_entry`.
+
+Q-W2A-3 picked the standalone launch shape. The ``__main__`` module is
+the canonical Python idiom; the ``plm-skill-kernel`` console script
+points at the same function via ``pyproject.toml [project.scripts]``.
+"""
+from __future__ import annotations
+
+from .server import _cli_entry
+
+
+if __name__ == "__main__":
+    _cli_entry()

plm_skill_kernel/dispatcher.py

@@ -0,0 +1,141 @@
+"""V1 in-process Kernel dispatcher.
+
+Resolves ``(skill_id, version)`` against the SDK registry, validates the
+payload + context, and invokes the registered callable. Exceptions are
+caught + converted to a typed :class:`SkillInvokeResult` carrying a
+:class:`SkillErrorEnvelope` — bare exceptions never escape the dispatch
+boundary so the HTTP server can rely on always getting back a
+serialisable result.
+
+Decision #51 (Conv M / Q-M2 = (c) "Both"): the dispatcher lives in
+plm-skill-kernel; the plm-engine-core dispatcher (under
+``plm_engine_core.agent_runtime.dispatcher``) becomes a thin transport
+proxy when ``SKILL_KERNEL_LOOPBACK=on`` (Wave 2 Conv A item 8 — the
+V1.1 transport closure for D-CONV-M-4).
+"""
+from __future__ import annotations
+
+import logging
+from typing import Any, Dict, Optional
+
+from .sdk._registry import RegisteredSkill, _Registry, get_registry
+from .sdk.context import SkillContext
+from .sdk.types import (
+    SkillErrorEnvelope,
+    SkillInvokeRequest,
+    SkillInvokeResult,
+)
+
+
+logger = logging.getLogger(__name__)
+
+
+# ── Error codes (D-AUDIT-7 entries owned by the Skill Kernel) ────────────
+#
+# These mirror string-values declared on
+# ``plm_engine_core.control_plane.capability_registry.errors`` +
+# ``services/llm_errors.py``. Wave 2 Conv A re-uses the existing
+# ``SKILL_NOT_FOUND`` / ``SKILL_VERSION_NOT_FOUND`` /
+# ``KERNEL_DISPATCH_DISABLED`` strings (no new codes — the close
+# audit at Conv N tallied 57 codes; this conv keeps that total).
+SKILL_NOT_FOUND = "SKILL_NOT_FOUND"
+SKILL_VERSION_NOT_FOUND = "SKILL_VERSION_NOT_FOUND"
+KERNEL_DISPATCH_FAILED = "KERNEL_DISPATCH_FAILED"
+
+
+class InProcessDispatcher:
+    """V1 in-process invoker.
+
+    Constructor accepts an explicit registry so tests can isolate
+    registration state. Production callers receive the module-level
+    singleton via :func:`get_registry`.
+    """
+
+    def __init__(self, registry: Optional[_Registry] = None) -> None:
+        self._registry = registry if registry is not None else get_registry()
+
+    async def dispatch(
+        self,
+        skill_id: str,
+        request: SkillInvokeRequest,
+        *,
+        context: SkillContext,
+    ) -> SkillInvokeResult:
+        """Resolve + invoke a skill.
+
+        Returns a :class:`SkillInvokeResult` always — exceptions raised
+        by the skill body are caught and surfaced via the
+        ``KERNEL_DISPATCH_FAILED`` envelope.
+        """
+        entry = self._registry.resolve(skill_id, request.version)
+        if entry is None:
+            return self._not_found(skill_id, request.version)
+
+        try:
+            result = await entry.fn(dict(request.payload), context)
+        except Exception as exc:  # noqa: BLE001 — boundary; we re-package
+            logger.exception(
+                "skill dispatch failed skill_id=%s version=%s",
+                skill_id,
+                request.version,
+            )
+            return SkillInvokeResult(
+                ok=False,
+                error=SkillErrorEnvelope(
+                    error_code=KERNEL_DISPATCH_FAILED,
+                    message=f"skill {skill_id!r} raised {type(exc).__name__}",
+                    detail={"exception_message": str(exc)},
+                ),
+            )
+
+        # V1 contract: skills return a JSON-serialisable dict.
+        if not isinstance(result, dict):
+            return SkillInvokeResult(
+                ok=False,
+                error=SkillErrorEnvelope(
+                    error_code=KERNEL_DISPATCH_FAILED,
+                    message=(
+                        f"skill {skill_id!r} returned a non-dict result; "
+                        "V1 contract requires `dict[str, Any]`"
+                    ),
+                    detail={"actual_type": type(result).__name__},
+                ),
+            )
+
+        return SkillInvokeResult(ok=True, result=result)
+
+    def _not_found(self, skill_id: str, version: str) -> SkillInvokeResult:
+        # Differentiate "skill_id has no entries" from
+        # "skill_id exists but the requested version is missing" by
+        # walking the registry once.
+        any_version_for_id = any(
+            e.skill_id == skill_id for e in self._registry.list_all()
+        )
+        if any_version_for_id:
+            return SkillInvokeResult(
+                ok=False,
+                error=SkillErrorEnvelope(
+                    error_code=SKILL_VERSION_NOT_FOUND,
+                    message=(
+                        f"skill {skill_id!r} version {version!r} is not "
+                        "registered"
+                    ),
+                    detail={"skill_id": skill_id, "version": version},
+                ),
+            )
+        return SkillInvokeResult(
+            ok=False,
+            error=SkillErrorEnvelope(
+                error_code=SKILL_NOT_FOUND,
+                message=f"no skill registered for id={skill_id!r}",
+                detail={"skill_id": skill_id, "version": version},
+            ),
+        )
+
+
+__all__ = [
+    "InProcessDispatcher",
+    "KERNEL_DISPATCH_FAILED",
+    "SKILL_NOT_FOUND",
+    "SKILL_VERSION_NOT_FOUND",
+]

plm_skill_kernel/registry.py

@@ -0,0 +1,80 @@
+"""Boot-time skill discovery + registration.
+
+Importing :func:`load_starter_skills` triggers the import of each
+starter-skill module. Each module's top-level ``@skill(...)``
+decorator runs as a side-effect of import, so by the time
+:func:`load_starter_skills` returns the SDK registry contains every
+starter skill.
+
+This module is the V1 wiring point — production ``server.py`` calls
+:func:`load_starter_skills` at startup. Tests that need a clean
+registry call ``get_registry().clear()`` first.
+
+Wave 3 Conv A (per Decision #60) added ``documents.parse`` +
+``agents.suggest`` to the fan-out — bringing the starter set to 5
+skills (3 Wave 2 + 2 Wave 3).
+
+Wave 5 Conv C (FTR-603 / Decision #122 + #124) adds the 5 active V1
+``knowledge.*`` primitives — bringing the boot-loaded set to 10
+skills (3 Wave 2 + 2 Wave 3 + 5 Wave 5). The 2 deferred primitives
+(``explain`` / ``context_pack``) stay YAML ``draft`` capabilities
+only and do NOT register a kernel skill in V1; their dispatch is
+short-circuited by the engine-core envelope returning
+``KS_PRIMITIVE_DEFERRED_V1_1``.
+"""
+from __future__ import annotations
+
+import logging
+from typing import List, Tuple
+
+from .sdk._registry import RegisteredSkill, get_registry
+
+
+logger = logging.getLogger(__name__)
+
+
+def load_starter_skills() -> List[RegisteredSkill]:
+    """Import the 5 starter skills + return the resulting list.
+
+    The imports themselves run the decorator side-effects; this
+    function returns the registry's view post-load so callers can
+    log or assert on the exact skills available.
+
+    Idempotent — re-importing a module is a no-op (Python caches),
+    and the SDK registry tolerates same-callable re-registration.
+    """
+    # Local imports — module-load side effect is the registration. The
+    # imports MUST be inside the function so test fixtures that clear
+    # the registry can re-trigger registration by re-calling.
+    # NOTE: `noqa: F401` because the bound names are unused; the
+    # imports' side effect (decorator registration) is the point.
+    from .skills.cleansing import dedupe as _dedupe  # noqa: F401
+    from .skills.cleansing import normalise as _normalise  # noqa: F401
+    from .skills.bpmn import generate as _generate  # noqa: F401
+    from .skills.documents import parse as _parse  # noqa: F401
+    from .skills.agents import suggest as _suggest  # noqa: F401
+    # Wave 5 Conv C — FTR-603 Knowledge Services V1 active primitives.
+    from .skills.knowledge import search as _ks_search  # noqa: F401
+    from .skills.knowledge import get_record as _ks_get_record  # noqa: F401
+    from .skills.knowledge import retrieve as _ks_retrieve  # noqa: F401
+    from .skills.knowledge import resolve as _ks_resolve  # noqa: F401
+    from .skills.knowledge import validate as _ks_validate  # noqa: F401
+
+    entries = get_registry().list_all()
+    logger.info(
+        "skill_kernel boot_loaded count=%s ids=%s",
+        len(entries),
+        ",".join(sorted(f"{e.skill_id}@{e.version}" for e in entries)),
+    )
+    return entries
+
+
+def list_registered_skill_ids() -> List[Tuple[str, str]]:
+    """Return ``(skill_id, version)`` pairs for every registered entry.
+
+    Used by the federation manifest builder + introspection endpoints.
+    """
+    return [(e.skill_id, e.version) for e in get_registry().list_all()]
+
+
+__all__ = ["list_registered_skill_ids", "load_starter_skills"]

plm_skill_kernel/sdk/__init__.py

@@ -0,0 +1,29 @@
+"""Public Skill SDK surface (Wave 2 Conv A / Decision #59).
+
+Skill authors import from here:
+
+    from plm_skill_kernel import skill, SkillContext
+    # or, equivalently:
+    from plm_skill_kernel.sdk import skill, SkillContext
+
+The decorator + context + wire types are the V1-stable authoring
+surface; internal helpers (the registry implementation, validation
+helpers) live under ``plm_skill_kernel.sdk._registry`` and are NOT
+re-exported.
+"""
+from .context import SkillContext
+from .decorator import SkillDecoratorError, skill
+from .types import (
+    SkillErrorEnvelope,
+    SkillInvokeRequest,
+    SkillInvokeResult,
+)
+
+__all__ = [
+    "SkillContext",
+    "SkillDecoratorError",
+    "SkillErrorEnvelope",
+    "SkillInvokeRequest",
+    "SkillInvokeResult",
+    "skill",
+]

plm_skill_kernel/sdk/_registry.py

@@ -0,0 +1,111 @@
+"""Internal in-process decorator registry.
+
+The :func:`plm_skill_kernel.sdk.skill` decorator stamps each
+``async def`` it wraps into this module-level registry at import
+time. The Kernel dispatcher then resolves ``(skill_id, version)``
+back to the callable at dispatch time.
+
+Hot-reload (V1.1) replaces a single entry atomically; V1 callers that
+re-import a skill module will get a duplicate-registration error so
+test suites can detect accidental re-registration.
+
+Decision #25 / #41 / #52 / #53 V1 in-memory + Protocol pattern:
+the registry is a module-level dict + an ``RLock``. Wave 4+ may swap
+the backing store for a process-shared cache without changing the
+public surface (which is just ``register`` + ``resolve`` + ``list_all``).
+"""
+from __future__ import annotations
+
+import threading
+from dataclasses import dataclass
+from typing import Awaitable, Callable, Dict, List, Optional, Tuple
+
+from .context import SkillContext
+
+
+# Type alias for a registered skill body — every skill is
+# ``async def fn(payload: dict, ctx: SkillContext) -> dict``.
+SkillCallable = Callable[
+    [Dict, SkillContext], Awaitable[Dict]
+]
+
+
+@dataclass(frozen=True)
+class RegisteredSkill:
+    """One entry in the decorator registry.
+
+    The ``min_autonomy`` + ``streaming`` + ``hitl_required`` fields
+    are advisory metadata the SDK can pass through to the federation
+    manifest builder (CR.9) at boot. They are NOT enforced at dispatch
+    time — Core's selector + gating already ran upstream.
+    """
+
+    skill_id: str
+    version: str
+    fn: SkillCallable
+    description: Optional[str]
+    min_autonomy: str  # "L1" / "L2" / "L3"
+    streaming: bool
+    hitl_required: bool
+
+
+class _Registry:
+    """Thread-safe registry of decorated skills.
+
+    Keyed by ``(skill_id, version)``. Adding a duplicate raises a
+    :class:`RuntimeError` so test fixtures catch double-registration
+    rather than silently shadowing.
+    """
+
+    def __init__(self) -> None:
+        self._lock = threading.RLock()
+        self._entries: Dict[Tuple[str, str], RegisteredSkill] = {}
+
+    def register(self, entry: RegisteredSkill) -> None:
+        key = (entry.skill_id, entry.version)
+        with self._lock:
+            existing = self._entries.get(key)
+            if existing is not None and existing.fn is not entry.fn:
+                raise RuntimeError(
+                    f"skill {entry.skill_id!r} version {entry.version!r} "
+                    "is already registered with a different callable; "
+                    "duplicate registration is forbidden in V1"
+                )
+            self._entries[key] = entry
+
+    def resolve(
+        self, skill_id: str, version: str
+    ) -> Optional[RegisteredSkill]:
+        with self._lock:
+            return self._entries.get((skill_id, version))
+
+    def list_all(self) -> List[RegisteredSkill]:
+        with self._lock:
+            return list(self._entries.values())
+
+    def clear(self) -> None:
+        """Test-only — unregister everything. Production callers MUST NOT."""
+        with self._lock:
+            self._entries.clear()
+
+
+# Module-level singleton. Imported by the decorator + the dispatcher.
+_REGISTRY = _Registry()
+
+
+def get_registry() -> _Registry:
+    """Return the module-level registry singleton.
+
+    Tests that need isolation can call ``get_registry().clear()`` in a
+    fixture's setup; production callers never construct a fresh registry
+    (skills register at import time into the singleton).
+    """
+    return _REGISTRY
+
+
+__all__ = [
+    "RegisteredSkill",
+    "SkillCallable",
+    "_Registry",
+    "get_registry",
+]

plm_skill_kernel/sdk/context.py

@@ -0,0 +1,66 @@
+"""V1 :class:`SkillContext` — per-call ambient context handed to skills.
+
+Decision #59 (Conv N / Q-N4 = Option α decorator) — the SDK takes the
+shape ``async def skill(payload, ctx) -> dict`` so every skill function
+receives a typed context object alongside the validated payload.
+
+The context carries the bits a skill genuinely needs in V1:
+
+* ``tenant_id`` — for tenant-scoped reads / writes (RLS still
+  applies at the DB layer if the skill performs persistence).
+* ``run_id`` — links Kernel-side telemetry back to the originating
+  Core run (CR.1b RunTaskTracker surface).
+* ``trace_id`` — W3C ``traceparent`` propagation; emitted alongside
+  any telemetry the skill itself produces (V1.1 — V1 skills do NOT
+  emit telemetry directly; the Kernel's dispatcher records the
+  Skill-level invocation envelope).
+* ``autonomy_level`` — copied from ``SkillInvokeRequest.autonomy_hint``;
+  advisory, NOT authoritative.
+* ``idempotency_key`` — propagated from CR.10's caller; skills MAY
+  use it to dedupe side-effects.
+
+Skills MUST treat the context as immutable — the Pydantic model is
+``frozen=True``.
+"""
+from __future__ import annotations
+
+from typing import Optional
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class SkillContext(BaseModel):
+    """Per-call context object handed to every ``@skill``-decorated function.
+
+    Construct via :meth:`SkillContext.from_request` from the inbound
+    HTTP request + parsed body — server.py owns the construction so
+    skills never see the raw HTTP layer.
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    skill_id: str = Field(min_length=1)
+    skill_version: str = Field(min_length=1)
+    tenant_id: str = Field(default="anonymous", min_length=1)
+    run_id: Optional[str] = None
+    trace_id: Optional[str] = None
+    autonomy_level: Optional[str] = Field(
+        default=None,
+        description=(
+            "Advisory autonomy level (L1/L2/L3). Skills MAY consult "
+            "this for behaviour gating but MUST NOT treat it as "
+            "authoritative — Core already gated."
+        ),
+    )
+    idempotency_key: Optional[str] = None
+    core_caller: Optional[str] = Field(
+        default=None,
+        description=(
+            "X-Core-Caller header value (UUID). Identifies the Core "
+            "instance that issued the dispatch. None when the skill "
+            "is invoked directly (dev / test paths)."
+        ),
+    )
+
+
+__all__ = ["SkillContext"]

plm_skill_kernel/sdk/decorator.py

@@ -0,0 +1,147 @@
+"""``@skill`` decorator — Decision #59 (Conv N / Q-N4 = Option α).
+
+Skill authoring shape:
+
+    from plm_skill_kernel import skill, SkillContext
+
+    @skill(id="cleansing.normalise", version="1.0.0", min_autonomy="L2")
+    async def normalise(payload: dict, ctx: SkillContext) -> dict:
+        ...
+
+The decorator validates the function's shape (must be ``async def`` +
+2 positional params) and registers it into the module-level registry
+at import time. ``@skill`` does NOT mutate the function — calling the
+decorated callable still works as a plain async function (so unit
+tests can call it without going through the Kernel).
+
+Validation:
+
+* ``id`` — non-empty dotted string (``a.b`` / ``a.b.c``).
+* ``version`` — non-empty string; opaque to the registry (the
+  registry sorts by lifecycle precedence, not semver).
+* ``min_autonomy`` — must be ``"L1"`` / ``"L2"`` / ``"L3"``.
+
+The decorator raises :class:`SkillDecoratorError` (a ``ValueError``
+subclass) on any validation failure, fail-fast at import time.
+"""
+from __future__ import annotations
+
+import inspect
+import re
+from typing import Awaitable, Callable, Dict, Optional
+
+from ._registry import RegisteredSkill, SkillCallable, get_registry
+from .context import SkillContext
+
+
+_VALID_AUTONOMY = frozenset({"L1", "L2", "L3"})
+_SKILL_ID_PATTERN = re.compile(r"^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)+$")
+
+
+class SkillDecoratorError(ValueError):
+    """Raised when ``@skill(...)`` arguments or the wrapped function
+    fail validation. Surfaces at module import time.
+    """
+
+
+def _validate_skill_id(skill_id: str) -> None:
+    if not isinstance(skill_id, str) or not skill_id:
+        raise SkillDecoratorError("@skill: id must be a non-empty string")
+    if not _SKILL_ID_PATTERN.match(skill_id):
+        raise SkillDecoratorError(
+            f"@skill: id must be dotted lowercase identifiers "
+            f"(e.g. 'cleansing.normalise'); got {skill_id!r}"
+        )
+
+
+def _validate_version(version: str) -> None:
+    if not isinstance(version, str) or not version.strip():
+        raise SkillDecoratorError("@skill: version must be a non-empty string")
+
+
+def _validate_autonomy(level: str) -> None:
+    if level not in _VALID_AUTONOMY:
+        raise SkillDecoratorError(
+            f"@skill: min_autonomy must be one of L1/L2/L3; got {level!r}"
+        )
+
+
+def _validate_callable(fn: Callable) -> None:
+    if not inspect.iscoroutinefunction(fn):
+        raise SkillDecoratorError(
+            f"@skill: {fn.__qualname__} must be `async def` "
+            "(V1 dispatch is fully async)"
+        )
+    sig = inspect.signature(fn)
+    pos_params = [
+        p
+        for p in sig.parameters.values()
+        if p.kind
+        in (
+            inspect.Parameter.POSITIONAL_ONLY,
+            inspect.Parameter.POSITIONAL_OR_KEYWORD,
+        )
+    ]
+    if len(pos_params) != 2:
+        raise SkillDecoratorError(
+            f"@skill: {fn.__qualname__} must accept exactly 2 positional "
+            "params (payload: dict, ctx: SkillContext); "
+            f"got {len(pos_params)}"
+        )
+
+
+def skill(
+    *,
+    id: str,
+    version: str,
+    description: Optional[str] = None,
+    min_autonomy: str = "L1",
+    streaming: bool = False,
+    hitl_required: bool = False,
+) -> Callable[[SkillCallable], SkillCallable]:
+    """Register an ``async def`` as a Skill.
+
+    Returns the original callable unchanged — the decorator's only
+    side-effect is registry insertion, so unit tests can ``await fn(...)``
+    without going through the Kernel.
+
+    Args:
+        id: dotted skill identifier (``cleansing.normalise``).
+        version: opaque version string (``1.0.0``).
+        description: optional human-readable summary; surfaced on
+            ``GET /v1/skills`` introspection + the federation manifest.
+        min_autonomy: ``"L1"`` / ``"L2"`` / ``"L3"`` — advisory metadata.
+            Default ``"L1"``.
+        streaming: True for skills that emit progress chunks (V1.1
+            wire-protocol — V1 ignores the bit beyond manifest reporting).
+        hitl_required: True for skills whose work needs an explicit
+            HITL approval before completion. Surfaced on the manifest
+            so callers can pre-warn UI; the actual HITL ticket
+            lifecycle is owned by CR.13's HitlGate, not the Kernel.
+
+    Raises:
+        SkillDecoratorError: any validation failure (bad id, bad version,
+            wrong function shape, duplicate registration).
+    """
+    _validate_skill_id(id)
+    _validate_version(version)
+    _validate_autonomy(min_autonomy)
+
+    def _wrap(fn: SkillCallable) -> SkillCallable:
+        _validate_callable(fn)
+        entry = RegisteredSkill(
+            skill_id=id,
+            version=version,
+            fn=fn,
+            description=description,
+            min_autonomy=min_autonomy,
+            streaming=streaming,
+            hitl_required=hitl_required,
+        )
+        get_registry().register(entry)
+        return fn
+
+    return _wrap
+
+
+__all__ = ["SkillDecoratorError", "skill"]