source/README.md

---
title: Transportation AI System
emoji: 🚚
colorFrom: blue
colorTo: green
sdk: docker
pinned: false
license: mit
---

An AI-powered system to predict optimal transportation modes for logistics and supply chain management, deployable via Docker.

## Quick Start with Docker

### Option 1: Frontend Only (Gradio UI)

```bash
# Build and run frontend only
docker build -t transportation-ai .
docker run -p 7860:7860 transportation-ai
```

### Option 2: Backend + Frontend (Recommended)

```bash
# Run both services with docker-compose
docker-compose up -d
```

### Option 3: All-in-one Container

```bash
# Run both services in single container
docker-compose --profile all-in-one up
```

## Development Setup

### Local Development

```bash
# Install dependencies
pip install -r requirements.txt

# Start backend API
python -m src.main

# Start frontend (in another terminal)
python app.py
```

### Windows Users

```batch
# Use the batch script
start.bat
```

### Linux/Mac Users

```bash
# Use the shell script
chmod +x start.sh
./start.sh
```

## Features

### Transportation Prediction

- Predict optimal shipping methods (Air, Air Charter, Ocean, Truck)
- Display confidence scores and alternatives  
- Interactive probability distribution charts
- Automatic weight and cost estimation

### AI Chat Assistant

- Chat about transportation and logistics
- Get insights on shipping methods
- Compare different transportation modes
- Cost analysis and optimization tips

## How to Use

1. **Prediction Tab**: Enter shipment details to get AI recommendations
2. **Chat Tab**: Ask questions about transportation and logistics

## Docker Services

### Backend API (Port 3454)

- FastAPI server với prediction endpoints
- Loads models from Hugging Face
- REST API documentation tại `/docs`

### Frontend UI (Port 7860)

- Gradio interface
- Real-time streaming chat
- Interactive prediction forms

## Technical Details

- **Model**: XGBoost trained on logistics data từ Hugging Face
- **Input Features**: Project code, country, price, vendor, weight, etc.
- **Output**: Transportation mode with confidence score
- **Framework**: FastAPI + Gradio + scikit-learn + XGBoost
- **Deployment**: Docker + Docker Compose

## Sample Questions for Chat

- "Compare Air vs Ocean transportation"
- "What affects shipping costs?"
- "When should I use truck transport?"
- "Optimize logistics for my company"

## Configuration

### Environment Variables

```env
GEMINI_API_KEY=your_gemini_api_key
ACCESS=your_huggingface_token
API_BASE_URL=http://localhost:3454/api
```

### Docker Compose Services

- `backend`: FastAPI server (port 3454)
- `frontend`: Gradio UI (port 7860)  
- `app`: All-in-one service (both ports)

## API Endpoints

- `GET /` - API status
- `POST /api/predict-transportation` - Prediction
- `GET /api/transportation-options` - Available options
- `POST /api/chat` - AI chat (streaming)

Built with Docker, FastAPI, Gradio and XGBoost