unicode-logic-kit 0.31.0__py3-none-any.whl

unicode_logic_kit/drt/resolve.py

@@ -0,0 +1,195 @@
+"""Accessibility-respecting pronoun resolution (unicode_logic_kit.drt.resolve).
+
+This is explicitly NOT an NLP guesser: it has no gender/number agreement, no world
+knowledge, and no salience model. What it DOES do — and does precisely — is apply the
+classical Kamp/Reyle DISCOURSE STRUCTURE constraint on pronoun resolution: a pronoun can
+only corefer with a referent that is ACCESSIBLE to it (see the accessibility relation in
+:mod:`unicode_logic_kit.drt.nodes`'s module docstring), and among the accessible candidates,
+the "closest" one is preferred — the classical RIGHT-TO-LEFT (most recently mentioned)
+default reading.
+
+Marking a pronoun
+------------------
+The caller marks a referent as an unresolved pronoun with the reserved unary condition
+``Pred(PRONOUN, (ref,))`` (``PRONOUN = "PRONOUN"``), placed in the SAME box that declares
+``ref`` — exactly like any other condition, using the ordinary five-variant condition
+vocabulary from :mod:`unicode_logic_kit.drt.nodes` (no sixth "Condition" subtype is added
+for this — a reserved predicate name is enough and keeps the classical Kamp/Reyle
+condition inventory exactly as-is). :func:`resolve_anaphora` finds every such marker
+(or just the ones named in ``pronouns``, if given) and REPLACES it with
+``Eq(ref, antecedent)`` — ``ref`` stays a bound referent in its box (so the standard
+translation in :mod:`unicode_logic_kit.drt.export` still existentially/universally quantifies
+it, exactly as any other referent), and the added equality forces it to denote the same
+individual as its antecedent once translated to FOL.
+
+Recency ranking
+------------------
+:func:`~unicode_logic_kit.drt.nodes.walk_boxes` gives each box its accessible referents as an
+ORDERED sequence of "layers", outermost first, the box's own referents last. A candidate's
+recency rank is ``(layer_index, position_within_that_layer)`` — read: prefer the INNERMOST
+layer (the pronoun's own box beats an ancestor's, which beats a more distant ancestor's);
+within one layer (one box's own referents tuple), prefer the LATER position (the rightmost,
+i.e. most recently written, referent in that box's own list). This is a total order with no
+ties possible (two distinct referents can never share both coordinates), so "most recent"
+always has a single well-defined answer whenever there is at least one candidate — see
+"Ambiguity policy" below for what "ambiguous" means instead. Note that within a single box,
+EVERY other referent in that box counts as a same-layer candidate regardless of whether it
+was written before or after the pronoun in that box's referent tuple — DRT's own theory
+treats a box's referents as an unordered set, so intra-box "before/after" is not a
+structural distinction; only the WRITTEN tuple position (used purely as a tie-break, not as
+an accessibility criterion) makes recency well-defined at that granularity.
+
+Ambiguity policy
+-------------------
+* Zero accessible candidates: always :class:`ValueError` (there is nothing to resolve to,
+  strict or not).
+* Exactly one accessible candidate: resolved automatically, regardless of ``strict`` — this
+  is the unambiguous case, no heuristic guessing involved.
+* Two or more accessible candidates: this module will not silently pick one FOR you (it is
+  not a guesser) — with ``strict=True`` (the default) it raises :class:`ValueError` listing
+  every candidate, most-recent first, so the caller can disambiguate explicitly. With
+  ``strict=False`` it accepts the recency heuristic above and records which referent it
+  picked (:attr:`Resolution.ambiguous` is ``True`` in this case, so the choice is always
+  visible in the returned report, never silently made).
+"""
+
+from dataclasses import dataclass
+from typing import Dict, Optional, Sequence, Tuple
+
+from .nodes import DRS, Pred, Eq, Neg, Impl, Or, walk_boxes
+
+__all__ = ["PRONOUN", "Resolution", "ResolutionReport", "resolve_anaphora"]
+
+PRONOUN = "PRONOUN"
+
+
+@dataclass(frozen=True)
+class Resolution:
+    """The outcome of resolving one pronoun.
+
+    ``candidates`` lists every accessible referent that was considered, MOST RECENT
+    FIRST (so ``candidates[0] == antecedent`` always); ``ambiguous`` is True iff there
+    was more than one (i.e. ``antecedent`` was chosen by the recency heuristic rather
+    than being the sole option).
+    """
+
+    referent: str
+    antecedent: str
+    candidates: Tuple[str, ...]
+    ambiguous: bool
+
+    def to_dict(self) -> dict:
+        return {"referent": self.referent, "antecedent": self.antecedent,
+                "candidates": list(self.candidates), "ambiguous": self.ambiguous}
+
+
+@dataclass(frozen=True)
+class ResolutionReport:
+    """The result of :func:`resolve_anaphora`: the resolved DRS (every processed
+    ``PRONOUN`` marker replaced by an ``Eq``) plus one :class:`Resolution` per pronoun,
+    in the order they were resolved."""
+
+    drs: DRS
+    resolutions: Tuple[Resolution, ...]
+
+    def to_dict(self) -> dict:
+        return {"drs": self.drs.to_dict(),
+                "resolutions": [r.to_dict() for r in self.resolutions]}
+
+
+def _recency_sorted_candidates(layers, pronoun: str):
+    """Every OTHER referent visible in ``layers``, most-recent-first (see the module
+    docstring's recency ranking)."""
+    ranked = []
+    for i, layer in enumerate(layers):
+        for j, name in enumerate(layer):
+            if name != pronoun:
+                ranked.append((i, j, name))
+    ranked.sort(key=lambda t: (t[0], t[1]), reverse=True)
+    return tuple(name for _, _, name in ranked)
+
+
+def _replace_markers(box: DRS, replacements: Dict[str, Eq]) -> DRS:
+    """Rebuild ``box`` with every resolved ``PRONOUN`` marker condition replaced by its
+    ``Eq``, recursing into every nested sub-DRS (Neg/Impl/Or operands)."""
+    new_conditions = []
+    for cond in box.conditions:
+        if (isinstance(cond, Pred) and cond.name == PRONOUN
+                and cond.args[0] in replacements):
+            new_conditions.append(replacements[cond.args[0]])
+        elif isinstance(cond, Neg):
+            new_conditions.append(Neg(_replace_markers(cond.drs, replacements)))
+        elif isinstance(cond, Impl):
+            new_conditions.append(Impl(_replace_markers(cond.antecedent, replacements),
+                                       _replace_markers(cond.consequent, replacements)))
+        elif isinstance(cond, Or):
+            new_conditions.append(Or(_replace_markers(cond.left, replacements),
+                                     _replace_markers(cond.right, replacements)))
+        else:
+            new_conditions.append(cond)
+    return DRS(box.referents, tuple(new_conditions))
+
+
+def resolve_anaphora(drs: DRS, pronouns: Optional[Sequence[str]] = None, *,
+                     strict: bool = True) -> ResolutionReport:
+    """Resolve every ``PRONOUN``-marked referent in ``drs`` (see the module docstring).
+
+    ``drs.validate()`` is called first (a pronoun's antecedent search is only meaningful
+    over an already-accessibility-valid tree). ``pronouns``, if given, restricts
+    resolution to those referent names (each MUST carry a ``Pred(PRONOUN, (ref,))``
+    marker somewhere in ``drs``, else :class:`ValueError`); ``None`` (the default)
+    resolves every marker found, in the order :func:`~unicode_logic_kit.drt.nodes.walk_boxes`
+    discovers them (pre-order, deterministic).
+
+    Raises:
+        ValueError: a named pronoun has no marker; a pronoun has zero accessible
+            candidates; or (with ``strict=True``, the default) a pronoun has two or more
+            accessible candidates (message lists them, most recent first).
+    """
+    drs.validate()
+    boxes = list(walk_boxes(drs))
+
+    marker_boxes: Dict[str, tuple] = {}
+    for box, layers in boxes:
+        for cond in box.conditions:
+            if isinstance(cond, Pred) and cond.name == PRONOUN:
+                if len(cond.args) != 1:
+                    raise ValueError(
+                        f"resolve_anaphora: a {PRONOUN} marker must have exactly one "
+                        f"argument, got {cond.args!r}")
+                ref = cond.args[0]
+                if ref in marker_boxes:
+                    raise ValueError(
+                        f"resolve_anaphora: referent {ref!r} has more than one "
+                        f"{PRONOUN} marker")
+                marker_boxes[ref] = (box, layers)
+
+    if pronouns is None:
+        targets = list(marker_boxes)
+    else:
+        targets = list(pronouns)
+        for p in targets:
+            if p not in marker_boxes:
+                raise ValueError(
+                    f"resolve_anaphora: no {PRONOUN} marker found for referent {p!r}")
+
+    resolutions = []
+    replacements: Dict[str, Eq] = {}
+    for p in targets:
+        box, layers = marker_boxes[p]
+        candidates = _recency_sorted_candidates(layers, p)
+        if not candidates:
+            raise ValueError(
+                f"resolve_anaphora: pronoun {p!r} has no accessible referent to bind to.")
+        ambiguous = len(candidates) > 1
+        if ambiguous and strict:
+            raise ValueError(
+                f"resolve_anaphora: pronoun {p!r} has {len(candidates)} accessible "
+                f"candidates {candidates} (most recent first) — ambiguous under "
+                f"strict=True. Pass strict=False to accept the most-recent heuristic, "
+                f"or disambiguate by hand.")
+        antecedent = candidates[0]
+        resolutions.append(Resolution(p, antecedent, candidates, ambiguous))
+        replacements[p] = Eq(p, antecedent)
+
+    return ResolutionReport(_replace_markers(drs, replacements), tuple(resolutions))

