structuremappingmemory 1.0.0__py3-none-any.whl

sma/index/__init__.py

@@ -0,0 +1,15 @@
+from .content_vectors import CaseVector, cosine, functor_vector
+from .inverted import InvertedIndex, histogram_intersection, ses_upper_bound
+from .macfac import MacFacIndex, RetrievalResult
+
+__all__ = [
+    "CaseVector",
+    "InvertedIndex",
+    "MacFacIndex",
+    "RetrievalResult",
+    "cosine",
+    "functor_vector",
+    "histogram_intersection",
+    "ses_upper_bound",
+]
+

sma/index/ann.py

@@ -0,0 +1,21 @@
+"""Small ANN facade with deterministic brute-force fallback."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from .content_vectors import Vector, cosine
+
+
+@dataclass
+class AnnIndex:
+    vectors: dict[str, Vector] = field(default_factory=dict)
+
+    def add(self, case_id: str, vector: Vector) -> None:
+        self.vectors[case_id] = vector
+
+    def search(self, query: Vector, k: int = 200) -> list[tuple[str, float]]:
+        ranked = [(case_id, cosine(query, vector)) for case_id, vector in self.vectors.items()]
+        ranked.sort(key=lambda row: (-row[1], row[0]))
+        return ranked[:k]
+

sma/index/content_vectors.py

@@ -0,0 +1,60 @@
+"""MAC content vectors with WL-1 refinement features."""
+
+from __future__ import annotations
+
+from collections import Counter
+from dataclasses import dataclass
+
+from sma.ir.canon import Canonicalizer, default_canonicalizer
+from sma.ir.schema import Case, Statement
+
+
+Vector = Counter[str]
+
+
+def functor_vector(
+    case: Case,
+    wl: bool = True,
+    canon: Canonicalizer | None = None,
+    canonicalize: bool = True,
+    delta: int = 0,
+) -> Vector:
+    """MAC content vector: canonical functor counts + WL-1 features.
+
+    With delta > 0, each functor also contributes its lattice ancestors within
+    delta steps (blueprint 2.7: counts over the <=delta ancestor closure), so
+    vocabularies bridged only by the lattice still intersect at the MAC stage.
+    Ancestor features only ADD mass, keeping the Lemma-2 bound admissible.
+    """
+    canon = canon or default_canonicalizer()
+    counts: Vector = Counter()
+    for expr in case.expressions():
+        functor = canon.canonical(expr.functor) if canonicalize else expr.functor
+        counts[f"f:{functor}"] += 1
+        if delta:
+            for ancestor, dist in canon.lattice.ancestors(functor, delta).items():
+                if ancestor != functor:
+                    counts[f"f:{ancestor}"] += 1
+        if wl:
+            for i, arg in enumerate(expr.args):
+                if isinstance(arg, Statement):
+                    child_functor = canon.canonical(arg.functor) if canonicalize else arg.functor
+                    counts[f"wl:{functor}:{i}:{child_functor}"] += 1
+                else:
+                    counts[f"wl:{functor}:{i}:ENTITY"] += 1
+    return counts
+
+
+def cosine(left: Vector, right: Vector) -> float:
+    dot = sum(v * right.get(k, 0) for k, v in left.items())
+    left_norm = sum(v * v for v in left.values()) ** 0.5
+    right_norm = sum(v * v for v in right.values()) ** 0.5
+    if left_norm == 0 or right_norm == 0:
+        return 0.0
+    return dot / (left_norm * right_norm)
+
+
+@dataclass(frozen=True)
+class CaseVector:
+    case_id: str
+    vector: Vector

sma/index/inverted.py

@@ -0,0 +1,63 @@
+"""Exact histogram-intersection upper bounds."""
+
+from __future__ import annotations
+
+from collections import Counter, defaultdict
+from dataclasses import dataclass, field
+
+from .content_vectors import Vector
+
+
+def histogram_intersection(left: Vector, right: Vector) -> int:
+    if len(left) > len(right):
+        left, right = right, left
+    return sum(min(value, right.get(key, 0)) for key, value in left.items())
+
+
+def ses_upper_bound(
+    left: Vector, right: Vector, max_score_per_mh: float = 2.0, costs: dict | None = None
+) -> float:
+    """Admissible bound on the (optionally surprisal-weighted) SES score.
+
+    Unweighted: max_score_per_mh * histogram intersection (Lemma 2). With
+    costs, each shared functor occurrence may carry at most cost * s-bar, so
+    'f:' features are cost-weighted; WL features keep weight 1, which only
+    adds slack (still admissible, blueprint section 2.7 weighted form).
+    """
+    if costs is None:
+        return max_score_per_mh * histogram_intersection(left, right)
+    if len(left) > len(right):
+        left, right = right, left
+    total = 0.0
+    for key, value in left.items():
+        shared = min(value, right.get(key, 0))
+        if not shared:
+            continue
+        weight = costs.get(key[2:], 1.0) if key.startswith("f:") else 1.0
+        total += weight * shared
+    return max_score_per_mh * total
+
+
+@dataclass
+class InvertedIndex:
+    postings: dict[str, set[str]] = field(default_factory=lambda: defaultdict(set))
+    vectors: dict[str, Vector] = field(default_factory=dict)
+
+    def add(self, case_id: str, vector: Vector) -> None:
+        self.vectors[case_id] = vector
+        for feature in vector:
+            self.postings.setdefault(feature, set()).add(case_id)
+
+    def candidates(self, query: Vector) -> set[str]:
+        out: set[str] = set()
+        for feature in query:
+            out.update(self.postings.get(feature, ()))
+        return out
+
+    def bound(
+        self, query: Vector, case_id: str, max_score_per_mh: float = 2.0, costs: dict | None = None
+    ) -> float:
+        return ses_upper_bound(
+            query, self.vectors[case_id], max_score_per_mh=max_score_per_mh, costs=costs
+        )
+

sma/index/macfac.py

@@ -0,0 +1,174 @@
+"""Certified MAC/FAC retrieval over a case library."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from sma.ir.canon import Canonicalizer, default_canonicalizer
+from sma.ir.schema import Case
+from sma.match.engine import match_cases
+from sma.match.ses import self_score
+from sma.match.types import MatchConfig
+
+from .ann import AnnIndex
+from .content_vectors import functor_vector
+from .inverted import InvertedIndex
+
+
+@dataclass(frozen=True)
+class RetrievalResult:
+    case_id: str
+    ses_n: float
+    score: float
+    u_bound: float
+    certified: bool
+
+
+class MacFacIndex:
+    # Below this corpus size the admissible bound orders ALL candidates
+    # directly; above it the ANN cosine pre-screen trims first (scale only).
+    ANN_THRESHOLD = 20000
+
+    def __init__(self, config: MatchConfig | None = None, canon: Canonicalizer | None = None):
+        self.config = config or MatchConfig()
+        self.canon = canon or default_canonicalizer()
+        self.cases: dict[str, Case] = {}
+        self.ann = AnnIndex()
+        self.inverted = InvertedIndex()
+        self._score_cache: dict[tuple, tuple[float, float]] = {}
+
+    def add(self, case: Case) -> None:
+        vector = functor_vector(case, canon=self.canon, delta=self.config.delta)
+        self.cases[case.case_id] = case
+        self.ann.add(case.case_id, vector)
+        self.inverted.add(case.case_id, vector)
+        if self.config.functor_costs is not None:
+            # Corpus changed; surprisal costs and cached scores are stale.
+            self.config.functor_costs = None
+            self._score_cache.clear()
+
+    def build(self, cases: list[Case]) -> None:
+        for case in cases:
+            self.add(case)
+
+    def corpus_costs(self) -> dict[str, float]:
+        """Corpus surprisal (-log2 p, KT-smoothed) per canonical functor."""
+        import math
+        from collections import Counter
+
+        counts: Counter[str] = Counter()
+        for vector in self.inverted.vectors.values():
+            for feature, n in vector.items():
+                if feature.startswith("f:"):
+                    counts[feature[2:]] += n
+        total = sum(counts.values())
+        vocab = max(len(counts), 1)
+        return {
+            functor: -math.log2((count + 0.5) / (total + 0.5 * vocab))
+            for functor, count in counts.items()
+        }
+
+    def retrieve(
+        self, query: Case, k: int = 10, shortlist: int = 200, fac_budget: int | None = None
+    ) -> list[RetrievalResult]:
+        if self.config.scorer == "surprisal" and self.config.functor_costs is None:
+            # Lazily derive costs from the indexed corpus; deterministic given
+            # contents. Stale after add() — cleared there.
+            self.config.functor_costs = self.corpus_costs()
+        qvec = functor_vector(query, canon=self.canon, delta=self.config.delta)
+        bound_costs = self.config.functor_costs if self.config.scorer == "surprisal" else None
+        # Lemma 2: the weighted histogram-intersection bound IS the admissible
+        # MAC ordering. Up to ANN_THRESHOLD cases we bound-order everything
+        # directly (the Liberty haystack showed cosine pre-screening can drop
+        # the true positives the bound ordering ranks first); beyond it, the
+        # ANN cosine pre-screen trims the candidate set for tractability.
+        if len(self.cases) <= self.ANN_THRESHOLD:
+            candidate_ids = set(self.inverted.candidates(qvec))
+            if len(candidate_ids) < min(shortlist, len(self.cases)):
+                # Zero-overlap cases still belong in the candidate pool (bound
+                # 0, scored only if budget reaches them) so top-k cardinality
+                # matches brute force on tiny/disjoint corpora.
+                candidate_ids = set(self.cases)
+        else:
+            candidate_ids = {
+                case_id
+                for case_id, _ in self.ann.search(qvec, k=min(max(shortlist * 5, 1000), len(self.cases)))
+            }
+        bounded = [
+            (case_id, self.inverted.bound(qvec, case_id, max_score_per_mh=4.0, costs=bound_costs))
+            for case_id in candidate_ids
+        ]
+        bounded.sort(key=lambda row: (-row[1], row[0]))
+        bounded = bounded[: max(shortlist, 1)]
+        # ses_n = score / max(self(base), self(target)) <= U_bound / self(target),
+        # so dividing the raw-score bound by the query's self-score gives an
+        # admissible bound in ses_n units (weighted consistently for the
+        # surprisal scorer). The MDL scorer has no such bound, so it never
+        # early-stops on bounds (budget only).
+        ses_n_denom = None
+        if self.config.scorer in ("ses", "surprisal") and self.config.normalization != "min":
+            cost_fn = None
+            if bound_costs:
+                costs = bound_costs
+
+                def cost_fn(mh):
+                    from sma.ir.schema import Statement
+
+                    if isinstance(mh.base, Statement):
+                        return costs.get(self.canon.canonical(mh.base.functor), 1.0)
+                    return 1.0
+
+            ses_n_denom = max(self_score(query, gamma=self.config.gamma, cost_fn=cost_fn), 1e-9)
+        scored: list[tuple[str, float, float, float]] = []
+        kth_ses_n = float("-inf")
+        n_examined = 0
+        for case_id, bound in bounded:
+            if fac_budget is not None and n_examined >= fac_budget:
+                break
+            if (
+                ses_n_denom is not None
+                and len(scored) >= k
+                and bound / ses_n_denom < kth_ses_n
+            ):
+                break
+            score, ses_n = self._score_case(case_id, query)
+            scored.append((case_id, ses_n, score, bound))
+            n_examined += 1
+            if len(scored) >= k:
+                kth_ses_n = sorted(s[1] for s in scored)[-k]
+        # The top-k is certified exact over the shortlist iff no unexamined
+        # candidate's bound could still beat the k-th best ses_n.
+        remaining = bounded[n_examined:]
+        certified = not remaining or (
+            ses_n_denom is not None
+            and len(scored) >= k
+            and remaining[0][1] / ses_n_denom < kth_ses_n
+        )
+        scored.sort(key=lambda row: (-row[1], row[0]))
+        return [
+            RetrievalResult(case_id=cid, ses_n=ses_n, score=score, u_bound=bound, certified=certified)
+            for cid, ses_n, score, bound in scored[:k]
+        ]
+
+    def brute_force(self, query: Case, k: int = 10) -> list[RetrievalResult]:
+        qvec = functor_vector(query, canon=self.canon, delta=self.config.delta)
+        results: list[RetrievalResult] = []
+        for case_id, case in self.cases.items():
+            score, ses_n = self._score_case(case_id, query)
+            results.append(
+                RetrievalResult(
+                    case_id=case_id,
+                    ses_n=ses_n,
+                    score=score,
+                    u_bound=self.inverted.bound(qvec, case_id, max_score_per_mh=4.0),
+                    certified=True,
+                )
+            )
+        return sorted(results, key=lambda row: (-row.ses_n, row.case_id))[:k]
+
+    def _score_case(self, case_id: str, query: Case) -> tuple[float, float]:
+        key = (case_id, query.case_id, self.config.scorer, self.config.normalization)
+        if key not in self._score_cache:
+            gmap = match_cases(self.cases[case_id], query, config=self.config, canon=self.canon)
+            self._score_cache[key] = (gmap.score, gmap.normalized_score)
+        return self._score_cache[key]

