structuremappingmemory 1.0.0__py3-none-any.whl

sma/match/mh.py

@@ -0,0 +1,177 @@
+"""Match hypothesis seeding and support closure."""
+
+from __future__ import annotations
+
+from collections import defaultdict, deque
+
+from sma.ir.canon import Canonicalizer, default_canonicalizer
+from sma.ir.schema import Entity, Statement
+from sma.ir.sexpr import dumps_node
+
+from .types import MatchConfig, MatchHypothesis
+
+
+def seed_expression_mhs(
+    base_exprs: tuple[Statement, ...],
+    target_exprs: tuple[Statement, ...],
+    config: MatchConfig | None = None,
+    canon: Canonicalizer | None = None,
+) -> tuple[MatchHypothesis, ...]:
+    config = config or MatchConfig()
+    canon = canon or default_canonicalizer()
+    base_groups = _group_by_signature(base_exprs, canon)
+    target_groups = _group_by_signature(target_exprs, canon)
+
+    out: list[MatchHypothesis] = []
+    for key, bases in base_groups.items():
+        targets = target_groups.get(key)
+        if targets:
+            for b, t in _capped_pairs(bases, targets, config.mh_group_cap):
+                out.append(MatchHypothesis(b, t))
+    if config.delta > 0:
+        # Minimal ascension across canonical groups, also capped per group pair.
+        for (b_functor, b_arity), bases in base_groups.items():
+            for (t_functor, t_arity), targets in target_groups.items():
+                if b_arity != t_arity or b_functor == t_functor:
+                    continue
+                ok, asc, ancestor, dist = canon.compatible(
+                    b_functor, t_functor, delta=config.delta, rho=config.rho
+                )
+                if ok:
+                    for b, t in _capped_pairs(bases, targets, config.mh_group_cap):
+                        out.append(MatchHypothesis(b, t, asc, ancestor, dist))
+    return tuple(out)
+
+
+def _group_by_signature(
+    exprs: tuple[Statement, ...], canon: Canonicalizer
+) -> dict[tuple[str, int], list[Statement]]:
+    groups: dict[tuple[str, int], list[Statement]] = defaultdict(list)
+    for expr in exprs:
+        groups[(canon.canonical(expr.functor), expr.arity)].append(expr)
+    return groups
+
+
+def _capped_pairs(
+    bases: list[Statement], targets: list[Statement], cap: int
+) -> list[tuple[Statement, Statement]]:
+    """Deterministic U-ordered pair selection within one functor group.
+
+    Small groups keep the full cross product. Large groups are capped:
+    bit-identical statements pair first (they carry the highest achievable
+    match score), then a band around the canonical sort order fills the rest.
+    """
+    if len(bases) * len(targets) <= cap:
+        return [(b, t) for b in bases for t in targets]
+
+    base_text = {id(b): dumps_node(b) for b in bases}
+    target_text = {id(t): dumps_node(t) for t in targets}
+    sorted_bases = sorted(bases, key=lambda s: base_text[id(s)])
+    sorted_targets = sorted(targets, key=lambda s: target_text[id(s)])
+
+    pairs: list[tuple[Statement, Statement]] = []
+    used: set[tuple[int, int]] = set()
+
+    by_text: dict[str, deque] = defaultdict(deque)
+    for t in sorted_targets:
+        by_text[target_text[id(t)]].append(t)
+    for b in sorted_bases:
+        queue = by_text.get(base_text[id(b)])
+        if queue:
+            t = queue.popleft()
+            pairs.append((b, t))
+            used.add((id(b), id(t)))
+            if len(pairs) >= cap:
+                return pairs
+
+    n_targets = len(sorted_targets)
+    for offset in range(n_targets):
+        for i, b in enumerate(sorted_bases):
+            for j in ((i + offset, i - offset) if offset else (i,)):
+                if 0 <= j < n_targets:
+                    t = sorted_targets[j]
+                    if (id(b), id(t)) not in used:
+                        used.add((id(b), id(t)))
+                        pairs.append((b, t))
+                        if len(pairs) >= cap:
+                            return pairs
+    return pairs
+
+
+# Entity types whose names are CONSTANTS, not variables (blueprint 2.1:
+# entities/constants are distinct vocabulary classes). A template-name or
+# integer entity denotes itself; pairing count(template_A, 3) with
+# count(template_B, 2) is vacuous shape-matching, not analogy - it was the
+# root cause of the Liberty haystack failure (generic bookkeeping skeleton
+# matching any session against any other).
+# Integers are deliberately NOT constants: count(template_X, 3) vs
+# count(template_X, 5) is a legitimate analogy (same burst, different size);
+# the template-name constraint alone blocks the vacuous cross-template case.
+CONSTANT_ENTITY_TYPES = frozenset({"event_type"})
+
+
+def constants_compatible(b_ent: Entity, t_ent: Entity) -> bool:
+    if b_ent.type in CONSTANT_ENTITY_TYPES and t_ent.type in CONSTANT_ENTITY_TYPES:
+        return b_ent.name == t_ent.name
+    return True
+
+
+def support_closure(
+    root: MatchHypothesis,
+    canon: Canonicalizer | None = None,
+    delta: int = 0,
+    rho: float = 1.0,
+) -> tuple[MatchHypothesis, ...] | None:
+    """Downward closure of a root MH; None when structurally impossible.
+
+    SME parallel connectivity: argument correspondences must themselves be
+    LEGAL match hypotheses. A statement-argument pair with incompatible
+    functors invalidates the whole kernel (previously it was silently
+    admitted, letting higher-order parents like `before` manufacture
+    cross-template "matches" that surprisal weighting then amplified - the
+    Liberty ses_n>1 anomaly). Compatibility = canonical identity, or lattice
+    ascension within delta at rho^dist penalty. Unequal constants likewise
+    invalidate.
+    """
+    canon = canon or default_canonicalizer()
+    out: list[MatchHypothesis] = []
+    seen: set[tuple[str, str]] = set()
+    bad = False
+
+    def add(mh: MatchHypothesis) -> None:
+        nonlocal bad
+        if bad or mh.key in seen:
+            return
+        seen.add(mh.key)
+        out.append(mh)
+        if isinstance(mh.base, Statement) and isinstance(mh.target, Statement):
+            if mh.base.arity != mh.target.arity:
+                bad = True
+                return
+            for b_arg, t_arg in zip(mh.base.args, mh.target.args, strict=True):
+                if isinstance(b_arg, Entity) and isinstance(t_arg, Entity):
+                    if not constants_compatible(b_arg, t_arg):
+                        bad = True
+                        return
+                    add(MatchHypothesis(b_arg, t_arg))
+                elif isinstance(b_arg, Statement) and isinstance(t_arg, Statement):
+                    ok, asc, ancestor, dist = canon.compatible(
+                        b_arg.functor, t_arg.functor, delta=delta, rho=rho
+                    )
+                    if not ok:
+                        bad = True
+                        return
+                    # Each MH pays ITS OWN ascension penalty only - the
+                    # parent's penalty lives in the parent's weight.
+                    # Multiplying down the chain (a previous bug) punished
+                    # deep systems exponentially, the opposite of
+                    # systematicity.
+                    add(MatchHypothesis(b_arg, t_arg, ascension=asc,
+                                        ancestor=ancestor, distance=dist))
+                else:
+                    # Statement paired with entity (or vice versa): illegal.
+                    bad = True
+                    return
+
+    add(root)
+    return None if bad else tuple(out)

