mathlas-mcp 1.0.0__py3-none-any.whl

mathlas/__init__.py

@@ -0,0 +1,94 @@
+"""mathlas — a tool FOR an AI, not a tool that uses an AI. No API key. Free.
+
+mathlas gives a CALLING AI (Claude Code, Cursor, any MCP client / agent) the
+capabilities it lacks: search over EXISTING math, AIRTIGHT numeric/formal
+verification, structured needs<->guarantees scaffolds, and honest provenance
+(never "novel"). **mathlas itself NEVER calls an LLM and needs NO API key** — the
+AI is the brain; mathlas is the toolbox. Plug it in over MCP (``mathlas.server``)
+or call the library functions directly.
+
+What mathlas provides (all with NO LLM, returning DATA for the AI to reason over)
+---------------------------------------------------------------------------------
+  IDENTIFY  a real value/constant -> a known closed form, verified by independent
+            high-precision re-evaluation. ``identify`` / ``engine.py``. Airtight.
+  SEARCH    a query -> ranked candidate EXISTING results, via OUR OWN hybrid
+            (dense+BM25+RRF) index. ``retrieve`` / ``HybridRetriever``.
+  VERIFY    numeric (airtight digit agreement) + formal (Lean, stubbed) tiers,
+            plus an ``applicability_checklist`` -- the candidate's atomic
+            preconditions for the AI to check. ``verify`` / ``verify_apply``.
+  SCAFFOLD  the needs<->guarantees questions as data (``mapping_scaffold``) for
+            the AI to answer -- the analogy reasoning is the AI's job. ``map``.
+  PROVENANCE every result is tied to an existing source or labelled UNIDENTIFIED.
+
+A small bring-your-own-LLM ``solve()`` helper exists as a SECONDARY standalone
+convenience (you supply the LLM; the default is a no-op stub). mathlas ships no
+vendor SDK and no default model.
+
+    >>> import mpmath
+    >>> from mathlas import identify
+    >>> print(identify(mpmath.zeta(2)))      # doctest: +SKIP
+    1.64493406684823 -> pi**2/6  [known_form, verified 48 digits]
+"""
+# Numeric domain (airtight, no LLM, no network).
+from .engine import identify, Result, Candidate
+from .provenance import Provenance, Novelty
+from .verify import verify_closed_form, VerifyResult
+
+# Integer-sequence domain (airtight EXACT term-match vs a local copy of OEIS;
+# no LLM, no network at call time). Heavy data load stays lazy inside the module.
+from .sequence import (identify_sequence, SequenceResult, SequenceMatch,
+                       OEISIndex)
+
+# Retrieval + scaffolds + verification tiers (NO LLM). ``solve`` pulls in
+# numpy/scipy (declared deps); the heavier retrieval corpus/embedder imports
+# stay lazy inside their modules.
+from .map import (mapping_scaffold, MappingScaffold,
+                  map_candidates, extract_signature, Mapping, Signature)
+from .verify_apply import (applicability_checklist, Checklist,
+                           verify_numeric_claim, verify_formal, verify_informal,
+                           ApplyVerdict, Tier, Condition)
+from .retrieve import Retriever, Candidate as RetrievedCandidate
+
+# DISCOVERY + WEB-AUGMENTATION layer (NO LLM, no network, no API key).
+#   ramanujan  -- PSLQ-over-richer-basis + Ramanujan-Machine continued-fraction
+#                 conjectures, each numerically VERIFIED (provenance = conjecture).
+#   funsearch  -- the deterministic HARNESS for AI-generated program search
+#                 (sandboxed evaluate + on-disk MAP-Elites DB + few-shot status).
+#   webaug     -- search_directive (tell the AI what to web-search) + add_finding
+#                 (ingest a web result into the live corpus with NO model load).
+from .ramanujan import (conjecture, ConjectureResult, integer_relations,
+                        continued_fractions, simple_continued_fraction)
+from .webaug import (search_directive, SearchDirective, add_finding,
+                     AddFindingResult, search_findings, load_findings)
+
+# OPTIONAL bring-your-own-LLM standalone helper (secondary; no vendor SDK).
+from .solve import solve, Solution, AppliedResult
+from .llm import LLM, EchoLLM
+
+__version__ = "0.1.0"
+__all__ = [
+    # numeric (airtight)
+    "identify", "Result", "Candidate",
+    "verify_closed_form", "VerifyResult",
+    "verify_numeric_claim",
+    # integer sequences (airtight OEIS exact term-match)
+    "identify_sequence", "SequenceResult", "SequenceMatch", "OEISIndex",
+    # provenance
+    "Provenance", "Novelty",
+    # search (no LLM)
+    "Retriever", "RetrievedCandidate",
+    # scaffolds + verification tiers (no LLM)
+    "mapping_scaffold", "MappingScaffold",
+    "applicability_checklist", "Checklist",
+    "verify_formal", "ApplyVerdict", "Tier", "Condition",
+    # discovery + web-augmentation (no LLM, no network)
+    "conjecture", "ConjectureResult", "integer_relations",
+    "continued_fractions", "simple_continued_fraction",
+    "search_directive", "SearchDirective", "add_finding", "AddFindingResult",
+    "search_findings", "load_findings",
+    # optional bring-your-own-LLM standalone path (secondary)
+    "solve", "Solution", "AppliedResult",
+    "map_candidates", "extract_signature", "Mapping", "Signature",
+    "verify_informal",
+    "LLM", "EchoLLM",
+]

