README.md

metadata

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

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:

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

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:

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:

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:

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:

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

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

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:

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:

cd shambasense-ai-2/backend
pip install -r requirements.txt
pip install pytest httpx
pytest -q

Frontend syntax and static checks:

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.