From 32b1009084409791e2d0efcb9ddf21641c11a8aa Mon Sep 17 00:00:00 2001 From: Hamad Abbasi Date: Wed, 1 Jul 2026 18:01:09 +0500 Subject: [PATCH] feat: ship API shell on fallback stub, resolve Vercel/PyTorch hosting decision, pin deps, update docs --- README.md | 7 +++++-- api/_shared.py | 3 +++ docs/HOSTING_DECISION.md | 20 ++++++++++++++++++++ docs/KNOWN_ISSUES.md | 28 ++++++++++++++++++++++++++++ docs/RUN_LOCALLY.md | 13 +++++++++---- requirements-neural.txt | 6 ++++++ requirements.txt | 11 +++++++---- vercel.json | 2 -- 8 files changed, 78 insertions(+), 12 deletions(-) create mode 100644 docs/HOSTING_DECISION.md create mode 100644 requirements-neural.txt diff --git a/README.md b/README.md index 897fa50..72a9553 100644 --- a/README.md +++ b/README.md @@ -52,7 +52,7 @@ CalculusSolver/ ## Installation & Local Development ### 1. Minimal Installation (Fallback Mode) -For development, testing, and standard Vercel deployments, install the lightweight dependencies: +For development, testing, and standard Vercel deployments, install the lightweight dependencies. Local dev and Vercel use `requirements.txt` only. Neural/local training uses `requirements-neural.txt` (see below) — do not install it before deploying to Vercel. ```bash pip install -r requirements.txt ``` @@ -63,7 +63,7 @@ uvicorn api.app:app --reload --port 8000 ``` ### 2. Full Neural Installation (Optional) -If you want to run neural inference locally with model weights, install the neural requirements: +If you want to run neural inference locally with model weights, install the neural requirements (which includes PyTorch and NumPy): ```bash pip install -r requirements-neural.txt ``` @@ -163,3 +163,6 @@ Deploying the CalculusSolver API to Vercel is simple. You can use the Vercel CLI vercel ``` Or connect your GitHub repository containing this codebase directly to your Vercel dashboard. Vercel will automatically read `vercel.json`, build the serverless functions using `@vercel/python`, and expose the endpoints. + +### Hosting & Deployment Decision +See [docs/HOSTING_DECISION.md](docs/HOSTING_DECISION.md) for details on why the PyTorch model is excluded from the Vercel serverless deployment and the API uses `FallbackSolver` by default. diff --git a/api/_shared.py b/api/_shared.py index 3614630..76dc263 100644 --- a/api/_shared.py +++ b/api/_shared.py @@ -108,6 +108,9 @@ def _resolve_model_path(): return None, None +# NOTE: keep `groq` and `torch` imports lazy (inside the branches below). +# The Vercel build only installs requirements.txt (no torch/groq-heavy deps). +# A top-level import here will break every serverless function at import time. def get_solver(): """ Lazy-load and return the solver singleton. diff --git a/docs/HOSTING_DECISION.md b/docs/HOSTING_DECISION.md new file mode 100644 index 0000000..411536a --- /dev/null +++ b/docs/HOSTING_DECISION.md @@ -0,0 +1,20 @@ +# Hosting Decision — Neural Model vs Vercel Serverless + +## Constraint +Vercel Python serverless functions cap deployment size at 250MB unzipped. +torch + numpy + model.pkl exceed this by 2-3x. Confirmed not feasible to +run the neural path (`inference/solve.py`) inside a Vercel function. + +## Decision +- Production (Vercel): FallbackSolver only, optionally Groq if + GROQ_API_KEY is set. No torch/numpy in requirements.txt. +- Neural mode (`model/`, `train.py`, checkpoints) is local-dev / + research only, gated behind `requirements-neural.txt`. +- Revisit self-hosting the neural model as a separate service only if + product requirements demand it. + +## Why this doesn't limit functionality today +`FallbackSolver` already covers diff, partial, integrate, gradient, +tangent_line for polynomial expressions — the full scope described in +README.md's "Key Features". Neural mode is an accuracy upgrade for +non-polynomial rules (trig, exp, log), not a hard requirement for launch. diff --git a/docs/KNOWN_ISSUES.md b/docs/KNOWN_ISSUES.md index 7411c14..f591bca 100644 --- a/docs/KNOWN_ISSUES.md +++ b/docs/KNOWN_ISSUES.md @@ -99,6 +99,34 @@ print("STRUCT:OPEN correctly registered at ID 23") --- +## [RESOLVED] Vercel build fails due to empty website/ directory + +**Discovered:** During deployment packaging audit (Task 4) +**Fixed:** Removed website build steps from vercel.json +**Severity:** High — completely blocks Vercel deployment +**Affected path:** Deployment / API hosting + +### What was wrong + +`vercel.json` contained a `buildCommand` (`cd website && npm install && npm run build`) and an `outputDirectory` (`website/dist`). However, the `website/` directory in this repository is an uninitialized or empty submodule with no `package.json`. + +### Why it mattered + +Vercel's build process executes the `buildCommand` before attempting to deploy any serverless functions. Because `npm install` fails in an empty directory without a package definition, the entire build process would crash. This prevented the Python API functions under `api/` from ever being built or deployed, resulting in a completely broken deployment pipeline. + +### The fix + +Since the focus is currently on an API-only deployment (and the frontend is either non-existent or managed elsewhere), the `buildCommand` and `outputDirectory` keys were entirely removed from `vercel.json`. Vercel now correctly defaults to only building the Python functions defined in the `builds` array. + +### Files changed + +| File | Change | +|---|---| +| `vercel.json` | Removed `buildCommand` and `outputDirectory` keys | +| `docs/KNOWN_ISSUES.md` | Added this entry | + +--- + ## Filing new issues To add a new entry, copy the template below and fill it in: diff --git a/docs/RUN_LOCALLY.md b/docs/RUN_LOCALLY.md index dda836a..53622f6 100644 --- a/docs/RUN_LOCALLY.md +++ b/docs/RUN_LOCALLY.md @@ -2,10 +2,15 @@ This guide walks you through running the CalculusSolver backend locally, using Groq as the primary model. +> **Note:** A GROQ_API_KEY is optional. Without one, the API runs in +> `fallback` mode (deterministic polynomial solver) — fully functional +> for diff/partial/integrate/gradient/tangent_line. See DATASET_REPORT.md +> for the current rule coverage gap between fallback and neural modes. + ## Prerequisites - **Python 3.10+** - **Git** -- A **Groq API Key** (You can obtain one from the [Groq Console](https://console.groq.com/keys)) +- (Optional) A **Groq API Key** for intelligent LLM-backed solving (obtain from [Groq Console](https://console.groq.com/keys)) ## Setup Instructions @@ -32,9 +37,9 @@ This guide walks you through running the CalculusSolver backend locally, using G pip install -r requirements.txt ``` -4. **Configure Environment Variables** - The application requires a Groq API key to process complex calculus requests intelligently. - Create a `.env` file in the root of the project or export the variable in your shell: +4. **Configure Environment Variables (Optional)** + The application can use a Groq API key to process complex calculus requests intelligently. + If you want to use Groq, create a `.env` file in the root of the project or export the variable in your shell: ```bash # Linux/macOS export GROQ_API_KEY="your-groq-api-key-here" diff --git a/requirements-neural.txt b/requirements-neural.txt new file mode 100644 index 0000000..5eb80e3 --- /dev/null +++ b/requirements-neural.txt @@ -0,0 +1,6 @@ +# Local-dev / research only. NOT installed on Vercel. +# Needed to run inference/solve.py, model/, train.py. +-r requirements.txt +torch==2.3.1 +numpy==1.26.4 +joblib==1.4.2 diff --git a/requirements.txt b/requirements.txt index b917c64..3ba7439 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,4 +1,7 @@ -starlette>=0.37.0 -uvicorn>=0.29.0 -python-dotenv>=1.0.0 -groq>=0.5.0 +# Production / Vercel requirements — keep this file free of torch, numpy, +# or any package that pushes the serverless bundle over Vercel's size limit. +# See docs/HOSTING_DECISION.md. +starlette==1.3.1 +uvicorn==0.49.0 +python-dotenv==1.2.2 +groq==1.5.0 diff --git a/vercel.json b/vercel.json index a00ec7a..7a5c85d 100644 --- a/vercel.json +++ b/vercel.json @@ -1,7 +1,5 @@ { "version": 2, - "buildCommand": "cd website && npm install && npm run build", - "outputDirectory": "website/dist", "builds": [ { "src": "api/index.py",