Spaces:
Running
Running
|
Download README.md from QuantModelDev/shambasense-ai-2: direct link, hf CLI and curl.
- Browser
- Download file 8.7 kB
-
https://huggingface.co/spaces/QuantModelDev/shambasense-ai-2/resolve/main/README.md
- Command line
-
hf download hf://spaces/QuantModelDev/shambasense-ai-2/README.md
-
curl -L -o README.md https://huggingface.co/spaces/QuantModelDev/shambasense-ai-2/resolve/main/README.md
8.7 kB
| title: ShambaSense AI | |
| emoji: π± | |
| colorFrom: green | |
| colorTo: yellow | |
| sdk: static | |
| pinned: false | |
| # ShambaSense AI | |
| ShambaSense AI is a crop-health screening tool for Kenyan smallholder farmers. The user interface runs on a Hugging Face **Static Space** and sends image-analysis requests to a separate Python **FastAPI service on Render**. The browser never runs Python, PyTorch, or model inference. | |
| > **Safety:** This is a screening aid, not a confirmed agricultural diagnosis. Model confidence is not proof that a disease is present. Consult a qualified local agricultural extension officer before treatment, especially for severe or uncertain cases. | |
| ## Architecture | |
| ```text | |
| Hugging Face Static Space | |
| index.html + style.css + app.js | |
| | | |
| | HTTPS multipart/form-data | |
| v | |
| Render Web Service | |
| backend/main.py + backend/inference.py | |
| | | |
| v | |
| Transformers/PyTorch model | |
| neghani/plantvillage-mobilenetv2 | |
| ``` | |
| Repository structure: | |
| ```text | |
| shambasense-ai-2/ | |
| βββ index.html | |
| βββ style.css | |
| βββ app.js | |
| βββ README.md | |
| βββ render.yaml # authoritative Render Blueprint | |
| βββ data/guidance_sources.json | |
| βββ backend/ | |
| βββ main.py | |
| βββ inference.py | |
| βββ guidance.py | |
| βββ requirements.txt | |
| βββ README.md | |
| βββ tests/test_api.py | |
| ``` | |
| ## Implemented frontend features | |
| - Responsive, accessible static UI for mobile, tablet, and desktop. | |
| - English/Kiswahili language switching. | |
| - Drag-and-drop and file-picker upload with preview and removal. | |
| - JPEG, PNG, and WEBP validation with a 10 MB client-side limit. | |
| - Crop metadata for maize, tomato, potato, beans, banana, and other/unknown. | |
| - Symptom notes, loading/error states, local field history, and TXT/JSON reports. | |
| - No predictions are shown unless the backend returns valid model output. | |
| - Photos are not stored in browser history or reports. | |
| ## AI model and limitations | |
| The backend reuses the existing public model: | |
| [`neghani/plantvillage-mobilenetv2`](https://huggingface.co/neghani/plantvillage-mobilenetv2) | |
| Its actual labels include maize/corn, potato, and tomato classes. Beans and banana are accepted as field metadata, but this model does not provide validated disease classes for them. The model was trained on curated PlantVillage-style images and may perform poorly on real field photographs, unfamiliar varieties, mixed symptoms, or poor lighting. | |
| The backend reports `503 model_unavailable` if the model cannot load. It never substitutes a mock classifier or fabricated confidence. | |
| ## Deployment order | |
| ### 1. Deploy the Render backend first | |
| The repository-root `render.yaml` is the only Render configuration. It defines a Python Web Service with `rootDir: backend`: | |
| ```yaml | |
| buildCommand: pip install -r requirements.txt | |
| startCommand: uvicorn main:app --host 0.0.0.0 --port $PORT | |
| healthCheckPath: /health | |
| ``` | |
| In Render, create a Web Service from this repository and apply the Blueprint, or enter the equivalent settings: | |
| | Render setting | Value | | |
| | --- | --- | | |
| | Runtime | Python | | |
| | Root Directory | `backend` | | |
| | Build Command | `pip install -r requirements.txt` | | |
| | Start Command | `uvicorn main:app --host 0.0.0.0 --port $PORT` | | |
| | Health Check Path | `/health` | | |
| | Python version | `3.11.11` via `PYTHON_VERSION` in the root `render.yaml` | | |
| Set these environment variables in Render: | |
| | Variable | Required | Purpose | | |
| | --- | --- | --- | | |
| | `MODEL_ID` | No | Defaults to `neghani/plantvillage-mobilenetv2`. | | |
| | `FRONTEND_ORIGIN` | Yes for deployed browser calls | Exact Space origin, for example `https://quantmodeldev-shambasense-ai-2.hf.space`. Multiple origins may be comma-separated. | | |
| | `HF_TOKEN` | No | Only needed if you replace the public model with a private model. Store it as a Render secret; never expose it to the browser. | | |
| | `PYTHON_VERSION` | Set by Blueprint | `3.11.11`, matching the pinned PyTorch wheel. | | |
| Wait for `/health` to respond. `status: "ready"` means the model has loaded; `unavailable` means it is not configured or failed to load. The first health check can be slow while Transformers downloads model files. | |
| **Memory limitation:** PyTorch and Transformers require substantially more memory than the static frontend. Check Render's current free-plan RAM and runtime limits before relying on this service for real farmer traffic. A cold start may reload the model. | |
| ### 2. Configure the frontend | |
| After Render provides the actual service URL, edit the single central setting near the top of `app.js`: | |
| ```javascript | |
| const API_BASE_URL = "https://YOUR-RENDER-SERVICE.onrender.com"; | |
| ``` | |
| Replace the placeholder with the exact HTTPS Render URL. Do not add `/api/v1/predict` to this line; the frontend appends that route itself. Do not put `HF_TOKEN` or any private key in `app.js`. | |
| ### 3. Push the Static Space | |
| From this directory: | |
| ```bash | |
| git add index.html style.css app.js README.md render.yaml backend | |
| git commit -m "Connect ShambaSense static frontend to FastAPI backend" | |
| git push origin main | |
| ``` | |
| The Hugging Face Space continues to use `sdk: static` and serves the root `index.html`. | |
| ## API endpoints | |
| - `GET /` β service status. | |
| - `GET /health` β model configuration/loading status. | |
| - `GET /api/v1/info` β API version, model ID, and supported crop metadata. | |
| - `POST /api/v1/predict` β accepts multipart fields: | |
| - `image`: JPEG, PNG, or WEBP file | |
| - `crop`: `maize`, `tomato`, `potato`, `beans`, `banana`, or `other` | |
| - `symptoms`: optional text up to 600 characters | |
| - `language`: `en` or `sw` | |
| Example: | |
| ```bash | |
| curl -X POST "https://YOUR-RENDER-SERVICE.onrender.com/api/v1/predict" \ | |
| -F "image=@leaf.jpg" \ | |
| -F "crop=tomato" \ | |
| -F "symptoms=yellow spots after rain" \ | |
| -F "language=en" | |
| ``` | |
| The response contains only model-derived `diagnosis`, `confidence`, and top predictions, plus guidance from the existing conservative guidance logic. A model loading failure returns a structured `503` response. | |
| ## Local development | |
| ### Frontend | |
| ```bash | |
| cd shambasense-ai-2 | |
| python3 -m http.server 8000 | |
| ``` | |
| Open <http://127.0.0.1:8000>. Until `API_BASE_URL` is changed, the page deliberately shows that backend inference is unavailable. | |
| ### Backend | |
| ```bash | |
| cd shambasense-ai-2/backend | |
| python3.11 -m venv .venv | |
| source .venv/bin/activate | |
| pip install -r requirements.txt | |
| export MODEL_ID=neghani/plantvillage-mobilenetv2 | |
| export FRONTEND_ORIGIN=http://localhost:8000 | |
| uvicorn main:app --reload --port 8000 | |
| ``` | |
| The backend and frontend cannot use the same local port. Use a different frontend port, for example: | |
| ```bash | |
| cd shambasense-ai-2 | |
| python3 -m http.server 8080 | |
| export FRONTEND_ORIGIN=http://localhost:8080 | |
| ``` | |
| ## Testing | |
| Backend tests use a controlled test double only for the successful-inference case: | |
| ```bash | |
| cd shambasense-ai-2/backend | |
| pip install -r requirements.txt | |
| pip install pytest httpx | |
| pytest -q | |
| ``` | |
| Frontend syntax and static checks: | |
| ```bash | |
| cd shambasense-ai-2 | |
| node --check app.js | |
| python3 - <<'PY' | |
| from pathlib import Path | |
| from html.parser import HTMLParser | |
| HTMLParser().feed(Path("index.html").read_text()) | |
| assert Path("style.css").exists() | |
| assert Path("app.js").exists() | |
| print("Static assets are valid") | |
| PY | |
| ``` | |
| These tests do not claim that the live Render model loaded successfully. Test that separately through `/health` and a real, suitable leaf image. | |
| ## Troubleshooting | |
| - **Frontend says backend unavailable:** replace `API_BASE_URL` in `app.js` with the actual HTTPS Render URL and redeploy the Static Space. | |
| - **CORS errors:** set `FRONTEND_ORIGIN` to the exact Space origin, without a trailing slash, then redeploy/restart Render. | |
| - **`503 model_unavailable`:** inspect Render logs and `/health`; verify `MODEL_ID`, model access, available RAM, and cold-start completion. | |
| - **Slow first request:** Transformers downloads model files on first load. Render may also sleep or restart a free service. | |
| - **No predictions for beans or banana:** the current model does not contain validated classes for those crops. Use a model trained and evaluated for them before presenting those results. | |
| - **Reports/history disappear:** they are browser-local and are not synchronized to a database. | |
| ## Privacy | |
| Field history remains in the current browser's local storage. Raw photos are not stored there. When the backend is configured, the selected image and symptom note are sent to the Render service for inference. Do not enter unnecessary personal information. Review the backend hosting and model provider policies before collecting real farmer data. | |
| Guidance provenance is retained in `data/guidance_sources.json`, including KALRO, FAO Plant Production and Protection, and the original model card. | |