sma/match/ses.py

@@ -0,0 +1,84 @@
+"""Structural evaluation score with trickle-down support.
+
+Two weighting regimes share this code path:
+- SES (default): every match hypothesis carries unit base weight sigma_0 = 1.
+- surprisal-SES (score-v2 candidate, ADR-004 upgrade path): statement MHs
+  carry sigma_0 = corpus surprisal of their canonical functor (-log2 p), so
+  rare shared structure counts more while systematicity still compounds via
+  trickle-down. With cost_fn=None this reduces exactly to SES.
+"""
+
+from __future__ import annotations
+
+from typing import Callable
+
+from sma.ir.schema import Statement
+
+from .types import GMap, MatchHypothesis, node_key
+
+CostFn = Callable[[MatchHypothesis], float]
+
+
+def structural_evaluation(
+    hypotheses: tuple[MatchHypothesis, ...],
+    gamma: float = 0.25,
+    cost_fn: CostFn | None = None,
+) -> float:
+    by_key = {mh.key: mh for mh in hypotheses}
+    parents: dict[tuple[str, str], list[tuple[str, str]]] = {mh.key: [] for mh in hypotheses}
+    for mh in hypotheses:
+        if not isinstance(mh.base, Statement) or not isinstance(mh.target, Statement):
+            continue
+        for b_arg, t_arg in zip(mh.base.args, mh.target.args, strict=True):
+            child_key = (node_key(b_arg), node_key(t_arg))
+            if child_key in parents:
+                parents[child_key].append(mh.key)
+
+    def weight(mh: MatchHypothesis) -> float:
+        return 1.0 if cost_fn is None else cost_fn(mh)
+
+    memo: dict[tuple[str, str], float] = {}
+
+    def score(key: tuple[str, str], stack: frozenset[tuple[str, str]] = frozenset()) -> float:
+        if key in memo:
+            return memo[key]
+        if key in stack:
+            return weight(by_key[key]) * by_key[key].ascension
+        parent_score = sum(score(parent, stack | {key}) for parent in parents.get(key, ()))
+        value = weight(by_key[key]) * by_key[key].ascension + gamma * parent_score
+        memo[key] = value
+        return value
+
+    return sum(score(key) for key in by_key)
+
+
+def self_score(case, gamma: float = 0.25, cost_fn: CostFn | None = None) -> float:
+    hyps: list[MatchHypothesis] = []
+    for expr in case.expressions():
+        hyps.append(MatchHypothesis(expr, expr))
+        for entity in expr.entities():
+            hyps.append(MatchHypothesis(entity, entity))
+    unique = {mh.key: mh for mh in hyps}
+    return structural_evaluation(tuple(unique.values()), gamma=gamma, cost_fn=cost_fn)
+
+
+def normalize_score(
+    score: float,
+    base,
+    target,
+    gamma: float = 0.25,
+    cost_fn: CostFn | None = None,
+    normalization: str = "max",
+) -> float:
+    # Same weights in numerator and denominators keep ses_n scale-free.
+    self_base = self_score(base, gamma, cost_fn=cost_fn)
+    self_target = self_score(target, gamma, cost_fn=cost_fn)
+    if normalization == "min":
+        denom = min(self_base, self_target)
+    elif normalization == "sqrt":
+        denom = (self_base * self_target) ** 0.5
+    elif normalization == "target":
+        denom = self_target
+    else:  # "max", blueprint 2.3
+        denom = max(self_base, self_target)
+    return score / max(denom, 1e-9)

