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

plm_skill_kernel/skills/knowledge/_v1_corpus.py

@@ -0,0 +1,153 @@
+"""V1 in-memory deterministic seed corpus for the knowledge.* skills.
+
+FTR-603 Wave 5 Conv C / Decision #122 — V1 thin-proxy harvest. The 5
+active primitives operate on a deterministic in-process seed corpus
+so the kernel container is self-contained at boot (no Azure / file-
+system dependency). V1.1 replaces this seed with a real backend bind
+through the lazy-import boundary documented on each skill module.
+
+The seed shape is the minimum that keeps the 5 primitives' V1
+contract demonstrable:
+
+* Two corpora — ``demo`` (3 BPMN-flavoured records) + ``foundation``
+  (2 entity records) so cross-corpus + cross-record cases are
+  exercisable from tests.
+* One entity catalog — keyed by ``(entity_kind, surface_form)`` for
+  ``resolve`` exact-match.
+* One rule set — ``v1_smoke`` for ``validate`` keyed by required
+  fields.
+
+Adding fixtures here is a deliberate, additive YAML-style edit; the
+runtime contract on the request / response Pydantic schemas is the
+frozen V1 contract — this seed is wallpaper.
+"""
+from __future__ import annotations
+
+from typing import Any, Dict, List, Tuple
+
+
+# ── Records (search / get_record / retrieve) ──────────────────────────
+
+
+CORPUS_RECORDS: Dict[str, Dict[str, Dict[str, Any]]] = {
+    "demo": {
+        "rec-001": {
+            "title": "Approval flow",
+            "body": "Route every change order through the design-review gate.",
+            "source_uri": "doc://demo/rec-001",
+            "revision": "rev-1",
+            "payload": {"tags": ["bpmn", "approval"]},
+        },
+        "rec-002": {
+            "title": "Manufacturing release",
+            "body": "Promote a part to released after BOM consolidation.",
+            "source_uri": "doc://demo/rec-002",
+            "revision": "rev-1",
+            "payload": {"tags": ["bpmn", "release"]},
+        },
+        "rec-003": {
+            "title": "ECO impact analysis",
+            "body": "Evaluate the impact of a change on dependent assemblies.",
+            "source_uri": "doc://demo/rec-003",
+            "revision": "rev-2",
+            "payload": {"tags": ["change", "impact"]},
+        },
+    },
+    "foundation": {
+        "ent-part-001": {
+            "title": "Part WASHER-M6",
+            "body": "Foundation entity for the WASHER-M6 standard hardware part.",
+            "source_uri": "foundation://parts/WASHER-M6",
+            "revision": "rev-1",
+            "payload": {"kind": "Part", "category": "hardware"},
+        },
+        "ent-part-002": {
+            "title": "Part BRACKET-A1",
+            "body": "Foundation entity for the BRACKET-A1 fabricated bracket.",
+            "source_uri": "foundation://parts/BRACKET-A1",
+            "revision": "rev-1",
+            "payload": {"kind": "Part", "category": "fabricated"},
+        },
+    },
+}
+"""Two-corpus seed: ``demo`` (3 records) + ``foundation`` (2 records)."""
+
+
+# ── Entity resolution catalog (resolve) ───────────────────────────────
+
+
+ENTITY_CATALOG: Dict[Tuple[str, str], Dict[str, Any]] = {
+    ("part", "washer-m6"): {
+        "canonical_id": "ent-part-001",
+        "label": "WASHER-M6",
+        "confidence": 0.95,
+    },
+    ("part", "bracket-a1"): {
+        "canonical_id": "ent-part-002",
+        "label": "BRACKET-A1",
+        "confidence": 0.92,
+    },
+    ("part", "bracket"): {
+        "canonical_id": "ent-part-002",
+        "label": "BRACKET-A1",
+        "confidence": 0.55,
+    },
+}
+"""V1 entity catalog keyed by ``(entity_kind, surface_form_lower)``."""
+
+
+# ── Rule sets (validate) ──────────────────────────────────────────────
+
+
+RULE_SETS: Dict[str, List[Dict[str, Any]]] = {
+    "v1_smoke": [
+        {
+            "rule_id": "v1.required.title",
+            "severity": "error",
+            "message": "Field 'title' is required.",
+            "kind": "required",
+            "field": "title",
+        },
+        {
+            "rule_id": "v1.required.body",
+            "severity": "warning",
+            "message": "Field 'body' is recommended.",
+            "kind": "required",
+            "field": "body",
+        },
+        {
+            "rule_id": "v1.evidence_refs.curation",
+            "severity": "error",
+            "message": (
+                "Each evidence_refs entry must be backed by a "
+                "connector_access_index row (curation index)."
+            ),
+            "kind": "curation",
+            "field": "evidence_refs",
+        },
+    ]
+}
+"""V1 ``v1_smoke`` rule set with 3 rules covering required-fields +
+the curation-index evidence-ref check (per readiness sweep §3.2)."""
+
+
+def known_corpus(corpus_id: str) -> bool:
+    return corpus_id in CORPUS_RECORDS
+
+
+def list_records(corpus_id: str) -> List[Tuple[str, Dict[str, Any]]]:
+    """Return ``[(record_id, record_payload), ...]`` for the corpus.
+
+    Empty list when the corpus is unknown — V1 contract is open-world
+    on corpus_id (no error; consumer treats empty as miss).
+    """
+    return list(CORPUS_RECORDS.get(corpus_id, {}).items())
+
+
+__all__ = [
+    "CORPUS_RECORDS",
+    "ENTITY_CATALOG",
+    "RULE_SETS",
+    "known_corpus",
+    "list_records",
+]

