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

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)

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]

Knowledge corpora

knowledge.search / get_record / retrieve serve the in-process seed (demo, foundation) plus every <corpus_id>.json under PLM_KERNEL_CORPORA_DIR, loaded once at boot. Shape: {"records": {"<record_id>": {title, body, source_uri, revision, payload}}}; source_uri and revision are required. A malformed file, or one reusing a seed corpus_id, fails the boot. Search matches the exact phrase first, then all query terms in any order (scored at half weight). knowledge.list_records pages a whole corpus without a query ({corpus_id, limit, offset, with_body}), for catalogue views.

Skill authoring (Decision #59 — decorator)

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:

lint-imports --config 02_App/plm-skill-kernel/pyproject.toml

Tests

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).