boolean-algebra-engine 0.1.0__py3-none-any.whl

core/synthesizer.py

@@ -0,0 +1,167 @@
+"""
+core/synthesizer.py — minimal expression synthesis via Quine-McCluskey.
+
+Public API:
+  synthesize(truth_table) → (str, PerformanceMetrics)
+
+The inverse of evaluate(): given a TruthTable, returns the minimal sum-of-
+products boolean expression that produces it. Uses the Quine-McCluskey
+algorithm: iteratively merge minterms that differ by one bit to find prime
+implicants, then select the minimum cover using essential prime implicants
+first, greedy cover for the remainder.
+
+Special cases:
+  No minterms (contradiction) → '0'
+  All minterms (tautology)    → '1'
+"""
+from __future__ import annotations
+import time
+import tracemalloc
+from .models import TruthTable, PerformanceMetrics
+
+
+def _can_merge(a: str, b: str) -> tuple[bool, str]:
+    """Return (True, merged) if two implicants differ in exactly one non-dash bit."""
+    diff_count = 0
+    diff_pos = -1
+    for i, (x, y) in enumerate(zip(a, b)):
+        if x != y:
+            if x == '-' or y == '-':
+                return False, ''
+            diff_count += 1
+            diff_pos = i
+            if diff_count > 1:
+                return False, ''
+    if diff_count == 1:
+        result = list(a)
+        result[diff_pos] = '-'
+        return True, ''.join(result)
+    return False, ''
+
+
+def _covers(implicant: str, minterm: int, n: int) -> bool:
+    """Return True if an implicant pattern covers a given minterm index."""
+    bits = format(minterm, f'0{n}b')
+    return all(p == '-' or p == b for p, b in zip(implicant, bits))
+
+
+def _minimum_cover(prime_implicants: list[str], minterms: list[int], n: int) -> list[str]:
+    """Select the minimum set of prime implicants that covers all minterms."""
+    coverage = {pi: {m for m in minterms if _covers(pi, m, n)} for pi in prime_implicants}
+    selected = []
+    covered = set()
+
+    for m in minterms:
+        covering = [pi for pi in prime_implicants if m in coverage[pi]]
+        if len(covering) == 1 and covering[0] not in selected:
+            selected.append(covering[0])
+            covered |= coverage[covering[0]]
+
+    remaining = set(minterms) - covered
+    while remaining:
+        best = max(
+            (pi for pi in prime_implicants if pi not in selected),
+            key=lambda pi: len(coverage[pi] & remaining),
+            default=None,
+        )
+        if best is None:
+            break
+        selected.append(best)
+        covered |= coverage[best]
+        remaining -= coverage[best]
+
+    return selected
+
+
+def _pi_to_expr(pi: str, variables: list[str]) -> str:
+    """Convert a prime implicant bit pattern to a boolean product term string."""
+    terms = []
+    for bit, var in zip(pi, variables):
+        if bit == '1':
+            terms.append(var)
+        elif bit == '0':
+            terms.append(f'!{var}')
+    return '.'.join(terms) if terms else '1'
+
+
+def synthesize(truth_table: TruthTable) -> tuple[str, PerformanceMetrics]:
+    """
+    Synthesize the minimal boolean expression for a given truth table.
+
+    Uses Quine-McCluskey to find all prime implicants, then selects the
+    minimum cover — essential prime implicants first, greedy for the rest.
+
+    Args:
+        truth_table: A TruthTable returned by evaluate().
+
+    Returns:
+        (expression, PerformanceMetrics) — minimal SOP expression string
+        and timing/memory data. Returns '0' for contradictions, '1' for
+        tautologies.
+
+    Example:
+        table, _ = evaluate('A.B+A.!B')
+        expr, metrics = synthesize(table)
+        print(expr)                          # 'A'
+        print(metrics.prime_implicant_count) # 1
+    """
+    minterms = truth_table.minterms
+    variables = truth_table.variables
+    n = len(variables)
+
+    tracemalloc.start()
+    t_start = time.perf_counter()
+
+    if not minterms:
+        synth_time_ms = (time.perf_counter() - t_start) * 1000
+        _, peak = tracemalloc.get_traced_memory()
+        tracemalloc.stop()
+        return '0', PerformanceMetrics(synth_time_ms=round(synth_time_ms, 4), peak_memory_bytes=peak, prime_implicant_count=0)
+
+    if len(minterms) == 2 ** n:
+        synth_time_ms = (time.perf_counter() - t_start) * 1000
+        _, peak = tracemalloc.get_traced_memory()
+        tracemalloc.stop()
+        return '1', PerformanceMetrics(synth_time_ms=round(synth_time_ms, 4), peak_memory_bytes=peak, prime_implicant_count=0)
+
+    current: dict[str, set[int]] = {format(m, f'0{n}b'): {m} for m in minterms}
+    prime_implicants: list[str] = []
+
+    while True:
+        next_round: dict[str, set[int]] = {}
+        used: set[str] = set()
+        items = list(current.items())
+
+        for i in range(len(items)):
+            for j in range(i + 1, len(items)):
+                a, a_cov = items[i]
+                b, b_cov = items[j]
+                ok, merged = _can_merge(a, b)
+                if ok:
+                    if merged not in next_round:
+                        next_round[merged] = set()
+                    next_round[merged] |= a_cov | b_cov
+                    used.add(a)
+                    used.add(b)
+
+        for term in current:
+            if term not in used:
+                prime_implicants.append(term)
+
+        if not next_round:
+            break
+        current = next_round
+
+    selected = _minimum_cover(prime_implicants, minterms, n)
+    expr = '+'.join(_pi_to_expr(pi, variables) for pi in selected)
+
+    synth_time_ms = (time.perf_counter() - t_start) * 1000
+    _, peak = tracemalloc.get_traced_memory()
+    tracemalloc.stop()
+
+    metrics = PerformanceMetrics(
+        synth_time_ms=round(synth_time_ms, 4),
+        peak_memory_bytes=peak,
+        prime_implicant_count=len(prime_implicants),
+    )
+    return expr, metrics

