mathslate 0.1.0__py3-none-any.whl

mathslate/__init__.py

@@ -0,0 +1,140 @@
+"""MathSlate — a mathematical workspace that grows with you.
+
+    from mathslate import *
+    plot(sin(x)/x)
+
+Everything symbolic is SymPy's, unwrapped and re-exported. MathSlate adds
+eight callables and one guarantee: the graph is right, and you can always ask
+it what the plain Python was.
+"""
+
+from __future__ import annotations
+
+# --- SymPy re-exports (zero MathSlate code) -------------------------------
+# PRD 6.3: thin wrappers around identically named SymPy functions are not
+# wrapped at all. What follows is a plain re-export.
+import sympy as sympy
+from sympy import (  # noqa: F401
+    E,
+    Abs,
+    Eq,
+    Float,
+    Function,
+    I,
+    Integer,
+    Matrix,
+    Piecewise,
+    Rational,
+    Sum,
+    Symbol,
+    acos,
+    apart,
+    asin,
+    atan,
+    binomial,
+    cancel,
+    cbrt,
+    ceiling,
+    cos,
+    cosh,
+    cot,
+    csc,
+    diff,
+    exp,
+    expand,
+    factor,
+    factorial,
+    floor,
+    gcd,
+    integrate,
+    lambdify,
+    limit,
+    log,
+    nsimplify,
+    nsolve,
+    oo,
+    pi,
+    root,
+    sec,
+    series,
+    sign,
+    simplify,
+    sin,
+    sinh,
+    solve,
+    solveset,
+    sqrt,
+    symbols,
+    tan,
+    tanh,
+    together,
+    trigsimp,
+)
+
+from . import errors as errors
+from .api import (
+    analyze,
+    animate,
+    dataset,
+    frontend_report,
+    get_range_controls,
+    get_verbose,
+    plot,
+    polar,
+    set_range_controls,
+    set_verbose,
+    show_python,
+    slider,
+    table,
+)
+from .core.analysis import Analysis
+from .core.data import Dataset
+from .core.tables import Table
+from .result import PlotResult
+
+__version__: str = "0.1.0"
+
+# --- predefined symbols (PRD 6.3) -----------------------------------------
+# Open decision 3: `import *` is permitted so that these exist, but
+# show_python() always emits the explicit `x = sp.symbols('x')`.
+x, y, z, t, n, k = symbols("x y z t n k", real=True)
+theta = Symbol("theta", real=True)
+
+#: New public symbols introduced by MathSlate — the API-surface budget.
+NEW_API: tuple[str, ...] = (
+    "plot",
+    "polar",
+    "slider",
+    "animate",
+    "table",
+    "analyze",
+    "show_python",
+    "dataset",
+    "set_verbose",
+    "get_verbose",
+    "set_range_controls",
+    "get_range_controls",
+    "frontend_report",
+    "PlotResult",
+    "Analysis",
+    "Table",
+    "Dataset",
+)
+
+__all__ = [
+    # MathSlate
+    *NEW_API,
+    "errors",
+    "sympy",
+    "__version__",
+    # predefined symbols
+    "x", "y", "z", "t", "n", "k", "theta",
+    # SymPy re-exports
+    "E", "Abs", "Eq", "Float", "Function", "I", "Integer", "Matrix", "Piecewise",
+    "Rational", "Sum", "Symbol", "acos", "apart", "asin", "atan", "binomial",
+    "cancel", "cbrt", "ceiling", "cos", "cosh", "cot", "csc", "diff", "exp",
+    "expand", "factor", "factorial", "floor", "gcd", "integrate", "lambdify",
+    "limit", "log", "nsimplify", "nsolve", "oo", "pi", "root", "sec", "series",
+    "sign", "simplify", "sin", "sinh", "solve", "solveset", "sqrt", "symbols",
+    "tan", "tanh", "together", "trigsimp",
+]

mathslate/_text.py

