structuremappingmemory 1.0.0__py3-none-any.whl

sma/ir/sexpr.py

@@ -0,0 +1,86 @@
+"""Canonical S-expression codec for SMA cases."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+
+from .schema import Entity, Node, Statement, entity
+
+
+def dumps_node(node: Node) -> str:
+    if isinstance(node, Entity):
+        return node.name
+    return dumps_statement(node)
+
+
+def dumps_statement(statement: Statement) -> str:
+    if not statement.args:
+        return f"({statement.functor})"
+    args = " ".join(dumps_node(arg) for arg in statement.args)
+    return f"({statement.functor} {args})"
+
+
+def canonical_case_text(statements: Iterable[Statement]) -> str:
+    return "\n".join(sorted(dumps_statement(stmt) for stmt in statements))
+
+
+def loads_statement(text: str) -> Statement:
+    tokens = _tokenize(text)
+    node, pos = _parse(tokens, 0)
+    if pos != len(tokens):
+        raise ValueError(f"trailing tokens after S-expression: {tokens[pos:]}")
+    if not isinstance(node, Statement):
+        raise ValueError("top-level S-expression must be a statement")
+    return node
+
+
+def loads_case(text: str) -> tuple[Statement, ...]:
+    statements: list[Statement] = []
+    tokens = _tokenize(text)
+    pos = 0
+    while pos < len(tokens):
+        node, pos = _parse(tokens, pos)
+        if not isinstance(node, Statement):
+            raise ValueError("case entries must be statements")
+        statements.append(node)
+    return tuple(statements)
+
+
+def _tokenize(text: str) -> list[str]:
+    tokens: list[str] = []
+    token = []
+    for ch in text:
+        if ch in "()":
+            if token:
+                tokens.append("".join(token))
+                token = []
+            tokens.append(ch)
+        elif ch.isspace():
+            if token:
+                tokens.append("".join(token))
+                token = []
+        else:
+            token.append(ch)
+    if token:
+        tokens.append("".join(token))
+    return tokens
+
+
+def _parse(tokens: list[str], pos: int) -> tuple[Node, int]:
+    if pos >= len(tokens):
+        raise ValueError("unexpected end of input")
+    tok = tokens[pos]
+    if tok != "(":
+        return entity(tok), pos + 1
+    if pos + 1 >= len(tokens):
+        raise ValueError("missing functor")
+    functor = tokens[pos + 1]
+    args: list[Node] = []
+    pos += 2
+    while pos < len(tokens) and tokens[pos] != ")":
+        arg, pos = _parse(tokens, pos)
+        args.append(arg)
+    if pos >= len(tokens) or tokens[pos] != ")":
+        raise ValueError("unclosed statement")
+    return Statement(functor, tuple(args)), pos + 1
+

sma/ir/signatures.py

@@ -0,0 +1,76 @@
+"""Signature registry and type validation."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from .schema import Entity, Signature, Statement, SymbolKind
+
+
+DEFAULT_SIGNATURES = (
+    Signature("before", 2, higher_order=True),
+    Signature("after", 2, higher_order=True),
+    Signature("cause", 2, higher_order=True),
+    Signature("implies", 2, higher_order=True),
+    Signature("enables", 2, higher_order=True),
+    Signature("prevents", 2, higher_order=True),
+    Signature("during", 2, higher_order=True),
+    Signature("count", 2),
+    Signature("burst", 2),
+    Signature("frame", 4),
+    Signature("calledFrom", 2, higher_order=True),
+    Signature("defines", 2),
+    Signature("calls", 2),
+    Signature("imports", 2),
+    Signature("throws", 2),
+    Signature("catches", 2),
+    Signature("adds", 1),
+    Signature("removes", 1),
+    Signature("modifies", 1),
+)
+
+
+@dataclass
+class SignatureRegistry:
+    signatures: dict[str, Signature] = field(default_factory=dict)
+
+    @classmethod
+    def with_defaults(cls) -> "SignatureRegistry":
+        registry = cls()
+        for sig in DEFAULT_SIGNATURES:
+            registry.register(sig)
+        return registry
+
+    def register(self, signature: Signature) -> None:
+        self.signatures[signature.functor] = signature
+
+    def get(self, functor: str, arity: int | None = None) -> Signature:
+        if functor in self.signatures:
+            sig = self.signatures[functor]
+            if arity is not None and sig.arity != arity:
+                raise ValueError(f"{functor} registered with arity {sig.arity}, got {arity}")
+            return sig
+        return Signature(functor=functor, arity=arity if arity is not None else -1)
+
+    def validate_statement(self, statement: Statement) -> None:
+        sig = self.get(statement.functor, statement.arity)
+        if sig.arity >= 0:
+            sig.validate_arity(statement.args)
+        for arg in statement.args:
+            if isinstance(arg, Statement):
+                self.validate_statement(arg)
+            elif not isinstance(arg, Entity):
+                raise TypeError(f"unsupported argument node: {arg!r}")
+
+    def validate_case(self, statements: tuple[Statement, ...]) -> None:
+        for statement in statements:
+            self.validate_statement(statement)
+
+
+def infer_kind(functor: str, arity: int) -> SymbolKind:
+    if arity == 0:
+        return SymbolKind.ATTRIBUTE
+    if arity == 1:
+        return SymbolKind.ATTRIBUTE
+    return SymbolKind.RELATION
+

