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

plm_skill_kernel/skills_legacy/skill_orchestrator.py

@@ -0,0 +1,163 @@
+"""Skill Orchestrator — LLM-based selection of PLM expertise profiles for Plan mode.
+
+Uses a structured JSON LLM call to select the best expertise profile for a given
+user request, with reasoning and confidence score.
+"""
+from __future__ import annotations
+
+import json
+import logging
+from dataclasses import dataclass, field
+
+from plm_engine_core.runtime.llm_service import llm_service
+from plm_skill_kernel.skills_legacy.plm_skill_registry import PLMSkillRegistry
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class SkillSelectionResult:
+    profile_id: str
+    profile_label: str
+    domain: str
+    reasoning: str          # 1-2 sentence explanation
+    confidence: float       # 0.0 – 1.0
+    considered_profiles: list[str] = field(default_factory=list)  # top candidates evaluated
+
+
+class SkillOrchestrator:
+    """
+    Multi-criteria PLM skill selector.
+
+    Calls the LLM with a JSON schema prompt to select the best expertise profile
+    for a given user request. Falls back to the global PLM profile on error or
+    low confidence.
+    """
+
+    _SELECTION_SCHEMA = {
+        "type": "object",
+        "properties": {
+            "profile_id": {
+                "type": "string",
+                "description": "Exact ID of the selected profile from the list",
+            },
+            "reasoning": {
+                "type": "string",
+                "description": "Short explanation (1-2 sentences) of why this profile was selected",
+            },
+            "confidence": {
+                "type": "number",
+                "minimum": 0.0,
+                "maximum": 1.0,
+                "description": "Confidence score between 0 and 1",
+            },
+            "considered_profiles": {
+                "type": "array",
+                "items": {"type": "string"},
+                "description": "Top 3 profile IDs that were considered (including the selected one)",
+            },
+        },
+        "required": ["profile_id", "reasoning", "confidence", "considered_profiles"],
+    }
+
+    async def select_skill(
+        self,
+        user_request: str,
+        document_context: str = "",
+    ) -> SkillSelectionResult:
+        """
+        Select the most appropriate PLM skill profile for the given request.
+
+        Args:
+            user_request: The user's message/request text.
+            document_context: Optional document context excerpt.
+
+        Returns:
+            SkillSelectionResult with selected profile + reasoning.
+            Falls back to generique-plm on any error or confidence < 0.3.
+        """
+        fallback = PLMSkillRegistry.get_fallback()
+
+        try:
+            profiles_json = PLMSkillRegistry.get_descriptions_for_llm()
+            valid_ids = PLMSkillRegistry.get_ids()
+
+            context_section = ""
+            if document_context and document_context.strip():
+                context_section = (
+                    f"\n\nContexte documentaire (extrait):\n{document_context[:800]}"
+                )
+
+            user_prompt = (
+                f"Analyse la demande suivante et sélectionne le profil d'expertise PLM le plus adapté.\n\n"
+                f"Demande utilisateur: {user_request[:600]}"
+                f"{context_section}\n\n"
+                f"Profils disponibles:\n{profiles_json}\n\n"
+                f"Sélectionne le profil dont l'id, le domaine et les mots-clés correspondent le mieux à la demande.\n"
+                f"Si la demande est générale ou multi-domaine, utilise \"generique-plm\".\n\n"
+                f"IMPORTANT: Réponds UNIQUEMENT avec un JSON valide correspondant exactement au schéma suivant:\n"
+                f"{json.dumps(self._SELECTION_SCHEMA, ensure_ascii=False)}"
+            )
+
+            system_prompt = (
+                "Tu es un orchestrateur d'expertise PLM. "
+                "Tu analyses les demandes utilisateur et sélectionnes le profil d'expertise le plus adapté. "
+                "Tu réponds uniquement en JSON structuré, sans texte supplémentaire."
+            )
+
+            result_text = await llm_service.generate_reply(
+                system_prompt=system_prompt,
+                user_prompt=user_prompt,
+                temperature=0.1,
+            )
+
+            # Strip potential markdown code blocks
+            result_text = result_text.strip()
+            if result_text.startswith("```"):
+                lines = result_text.split("\n")
+                result_text = "\n".join(lines[1:-1]) if len(lines) > 2 else result_text
+                result_text = result_text.replace("```json", "").replace("```", "").strip()
+
+            parsed = json.loads(result_text)
+
+            profile_id = str(parsed.get("profile_id", "")).strip()
+            if profile_id not in valid_ids:
+                logger.warning(
+                    f"SkillOrchestrator returned unknown profile_id={profile_id!r}, falling back to generique-plm"
+                )
+                profile_id = fallback.id
+
+            confidence = float(parsed.get("confidence", 0.5))
+            if confidence < 0.3:
+                logger.info(
+                    f"SkillOrchestrator low confidence={confidence:.2f}, falling back to generique-plm"
+                )
+                profile_id = fallback.id
+
+            profile = PLMSkillRegistry.get(profile_id) or fallback
+            considered_raw = parsed.get("considered_profiles", [])
+            considered = [str(p) for p in considered_raw if str(p) in valid_ids][:3]
+
+            return SkillSelectionResult(
+                profile_id=profile.id,
+                profile_label=profile.label,
+                domain=profile.domain,
+                reasoning=str(parsed.get("reasoning", ""))[:300],
+                confidence=confidence,
+                considered_profiles=considered,
+            )
+
+        except Exception as e:
+            logger.warning(f"SkillOrchestrator selection failed: {e!r}, using fallback")
+            return SkillSelectionResult(
+                profile_id=fallback.id,
+                profile_label=fallback.label,
+                domain=fallback.domain,
+                reasoning="Sélection par défaut (erreur d'orchestration).",
+                confidence=0.5,
+                considered_profiles=[fallback.id],
+            )
+
+
+# Module-level singleton
+skill_orchestrator = SkillOrchestrator()