@@ -0,0 +1,64 @@
+"""Printing that survives a non-UTF-8 console.
+
+MathSlate's inference report and π tick labels are nicer with real Unicode,
+and notebooks render it happily. A Windows terminal on a legacy code page
+(cp949, cp1252, …) raises ``UnicodeEncodeError`` instead — which would turn a
+learner's very first ``plot()`` into a traceback. So: keep the Unicode, and
+transliterate only when the destination cannot take it.
+"""
+
+from __future__ import annotations
+
+import sys
+from typing import Final, TextIO
+
+__all__ = ["to_ascii", "encodable", "safe_print"]
+
+_REPLACEMENTS: Final[tuple[tuple[str, str], ...]] = (
+    ("∈", "in"),        # ∈
+    ("·", "-"),         # ·
+    ("—", "--"),        # —
+    ("–", "-"),         # –
+    ("→", "->"),        # →
+    ("π", "pi"),        # π
+    ("θ", "theta"),     # θ
+    ("φ", "phi"),       # φ
+    ("≤", "<="),        # ≤
+    ("≥", ">="),        # ≥
+    ("×", "x"),         # ×
+    ("∞", "inf"),       # ∞
+)
+
+
+def to_ascii(text: str) -> str:
+    """Replace MathSlate's decorative Unicode with plain ASCII equivalents."""
+    for source, target in _REPLACEMENTS:
+        text = text.replace(source, target)
+    return text.encode("ascii", "replace").decode("ascii")
+
+
+def encodable(text: str, stream: TextIO) -> bool:
+    """Can ``stream`` represent ``text`` without loss?"""
+    encoding = getattr(stream, "encoding", None)
+    if not encoding:
+        return True
+    try:
+        text.encode(encoding)
+    except (UnicodeEncodeError, LookupError):
+        return False
+    return True
+
+
+def safe_print(text: str, stream: TextIO | None = None) -> None:
+    """``print`` that transliterates rather than raising or printing mojibake.
+
+    Checking up front matters: a console configured with ``errors='replace'``
+    does not raise, it silently prints question marks.
+    """
+    target = stream if stream is not None else sys.stdout
+    if not encodable(text, target):
+        text = to_ascii(text)
+    try:
+        print(text, file=target)
+    except UnicodeEncodeError:
+        print(to_ascii(text), file=target)

mathslate/ai/__init__.py

@@ -0,0 +1,51 @@
+"""Natural language → MathSlate code (PRD 6.1, 7 v1.0).
+
+    from mathslate.ai import ask
+    print(ask("plot the tangent over one period").code)
+
+Three rules, and the first two are absolute.
+
+**The core never imports this package.** PRD §8 lists "AI dependency blocked on
+school or corporate networks" as a risk whose mitigation is that the core must
+work fully offline and the AI ships as extras. ``import mathslate`` does not
+reach this module, and this module's provider libraries are imported lazily
+inside the adapter that needs them, so nothing here can make a plain install
+heavier or a school network a problem. ``tests/test_ai.py`` asserts it.
+
+**It returns code; it does not run it.** A model writing Python and the library
+executing it unseen is not something a learner can check, and checking is the
+whole point of this project. :class:`Suggestion` holds the source and prints it.
+An explicit :meth:`Suggestion.run` validates a small MathSlate-oriented AST,
+uses restricted builtins, and runs under a wall-clock budget so an
+allowlisted-but-runaway expression cannot hang the caller; unrestricted Python
+requires ``unsafe=True``.
+
+**No provider is bundled.** :func:`ask` resolves one at call time from what is
+installed and configured, and says exactly what to install when it finds
+nothing. Resolving PRD §9 open decision 4: the layer lives in the core package
+as extras, not as a separate distribution — it is a few hundred lines and a
+separate package would cost more in version skew than it saves.
+"""
+
+from __future__ import annotations
+
+from .providers import (
+    PROVIDERS,
+    Provider,
+    available_providers,
+    resolve_provider,
+)
+from .suggest import Suggestion, ask, configure, configured, forget, system_prompt
+
+__all__ = [
+    "ask",
+    "configure",
+    "configured",
+    "forget",
+    "Suggestion",
+    "Provider",
+    "PROVIDERS",
+    "available_providers",
+    "resolve_provider",
+    "system_prompt",
+]