sma/match/__init__.py

@@ -0,0 +1,20 @@
+from .engine import match_cases
+from .explain import correspondence_table, explain_text
+from .infer import candidate_inferences
+from .types import CandidateInference, GMap, Kernel, MatchConfig, MatchHypothesis
+from .verifier import VerificationResult, verify_inference
+
+__all__ = [
+    "CandidateInference",
+    "GMap",
+    "Kernel",
+    "MatchConfig",
+    "MatchHypothesis",
+    "VerificationResult",
+    "candidate_inferences",
+    "correspondence_table",
+    "explain_text",
+    "match_cases",
+    "verify_inference",
+]
+

sma/match/conflicts.py

@@ -0,0 +1,46 @@
+"""Structural consistency checks and kernel conflict graph."""
+
+from __future__ import annotations
+
+from itertools import combinations
+
+from .types import Kernel, MatchHypothesis
+
+
+def structurally_consistent(hypotheses: tuple[MatchHypothesis, ...]) -> bool:
+    base_to_target: dict[str, str] = {}
+    target_to_base: dict[str, str] = {}
+    for mh in hypotheses:
+        if mh.base_key in base_to_target and base_to_target[mh.base_key] != mh.target_key:
+            return False
+        if mh.target_key in target_to_base and target_to_base[mh.target_key] != mh.base_key:
+            return False
+        base_to_target[mh.base_key] = mh.target_key
+        target_to_base[mh.target_key] = mh.base_key
+    return True
+
+
+def kernels_conflict(left: Kernel, right: Kernel) -> bool:
+    # Iterate over the smaller binding table; both tables are cached on the
+    # kernels, so each check is O(min(|left|, |right|)) hash probes.
+    if len(left.bindings) > len(right.bindings):
+        left, right = right, left
+    right_bindings = right.bindings
+    right_reverse = right.reverse_bindings
+    for b_key, t_key in left.bindings.items():
+        other_t = right_bindings.get(b_key)
+        if other_t is not None and other_t != t_key:
+            return True
+        other_b = right_reverse.get(t_key)
+        if other_b is not None and other_b != b_key:
+            return True
+    return False
+
+
+def conflict_edges(kernels: tuple[Kernel, ...]) -> set[tuple[int, int]]:
+    edges: set[tuple[int, int]] = set()
+    for i, j in combinations(range(len(kernels)), 2):
+        if kernels_conflict(kernels[i], kernels[j]):
+            edges.add((i, j))
+    return edges
+

sma/match/engine.py

