---
title: AgroSense
emoji: 🌱
colorFrom: green
colorTo: yellow
sdk: docker
app_port: 7860
pinned: false
short_description: Offline-first AI farming advisor for India
---

# 🌱 AgroSense — RAG-Based Agriculture Farming Advisor

A working implementation of the **AgroSense** concept from the project report: a
Retrieval-Augmented Generation (RAG) advisor that answers farmer questions with
**grounded, cited** guidance drawn from an agriculture knowledge base.

This is the **Phase 1 MVP** (text interface, offline) — built as a full stack:

```
Knowledge Base (JSON)  ->  Embeddings  ->  Vector Store  ->  Retrieve + Re-rank  ->  Grounded Generation (cited)
                                                                                          |
                          Modern Web App (SPA) / Streamlit UI / CLI  <----  FastAPI  <----  RAGEngine
```

## 🖥️ Modern web app

A responsive single-page dashboard (no build step — modern HTML/CSS/vanilla JS in
[web/](web/)) is **served by FastAPI itself**. Start the API and open it:

```powershell
uvicorn api.main:app --reload      # then open:
#   http://127.0.0.1:8000/ui/       (the web app)
#   http://127.0.0.1:8000/docs      (API docs)
```

It covers every feature via the API: the date/calendar/IST header, news + commodities
tickers, the advisor chat with a **speaking avatar** ("AgroBot" — an animated SVG
mascot that reads answers aloud via the browser's Web Speech API, keyless and
multilingual, with an Auto-speak toggle), a **Location intel** dashboard (weather · satellite · NDVI ·
environment · sky · hazards · advisories), market prices, and the **Plant clinic** —
AI image diagnosis + telemedicine that escalates to a **live verified plant doctor**
(expert routing, video room, chat) in one tab.

There is also a polished **marketing landing page** (the campaign destination) at
**`/landing`** ([web/landing/index.html](web/landing/index.html)) — hero, features,
how-it-works, audience segments, CTAs into the app, and the downloadable campaign kit.
A headless render test lives at [web/smoke.mjs](web/smoke.mjs) (`node web/smoke.mjs`,
needs `npm i jsdom`). The Streamlit UI (`streamlit run ui/app.py`) and CLI remain as
alternatives.

### 📘 Documentation & marketing kit (Word + PDF, downloadable)

A full set of documents is provided in **both Word and PDF**, with download links in
the web app header. They live in [docs/](docs/):

| Document | What it covers |
| --- | --- |
| **User Manual** | End-user guide to every feature/tab |
| **Technical Guide** | Architecture, modules, API, config, extending, deployment, security |
| **Standard Operating Procedure (SOP)** | Operational runbook: start/stop, monitoring, KB + doctor admin, incident response, backup/recovery |
| **Go-to-Market & Monetization Plan (India)** | Freemium tiers, pricing, monetization streams, 3-year financial projection, unit economics, GTM strategy |
| **Instagram Campaign** | Reels/storyboards, voiceover + audio direction, captions, hashtags |
| **Facebook Campaign** | Page, Groups, Meta Ads + Lead Ads, ad copy |
| **LinkedIn (B2B) Campaign** | FPOs, agri-input partners, investors, enterprise/API |
| **30-Day Content Calendar** | Post-launch monthly plan with recurring series |

Served at `GET /downloads/{user-manual|technical-guide|sop|gtm-plan|instagram-campaign|`
`facebook-campaign|linkedin-campaign|content-calendar}.{pdf|docx}`. All share a
renderer ([scripts/docgen.py](scripts/docgen.py)) so the two formats never drift.
**Regenerate everything with one command:**

```powershell
pip install python-docx fpdf2
python scripts/build_docs.py
```

### ⚙️ Admin — configure the knowledge base

The web app has an **Admin** tab to add / edit / delete knowledge-base entries. Saving
persists to [data/knowledge_base.json](data/knowledge_base.json) and **rebuilds the
live vector index**, so new guidance is retrievable immediately. Admin endpoints are
token-gated (`X-Admin-Token` header):

```
GET /admin/kb · POST /admin/kb · PUT /admin/kb/{id} · DELETE /admin/kb/{id}
```

Set the token with `AGROSENSE_ADMIN_TOKEN` (defaults to `admin` for the local POC —
**change it** for any shared deployment). Logic lives in
[agrosense/kb_admin.py](agrosense/kb_admin.py); validation requires at least `crop`
and `source`.

### Live local weather (optional, no API key)