mathslate/ai/providers.py

@@ -0,0 +1,231 @@
+"""The three backends, behind one small protocol.
+
+Each adapter is the least code that turns "a system prompt and a question" into
+"some text". Provider SDKs are imported **inside** the call, never at module
+scope, so importing :mod:`mathslate.ai` costs nothing and a missing SDK is a
+sentence rather than an ImportError from three frames down.
+
+Model names are defaults, not decisions: every provider moves faster than a
+release cycle, so ``ask(..., model=...)`` overrides and the default is only
+what a first-time caller gets.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from typing import Callable, Protocol
+
+from ..errors import UnsupportedInputError
+
+__all__ = [
+    "Provider",
+    "Backend",
+    "PROVIDERS",
+    "available_providers",
+    "resolve_provider",
+]
+
+#: How many tokens a suggestion may take. MathSlate answers are short.
+MAX_TOKENS: int = 1500
+
+
+class Backend(Protocol):
+    """What a provider adapter has to be able to do."""
+
+    def complete(self, system: str, question: str, model: str) -> str:
+        """Return the model's reply to ``question`` under ``system``."""
+
+
+@dataclass(frozen=True)
+class Provider:
+    """One named backend: what to install, what to set, and what it defaults to."""
+
+    name: str
+    #: The import path, for detection.
+    package: str
+    #: What to type after `pip install` — not always the import path.
+    pip_name: str
+    env_var: str
+    default_model: str
+    build: Callable[[str | None], Backend]
+
+    def installed(self) -> bool:
+        import importlib.util
+
+        try:
+            return importlib.util.find_spec(self.package) is not None
+        except (ImportError, ModuleNotFoundError, ValueError):
+            # `find_spec("google.genai")` raises rather than returning None when
+            # the parent package is absent, which is the ordinary case here.
+            return False
+
+    def configured(self) -> bool:
+        return bool(os.environ.get(self.env_var))
+
+    def ready(self) -> bool:
+        return self.installed() and self.configured()
+
+    def describe(self) -> str:
+        if not self.installed():
+            return f"{self.name}: not installed (pip install {self.pip_name})"
+        if not self.configured():
+            return f"{self.name}: installed, but {self.env_var} is not set"
+        return f"{self.name}: ready"
+
+
+# --------------------------------------------------------------------------
+# adapters
+# --------------------------------------------------------------------------
+
+
+class _Anthropic:
+    def __init__(self, api_key: str | None = None) -> None:
+        self._api_key = api_key
+
+    def complete(self, system: str, question: str, model: str) -> str:
+        import anthropic
+
+        client = anthropic.Anthropic(api_key=self._api_key or None)
+        reply = client.messages.create(
+            model=model,
+            max_tokens=MAX_TOKENS,
+            system=system,
+            messages=[{"role": "user", "content": question}],
+        )
+        return "".join(
+            block.text for block in reply.content if getattr(block, "type", "") == "text"
+        )
+
+
+class _OpenAI:
+    def __init__(self, api_key: str | None = None) -> None:
+        self._api_key = api_key
+
+    def complete(self, system: str, question: str, model: str) -> str:
+        import openai
+
+        client = openai.OpenAI(api_key=self._api_key or None)
+        reply = client.chat.completions.create(
+            model=model,
+            max_completion_tokens=MAX_TOKENS,
+            messages=[
+                {"role": "system", "content": system},
+                {"role": "user", "content": question},
+            ],
+        )
+        return reply.choices[0].message.content or ""
+
+
+class _Gemini:
+    def __init__(self, api_key: str | None = None) -> None:
+        self._api_key = api_key
+
+    def complete(self, system: str, question: str, model: str) -> str:
+        from google import genai
+        from google.genai import types
+
+        client = genai.Client(api_key=self._api_key or None)
+        reply = client.models.generate_content(
+            model=model,
+            contents=question,
+            config=types.GenerateContentConfig(
+                system_instruction=system, max_output_tokens=MAX_TOKENS
+            ),
+        )
+        return reply.text or ""
+
+
+#: In preference order. Claude first because MathSlate's own development is
+#: done against it, so its behaviour on this prompt is the best understood.
+PROVIDERS: tuple[Provider, ...] = (
+    Provider(
+        name="claude",
+        package="anthropic",
+        pip_name="anthropic",
+        env_var="ANTHROPIC_API_KEY",
+        default_model="claude-sonnet-5",
+        build=_Anthropic,
+    ),
+    Provider(
+        name="openai",
+        package="openai",
+        pip_name="openai",
+        env_var="OPENAI_API_KEY",
+        default_model="gpt-5",
+        build=_OpenAI,
+    ),
+    Provider(
+        name="gemini",
+        package="google.genai",
+        pip_name="google-genai",
+        env_var="GOOGLE_API_KEY",
+        default_model="gemini-2.5-pro",
+        build=_Gemini,
+    ),
+)
+
+
+def available_providers() -> tuple[Provider, ...]:
+    """Every provider that is both installed and configured."""
+    return tuple(provider for provider in PROVIDERS if provider.ready())
+
+
+def resolve_provider(
+    name: str | None = None, *, api_key: str | None = None
+) -> Provider:
+    """Pick a provider, or explain precisely what is missing.
+
+    An explicitly supplied key is a complete credential. Requiring the same
+    key to also exist in an environment variable would make ``ask(api_key=...)``
+    and ``configure(api_key=...)`` unusable in notebooks.
+    """
+    if name is not None:
+        for provider in PROVIDERS:
+            if provider.name == name:
+                if not provider.installed():
+                    raise UnsupportedInputError(
+                        f"provider {name!r} needs its SDK: "
+                        f"pip install {provider.pip_name}."
+                    )
+                if not api_key and not provider.configured():
+                    raise UnsupportedInputError(
+                        f"provider {name!r} needs {provider.env_var} in the "
+                        "environment or an explicit api_key=."
+                    )
+                return provider
+        known = ", ".join(p.name for p in PROVIDERS)
+        raise UnsupportedInputError(f"unknown provider {name!r}; known: {known}.")
+
+    if api_key:
+        # A key is a credential for exactly one service, and nothing in the
+        # string reliably says which. Guessing would send the user's secret to
+        # a company it does not belong to, so an explicit key requires an
+        # explicit provider unless there is only one candidate.
+        candidates = tuple(p for p in PROVIDERS if p.installed())
+        if len(candidates) == 1:
+            return candidates[0]
+        if not candidates:
+            raise UnsupportedInputError(
+                "an api_key was given but no provider SDK is installed, so there "
+                "is nothing to send it to. Install one with "
+                "`pip install 'mathslate[ai]'`."
+            )
+        names = ", ".join(p.name for p in candidates)
+        raise UnsupportedInputError(
+            f"an explicit api_key needs an explicit provider: {names} are all "
+            "installed, and sending a key to the wrong one would hand your "
+            f"credential to the wrong company. Say which, e.g. "
+            f"provider='{candidates[0].name}'."
+        )
+
+    ready = available_providers()
+    if ready:
+        return ready[0]
+    status = "\n  ".join(provider.describe() for provider in PROVIDERS)
+    raise UnsupportedInputError(
+        "no AI provider is ready. MathSlate itself needs none of this and works "
+        "offline; the assistant is an optional extra.\n"
+        f"  {status}\n"
+        "Install one with `pip install 'mathslate[ai]'` and set its API key."
+    )