@@ -0,0 +1,60 @@
+"""Top-level mapping engine."""
+
+from __future__ import annotations
+
+from sma.ir.canon import Canonicalizer, default_canonicalizer
+from sma.ir.schema import Case, Statement
+
+from .kernels import build_kernels
+from .mdl import mdl_gain
+from .merge_cpsat import exact_or_greedy_merge
+from .ses import normalize_score, structural_evaluation
+from .types import GMap, MatchConfig, MatchHypothesis
+
+
+def match_cases(
+    base: Case,
+    target: Case,
+    config: MatchConfig | None = None,
+    canon: Canonicalizer | None = None,
+) -> GMap:
+    config = config or MatchConfig()
+    canon = canon or default_canonicalizer()
+    cost_fn = None
+    if config.scorer == "surprisal" and config.functor_costs:
+        costs = config.functor_costs
+
+        def cost_fn(mh):
+            if isinstance(mh.base, Statement):
+                return costs.get(canon.canonical(mh.base.functor), 1.0)
+            return 1.0
+
+    kernels = build_kernels(base, target, config=config, canon=canon, cost_fn=cost_fn)
+    selected, gap = exact_or_greedy_merge(
+        kernels, exact_limit=config.exact_kernel_limit, time_budget_ms=config.cpsat_time_ms
+    )
+    unique: dict[tuple[str, str], MatchHypothesis] = {}
+    for kernel in selected:
+        for mh in kernel.hypotheses:
+            unique[mh.key] = mh
+    hypotheses = tuple(unique.values())
+    if config.scorer == "mdl":
+        score = mdl_gain(hypotheses, target)
+        normalized = score / max(len(target.expressions()), 1)
+    else:
+        score = structural_evaluation(hypotheses, gamma=config.gamma, cost_fn=cost_fn)
+        normalized = normalize_score(
+            score, base, target, gamma=config.gamma, cost_fn=cost_fn,
+            normalization=config.normalization,
+        )
+    return GMap(
+        base=base,
+        target=target,
+        hypotheses=hypotheses,
+        kernels=selected,
+        score=score,
+        normalized_score=normalized,
+        scorer=config.scorer,
+        optimality_gap=gap,
+    )
+

sma/match/explain.py

@@ -0,0 +1,59 @@
+"""Human-readable mapping explanations."""
+
+from __future__ import annotations
+
+from .types import GMap
+
+
+def correspondence_table(gmap: GMap) -> list[dict[str, str]]:
+    rows: list[dict[str, str]] = []
+    for mh in gmap.hypotheses:
+        rows.append(
+            {
+                "base": mh.base_key,
+                "target": mh.target_key,
+                "ascension": f"{mh.ascension:.3f}",
+                "ancestor": mh.ancestor or "",
+            }
+        )
+    return rows
+
+
+def explain_text(gmap: GMap) -> str:
+    lines = [
+        f"gmap score={gmap.score:.3f} SES_n={gmap.normalized_score:.3f} scorer={gmap.scorer}",
+        "correspondences:",
+    ]
+    for row in correspondence_table(gmap):
+        lines.append(f"- {row['base']} -> {row['target']} asc={row['ascension']} {row['ancestor']}")
+    return "\n".join(lines)
+
+
+
+def alignment_summary(gmap: GMap) -> str:
+    """One-line 'why this precedent matched' for verbalizers and evidence panels.
+
+    Aggregates matched statement-level correspondences by canonical functor so
+    an LLM (or human) sees the shared STRUCTURE (e.g. 'kernelEvent x4,
+    failureEvent x4, before x3') instead of re-deriving similarity from raw
+    text semantics.
+    """
+    from collections import Counter
+
+    from sma.ir.canon import default_canonicalizer
+    from sma.ir.schema import Statement
+
+    canon = default_canonicalizer()
+    matched: Counter[str] = Counter()
+    for mh in gmap.hypotheses:
+        if isinstance(mh.base, Statement):
+            functor = canon.canonical(mh.base.functor)
+            if functor != "logSession":
+                matched[functor] += 1
+    if not matched:
+        return "no statement-level correspondences"
+    parts = ", ".join(
+        f"{functor} x{count}" if count > 1 else functor
+        for functor, count in matched.most_common(6)
+    )
+    return f"shared structure: {parts}; ses_n={gmap.normalized_score:.2f}"

sma/match/infer.py

