# EAMCO Auto-Delivery API

The **EAMCO Auto-Delivery API** is an intelligent microservice responsible for managing and automating heating oil deliveries. Using a predictive model based on weather data, it estimates when customers will need a refill and helps schedule deliveries proactively.

This service is the backbone of the automatic delivery program, featuring a self-correcting algorithm that refines its predictions over time, ensuring customers never run out of oil.

[![Language](https://img.shields.io/badge/Language-Python%203.11-blue)](https://www.python.org/)
[![Framework](https://img.shields.io/badge/Framework-FastAPI-green)](https://fastapi.tiangolo.com/)
[![Database](https://img.shields.io/badge/Database-PostgreSQL-blue)](https://www.postgresql.org/)

---

## Core Features

- **Predictive Fuel Estimation**: The core `FuelEstimator` script calculates daily fuel consumption for each automatic delivery customer based on historical temperature data (Heating Degree Days).
- **Intelligent K-Factor**: Each customer has a unique "K-Factor" (house consumption factor) that represents their home's specific fuel usage rate.
- **Self-Correcting Algorithm**: After a delivery is completed, the service uses the actual gallons delivered to refine the customer's K-Factor, making future predictions progressively more accurate.
- **Automated Delivery Ticketing**: Automatically identifies customers who are low on fuel and provides endpoints to create delivery tickets.
- **Driver and Delivery Management**: Offers API endpoints to view upcoming deliveries for all customers or for specific drivers.
- **Weather Integration**: Fetches daily temperature data from a weather API to feed its prediction model.

## How It Works

The service's intelligence lies in its daily estimation and refinement cycle:

1.  **Daily Update**: A scheduled job calls the `/main/update/auto` endpoint.
2.  **Fetch Temperature**: The service ensures it has the latest daily temperature from an external weather API.
3.  **Estimate Consumption**: For each customer, it calculates the day's estimated fuel consumption using the temperature and the customer's unique K-Factor.
4.  **Identify Low-Fuel Customers**: It queries for customers whose estimated remaining gallons have fallen below a certain threshold.
5.  **Create Tickets**: The system (or a user) can then create a delivery ticket for these customers via the `/confirm/auto/create/{autoid}` endpoint.
6.  **Confirm Delivery**: Once the delivery is made, a `PUT` request to `/confirm/auto/update/{autoid}` with the actual `gallons_delivered` is made.
7.  **Refine K-Factor**: This is the crucial step. The service compares its predicted usage against the actual usage (based on gallons delivered) and adjusts the K-Factor, improving the accuracy of all future predictions for that customer.

---

## API Endpoints

### Main Triggers

- `GET /main/temp`
  - **Description**: Manually triggers the fetch and storage of the current day's temperature.
- `GET /main/update/auto`
  - **Description**: The main cron job entry point. Triggers the daily fuel consumption update for all automatic delivery customers.
- `GET /main/update/normal`
  - **Description**: Triggers the daily fuel consumption update for "normal" (non-auto) customers.

### Delivery & Ticket Management

- `POST /confirm/auto/create/{autoid}`
  - **Description**: Creates a new delivery ticket for an automatic delivery customer, often with pre-authorization details.
- `PUT /confirm/auto/update/{autoid}`
  - **Description**: Confirms a delivery by providing the actual gallons delivered. This triggers the K-Factor refinement.
- `GET /delivery/all/customers`
  - **Description**: Returns a list of all automatic delivery customers, ordered by who needs a delivery most urgently.
- `GET /delivery/driver/{driver_employee_id}`
  - **Description**: Gets a list of all pending automatic deliveries assigned to a specific driver.

---

## Getting Started

### Prerequisites

- Python 3.10+
- PostgreSQL database
- Access to a weather API (configured in settings).

### Installation

1.  **Clone the repository and navigate into it.**

2.  **Create a virtual environment and install dependencies:**
    ```bash
    python -m venv venv
    source venv/bin/activate
    pip install -r requirements.txt
    ```

3.  **Configure your environment:**
    The application's configuration is managed by environment variables set in `settings_local.py`, `settings_dev.py`, or `settings_prod.py`. The `MODE` environment variable determines which configuration to use.

### Running the Service

#### For Development

```bash
export MODE=DEVELOPMENT
uvicorn main:app --reload --host 0.0.0.0 --port <your_port>
```

The API will be available at `http://localhost:<your_port>`, with interactive docs at `http://localhost:<your_port>/docs`.

#### Using Docker

The project includes Dockerfiles for containerized deployment.

-   **Build the image:**
    ```bash
    docker build -f Dockerfile.local -t eamco_auto_api:local .
    ```
-   **Run the container:**
    ```bash
    docker run -d -p <your_port>:<your_port> --env MODE=LOCAL --name auto_api eamco_auto_api:local
    ```
---

## Project Structure

```
eamco_auto_api/
├── app/
│   ├── models/           # SQLAlchemy ORM models (Auto_Delivery, Tickets_Auto_Delivery)
│   ├── routers/          # API endpoint definitions (main, confirm, delivery)
│   ├── schema/           # Pydantic models (if any)
│   └── script/           # Core logic (FuelEstimator, temp_getter)
├── config.py             # Logic for loading environment-specific settings
├── database.py           # SQLAlchemy engine and session setup
├── main.py               # FastAPI application entry point
├── settings_local.py     # Settings for the LOCAL environment
├── requirements.txt      # Python dependencies
└── README.md             # This file
```