| --- |
| title: Saad.AI |
| emoji: 🧠 |
| colorFrom: blue |
| colorTo: indigo |
| sdk: streamlit |
| sdk_version: "1.40.0" |
| python_version: "3.10" |
| app_file: app.py |
| pinned: false |
| --- |
| |
| # Saad.AI — B.Sc. Mathematics Engine |
|
|
| Saad.AI is an academic mathematics assistant for university students. It combines a deterministic **SymPy computation engine** with configurable AI providers for explanations, proofs, theory questions, graph descriptions, and image/PDF-based problem solving. |
|
|
| > **Important:** SymPy verification applies only when a request matches one of the implemented deterministic adapters. General proofs, theory questions, unsupported matrix formats, and unsupported subjects are treated as AI-generated unless a deterministic adapter returns a verified result. |
|
|
| ## Current capabilities |
|
|
| | Area | Examples | Verification mode | |
| |---|---|---| |
| | Calculus | Derivatives, integrals, limits | SymPy when parsed successfully | |
| | Equations | Polynomial equations and roots | SymPy when parsed successfully | |
| | Differential equations | Selected first- and second-order ODE forms | SymPy for supported forms | |
| | Numerical methods | Newton–Raphson, bisection, secant, Simpson, trapezoidal, Euler, RK4 | Deterministic numeric adapter | |
| | Number theory | GCD, LCM, factorization, totient, congruences, CRT, selected theorems, modulo | SymPy / deterministic adapter | |
| | Linear algebra | Determinants, eigenvalues/eigenvectors, inverses, ranks, transposes | Deterministic SymPy adapter | |
| | Real analysis | Selected sequence, series, Taylor, and integral computations | SymPy for supported computations; AI for theory/proofs | |
| | Differential geometry | Curvature, arc length, Frenet–Serret, fundamental forms | SymPy for supported parametric forms | |
| | Hydro mechanics | Continuity, Bernoulli, Reynolds, flow rate, pressure, Torricelli | Deterministic formula adapter for supported prompts | |
| | Graphing | Explicit requests to plot or graph a function | Matplotlib rendering | |
| | Attachments | JPG, PNG, WEBP, and PDF questions | Vision provider; deterministic verification when extractable | |
|
|
| The engine is intentionally not presented as a universal proof checker. For questions that cannot be deterministically parsed, the application sends the prompt to the configured AI provider and labels the result as AI-generated where appropriate. |
|
|
| ## Portfolio architecture |
|
|
| The deployed Space uses a flat layout because the Hugging Face web uploader preserves uploaded filenames. The responsibilities remain separated into the same modules used by the GitHub portfolio branch: |
|
|
| ```text |
| app.py # Streamlit UI, session flow, and graph rendering |
| config.py # Centralized provider and runtime configuration |
| sympy_engine.py # Deterministic symbolic and numeric adapters |
| ai.py # Provider rotation, vision, uploads, and verification |
| requirements.txt # Runtime dependencies |
| ``` |
|
|
| Chat history is intentionally **session-local** in the portfolio edition. This keeps the application easy to understand and deploy while still allowing users to create, switch, and delete conversations during a demo session. A database is not required. |
|
|
| ## Example prompts |
|
|
| ```text |
| Find the derivative of x^3 + 5x^2 - 3x + 7 |
| Integrate sin(x) * e^x dx |
| Find limit of sin(x)/x as x -> 0 |
| Apply Newton-Raphson to x^3 - 2x - 5 = 0, x0=2, 3 iterations |
| Apply bisection of x^3 - x on [0, 2], 4 iterations |
| Find gcd of 84 and 30 |
| Solve 14x ≡ 30 (mod 44) using Euclidean algorithm |
| Plot y = x^2 - 4 from -3 to 3 |
| ``` |
|
|
| ## Configuration |
|
|
| AI providers are optional for deterministic SymPy requests but required for explanations and unsupported subjects. Configure provider credentials through Hugging Face Space secrets: |
|
|
| ```text |
| GROQ_API_KEY_1 |
| GROQ_API_KEY_2 |
| GROQ_API_KEY_3 |
| GEMINI_API_KEY_1 |
| GEMINI_API_KEY_2 |
| GEMINI_API_KEY_3 |
| GEMINI_API_KEY_4 |
| OPENROUTER_API_KEY |
| ``` |
|
|
| If providers are unavailable, supported deterministic requests still return their verified SymPy result instead of failing with “All providers failed.” |
|
|
| ## Local development |
|
|
| ```bash |
| git clone https://github.com/almuyed-saad/math-engine.git |
| cd math-engine |
| python -m venv .venv |
| source .venv/bin/activate |
| pip install -r requirements.txt |
| streamlit run app.py |
| ``` |
|
|
| The project source and full test suite are maintained in the [GitHub repository](https://github.com/almuyed-saad/math-engine/tree/refactor/stabilize-saadai). |
|
|
| ## Credits |
|
|
| The project was created by Saad for B.Sc. Mathematics students at Shahjalal University of Science and Technology. It uses [Streamlit](https://streamlit.io), [SymPy](https://www.sympy.org), [Matplotlib](https://matplotlib.org), and hosted AI provider APIs. |
|
|