unicode_logic_kit/drt/reverse.py

@@ -0,0 +1,175 @@
+"""FOL → DRS (``fol_to_drs``): the standard translation, run backwards.
+
+:func:`unicode_logic_kit.drt.export.drs_to_fol` maps every DRS onto a
+first-order formula of a very particular SHAPE — outer ∃-chains for boxes,
+``∀-chain(antecedent → ∃-chain consequent)`` for duplex conditions,
+``¬∃-chain`` for negations, counting quantifiers over ``Part_of`` for
+``Card``. This module recognizes exactly that image and rebuilds the box
+structure; everything outside it is refused by name
+(:class:`FolToDrsError`), never approximated:
+
+- modal/temporal/second-order operators — no classical DRS holds them
+  (the ACE formula route exists precisely because of that);
+- a bare universal without an implication body — no box exports to it;
+- a counting quantifier whose matrix is not ``Part_of(v, g)`` — that is
+  the FORMULA-level counting reading (``∃=2 x (Dog(x) ∧ …)``), which is
+  strictly more expressive than a ``Card`` condition;
+- function or number terms in argument positions, and free variables
+  (caught by ``DRS.validate`` — an undeclared referent is exactly what a
+  free variable becomes).
+
+Two deliberate canonicalizations, both semantically invisible:
+``Part_of(a, b)`` atoms come back as the typed ``Part`` condition (the
+two export identically), and a strict ``Card`` bound that was shifted on
+export returns in shifted form (``Card(g, >, 2)`` exports as ``∃≥3`` and
+reads back as ``Card(g, >=, 3)`` — the same claim over natural counts).
+The inverse property the tests pin is therefore at the FORMULA level:
+``drs_to_fol(fol_to_drs(f)) == f`` node-identically for every ``f`` in
+the export's image, and Z3-equivalent to the originating DRS.
+
+The practical use is the ACE chain: ``formula_to_ace`` =
+:func:`~unicode_logic_kit.ace.verbalize.drs_to_ace` ∘ ``fol_to_drs`` — "is
+this formula expressible as ACE?" becomes two refusal-checked steps with
+the round trip as the safety net.
+"""
+
+from __future__ import annotations
+
+from typing import List, Tuple
+
+from ..fol.nodes import (
+    And, Atom, Constant, Count, Implies, Node, Not, Number, Or as FolOr,
+    Quantifier, Variable,
+)
+from .nodes import DRS, Card, Condition, Eq, Impl, Neg, Or, Part, Pred
+
+__all__ = ["fol_to_drs", "FolToDrsError"]
+
+
+class FolToDrsError(ValueError):
+    """The formula lies outside the image of the standard translation."""
+
+
+_COUNT_TO_CARD = {"ge": ">=", "le": "<=", "eq": "="}
+
+
+def fol_to_drs(formula: Node) -> DRS:
+    """Rebuild the DRS a formula is the standard translation of.
+
+    Refuses (:class:`FolToDrsError`) anything outside
+    :func:`~unicode_logic_kit.drt.export.drs_to_fol`'s image — see the
+    module docstring for the exact boundary and the two canonicalizations.
+    The result always passes ``DRS.validate``.
+    """
+    drs = _box(formula)
+    try:
+        drs.validate()
+    except ValueError as exc:
+        raise FolToDrsError(
+            f"fol_to_drs: the rebuilt DRS fails validation — usually a "
+            f"free variable in the input formula ({exc})") from exc
+    return drs
+
+
+def _box(formula: Node) -> DRS:
+    refs: List[str] = []
+    while isinstance(formula, Quantifier) and formula.type == "∃":
+        refs.append(formula.variable.name)
+        formula = formula.formula
+    conditions = tuple(_condition(c) for c in _conjuncts(formula))
+    try:
+        return DRS(tuple(refs), conditions)
+    except ValueError as exc:
+        raise FolToDrsError(f"fol_to_drs: {exc}") from exc
+
+
+def _conjuncts(formula: Node) -> List[Node]:
+    if isinstance(formula, And):
+        return _conjuncts(formula.left) + _conjuncts(formula.right)
+    return [formula]
+
+
+def _condition(formula: Node) -> Condition:
+    if isinstance(formula, Atom):
+        return _atom_condition(formula)
+    if isinstance(formula, Count):
+        return _card_condition(formula)
+    if isinstance(formula, Not):
+        return Neg(_box(formula.formula))
+    if isinstance(formula, FolOr):
+        return Or(_box(formula.left), _box(formula.right))
+    if isinstance(formula, Quantifier) and formula.type == "∀":
+        return _duplex_condition(formula)
+    if isinstance(formula, Quantifier):
+        # A ∃ HERE (not in an outer chain) means the input associated its
+        # conjunction around it — ∃x P ∧ Q is not a box shape the export
+        # produces (it puts every ∃ in front of its whole box).
+        raise FolToDrsError(
+            "fol_to_drs: an existential inside a conjunct — the export "
+            "always lifts ∃ in front of its whole box, so this formula is "
+            "not in its image")
+    raise FolToDrsError(
+        f"fol_to_drs: {type(formula).__name__} has no classical DRS "
+        "condition — outside the standard translation's image")
+
+
+def _atom_condition(atom: Atom) -> Condition:
+    args = tuple(_term_name(t) for t in atom.args)
+    try:
+        if atom.predicate == "=" and len(args) == 2:
+            return Eq(args[0], args[1])
+        if atom.predicate == "Part_of" and len(args) == 2:
+            # Canonicalization: the typed Part condition and a plain
+            # Part_of atom export identically; the typed form wins.
+            return Part(args[0], args[1])
+        return Pred(atom.predicate, args)
+    except ValueError as exc:
+        raise FolToDrsError(f"fol_to_drs: {exc}") from exc
+
+
+def _card_condition(count: Count) -> Condition:
+    body = count.formula
+    if not (isinstance(body, Atom) and body.predicate == "Part_of"
+            and len(body.args) == 2
+            and isinstance(body.args[0], Variable)
+            and body.args[0].name == count.variable.name):
+        raise FolToDrsError(
+            "fol_to_drs: a counting quantifier whose matrix is not "
+            "Part_of(v, g) is the FORMULA-level counting reading — "
+            "strictly more expressive than a Card condition, no DRS image")
+    group = _term_name(body.args[1])
+    try:
+        return Card(group, _COUNT_TO_CARD[count.op], count.n.value)
+    except ValueError as exc:
+        raise FolToDrsError(f"fol_to_drs: {exc}") from exc
+
+
+def _duplex_condition(formula: Node) -> Condition:
+    refs: List[str] = []
+    while isinstance(formula, Quantifier) and formula.type == "∀":
+        refs.append(formula.variable.name)
+        formula = formula.formula
+    if not isinstance(formula, Implies):
+        raise FolToDrsError(
+            f"fol_to_drs: a universal without an implication body (got "
+            f"{type(formula).__name__}) — no box exports to ∀ without →, "
+            "so this formula is not in the standard translation's image")
+    antecedent_conds = tuple(_condition(c) for c in _conjuncts(formula.left))
+    try:
+        antecedent = DRS(tuple(refs), antecedent_conds)
+    except ValueError as exc:
+        raise FolToDrsError(f"fol_to_drs: {exc}") from exc
+    return Impl(antecedent, _box(formula.right))
+
+
+def _term_name(term: Node) -> str:
+    if isinstance(term, (Variable, Constant)):
+        return term.name
+    if isinstance(term, Number):
+        raise FolToDrsError(
+            "fol_to_drs: a number in argument position — DRS conditions "
+            "take referents and constants only (values travel as c_ "
+            "constants, e.g. c_30)")
+    raise FolToDrsError(
+        f"fol_to_drs: a {type(term).__name__} term in argument position — "
+        "DRS conditions take referents and constants only")