sma/ir/__init__.py

@@ -0,0 +1,22 @@
+from .canon import Canonicalizer, PredicateLattice, default_canonicalizer
+from .schema import Case, Entity, Signature, Statement, SymbolKind, entity, make_case, stmt
+from .sexpr import canonical_case_text, dumps_statement, loads_case, loads_statement
+
+__all__ = [
+    "Canonicalizer",
+    "Case",
+    "Entity",
+    "PredicateLattice",
+    "Signature",
+    "Statement",
+    "SymbolKind",
+    "canonical_case_text",
+    "default_canonicalizer",
+    "dumps_statement",
+    "entity",
+    "loads_case",
+    "loads_statement",
+    "make_case",
+    "stmt",
+]
+

sma/ir/canon.py

@@ -0,0 +1,106 @@
+"""Symbolic canonicalization and minimal ascension support."""
+
+from __future__ import annotations
+
+from collections import deque
+from dataclasses import dataclass, field
+
+from .schema import safe_symbol
+
+
+@dataclass
+class PredicateLattice:
+    parents: dict[str, set[str]] = field(default_factory=dict)
+
+    def add(self, child: str, parent: str) -> None:
+        self.parents.setdefault(safe_symbol(child), set()).add(safe_symbol(parent))
+
+    def ancestors(self, symbol: str, max_depth: int = 2) -> dict[str, int]:
+        symbol = safe_symbol(symbol)
+        out = {symbol: 0}
+        queue = deque([(symbol, 0)])
+        while queue:
+            current, depth = queue.popleft()
+            if depth >= max_depth:
+                continue
+            for parent in self.parents.get(current, ()):
+                if parent not in out or depth + 1 < out[parent]:
+                    out[parent] = depth + 1
+                    queue.append((parent, depth + 1))
+        return out
+
+    def minimal_ascension(self, left: str, right: str, delta: int) -> tuple[str, int] | None:
+        left_anc = self.ancestors(left, delta)
+        right_anc = self.ancestors(right, delta)
+        overlap = set(left_anc).intersection(right_anc)
+        if not overlap:
+            return None
+        best = min(overlap, key=lambda s: (left_anc[s] + right_anc[s], s))
+        dist = left_anc[best] + right_anc[best]
+        if dist <= delta:
+            return best, dist
+        return None
+
+
+@dataclass
+class Canonicalizer:
+    aliases: dict[str, str] = field(default_factory=dict)
+    lattice: PredicateLattice = field(default_factory=PredicateLattice)
+
+    def canonical(self, symbol: str) -> str:
+        # NOTE: this used to strip "far_"/"near_" prefixes - a circularity
+        # with the old SSB generator (the benchmark's vocabulary bijection
+        # was known to the matcher). Removed: cross-vocabulary matching now
+        # goes exclusively through the lattice with ascension penalties.
+        symbol = safe_symbol(symbol)
+        seen: set[str] = set()
+        while symbol in self.aliases and symbol not in seen:
+            seen.add(symbol)
+            symbol = safe_symbol(self.aliases[symbol])
+        return symbol
+
+    def compatible(
+        self, left: str, right: str, delta: int = 0, rho: float = 1.0
+    ) -> tuple[bool, float, str | None, int]:
+        left_c = self.canonical(left)
+        right_c = self.canonical(right)
+        if left_c == right_c:
+            return True, 1.0, left_c, 0
+        if delta <= 0:
+            return False, 0.0, None, 0
+        asc = self.lattice.minimal_ascension(left_c, right_c, delta)
+        if asc is None:
+            return False, 0.0, None, 0
+        ancestor, dist = asc
+        return True, rho**dist, ancestor, dist
+
+
+def default_canonicalizer() -> Canonicalizer:
+    canon = Canonicalizer(
+        aliases={
+            "connTimeout": "timeout",
+            "connectionTimeout": "timeout",
+            "retryStorm": "retry",
+            "blockReceiveError": "ioError",
+            "pressure": "intensity",
+            "temperature": "intensity",
+            "waterFlow": "flow",
+            "heatFlow": "flow",
+            "sun": "centralBody",
+            "nucleus": "centralBody",
+            "planet": "orbitingBody",
+            "electron": "orbitingBody",
+            "attractsGravity": "attracts",
+            "attractsElectrostatic": "attracts",
+        }
+    )
+    for child, parent in (
+        ("timeout", "failureEvent"),
+        ("ioError", "failureEvent"),
+        ("exception", "failureEvent"),
+        ("retry", "recoveryAction"),
+        ("restart", "recoveryAction"),
+        ("saturation", "resourcePressure"),
+    ):
+        canon.lattice.add(child, parent)
+    return canon

