Cattle & Buffalo Breed Classification API

An AI-powered image classification API that identifies the breed of Indian cattle and buffaloes from a photograph, built for Smart India Hackathon (SIH) 2025.

Problem Statement


PS Number	SIH25004
Title	Image Based Breed Recognition for Cattle and Buffaloes of India
Organization	Ministry of Fisheries, Animal Husbandry & Dairying
Category	Software
Theme	Agriculture, FoodTech & Rural Development

Field workers under the Bharat Pashudhan App (BPA) manually record the breed of cattle and buffaloes during registration, which frequently leads to breed misclassification due to the sheer diversity of indigenous breeds and lack of expert knowledge on the ground. This reduces the accuracy of national livestock data and hampers breeding programs run under the Rashtriya Gokul Mission (RGM).

This project addresses that gap with an AI-driven solution: a worker uploads/captures an image of an animal, and the system automatically suggests the most probable breed with a confidence score — improving data accuracy and reducing dependency on manual expertise, so it can be integrated into BPA as a breed-suggestion assist.

What This Repo Contains

This repo hosts the backend inference API only. It loads a trained Keras model (Cattle.Keras) and exposes it over HTTP so a separate frontend/UI (built by a teammate) can consume it.

Accepts an uploaded animal image
Returns the predicted breed label and probability scores for all 50 supported breeds
Secured with an API key so only authorized clients can call it

Supported Breeds (50)

Purnea, motu, Himachali Pahari, kherigarh, ghumsari, gaolao, Dangi, Sahiwal, Kankrej, Hariana, nagori, Pulikulam, Kosali, Kangayam, bhelai, Konkan Kapila, Shweta Kapila, Kenkatha, Nimari, ponwar, Lakhimi, Vechur, Krishna_Valley, Nari, Hallikar, Punganur, Amritmahal, Tharparkar, Khariar, Khillari, Ayrshire, badri, thutho, Red_Sindhi, siri, Deoni, Bargur, Poda Thirupu, bachaur, Ongole, Malnad_gidda, dagri, Ladakhi, Mewati, Gir, Rathi, gangatari, Umblachery, Red kandhari, malvi

(Full list also available programmatically via the /classes endpoint.)

Repo Structure

your-repo/
├── app/
│   ├── main.py             # FastAPI app — /predict (key-protected), /health, /classes
│   └── class_names.py      # CLASS_NAMES list (50 breeds)
│
├── models/
│   └── Cattle.Keras        # trained model (use Git LFS if large)
│
├── test_client.py          # CLI script to test the API
├── requirements.txt        # Python dependencies
├── Dockerfile                # container build
├── .env.example              # template (safe to commit — no real secrets)
├── .env                        # real API_KEY + MODEL_PATH — NOT committed
├── .gitignore
└── README.md

Tech Stack

Model: TensorFlow / Keras (CNN-based image classifier)
API: FastAPI + Uvicorn
Image processing: Pillow, NumPy
Deployment: Docker

Setup

1. Clone and install dependencies

git clone <your-repo-url>
cd your-repo
pip install -r requirements.txt

2. Add your model

Place your trained model file at models/Cattle.Keras.

3. Configure environment

cp .env.example .env

Then edit .env and set a real API_KEY:

python -c "import secrets; print(secrets.token_hex(24))"

4. Run locally

cd app
uvicorn main:app --reload

API will be available at http://localhost:8000.

5. Run with Docker (alternative)

docker build -t cattle-api .
docker run -e API_KEY=your_key_here -p 8000:8000 cattle-api

API Reference

`GET /health`

Basic health check and model info.

`GET /classes`

Returns the list of all supported breed classes.

`POST /predict`

Upload an image and get breed predictions. Requires header x-api-key.

Request

POST /predict
Header: x-api-key: <your key>
Body (form-data): file=<image>

Response

{
  "predicted_label": "Sahiwal",
  "confidence": 0.87,
  "probabilities": {
    "Purnea": 0.001,
    "Sahiwal": 0.87,
    "...": "... all 50 classes"
  }
}

Testing the API

python test_client.py path/to/image.jpg --url http://localhost:8000

Integration Notes for Frontend/UI Developer

Send the API key as an x-api-key header on every request to /predict
Image should be sent as multipart/form-data under the field name file
probabilities in the response is a dict of all 50 breeds — sort it client-side to show top-N results
/health and /classes are open (no key required) for convenience

Team

Add your team name and member names here.

License

Add license info if applicable.