Installation

Installation guide for AQI prediction systems

Documentation Note: This guide describes typical installation patterns for AQI prediction systems. For current implementation status and actual installation instructions, visit the GitHub repository.

System Requirements

Typical system requirements for running AQI prediction models:

Python Version

Python 3.8 or higher

Operating System

Linux, macOS, or Windows

Memory

Minimum 4GB RAM (8GB recommended)

Storage

At least 500MB free disk space

Basic Installation

Install AQI Predictor using your preferred package manager:

pip

pip install aqi-predictor

Verify the installation:

python -c "import aqi_predictor; print(aqi_predictor.__version__)"

Expected Output

1.2.3

Installation Options

Minimal Installation

Install only the core prediction functionality without training dependencies:

pip install aqi-predictor --no-deps
pip install numpy pandas requests

This is ideal for production environments where you only need to make predictions using pre-trained models.

Full Installation

Install with all dependencies for model training, evaluation, and visualization:

pip install aqi-predictor[full]

This includes:

• Deep learning frameworks (TensorFlow, PyTorch)
• Advanced ML libraries (XGBoost, LightGBM)
• Visualization tools (Matplotlib, Seaborn, Plotly)
• Data processing utilities

Development Installation

For contributors or advanced users who want to modify the source code:

git clone https://github.com/git-devisha/aqi-predictor.git
cd aqi-predictor
pip install -e ".[dev]"

This installs the package in editable mode with development dependencies (pytest, black, mypy, etc.).

GPU Support

For faster model training, install GPU-accelerated versions of deep learning frameworks:

TensorFlow GPU

# For CUDA 11.2+
pip install aqi-predictor
pip install tensorflow[and-cuda]

# Verify GPU is available
python -c "import tensorflow as tf; print(tf.config.list_physical_devices('GPU'))"

PyTorch GPU

# For CUDA 11.8
pip install aqi-predictor
pip install torch torchvision --index-url https://download.pytorch.org/whl/cu118

# Verify GPU is available
python -c "import torch; print(torch.cuda.is_available())"

Metal (Apple Silicon)

# For M1/M2 Macs
pip install aqi-predictor
pip install tensorflow-metal

# Verify Metal is available
python -c "import tensorflow as tf; print(tf.config.list_physical_devices())"

GPU support significantly speeds up training but is not required for making predictions with pre-trained models.

Docker Installation

Run AQI Predictor in a Docker container for isolated and reproducible environments:

Using Pre-built Image

docker pull aqipredictor/aqi-predictor:latest
docker run -it --rm aqipredictor/aqi-predictor:latest python

Building from Source

Dockerfile

FROM python:3.10-slim

WORKDIR /app