@@ -0,0 +1,54 @@
+"""Candidate inference projection."""
+
+from __future__ import annotations
+
+from sma.ir.schema import Entity, Node, Statement
+from sma.ir.sexpr import dumps_statement
+
+from .types import CandidateInference, GMap, node_key
+
+
+def candidate_inferences(gmap: GMap) -> tuple[CandidateInference, ...]:
+    base_to_target: dict[str, Node] = {mh.base_key: mh.target for mh in gmap.hypotheses}
+    mapped_statement_keys = {
+        mh.base_key for mh in gmap.hypotheses if isinstance(mh.base, Statement)
+    }
+    out: list[CandidateInference] = []
+    skolem_counter = 0
+
+    def project(node: Node) -> Node:
+        nonlocal skolem_counter
+        mapped = base_to_target.get(node_key(node))
+        if mapped is not None:
+            return mapped
+        if isinstance(node, Entity):
+            skolem_counter += 1
+            return Entity(f"AnalogySkolemFn_{skolem_counter}", node.type)
+        return Statement(node.functor, tuple(project(arg) for arg in node.args), ascension=node.ascension)
+
+    for statement in gmap.base.statements:
+        if node_key(statement) in mapped_statement_keys:
+            continue
+        if not any(node_key(entity) in base_to_target for entity in statement.entities()):
+            continue
+        skolem_counter = 0
+        projected = project(statement)
+        skolems = tuple(
+            entity.name for entity in projected.entities() if entity.name.startswith("AnalogySkolemFn_")
+        )
+        ascensions = tuple(
+            f"{mh.base_key}->{mh.ancestor}" for mh in gmap.hypotheses if mh.distance > 0 and mh.ancestor
+        )
+        out.append(
+            CandidateInference(
+                inference_sexpr=dumps_statement(projected),
+                base_case_id=gmap.base.case_id,
+                target_case_id=gmap.target.case_id,
+                ses_n=gmap.normalized_score,
+                support=tuple(sorted(mapped_statement_keys)),
+                skolems=skolems,
+                ascensions=ascensions,
+            )
+        )
+    return tuple(out)
+

sma/match/kernels.py

@@ -0,0 +1,54 @@
+"""Kernel construction."""
+
+from __future__ import annotations
+
+from sma.ir.canon import Canonicalizer, default_canonicalizer
+from sma.ir.schema import Case
+
+from sma.ir.schema import Statement
+
+from .conflicts import structurally_consistent
+from .mh import seed_expression_mhs, support_closure
+from .ses import structural_evaluation
+from .types import Kernel, MatchConfig, node_key
+
+
+def build_kernels(
+    base: Case,
+    target: Case,
+    config: MatchConfig | None = None,
+    canon: Canonicalizer | None = None,
+    cost_fn=None,
+) -> tuple[Kernel, ...]:
+    config = config or MatchConfig()
+    canon = canon or default_canonicalizer()
+    seeds = seed_expression_mhs(base.expressions(), target.expressions(), config=config, canon=canon)
+    # Root MHs only (blueprint section 2.2): a seed that appears as an argument
+    # pair of another seed is covered by its parent's support closure, so giving
+    # it its own kernel only inflates the merge problem.
+    child_keys: set[tuple[str, str]] = set()
+    for seed in seeds:
+        if isinstance(seed.base, Statement) and isinstance(seed.target, Statement):
+            for b_arg, t_arg in zip(seed.base.args, seed.target.args):
+                if isinstance(b_arg, Statement) and isinstance(t_arg, Statement):
+                    child_keys.add((node_key(b_arg), node_key(t_arg)))
+    kernels: list[Kernel] = []
+    seen: set[tuple[tuple[str, str], ...]] = set()
+    for seed in seeds:
+        if seed.key in child_keys:
+            continue
+        closure = support_closure(seed, canon=canon, delta=config.delta, rho=config.rho)
+        if closure is None:
+            # Root pairs unequal constants (e.g. different template-name
+            # entities under count): structurally impossible, discard.
+            continue
+        if not structurally_consistent(closure):
+            continue
+        key = tuple(sorted(mh.key for mh in closure))
+        if key in seen:
+            continue
+        seen.add(key)
+        weight = structural_evaluation(closure, gamma=config.gamma, cost_fn=cost_fn)
+        kernels.append(Kernel(seed, closure, weight=weight))
+    return tuple(kernels)
+

sma/match/mdl.py

@@ -0,0 +1,30 @@
+"""Parameter-free MDL-like scorer."""
+
+from __future__ import annotations
+
+import math
+from collections import Counter
+
+from sma.ir.schema import Case
+
+from .types import MatchHypothesis
+
+
+def corpus_functor_costs(cases: list[Case]) -> dict[str, float]:
+    counts: Counter[str] = Counter()
+    total = 0
+    for case in cases:
+        for functor, n in case.functor_counts().items():
+            counts[functor] += n
+            total += n
+    vocab = max(len(counts), 1)
+    return {functor: -math.log2((count + 0.5) / (total + 0.5 * vocab)) for functor, count in counts.items()}
+
+
+def mdl_gain(hypotheses: tuple[MatchHypothesis, ...], target: Case) -> float:
+    costs = corpus_functor_costs([target])
+    matched_target_exprs = {
+        mh.target.functor for mh in hypotheses if hasattr(mh.target, "functor")
+    }
+    return sum(costs.get(functor, 1.0) for functor in matched_target_exprs)
+

