🌾 FarmAssist - AI-Powered Agricultural Decision Support System

FarmAssist is a modern, full-stack smart farming ecosystem that empowers farmers and agronomists with data-driven decision-making tools. By combining custom Machine Learning pipelines, agronomic heuristic engines, a relational database backend, and an interactive analytics dashboard, FarmAssist provides actionable advice on crop selection, soil health, fertilizer management, yield prediction, and climate monitoring. It also features a conversational AI agent to offer real-time agronomic consulting.

---

📋 Table of Contents

1. Key Features
   • Crop Recommendation Engine
   • Soil Quality Index (SQI) Scoring
   • Crop Yield Prediction
   • Fertilizer Recommendation System
   • Lands & Plot Management
   • Conversational AI Assistant
   • Interactive Insights & Analytics Dashboard
2. Technology Stack
3. Machine Learning Pipeline & Feature Engineering
   • Feature Engineering Details
   • Model Comparison and Selection
4. Database Schema (Prisma Models)
5. System Architecture
6. Installation & Setup
   • Prerequisites
   • ML Service & Flask Backend Setup
   • Node.js API Gateway Setup
   • Frontend React Application Setup
7. API Endpoints Reference
   • Flask ML Backend Endpoints
   • Node.js API Gateway Endpoints

---

🚀 Key Features

1. Crop Recommendation Engine

• ML Classifier: Utilizes a custom-trained CalibratedClassifierCV wrapping a HistGradientBoostingClassifier with Sigmoid Calibration.
• Top-N Predictions: Predicts the top 3 most suitable crops out of 51 supported classes, showing precise calibrated confidence percentages for each.
• Reliability Classifier: If the top crop confidence is $\ge 70%$, the recommendation is flagged as Reliable; otherwise, it warns the user of environmental marginality.
• Inputs Taken: Soil Nitrogen (N), Phosphorus (P), Potassium (K), pH level, Temperature (°C), Humidity (%), and Rainfall (mm).

2. Soil Quality Index (SQI) Scoring

Computes a hybrid Soil Quality Score ($0\text{--}100$) reflecting both crop-specific suitability and general soil productivity:

• Method 1 (60% Weight): Top-1 crop prediction confidence (the calibrated output probability from the ML classifier). High confidence indicates the soil profile closely matches a well-characterized crop profile.
• Method 3 (40% Weight): Normalized weighted sum of raw soil parameters (N, P, K, pH, temperature, humidity, rainfall). Features are normalized against training-set limits ($0\text{--}1$) and weighted by their absolute Pearson correlation with crop labels.
• Qualitative Ratings:
  • $\ge 80$: Excellent
  • $\ge 65$: Good
  • $\ge 50$: Average
  • $\ge 35$: Below Average
  • $< 35$: Poor

3. Crop Yield Prediction

Calculates expected crop yield (tonnes/acre) using a combination of baseline agronomical yields, soil quality multipliers, and regional seasonal factors:

• Agromonic Lookup Table: Holds baseline yields for all 51 crops (e.g., Banana = 8.0 t/acre, Potato = 7.0 t/acre, Rice = 2.0 t/acre, Wheat = 2.2 t/acre).
• Soil Multiplier: Scales yield from $0.40\times$ (poor soil) up to $1.20\times$ (excellent soil) using the formula: $$\text{Multiplier} = 0.40 + \left(\frac{\text{Soil Quality Score}}{100}\right) \times 0.80$$
• Seasonal Factors: Adjusts yields for different crop cycles (Kharif: $1.05$, Rabi: $1.00$, Zaid: $0.90$, Summer: $0.90$, Winter: $1.00$, Annual: $1.00$).
• Formula: $$\text{Yield} = \text{Base Yield} \times \text{Soil Multiplier} \times \text{Seasonal Factor} \times \text{Plot Area (acres)}$$

4. Fertilizer Recommendation System

