AirSense is a full-stack air quality analytics platform that ingests data from multiple sources (Open-Meteo, OpenAQ, IQAir, WAQI), performs weighted aggregation with outlier trimming, and stores clean time-series data in MySQL. The system includes an AI-powered forecasting component using SARIMAX and an LLM-based planning agent that can convert natural-language queries into executable analytical plans. Developers can start the MCP-enabled server to enable orchestrated tool usage by the agent, enabling tasks such as city comparisons, KPI calculations, forecast generation, and PDF report creation. To interact with the server, run the MCP server via the configured uvicorn-based entry point and query the FastAPI endpoints for data access, analytics, and reporting features. The planning agent can be invoked to translate natural language requests (e.g., “compare PM2.5 trends across cities for last 30 days”) into reproducible analysis steps with transparent execution traces.

Prerequisites:

• Python 3.9+ and pip
• MySQL server and database created for AirSense data
• Git to clone the repository
• Optional: Ollama/Gemma or cloud LLM if using the enterprise planning agent

1. Clone the repository: git clone https://github.com/dyneth02/Air-Quality-Trends-Analysis-Project.git cd Air-Quality-Trends-Analysis-Project

2. Set up a Python virtual environment and activate it: python -m venv venv

   Windows

   venv\Scripts\activate

   macOS/Linux

   source venv/bin/activate

3. Install dependencies (backend and related tooling): pip install -r requirements.txt

   If a separate requirements file exists for the API, install it as well

4. Configure environment variables (examples):

   • DATABASE_URL=mysql+pymysql://user:pass@host:3306/airsense
   • JWT_SECRET=your_jwt_secret_key
   • LLM_PROVIDER=ollama or gemma
   • LLM_MODEL=air-sense-planner

5. Apply database migrations or initialize the MySQL schema as required by the project. (Refer to the project’s migration scripts or ORM setup in the data layer.)

6. Start the server (example using uvicorn entry point): uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

7. Optional: run the MCP server wrapper (as configured in mcp_config) to enable tool orchestration by the planning agent.

Tips and considerations:

• Ensure MySQL is reachable from the server environment and that the schema matches the ORM models.
• If using a cloud-hosted LLM, set OPENAI_API_KEY or equivalent environment variables as required by your provider.
• For local LLM execution (Ollama/Gemma), ensure the model is downloaded and accessible to the planning agent.
• The planning agent’s execution traces should be reviewed during first runs to validate security boundaries and capability limits.
• If you deploy in Docker, you may want to containerize the FastAPI app along with the MySQL instance or point to an external database to simplify setup.
• Check JWT expiration and token rotation strategies for long-running deployments.
• Update the environment variable placeholders with production-ready secrets before deploying.