sma/match/merge_cpsat.py

@@ -0,0 +1,77 @@
+"""Exact-anytime MWIS merge using Google OR-Tools CP-SAT solver."""
+
+from __future__ import annotations
+
+from .conflicts import conflict_edges
+from .merge_greedy import greedy_merge
+from .types import Kernel
+
+try:
+    from ortools.sat.python import cp_model
+except ImportError:  # pragma: no cover - ortools is a hard dependency in pyproject
+    cp_model = None
+
+# Brute-force enumeration cap when ortools is unavailable (2^12 masks max).
+_BRUTE_FORCE_LIMIT = 12
+
+
+def exact_or_greedy_merge(
+    kernels: tuple[Kernel, ...],
+    exact_limit: int = 60,
+    time_budget_ms: int = 20,
+) -> tuple[tuple[Kernel, ...], float | None]:
+    """Select a maximum-weight independent set of kernels.
+
+    Returns (selected kernels, optimality gap). Gap 0.0 means certified
+    optimal; None means the greedy/anytime fallback was used without a
+    certificate.
+    """
+    if not kernels:
+        return (), 0.0
+
+    # Greedy is the published O(n^2 log n) fallback; use it directly when the
+    # MIP model would cost more than it buys (large conflict-kernel counts).
+    if len(kernels) > exact_limit:
+        return greedy_merge(kernels), None
+
+    edges = conflict_edges(kernels)
+
+    if cp_model is not None:
+        model = cp_model.CpModel()
+        n = len(kernels)
+        x = [model.NewBoolVar(f"x_{i}") for i in range(n)]
+        for i, j in edges:
+            model.Add(x[i] + x[j] <= 1)
+        # CP-SAT needs integer weights; 1e5 scaling keeps 5 decimal places.
+        scaled_weights = [int(round(max(k.weight, 0.0) * 100000)) for k in kernels]
+        model.Maximize(sum(scaled_weights[i] * x[i] for i in range(n)))
+
+        solver = cp_model.CpSolver()
+        solver.parameters.max_time_in_seconds = time_budget_ms / 1000.0
+        status = solver.Solve(model)
+        if status in (cp_model.OPTIMAL, cp_model.FEASIBLE):
+            selected = tuple(kernels[i] for i in range(n) if solver.Value(x[i]))
+            gap = 0.0 if status == cp_model.OPTIMAL else None
+            return selected, gap
+        return greedy_merge(kernels), None
+
+    # No ortools: exact enumeration for tiny instances, greedy otherwise.
+    n = len(kernels)
+    if n > _BRUTE_FORCE_LIMIT:
+        return greedy_merge(kernels), None
+    best_mask = 0
+    best_weight = float("-inf")
+    for mask in range(1 << n):
+        ok = True
+        for i, j in edges:
+            if (mask & (1 << i)) and (mask & (1 << j)):
+                ok = False
+                break
+        if not ok:
+            continue
+        weight = sum(kernels[i].weight for i in range(n) if mask & (1 << i))
+        if weight > best_weight:
+            best_weight = weight
+            best_mask = mask
+    selected = tuple(kernels[i] for i in range(n) if best_mask & (1 << i))
+    return selected, 0.0

sma/match/merge_greedy.py

@@ -0,0 +1,15 @@
+"""Published-style greedy kernel merge fallback."""
+
+from __future__ import annotations
+
+from .conflicts import kernels_conflict
+from .types import Kernel
+
+
+def greedy_merge(kernels: tuple[Kernel, ...]) -> tuple[Kernel, ...]:
+    selected: list[Kernel] = []
+    for kernel in sorted(kernels, key=lambda k: (-k.weight, k.root.base_key, k.root.target_key)):
+        if all(not kernels_conflict(kernel, existing) for existing in selected):
+            selected.append(kernel)
+    return tuple(selected)
+