mcp_server/server.py

@@ -0,0 +1,247 @@
+"""
+mcp_server/server.py — MCP server wrapping the boolean algebra engine.
+
+Exposes five tools Claude can call mid-conversation:
+
+  evaluate     expression → full truth table + metrics
+  simplify     expression → minimal equivalent expression
+  equivalent   expr1, expr2 → bool (same truth table?)
+  satisfiable  expression → bool (any row outputs 1?)
+  check_contradiction  expression → bool (no row outputs 1?)
+
+Run with:
+    python3.11 -m mcp_server.server
+or via the MCP CLI:
+    mcp dev mcp_server/server.py
+"""
+from __future__ import annotations
+
+import sys
+import os
+
+# Allow running from project root: `python3.11 -m mcp_server.server`
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+from mcp.server.fastmcp import FastMCP
+from core.evaluator import evaluate as _evaluate
+from core.synthesizer import synthesize as _synthesize
+
+mcp = FastMCP(
+    "boolean-algebra-engine",
+    instructions=(
+        "Tools for evaluating boolean algebra expressions. "
+        "Use these to verify logic exactly — do not predict boolean results yourself. "
+        "Variables must be uppercase letters A-Z. "
+        "Operators: ! (NOT), . (AND), ^ (XOR), + (OR). "
+        "Parentheses override precedence."
+    ),
+)
+
+
+@mcp.tool()
+def evaluate(expression: str) -> dict:
+    """
+    Evaluate a boolean expression and return its full truth table.
+
+    Args:
+        expression: Boolean expression using variables A-Z and operators ! . ^ +
+                    Example: "A.(B+C)", "!(A.B)", "A^B"
+
+    Returns:
+        Dictionary with keys: expression, variables, rows (list of input/output dicts),
+        satisfiable, tautology, minterms, maxterms, eval_time_ms, rows_evaluated.
+    """
+    table, metrics = _evaluate(expression)
+    return {
+        "expression": table.expression,
+        "variables": table.variables,
+        "rows": [{**row.inputs, "output": row.output} for row in table.rows],
+        "satisfiable": table.satisfiable,
+        "tautology": table.tautology,
+        "minterms": table.minterms,
+        "maxterms": table.maxterms,
+        "eval_time_ms": metrics.eval_time_ms,
+        "rows_evaluated": metrics.rows_evaluated,
+    }
+
+
+@mcp.tool()
+def simplify(expression: str) -> dict:
+    """
+    Simplify a boolean expression to its minimal sum-of-products form.
+
+    Useful for finding redundant conditions, dead branches, or the canonical
+    form of a complex expression.
+
+    Args:
+        expression: Boolean expression using variables A-Z and operators ! . ^ +
+                    Example: "A.B+A.!B" simplifies to "A"
+
+    Returns:
+        Dictionary with keys: original, minimal, changed (bool),
+        prime_implicant_count, synth_time_ms.
+    """
+    table, _ = _evaluate(expression)
+    minimal, metrics = _synthesize(table)
+    return {
+        "original": expression,
+        "minimal": minimal,
+        "changed": minimal != expression,
+        "prime_implicant_count": metrics.prime_implicant_count,
+        "synth_time_ms": metrics.synth_time_ms,
+    }
+
+
+@mcp.tool()
+def equivalent(expression1: str, expression2: str) -> dict:
+    """
+    Check whether two boolean expressions are logically equivalent.
+
+    Two expressions are equivalent if they produce identical output columns
+    for all possible input combinations.
+
+    Args:
+        expression1: First boolean expression.
+        expression2: Second boolean expression.
+
+    Returns:
+        Dictionary with keys: equivalent (bool), expression1, expression2,
+        and on mismatch: differing_rows (list of input combos where they differ).
+    """
+    t1, _ = _evaluate(expression1)
+    t2, _ = _evaluate(expression2)
+
+    vars1 = set(t1.variables)
+    vars2 = set(t2.variables)
+    all_vars = sorted(vars1 | vars2)
+
+    # Re-evaluate both over the union variable set for fair comparison
+    from core.parser import get_variables
+    combined_expr1 = expression1
+    combined_expr2 = expression2
+
+    # Evaluate over shared variable space
+    n = len(all_vars)
+    differing = []
+    for i in range(2 ** n):
+        values = {var: (i >> (n - 1 - j)) & 1 for j, var in enumerate(all_vars)}
+        # Filter to each expression's variables
+        from core.evaluator import _evaluate_prefix
+        from core.parser import infix_to_prefix
+        p1 = infix_to_prefix(expression1)
+        p2 = infix_to_prefix(expression2)
+        v1 = {k: v for k, v in values.items() if k in vars1}
+        v2 = {k: v for k, v in values.items() if k in vars2}
+        out1 = _evaluate_prefix(p1, v1)
+        out2 = _evaluate_prefix(p2, v2)
+        if out1 != out2:
+            differing.append({**values, expression1: out1, expression2: out2})
+
+    result: dict = {
+        "equivalent": len(differing) == 0,
+        "expression1": expression1,
+        "expression2": expression2,
+    }
+    if differing:
+        result["differing_rows"] = differing[:10]  # cap at 10 for readability
+        result["total_differing"] = len(differing)
+    return result
+
+
+@mcp.tool()
+def satisfiable(expression: str) -> dict:
+    """
+    Check whether a boolean expression is satisfiable.
+
+    A satisfiable expression has at least one input combination that outputs 1.
+    An unsatisfiable expression is a contradiction (always 0).
+
+    Args:
+        expression: Boolean expression. Example: "A.!A" is unsatisfiable.
+
+    Returns:
+        Dictionary with keys: satisfiable (bool), expression,
+        and if satisfiable: example (first input combo that satisfies it).
+    """
+    table, _ = _evaluate(expression)
+    result: dict = {
+        "satisfiable": table.satisfiable,
+        "expression": expression,
+    }
+    if table.satisfiable:
+        first = table.rows[table.minterms[0]]
+        result["example"] = {**first.inputs, "output": first.output}
+    return result
+
+
+@mcp.tool()
+def check_prompt_logic(rules: list[str]) -> dict:
+    """
+    Check a set of boolean rules (e.g. from a system prompt) for contradictions,
+    tautologies, and pairwise equivalences.
+
+    Each rule should be a boolean expression using A-Z variables. Use consistent
+    variable naming across rules (e.g. A=user_authenticated, B=is_admin).
+
+    Args:
+        rules: List of boolean expressions representing logical conditions.
+               Example: ["A.B", "!A+!B", "A^B"]
+
+    Returns:
+        Dictionary with per-rule analysis (satisfiable, tautology, minimal form)
+        and pairwise checks (equivalent pairs, contradictory pairs).
+    """
+    analysis = []
+    for rule in rules:
+        try:
+            table, _ = _evaluate(rule)
+            minimal, _ = _synthesize(table)
+            analysis.append({
+                "rule": rule,
+                "satisfiable": table.satisfiable,
+                "tautology": table.tautology,
+                "contradiction": not table.satisfiable,
+                "minimal": minimal,
+                "simplified": minimal != rule,
+            })
+        except ValueError as e:
+            analysis.append({"rule": rule, "error": str(e)})
+
+    # Pairwise equivalence and contradiction checks
+    pairs = []
+    valid = [a for a in analysis if "error" not in a]
+    for i in range(len(valid)):
+        for j in range(i + 1, len(valid)):
+            r1, r2 = valid[i]["rule"], valid[j]["rule"]
+            try:
+                eq = equivalent(r1, r2)
+                t1, _ = _evaluate(r1)
+                t2, _ = _evaluate(r2)
+                # Contradiction: rules can never both be true simultaneously
+                combined = f"({r1}).({r2})"
+                combined_table, _ = _evaluate(combined)
+                pairs.append({
+                    "rule1": r1,
+                    "rule2": r2,
+                    "equivalent": eq["equivalent"],
+                    "can_both_be_true": combined_table.satisfiable,
+                    "always_conflict": not combined_table.satisfiable,
+                })
+            except ValueError:
+                pass
+
+    return {
+        "rules": analysis,
+        "pairwise": pairs,
+        "summary": {
+            "total": len(rules),
+            "contradictions": sum(1 for a in analysis if a.get("contradiction")),
+            "tautologies": sum(1 for a in analysis if a.get("tautology")),
+            "equivalent_pairs": sum(1 for p in pairs if p.get("equivalent")),
+            "conflicting_pairs": sum(1 for p in pairs if p.get("always_conflict")),
+        },
+    }
+
+
+if __name__ == "__main__":
+    mcp.run(transport="stdio")