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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plm-skill-kernel
-Version: 1.2.0
+Version: 1.3.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
@@ -13,6 +13,7 @@ Requires-Dist: uvicorn>=0.27
 Requires-Dist: httpx>=0.27.0
 Requires-Dist: plm-engine-core
 Requires-Dist: plm-knowledge
+Requires-Dist: plm-connector-sdk<2,>=1.1
 Provides-Extra: test
 Requires-Dist: pytest; extra == "test"
 Requires-Dist: pytest-asyncio; extra == "test"

{plm_skill_kernel-1.2.0 → plm_skill_kernel-1.3.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.2.0"
+__version__ = "1.3.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-1.3.0}/plm_skill_kernel/mocks/__init__.py

@@ -50,4 +50,25 @@ def require_mocks(what: str = "this mock") -> None:
         )
 
 
-__all__ = ["MOCKS_ENV", "MocksDisabled", "mocks_enabled", "require_mocks"]
+# ── governed contract package versions this mocks layer targets (AC4) ──────
+# The MVP mocks stand in for three governed, separately-versioned packages. This
+# dict is the single authoritative record of the exact versions the mocks were
+# written against; ``tests/contracts/test_mvp_mocks_boundary.py`` asserts each
+# against what is actually installed. A governed-package bump therefore surfaces
+# as a failing pin that a human re-syncs on purpose (updating MOCKS.md), never a
+# silent absorption. Per-mock *shape* pins (KS_CONTRACT_VERSION,
+# CONNECTOR_SDK_VERSION, SELECTION_REQUIRED_KEYS) live in their own modules.
+GOVERNED_CONTRACT_VERSIONS = {
+    "plm-shared": "1.2.1",         # CR.10/CR.12 wire shapes the SDK + dispatcher consume
+    "plm-connector-sdk": "1.3.1",  # ConnectorReadResult — AC2 reaches a connector through it
+    "plm-engine-core": "1.6.0",    # runtime.llm_service — the AC3 stub stands in for it
+}
+
+
+__all__ = [
+    "GOVERNED_CONTRACT_VERSIONS",
+    "MOCKS_ENV",
+    "MocksDisabled",
+    "mocks_enabled",
+    "require_mocks",
+]

plm_skill_kernel-1.3.0/plm_skill_kernel/mocks/connectors.py