mathlas/cli.py

@@ -0,0 +1,236 @@
+"""``mathlas`` command-line entry point — NO LLM, NO API key.
+
+mathlas is a tool an AI *uses*; the CLI is a thin, human-facing view of the same
+no-LLM capabilities the AI gets over MCP. Modes:
+
+  NUMERIC  ``mathlas 1.6449340668482264``   -> the airtight constant->closed-form
+           path (engine.identify). Airtight, no LLM, no network. The default when
+           the argument parses as a single number.
+
+  SEQUENCE ``mathlas 1,1,2,3,5,8,13,21``  (or ``mathlas 1 1 2 3 5 8 13 21``)
+           -> identify an integer sequence against a LOCAL copy of OEIS by EXACT
+           term match (sequence.identify_sequence). Airtight, no LLM. The default
+           when the argument is two or more integers. Prints A-number/name/URL.
+
+  PROBLEM  ``mathlas "Banach contraction gives a unique fixed point"``
+           -> search EXISTING math (our own index) and, for the top candidate,
+           print the needs<->guarantees SCAFFOLD + applicability CHECKLIST as
+           data — the structure an AI (or you) reasons over. NO LLM is called.
+           Uses a small built-in seed corpus by default; point ``--corpus DIR`` at
+           the open theorem dataset for the real index.
+
+  MCP      ``mathlas mcp``  (or ``python -m mathlas.server``)
+           -> run the MCP server so an AI client can call the tools. Register in
+           Claude Code with:  ``claude mcp add mathlas -- python -m mathlas.server``
+
+Examples
+--------
+  mathlas 1.6449340668482264364724151666460251892
+  mathlas --basis pi,e,catalan 0.915965594177219
+  mathlas 1,1,2,3,5,8,13,21            # OEIS: Fibonacci (A000045)
+  mathlas 2 3 5 7 11 13                # OEIS: the primes (A000040)
+  mathlas "a bounded sequence has a convergent subsequence" --k 5
+  mathlas "<problem>" --corpus reference/theorem-search-dataset --limit 5000
+  mathlas mcp
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from typing import List, Optional
+
+
+def _looks_numeric(s: str) -> bool:
+    try:
+        float(s)
+        return True
+    except ValueError:
+        return False
+
+
+def _parse_sequence(s: str) -> Optional[List[int]]:
+    """Parse ``s`` as an integer sequence if it looks like one (>= 2 comma- or
+    whitespace-separated integers, optionally wrapped in [] or ()), else None.
+
+    A single number is NOT a sequence (that is numeric mode). Any non-integer
+    token (e.g. a decimal or word) disqualifies the whole string."""
+    body = s.strip().strip("[]()").strip()
+    # split on commas and/or whitespace
+    toks = [t for t in re.split(r"[,\s]+", body) if t]
+    if len(toks) < 2:
+        return None
+    out: List[int] = []
+    for t in toks:
+        if not re.fullmatch(r"[+-]?\d+", t):
+            return None
+        out.append(int(t))
+    return out
+
+
+def _looks_sequence(s: str) -> bool:
+    return _parse_sequence(s) is not None
+
+
+def _run_numeric(value: str, args) -> int:
+    import mpmath
+    from .engine import identify
+    from .identify import DEFAULT_BASIS
+    basis = tuple(args.basis.split(",")) if args.basis else DEFAULT_BASIS
+    mpmath.mp.dps = max(args.dps_verify + 10, 60)
+    v = mpmath.mpf(value)  # str -> full precision if more digits were given
+    res = identify(v, dps_search=args.dps_search, dps_verify=args.dps_verify,
+                   min_digits=args.min_digits, basis=basis)
+    print(res)
+    if args.verbose and res.candidates:
+        for c in res.candidates:
+            print(f"    candidate {c.expr}: verified {c.verify.digits_agreed} digits "
+                  f"[{c.provenance.novelty.value}]")
+    return 0 if res.identified else 1
+
+
+def _run_sequence(seq: List[int], args) -> int:
+    """Integer-sequence mode (NO LLM, airtight): exact term-match against a local
+    copy of OEIS. Prints the matching A-numbers, names and OEIS URLs."""
+    from .server import tool_identify_sequence
+    res = tool_identify_sequence(seq, max_results=args.k, data_dir=args.oeis_dir)
+    if args.json:
+        print(json.dumps(res, indent=2, default=str))
+        return 0 if res["identified"] else 1
+    print(f"# integer sequence {res['query']} — OEIS exact term-match:")
+    if not res["identified"]:
+        print(f"  (no match) {res['note']}")
+        return 1
+    for m in res["matches"]:
+        where = "prefix" if m["exact_prefix"] else f"offset {m['offset']}"
+        print(f"  {m['a_number']}  [{where}]  {m['url']}")
+        if m["name"]:
+            print(f"      {m['name']}")
+    print(f"\n({res['note']})")
+    return 0
+
+
+def _run_problem(problem: str, args) -> int:
+    """AI-driven, NO-LLM path: search existing math, then print the scaffold +
+    checklist the calling AI reasons over. mathlas itself never judges."""
+    from .server import (tool_search_existing_math, tool_mapping_scaffold,
+                         tool_applicability_checklist)
+    search = tool_search_existing_math(problem, k=args.k, corpus_dir=args.corpus,
+                                       corpus_limit=args.limit)
+    if args.json:
+        out = {"search": search}
+        if search["candidates"]:
+            top = search["candidates"][0]["statement"]
+            out["mapping_scaffold"] = tool_mapping_scaffold(problem, top)
+            out["applicability_checklist"] = tool_applicability_checklist(top)
+        print(json.dumps(out, indent=2, default=str))
+        return 0 if search["candidates"] else 1
+
+    print(f"# search ({search['corpus']}) — top {args.k} candidate existing results:")
+    for c in search["candidates"]:
+        score = c["score"]
+        print(f"  [{score:.4f}] {c['name'] or '(unnamed)'}  -- {c['source'] or ''}")
+        print(f"      {(c['slogan'] or c['statement'])[:160]}")
+    if not search["candidates"]:
+        print("  (no candidates; try --corpus DIR for a larger index)")
+        return 1
+
+    top = search["candidates"][0]
+    print(f"\n# needs<->guarantees SCAFFOLD for the top candidate "
+          f"({top['name'] or 'unnamed'}) — the AI reasons over this (NO LLM):")
+    sc = tool_mapping_scaffold(problem, top["statement"])
+    for q in sc["questions"]:
+        print(f"  - {q}")
+    print("\n# applicability CHECKLIST (mark each against your problem):")
+    cl = tool_applicability_checklist(top["statement"])
+    for cond in cl["preconditions"]:
+        print(f"  [ ] {cond['text']}")
+    print(f"  => guarantees: {cl['conclusion']}")
+    print("\n(mathlas provided search + scaffold + checklist; an AI does the "
+          "judging. Run `mathlas mcp` to expose these as MCP tools.)")
+    return 0
+
+
+def _run_mcp(_args) -> int:
+    from .server import main as server_main
+    return server_main()
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="mathlas",
+        description="A tool FOR an AI: search existing math + airtight "
+                    "verification + needs<->guarantees scaffolds. No API key.")
+    p.add_argument("query", nargs="*",
+                   help="a number (numeric mode), an integer sequence such as "
+                        "1,1,2,3,5,8 or '1 1 2 3 5 8' (sequence mode), a problem "
+                        "description (problem mode), or 'mcp' to run the MCP server")
+    p.add_argument("--mode",
+                   choices=["auto", "numeric", "sequence", "problem", "mcp"],
+                   default="auto")
+    p.add_argument("-v", "--verbose", action="store_true")
+    p.add_argument("--json", action="store_true",
+                   help="emit machine-readable JSON (problem/sequence mode)")
+
+    g = p.add_argument_group("numeric mode")
+    g.add_argument("--basis", help="comma-separated constant basis (e.g. pi,e,catalan)")
+    g.add_argument("--dps-search", type=int, default=30)
+    g.add_argument("--dps-verify", type=int, default=50)
+    g.add_argument("--min-digits", type=int, default=20)
+
+    g = p.add_argument_group("sequence mode")
+    g.add_argument("--oeis-dir", help="dir holding OEIS stripped.gz/names.gz "
+                                      "(omit to use the standard search path)")
+
+    g = p.add_argument_group("problem mode")
+    g.add_argument("--corpus", help="dir with the open theorem dataset parquets "
+                                    "(omit to use the built-in seed corpus)")
+    g.add_argument("--limit", type=int, default=5000,
+                   help="cap corpus size (keep small without a GPU)")
+    g.add_argument("--k", type=int, default=10,
+                   help="candidates/matches to return")
+    return p
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    args = build_parser().parse_args(argv)
+    # ``query`` is now a list of tokens (nargs="*"). Reconstruct the user's intent:
+    # join multiple tokens into one string (so "1 1 2 3" -> a space-separated
+    # sequence, and a multi-word problem stays intact).
+    tokens: List[str] = args.query or []
+    query = " ".join(tokens).strip()
+    mode = args.mode
+
+    if mode == "auto":
+        if not query:
+            print("error: provide a number, an integer sequence, a problem "
+                  "description, or 'mcp'", file=sys.stderr)
+            return 2
+        if query == "mcp":
+            mode = "mcp"
+        elif _looks_numeric(query):          # a single bare number -> numeric
+            mode = "numeric"
+        elif _looks_sequence(query):         # >= 2 integers -> sequence
+            mode = "sequence"
+        else:
+            mode = "problem"
+
+    if mode == "mcp":
+        return _run_mcp(args)
+    if not query:
+        print("error: a query is required for this mode", file=sys.stderr)
+        return 2
+    if mode == "numeric":
+        return _run_numeric(query, args)
+    if mode == "sequence":
+        seq = _parse_sequence(query)
+        if seq is None:
+            print(f"error: {query!r} is not an integer sequence", file=sys.stderr)
+            return 2
+        return _run_sequence(seq, args)
+    return _run_problem(query, args)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

mathlas/embed.py

@@ -0,0 +1,129 @@
+"""Pluggable dense-embedding backend for semantic retrieval.
+
+Mirrors the ``llm.py`` design: the embedder is an interface, not a hardwired
+vendor. The PRODUCTION path is an open-weights instruction-tuned text embedder
+(Qwen3-Embedding, the current open MTEB SOTA — Zhang et al., arXiv:2506.05176);
+the DEFAULT path needs no model download so validation runs CPU-only/offline.
+
+Why Qwen3-Embedding for the production index
+--------------------------------------------
+Qwen3-Embedding (0.6B/4B/8B; 1024/2560/4096-dim, Matryoshka-truncatable) tops
+MTEB as of mid-2026 and is exactly what TheoremSearch independently converged on
+for the same corpus — but we build OUR OWN index with it, over the open dataset.
+It is *instruction-aware*: prefixing the query with a task instruction gives a
+documented +1-5% on retrieval, so ``Qwen3Embedder`` adds that prefix to queries
+(never to documents), per the model card.
+
+The corpus unit we embed is the natural-language *slogan/denotation* of a
+theorem, NOT raw LaTeX (the load-bearing lesson: symbol-heavy LaTeX drowns dense
+embedders; mathematicians query in prose). See ``retrieve/corpus.py``.
+
+References
+----------
+- Qwen3-Embedding: Zhang et al., "Qwen3 Embedding," arXiv:2506.05176 (2026).
+- MTEB: Muennighoff et al., "MTEB: Massive Text Embedding Benchmark," 2023.
+"""
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import List, Optional, Sequence
+
+import numpy as np
+
+
+class Embedder(ABC):
+    """Text -> unit-norm dense vectors. Documents and queries embed the same
+    way unless a backend opts to instruction-prefix queries (Qwen3 does)."""
+
+    #: dimensionality of the returned vectors
+    dim: int
+
+    @abstractmethod
+    def encode(self, texts: Sequence[str], *, is_query: bool = False) -> np.ndarray:
+        """Return an ``(len(texts), dim)`` float32 array of L2-normalised rows."""
+        ...
+
+
+def _l2norm(x: np.ndarray) -> np.ndarray:
+    n = np.linalg.norm(x, axis=1, keepdims=True)
+    n[n == 0] = 1.0
+    return (x / n).astype(np.float32)
+
+
+class HashingEmbedder(Embedder):
+    """Zero-dependency, zero-download fallback embedder (the DEFAULT).
+
+    A deterministic word-hashing bag-of-words projected to ``dim`` and
+    L2-normalised. It is intentionally weak -- it exists so the retrieval +
+    fusion + map + verify pipeline can be exercised end-to-end on CPU with no
+    model weights. For any real corpus, plug in ``Qwen3Embedder`` (production)
+    or another open embedder. We deliberately keep the *dense channel* honest
+    by pairing it with BM25 in the hybrid retriever, so a weak dense backend
+    still yields a usable system (sparse carries exact-term matches).
+    """
+
+    def __init__(self, dim: int = 256, ngram: int = 1) -> None:
+        self.dim = int(dim)
+        self.ngram = int(ngram)
+
+    def _toks(self, text: str) -> List[str]:
+        words = "".join(c.lower() if (c.isalnum() or c.isspace()) else " "
+                        for c in text).split()
+        if self.ngram <= 1:
+            return words
+        grams = words[:]
+        for n in range(2, self.ngram + 1):
+            grams += ["_".join(words[i:i + n]) for i in range(len(words) - n + 1)]
+        return grams
+
+    def encode(self, texts: Sequence[str], *, is_query: bool = False) -> np.ndarray:
+        out = np.zeros((len(texts), self.dim), dtype=np.float32)
+        for i, t in enumerate(texts):
+            for tok in self._toks(t):
+                h = hash((tok, "mathlas-embed")) % self.dim
+                sign = 1.0 if (hash((tok, "sign")) & 1) else -1.0
+                out[i, h] += sign
+        return _l2norm(out)
+
+
+class Qwen3Embedder(Embedder):
+    """Open-weights production embedder (Qwen3-Embedding via sentence-transformers).
+
+    Lazy-loaded so importing mathlas never pulls torch/transformers unless a
+    caller actually constructs this. Heavy on CPU; run on GPU for the full
+    index. Validation in this repo uses ``HashingEmbedder`` to stay light.
+    """
+
+    # Query-side instruction (documents are embedded bare). Per the Qwen3 card,
+    # the instruction goes ONLY on the query and lifts retrieval 1-5%.
+    DEFAULT_INSTRUCT = (
+        "Given a mathematical problem or a description of a result, retrieve the "
+        "statement of the existing theorem or lemma that applies to it."
+    )
+
+    def __init__(self, model: str = "Qwen/Qwen3-Embedding-0.6B",
+                 dim: Optional[int] = None, device: Optional[str] = None,
+                 instruct: Optional[str] = DEFAULT_INSTRUCT) -> None:
+        try:
+            from sentence_transformers import SentenceTransformer
+        except ImportError as e:  # pragma: no cover - optional heavy dep
+            raise ImportError(
+                "pip install 'mathlas[embed]' (sentence-transformers + torch) "
+                "for the Qwen3 production embedder; the default HashingEmbedder "
+                "needs no extra deps."
+            ) from e
+        self._st = SentenceTransformer(model, device=device,
+                                       truncate_dim=dim)  # MRL truncation if set
+        self.dim = int(dim or self._st.get_sentence_embedding_dimension())
+        self._instruct = instruct
+
+    def encode(self, texts: Sequence[str], *, is_query: bool = False) -> np.ndarray:
+        kw = {}
+        if is_query and self._instruct:
+            kw["prompt"] = f"Instruct: {self._instruct}\nQuery: "
+        vecs = self._st.encode(list(texts), normalize_embeddings=True,
+                               convert_to_numpy=True, **kw)
+        return vecs.astype(np.float32)
+
+
+__all__ = ["Embedder", "HashingEmbedder", "Qwen3Embedder"]

mathlas/engine.py

@@ -0,0 +1,95 @@
+"""math_engine v0 facade -- the numeric beachhead.
+
+``identify(value)`` runs the full loop:
+
+    route (implicit: real constant)
+      -> identify   (find an existing closed form)
+      -> verify     (independent high-precision re-evaluation)
+      -> provenance (label the source; never "novel")
+
+and returns a ``Result`` you can inspect or print.
+
+Precision caveat: pass high-precision inputs as ``mpmath.mpf`` or as strings.
+A Python ``float`` carries only ~15 digits, which limits PSLQ to the simplest
+relations.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import List, Optional
+
+import mpmath
+
+from .identify import identify_constant, DEFAULT_BASIS
+from .verify import verify_closed_form, VerifyResult
+from .provenance import Provenance, Novelty
+
+
+def _pretty(expr: str) -> str:
+    """A human-readable form of a verified PSLQ expression for DISPLAY only.
+    Runs after verification, so it can never weaken the airtight check; on any
+    failure it falls back to the raw expression. ``pi**2*(sqrt(24)/12)**2`` ->
+    ``pi**2/6``; ``(1*catalan)`` -> ``Catalan``."""
+    try:
+        import sympy
+        from .verify import _to_sympy_expr
+        return str(sympy.simplify(_to_sympy_expr(expr)))
+    except Exception:
+        return expr
+
+
+@dataclass(frozen=True)
+class Candidate:
+    expr: str                      # the verified PSLQ expression (raw)
+    verify: VerifyResult
+    provenance: Provenance
+
+    @property
+    def display(self) -> str:
+        """Simplified, human-readable form (verification used ``expr``)."""
+        return _pretty(self.expr)
+
+
+@dataclass(frozen=True)
+class Result:
+    query: str
+    best: Optional[Candidate]
+    candidates: List[Candidate]
+
+    @property
+    def identified(self) -> bool:
+        return self.best is not None
+
+    def __str__(self) -> str:
+        if self.best is None:
+            return f"{self.query} -> UNIDENTIFIED (no verified closed form)"
+        b = self.best
+        return (f"{self.query} -> {b.display}  "
+                f"[{b.provenance.novelty.value}, verified {b.verify.digits_agreed} digits]")
+
+
+def identify(value, dps_search: int = 30, dps_verify: int = 50,
+             min_digits: int = 20, basis=DEFAULT_BASIS) -> Result:
+    """Find and verify an existing closed form for a real ``value``."""
+    with mpmath.workdps(dps_verify):
+        v = value if isinstance(value, mpmath.mpf) else mpmath.mpf(value)
+        query = mpmath.nstr(v, 15)
+
+        proposals = identify_constant(v, dps_search=dps_search, basis=basis)
+
+        cands: List[Candidate] = []
+        for expr in proposals:
+            vr = verify_closed_form(v, expr, dps_verify=dps_verify,
+                                    min_digits=min_digits)
+            if vr.ok:
+                prov = Provenance(
+                    novelty=Novelty.KNOWN_FORM,
+                    method="mpmath.identify+sympy-verify",
+                    source=expr,
+                    basis=tuple(basis),
+                )
+                cands.append(Candidate(expr=expr, verify=vr, provenance=prov))
+
+        cands.sort(key=lambda c: c.verify.digits_agreed, reverse=True)
+        best = cands[0] if cands else None
+        return Result(query=query, best=best, candidates=cands)