HerbWise API

AI-powered African herbal medicine assistant specialized in Nigerian traditional plants. Combines image recognition, semantic search, and LLM-generated responses to provide culturally-aware plant identification and traditional remedy recommendations.

Features

• Plant Identification - Upload plant images for automatic identification using Google Vision AI
• Hybrid Queries - Combine image upload with text questions for contextual responses
• Semantic Search - Vector-based search for plants by symptoms or traditional uses
• Conversation History - Multi-turn dialogues with persistent conversation storage
• Cloudinary Integration - Automatic image upload with retry logic and fallback storage
• Structured Outputs - LLM-generated plant info (uses, benefits, preparation, safety warnings)
• Nigerian Context - Local names in Yoruba, Igbo, Hausa and safety-first approach

Tech Stack

• FastAPI - Async web framework
• Google Vertex AI - Embeddings and LLM generation (Gemini 2.5 Flash)
• LangChain - LLM orchestration and structured outputs
• Google Cloud Storage - Conversation persistence
• Cloudinary - Image hosting
• Pydantic v2 - Data validation
• Docker - Containerization

Quick Start

Prerequisites

• Python 3.11+
• Google Cloud Project with Vertex AI enabled
• Cloudinary account
• Gemini API key

Run Locally

python -m app.main

API available at http://localhost:8080

Run with Docker

docker-compose up --build

API Endpoints

Main Endpoint

POST /chat/ - Primary conversation endpoint (public)

{
  "text_input": "What helps with headaches?",
  "image_base64": "data:image/jpeg;base64,...",  // optional
  "conversation_id": "uuid"  // optional for continuity
}

Service Endpoints (require API key)

All /services/* endpoints require X-API-Key header:

• POST /services/classify - Image classification only
• POST /services/generate/plant-info - Generate structured plant data
• POST /services/generate/conversational - Generate text responses
• POST /services/search/semantic - Semantic text search
• POST /services/search/strict - Exact plant ID search

Example Usage

# Chat endpoint (public)
curl -X POST http://localhost:8080/chat/ \
  -H "Content-Type: application/json" \
  -d '{"text_input": "What is this plant used for?", "image_base64": "..."}'

# Service endpoint (requires API key)
curl -X POST http://localhost:8080/services/classify \
  -H "X-API-Key: your-key" \
  -H "Content-Type: application/json" \
  -d '{"image_base64": "..."}'

Project Structure

app/
├── controllers/     # Business logic orchestration
├── interfaces/      # Abstract base classes
├── routes/          # FastAPI endpoints
├── schemas/         # Pydantic models
├── services/        # Service implementations
└── dependencies.py  # Dependency injection

tests/               # Test suites (gitignored)
utils/               # Utility scripts
credentials/         # GCP service account (gitignored)

License

MIT

Contributing

Pull requests welcome. Please ensure tests pass before submitting.