plm_skill_kernel-1.0.0.dist-info/METADATA

@@ -0,0 +1,135 @@
+Metadata-Version: 2.4
+Name: plm-skill-kernel
+Version: 1.0.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
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: plm-shared
+Requires-Dist: pydantic>=2.5.0
+Requires-Dist: fastapi>=0.110
+Requires-Dist: uvicorn>=0.27
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: plm-engine-core
+Requires-Dist: plm-knowledge
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: pytest-asyncio; extra == "test"
+Requires-Dist: httpx<1,>=0.27; extra == "test"
+
+# plm-skill-kernel
+
+Wave 2 Conv A (FTR-604). The Skill Kernel package — sibling of
+`plm-engine-core` — that hosts the decorator-based Skill SDK, the V1
+in-process dispatcher, and the Kernel HTTP server stub matching CR.10
+§7.bis verbatim.
+
+## Layout
+
+```
+02_App/plm-skill-kernel/
+├── pyproject.toml             # editable install + import-linter contracts
+├── plm_skill_kernel/
+│   ├── __init__.py            # re-exports `skill`, `SkillContext`, etc.
+│   ├── __main__.py            # `python -m plm_skill_kernel` → server
+│   ├── server.py              # FastAPI app at POST /v1/skills/{id}/invoke
+│   ├── dispatcher.py          # V1 in-process invoker
+│   ├── registry.py            # boot wiring — discovers + registers skills
+│   ├── sdk/
+│   │   ├── decorator.py       # `@skill(id=, version=)`
+│   │   ├── context.py         # SkillContext Pydantic
+│   │   ├── types.py           # SkillInvokeRequest / SkillInvokeResult
+│   │   └── _registry.py       # in-process decorator registry
+│   └── skills/                # 3 starter skills (Q-W2A-1 nested layout)
+│       ├── cleansing/
+│       │   ├── normalise.py   # cleansing.normalise / 1.0.0 / L2
+│       │   └── dedupe.py      # cleansing.dedupe / 1.0.0 / L2
+│       └── bpmn/
+│           └── generate.py    # bpmn.generate / 1.0.0 / L1 (thin proxy)
+└── tests/                     # unit + ASGI in-process integration
+```
+
+## Editable install
+
+```bash
+cd 02_App/backend
+.\venv\Scripts\Activate.ps1                  # Windows
+pip install -e ../plm-skill-kernel
+```
+
+Mirrors the plm-engine-core editable-install pattern.
+
+## Dev launch (Q-W2A-3)
+
+```bash
+python -m plm_skill_kernel               # uvicorn on port 8100
+plm-skill-kernel --port 8100             # equivalent CLI
+```
+
+The backend at port 8000 is unaffected. The V1.1 loopback round-trip
+(D-CONV-M-4 closure) sends HTTP from the Engine Core dispatcher to
+this Kernel server when `SKILL_KERNEL_LOOPBACK=on`.
+
+## V1 wire contract
+
+`POST /v1/skills/{id}/invoke` — frozen at CR.10 §7.bis.
+
+```
+Headers:
+  X-Core-Caller: <UUID>            (required when caller is Core)
+  Idempotency-Key: <uuid>          (optional, V1)
+  traceparent: <W3C>               (optional)
+
+Request body (SkillInvokeRequest):
+  payload:        Dict[str, Any]
+  version:        str  ("1.0.0", etc.)
+  autonomy_hint:  Optional[str]    ("L1" / "L2" / "L3")
+
+Response body (SkillInvokeResult):
+  ok:             bool
+  result:         Optional[Dict[str, Any]]
+  error:          Optional[SkillErrorEnvelope]
+  deferred_to:    Optional[str]
+  cancelled:      Optional[bool]
+```
+
+## Skill authoring (Decision #59 — decorator)
+
+```python
+from plm_skill_kernel import skill, SkillContext
+
+@skill(id="cleansing.normalise", version="1.0.0")
+async def normalise(payload: dict, ctx: SkillContext) -> dict:
+    return {"normalised": _normalise_records(payload["records"])}
+```
+
+The decorator auto-registers into the in-process registry at module
+import time + carries `version` through to the federated manifest
+builder (CR.9).
+
+## Import-linter contracts
+
+Two Forbidden contracts live in `pyproject.toml`:
+
+1. `plm_skill_kernel` MUST NOT import `plm_engine_core` — federation
+   contract preservation. The two communicate over HTTP, not Python.
+2. `plm_skill_kernel` MUST NOT import `plm_accelerators` (Workbench)
+   — mirror of the plm-engine-core constraint.
+
+Run:
+
+```bash
+lint-imports --config 02_App/plm-skill-kernel/pyproject.toml
+```
+
+## Tests
+
+```bash
+cd 02_App/plm-skill-kernel
+python -m pytest -q
+```
+
+The V1.1 HTTP round-trip integration test mounts the FastAPI app via
+httpx.AsyncClient(ASGITransport) — no subprocess, no real port
+(Q-W2A-4).