plm_skill_kernel/skills/knowledge/get_record.py

@@ -0,0 +1,102 @@
+"""``knowledge.get_record`` / 1.0.0 / L1 — fetch a record by id.
+
+FTR-603 Wave 5 Conv C / Decision #122. V1 thin-proxy harvest of the
+D-LOCKED-23 active V1 ``get_record`` primitive (PRD §8.11.3).
+
+V1 contract:
+
+    payload = {
+        "corpus_id":  str,   # required
+        "record_id":  str,   # required
+    }
+
+Output:
+
+    {
+        "payload": {"record": <KnowledgeRecord as dict | None>},
+        "source_refs":      [<KnowledgeSourceRef as dict>] | [],
+        "evidence_refs":    [],
+        "connector_access": [],
+        "baseline_version": "v1-corpus@rev-1",
+    }
+
+V1 implementation: dictionary lookup against the in-process seed corpus.
+Missing record → ``payload.record = None`` (consumer maps to 404-style
+outcome). V1.1 backs onto a real corpus connector through the same
+public contract.
+"""
+from __future__ import annotations
+
+from typing import Any, Dict
+
+from pydantic import ValidationError
+
+from plm_shared.knowledge.primitives_v1 import (
+    KnowledgeGetRecordRequest,
+    KnowledgeGetRecordResponse,
+    KnowledgeRecord,
+)
+from plm_shared.knowledge_envelope import KnowledgeSourceRef
+from plm_skill_kernel import SkillContext, skill
+
+from ._v1_corpus import CORPUS_RECORDS
+from .search import V1_BASELINE_VERSION
+
+
+@skill(
+    id="knowledge.get_record",
+    version="1.0.0",
+    description=(
+        "Fetch a Knowledge record by id from a corpus. L1 read-only "
+        "surface; V1 thin-proxy against the in-process seed corpus."
+    ),
+    min_autonomy="L1",
+    streaming=False,
+    hitl_required=False,
+)
+async def knowledge_get_record(
+    payload: Dict[str, Any], ctx: SkillContext
+) -> Dict[str, Any]:
+    """Validate the request + emit the record (or None) + envelope artefacts."""
+    try:
+        request = KnowledgeGetRecordRequest.model_validate(payload)
+    except ValidationError as exc:
+        raise ValueError(
+            f"knowledge.get_record: invalid request payload — {exc.errors()}"
+        ) from exc
+
+    raw = CORPUS_RECORDS.get(request.corpus_id, {}).get(request.record_id)
+
+    if raw is None:
+        response = KnowledgeGetRecordResponse(record=None)
+        source_refs: list[dict] = []
+    else:
+        record = KnowledgeRecord(
+            record_id=request.record_id,
+            source_uri=raw["source_uri"],
+            corpus_id=request.corpus_id,
+            revision=raw["revision"],
+            title=raw.get("title"),
+            body=raw.get("body"),
+            payload=dict(raw.get("payload", {})),
+        )
+        response = KnowledgeGetRecordResponse(record=record)
+        source_refs = [
+            KnowledgeSourceRef(
+                ref_id=request.record_id,
+                ref_type=f"corpus:{request.corpus_id}",
+                title=record.title,
+                locator=record.source_uri,
+            ).model_dump()
+        ]
+
+    return {
+        "payload": response.model_dump(),
+        "source_refs": source_refs,
+        "evidence_refs": [],
+        "connector_access": [],
+        "baseline_version": V1_BASELINE_VERSION,
+    }
+
+
+__all__ = ["knowledge_get_record"]

