AERIS-AQ

AERIS-AQ is an air-quality decision-support API for operational and policy workflows.

What This Build Prioritizes

• Accurate, source-aware air-quality responses
• Conservative health guidance for sensitive populations
• Clean failure behavior (no stack traces or internal tool leaks)
• Free-tier cold-start handling for deployments that sleep when idle
• Leaner prompt instructions for lower token cost and more stable outputs

Key Endpoints

• POST /api/v1/agent/chat - primary conversational endpoint
• POST /api/v1/air-quality/query - structured multi-source air data query
• GET /api/v1/sessions - list sessions
• POST /api/v1/sessions/new - create session
• GET /api/v1/sessions/{session_id} - session details
• DELETE /api/v1/sessions/{session_id} - delete session
• GET /health - liveness + startup metadata
• GET /health/detailed - component health and metrics
• GET /health/readiness - readiness gate for free-tier warmup

Free-Tier Cold-Start Behavior

If your deployment sleeps during inactivity (for example free Render), enable:

FREE_TIER_DEPLOYMENT=true
COLD_START_WAIT_SECONDS=50

Behavior:

• During warmup, POST /api/v1/agent/chat returns 503 with:
  • status: warming_up
  • message explaining the server is waking up
  • retry_after seconds
• GET /health/readiness returns 503 until warmup window ends.
• Database and timeout handlers include a cold-start hint when applicable.

Quick Start

python -m venv .venv
. .venv/Scripts/activate  # Windows PowerShell
pip install -r requirements.txt
copy .env.example .env
python -m uvicorn interfaces.rest_api.main:app --host 0.0.0.0 --port 8000

Open docs at http://localhost:8000/docs.

Environment Essentials

Required/important settings:

AI_PROVIDER=gemini
AI_MODEL=gemini-1.5-flash
AI_API_KEY=...

DATABASE_URL=sqlite:///./data/chat_sessions.db
ENABLED_DATA_SOURCES=waqi,airqo,openmeteo,carbon_intensity,defra,uba,nsw

FREE_TIER_DEPLOYMENT=false
COLD_START_WAIT_SECONDS=50

Operational Guidance

• Treat outputs as decision support, not a medical diagnosis.
• For high-risk alerts, always include local authority validation paths in your frontend/workflow.
• Monitor /health/detailed and /metrics in production.
• Keep API keys and secrets out of client applications.

Testing

pytest -q

Run before deployment after config or prompt changes.

Project Structure

• interfaces/rest_api/ - API routes and app bootstrap
• domain/services/ - core agent orchestration
• core/memory/prompts/ - system instruction builder
• infrastructure/api/ - external provider integrations
• shared/config/ - settings and environment handling
• tests/ - integration and behavior tests