unicode_logic_kit/eval/__init__.py

@@ -0,0 +1,106 @@
+"""Evaluation utilities for NL→FOL work.
+
+- :func:`canonicalize` puts a formula into a normal form that quotients out
+  bound-variable renaming, commutativity/associativity of the commutative
+  connectives, operand duplication, and double negation — while staying
+  logically equivalent. :func:`exact_match` uses it for a fair "canonical exact
+  match" that is stricter than logical equivalence but more forgiving than raw
+  string/structural equality.
+- :func:`validate` / :func:`is_wellformed` / :func:`validate_text` report the
+  common defects in a generated formula (free variables, inconsistent predicate
+  or function arity, leftover lambda nodes, unparseable text).
+- :func:`match_predicates` / :func:`formulas_are_matched_identical` /
+  :func:`formulas_are_identical` provide a lexical, predicate-aligned string
+  match (Levenshtein-based predicate renaming) — complementary to the AST-level
+  :func:`exact_match`, which instead quotients out the structural rewrites.
+- :func:`align_symbols` / :func:`aligned_exact_match` are the parsed-AST
+  counterpart of the lexical matcher: separate predicate/function/constant
+  namespaces, arity-aware, injective and capture-free — combined with
+  :func:`exact_match` they quotient out BOTH vocabulary and structural noise.
+- :func:`explain_countermodel` renders any countermodel witness (Kripke,
+  Tarski structure, Z3 assignment, Verdict-layer dict) as a few short,
+  deterministic English sentences; :func:`explain_proof` is its validity-side
+  counterpart, rendering a recorded proof object (tableau, TSTP derivation,
+  Twee proof, Z3 unsat core, cvc5 Alethe proof) the same way.
+- :func:`~unicode_logic_kit.eval.converses.validate_converses` /
+  :func:`~unicode_logic_kit.eval.converses.converse_axioms` let a caller declare
+  that two predicates name the same relation with their arguments permuted
+  (:data:`~unicode_logic_kit.eval.converses.ConverseDeclaration`), an opt-in
+  bridge consumed only by :func:`equivalent`'s solver level.
+- :func:`batch_decide` runs the prover chain over many formulas with a
+  content-addressed cache, process parallelism, and JSONL results.
+- :mod:`~unicode_logic_kit.eval.datasets` holds the NL→logic benchmark
+  adapters (FOLIO, MALLS, …) with a shared example shape and gold-formula
+  self-audit.
+"""
+
+from .canonical import canonicalize, exact_match
+from .validate import validate, is_wellformed, validate_text, ValidationReport
+from .predicate_match import (
+    formulas_are_identical,
+    match_predicates,
+    formulas_are_matched_identical,
+    align_symbols,
+    aligned_exact_match,
+)
+from .equivalence import EquivalenceResult, equivalent
+from .explain import explain_countermodel, explain_proof
+from .metric_hf import compute_fol_metrics
+from .converses import ConverseDeclaration, validate_converses, converse_axioms
+from .theory_check import (
+    Definitions, CyclicDefinition, UnfoldDepthExceeded,
+    dependency_graph, find_cycles, unfold,
+    SatisfiabilityResult, check_satisfiable,
+    SubsumptionResult, check_subsumption,
+    TheoryReport, check_theory,
+)
+from .generality import (
+    MinimalModelResult, minimal_model_size,
+    GeneralityReport, generality_report,
+    StrictlyStrongerResult, strictly_stronger,
+    VacuousSpecialisationResult, is_vacuous_specialisation,
+)
+from .batch import batch_decide
+from .chem_batch import check_definitions, ChemBatchResult
+from .exercise_gen import (
+    ValidInvalidPair, generate_valid_invalid_pair,
+    EntailmentExercise, generate_entailment_with_proof,
+    ModelSizeExercise, generate_theory_with_model_size,
+)
+from . import datasets   # NL→logic benchmark adapters (datasets.load_folio, …)
+
+__all__ = [
+    "check_definitions", "ChemBatchResult",
+    "canonicalize", "exact_match",
+    "validate", "is_wellformed", "validate_text", "ValidationReport",
+    "formulas_are_identical", "match_predicates", "formulas_are_matched_identical",
+    "align_symbols", "aligned_exact_match",
+    "EquivalenceResult", "equivalent",
+    "explain_countermodel", "explain_proof",
+    "compute_fol_metrics",
+    # Declared converse/argument-permutation axioms — an opt-in equivalence
+    # bridge consumed only by `equivalent`'s solver level (see
+    # unicode_logic_kit.eval.converses).
+    "ConverseDeclaration", "validate_converses", "converse_axioms",
+    # Deductive checks over a set of predicate DEFINITIONS: cycles, dead
+    # (unsatisfiable) definitions, subclass ⊨ superclass — with a
+    # countermodel whenever the answer is "no", not just "not proved".
+    "Definitions", "CyclicDefinition", "UnfoldDepthExceeded",
+    "dependency_graph", "find_cycles", "unfold",
+    "SatisfiabilityResult", "check_satisfiable",
+    "SubsumptionResult", "check_subsumption",
+    "TheoryReport", "check_theory",
+    # Logical generality analysis — how easily is a definition satisfied,
+    # and does a "specialisation" actually specialise anything?
+    "MinimalModelResult", "minimal_model_size",
+    "GeneralityReport", "generality_report",
+    "StrictlyStrongerResult", "strictly_stronger",
+    "VacuousSpecialisationResult", "is_vacuous_specialisation",
+    "batch_decide",
+    # Constructively-generated, independently-checked practice exercises --
+    # no LLM anywhere (unicode_logic_kit.eval.exercise_gen).
+    "ValidInvalidPair", "generate_valid_invalid_pair",
+    "EntailmentExercise", "generate_entailment_with_proof",
+    "ModelSizeExercise", "generate_theory_with_model_size",
+    "datasets",
+]