plm_skill_kernel/skills/knowledge/resolve.py

@@ -0,0 +1,143 @@
+"""``knowledge.resolve`` / 1.0.0 / L1 — entity resolution.
+
+FTR-603 Wave 5 Conv C / Decision #122. V1 thin-proxy harvest of the
+D-LOCKED-23 active V1 ``resolve`` primitive (PRD §8.11.3).
+
+V1 contract:
+
+    payload = {
+        "entity_kind":   str,    # required
+        "surface_form":  str,    # required
+        "corpus_id":     str,    # required
+        "context":       dict,   # default {}
+    }
+
+Output:
+
+    {
+        "payload": {
+            "candidates":  [<KnowledgeResolution as dict>, ...],
+            "best":        <KnowledgeResolution as dict | None>,
+        },
+        "source_refs":      [<KnowledgeSourceRef as dict>, ...],
+        "evidence_refs":    [],
+        "connector_access": [],
+        "baseline_version": "v1-catalog@rev-1",
+    }
+
+V1 implementation: exact + normalised-substring match against the
+in-process entity catalog
+(:data:`plm_skill_kernel.skills.knowledge._v1_corpus.ENTITY_CATALOG`).
+The catalog is keyed by ``(entity_kind, surface_form_lower)``;
+returns 0..N candidates ordered by descending confidence.
+"""
+from __future__ import annotations
+
+from typing import Any, Dict, List
+
+from pydantic import ValidationError
+
+from plm_shared.knowledge.primitives_v1 import (
+    KnowledgeResolution,
+    KnowledgeResolveRequest,
+    KnowledgeResolveResponse,
+)
+from plm_shared.knowledge_envelope import KnowledgeSourceRef
+from plm_skill_kernel import SkillContext, skill
+
+from ._v1_corpus import ENTITY_CATALOG
+
+V1_BASELINE_VERSION = "v1-catalog@rev-1"
+
+
+def _candidates(entity_kind: str, surface_form: str) -> List[KnowledgeResolution]:
+    """V1 deterministic resolution.
+
+    Returns 0..N candidates ordered by descending confidence. Match
+    rules (V1):
+
+      * Exact lookup ``(entity_kind, surface_form_lower)`` — full confidence.
+      * Substring fallback — every entry whose surface_form is a
+        substring of the requested surface_form (or vice versa) is
+        emitted with a 0.4 confidence floor.
+
+    The catalog is small (≤4 entries V1) so the linear scan is fine;
+    V1.1 swaps in a real resolver behind the same skill contract.
+    """
+    needle = (entity_kind, surface_form.strip().lower())
+    out: List[KnowledgeResolution] = []
+    seen: set[str] = set()
+
+    direct = ENTITY_CATALOG.get(needle)
+    if direct is not None:
+        out.append(KnowledgeResolution(**direct))
+        seen.add(direct["canonical_id"])
+
+    needle_lower = needle[1]
+    for (kind, form), candidate in ENTITY_CATALOG.items():
+        if kind != entity_kind:
+            continue
+        if candidate["canonical_id"] in seen:
+            continue
+        if form in needle_lower or needle_lower in form:
+            out.append(
+                KnowledgeResolution(
+                    canonical_id=candidate["canonical_id"],
+                    label=candidate.get("label"),
+                    confidence=min(0.4, candidate["confidence"]),
+                )
+            )
+            seen.add(candidate["canonical_id"])
+
+    out.sort(key=lambda r: r.confidence, reverse=True)
+    return out
+
+
+@skill(
+    id="knowledge.resolve",
+    version="1.0.0",
+    description=(
+        "Entity resolution to a canonical id (Foundation). L1 "
+        "read-only surface; V1 thin-proxy against the in-process "
+        "entity catalog."
+    ),
+    min_autonomy="L1",
+    streaming=False,
+    hitl_required=False,
+)
+async def knowledge_resolve(
+    payload: Dict[str, Any], ctx: SkillContext
+) -> Dict[str, Any]:
+    """Validate the request + emit candidates + envelope artefacts."""
+    try:
+        request = KnowledgeResolveRequest.model_validate(payload)
+    except ValidationError as exc:
+        raise ValueError(
+            f"knowledge.resolve: invalid request payload — {exc.errors()}"
+        ) from exc
+
+    candidates = _candidates(request.entity_kind, request.surface_form)
+    best = candidates[0] if candidates else None
+
+    response = KnowledgeResolveResponse(candidates=candidates, best=best)
+
+    source_refs = [
+        KnowledgeSourceRef(
+            ref_id=c.canonical_id,
+            ref_type=f"entity:{request.entity_kind}",
+            title=c.label,
+            locator=f"foundation://entities/{c.canonical_id}",
+        ).model_dump()
+        for c in candidates
+    ]
+
+    return {
+        "payload": response.model_dump(),
+        "source_refs": source_refs,
+        "evidence_refs": [],
+        "connector_access": [],
+        "baseline_version": V1_BASELINE_VERSION,
+    }
+
+
+__all__ = ["V1_BASELINE_VERSION", "knowledge_resolve"]