Provide a **location** and AgroSense attaches a real-time forecast + farming
advisory from **[Open-Meteo](https://open-meteo.com/)** (free, **no API key**),
implementing the report's Data Layer "dynamic (weather) data" source:

```powershell
python cli.py --location Belagavi "I grow cotton on black soil — fertilizer and pest steps?"
```

The advisory is computed strictly from the forecast numbers (e.g. *"rain likely on
2026-05-30 — postpone foliar sprays and nitrogen top-dressing to avoid wash-off"*),
so it stays as trustworthy as the KB-grounded advice. If there's no internet (or the
place can't be resolved), weather is silently skipped and the KB answer is unaffected.

### Satellite monitoring (optional, no API key)

Provide a location and AgroSense pulls **real satellite monitoring** from two free,
keyless NASA sources:

- **NASA GIBS** — MODIS **true-color** and **NDVI** (vegetation greenness) imagery
  for your area's bounding box, plus a one-click NASA Worldview link.
- **NASA POWER** — satellite-derived **agroclimate** (solar radiation, temperature,
  rainfall) for the point, with number-grounded notes (e.g. *"ample solar radiation
  — good for growth"*, *"very little rainfall — check soil moisture"*).

```powershell
python cli.py --location Belagavi --satellite "How is my paddy field doing?"
```

In the UI, set a location and tick **🛰️ Show satellite monitoring** to see the
imagery and agroclimate panel.

### Field-level numeric NDVI (optional, Google Earth Engine)

For a true **per-field Sentinel-2 (~10 m) NDVI time series** — latest value, mean,
trend, and a health status (`healthy/dense` · `moderate` · `sparse/stressed`) —
AgroSense integrates **Google Earth Engine**. It is fully optional and **credential-
gated**: with no credentials the app silently uses MODIS NDVI imagery + POWER
agroclimate instead (see [agrosense/ndvi.py](agrosense/ndvi.py)).

**Enable it:**

```powershell
pip install earthengine-api

# Option A — user / default credentials (after a one-time browser auth):
earthengine authenticate
$env:AGROSENSE_EE_PROJECT = "your-gcp-project-id"

# Option B — service account (for servers / CI, no browser):
$env:AGROSENSE_EE_SERVICE_ACCOUNT = "agro@your-project.iam.gserviceaccount.com"
$env:AGROSENSE_EE_KEY_FILE        = "C:\path\to\service-account-key.json"
$env:AGROSENSE_EE_PROJECT         = "your-gcp-project-id"
```

Then any satellite request (UI checkbox, `--satellite`, or `GET /satellite`) adds a
`numeric_ndvi` block with the time series, trend, and number-grounded notes (e.g.
*"NDVI is trending down — investigate for stress, senescence, or recent harvest"*).
Tunables: `AGROSENSE_NDVI_DAYS` (60), `AGROSENSE_NDVI_BUFFER_M` (100 m field radius),
`AGROSENSE_NDVI_MAX_CLOUD` (40%). The architecture is provider-agnostic — swap in
Sentinel Hub by adding a sibling provider in [agrosense/ndvi.py](agrosense/ndvi.py).

Cloud handling is two-layer: scenes are filtered by `CLOUDY_PIXEL_PERCENTAGE`, **and**
clouds/shadows/cirrus/snow are masked **per pixel** via the Sentinel-2 SCL band
(`build_scl_mask`), so cloud over the field can't skew the field-mean NDVI.

### Location environment profile

Display a full environment readout for a place or lat/lon — **keyless** (Open-Meteo):

| Field | Source | Notes |
| --- | --- | --- |
| Longitude, Latitude | geocoding | |
| Altitude (sea level) | geocoding / elevation API | metres |
| Local population | geocoding | of the resolved place |
| Humidity | forecast `current` | % |
| Sunlight | forecast | sunshine hours/day, UV-index max, live solar W/m² |
| Wind speed & direction | forecast `current` | km/h + 16-point compass |
| Air quality | Air Quality API | US/EU AQI, PM2.5, PM10, ozone + category |
| Pollen | Air Quality API | **Europe-only (CAMS)** — shows "not available for this region" elsewhere |
| Ground water level | CGWB / data.gov.in (keyed) | real nearest-well water-table depth when `AGROSENSE_GROUNDWATER_RESOURCE` + `AGROSENSE_DATAGOV_API_KEY` are set ([agrosense/groundwater.py](agrosense/groundwater.py)); otherwise a labelled **soil-moisture proxy** (3–9 cm) |

```powershell
python cli.py --location Belagavi --environment "..."
```

Endpoint: `GET /environment?location=…` or `?latitude=…&longitude=…`. UI: tick
**🌍 Show location environment**. See [agrosense/environment.py](agrosense/environment.py).

**Real ground-water level (optional):** set a CGWB "depth to water level" resource id
and a data.gov.in key to replace the proxy with an actual nearest-observation-well
water-table depth:

```powershell
$env:AGROSENSE_DATAGOV_API_KEY       = "your-data.gov.in-key"
$env:AGROSENSE_GROUNDWATER_RESOURCE  = "<cgwb-resource-id>"
$env:AGROSENSE_GROUNDWATER_STATE     = "Karnataka"   # optional server-side filter
```

The nearest-well geometry (haversine + parsing) is unit-tested; the live fetch is
mock-tested. **Caveat:** CGWB data is station-based and ~quarterly (not real-time),
and resource field names vary — confirm your resource's schema (see
[agrosense/groundwater.py](agrosense/groundwater.py)).

### Natural-hazard events & active fires (NASA EONET + FIRMS)

Shows natural-hazard events and active fires near the location:
- **NASA EONET** — **keyless** open natural events (wildfires, severe storms, floods,
  drought, dust/haze…) filtered to a radius of the farm and sorted by distance.
- **NASA FIRMS** — active fire / thermal anomalies (VIIRS/MODIS); needs a **free
  map-key** (`AGROSENSE_FIRMS_MAP_KEY`) — shows "set key to enable" otherwise.

UI: tick **⚠️ Show hazards & fires**. `GET /hazards?location=…` (or lat/lon).
See [agrosense/hazards.py](agrosense/hazards.py).

### Plant-disease, plant-ID & pest vision

Upload a leaf/plant/insect photo (UI: **🌿 Plant image diagnosis**, or
`POST /vision/classify?task=all`) to get three classifications — **disease/health**,
**plant ID**, and **pest ID**:
- With trained models configured (`AGROSENSE_VISION_DISEASE_MODEL` / `_PLANT_MODEL` /
  `_PEST_MODEL`) and TensorFlow installed, real CNN inference runs.
- Without them, an **honest Pillow colour heuristic** gives a leaf-health indication
  (clearly labelled "not a diagnosis"); plant-ID and pest-ID report that a trained
  model is required. See [agrosense/vision.py](agrosense/vision.py).

**Train the models** (needs TensorFlow + datasets — run outside this sandbox) with
[scripts/train_plant_models.py](scripts/train_plant_models.py):
- **disease** → PlantVillage (~54k images, 38 classes)
- **plant** → any per-class leaf/plant folder dataset (Flavia, Oxford-102…)
- **pest** → **IP102** (~75k images, 102 crop-pest classes) or the Kaggle
  "Agricultural Pests Image Dataset" (12 classes)

Point the env vars at the resulting `.keras` + labels files to activate real inference.

> Note: this Python 3.14 POC has Pillow + numpy but **not** TensorFlow/ONNX, so only
> the heuristic path runs here; the model backend activates wherever TF is available.

### Plant telemedicine (diagnosis → prescription)

A clinician-style consult that fuses the image diagnosis (disease/pest vision) +
symptom intake + the KB's treatment fields + weather-aware timing into a structured
**diagnosis → health assessment → prescription → follow-up**:

- Intake: crop, free-text symptoms, optional leaf photo, location.
- Assessment: diagnosis (from image and/or symptom keywords), health status, severity.
- **Diagnosis-driven prescription**: a recognized disease/pest **class** — from the
  vision model's predicted label (e.g. PlantVillage `Tomato___Late_blight`) or from
  symptom text that names the condition — is mapped to a **targeted IPM prescription**
  via [agrosense/ipm.py](agrosense/ipm.py) + [data/ipm_prescriptions.json](data/ipm_prescriptions.json)
  (e.g. *"Late blight → spray Mancozeb 0.25%…"*). This specific treatment is listed
  first, then the crop's KB-grounded steps follow.
- **Prescription**: treatment + nutrition + cultural/IPM steps composed **only** from
  the IPM lookup and retrieved KB fields (dosages verbatim, every line cited) — never invented.
- Weather-aware timing (e.g. "rain likely → postpone foliar sprays") + a clear
  **safety disclaimer** (decision support, not a substitute for an expert).

UI: sidebar **🩺 Plant telemedicine** (crop + symptoms + the uploaded photo) →
consultation card. `POST /telemedicine` (multipart: crop/symptoms/location + optional
image). See [agrosense/telemedicine.py](agrosense/telemedicine.py).

### Farmers' digital clubs

**Location-wise** and **commodity-wise** farmer communities (👥 Clubs tab). Browse/filter
clubs by location or commodity, **create** a club, **join**, post to a **discussion feed**
and **share information/links**, and start a **live video meeting** (Jitsi room per club,
keyless). Each club has members, a feed, and its own meeting room. Seeded with starter
clubs (Karnataka/Maharashtra; Tomato/Cotton/Coffee/Paddy). API: `GET/POST /clubs`,
`GET /clubs/{id}`, `POST /clubs/{id}/join`, `POST /clubs/{id}/post`. See
[agrosense/clubs.py](agrosense/clubs.py) (persisted to `data/clubs.json`).

### Live agri-doctor consultation

Escalate from the AI consult to a **human expert**: a consultation request is **routed
to a matching available expert** (pest → entomologist, disease → pathologist, etc.,
honoring language), attaches the **AI telemedicine consult as context**, and opens a
**live video room** (Jitsi, keyless) plus an in-app **chat thread**.

UI: sidebar **👨‍⚕️ Live agri-doctor** (name + channel + language) → session card with
the assigned expert, a *Join live video room* button, and chat. API: `GET /experts`,
`POST /consult/request`, `GET /consult/{id}`, `POST /consult/{id}/message`. See
[agrosense/consultation.py](agrosense/consultation.py) + [data/agri_experts.json](data/agri_experts.json).

**Onboarding & verification:** anyone can **apply to become a plant doctor**
(`POST /doctors/apply`, status `pending`); an **admin verifies** them
(`POST /admin/doctors/{id}/verify`, token-gated) — and only **verified** doctors enter
the consultation directory (`GET /experts`) and can be routed live consults.
Applications require name, specialization, region, contact, languages, credentials,
and a format-checked **ICAR / registration number**; routing tags are derived from the
specialization.

**Profiles & ratings:** each verified doctor has a public **profile page**
(`GET /doctors/{id}`) showing specialization, region, languages, registration number,
and an aggregate **star rating** with recent reviews; farmers rate a doctor
(`POST /doctors/{id}/rate`, 1-5 stars + comment). Ratings show in the directory and on
the profile. The web app has an *Apply as a plant doctor* form + *View profile* with a
rating widget (in the Plant clinic tab's live-doctor section) and a *Plant doctor
verification* panel (Admin tab).
Backed by [agrosense/doctors.py](agrosense/doctors.py) (`data/plant_doctors.json`,
seeded from [data/agri_experts.json](data/agri_experts.json)).

**Expert notifications:** when a consult is routed, the assigned expert is notified —
always recorded in an in-app **audit log** (`GET /notifications`), and, when
configured, delivered via **webhook** (`AGROSENSE_NOTIFY_WEBHOOK` — Slack/Discord/
Zapier/custom, keyless) and/or **email** (`AGROSENSE_NOTIFY_EMAIL_TO` + SMTP env). See
[agrosense/notifications.py](agrosense/notifications.py).

> Honest scope: the experts are **demo/seed entries** — there are no real practitioners
> on the other end in the POC. Connecting real experts means populating the directory
> with availability + contact, and they'll be alerted via the notification channels
> above; the video room, chat, and notifications are functional. The default Jitsi room
> (meet.jit.si) may ask the first joiner to sign in as moderator — set
> `AGROSENSE_VIDEO_BASE` to a self-hosted Jitsi for production.

### Traditional Advisor (traditional knowledge + Panchang)

A **🪔 Traditional** advisor for daily farm activities that combines **Indian
traditional/desi practices** with **Panchang (astrological) guidance**. For an activity
(sowing, transplanting, harvesting, pest control, …) it gives:
- an **astrological suitability** verdict from today's Panchang — favourable nakshatras
  for sowing, waxing vs waning moon (Shukla/Krishna paksha), Vishti (Bhadra) karana and
  Amavasya/Rikta-tithi cautions — with the reasons, and
- relevant **traditional practices** (Beejamrit, Jeevamrit, lunar/nakshatra sowing, neem
  & panchagavya pest control, mixed cropping…), **matched to the area/region**.

`GET /traditional?activity=…&location=…` (keyless). See
[agrosense/traditional.py](agrosense/traditional.py) +
[data/traditional_knowledge.json](data/traditional_knowledge.json).

### Finance — bank assistance + government schemes & subsidies

A single **🏦 Finance** tab combines two things a farmer needs money-wise:

**Bank assistance & agri-loans.** A curated catalog of agri-credit products — KCC and
crop/production loans, term/investment loans, farm-mechanization, allied
(dairy/AH/fisheries), agri gold loans, warehouse-receipt finance, FPO & SHG credit, the
Agriculture Infrastructure Fund, solar-pump (PM-KUSUM) and horticulture loans. Each lists
**provider, interest, loan amount, tenure, benefits, eligibility, step-by-step application
process, documents, portal and helpline**. Browse/filter by **category** or search, then
**lodge a loan enquiry** (name + contact + requested amount) — applications are recorded
and visible to an admin in the ⚙️ Admin tab (`GET /admin/finance/applications`,
token-gated). API: `GET /finance?category=&provider=&search=`, `GET /finance/{id}`,
`POST /finance/{id}/apply`. See [agrosense/finance.py](agrosense/finance.py) +
[data/finance.json](data/finance.json) (enquiries persist to the gitignored runtime
`data/finance_applications.json`).

**Government schemes & subsidies.** Central and state agricultural schemes with the full
publication for each — **summary, benefits, eligibility, step-by-step application
process, documents required, official portal, helpline** — plus an
**announcements/updates** feed. Browse and filter by **level** (Central / State),
**state** (the sidebar Location surfaces schemes that apply to you — central schemes
always show), **category**, or free-text **search**; open any scheme for its full detail,
and see a **latest-announcements** feed aggregated across all schemes (newest first).
Seeded with 13 schemes — 10 central (PM-KISAN, PMFBY, KCC, PMKSY, Soil Health Card, SMAM,
PKVY, eNAM, AIF, PM-KMY) and 3 state (Krishi Bhagya/Karnataka, Rythu Bandhu/Telangana,
Magel Tyala Shettale/Maharashtra). Admins can **append updates** to a scheme
(`POST /admin/subsidies/{id}/update`, token-gated). API:
`GET /subsidies?level=&state=&category=&search=`, `GET /subsidies/{id}`,
`GET /subsidies/updates`. See [agrosense/subsidies.py](agrosense/subsidies.py) +
[data/subsidies.json](data/subsidies.json).

> Honest scope: both are **curated knowledge bases** (no reliable keyless live
> scheme/loan-rate feed exists). Interest rates, scheme amounts and rules are set by
> RBI/NABARD/banks and governments and change over time; **"apply" lodges an enquiry in
> AgroSense, not a bank/portal submission**. Each view carries a disclaimer to verify and
> apply through the bank or official portal.

### Land record search & documents

A **🗺️ Land records** tab to find your **State's official land-record system** and take
the exact steps to view/download your record. Land is a State subject, so the tab is a
**searchable directory** (15 states + an all-India fallback) giving, per state: the local
**record name** (RTC/Pahani, 7/12 Saatbara, Khatauni, Jamabandi, Patta/Chitta, …), the
official **portal** and **cadastral-map (Bhu-Naksha)** portal, **what to search by**
(district, taluk/tehsil, village, survey/khasra/khata number), **step-by-step** search &
download instructions, what the record **contains**, and the helpline. The sidebar
**Location** is geocoded to its state (or pick a state explicitly). You can also
**download a printable guide** (Word/PDF) for that state, generated on the fly.

API: `GET /land-records?location=&state=`, `GET /land-records/guide.{pdf|docx}?location=&state=`.
See [agrosense/land_records.py](agrosense/land_records.py) +
[data/land_records.json](data/land_records.json) (PDF/Word via the shared
[scripts/docgen.py](scripts/docgen.py) renderer).

> Honest scope: AgroSense **does not fetch or store your actual land record** — those
> live on each State's portal, usually behind a login/OTP/fee. This feature helps you
> **find and download yours from the official source**; always rely on the State portal's
> copy.

> This is cultural, belief-based knowledge offered as **complementary to — not a
> replacement for — scientific agronomy**, soil tests and local conditions. The
> nakshatra/yoga rely on an approximate ayanamsa (see the Panchang note above).

### Decision-fusion advisories

Fuse the live signals — **weather forecast + satellite agroclimate (NASA POWER) +
field NDVI** — into **prioritized, cross-signal, actionable** advisories that no
single source can give (e.g. *"NDVI trending down while rain is forecast → inspect
drainage and scout disease"*). Works by place name **or** latitude/longitude:

```powershell
python cli.py --location Belagavi --advisories "advice for my cotton field?"
```

Advisories are tagged by urgency (high/medium/low) and category (irrigation, spray,
disease, protection, monitoring), each with the **rationale** (which signals drove
it). The rule set lives in [agrosense/fusion.py](agrosense/fusion.py) as a pure
function over the fetched signals, so it is fully unit-tested.

**Crop- and stage-aware:** pass a `crop` and growth `stage`
(seedling/vegetative/flowering/maturity) and the thresholds + urgencies adapt per
[agrosense/crop_profiles.py](agrosense/crop_profiles.py) — e.g. tomato flags heat at
32°C while cotton tolerates 40°C, flowering/seedling stages escalate stress
advisories, and rain near *maturity* raises a harvest-quality warning.

```powershell
python cli.py --location Belagavi --advisories --stage flowering "advice for my tomato?"
```

Endpoint: `GET /advisories?location=…&crop=Tomato&stage=flowering` (or `latitude`/`longitude`).

### Planetary positions

Show the **Sun, Moon (with phase) and classical planets** (Mercury–Saturn) for the
location at the current time — altitude/azimuth, RA/Dec, and what's above the
horizon — useful for sky context and traditional/Panchang-style scheduling.

```powershell
python cli.py --location Belagavi --planets "..."
```

Computed locally with a pure-Python ephemeris (Schlyter's algorithm) — **keyless,
offline, no dependencies** ([agrosense/planetary.py](agrosense/planetary.py)),
validated in tests against known astronomy (solar declination ≈ +23.4° at the June
solstice). Endpoint: `GET /planetary?location=…` or `?latitude=…&longitude=…`.

### Multilingual answers (Phase 2)

Ask in — or get answers in — the report's Phase 2 languages (Hindi, Kannada,
Telugu, Tamil, Marathi, Bengali, Malayalam, Gujarati, Punjabi). The query is
translated to English for retrieval and the grounded answer is translated back:

```powershell
python cli.py --lang hi "What fertilizer should I use for maize?"
```

Backends (auto-selected, optional): **argostranslate** (fully offline) → **deep-
translator** (online, no key) → identity (English passthrough). If no backend is
installed, the answer simply stays English and the UI/CLI says so. See
[agrosense/translation.py](agrosense/translation.py).

### Real-time market prices (closes the report's last pain point)

Attach live mandi (Agmarknet) prices for the crop in a question — min/max/modal
₹/quintal across markets, with a "compare mandis" note when prices spread widely:

```powershell
python cli.py --prices "what's the price of tomato in Karnataka?"
```

Requires a **free data.gov.in api-key** (set `AGROSENSE_DATAGOV_API_KEY`); without
it, prices degrade gracefully to "unavailable". See
[agrosense/prices.py](agrosense/prices.py).

### 🤝 Farmer trading platform (in the Market tab)

A peer-to-peer **produce marketplace** inside the Market tab: farmers post **sell**
offers and buyers post **buy** requirements (commodity, quantity/unit, price, grade,
location/state, description). Anyone can **browse/filter** by type (sell|buy), commodity
or state, **open a listing**, **express interest** (an inquiry with contact + offer +
quantity), **negotiate live** in a per-listing **video room** (Jitsi, keyless), and the
poster can **mark it sold/closed** (closed listings drop out of the default browse). Live
mandi prices and the commodity ticker sit alongside in the same tab as a pricing
reference. Seeded with demo listings on first run.

API: `GET/POST /market/listings`, `GET /market/listings/{id}`,
`POST /market/listings/{id}/inquire`, `POST /market/listings/{id}/close`. See
[agrosense/trading.py](agrosense/trading.py) (persisted to `data/market_listings.json`,
gitignored runtime state).

> Honest scope: a **POC marketplace** — listings and seed buyers/sellers are
> demo/user-generated; there is **no payment, escrow, KYC or logistics**. Verify the
> other party and agree terms independently before transacting (the UI carries this
> disclaimer).

### 📻 Internet radio

A **Radio** tab lists online radio stations for India (Vivid Bharti, Radio Mirchi,
Red FM, AIR, regional/agriculture stations…) and plays them in an in-app audio player.
Keyless via the **Radio Browser** community API. `GET /radio?country=IN&search=…`. See
[agrosense/radio.py](agrosense/radio.py).

> This is **internet radio**, not over-the-air FM tuning (a browser has no RF
> hardware). Many FM/AIR stations stream online so the local station is often present,
> but coverage of small stations varies and some streams may be temporarily offline
> (filtered with `hidebroken=true` + popularity ordering). On an HTTPS deployment,
> plain `http://` streams are blocked as mixed content — prefer https streams or proxy.

### Date/time header + Reuters news ticker

The UI shows a top bar with the date in the **Gregorian (English)** calendar, the
**Indian National (Saka)** calendar with a mini-**Panchang** — lunar day (tithi),
nakshatra shown inline (e.g. "Shukla Purnima · Anuradha") and the full five limbs
(vaara, tithi, nakshatra, yoga, karana) in a hover tooltip, computed from the
ephemeris — and the current **IST** time, plus the Google News headline ticker.

- Calendar/IST logic: [agrosense/calendars.py](agrosense/calendars.py) (pure,
  unit-tested — the Gregorian→Saka conversion is exact). Endpoint `GET /datetime`.
- Headlines: [agrosense/news.py](agrosense/news.py) — Google News RSS, **keyless**,
  graceful empty list on failure. The UI has **region** (India/US/UK/Australia/
  Canada/Singapore) and **topic** (Top stories/Agriculture/Business/Technology/
  Science/Health/Sports/World) selectors above the ticker.
  `GET /news?region=US&query=technology&limit=15` — `region` selects the locale,
  `query`=None gives general top stories, or pass a topic/keyword (or a
  `site:reuters.com` filter for the Reuters feed).

Directly below the news scroll, a **slow-scrolling commodity ticker** shows
**Gold, Silver, Crude Oil, Coffee** (Yahoo Finance futures, **keyless**, with day
change %) and **Arecanut, Coconut** (Agmarknet via data.gov.in — show "n/a" until a
key is set). See [agrosense/commodities.py](agrosense/commodities.py); `GET /commodities`.

Below that, a **local weather strip** shows current conditions for the sidebar
location (temperature, humidity, today's range, rain chance, top advisory) — driven
by the same Open-Meteo forecast as the rest of the app.

The displayed time reflects the page render (updates on refresh/interaction).

### Evaluation harness (RAGAS-style, offline)

Measure the report's accuracy targets against a gold question→expected-source set:

```powershell
$env:AGROSENSE_EMBEDDING_BACKEND="hashing"; python scripts/evaluate.py
```

Reports context relevance, citation MRR, faithfulness, hallucination rate, answer
relevance, out-of-domain accuracy, and latency p50/p95 — each checked against the
report's targets (≥95% relevance/faithfulness, <5% hallucination, ≤3 s). Exits
non-zero if any target is missed (CI-friendly). Metrics are pure functions
([agrosense/evaluation.py](agrosense/evaluation.py)); the gold set is
[data/eval_set.json](data/eval_set.json).

> On the offline hashing-embedder POC the current set passes all targets (context
> relevance 100%, faithfulness 100%, hallucination 0%, p95 < 1 ms). Faithfulness is
> high by construction for the extractive generator; the harness's value is catching
> regressions and re-measuring once a real embedder/LLM is plugged in.

### Runs fully offline, no API keys, no internet

Every heavy dependency is **optional**. Out of the box the app uses:
- a deterministic **hashing embedder** (no model download), and
- a **numpy** cosine-similarity vector store (no FAISS), and
- an **extractive grounded generator** that composes answers *only* from retrieved
  KB fields and attaches citations — so it cannot hallucinate agronomic facts.

If you install the optional accelerators, the same code automatically upgrades:
- `pip install sentence-transformers` → better semantic embeddings
- `pip install faiss-cpu` → faster vector search

---

## Quick start

```powershell
# 1. (optional) create a venv, then install core deps
pip install -r requirements.txt

# 2a. Try it on the command line (no server needed)
python cli.py "My soil is sandy, rainfall 900 mm, I plan to grow maize. What fertilizer and pest steps?"

# 2b. Or run the interactive REPL
python cli.py

# 3. Run the API
uvicorn api.main:app --reload          # http://127.0.0.1:8000/docs

# 4. Run the chat UI (in another terminal)
streamlit run ui/app.py                # http://localhost:8501
```

The Streamlit UI calls the FastAPI backend if it's running, and otherwise falls
back to running the engine in-process — so the UI works on its own too.

### Run the tests

```powershell
python tests/test_rag.py     # or: python -m pytest
```

---

## How it maps to the report

| Report concept | Where it lives |
| --- | --- |
| Data Layer / Knowledge Base (structured JSON entries) | [data/knowledge_base.json](data/knowledge_base.json), [agrosense/knowledge_base.py](agrosense/knowledge_base.py) |
| Knowledge Layer (vectorized documents) | [agrosense/embeddings.py](agrosense/embeddings.py), [agrosense/vector_store.py](agrosense/vector_store.py) |
| Cognitive Layer — RAG pipeline (retrieval + re-ranking + generation) | [agrosense/retriever.py](agrosense/retriever.py), [agrosense/generator.py](agrosense/generator.py), [agrosense/rag.py](agrosense/rag.py) |
| Cognitive Layer — decision fusion (multi-signal advisories) | [agrosense/fusion.py](agrosense/fusion.py), [agrosense/crop_profiles.py](agrosense/crop_profiles.py) |
| Cognitive Layer — traditional advisor (Panchang + desi practices) | [agrosense/traditional.py](agrosense/traditional.py) |
| Data Layer — government schemes & subsidies (central + state, updates) | [agrosense/subsidies.py](agrosense/subsidies.py), [data/subsidies.json](data/subsidies.json) |
| Application Layer — agri finance (bank assistance / loans + apply) | [agrosense/finance.py](agrosense/finance.py), [data/finance.json](data/finance.json) |
| Data Layer — land records (state RoR portal directory + generated guide) | [agrosense/land_records.py](agrosense/land_records.py), [data/land_records.json](data/land_records.json) |
| Data Layer — planetary positions | [agrosense/planetary.py](agrosense/planetary.py) (pure-Python ephemeris) |
| Data Layer — hazards & fires | [agrosense/hazards.py](agrosense/hazards.py) (NASA EONET keyless + FIRMS keyed) |
| Cognitive Layer — plant vision | [agrosense/vision.py](agrosense/vision.py) (disease + plant ID + pest ID; Keras backend + heuristic) |
| Cognitive Layer — plant telemedicine | [agrosense/telemedicine.py](agrosense/telemedicine.py) (diagnosis + grounded, cited prescription) |
| Engagement Layer — live agri-doctor | [agrosense/consultation.py](agrosense/consultation.py) (expert routing + Jitsi video + chat) |
| Engagement Layer — farmers' clubs | [agrosense/clubs.py](agrosense/clubs.py) (location/commodity communities: feed + video + sharing) |
| RAG Workflow steps 1–7 (intake → preprocess → retrieve → re-rank → generate → cite) | [agrosense/rag.py](agrosense/rag.py) (`RAGEngine.answer`) |
| **CARO** — Context-Aware Retrieval Optimizer (metadata-weighted re-ranking) | `Retriever._rerank_score` in [agrosense/retriever.py](agrosense/retriever.py) |
| Data Layer — dynamic (weather) data | [agrosense/weather.py](agrosense/weather.py) (Open-Meteo, no key) |
| Data Layer — location environment | [agrosense/environment.py](agrosense/environment.py) (elevation, AQ, pollen, wind, groundwater proxy) |
| Data Layer — satellite / remote sensing | [agrosense/satellite.py](agrosense/satellite.py) (NASA GIBS + POWER, no key) |
| Data Layer — field-level NDVI (keyed) | [agrosense/ndvi.py](agrosense/ndvi.py) (Sentinel-2 via Google Earth Engine) |
| Data Layer — market prices | [agrosense/prices.py](agrosense/prices.py) (Agmarknet via data.gov.in) |
| Application Layer — farmer trading platform (P2P produce marketplace) | [agrosense/trading.py](agrosense/trading.py), `data/market_listings.json` |
| Engagement Layer — multilingual | [agrosense/translation.py](agrosense/translation.py) (argos / deep-translator) |
| Interaction Layer (conversational UI) | [ui/app.py](ui/app.py) |
| "Use only retrieved KB data. Include citations." system prompt | `SYSTEM_PROMPT` in [agrosense/generator.py](agrosense/generator.py) |
| Faithfulness / low-hallucination targets | extractive generator + relevance gate → off-domain queries get a safe fallback, never fabricated advice |
| Latency ≤ 3 s target | every response reports `latency_ms` (sub-millisecond on the offline backends) |

### Sample knowledge base
Covers paddy, maize, wheat, cotton, plus fertilizer schedules for aromatic
(mint, citronella), vegetable (tomato), fruit (banana) and flower (marigold) crops,
and a general soil-health entry — modeled on the report's KB design and the Azure
assistant examples shown in the document.

---

## Configuration

All tunable via environment variables (see [agrosense/config.py](agrosense/config.py)):

| Variable | Default | Purpose |
| --- | --- | --- |
| `AGROSENSE_EMBEDDING_BACKEND` | `auto` | `auto` \| `sentence-transformers` \| `hashing` |
| `AGROSENSE_GENERATION_BACKEND` | `extractive` | `extractive` (offline) \| `openai` (real LLM seam) |
| `AGROSENSE_TOP_K` | `5` | candidates from vector search |
| `AGROSENSE_RERANK_K` | `3` | kept after re-ranking |
| `AGROSENSE_KB_PATH` | `data/knowledge_base.json` | knowledge base location |
| `AGROSENSE_API_URL` | `http://127.0.0.1:8000` | API URL used by the UI |

### Plugging in a real LLM (production path)
`OpenAIGenerator` in [agrosense/generator.py](agrosense/generator.py) shows the seam.
Set `AGROSENSE_GENERATION_BACKEND=openai`, `pip install openai`, and provide
`OPENAI_API_KEY`. The same pattern adapts to Azure OpenAI (the report's `gpt-5-mini`
deployment). The retrieval context and the strict "use only the provided context,
cite sources" instruction are already wired in.

---

## Project layout

```
AgroSense/
├── data/knowledge_base.json     # the agriculture KB (structured JSON)
├── agrosense/                   # RAG core (the reusable library)
│   ├── config.py                # env-driven configuration
│   ├── embeddings.py            # hashing (offline) + sentence-transformers backends
│   ├── knowledge_base.py        # KB loading + document construction
│   ├── vector_store.py          # numpy fallback + FAISS backend
│   ├── retriever.py             # vector search + CARO-style re-ranking + relevance gate
│   ├── generator.py             # extractive grounded generator (+ OpenAI seam)
│   ├── weather.py               # live local forecast + advisory (Open-Meteo, no key)
│   ├── satellite.py             # satellite imagery + agroclimate (NASA GIBS + POWER)
│   ├── ndvi.py                  # field-level Sentinel-2 NDVI (Google Earth Engine, keyed)
│   ├── translation.py           # multilingual layer (argos / deep-translator / identity)
│   ├── prices.py                # mandi market prices (Agmarknet via data.gov.in, keyed)
│   ├── fusion.py                # decision-fusion advisories (weather + satellite + NDVI)
│   ├── crop_profiles.py         # per-crop thresholds + growth stages (crop-aware fusion)
│   ├── environment.py           # location environment profile (Open-Meteo, keyless)
│   ├── planetary.py             # Sun/Moon/planet positions (pure-Python ephemeris)
│   ├── groundwater.py           # real water-table depth (CGWB/data.gov.in, keyed)
│   ├── evaluation.py            # RAGAS-style eval metrics (pure) + evaluate()
│   ├── calendars.py             # Gregorian + Indian National (Saka) calendars + IST
│   ├── news.py                  # Google News headlines (region/topic, keyless)
│   ├── radio.py                 # internet radio stations (Radio Browser, keyless)
│   ├── commodities.py           # Gold/Silver/Oil/Coffee (Yahoo) + Arecanut/Coconut (Agmarknet)
│   ├── hazards.py               # NASA EONET events (keyless) + FIRMS fires (keyed)
│   ├── vision.py                # plant disease + ID + pest (Keras backend + Pillow heuristic)
│   ├── telemedicine.py          # plant consult: diagnosis + grounded, cited prescription
│   ├── ipm.py                   # recognized class -> exact IPM prescription lookup
│   ├── consultation.py          # live agri-doctor: expert routing + video + chat
│   ├── doctors.py               # plant-doctor onboarding + verification registry
│   ├── notifications.py         # expert alerts: in-app log + webhook + email
│   ├── kb_admin.py              # knowledge-base CRUD store + validation (admin)
│   └── rag.py                   # RAGEngine: end-to-end pipeline
├── api/main.py                  # FastAPI: /query /weather /satellite /environment /planetary /hazards /vision/classify /telemedicine /experts /doctors/apply /doctors/{id} /doctors/{id}/rate /admin/doctors /consult/* /notifications /admin/kb /advisories /prices /news /commodities /datetime /languages
├── scripts/evaluate.py          # run the evaluation harness over data/eval_set.json
├── scripts/train_plant_models.py # train the disease + plant-ID CNNs (needs TF + datasets)
├── ui/app.py                    # Streamlit chat UI
├── cli.py                       # command-line interface
├── tests/test_rag.py            # offline smoke + behavior tests
└── requirements.txt
```

---

## Limitations & next steps (toward the report's later phases)
- The offline hashing embedder is lexical-ish; install `sentence-transformers` for
  true semantic retrieval.
- The extractive generator returns KB fields verbatim with citations rather than
  free-form prose — swap in the LLM backend for natural-language synthesis.
- Phase 2+: voice/image input, multilingual responses, live weather/market data,
  and IoT signals (the data layer and `RAGEngine` are structured to accept them).