@@ -0,0 +1,182 @@
+"""3DEXPERIENCE connector reached behind its real ``ConnectorReadResult`` (FTR-2234 / E3, AC2).
+
+# MOCK(MVP-DEMO): revert / re-sync under FTR-2234.
+#
+# AC2 is explicit: *reuse the existing connector mock, build no new one.* So this
+# module holds **no fixture data and no fake connector**. It wraps the portfolio's
+# already-shipped, fixture-backed ``Dassault3dexperienceMockConnector``
+# (``plm_mcp_connectors``) and exposes its reads through the connector SDK's real,
+# frozen ``ConnectorReadResult`` contract (``plm_connector_sdk`` v1.3.1). The kernel
+# reaches a connector *only* over this seam.
+#
+# Layering (mirrors reality, so the swap is a drop-in):
+#
+#     kernel (E4/E5, later)
+#         └── ConnectorReadPort.read(method, params)      ← reversible seam (this module)
+#                 └── ConnectorReadResult                 ← connector SDK contract (real)
+#                         └── Dassault3dexperienceMockConnector  ← existing fixture mock
+#                                 └── in-tree fixture rows (ENG-0001..0003)
+#
+# When a real connector is wired, the reader is handed engine-core's live
+# ``ConnectorRuntime`` instead of the fixture connector; it still returns the same
+# ``ConnectorReadResult``, so the kernel and every task are untouched.
+#
+# Honesty, two ways:
+#   * the seam stays **async**. Unlike the E1 knowledge seam (pure in-memory, so
+#     AC1 could drive it synchronously), a real connector performs network I/O and
+#     must be reached through an async call path — so this reader never pretends a
+#     connector read is synchronous, even though the *fixture* behind it is.
+#   * the wrapped connector's identity is literally ``dassault_3dexperience_mock``;
+#     ``PRODUCTION_BACKED`` is ``False`` and stays that way.
+#
+# Everything here is quarantined behind ``PLM_MVP_MOCKS`` (see
+# :func:`plm_skill_kernel.mocks.require_mocks`). The fixture host
+# (``plm_mcp_connectors``) is imported **lazily**, inside the constructor, so this
+# module stays importable — for the frozen-contract pin below — in an environment
+# that has the connector SDK but not the demo fixture package.
+"""
+from __future__ import annotations
+
+from typing import Any, List, Mapping, Optional, Protocol, runtime_checkable
+
+# The connector SDK is a governed contract package (like plm-shared), pinned as a
+# kernel dependency, so its frozen result type is imported at module top. The
+# *fixture host* is not a kernel dependency and is imported lazily below.
+from plm_connector_sdk.context import ConnectorContext
+from plm_connector_sdk.types import ConnectorReadRequest, ConnectorReadResult
+
+from . import require_mocks
+
+# ── pinned connector SDK identity ──────────────────────────────────────────
+# Mirror of plm-connector-sdk's package version. Pinned as a literal (the SDK
+# does not export ``__version__``) so the freeze test asserts the exact contract
+# generation this mock was written against; a bump must be re-synced on purpose.
+CONNECTOR_SDK_VERSION = "1.3.1"
+
+# The fixture connector this mock reuses (built under plm-mcp-connectors, NOT here).
+FIXTURE_CONNECTOR_MODULE = "plm_mcp_connectors.dassault_3dexperience_mock"
+
+# The read methods the fixture connector serves (§ FTR-2234 AC2). Asking for
+# anything else is a programming error, not a connector "not found".
+SUPPORTED_METHODS = frozenset({"get_eng_item", "search_eng_items", "get_bom"})
+
+DEFAULT_TENANT = "mvp-demo"
+
+
+class UnsupportedConnectorMethod(RuntimeError):
+    """Raised when the reader is asked for a method the fixture connector lacks."""
+
+
+@runtime_checkable
+class ConnectorReadPort(Protocol):
+    """The reversible connector seam: any object that answers a named read with a
+    :class:`~plm_connector_sdk.types.ConnectorReadResult`.
+
+    The demo satisfies it with :class:`FixtureConnectorReader` (wrapping the
+    fixture mock); a real deployment satisfies it with an engine-core connector
+    runtime. The kernel depends only on this surface, never on which side backs it.
+    """
+
+    async def read(
+        self, method: str, params: Mapping[str, Any], *, tenant_id: str = ...
+    ) -> ConnectorReadResult:
+        ...
+
+
+class FixtureConnectorReader:
+    """Reads the existing 3DEXPERIENCE **fixture** connector behind ``ConnectorReadResult`` (AC2).
+
+    Builds no connector and no fixture data of its own: it constructs the
+    portfolio's :class:`Dassault3dexperienceMockConnector` and forwards each read
+    to it, wrapping the call in the SDK's real ``ConnectorReadRequest`` /
+    ``ConnectorContext`` and returning the connector's real ``ConnectorReadResult``.
+
+    Gated: constructing without ``PLM_MVP_MOCKS`` raises
+    :class:`~plm_skill_kernel.mocks.MocksDisabled`.
+    """
+
+    # Honesty flags — parity with the KS mock's descriptor (AC1). A fixture
+    # connector is never a production claim.
+    PRODUCTION_BACKED = False
+    TEST_ONLY = True
+
+    def __init__(self, *, tenant_id: str = DEFAULT_TENANT) -> None:
+        require_mocks("FixtureConnectorReader")
+        # Lazy import: keeps this module importable (for the frozen-contract pin)
+        # without the demo fixture package present.
+        import importlib
+
+        fixture = importlib.import_module(FIXTURE_CONNECTOR_MODULE)
+        self._connector = fixture.Dassault3dexperienceMockConnector()
+        self.connector_id: str = fixture.CONNECTOR_ID
+        self.connector_version: str = fixture.CONNECTOR_VERSION
+        self._tenant_id = tenant_id
+
+    async def read(
+        self,
+        method: str,
+        params: Mapping[str, Any],
+        *,
+        tenant_id: Optional[str] = None,
+    ) -> ConnectorReadResult:
+        """Forward a named read to the fixture connector, returning its ``ConnectorReadResult``.
+
+        ``method`` must be one of :data:`SUPPORTED_METHODS`; an unknown method is a
+        caller bug (:class:`UnsupportedConnectorMethod`), distinct from a connector
+        "not found" — which the connector itself reports as ``ok=False`` with an
+        error envelope.
+        """
+        if method not in SUPPORTED_METHODS:
+            raise UnsupportedConnectorMethod(
+                f"{method!r} is not served by {self.connector_id}; "
+                f"supported: {sorted(SUPPORTED_METHODS)}"
+            )
+        request = ConnectorReadRequest(
+            params=dict(params), version=self.connector_version
+        )
+        context = ConnectorContext(
+            connector_id=self.connector_id,
+            connector_version=self.connector_version,
+            method_name=method,
+            tenant_id=tenant_id or self._tenant_id,
+        )
+        bound = getattr(self._connector, method)
+        return await bound(request, context)
+
+    # ── convenience wrappers over read() (the three fixture reads) ──────────
+    async def get_eng_item(
+        self, physical_id: str, *, tenant_id: Optional[str] = None
+    ) -> ConnectorReadResult:
+        return await self.read(
+            "get_eng_item", {"physical_id": physical_id}, tenant_id=tenant_id
+        )
+
+    async def search_eng_items(
+        self,
+        query: str,
+        *,
+        max_results: Optional[int] = None,
+        tenant_id: Optional[str] = None,
+    ) -> ConnectorReadResult:
+        params: dict[str, Any] = {"query": query}
+        if max_results is not None:
+            params["max_results"] = max_results
+        return await self.read("search_eng_items", params, tenant_id=tenant_id)
+
+    async def get_bom(
+        self, physical_id: str, *, tenant_id: Optional[str] = None
+    ) -> ConnectorReadResult:
+        return await self.read(
+            "get_bom", {"physical_id": physical_id}, tenant_id=tenant_id
+        )
+
+
+__all__: List[str] = [
+    "CONNECTOR_SDK_VERSION",
+    "DEFAULT_TENANT",
+    "FIXTURE_CONNECTOR_MODULE",
+    "SUPPORTED_METHODS",
+    "ConnectorReadPort",
+    "FixtureConnectorReader",
+    "UnsupportedConnectorMethod",
+]