• Nutrient Check: Evaluates current N, P, and K values against crop-specific optimal ranges.
• Dosage Calculations: Calculates exact quantities (kg/acre) of corrective fertilizers (Urea, DAP, MOP, or maintenance NPK 10-26-26) needed to reach optimal thresholds, including split-application guidance (e.g., 50% at sowing, 50% at tillering).
• pH & Soil Advice: Recommends amendments based on pH (e.g., agricultural lime for acidic soils, gypsum/sulfur for alkaline soils) and textures (e.g., frequency tips for Sandy vs. Clay soils).

5. Lands & Plot Management

• CRUD Operations: Create, read, update, and delete distinct farm plots (e.g., "North Field", "West Orchard").
• State Capture: Stores plot location, area (acres), soil parameters, and local climate averages.
• Historical Soil Logs: Automatically records soil history readings to track changes in NPK, pH, and climate parameters over time.

6. Conversational AI Assistant

• AI Engine: Powered by Gemini 2.5 Flash integrated via langchain-google-genai.
• Stateful Memory: Maintains conversational context for the last 10 turns (20 messages) per session using an in-memory history window (RunnableWithMessageHistory).
• Agricultural Persona: Configured as "FarmAssist AI", providing concise, friendly, and expert advice on pest control, crop rotation, organic practices, and climate adjustments.

7. Interactive Insights & Analytics Dashboard

• Feature Weights: Visualizes ML feature importance weights (18 total features) via interactive horizontal bar charts.
• Soil Radar Chart: Compares current plot soil nutrients against optimal reference benchmarks.
• Crop Distribution Pie: Aggregates user crop prediction history into a dynamic donut chart.
• Model Summary Card: Displays training parameters, test accuracy (99.77%), split samples, calibration folds, and data scalers used.

---

🛠 Technology Stack

Frontend Client

• Framework: React.js (Vite-based SPA)
• Styling: Tailwind CSS v4, Lucide React (Icons), Shadcn UI elements
• State Management & Fetching: TanStack React Query v5, React Context (Auth & Lands contexts)
• Visualizations: Recharts (Radar, Bar, Pie charts)
• Routing: React Router DOM v7

Node.js API Gateway (Middle Tier)

• Environment: Node.js (ES modules), Express.js
• Database ORM: Prisma Client v5 (PostgreSQL database connection)
• Security: JSON Web Tokens (JWT) authentication, bcrypt password hashing
• Validation: Zod schemas

Python Flask ML Service (Core Computation & ML serving)

• Microservice Framework: Flask, Flask-CORS
• Scientific Computing: NumPy, Pandas, Scikit-Learn
• Generative AI Framework: LangChain, langchain-google-genai, google-generativeai
• Utilities: Python-Dotenv, Pickle

---

🧠 Machine Learning Pipeline & Feature Engineering

The machine learning model recommendations are trained and validated in train_final.ipynb.

Feature Engineering Details

To create sharp decision boundaries and boost classifier confidence on borderline or ambiguous inputs, the model scales the 7 raw features into 18 features using domain-specific agronomic relationships:

1. Soil Nutrient Ratios:
   • N_P_ratio: Nitrogen-Phosphorus balance ($N / (P + 10^{-5})$).
   • N_K_ratio: Nitrogen-Potassium balance ($N / (K + 10^{-5})$).
   • P_K_ratio: Phosphorus-Potassium balance ($P / (K + 10^{-5})$).
   • NPK_sum: Sum of primary nutrients ($N + P + K$).
   • NPK_product: Nutrient product interaction ($N \times P \times K$).
2. Climate & Environmental Indexes:
   • heat_index: Heat/thermal stress ($\text{temperature} \times \text{humidity} / 100$).
   • aridity: De Martonne aridity index ($\text{rainfall} / (\text{temperature} + 1)$).
   • temp_rain: Interaction between temperature and precipitation ($\text{temperature} \times \text{rainfall}$).
   • humid_rain: Precipitation multiplied by relative humidity ($\text{humidity} \times \text{rainfall}$).
3. pH Interactions:
   • ph_N: Available nitrogen interaction ($pH \times N$).
   • ph_class: Categorized acidity levels (0: Acidic $< 5.5$, 1: Moderately Acidic $5.5\text{--}6.5$, 2: Neutral $6.5\text{--}7.5$, 3: Alkaline $> 7.5$).