sma/ir/schema.py

@@ -0,0 +1,165 @@
+"""Typed predicate IR for SMA cases.
+
+The implementation deliberately keeps the runtime representation small and
+serializable. It is immutable enough for hashing, but remains plain Python so
+fixtures and reports are easy to inspect.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any, Iterable, Mapping, Sequence
+
+import blake3
+
+
+class SymbolKind(str, Enum):
+    ENTITY = "entity"
+    FUNCTION = "function"
+    ATTRIBUTE = "attribute"
+    RELATION = "relation"
+
+
+@dataclass(frozen=True, slots=True)
+class Signature:
+    functor: str
+    arity: int
+    kind: SymbolKind = SymbolKind.RELATION
+    arg_types: tuple[str, ...] = ()
+    commutative: bool = False
+    higher_order: bool = False
+
+    def validate_arity(self, args: Sequence[Node]) -> None:
+        if len(args) != self.arity:
+            raise ValueError(f"{self.functor} expects {self.arity} args, got {len(args)}")
+
+
+@dataclass(frozen=True, slots=True)
+class Entity:
+    name: str
+    type: str = "entity"
+
+    def nodes(self) -> tuple[Entity, ...]:
+        return (self,)
+
+
+@dataclass(frozen=True, slots=True)
+class Statement:
+    functor: str
+    args: tuple["Node", ...] = ()
+    ascension: float = 1.0
+
+    def nodes(self) -> tuple["Node", ...]:
+        out: list[Node] = [self]
+        for arg in self.args:
+            out.extend(arg.nodes())
+        return tuple(out)
+
+    def expressions(self) -> tuple["Statement", ...]:
+        out: list[Statement] = [self]
+        for arg in self.args:
+            if isinstance(arg, Statement):
+                out.extend(arg.expressions())
+        return tuple(out)
+
+    def entities(self) -> tuple[Entity, ...]:
+        out: list[Entity] = []
+        for arg in self.args:
+            if isinstance(arg, Entity):
+                out.append(arg)
+            else:
+                out.extend(arg.entities())
+        return tuple(out)
+
+    @property
+    def arity(self) -> int:
+        return len(self.args)
+
+
+Node = Entity | Statement
+
+
+@dataclass(frozen=True, slots=True)
+class Case:
+    case_id: str
+    statements: tuple[Statement, ...]
+    metadata: Mapping[str, Any] = field(default_factory=dict)
+
+    def expressions(self) -> tuple[Statement, ...]:
+        seen: set[str] = set()
+        ordered: list[Statement] = []
+        from .sexpr import dumps_statement
+
+        for stmt in self.statements:
+            for expr in stmt.expressions():
+                key = dumps_statement(expr)
+                if key not in seen:
+                    seen.add(key)
+                    ordered.append(expr)
+        return tuple(ordered)
+
+    def entities(self) -> tuple[Entity, ...]:
+        seen: set[tuple[str, str]] = set()
+        ordered: list[Entity] = []
+        for stmt in self.statements:
+            for entity in stmt.entities():
+                key = (entity.name, entity.type)
+                if key not in seen:
+                    seen.add(key)
+                    ordered.append(entity)
+        return tuple(ordered)
+
+    def functor_counts(self) -> dict[str, int]:
+        counts: dict[str, int] = {}
+        for expr in self.expressions():
+            counts[expr.functor] = counts.get(expr.functor, 0) + 1
+        return counts
+
+
+def make_case(
+    statements: Iterable[Statement], metadata: Mapping[str, Any] | None = None, case_id: str = ""
+) -> Case:
+    from .sexpr import canonical_case_text
+
+    ordered = tuple(sorted(statements, key=lambda s: canonical_case_text([s])))
+    text = canonical_case_text(ordered)
+    return Case(case_id or content_id(text), ordered, dict(metadata or {}))
+
+
+def content_id(text: str) -> str:
+    # blake3 is a hard dependency: case ids are content addresses and must be
+    # identical across machines, so no fallback hash is allowed here.
+    return blake3.blake3(text.encode("utf-8")).hexdigest()
+
+
+def walk_statement(stmt: Statement) -> Iterable[Node]:
+    yield stmt
+    for arg in stmt.args:
+        if isinstance(arg, Statement):
+            yield from walk_statement(arg)
+        else:
+            yield arg
+
+
+def entity(name: str, type: str = "entity") -> Entity:
+    return Entity(name=safe_symbol(name), type=safe_symbol(type))
+
+
+def stmt(functor: str, *args: Node | str, ascension: float = 1.0) -> Statement:
+    coerced = tuple(arg if isinstance(arg, (Entity, Statement)) else entity(str(arg)) for arg in args)
+    return Statement(safe_symbol(functor), coerced, ascension=ascension)
+
+
+def safe_symbol(value: str) -> str:
+    value = str(value).strip()
+    if not value:
+        return "_"
+    out = []
+    for ch in value:
+        if ch.isalnum() or ch in "_-:.@/":
+            out.append(ch)
+        else:
+            out.append("_")
+    return "".join(out)
+