sma/match/types.py

@@ -0,0 +1,115 @@
+"""Shared matcher dataclasses."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from functools import cached_property
+
+from sma.ir.schema import Case, Entity, Node, Statement
+from sma.ir.sexpr import dumps_node
+
+
+def node_key(node: Node) -> str:
+    prefix = "E" if isinstance(node, Entity) else "S"
+    return f"{prefix}:{dumps_node(node)}"
+
+
+@dataclass(frozen=True)
+class MatchHypothesis:
+    base: Node
+    target: Node
+    ascension: float = 1.0
+    ancestor: str | None = None
+    distance: int = 0
+
+    # node_key serializes the whole expression tree, and these keys are read
+    # O(kernels^2) times during merge — they must be computed once per instance.
+    @cached_property
+    def base_key(self) -> str:
+        return node_key(self.base)
+
+    @cached_property
+    def target_key(self) -> str:
+        return node_key(self.target)
+
+    @cached_property
+    def key(self) -> tuple[str, str]:
+        return (self.base_key, self.target_key)
+
+
+@dataclass
+class Kernel:
+    root: MatchHypothesis
+    hypotheses: tuple[MatchHypothesis, ...]
+    weight: float = 0.0
+
+    @cached_property
+    def bindings(self) -> dict[str, str]:
+        return {mh.base_key: mh.target_key for mh in self.hypotheses}
+
+    @cached_property
+    def reverse_bindings(self) -> dict[str, str]:
+        return {target: base for base, target in self.bindings.items()}
+
+
+@dataclass
+class GMap:
+    base: Case
+    target: Case
+    hypotheses: tuple[MatchHypothesis, ...]
+    kernels: tuple[Kernel, ...]
+    score: float
+    normalized_score: float
+    scorer: str = "ses"
+    optimality_gap: float | None = None
+
+    @property
+    def correspondences(self) -> list[dict[str, str | float | int | None]]:
+        return [
+            {
+                "base": mh.base_key,
+                "target": mh.target_key,
+                "ascension": mh.ascension,
+                "ancestor": mh.ancestor,
+                "distance": mh.distance,
+            }
+            for mh in self.hypotheses
+        ]
+
+
+@dataclass(frozen=True)
+class CandidateInference:
+    inference_sexpr: str
+    base_case_id: str
+    target_case_id: str
+    ses_n: float
+    support: tuple[str, ...] = ()
+    skolems: tuple[str, ...] = ()
+    ascensions: tuple[str, ...] = ()
+    status: str = "hypothetical"
+
+
+@dataclass
+class MatchConfig:
+    gamma: float = 0.25
+    rho: float = 0.95  # frozen at prereg-v1 (calibration grid; inert when delta=0)
+    delta: int = 0
+    scorer: str = "surprisal"  # "ses" | "mdl" | "surprisal" (score-v2, ADR-005)
+    # Normalization of the structural score: "max" (blueprint 2.3),
+    # "min" (10.2 tripwire), "sqrt" (geometric mean, cosine-style symmetric),
+    # "target" (query-relative; ranking == raw-score ordering per query).
+    # Frozen to "max" at prereg-v1 (calibration grid: beats target on family
+    # and LOO-haystack validation). Registered caveat: out-of-corpus haystack
+    # probes use hybrid fused as the production posture.
+    normalization: str = "max"
+    # Corpus surprisal per canonical functor (-log2 p), supplied by the index
+    # for scorer="surprisal"; None means unit weights (identical to "ses").
+    functor_costs: dict | None = None
+    exact_kernel_limit: int = 60
+    cpsat_time_ms: int = 20
+    # Tripwire response from blueprint section 10.2: cap MH pairs per functor
+    # group (U-ordered: identical statements first) so sessions with many
+    # repeated event types cannot explode the kernel count quadratically.
+    mh_group_cap: int = 128
+    metadata: dict = field(default_factory=dict)
+

sma/match/verifier.py

@@ -0,0 +1,27 @@
+"""Inference verifier."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from sma.ir.sexpr import loads_statement
+from sma.ir.signatures import SignatureRegistry
+
+
+@dataclass(frozen=True)
+class VerificationResult:
+    status: str
+    reasons: tuple[str, ...] = ()
+
+
+def verify_inference(inference_sexpr: str, registry: SignatureRegistry | None = None) -> VerificationResult:
+    registry = registry or SignatureRegistry.with_defaults()
+    try:
+        statement = loads_statement(inference_sexpr)
+        registry.validate_statement(statement)
+    except Exception as exc:
+        return VerificationResult("type_fail", (str(exc),))
+    if "AnalogySkolemFn_" in inference_sexpr:
+        return VerificationResult("hypothetical", ("contains analogy skolems",))
+    return VerificationResult("pass", ())
+