# Install system dependencies
RUN apt-get update && apt-get install -y \
    build-essential \
    curl \
    && rm -rf /var/lib/apt/lists/*

# Install AQI Predictor
RUN pip install --no-cache-dir aqi-predictor[full]

# Copy your application code
COPY . /app

CMD ["python", "your_script.py"]

Build and run:

docker build -t my-aqi-app .
docker run -e AQI_API_KEY=your_key my-aqi-app

Docker Compose

For more complex setups with databases or multiple services:

docker-compose.yml

version: '3.8'

services:
  aqi-predictor:
    image: aqipredictor/aqi-predictor:latest
    environment:
      - AQI_API_KEY=${AQI_API_KEY}
    volumes:
      - ./models:/app/models
      - ./data:/app/data
    ports:
      - "8000:8000"
    command: python api_server.py

Run with:

docker-compose up

Configuration

Environment Variables

Configure AQI Predictor using environment variables:

.env

# API Configuration
AQI_API_KEY=your_api_key_here
AQI_API_URL=https://api.aqipredictor.com/v1
AQI_TIMEOUT=30

# Model Configuration
AQI_MODEL_PATH=/path/to/models
AQI_DEFAULT_MODEL=lstm_v2

# Logging
AQI_LOG_LEVEL=INFO
AQI_LOG_FILE=/var/log/aqi-predictor.log

Load environment variables in your code:

from aqi_predictor import AQIClient
import os

client = AQIClient(
    api_key=os.getenv("AQI_API_KEY"),
    api_url=os.getenv("AQI_API_URL"),
    timeout=int(os.getenv("AQI_TIMEOUT", 30))
)

Configuration File

Create a configuration file for persistent settings:

config.yaml

api:
  key: your_api_key_here
  url: https://api.aqipredictor.com/v1
  timeout: 30
  retry_attempts: 3

model:
  path: ./models
  default: lstm_v2
  cache_predictions: true

logging:
  level: INFO
  format: "%(asctime)s - %(name)s - %(levelname)s - %(message)s"
  file: ./logs/aqi-predictor.log

Load the configuration:

from aqi_predictor import AQIClient
import yaml

with open("config.yaml") as f:
    config = yaml.safe_load(f)

client = AQIClient(
    api_key=config["api"]["key"],
    api_url=config["api"]["url"],
    timeout=config["api"]["timeout"]
)

Dependency Management

Managing Dependencies with Poetry

If you use Poetry for dependency management:

pyproject.toml

[tool.poetry.dependencies]
python = "^3.8"
aqi-predictor = "^1.2.0"

[tool.poetry.group.dev.dependencies]
pytest = "^7.0"
black = "^23.0"

Install:

poetry install

Managing Dependencies with Conda

Create a conda environment:

environment.yml

name: aqi-predictor
channels:
  - conda-forge
  - defaults
dependencies:
  - python=3.10
  - pip
  - pip:
    - aqi-predictor
    - python-dotenv

Create and activate:

conda env create -f environment.yml
conda activate aqi-predictor

Upgrading

Upgrade to Latest Version

pip install --upgrade aqi-predictor

Upgrade to Specific Version

pip install aqi-predictor==1.2.3

Check Current Version

import aqi_predictor
print(aqi_predictor.__version__)

Troubleshooting

ImportError: No module named 'aqi_predictor'

Solution:

1. Verify installation: pip list | grep aqi-predictor
2. Check Python environment: which python
3. Reinstall: pip install --force-reinstall aqi-predictor

SSL Certificate Verification Failed

Solution:

If you encounter SSL errors when installing:

pip install --trusted-host pypi.org --trusted-host files.pythonhosted.org aqi-predictor

Or upgrade pip and certificates:

pip install --upgrade pip certifi

TensorFlow/PyTorch Installation Issues

Solution:

Install deep learning frameworks separately:

# Install core package first
pip install aqi-predictor --no-deps

# Install dependencies manually
pip install numpy pandas requests
pip install tensorflow  # or pytorch

Memory Error During Training

Solution:

Reduce batch size or use gradient checkpointing:

from aqi_predictor import ModelTrainer

trainer = ModelTrainer()
trainer.train(
    batch_size=32,  # Reduce from default 128
    gradient_checkpointing=True
)

Permission Denied on Linux/macOS

Solution:

Install in user directory:

pip install --user aqi-predictor

Or use a virtual environment:

python -m venv venv
source venv/bin/activate
pip install aqi-predictor

Platform-Specific Notes

Windows

On Windows, you may need to install Visual C++ Build Tools:

1. Download from Microsoft C++ Build Tools
2. Install “Desktop development with C++” workload
3. Restart your terminal and retry installation

macOS

On macOS, install Xcode Command Line Tools:

xcode-select --install

Linux

On Linux, install build dependencies:

Ubuntu/Debian

sudo apt-get update
sudo apt-get install -y python3-dev build-essential

Offline Installation

For air-gapped environments without internet access:

1. Download the package and dependencies on a machine with internet:

pip download aqi-predictor -d ./aqi-packages

2. Transfer the aqi-packages directory to the offline machine

3. Install from the local directory:

pip install --no-index --find-links=./aqi-packages aqi-predictor

Uninstallation

Remove AQI Predictor from your system:

pip uninstall aqi-predictor

Remove configuration files and cached models:

rm -rf ~/.aqi-predictor

Next Steps

Now that you have AQI Predictor installed:

Quickstart

Make your first prediction in 5 minutes

Configuration

Learn about data preparation and configuration

API Reference

Explore the complete API documentation

Examples

View code examples and usage patterns

Having issues? Check our GitHub Issues or reach out on our community forum.