plm-skill-kernel 1.3.0__tar.gz → 1.4.0__tar.gz

{plm_skill_kernel-1.3.0 → plm_skill_kernel-1.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plm-skill-kernel
-Version: 1.3.0
+Version: 1.4.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.3.0 → plm_skill_kernel-1.4.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.3.0"
+__version__ = "1.4.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.3.0 → plm_skill_kernel-1.4.0}/plm_skill_kernel/executor/__init__.py

@@ -23,6 +23,11 @@ path; the executor is driven by the demo entrypoint + tests.
 """
 from __future__ import annotations
 
+# NOTE: ``load_demo_skills`` is intentionally NOT re-exported here. Importing it
+# would fire the demo tasks' ``@skill`` decorators as a side effect of importing
+# the executor package, leaking ``demo.foundation.*`` into the SDK registry /
+# federation introspection. Demo registration is a deliberate opt-in — import
+# ``plm_skill_kernel.executor._demo_skills.load_demo_skills`` and call it.
 from .binding import BindingNotFound, resolve_binding
 from .executor import SkillExecutor, TaskFailure
 from .knowledge import EchoKnowledgeProvider, KnowledgeProvider, NullKnowledgeProvider

plm_skill_kernel-1.4.0/plm_skill_kernel/executor/_catalog_fixture.py

@@ -0,0 +1,102 @@
+"""Demo catalog fixture (FTR-2232 / E1; the certified package is FTR-2235 / E4).
+
+# 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`. E1 shipped a
+# structurally-valid stub here; **E4** replaces it with the concrete, certified
+# demo skill package: an ordered >= 2-task composite that carries all manifest
+# attributes and runs end-to-end over the E2 pump foundation seam (decision C1).
+
+The composite ``demo.knowledge_lookup`` decomposes into two ordered tasks:
+
+1. ``demo.foundation.retrieve`` — the executor injects a broad set of
+   foundation snippets (via the task's static ``knowledge_query`` seed); the
+   task narrows them to the runtime query.
+2. ``demo.foundation.synthesize`` — turns the retrieved snippets into a
+   grounded, cited answer.
+
+GOVERNANCE FIREWALL (FTR-2235 AC): ``certified`` / ``controlled`` and the
+attached :data:`~plm_skill_kernel.executor._demo_manifest.DEMO_MANIFEST` are
+**demo-fixture fakes** — advisory, unenforced, and confined to this layer.
+They must never reach the FTR-2034 register or the published profile.
+"""
+from __future__ import annotations
+
+from typing import Dict, Tuple
+
+from ._demo_ids import DEMO_TASK_VERSION, RETRIEVE_SKILL_ID, SYNTHESIZE_SKILL_ID
+from ._demo_manifest import DEMO_MANIFEST
+from .plan import SkillPlan, TaskStep
+
+DEMO_SKILL_ID = "demo.knowledge_lookup"
+DEMO_SKILL_VERSION = "0.1.0"
+
+# MOCK(MVP-DEMO): static seed the executor hands the knowledge provider for
+# task 1 — a broad "load the foundation context" query. It is intentionally
+# NOT the runtime query: the executor loads a broad set, then the certified
+# skill's task 1 narrows it to what the caller actually asked. Broad on
+# purpose so re-ranking in the task is meaningful.
+_FOUNDATION_SEED_QUERY = (
+    "hydraulic pump foundation reference material standard torque pressure shaft"
+)
+
+_DEMO_PLAN = SkillPlan(
+    skill_id=DEMO_SKILL_ID,
+    version=DEMO_SKILL_VERSION,
+    description=(
+        "Certified demo composite: retrieve grounding from the foundation "
+        "corpus, then synthesize a cited answer — an ordered two-task skill "
+        "the agent delegates to instead of answering from itself."
+    ),
+    # MOCK(MVP-DEMO): fixture governance flags — advisory, not real
+    # certification (real status lives in the FTR-2034 register).
+    certified=True,
+    controlled=True,
+    # MOCK(MVP-DEMO): all manifest-profile/1.0 attributes, faked (AC1).
+    manifest=DEMO_MANIFEST,
+    tasks=(
+        TaskStep(
+            task_id="retrieve",
+            skill_id=RETRIEVE_SKILL_ID,
+            version=DEMO_TASK_VERSION,
+            description=(
+                "Ordered task 1 — narrow the injected foundation snippets to "
+                "the runtime query."
+            ),
+            input_keys=("query",),
+            # Triggers foundation injection under payload['foundation'].
+            knowledge_query=_FOUNDATION_SEED_QUERY,
+        ),
+        TaskStep(
+            task_id="synthesize",
+            skill_id=SYNTHESIZE_SKILL_ID,
+            version=DEMO_TASK_VERSION,
+            description=(
+                "Ordered task 2 — synthesize a grounded, cited answer from "
+                "the retrieved snippets."
+            ),
+            input_keys=("retrieved", "query"),
+            output_key="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.4.0/plm_skill_kernel/executor/_demo_ids.py

@@ -0,0 +1,18 @@
+"""Shared ids for the demo composite's tasks (FTR-2235 / E4).
+
+Deliberately **dependency-free**. The catalog fixture names the demo tasks by
+these id strings *without* importing the skill module — because importing
+:mod:`plm_skill_kernel.executor._demo_skills` fires its ``@skill`` decorators
+and registers the demo callables into the SDK registry. Keeping the ids here
+means merely importing the ``executor`` package (or the catalog fixture) never
+has that side effect; registration is a deliberate act via
+:func:`plm_skill_kernel.executor._demo_skills.load_demo_skills`, so faked demo
+skills never boot-load or appear in federation introspection unasked.
+"""
+from __future__ import annotations
+
+RETRIEVE_SKILL_ID = "demo.foundation.retrieve"
+SYNTHESIZE_SKILL_ID = "demo.foundation.synthesize"
+DEMO_TASK_VERSION = "1.0.0"
+
+__all__ = ["DEMO_TASK_VERSION", "RETRIEVE_SKILL_ID", "SYNTHESIZE_SKILL_ID"]

plm_skill_kernel-1.4.0/plm_skill_kernel/executor/_demo_manifest.py

@@ -0,0 +1,146 @@
+"""Demo manifest attributes for the certified composite (FTR-2235 / E4).
+
+# MOCK(MVP-DEMO): every value in this module is a **demo-fixture fake**. This
+# is the "carries all manifest attributes" surface of the demo skill package
+# (AC1) — it mirrors the *field names* of the governed
+# ``manifest-profile/1.0`` (read-only source:
+# ``plm_skill_packages/manifest_profile/data/v1_profile.yaml``) so the demo
+# fixture is recognisably a full manifest, while every value is a stand-in.
+#
+# GOVERNANCE FIREWALL (FTR-2235 AC): the faked ``certified`` / ``maturity``
+# values below live ONLY in this demo fixture layer. They MUST NOT be written
+# to the FTR-2034 decision register or the published ``manifest-profile/1.0``.
+# The value string ``certified_industrial_capability`` is deliberately
+# confined to this module (a firewall guard test asserts it appears nowhere
+# else under ``plm_skill_kernel``).
+
+The model is ``frozen`` + ``extra="forbid"`` to mirror the discipline of the
+governed profile, but it is a demo descriptor — it is never validated against,
+or promoted into, the real profile. It carries no behaviour; the executor
+never reads it (AC4: no conformance gating).
+"""
+from __future__ import annotations
+
+from typing import Tuple
+
+from pydantic import BaseModel, ConfigDict, Field
+
+# The faked maturity/lifecycle/autonomy values. Named constants so the intent
+# is legible and the firewall guard has one obvious place to look.
+# MOCK(MVP-DEMO): a real certified maturity requires human sign-off in the
+# FTR-2034 register; this string is a fixture stand-in and nothing else.
+_MOCK_MATURITY_CERTIFIED = "certified_industrial_capability"
+_MOCK_LIFECYCLE_RELEASED = "released"
+_MOCK_AUTONOMY_SUPERVISED = "supervised"
+
+
+class DemoManifestAttributes(BaseModel):
+    """All ``manifest-profile/1.0`` attributes, mirrored as demo metadata.
+
+    One field per governed profile ``machine_key`` (28 total). Presence — not
+    enforcement — is the point: AC1 asks that the demo skill "carries all
+    manifest attributes", and AC4 explicitly says the executor does not gate
+    on a ``VALID`` conformance verdict, so these values are never validated.
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    # ── identity ──────────────────────────────────────────────────────────
+    skill_id: str
+    name: str
+    mission: str
+    semantic_version: str
+
+    # ── lifecycle / maturity / autonomy (the "certified" story) ───────────
+    lifecycle_state: str
+    maturity_level: str
+    autonomy_ceiling: str
+
+    # ── scope / ownership / audience ──────────────────────────────────────
+    tenant_scope: str
+    audience: str
+    owner: str
+
+    # ── governance references (certified-tier fields) ─────────────────────
+    minimum_trace_level: str
+    hitl_policy_reference: str
+    certification_reference: str
+    evaluation_reference: str
+    pinned_baseline_reference: str
+
+    # ── contract / schema surface ─────────────────────────────────────────
+    contract_hash: str
+    input_schema_ref: str
+    output_schema_ref: str
+
+    # ── behavioural contract ──────────────────────────────────────────────
+    preconditions: Tuple[str, ...] = Field(default=())
+    postconditions: Tuple[str, ...] = Field(default=())
+    failure_modes: Tuple[str, ...] = Field(default=())
+    evidence_expectations: Tuple[str, ...] = Field(default=())
+
+    # ── compatibility / dependencies ──────────────────────────────────────
+    kernel_api_compatibility: str
+    knowledge_api_compatibility: str
+    model_configuration: str
+    connector_deps: Tuple[str, ...] = Field(default=())
+    inference_deps: Tuple[str, ...] = Field(default=())
+    knowledge_deps: Tuple[str, ...] = Field(default=())
+
+
+# MOCK(MVP-DEMO): the concrete faked manifest for the demo composite skill.
+# Certified-tier so the demo can *show* an agent delegating to a certified,
+# controlled skill — every value here is a stand-in, none is ratified.
+DEMO_MANIFEST = DemoManifestAttributes(
+    skill_id="demo.knowledge_lookup",
+    name="Foundation Knowledge Lookup (DEMO)",
+    mission=(
+        "Delegate a knowledge request to an ordered, certified composite "
+        "skill that retrieves and then synthesizes grounded foundation "
+        "reference material — instead of the agent answering from itself."
+    ),
+    semantic_version="0.1.0",
+    lifecycle_state=_MOCK_LIFECYCLE_RELEASED,
+    maturity_level=_MOCK_MATURITY_CERTIFIED,
+    autonomy_ceiling=_MOCK_AUTONOMY_SUPERVISED,
+    tenant_scope="shared",
+    audience="internal-demo",
+    owner="mvp-demo-owner (MOCK)",
+    minimum_trace_level="standard",
+    hitl_policy_reference="mock://hitl-policy/none",
+    certification_reference="mock://certification/demo-knowledge-lookup@0.1.0",
+    evaluation_reference="mock://evaluation/demo-knowledge-lookup@0.1.0",
+    pinned_baseline_reference="mock://baseline/foundation-seed@rev-1",
+    contract_hash="sha256:0000000000000000000000000000000000000000000000000000000000000000",
+    input_schema_ref="mock://schema/demo.knowledge_lookup/input@0.1.0",
+    output_schema_ref="mock://schema/demo.knowledge_lookup/output@0.1.0",
+    preconditions=(
+        "A foundation knowledge provider is wired on the executor "
+        "(demo: SeedFoundationKnowledgeProvider behind PLM_MVP_MOCKS).",
+    ),
+    postconditions=(
+        "Returns a grounded answer citing foundation snippet ids, or an "
+        "explicitly empty grounding when nothing matched the query.",
+    ),
+    failure_modes=(
+        "No foundation snippet matches the query -> empty grounding, the "
+        "composite still succeeds (the demo does not fail closed on no-hit).",
+    ),
+    evidence_expectations=(
+        "Per-task execution trace with per-task knowledge-injection flags.",
+    ),
+    kernel_api_compatibility="v1",
+    knowledge_api_compatibility="v1",
+    model_configuration="none (deterministic; no inference in the demo composite)",
+    connector_deps=(),
+    inference_deps=(),
+    knowledge_deps=("foundation-seed (MOCK)",),
+)
+
+
+def manifest_field_names() -> Tuple[str, ...]:
+    """Return the mirrored profile attribute names (for AC1 assertions)."""
+    return tuple(DemoManifestAttributes.model_fields.keys())
+
+
+__all__ = ["DEMO_MANIFEST", "DemoManifestAttributes", "manifest_field_names"]

plm_skill_kernel-1.4.0/plm_skill_kernel/executor/_demo_skills.py

@@ -0,0 +1,195 @@
+"""The certified composite's ordered tasks (FTR-2235 / E4, decision C1).
+
+# MOCK(MVP-DEMO): two demo-scoped ``@skill`` tasks that make the composite
+# ``demo.knowledge_lookup`` do real, data-dependent work over the E2 pump
+# foundation seam — one coherent dataset, no ``extra="forbid"`` collision
+# (both tasks read the injected ``payload['foundation']`` freely, unlike the
+# strict ``knowledge.*`` request models).
+
+The composite's ordered steps:
+
+* **task 1 — ``demo.foundation.retrieve``**: the executor has already loaded a
+  broad set of foundation snippets into ``payload['foundation']`` (via the
+  task's static ``knowledge_query`` seed). This task *narrows* that set to the
+  caller's runtime ``query`` by token overlap and keeps the top matches.
+* **task 2 — ``demo.foundation.synthesize``**: turns the retrieved snippets
+  into a short, grounded, pump-themed answer with explicit citations
+  (snippet id + title + non-authoritative source label).
+
+Both are authored with the ordinary ``@skill`` decorator (Decision #59 shape)
+so they register into the SDK registry and run through the ordinary
+dispatcher — nothing about the executor changes. They are **deliberately kept
+out of** :func:`plm_skill_kernel.registry.load_starter_skills` (the production
+/ federation-manifest surface); the demo wires them via
+:func:`load_demo_skills` instead, so faked demo skills never boot-load into a
+real kernel.
+"""
+from __future__ import annotations
+
+import re
+from typing import Any, Dict, List
+
+from plm_skill_kernel import SkillContext, skill
+from plm_skill_kernel.sdk._registry import RegisteredSkill, get_registry
+
+from ._demo_ids import DEMO_TASK_VERSION, RETRIEVE_SKILL_ID, SYNTHESIZE_SKILL_ID
+
+# How many narrowed snippets task 1 forwards to task 2.
+_KEEP_TOP = 3
+_TOKEN_RE = re.compile(r"[a-z0-9]+")
+
+
+def _tokens(text: str) -> List[str]:
+    return _TOKEN_RE.findall((text or "").lower())
+
+
+def _snippet_blob(snippet: Dict[str, Any]) -> str:
+    """Searchable text for a foundation snippet (id/type/title/snippet)."""
+    parts = [
+        str(snippet.get("id", "")),
+        str(snippet.get("type", "")),
+        str(snippet.get("title", "")),
+        str(snippet.get("snippet", "")),
+    ]
+    return " ".join(parts).lower()
+
+
+@skill(
+    id=RETRIEVE_SKILL_ID,
+    version=DEMO_TASK_VERSION,
+    description=(
+        "Demo composite task 1: narrow the injected foundation snippets to "
+        "the runtime query by token overlap; keep the top matches."
+    ),
+    min_autonomy="L1",
+)
+async def demo_foundation_retrieve(
+    payload: Dict[str, Any], ctx: SkillContext
+) -> Dict[str, Any]:
+    """Rank ``payload['foundation']`` against ``payload['query']``.
+
+    Reads the foundation snippets the executor injected under the reserved
+    ``foundation`` key and re-ranks them for *this* request's query. Returns
+    the top matches under ``retrieved`` (shallow-merged into the running
+    state for task 2). Never fails closed on a no-hit — an empty ``retrieved``
+    is a valid, grounded-in-nothing outcome (AC4: the demo does not gate).
+    """
+    query = str(payload.get("query", ""))
+    foundation = payload.get("foundation") or []
+    q = set(_tokens(query))
+
+    scored: List[tuple] = []
+    for snippet in foundation:
+        if not isinstance(snippet, dict):
+            continue
+        blob = _snippet_blob(snippet)
+        overlap = sum(1 for tok in q if tok in blob)
+        if overlap > 0:
+            scored.append((overlap, snippet))
+
+    # Deterministic order: higher overlap first, then snippet id ascending.
+    scored.sort(key=lambda s: (-s[0], str(s[1].get("id", ""))))
+    retrieved = [snippet for _, snippet in scored[:_KEEP_TOP]]
+
+    return {
+        "retrieved": retrieved,
+        "match_count": len(scored),
+        "considered": len(foundation),
+        "query_used": query,
+    }
+
+
+@skill(
+    id=SYNTHESIZE_SKILL_ID,
+    version=DEMO_TASK_VERSION,
+    description=(
+        "Demo composite task 2: synthesize a short grounded answer from the "
+        "retrieved foundation snippets, with explicit citations."
+    ),
+    min_autonomy="L1",
+)
+async def demo_foundation_synthesize(
+    payload: Dict[str, Any], ctx: SkillContext
+) -> Dict[str, Any]:
+    """Compose a grounded, pump-themed answer from ``payload['retrieved']``.
+
+    The answer text names the top foundation reference(s) and every claim is
+    tied to a citation (snippet id + title + the non-authoritative ``source``
+    label). If nothing was retrieved, the answer says so plainly and
+    ``grounded`` is ``False`` — a legible, honest empty result.
+    """
+    query = str(payload.get("query", ""))
+    retrieved = payload.get("retrieved") or []
+
+    citations = [
+        {
+            "id": snippet.get("id"),
+            "title": snippet.get("title"),
+            "source": snippet.get("source"),
+        }
+        for snippet in retrieved
+        if isinstance(snippet, dict)
+    ]
+
+    if citations:
+        lead = retrieved[0]
+        titles = ", ".join(
+            f"{c['title']} [{c['id']}]" for c in citations if c.get("title")
+        )
+        answer = (
+            f"For '{query}': the most relevant foundation reference is "
+            f"{lead.get('title')} [{lead.get('id')}]. "
+            f"Grounded on {len(citations)} foundation snippet(s): {titles}."
+        )
+        grounded = True
+    else:
+        answer = (
+            f"For '{query}': no foundation reference matched the query, so no "
+            "grounded answer could be produced from the demo corpus."
+        )
+        grounded = False
+
+    return {
+        "answer": answer,
+        "citations": citations,
+        "grounded": grounded,
+    }
+
+
+# Capture the exact registry entries the decorators built at import time (with
+# their full metadata + the live callables). ``load_demo_skills`` re-registers
+# these same callables, so demo registration survives a ``registry.clear()``
+# in a test fixture — Python's module cache would not re-fire the decorators.
+_DEMO_ENTRIES = tuple(
+    entry
+    for entry in (
+        get_registry().resolve(RETRIEVE_SKILL_ID, DEMO_TASK_VERSION),
+        get_registry().resolve(SYNTHESIZE_SKILL_ID, DEMO_TASK_VERSION),
+    )
+    if entry is not None
+)
+
+
+def load_demo_skills() -> List[RegisteredSkill]:
+    """(Re)register the demo composite's tasks into the SDK registry.
+
+    Idempotent: the registry tolerates same-callable re-registration, so this
+    is safe to call after a ``registry.clear()`` (e.g. the ``fresh_registry``
+    test fixture) to restore the demo tasks. Kept separate from
+    :func:`plm_skill_kernel.registry.load_starter_skills` on purpose — demo
+    skills must never boot-load into a real kernel.
+    """
+    registry = get_registry()
+    for entry in _DEMO_ENTRIES:
+        registry.register(entry)
+    return list(_DEMO_ENTRIES)
+
+
+__all__ = [
+    "DEMO_TASK_VERSION",
+    "RETRIEVE_SKILL_ID",
+    "SYNTHESIZE_SKILL_ID",
+    "demo_foundation_retrieve",
+    "demo_foundation_synthesize",
+    "load_demo_skills",
+]

{plm_skill_kernel-1.3.0 → plm_skill_kernel-1.4.0}/plm_skill_kernel/executor/plan.py

@@ -23,6 +23,8 @@ from typing import Any, Dict, Optional, Tuple
 
 from pydantic import BaseModel, ConfigDict, Field
 
+from ._demo_manifest import DemoManifestAttributes
+
 
 class TaskStep(BaseModel):
     """One ordered task inside a :class:`SkillPlan`.
@@ -102,6 +104,12 @@ class SkillPlan(BaseModel):
     # register + published profile, never here. Present-but-unenforced.
     certified: bool = False
     controlled: bool = False
+    # MOCK(MVP-DEMO): optional mirror of the ``manifest-profile/1.0``
+    # attributes, present so the demo skill "carries all manifest attributes"
+    # (FTR-2235 AC1). Every value is a fixture fake; the executor never reads
+    # it (AC4: no conformance gating). Backward-compatible default ``None`` so
+    # E1 plans and tests that omit it are unaffected.
+    manifest: Optional[DemoManifestAttributes] = None
 
     def task_ids(self) -> Tuple[str, ...]:
         return tuple(t.task_id for t in self.tasks)

{plm_skill_kernel-1.3.0 → plm_skill_kernel-1.4.0}/plm_skill_kernel.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plm-skill-kernel
-Version: 1.3.0
+Version: 1.4.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.3.0 → plm_skill_kernel-1.4.0}/plm_skill_kernel.egg-info/SOURCES.txt

@@ -23,6 +23,9 @@ plm_skill_kernel/conformance/models.py
 plm_skill_kernel/conformance/protocol.py
 plm_skill_kernel/executor/__init__.py
 plm_skill_kernel/executor/_catalog_fixture.py
+plm_skill_kernel/executor/_demo_ids.py
+plm_skill_kernel/executor/_demo_manifest.py
+plm_skill_kernel/executor/_demo_skills.py
 plm_skill_kernel/executor/binding.py
 plm_skill_kernel/executor/executor.py
 plm_skill_kernel/executor/knowledge.py
@@ -65,6 +68,7 @@ plm_skill_kernel/skills_legacy/skill_orchestrator.py
 tests/test_agents_suggest_asgi.py
 tests/test_agents_suggest_unit.py
 tests/test_connector_read_mock.py
+tests/test_demo_skill_package.py
 tests/test_dispatcher.py
 tests/test_documents_parse_asgi.py
 tests/test_documents_parse_unit.py

{plm_skill_kernel-1.3.0 → plm_skill_kernel-1.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "plm-skill-kernel"
-version = "1.3.0"
+version = "1.4.0"
 description = "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."
 readme = "README.md"
 requires-python = ">=3.12"

plm_skill_kernel-1.4.0/tests/test_demo_skill_package.py

@@ -0,0 +1,261 @@
+"""Tests for the certified demo skill package (FTR-2235 / E4).
+
+Covers the ratified acceptance criteria:
+
+* **AC1** — the demo skill carries *all* manifest attributes: the fixture
+  manifest mirrors every ``manifest-profile/1.0`` machine key (28 total) and
+  is attached to the composite plan alongside the certified/controlled flags.
+* **AC2** — the skill is marked certified/controlled via the inline-marked
+  fixture manifest AND registered in the catalog fixture.
+* **AC3** — request → executor → ordered tasks → foundation knowledge →
+  grounded, cited result wires end-to-end, and the agent *delegates* to the
+  certified composite rather than answering itself.
+* **AC4** — with the profile non-effective, the executor does NOT hard-gate on
+  a ``VALID`` conformance verdict: a plan with a full fixture manifest and one
+  with no manifest at all run identically.
+
+Plus a **governance-firewall guard**: the faked ``certified`` maturity string
+lives only in the demo fixture module and nowhere else under the package.
+
+The demo tasks are quarantined out of ``load_starter_skills``; every test that
+runs the composite loads them deliberately via ``load_demo_skills`` into a
+cleared registry, exactly as the demo entrypoint does.
+"""
+from __future__ import annotations
+
+import os
+
+import pytest
+
+from plm_skill_kernel import SkillContext
+from plm_skill_kernel.dispatcher import InProcessDispatcher
+from plm_skill_kernel.executor import SkillExecutor, parse_request, resolve_binding, select_skill
+from plm_skill_kernel.executor._catalog_fixture import (
+    DEMO_SKILL_ID,
+    DEMO_SKILL_VERSION,
+    build_demo_catalog,
+)
+from plm_skill_kernel.executor._demo_manifest import DEMO_MANIFEST, DemoManifestAttributes
+from plm_skill_kernel.executor._demo_skills import (
+    demo_foundation_retrieve,
+    demo_foundation_synthesize,
+    load_demo_skills,
+)
+from plm_skill_kernel.mocks.foundation_seed import SeedFoundationKnowledgeProvider
+
+# The 28 governed ``manifest-profile/1.0`` machine keys the fixture mirrors.
+# Hardcoded (not derived from the model) so a drift in the model is caught
+# against the profile's actual field inventory, not against itself.
+_EXPECTED_MANIFEST_KEYS = frozenset(
+    {
+        "skill_id",
+        "name",
+        "mission",
+        "semantic_version",
+        "lifecycle_state",
+        "maturity_level",
+        "autonomy_ceiling",
+        "tenant_scope",
+        "audience",
+        "owner",
+        "minimum_trace_level",
+        "hitl_policy_reference",
+        "certification_reference",
+        "evaluation_reference",
+        "pinned_baseline_reference",
+        "contract_hash",
+        "input_schema_ref",
+        "output_schema_ref",
+        "preconditions",
+        "postconditions",
+        "failure_modes",
+        "evidence_expectations",
+        "kernel_api_compatibility",
+        "knowledge_api_compatibility",
+        "model_configuration",
+        "connector_deps",
+        "inference_deps",
+        "knowledge_deps",
+    }
+)
+
+# The faked maturity string that must be confined to the demo fixture module.
+_FIREWALLED_MATURITY = "certified_industrial_capability"
+
+
+@pytest.fixture(autouse=True)
+def _enable_mocks(monkeypatch):
+    """Enable the mocks quarantine so the seed provider can be constructed."""
+    monkeypatch.setenv("PLM_MVP_MOCKS", "1")
+
+
+def _ctx(plan) -> SkillContext:
+    return SkillContext(
+        skill_id=plan.skill_id,
+        skill_version=plan.version,
+        tenant_id="tenant-demo",
+        autonomy_level="L1",
+    )
+
+
+# ── AC1: carries all manifest attributes ──────────────────────────────────
+def test_manifest_mirrors_all_profile_keys():
+    assert set(DemoManifestAttributes.model_fields) == _EXPECTED_MANIFEST_KEYS
+    assert len(DemoManifestAttributes.model_fields) == 28
+
+
+def test_manifest_certified_tier_values_populated():
+    # The "certified" story: the fixture claims certified maturity and fills
+    # the certified-tier governance references (all fakes, but present).
+    assert DEMO_MANIFEST.maturity_level == _FIREWALLED_MATURITY
+    assert DEMO_MANIFEST.lifecycle_state == "released"
+    assert DEMO_MANIFEST.autonomy_ceiling == "supervised"
+    assert DEMO_MANIFEST.certification_reference.startswith("mock://certification/")
+    assert DEMO_MANIFEST.evaluation_reference.startswith("mock://evaluation/")
+    assert DEMO_MANIFEST.pinned_baseline_reference.startswith("mock://baseline/")
+    assert DEMO_MANIFEST.skill_id == DEMO_SKILL_ID
+    assert DEMO_MANIFEST.semantic_version == DEMO_SKILL_VERSION
+
+
+# ── AC2: marked certified/controlled + registered in the catalog ──────────
+def test_catalog_plan_is_certified_controlled_with_manifest():
+    plan = resolve_binding(DEMO_SKILL_ID, catalog=build_demo_catalog())
+    assert plan.certified is True
+    assert plan.controlled is True
+    assert plan.manifest is DEMO_MANIFEST
+    # An ordered set of >= 2 tasks (AC1's "ordered set of tasks").
+    assert plan.task_ids() == ("retrieve", "synthesize")
+    assert len(plan.tasks) >= 2
+
+
+# ── AC3: end-to-end request → tasks → knowledge → grounded result ─────────
+async def test_end_to_end_agent_delegates_to_certified_composite(fresh_registry):
+    load_demo_skills()  # deliberate opt-in (not boot-loaded)
+
+    request_text = "look up the foundation reference for the aluminium pump housing"
+
+    # The agent delegates: it routes to the certified composite skill id...
+    skill_id = select_skill(request_text)
+    assert skill_id == DEMO_SKILL_ID
+
+    # ...resolves it to an ordered task plan it did not itself author...
+    plan = resolve_binding(skill_id, catalog=build_demo_catalog())
+    assert plan.certified is True  # delegating to a *certified* skill
+
+    result = await SkillExecutor(
+        dispatcher=InProcessDispatcher(),
+        knowledge=SeedFoundationKnowledgeProvider(top_k=8),
+    ).run(plan, parse_request(request_text), context=_ctx(plan))
+
+    assert result.ok is True
+    state = result.result
+
+    # The ordered tasks ran, and foundation knowledge was injected into task 1
+    # (retrieve) but not task 2 (synthesize) — proving per-task threading.
+    trace = state["_trace"]
+    assert [e["task_id"] for e in trace] == ["retrieve", "synthesize"]
+    retrieve_entry = next(e for e in trace if e["task_id"] == "retrieve")
+    synth_entry = next(e for e in trace if e["task_id"] == "synthesize")
+    assert retrieve_entry["knowledge_injected"] is True
+    assert synth_entry["knowledge_injected"] is False
+
+    # The result is grounded and cites foundation snippet ids (FND-*).
+    answer = state["result"]
+    assert answer["grounded"] is True
+    assert answer["citations"], "expected at least one citation"
+    cited_ids = [c["id"] for c in answer["citations"]]
+    assert all(cid.startswith("FND-") for cid in cited_ids)
+    # The aluminium housing record is the natural top hit for this query.
+    assert "FND-101" in cited_ids or "FND-201" in cited_ids
+    assert all(c["source"] == "foundation-seed (MOCK)" for c in answer["citations"])
+
+
+# ── AC4: executor does NOT gate on a VALID conformance verdict ────────────
+async def test_executor_does_not_gate_on_conformance(fresh_registry):
+    """A fully-manifested certified plan and a bare plan run identically.
+
+    The executor never consults ``certified`` / ``controlled`` / ``manifest``
+    (the profile is non-effective — AC4). Stripping all of it must not change
+    the outcome; if the executor gated on a VALID verdict, the bare plan would
+    diverge.
+    """
+    load_demo_skills()
+    request_text = "aluminium pump housing foundation reference"
+    catalog = build_demo_catalog()
+    certified_plan = resolve_binding(DEMO_SKILL_ID, catalog=catalog)
+
+    # Same ordered tasks, but no certification/manifest metadata at all.
+    bare_plan = certified_plan.model_copy(
+        update={"certified": False, "controlled": False, "manifest": None}
+    )
+
+    executor = SkillExecutor(
+        dispatcher=InProcessDispatcher(),
+        knowledge=SeedFoundationKnowledgeProvider(top_k=8),
+    )
+    certified_result = await executor.run(
+        certified_plan, parse_request(request_text), context=_ctx(certified_plan)
+    )
+    bare_result = await executor.run(
+        bare_plan, parse_request(request_text), context=_ctx(bare_plan)
+    )
+
+    assert certified_result.ok is True
+    assert bare_result.ok is True
+    # Identical grounded answer regardless of the (ignored) governance metadata.
+    assert certified_result.result["result"] == bare_result.result["result"]
+
+
+# ── governance firewall: the faked maturity string is confined ────────────
+def test_firewall_certified_string_confined_to_fixture_module():
+    import plm_skill_kernel
+
+    package_root = os.path.dirname(plm_skill_kernel.__file__)
+    offenders = []
+    for dirpath, _dirs, files in os.walk(package_root):
+        for fname in files:
+            if not fname.endswith(".py"):
+                continue
+            path = os.path.join(dirpath, fname)
+            with open(path, encoding="utf-8") as fh:
+                if _FIREWALLED_MATURITY in fh.read():
+                    offenders.append(os.path.relpath(path, package_root))
+
+    assert offenders == [os.path.join("executor", "_demo_manifest.py")], (
+        "the faked certified maturity string must live ONLY in the demo "
+        f"fixture module; found in: {offenders}"
+    )
+
+
+# ── optional unit tests for the two composite tasks ───────────────────────
+async def test_retrieve_narrows_injected_foundation():
+    # Two snippets injected; only the aluminium one overlaps the query tokens.
+    foundation = [
+        {
+            "id": "FND-101",
+            "type": "material_spec",
+            "title": "Aluminium 6061-T6",
+            "snippet": "aluminium housing alloy",
+            "source": "foundation-seed (MOCK)",
+        },
+        {
+            "id": "FND-401",
+            "type": "unit_def",
+            "title": "Pressure units — bar and MPa",
+            "snippet": "pressure conversion",
+            "source": "foundation-seed (MOCK)",
+        },
+    ]
+    out = await demo_foundation_retrieve(
+        {"query": "aluminium housing", "foundation": foundation}, ctx=None
+    )
+    assert [s["id"] for s in out["retrieved"]] == ["FND-101"]
+    assert out["match_count"] == 1
+    assert out["considered"] == 2
+
+
+async def test_synthesize_empty_retrieval_is_honest():
+    out = await demo_foundation_synthesize({"query": "nothing", "retrieved": []}, ctx=None)
+    assert out["grounded"] is False
+    assert out["citations"] == []
+    assert "no foundation reference matched" in out["answer"]

{plm_skill_kernel-1.3.0 → plm_skill_kernel-1.4.0}/tests/test_executor.py

@@ -208,7 +208,7 @@ def test_resolve_binding_exact_version():
     plan = resolve_binding(DEMO_SKILL_ID, DEMO_SKILL_VERSION, catalog=catalog)
     assert plan.skill_id == DEMO_SKILL_ID
     assert len(plan.tasks) == 2  # ordered two-task demo skill
-    assert plan.task_ids() == ("search", "get_record")
+    assert plan.task_ids() == ("retrieve", "synthesize")
 
 
 def test_resolve_binding_none_version_single():

plm_skill_kernel-1.3.0/plm_skill_kernel/executor/_catalog_fixture.py

@@ -1,80 +0,0 @@
-"""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",
-]