# AI Crop Decision Support System

Production backend that evaluates whether a selected crop is suitable
for a given location and month in Tamil Nadu (extensible to other
states), using 6 machine learning models plus an LLM reasoning layer to
produce a clear, human-readable recommendation with risk explanation
and alternative crop suggestions.

This is a decision-support system — it explains tradeoffs and risks
based on real climate, agronomic, and market data, not a black-box
prediction.

## What's in this repository

```
app/                    FastAPI application — API, business logic, Celery workers
ml_pipeline/             Data preprocessing, feature engineering, model training
data/lookup/              Hand-curated crop and district reference tables (committed)
data/raw/ processed/ models/   Generated/downloaded data (gitignored, see docs/data_sourcing.md)
alembic/                  Database migrations
deployment/               Nginx, systemd, Docker configs + deploy scripts
monitoring/               Prometheus + Grafana configuration
tests/                    Unit, integration, and load tests
docs/                     Architecture, deployment, API contract, data sourcing
```

## Quick start (local development)

```bash
cp .env.example .env          # fill in real values, especially ANTHROPIC_API_KEY
python3.12 -m venv venv && source venv/bin/activate
pip install -r requirements-dev.txt
alembic upgrade head
pytest tests/unit tests/integration   # should pass with no real data/models needed
uvicorn app.main:app --reload          # in one terminal
celery -A app.workers.celery_app worker --loglevel=info   # in another
```

Full walkthrough including getting real data and training models: see
`docs/deployment.md`.

## Read these documents before touching production

1. **`docs/architecture.md`** — why the system is built this way
   (async task queue, model loading strategy, fail-fast startup, known
   v1 limitations). Read this first.
2. **`docs/data_sourcing.md`** — where to get real IMD/ICRISAT/Agmarknet
   data and the licensing considerations for commercial use. Critical
   to resolve before a real client launch.
3. **`docs/deployment.md`** — step-by-step VPS deployment, both
   bare-metal/systemd and Docker Compose paths.
4. **`docs/api_contract.md`** — the request/response contract for
   whoever builds the frontend.

## Production readiness summary

What this system has, built in from the start rather than bolted on
afterward:

- Async task queue (Celery + Redis) so ML/LLM compute never blocks web
  request handling, built for the client's stated "high scale from day
  one" requirement
- Per-model graceful degradation — one model failing returns a partial,
  clearly-labeled result instead of a total error
- Fail-fast startup — the service refuses to start if models or
  reference data are missing/corrupt, rather than starting broken
- Redis result caching with automatic invalidation on model version
  bump
- PostgreSQL audit trail of every analysis (and every failure) for
  client-facing usage analytics
- API key authentication + rate limiting
- Structured JSON logging with request-ID tracing through every layer
- Prometheus metrics + example Grafana dashboard
- Full automated test suite (unit + integration) runnable without live
  infrastructure, plus a Locust load test script
- CI pipeline (lint, test, Docker build) on every push
- Two deployment paths (bare-metal systemd or Docker Compose), both
  documented step by step
- Database migrations via Alembic, never manual schema changes
- Honest, code-comment-documented list of v1 limitations (see bottom of
  `docs/architecture.md`) rather than hidden gaps

## Known v1 limitations

See the "Known v1 limitations" section at the bottom of
`docs/architecture.md`. None of these break the system in production —
they degrade to clearly-labeled null/placeholder values — but they are
listed explicitly so they're a visible roadmap item for the next
development phase, not a surprise discovered later.

## Support

If something breaks in production, the structured logs (tagged with a
`request_id` that's also returned to the client in every error
response) are the fastest path to diagnosis: `journalctl -u crop-ai-api
-f` and `journalctl -u crop-ai-worker -f` on the VPS, or `docker compose
logs -f` if deployed via Docker.