feat: ship API shell on fallback stub, resolve Vercel/PyTorch hosting, decision, pin deps, update docs

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.

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.

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.

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:

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"

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

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

vercel.json

@@ -1,7 +1,5 @@
 {
   "version": 2,
-  "buildCommand": "cd website && npm install && npm run build",
-  "outputDirectory": "website/dist",
   "builds": [
     {
       "src": "api/index.py",