Model Comparison and Selection

During model development in the Jupyter Notebook, multiple algorithms were compared on identical stratified test sets (80% train / 20% test, 6,596 samples total, 51 classes) and evaluated on borderline samples:

Model Config	Feature Eng?	Calibration?	Test Accuracy	Prediction Confidence (Ambiguous Test Sample)	Status
1. Baseline Random Forest	No	No	99.70%	54.0%	❌ Low Confidence
2. Random Forest	Yes	No	99.70%	51.7%	❌ Low Confidence
3. ExtraTrees Classifier	Yes	No	99.77%	62.7%	⚠️ Moderate Confidence
4. HistGradientBoosting	Yes	No	99.32%	70.8%	✅ High Confidence (No Calib)
5. HistGradientBoosting	Yes	Sigmoid Calib (CV=3)	99.77%	58.3%	🏆 Selected & Served (Calibrated)
6. Soft Voting Ensemble	Yes	No	99.62%	60.8%	⚠️ Moderate Confidence

Note

While raw HistGradientBoosting achieved the highest raw confidence on the ambiguous test sample, HistGradientBoosting with Sigmoid Calibration (Model 5) was selected as the final model because calibration aligns model probabilities with true physical probabilities, preventing overconfidence while maintaining an outstanding 99.77% test accuracy across all 51 classes.

---

🗄 Database Schema (Prisma Models)

The system uses a PostgreSQL database structured via schema.prisma:

