🌿 GblackAI — Agricultural AI Analysis API

📱 Mobile app: GblackAI Mobile

An AI-powered API that analyzes farm images to detect diseases, pests, and crop problems.

---

🎯 What it does

• Detect diseases and pests on plants (close-up photos)
• Analyze farm fields from satellite or drone images
• Return structured recommendations (biological, chemical, cultural)

---

🗂️ Project structure

GblackAI-API/
│
├── main.py                          # API v12 — production version
├── main2.py                         # API v8.5 — reference version
│
├── app/
│   ├── config.py                    # Environment variables and constants
│   ├── models.py                    # Pydantic schemas (requests / responses)
│   ├── prompts.py                   # AI prompts (Plant, Satellite, Drone)
│   ├── key_manager.py               # Gemini API key rotation
│   └── services/
│       ├── gemini.py                # Gemini API calls with error handling
│       └── cloudinary.py            # Crop and upload to Cloudinary
│
├── tests/
│   ├── conftest.py                  # Test fixtures
│   └── test_api.py                  # Endpoint and module tests
│
├── Dockerfile
├── .env.example                     # Environment variables template
├── requirements.txt

---

🔄 Versions

Version	File	Endpoint	Description
v12	main.py	/api/v12/analyze	Modular architecture, 3 specialized prompts
v8.5	main2.py	/api/v8/analyze-image	Reference version, universal prompt

---

🦠 Analysis types (v12)

Type	Description
PLANT_PEST	Close-up photo — leaves, stems, insects
SATELLITE_REMOTE_SENSING	Satellite images (Sentinel-2, Landsat)
DRONE_ANALYSIS	High-resolution drone orthophotos

---

📦 Tech stack

Tool	Role
FastAPI	REST API framework
Gemini 3 Flash Preview	Multimodal AI model (vision + text)
Cloudinary	Store detected zone crops
Pydantic	JSON validation
slowapi	Rate limiting — 15 req/min
Docker	Containerization
pytest	Tests

---

⚙️ Local setup

1. Clone the repo

git clone https://github.com/Gblack98/GblackAI-API.git
cd GblackAI-API

2. Create a virtual environment

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

3. Install dependencies

pip install -r requirements.txt

4. Set environment variables

cp .env.example .env
# Fill in the values in .env

5. Start the API

uvicorn main:app --reload --port 8000

Interactive docs available at http://localhost:8000/docs

---

🐳 Docker

docker build -t gblackai-api .
docker run -p 8000:8000 --env-file .env gblackai-api

---

🔑 Environment variables

Variable	Description
GEMINI_API_KEYS	Gemini keys separated by commas (key1,key2,key3)
CLOUDINARY_CLOUD_NAME	Cloudinary cloud name
CLOUDINARY_API_KEY	Cloudinary API key
CLOUDINARY_API_SECRET	Cloudinary secret

KeyManager automatically switches to the next key when the quota is exceeded.

---

🧪 Tests

pytest tests/ -v

Tests mock Gemini and Cloudinary — no real keys needed.

---

📡 Usage example

curl -X POST "http://localhost:8000/api/v12/analyze" \
  -F "analysis_type=PLANT_PEST" \
  -F "file=@leaf.jpg"

Response:

{
  "subject": {
    "subjectType": "PLANT",
    "description": "Maize plant (Zea mays)",
    "confidence": 0.96
  },
  "detections": [
    {
      "className": "Common rust of maize",
      "confidenceScore": 0.89,
      "severity": "HIGH",
      "boundingBox": { "x_min": 0.1, "y_min": 0.2, "x_max": 0.6, "y_max": 0.7 },
      "croppedImageUrl": "https://res.cloudinary.com/...",
      "details": {
        "description": "Orange spots on leaves.",
        "impact": "Yield will decrease if nothing is done.",
        "recommendations": {
          "biological": [],
          "chemical": [],
          "cultural": []
        },
        "knowledgeBaseTags": ["rust", "maize", "fungus"]
      }
    }
  ]
}

---

⚠️ Disclaimer

This app is for informational purposes only. The analysis and recommendations provided are generated by an AI model and should not replace the advice of a qualified agronomist. Always consult a professional before applying any treatment to your crops.

Image data is processed by Google Gemini and stored on Cloudinary. By using this project, you accept Google AI Studio's Terms of Service and Cloudinary's Terms of Service. The free tier of Google AI Studio is intended for non-commercial use only.

---

👤 Author

Gblack98 — github.com/Gblack98