sma/ontology/__init__.py

@@ -0,0 +1,45 @@
+"""Universal OWL/OBO ontology loader, mounter, registry, and router for SMA-1.
+
+This package generalizes the hand-rolled HPO mount in
+``scripts/rare_disease_test.py`` into a reusable pipeline: parse any OBO/OWL
+ontology into a normalized :class:`OntologyGraph`, mount it onto a
+``Canonicalizer`` (is-a edges become the predicate lattice), build a
+``MacFacIndex`` over cases, and retrieve by structural analogy. A
+:class:`OntologyRegistry` caches mounted ontologies and a :class:`DomainRouter`
+selects which ontology a query belongs to. See ``sma/ontology/README.md``.
+"""
+
+from __future__ import annotations
+
+from .attack import load_attack_stix
+from .cpc import load_cpc
+from .mitre_xml import load_capec, load_cwe, load_mitre_xml
+from .rdf_loader import load_rdflib
+from .usgaap import load_usgaap
+from .graph import OntologyGraph, Term
+from .loader import fid, load_obo, load_ontology, load_owl, load_owl_dir
+from .mount import MountedOntology, mount
+from .registry import OntologyEntry, OntologyRegistry
+from .router import DomainRouter
+
+__all__ = [
+    "OntologyGraph",
+    "Term",
+    "load_obo",
+    "load_owl",
+    "load_owl_dir",
+    "load_ontology",
+    "fid",
+    "MountedOntology",
+    "mount",
+    "OntologyRegistry",
+    "OntologyEntry",
+    "DomainRouter",
+    "load_attack_stix",
+    "load_cpc",
+    "load_capec",
+    "load_cwe",
+    "load_mitre_xml",
+    "load_rdflib",
+    "load_usgaap",
+]

sma/ontology/attack.py