plm_skill_kernel/skills/knowledge/retrieve.py

@@ -0,0 +1,143 @@
+"""``knowledge.retrieve`` / 1.0.0 / L1 — top-K ranked retrieval.
+
+FTR-603 Wave 5 Conv C / Decision #122. V1 thin-proxy harvest of the
+D-LOCKED-23 active V1 ``retrieve`` primitive (PRD §8.11.3).
+
+V1 contract:
+
+    payload = {
+        "corpus_id":         str,   # required
+        "query":             str,   # required
+        "baseline_version":  str,   # required (obligation 2 binding)
+        "top_k":             int,   # default 10, 1..100
+        "filters":           dict,  # default {}
+    }
+
+Output:
+
+    {
+        "payload": {"hits": [<KnowledgeHit as dict>, ...]},
+        "source_refs":      [<KnowledgeSourceRef as dict>, ...],
+        "evidence_refs":    [<KnowledgeSourceRef as dict>, ...],
+        "connector_access": [],
+        "baseline_version": <echo of request.baseline_version>,
+    }
+
+The retrieve primitive's distinguishing feature vs ``search`` is the
+mandatory ``baseline_version`` binding (PRD §8.11.3 obligation 2).
+The skill echoes the caller-supplied baseline back into the response
+artefacts; the engine-core envelope stamps it onto the wire envelope.
+
+V1 implementation: substring + position score (same scorer as
+``search``) over a baseline-filtered slice. Records whose ``revision``
+differs from the requested ``baseline_version`` (when the version is
+prefixed ``rev-``) are excluded; ``v1-corpus@*`` baselines accept
+every record.
+
+The retrieve primitive emits ``evidence_refs`` (obligation 4) — every
+hit also surfaces as an evidence pointer so consumers can audit the
+provenance chain without a follow-up call.
+"""
+from __future__ import annotations
+
+from typing import Any, Dict, List
+
+from pydantic import ValidationError
+
+from plm_shared.knowledge.primitives_v1 import (
+    KnowledgeHit,
+    KnowledgeRecord,
+    KnowledgeRetrieveRequest,
+    KnowledgeRetrieveResponse,
+)
+from plm_shared.knowledge_envelope import KnowledgeSourceRef
+from plm_skill_kernel import SkillContext, skill
+
+from ._v1_corpus import CORPUS_RECORDS
+from .search import _score_substring
+
+
+def _accepts_baseline(record_revision: str, baseline_version: str) -> bool:
+    """V1 baseline filter — accept all when baseline starts with ``v1-``."""
+    if baseline_version.startswith("v1-"):
+        return True
+    if baseline_version.startswith("rev-"):
+        return record_revision == baseline_version
+    return True
+
+
+@skill(
+    id="knowledge.retrieve",
+    version="1.0.0",
+    description=(
+        "Top-K ranked retrieval over a baseline-versioned slice. L1 "
+        "read-only surface; V1 thin-proxy with mandatory "
+        "baseline_version binding (PRD §8.11.3 obligation 2)."
+    ),
+    min_autonomy="L1",
+    streaming=False,
+    hitl_required=False,
+)
+async def knowledge_retrieve(
+    payload: Dict[str, Any], ctx: SkillContext
+) -> Dict[str, Any]:
+    """Validate the request + emit ranked hits + envelope artefacts."""
+    try:
+        request = KnowledgeRetrieveRequest.model_validate(payload)
+    except ValidationError as exc:
+        raise ValueError(
+            f"knowledge.retrieve: invalid request payload — {exc.errors()}"
+        ) from exc
+
+    records = CORPUS_RECORDS.get(request.corpus_id, {})
+    scored: List[KnowledgeHit] = []
+    for rec_id, raw in records.items():
+        if not _accepts_baseline(raw["revision"], request.baseline_version):
+            continue
+        text_blob = " ".join(
+            v
+            for v in (raw.get("title"), raw.get("body"))
+            if isinstance(v, str)
+        )
+        score = _score_substring(text_blob, request.query)
+        if score <= 0.0:
+            continue
+        scored.append(
+            KnowledgeHit(
+                score=score,
+                record=KnowledgeRecord(
+                    record_id=rec_id,
+                    source_uri=raw["source_uri"],
+                    corpus_id=request.corpus_id,
+                    revision=raw["revision"],
+                    title=raw.get("title"),
+                    body=raw.get("body"),
+                    payload=dict(raw.get("payload", {})),
+                ),
+            )
+        )
+    scored.sort(key=lambda h: h.score, reverse=True)
+    hits = scored[: request.top_k]
+
+    response = KnowledgeRetrieveResponse(hits=hits)
+
+    refs = [
+        KnowledgeSourceRef(
+            ref_id=h.record.record_id,
+            ref_type=f"corpus:{h.record.corpus_id}",
+            title=h.record.title,
+            locator=h.record.source_uri,
+        ).model_dump()
+        for h in hits
+    ]
+
+    return {
+        "payload": response.model_dump(),
+        "source_refs": refs,
+        "evidence_refs": refs,
+        "connector_access": [],
+        "baseline_version": request.baseline_version,
+    }
+
+
+__all__ = ["knowledge_retrieve"]

