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.

---

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:

   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

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:

  docker build -f Dockerfile.local -t eamco_auto_api:local .
  

• Run the container:

  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