plm_skill_kernel-1.0.0.dist-info/RECORD

@@ -0,0 +1,38 @@
+plm_skill_kernel/__init__.py,sha256=R2fBlPKbx_OvvcPOblSObUSmU2-IlA3W-7_OB73JIos,1245
+plm_skill_kernel/__main__.py,sha256=WwG3kHkwheHiKpyYjyAjuCReKTauK3TnpPMuvKQ3FdY,424
+plm_skill_kernel/dispatcher.py,sha256=t2lfGWtkeSotmKph8rpX3FzeOJCgJc70hqNrK8gJR6I,5246
+plm_skill_kernel/registry.py,sha256=329aN2OGUncEL-YMX9wrp5-BdeZhEzELSCWCtKxtFWQ,3464
+plm_skill_kernel/server.py,sha256=QlotMcJfSzCD4aIJxittgvfA343cQUClW2cV7aRJJPg,6022
+plm_skill_kernel/sdk/__init__.py,sha256=Jmo9XVoSzdtkhxIbT4tuH2q3rsXG1hulOHCm4AWjpQ0,804
+plm_skill_kernel/sdk/_registry.py,sha256=5nEp00HUyexO1hZmT_hQppz2grJVJP7d8B2FeDfQyZg,3700
+plm_skill_kernel/sdk/context.py,sha256=l2Wk2mRZIatL_1oh2Qn1dON6-1wyobMgZyV7YzTWy-k,2538
+plm_skill_kernel/sdk/decorator.py,sha256=MvYdIi1YvN9Xv8x_iBxXT8UVefzlbKrzMdaMKVLLHyA,5162
+plm_skill_kernel/sdk/types.py,sha256=XnWo-DLPrPrUvseDwDQoPaJYqTPxCvyKffIcrvDN2cM,3032
+plm_skill_kernel/skills/__init__.py,sha256=iQvcy8h4MlhVLZUJVO8u8OZHaXHjTiX0hUgleCAtYBA,770
+plm_skill_kernel/skills/agents/__init__.py,sha256=z25y3B51ZoKnVEg-OKzx5l3xtTJ0Dfh42XTSgZI5cUg,532
+plm_skill_kernel/skills/agents/suggest.py,sha256=JtOBs5E-62DOIqw1PXMS1a3jHoVWPzQx_yJtpCYLpuE,7313
+plm_skill_kernel/skills/bpmn/__init__.py,sha256=UQjjIzPW4oV24nXgJQq_-8ziX1WGE9gYmXjzc-K02zQ,440
+plm_skill_kernel/skills/bpmn/generate.py,sha256=ySNCzjB1n4gMEHueasdQhfqGLMpKx0a6nQwO5LihDOQ,5522
+plm_skill_kernel/skills/cleansing/__init__.py,sha256=tapVpGsbNQDan7pf-SX1cBbc1j6h3-6xlAvt3EFttRQ,565
+plm_skill_kernel/skills/cleansing/dedupe.py,sha256=g6JKcultWnRGDAFr_2uBN00HYD7B6Z84Zpqhst93v70,5075
+plm_skill_kernel/skills/cleansing/normalise.py,sha256=tK-72K3M_VgQ4UG0OMS37jnHCJUGoKeh8ToQbZAeKYY,6068
+plm_skill_kernel/skills/documents/__init__.py,sha256=p7w9qsS6PhR4IuuvM3oYOAIyOxJjq3pWj33K5-kzEhc,464
+plm_skill_kernel/skills/documents/parse.py,sha256=xqjBtvePldFeEQJ1r2q3IgEjYnvOv_M32yygXi9QDqQ,7648
+plm_skill_kernel/skills/knowledge/__init__.py,sha256=Te_RvJvw0iIw-58_MH83d9RomQwQuFe0-1sOThxmsIw,1485
+plm_skill_kernel/skills/knowledge/_v1_corpus.py,sha256=snnX9n4x-MohhAWDAIN1GDzV9U2xXQcQoIqtSwMSc74,5436
+plm_skill_kernel/skills/knowledge/get_record.py,sha256=arCE32GJacd7hircrWR8DHDvJqBAs6OnmWBhRHen814,3165
+plm_skill_kernel/skills/knowledge/resolve.py,sha256=L-RGTaRL9kqL3k4c5zgtpi6RabplXIPCMMUh2PNJyi4,4643
+plm_skill_kernel/skills/knowledge/retrieve.py,sha256=MbYr_zJS-xxiMWeGTmpdk3F8Z7USdmTVZd_t9NYYBGE,4848
+plm_skill_kernel/skills/knowledge/search.py,sha256=9pwIqgwphHZy2J5vx6A205Dcp6JldbVjjZ6_nMPDCYc,5319
+plm_skill_kernel/skills/knowledge/validate.py,sha256=WKGqidejpOllcM7uF3JNJhj540MRuVEVVVzYyWSl57o,8101
+plm_skill_kernel/skills_legacy/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+plm_skill_kernel/skills_legacy/knowledge_pack_loader.py,sha256=OmnH4G0FBYatvRfmmNnKtuRHBaOtw4NQmsGmQT2cSo0,607
+plm_skill_kernel/skills_legacy/knowledge_search_engine.py,sha256=vlkCXv9pHsmd8l0NYHS042ziob-vW_JfpihIfElV_V4,991
+plm_skill_kernel/skills_legacy/plm_skill_registry.py,sha256=_E88Q4WeYvwGPUtx4R9T3gteTNijbCZVBhe_5a2Y-uo,37491
+plm_skill_kernel/skills_legacy/plm_tool_definitions.py,sha256=iYK4ENGPMILH4l5dxZG_b-J8gwP49tJGMtvmX4Revtc,1713
+plm_skill_kernel/skills_legacy/skill_orchestrator.py,sha256=IhZAg9w31GKiT71xmjmKvtNAGVik3QbErMZMJqu5FRM,6472
+plm_skill_kernel-1.0.0.dist-info/METADATA,sha256=GBSzfc7fXVYP3DdOwjTz0U2d5o-oJd1MSkLrNFVNrps,4894
+plm_skill_kernel-1.0.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+plm_skill_kernel-1.0.0.dist-info/entry_points.txt,sha256=1vXOuJFIwhhkEQkiRdhOi8IhTUEKMVt0MeMnplC2DHA,72
+plm_skill_kernel-1.0.0.dist-info/top_level.txt,sha256=nOy7tCl_qAoG0ppZHRHZQSLB8P6_FOdWbN_ylHfui8Q,17
+plm_skill_kernel-1.0.0.dist-info/RECORD,,

plm_skill_kernel-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

plm_skill_kernel-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+plm-skill-kernel = plm_skill_kernel.server:_cli_entry

plm_skill_kernel-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+plm_skill_kernel