Upload README.md

Fix Hugging Face Space configuration metadata

README.md

@@ -1,6 +1,18 @@
+---
+title: Saad.AI
+emoji: 🧠
+colorFrom: blue
+colorTo: indigo
+sdk: streamlit
+sdk_version: "1.32.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. See [PORTFOLIO.md](PORTFOLIO.md) for the project story and demo flow.
+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.
 
@@ -22,48 +34,36 @@ Saad.AI is an academic mathematics assistant for university students. It combine
 
 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.
 
-## Architecture
+## Portfolio architecture
 
-The current stabilization refactor keeps Streamlit as the user interface while separating the main responsibilities:
+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
-math-engine/
-├── app.py                         # Streamlit UI, session flow, and graph rendering
-├── src/
-│   ├── engine/
-│   │   └── sympy_engine.py        # Deterministic symbolic and numeric adapters
-│   └── services/
-│       └── ai.py                  # Provider rotation, vision, uploads, verification
-├── tests/
-│   └── test_engine.py             # Deterministic engine regression tests
-├── requirements.txt               # Runtime dependencies actually used by the app
-└── README.md
-```
-
-The next recommended phase is to split the remaining UI, persistence, and plotting concerns into their own modules and add provider mocks and upload fixtures.
-
-## Run locally
-
-```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
+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
 ```
 
-Open `http://localhost:8501` in a browser.
+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.
 
-Run the deterministic regression tests with:
+## Example prompts
 
-```bash
-python -m unittest discover -s tests -v
+```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 environment variables or Hugging Face Space secrets:
+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
@@ -76,28 +76,20 @@ GEMINI_API_KEY_4
 OPENROUTER_API_KEY
 ```
 
-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.
+If providers are unavailable, supported deterministic requests still return their verified SymPy result instead of failing with “All providers failed.”
 
-## Example prompts
+## Local development
 
-```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
+```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
 ```
 
-## Deployment notes
-
-The active source uses hosted API providers rather than loading a local Hugging Face model at runtime. The dependency list therefore excludes the previously declared `transformers` and `torch` packages, which were not used by the current application and added unnecessary deployment weight.
-
-Runtime configuration is centralized in `src/config.py`. Copy `.env.example` to `.env` for local development, or add the same variables as Hugging Face Space secrets. Provider timeouts, upload size, and PDF page limits are validated and clamped at startup so malformed deployment values cannot create unbounded resource usage.
-
-For a portfolio deployment, add the provider secrets to Hugging Face Spaces or another Streamlit host, then launch the app with `streamlit run app.py`. No database or authentication setup is required. Every push and pull request runs the deterministic test suite and Python compilation checks through [`.github/workflows/ci.yml`](.github/workflows/ci.yml).
+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