Cattle Breed Classification/README.md

# 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
```bash
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
```bash
cp .env.example .env
```
Then edit `.env` and set a real `API_KEY`:
```bash
python -c "import secrets; print(secrets.token_hex(24))"
```

### 4. Run locally
```bash
cd app
uvicorn main:app --reload
```
API will be available at `http://localhost:8000`.

### 5. Run with Docker (alternative)
```bash
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**
```json
{
  "predicted_label": "Sahiwal",
  "confidence": 0.87,
  "probabilities": {
    "Purnea": 0.001,
    "Sahiwal": 0.87,
    "...": "... all 50 classes"
  }
}
```

### Testing the API
```bash
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._