erDiagram
    User ||--o{ Land : "manages"
    User ||--o{ CropPrediction : "requests"
    User ||--o{ YieldPrediction : "requests"
    User ||--o{ FertilizerRecommendation : "requests"
    
    Land ||--o{ SoilReading : "logs"
    Land ||--o{ CropPrediction : "linked to"
    Land ||--o{ YieldPrediction : "linked to"
    Land ||--o{ FertilizerRecommendation : "linked to"

    User {
        String id PK
        String email UK
        String name
        String password
        String phone
        String avatarUrl
        DateTime createdAt
    }
    Land {
        String id PK
        String userId FK
        String name
        String location
        Float area
        Float nitrogen
        Float phosphorus
        Float potassium
        Float ph
        String soilType
        Float temperature
        Float humidity
        Float rainfall
        Boolean isActive
    }
    SoilReading {
        String id PK
        String landId FK
        Float nitrogen
        Float phosphorus
        Float potassium
        Float ph
        Float temperature
        Float humidity
        Float rainfall
        DateTime recordedAt
    }
    CropPrediction {
        String id PK
        String userId FK
        String landId FK
        Float nitrogen
        Float phosphorus
        Float potassium
        Float ph
        Float temperature
        Float humidity
        Float rainfall
        String predictedCrop
        Float confidence
        Json alternativeCrops
        DateTime createdAt
    }
    YieldPrediction {
        String id PK
        String userId FK
        String landId FK
        String crop
        String season
        Float area
        Float predictedYield
        Float soilQualityScore
        DateTime createdAt
    }
    FertilizerRecommendation {
        String id PK
        String userId FK
        String landId FK
        String crop
        String soilType
        Float nitrogen
        Float phosphorus
        Float potassium
        Float ph
        String recommendedFertilizer
        String nitrogenStatus
        String phosphorusStatus
        String potassiumStatus
        String advice
        DateTime createdAt
    }

Loading

---

🧱 System Architecture

                                    +-----------------------+
                                    |     React Frontend    |
                                    |     (Vite + Tailwind) |
                                    +-----------+-----------+
                                                |
                                          HTTP REST API
                                                |
                                                v
                                    +-----------+-----------+
                                    |     Node.js Express   |
                                    |       API Gateway     |
                                    +-----+-----------+-----+
                                          |           |
                                     Prisma ORM     Axios (Internal HTTP)
                                          |           |
                                          v           v
                                    +-----+-----+   +-+---------------------+
                                    |PostgreSQL |   | |  Python Flask ML    |
                                    | Database  |   | |     Microservice    |
                                    +-----------+   | +----------+----------+
                                                    |            |
                                                    |      Pickle Loader
                                                    |            v
                                                    |     +------+------+
                                                    |     |  HGB Model  |
                                                    |     |  LangChain  |
                                                    |     +-------------+
                                                    +-----------------------+

---

⚙️ Installation & Setup

Prerequisites

• Node.js (v18 or higher)
• Python 3.10+ (with pip and virtualenv)
• PostgreSQL database server running locally or hosted

1. ML Service & Flask Backend Setup

The Flask backend serves predictions and Chatbot workflows.

1. Navigate to the Flask directory:

   cd backend/flask

2. Create and activate a Python virtual environment:

   python -m venv .venv
   # Windows:
   .venv\Scripts\activate
   # Linux/macOS:
   source .venv/bin/activate

3. Install dependencies:

   pip install -r requirements.txt

4. Create a .env file in backend/flask/.env:

   FLASK_PORT=5001
   GEMINI_API_KEY=your_gemini_api_key_here
   MODEL_PATH=../model.pkl
   ENCODER_PATH=../encoder.pkl
   METADATA_PATH=../soil_metadata.pkl

5. Run the server:

   python app.py

   The Flask microservice will start on http://localhost:5001.

2. Node.js API Gateway Setup

This service acts as the gateway database interface and auth manager.

1. Navigate to the Node directory:

   cd backend/node

2. Install dependencies:

   npm install

3. Create a .env file in backend/node/.env:

   PORT=5000
   DATABASE_URL="postgresql://username:password@localhost:5432/farmassist?schema=public"
   JWT_SECRET="your-super-secret-key-here"
   PYTHON_SERVICE_URL="http://localhost:5001"

4. Push database migrations using Prisma:

   npx prisma db push

5. Run the server:

   node server.js

   The API gateway will start on http://localhost:5000.

3. Frontend React Application Setup

1. Navigate to the frontend directory:

   cd frontend

2. Install dependencies:

   npm install

3. Create a .env file in frontend/.env:

   VITE_API_URL="http://localhost:5000"
   VITE_FLASK_API_URL="http://localhost:5001"

4. Start the Vite development server:

   npm run dev

   Open browser and navigate to http://localhost:5173 (or the console-indicated port).

---

🔌 API Endpoints Reference

Flask ML Backend Endpoints

• POST /predict-crop - Predicts top crops and computes soil quality metrics.
• POST /soil-quality - Computes soil quality index only.
• POST /predict-yield - Computes expected crop yield tonnes/acre.
• POST /recommend-fertilizer - Formulates NPK adjustment advice.
• GET /model-info - Retrieves feature weights and training configurations.
• POST /api/chat - Chats with FarmAssist AI (incorporates LangChain session state).
• DELETE /api/chat/<session_id> - Clears session chat history.

Node.js API Gateway Endpoints

All routes except login/register require an Authorization: Bearer <token> header.

• Authentication (/api/auth)
  • POST /register - Register a new user account.
  • POST /login - Login to account.
  • GET /me - Retrieve current logged-in user profile.
• Lands CRUD (/api/lands)
  • GET / - Retrieve all lands managed by user.
  • POST / - Register a new farm plot.
  • PUT /:id - Update plot details.
  • DELETE /:id - Delete agricultural plot.
• Predictions (/api/predictions)
  • POST /crop - Predicts crop, saves result, returns index.
  • GET /crop - Retrieve user's historical crop predictions.
  • POST /yield - Predicts crop yield, saves result.
  • GET /yield - Retrieve yield prediction history.
  • POST /soil-quality - Calculates soil quality index score (proxies Flask).
• Fertilizer (/api/fertilizer)
  • POST / - Formulates fertilizer advice, saves records.
  • GET / - Retrieves user's history of fertilizer calculations.

---

🌾 FarmAssist - Bridging AI, data science, and modern agronomic standards to make farming smarter, sustainable, and highly productive.