scripts/build_manual.py

"""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())