"""Generate the AgroSense User Manual as both Word (.docx) and PDF. One content source -> two formats, so they never drift. Output goes to docs/. pip install python-docx fpdf2 python scripts/build_manual.py Content is kept ASCII so the PDF renders with the built-in core fonts (no bundled Unicode TTF needed). """ from __future__ import annotations from pathlib import Path DOCS_DIR = Path(__file__).resolve().parent.parent / "docs" TITLE = "AgroSense - User Manual" SUBTITLE = "Intelligent RAG-based Agriculture Farming Advisor - Version 0.1 (POC)" # Each section: (heading, [blocks]). Block = (kind, content): # "p" -> paragraph str ; "h2" -> subheading str ; "ul"/"ol" -> list[str] SECTIONS = [ ("1. Introduction", [ ("p", "AgroSense is an AI-powered farming advisor. It answers a farmer's " "questions with grounded, cited guidance from an agriculture knowledge " "base, and adds live context: weather, satellite, environment, market " "prices, hazards, plant-image diagnosis, telemedicine, and live " "consultation with verified plant doctors."), ("p", "Beyond advice, it is a working farm companion: a speaking-avatar advisor, " "farmer community clubs with video meetings, a traditional/Panchang advisor, " "a finance hub (bank loans + government schemes & subsidies), a state-wise " "land-record finder with downloadable guides, and a peer-to-peer produce " "trading marketplace."), ("p", "It runs fully offline for the core advisor (no API keys, no internet). " "Optional integrations add live data when keys are configured."), ("h2", "Who is it for"), ("ul", ["Farmers - ask questions, diagnose crop problems, consult doctors, join " "clubs, find schemes/loans and trade produce.", "Agri-experts (plant doctors) - onboard, get verified, take consults.", "Administrators - configure the knowledge base, verify doctors, post " "scheme announcements and review loan enquiries."]), ]), ("2. Getting Started", [ ("p", "AgroSense ships as a FastAPI backend that also serves a modern " "single-page web app. Start the server and open the web app:"), ("ol", ["Install dependencies: pip install -r requirements.txt", "Start the server: uvicorn api.main:app --reload", "Open the web app: http://127.0.0.1:8000/ui/", "API docs (optional): http://127.0.0.1:8000/docs"]), ("p", "The Streamlit UI (streamlit run ui/app.py) and a command-line " "interface (python cli.py \"your question\") are available as " "alternatives."), ("p", "Documentation - this User Manual, a Technical Guide and a Standard " "Operating Procedure - can be downloaded as PDF or Word from the links in " "the web app header."), ]), ("3. The Web App at a Glance", [ ("h2", "Top bar"), ("ul", ["Date in the Gregorian (English) and Indian National (Saka) calendars, " "and the current time in IST.", "A scrolling Google News headline ticker (choose region and topic).", "A scrolling commodities ticker (Gold, Silver, Oil, Coffee, Arecanut, " "Coconut)."]), ("h2", "Shared controls"), ("p", "Set your Location, Answer language, Crop and Growth stage once - they " "drive the advisor, the Location-intel dashboard, consultations, and they " "surface your state's schemes and land records."), ("h2", "Speaking avatar"), ("p", "A speaking-avatar mascot can read the advisor's answer aloud via the " "browser's Web Speech API (keyless, multilingual), with Speak/Stop controls " "and an auto-speak option. It degrades gracefully where speech is unavailable."), ("h2", "Tabs"), ("ul", ["Advisor - ask questions (with the speaking avatar).", "Location intel - weather, satellite, environment, sky, hazards, advisories.", "Market - mandi prices, commodities, and the farmer trading marketplace.", "Plant clinic - AI image diagnosis + telemedicine, then escalate to a " "live verified plant doctor (request a consult, directory, apply) - all " "in one tab.", "Clubs - location- and commodity-wise farmer communities with chat, " "sharing and video meetings.", "Traditional - traditional/desi practices + Panchang (astrological) " "guidance for daily farm activities.", "Finance - bank assistance & agri-loans (with apply) plus government " "schemes & subsidies (central + state) and announcements.", "Land records - find your state's land-record portal and download a guide.", "Radio - listen to internet radio stations for India.", "Admin - knowledge base, doctor verification, scheme announcements and " "loan enquiries (token-gated)."]), ("h2", "Internet radio (Radio tab)"), ("p", "Open the Radio tab and click 'Load stations' to list online radio " "stations for India (Vivid Bharti, Radio Mirchi, Red FM, All India Radio, " "and regional/agriculture stations). Type a filter (e.g. AIR, Tamil, news, " "agriculture) to narrow the list, then press Play to listen in the built-in " "audio player. These are internet streams, not over-the-air FM; some " "streams may occasionally be offline - try another."), ]), ("4. Asking the Advisor", [ ("ol", ["Go to the Advisor tab and type your question (e.g. 'Sandy soil, " "rainfall 900 mm, growing maize - fertilizer and pest steps?').", "Optionally tick Satellite, Advisories, or Prices to attach extra context.", "Click Ask."]), ("p", "The answer is composed only from the knowledge base and shows citations " "(sources) for every recommendation. Choose a non-English language in the " "controls to get the answer translated."), ]), ("5. Location Intelligence", [ ("p", "Enter a Location, open the Location intel tab, and click 'Load for " "location'. Cards appear for:"), ("ul", ["Weather - current conditions plus a short forecast and advisories.", "Satellite - NDVI vegetation image and agroclimate (solar, rainfall).", "Environment - altitude, population, humidity, wind, air quality, " "groundwater (soil-moisture proxy unless a CGWB key is set).", "Sky - Sun, Moon (phase) and planet positions for the current time.", "Hazards - nearby natural-hazard events (NASA EONET) and active fires " "(NASA FIRMS, if a key is set).", "Advisories - prioritized, crop- and stage-aware actions that fuse the " "weather, satellite and NDVI signals."]), ]), ("6. Market, Prices and Farmer Trading", [ ("ul", ["Mandi prices: enter a commodity (and optional state) to see modal " "min/avg/max prices. Requires a free data.gov.in key (otherwise shows " "'unavailable').", "Commodities: live Gold/Silver/Oil/Coffee (keyless); Arecanut and " "Coconut need the data.gov.in key."]), ("h2", "Farmer trading marketplace"), ("p", "In the same Market tab, a peer-to-peer marketplace lets you buy and sell " "produce directly:"), ("ol", ["Browse/filter listings by type (selling or buying), commodity or " "state/place.", "Open a listing to see price, quantity, grade, location and the poster, " "then 'Send inquiry' (your name, contact, offer and quantity) or click " "'Negotiate (video room)' to talk live.", "Post your own listing with the 'Post a listing' form (sell or buy; " "commodity, quantity/unit, price, grade, location, description).", "Mark your listing 'sold/closed' when done - closed listings drop out of " "the default browse."]), ("p", "This is a POC marketplace: there is no payment, escrow or KYC. Verify the " "other party and agree terms independently before transacting."), ]), ("7. Plant Clinic and Live Doctor", [ ("p", "Diagnose with AI (image + symptoms), then escalate to a verified human " "plant doctor for a live consult - all in one Plant clinic tab."), ("h2", "Image diagnosis"), ("ol", ["Upload a leaf/plant/insect photo.", "Click 'Analyze image' to get a disease/health assessment, a plant ID, " "and a pest ID."]), ("p", "Without trained vision models, an honest colour heuristic gives a leaf-" "health hint (clearly labelled 'not a diagnosis'). Train real models with " "scripts/train_plant_models.py and set the model environment variables to " "enable CNN inference."), ("h2", "Telemedicine"), ("ol", ["Enter the Crop (in controls) and describe the Symptoms.", "Click 'Get consultation'."]), ("p", "You receive a diagnosis, health status and severity, plus a PRESCRIPTION " "composed only from knowledge-base fields (dosages are taken verbatim and " "cited). A recognized disease/pest maps to a targeted IPM treatment. Timing " "is weather-aware. A safety disclaimer makes clear this is decision support, " "not a substitute for an expert."), ]), ("8. Live Plant Doctor (within Plant clinic)", [ ("h2", "Consult a doctor"), ("ol", ["In the Plant clinic tab, scroll to 'Talk to a live plant doctor', enter " "your name, channel and language.", "Click 'Request consultation'. You are routed to a matching verified " "doctor and get a live video room link and a chat thread.", "Use 'Join live video room' and message the doctor in the chat."]), ("h2", "Doctor directory, profiles and ratings"), ("ul", ["Verified doctors are listed with their star rating.", "Click 'View profile' to see specialization, region, languages, " "ICAR/registration number, credentials and recent reviews.", "Leave a rating (1-5 stars) and an optional review."]), ("h2", "Apply to become a plant doctor"), ("p", "Fill the 'Apply as a plant doctor' form (name, specialization, region, " "languages, contact, credentials, and an ICAR/registration number). Your " "application is 'pending' until an administrator verifies it. Only verified " "doctors appear in the directory and receive consultations."), ]), ("9. Farmer Clubs", [ ("p", "The Clubs tab hosts location-wise and commodity-wise farmer communities " "for peer support and knowledge sharing."), ("ol", ["Find a club by type (location or commodity), state or crop, or create " "your own.", "Open a club to join, post messages and share links/resources in the " "discussion feed.", "Click 'Join video meeting' to start/enter the club's live video room " "(keyless)."]), ("p", "Seeded with starter clubs (Karnataka/Maharashtra; Tomato/Cotton/Coffee/" "Paddy); anyone can add more."), ]), ("10. Traditional Advisor", [ ("p", "The Traditional tab gives guidance for daily farm activities by combining " "Indian traditional/desi practices with Panchang (astrological) timing."), ("ol", ["Pick an activity (sowing, transplanting, ploughing, pest control, " "harvesting, etc.).", "Get a suitability verdict from today's Panchang (nakshatra, paksha, " "tithi, karana) with reasons, plus relevant traditional practices " "(Beejamrit, Jeevamrit, neem-based pest control, mixed cropping...) " "matched to your area."]), ("p", "This is complementary to scientific agronomy, not a replacement - a " "disclaimer accompanies each result."), ]), ("11. Finance - Bank Assistance and Government Schemes", [ ("p", "The Finance tab combines agri-credit and government support in one place."), ("h2", "Bank assistance and agri-loans"), ("ol", ["Browse/filter loan products by category or search (KCC, crop/term " "loans, farm mechanization, dairy/allied, gold loan, warehouse-receipt, " "FPO/SHG, AIF, solar pump, horticulture).", "Open a product to see interest, loan amount, tenure, eligibility, the " "step-by-step application process, documents, portal and helpline.", "Lodge a loan enquiry (your name and contact are required, amount " "optional) - it is recorded for an administrator to follow up."]), ("h2", "Government schemes and subsidies"), ("ol", ["Filter central/state schemes by level, search or your location's state " "(central schemes always show).", "Open a scheme for benefits, eligibility, application steps, documents " "and the official portal.", "Read the aggregated 'Latest announcements' feed across all schemes."]), ("p", "Both are curated knowledge bases - rates, amounts and rules change. " "'Apply' lodges an enquiry in AgroSense; always confirm and apply through " "the bank or official portal."), ]), ("12. Land Records", [ ("p", "The Land records tab helps you find and obtain your land record. Land is a " "State subject, so AgroSense does not fetch your actual record - it guides " "you to the official source."), ("ol", ["Set your Location (or pick a State) to see the state's land-record " "system - the local record name (RTC/Pahani, 7/12, Khatauni, Jamabandi, " "Patta/Chitta...), the official portal and cadastral-map portal.", "Follow the 'How to search & download' steps (district, taluk/tehsil, " "village, survey/khasra/khata number).", "Download a printable guide (PDF or Word) for your state to use offline."]), ]), ("13. Administration", [ ("p", "The Admin tab is gated by an admin token (set AGROSENSE_ADMIN_TOKEN; " "default is 'admin' for the local demo - change it for any shared use). " "Enter the token and click Unlock."), ("h2", "Configure the knowledge base"), ("ul", ["Add a new entry (crop and source are required; fertilizer, disease, " "pest, soil, rainfall, etc. are optional).", "Edit or Delete existing entries.", "Saving rebuilds the live search index, so changes take effect " "immediately."]), ("h2", "Verify plant doctors"), ("ul", ["Review pending applications (name, specialization, contact, " "credentials, registration number).", "Verify (approve) to add them to the directory, or Reject."]), ("h2", "Post a scheme announcement"), ("p", "Pick a government scheme, add an announcement/update (optional date) and " "post it; it appears immediately in the scheme detail and the 'Latest " "announcements' feed."), ("h2", "Review loan enquiries"), ("p", "See the loan enquiries lodged from the Finance tab (applicant name, " "product, amount, contact, location and message) so you can follow up."), ]), ("14. Optional Integrations and Keys", [ ("p", "The core app is keyless. These environment variables unlock live data:"), ("ul", ["AGROSENSE_DATAGOV_API_KEY - mandi prices and groundwater (data.gov.in).", "AGROSENSE_FIRMS_MAP_KEY - active fires (NASA FIRMS).", "AGROSENSE_EE_PROJECT (+ service account vars) - field-level NDVI " "(Google Earth Engine).", "AGROSENSE_NOTIFY_WEBHOOK / SMTP vars - notify experts on new consults.", "AGROSENSE_VIDEO_BASE - self-hosted Jitsi for live video.", "AGROSENSE_ADMIN_TOKEN - the admin token (change the default)."]), ("p", "Weather, news, commodities, satellite imagery, hazards (EONET) and " "planetary positions need no key."), ]), ("15. API Reference (summary)", [ ("p", "All features are available via the REST API (see /docs). Key endpoints:"), ("ul", ["POST /query - ask the advisor.", "GET /weather /satellite /environment /planetary /hazards /advisories.", "GET /prices /commodities /news /radio /datetime /languages.", "POST /vision/classify - image diagnosis; POST /telemedicine - consult.", "GET /experts ; GET /doctors/{id} ; POST /doctors/{id}/rate ; " "POST /doctors/apply.", "POST /consult/request ; GET/POST /consult/{id} (messages).", "GET/POST /clubs ; GET /clubs/{id} ; POST /clubs/{id}/join|post.", "GET /traditional - traditional + Panchang advice.", "GET /subsidies[/{id}] ; GET /subsidies/updates - schemes.", "GET /finance[/{id}] ; POST /finance/{id}/apply - loans.", "GET /land-records ; GET /land-records/guide.{pdf,docx}.", "GET/POST /market/listings ; GET /market/listings/{id} ; " "POST /market/listings/{id}/inquire|close - trading.", "Admin (X-Admin-Token): /admin/kb (CRUD), /admin/doctors[/{id}/verify], " "/admin/subsidies/{id}/update, /admin/finance/applications.", "Docs: GET /downloads/{user-manual,technical-guide,sop}.{pdf,docx}."]), ]), ("16. Troubleshooting and FAQ", [ ("ul", ["The web app does not load - ensure the server is running and open " "http://127.0.0.1:8000/ui/ (the root / redirects there).", "A feature says 'unavailable' - it needs a key (prices, groundwater, " "fires) or internet (weather, news). The core advisor still works offline.", "Plant ID / pest ID says 'needs a trained model' - train the CNNs and " "set the model environment variables.", "Admin says 'Invalid token' - check AGROSENSE_ADMIN_TOKEN.", "Video room asks to sign in - the public Jitsi instance may require a " "moderator login; set AGROSENSE_VIDEO_BASE to a self-hosted Jitsi."]), ]), ("17. Data Sources and Disclaimer", [ ("ul", ["Knowledge base: ICAR-aligned agronomic guidance (configurable by admins).", "Weather/air/elevation: Open-Meteo. Satellite: NASA GIBS/POWER. " "Hazards: NASA EONET/FIRMS. Prices: Agmarknet via data.gov.in. " "News: Google News. Commodities: Yahoo Finance."]), ("p", "AgroSense provides decision support, not professional or medical " "authority. Always confirm product names, dosages, pre-harvest intervals " "and local regulations before applying any agro-chemical, and consult a " "qualified agronomist or local extension officer for critical decisions."), ]), ] def main() -> int: import sys sys.path.insert(0, str(Path(__file__).resolve().parent)) from docgen import build_both build_both(TITLE, SUBTITLE, SECTIONS, DOCS_DIR, "AgroSense_User_Manual") return 0 if __name__ == "__main__": raise SystemExit(main())