@@ -0,0 +1,134 @@
+"""Load MITRE ATT&CK (STIX 2.1 JSON) into the normalized :class:`OntologyGraph`.
+
+ATT&CK ships as a STIX bundle (``mitre/cti`` ``enterprise-attack.json``), not
+OBO/OWL, so it needs a dedicated parser. It maps cleanly onto the same shape the
+rest of the ontology package consumes:
+
+* ``attack-pattern`` objects become technique terms, keyed by their ATT&CK
+  ``external_id`` (e.g. ``"T1059"`` or sub-technique ``"T1059.001"``).
+* ``x-mitre-tactic`` objects become tactic terms, keyed by their ``shortname``.
+* A sub-technique ``T1059.001`` gets is_a parent ``T1059`` (split on ``"."``);
+  this is corroborated by ``relationship`` objects of type ``subtechnique-of``.
+* A technique's ``kill_chain_phases`` and STIX ``uses``/``mitigates``
+  relationships become typed relations between the mapped external ids.
+
+Revoked or ``x_mitre_deprecated`` objects are marked obsolete.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from .graph import OntologyGraph, Term
+
+#: ATT&CK download URL (kept here so the demo can surface it without fetching).
+ATTACK_STIX_URL = (
+    "https://raw.githubusercontent.com/mitre/cti/master/"
+    "enterprise-attack/enterprise-attack.json"
+)
+
+
+def _external_id(obj: dict) -> str:
+    """Return the ATT&CK external_id (e.g. ``T1059``) for a STIX object, or ``""``."""
+    for ref in obj.get("external_references", ()):
+        if ref.get("source_name") == "mitre-attack" and ref.get("external_id"):
+            return ref["external_id"]
+    return ""
+
+
+def _is_obsolete(obj: dict) -> bool:
+    """True if the STIX object is revoked or marked deprecated."""
+    return bool(obj.get("revoked")) or bool(obj.get("x_mitre_deprecated"))
+
+
+def load_attack_stix(path: str, name: str = "attack") -> OntologyGraph:
+    """Parse an ATT&CK STIX 2.1 bundle into an :class:`OntologyGraph`.
+
+    Techniques (``attack-pattern``) and tactics (``x-mitre-tactic``) become
+    terms; sub-technique is_a edges, kill-chain ``accomplishes`` links, and
+    ``uses``/``mitigates`` relationships become parents/typed relations between
+    the resolved external ids.
+    """
+    with open(path, "r", encoding="utf-8") as handle:
+        bundle = json.load(handle)
+
+    version = str(bundle.get("spec_version", "") or "")
+    objects = bundle.get("objects", [])
+
+    terms: dict[str, Term] = {}
+    # STIX object 'id' -> our term id (external_id / tactic shortname), so that
+    # 'relationship' objects (which reference STIX ids) can resolve endpoints.
+    stix_to_term: dict[str, str] = {}
+    # Accumulate parents/relations per term id before constructing Term records.
+    parents: dict[str, set[str]] = {}
+    relations: dict[str, set[tuple[str, str]]] = {}
+    obsolete: dict[str, bool] = {}
+    names: dict[str, str] = {}
+
+    # --- First pass: collect technique + tactic terms. --------------------- #
+    for obj in objects:
+        otype = obj.get("type")
+        if otype == "attack-pattern":
+            tid = _external_id(obj)
+            if not tid:
+                continue
+            stix_to_term[obj.get("id", "")] = tid
+            names[tid] = obj.get("name", "")
+            obsolete[tid] = _is_obsolete(obj)
+            parents.setdefault(tid, set())
+            relations.setdefault(tid, set())
+            # Sub-technique is_a parent derived by splitting the id on ".".
+            if "." in tid:
+                parents[tid].add(tid.split(".", 1)[0])
+            # kill_chain_phases -> ("accomplishes", tactic_shortname)
+            for phase in obj.get("kill_chain_phases", ()):
+                if phase.get("kill_chain_name") == "mitre-attack":
+                    pname = phase.get("phase_name")
+                    if pname:
+                        relations[tid].add(("accomplishes", pname))
+        elif otype == "x-mitre-tactic":
+            short = obj.get("x_mitre_shortname") or _external_id(obj)
+            if not short:
+                continue
+            stix_to_term[obj.get("id", "")] = short
+            names[short] = obj.get("name", "")
+            obsolete[short] = _is_obsolete(obj)
+            parents.setdefault(short, set())
+            relations.setdefault(short, set())
+
+    # --- Second pass: STIX relationship objects. --------------------------- #
+    for obj in objects:
+        if obj.get("type") != "relationship":
+            continue
+        if _is_obsolete(obj):
+            continue
+        rtype = obj.get("relationship_type")
+        src = stix_to_term.get(obj.get("source_ref", ""))
+        tgt = stix_to_term.get(obj.get("target_ref", ""))
+        if not src or not tgt:
+            continue
+        if rtype == "subtechnique-of":
+            # Corroborates (and is the source of truth for) the is_a edge.
+            parents.setdefault(src, set()).add(tgt)
+        elif rtype in ("uses", "mitigates"):
+            relations.setdefault(src, set()).add((rtype, tgt))
+
+    # --- Materialize Term records (parents/relations to resolvable ids). --- #
+    for tid in names:
+        ps = tuple(sorted(p for p in parents.get(tid, ()) if p in names))
+        rs = tuple(sorted(
+            (rel, obj_id) for rel, obj_id in relations.get(tid, ())
+            if obj_id in names
+        ))
+        terms[tid] = Term(
+            id=tid,
+            name=names[tid],
+            parents=ps,
+            relations=rs,
+            obsolete=obsolete.get(tid, False),
+        )
+
+    if not name:
+        name = Path(path).stem
+    return OntologyGraph(name=name, version=version, terms=terms)

sma/ontology/cpc.py

@@ -0,0 +1,69 @@
+"""Loader for the Cooperative Patent Classification (CPC) scheme XML.
+
+CPC ships as one XML file per subclass (``cpc-scheme-A01B.xml`` ...), each a tree
+of nested ``<classification-item>`` elements. The nesting IS the is-a hierarchy:
+a classification-item nested inside another is a narrower category of it. We map
+each item's ``<classification-symbol>`` to a :class:`Term` id, its
+``<class-title>`` text to the name, and the enclosing item's symbol to its is-a
+parent. This yields the deep (~250k node) golden taxonomy for the legal/IP arm.
+"""
+from __future__ import annotations
+
+import xml.etree.ElementTree as ET
+from pathlib import Path
+
+from .graph import OntologyGraph, Term
+
+
+def _local(tag: str) -> str:
+    return tag.rsplit("}", 1)[-1] if "}" in tag else tag
+
+
+def _title(item: ET.Element) -> str:
+    """Concatenate the text fragments under an item's direct <class-title>."""
+    for child in item:
+        if _local(child.tag) == "class-title":
+            parts = [t.text.strip() for t in child.iter()
+                     if _local(t.tag) == "text" and t.text and t.text.strip()]
+            return "; ".join(parts)
+    return ""
+
+
+def _walk(item: ET.Element, parent_symbol: str, terms: dict[str, Term]) -> None:
+    symbol = ""
+    for child in item:
+        if _local(child.tag) == "classification-symbol":
+            symbol = (child.text or "").strip()
+            break
+    if symbol:
+        existing = terms.get(symbol)
+        parents = (parent_symbol,) if parent_symbol else ()
+        if existing is None:
+            terms[symbol] = Term(id=symbol, name=_title(item), parents=parents)
+        elif parent_symbol and parent_symbol not in existing.parents:
+            terms[symbol] = Term(id=symbol, name=existing.name or _title(item),
+                                 parents=tuple(dict.fromkeys((*existing.parents, parent_symbol))))
+    next_parent = symbol or parent_symbol
+    for child in item:
+        if _local(child.tag) == "classification-item":
+            _walk(child, next_parent, terms)
+
+
+def load_cpc(path: str, name: str = "cpc") -> OntologyGraph:
+    """Load the CPC scheme from a directory of cpc-scheme-*.xml files (or one file)."""
+    root_path = Path(path)
+    files = sorted(root_path.glob("cpc-scheme-*.xml")) if root_path.is_dir() else [root_path]
+    terms: dict[str, Term] = {}
+    version = ""
+    for f in files:
+        try:
+            tree = ET.parse(f)
+        except ET.ParseError:
+            continue
+        scheme = tree.getroot()
+        if not version:
+            version = scheme.get("publication-date", "")
+        for child in scheme:
+            if _local(child.tag) == "classification-item":
+                _walk(child, "", terms)
+    return OntologyGraph(name=name, version=version, terms=terms)