README.md

metadata

title: Mushroom Species Recognition API
emoji: 🍄
colorFrom: green
colorTo: yellow
sdk: docker
pinned: false
license: mit
app_port: 7860

Mushroom & Plant Species Recognition API

AI-powered mushroom and plant species identification using BioCLIP, VLM models, and PlantNet API.

Features

• BioCLIP Model: Fast species recognition from biological specimens
• PlantNet API: Specialized plant identification with 77M+ observations
• VLM Fallback: Nvidia Nemotron VLM for enhanced accuracy
• MCC Campus Database: Location data for species found at MCC campus
• RESTful API: Simple JSON-based API
• Multi-Model Verification: Cross-validates results across multiple AI systems

API Endpoints

POST /recognize

Upload an image to identify mushroom or plant species.

Request:

curl -X POST "https://your-space.hf.space/recognize" \
  -F "file=@plant.jpg"

Response:

{
  "success": true,
  "found_in_database": true,
  "species": "Alstonia scholaris",
  "species_type": "plant",
  "location": "Anderson Hall",
  "latitude": 12.92100,
  "longitude": 80.12200,
  "confidence": 0.95,
  "identified_by": "PlantNet + BioCLIP (both agree)",
  "top_matches": [...]
}

GET /health

Check API health status and enabled features.

GET /test/plantnet

Test PlantNet API connection and configuration.

GET /

API documentation and info.

Usage

Visit /docs for interactive Swagger documentation.

Technology Stack

PlantNet API**: Specialized plant identification database

• Nvidia Nemotron VLM: Fallback identification via OpenRouter
• Docker: Containerization

Setup

API Keys

You need to configure API keys for enhanced functionality:

1. OPENROUTER_API_KEY - For VLM fallback (optional)

   • Get from: https://openrouter.ai/
   • See VLM_SETUP.md

2. PLANTNET_API_KEY - For plant identification (recommended for plants)

   • Get from: https://my.plantnet.org/
   • Free tier: 500 requests/day
   • See PLANTNET_SETUP.md

Environment Setup

1. Copy .env.example to .env:

cp .env.example .env

2. Edit .env and add your API keys:

OPENROUTER_API_KEY=your_key_here
PLANTNET_API_KEY=your_key_here

3. Install dependencies:

pip install -r requirements.txt

4. Run the API:

python api.py
# Or with uvicorn:
uvicorn api:app --host 0.0.0.0 --port 8000

Model Hierarchy

The API uses a multi-model approach for best accuracy:

For Plants:

1. BioCLIP (initial classification)
2. PlantNet API (primary identification if configured)
3. VLM (verification/fallback if configured)
4. Higher confidence when multiple models agree

For Mushrooms:

1. BioCLIP (primary identification)
2. VLM (fallback if BioCLIP uncertain)

API Rate Limits

• BioCLIP: Unlimited (local model)
• PlantNet Free: 500 requests/day
• OpenRouter: Varies by plan

Setup

Set your OPENROUTER_API_KEY in the Space secrets for VLM fallback functionality.

License

MIT