plm_skill_kernel-1.3.0/plm_skill_kernel/mocks/engine_core_stub.py

@@ -0,0 +1,136 @@
+"""Core LLM / DB paths mocked, kept OFF the critical path (FTR-2234 / E3, AC3).
+
+# MOCK(MVP-DEMO): revert / re-sync under FTR-2234.
+#
+# The MVP critical path — parse_request -> select_skill -> SkillExecutor.run ->
+# ordered tasks -> KnowledgeProvider.fetch — is deterministic and touches
+# neither an LLM nor a database. Determinism is the property that makes the demo
+# reproducible, not a lack of ambition: the request is routed by keyword rules
+# (executor/selector.py), not by a model.
+#
+# There are exactly two ways the *kernel* could reach engine-core at runtime,
+# and both are behind the federation boundary import-linter already fences off
+# (Decision #51, CR.9 §6 — see pyproject.toml [tool.importlinter]):
+#
+#   * the LLM path — the legacy ``SkillOrchestrator`` (plan-mode selection) does
+#     ``from plm_engine_core.runtime.llm_service import llm_service`` lazily,
+#     inside ``select_skill`` (skill_orchestrator.py:115). That single line is
+#     the *only* allowlisted exception to "the kernel must not import
+#     plm_engine_core". The MVP demo path never calls it.
+#   * the DB path — engine-core owns persistence. The kernel has NO database
+#     seam of its own: nothing under ``plm_skill_kernel`` imports a DB driver or
+#     ``plm_engine_core.*`` persistence. So there is nothing kernel-side to
+#     "mock" for the DB — the import-linter forbidden contract already keeps that
+#     path off every kernel module, critical or not.
+#
+# This module supplies the LLM half: a deterministic, in-memory stand-in for the
+# ``llm_service`` singleton, so that IF the legacy plan-mode selection path is
+# exercised in a demo it runs against canned, schema-valid output instead of
+# LiteLLM + a live model — importing neither ``plm_engine_core`` nor ``litellm``.
+#
+# What it is NOT: it is never imported by any production path and never wired
+# into the executor. A caller opts in explicitly, under ``PLM_MVP_MOCKS``. The
+# freeze pin (tests/contracts/test_mvp_engine_core_stub_freeze.py) asserts, by
+# source scan, that this file imports no engine-core / LiteLLM symbol — so the
+# "no heavy import" promise cannot rot silently.
+"""
+from __future__ import annotations
+
+import json
+from typing import Any, Dict, List, Optional
+
+from . import require_mocks
+
+# ── the reply contract the legacy orchestrator expects ─────────────────────
+# SkillOrchestrator.generate_reply returns a *string* that json.loads-es into an
+# object with exactly these keys (its ``_SELECTION_SCHEMA["required"]``). Pinned
+# here as a literal; the behavioural test cross-checks it against the real
+# orchestrator schema so the two cannot drift apart unnoticed.
+SELECTION_REQUIRED_KEYS = ("profile_id", "reasoning", "confidence", "considered_profiles")
+
+# The orchestrator's own documented fallback profile id (used when no candidate
+# keyword matches). Kept as a literal so this module needs no registry import.
+DEFAULT_PROFILE_ID = "generique-plm"
+
+
+class StubLLMService:
+    """Deterministic, in-memory stand-in for ``plm_engine_core.runtime.llm_service``.
+
+    Satisfies the single coroutine the legacy :class:`SkillOrchestrator` calls —
+    ``generate_reply(system_prompt, user_prompt, temperature)`` — and returns a
+    canned, schema-valid selection JSON *string* (never touching a model). Same
+    ``user_prompt`` in → same reply out; there is no clock, no network, no
+    provider, and no ``plm_engine_core`` / ``litellm`` import anywhere in reach.
+
+    Gated: constructing without ``PLM_MVP_MOCKS`` raises
+    :class:`~plm_skill_kernel.mocks.MocksDisabled`.
+
+    A caller may pass ``candidates`` (the valid profile ids for the run); the stub
+    picks, deterministically, the first candidate whose id appears as a substring
+    of the user prompt, else :attr:`DEFAULT_PROFILE_ID`. That keeps the fake
+    "selection" explainable without pretending to be intelligent.
+    """
+
+    # Honesty flags — parity with the KS mock (AC1) and connector reader (AC2).
+    PRODUCTION_BACKED = False
+    TEST_ONLY = True
+
+    def __init__(
+        self,
+        *,
+        profile_id: str = DEFAULT_PROFILE_ID,
+        confidence: float = 0.9,
+        candidates: Optional[List[str]] = None,
+    ) -> None:
+        require_mocks("StubLLMService")
+        self._profile_id = profile_id
+        self._confidence = float(confidence)
+        # Candidate ids to route among; defaults to just the fallback profile.
+        self._candidates: List[str] = list(candidates or [profile_id])
+        # Every call recorded verbatim, so a test can assert the seam was used
+        # and with what prompts — without a real model to introspect.
+        self.calls: List[Dict[str, Any]] = []
+
+    async def generate_reply(
+        self, *, system_prompt: str, user_prompt: str, temperature: float = 0.1
+    ) -> str:
+        """Return canned, schema-valid selection JSON (a *string*, like the real service).
+
+        Keyword-only args mirror the orchestrator's call site
+        (``generate_reply(system_prompt=..., user_prompt=..., temperature=0.1)``).
+        """
+        self.calls.append(
+            {
+                "system_prompt": system_prompt,
+                "user_prompt": user_prompt,
+                "temperature": temperature,
+            }
+        )
+        chosen = self._select(user_prompt)
+        payload = {
+            "profile_id": chosen,
+            "reasoning": "Deterministic MVP stub selection (no live model was called).",
+            "confidence": self._confidence,
+            # top-3 considered, selected id first — matches the schema's intent
+            "considered_profiles": self._considered(chosen),
+        }
+        return json.dumps(payload, ensure_ascii=False)
+
+    # ── deterministic, explainable "selection" ─────────────────────────────
+    def _select(self, user_prompt: str) -> str:
+        hay = (user_prompt or "").lower()
+        for candidate in self._candidates:
+            if candidate.lower() in hay:
+                return candidate
+        return self._profile_id
+
+    def _considered(self, chosen: str) -> List[str]:
+        ordered = [chosen] + [c for c in self._candidates if c != chosen]
+        return ordered[:3]
+
+
+__all__: List[str] = [
+    "DEFAULT_PROFILE_ID",
+    "SELECTION_REQUIRED_KEYS",
+    "StubLLMService",
+]