plm_skill_kernel/skills/knowledge/search.py

@@ -0,0 +1,161 @@
+"""``knowledge.search`` / 1.0.0 / L1 — semantic / hybrid search.
+
+FTR-603 Wave 5 Conv C / Decision #122. V1 thin-proxy harvest of the
+D-LOCKED-23 active V1 ``search`` primitive (PRD §8.11.3).
+
+V1 contract surface (from
+:class:`plm_shared.knowledge.primitives_v1.KnowledgeSearchRequest`):
+
+    payload = {
+        "corpus_id":  str,           # required
+        "query":      str,           # required
+        "top_k":      int,           # default 10, 1..100
+        "filters":    dict,          # default {}
+    }
+
+Output:
+
+    {
+        "payload": {
+            "hits":   [<KnowledgeHit as dict>, ...],
+            "total":  int,
+        },
+        "source_refs":      [<KnowledgeSourceRef as dict>, ...],
+        "evidence_refs":    [<KnowledgeSourceRef as dict>, ...],
+        "connector_access": [],   # V1 corpus is local — no connector reach-out
+        "baseline_version": "v1-corpus@rev-1",
+    }
+
+V1 implementation: deterministic substring-match against the in-process
+seed corpus (:mod:`plm_skill_kernel.skills.knowledge._v1_corpus`).
+V1.1 will swap to the production retrieval backend through the same
+public skill contract — the lazy backend-binding pattern in the
+``agents.suggest`` precedent (Wave 3 Conv A) is the V1.1 template.
+
+Read-only by design — no connector_access entries emitted (Foundation /
+local corpus reads are not connector calls). Obligation 8 / invariant
+#11 trivially satisfied.
+"""
+from __future__ import annotations
+
+from typing import Any, Dict, List
+
+from pydantic import ValidationError
+
+from plm_shared.knowledge.primitives_v1 import (
+    KnowledgeHit,
+    KnowledgeRecord,
+    KnowledgeSearchRequest,
+    KnowledgeSearchResponse,
+)
+from plm_shared.knowledge_envelope import KnowledgeSourceRef
+from plm_skill_kernel import SkillContext, skill
+
+from ._v1_corpus import CORPUS_RECORDS
+
+V1_BASELINE_VERSION = "v1-corpus@rev-1"
+
+
+def _score_substring(haystack: str, needle: str) -> float:
+    """V1 deterministic relevance score in [0, 1].
+
+    Returns 0.0 when the needle is not found; otherwise weights inverse
+    position + length match. The score is corpus-relative, NOT a
+    normalised semantic score — consumers MUST treat it as opaque.
+    """
+    if not needle:
+        return 0.0
+    h = haystack.lower()
+    n = needle.lower()
+    idx = h.find(n)
+    if idx < 0:
+        return 0.0
+    return round(1.0 - (idx / (len(h) + 1)), 4)
+
+
+def _record_dict(corpus_id: str, record_id: str, raw: Dict[str, Any]) -> Dict[str, Any]:
+    return KnowledgeRecord(
+        record_id=record_id,
+        source_uri=raw["source_uri"],
+        corpus_id=corpus_id,
+        revision=raw["revision"],
+        title=raw.get("title"),
+        body=raw.get("body"),
+        payload=dict(raw.get("payload", {})),
+    ).model_dump()
+
+
+@skill(
+    id="knowledge.search",
+    version="1.0.0",
+    description=(
+        "Semantic / hybrid search over a Knowledge corpus. L1 read-only "
+        "surface; V1 thin-proxy against the in-process seed corpus."
+    ),
+    min_autonomy="L1",
+    streaming=False,
+    hitl_required=False,
+)
+async def knowledge_search(
+    payload: Dict[str, Any], ctx: SkillContext
+) -> Dict[str, Any]:
+    """Validate the request + emit V1 hits + envelope artefacts."""
+    try:
+        request = KnowledgeSearchRequest.model_validate(payload)
+    except ValidationError as exc:
+        raise ValueError(
+            f"knowledge.search: invalid request payload — {exc.errors()}"
+        ) from exc
+
+    records = CORPUS_RECORDS.get(request.corpus_id, {})
+    scored: List[KnowledgeHit] = []
+    for rec_id, raw in records.items():
+        # V1 substring match against title + body; filters are ignored
+        # at V1 (kept on the request for V1.1 contract preservation).
+        text_blob = " ".join(
+            v
+            for v in (raw.get("title"), raw.get("body"))
+            if isinstance(v, str)
+        )
+        score = _score_substring(text_blob, request.query)
+        if score <= 0.0:
+            continue
+        scored.append(
+            KnowledgeHit(
+                score=score,
+                record=KnowledgeRecord(
+                    record_id=rec_id,
+                    source_uri=raw["source_uri"],
+                    corpus_id=request.corpus_id,
+                    revision=raw["revision"],
+                    title=raw.get("title"),
+                    body=raw.get("body"),
+                    payload=dict(raw.get("payload", {})),
+                ),
+            )
+        )
+    scored.sort(key=lambda h: h.score, reverse=True)
+    hits = scored[: request.top_k]
+
+    response = KnowledgeSearchResponse(hits=hits, total=len(scored))
+
+    source_refs = [
+        KnowledgeSourceRef(
+            ref_id=h.record.record_id,
+            ref_type=f"corpus:{h.record.corpus_id}",
+            title=h.record.title,
+            locator=h.record.source_uri,
+        ).model_dump()
+        for h in hits
+    ]
+
+    return {
+        "payload": response.model_dump(),
+        "source_refs": source_refs,
+        "evidence_refs": [],
+        "connector_access": [],
+        "baseline_version": V1_BASELINE_VERSION,
+    }
+
+
+__all__ = ["V1_BASELINE_VERSION", "knowledge_search"]