SETUP.md

# Setup and Recreation Guide

This document provides instructions on how to set up and recreate the Predictive Machine project locally without overwriting the `README.md` file (which is essential for Hugging Face Spaces).

## Prerequisites

- Python 3.8 or higher
- pip (Python package manager)
- Git
- Docker (optional, for containerized deployment)

## Local Setup

### 1. Clone the Repository

```bash
git clone https://huggingface.co/spaces/Asah-ML-Copilot-A25-CS047/Predictive-Machine
cd Predictive-Machine
```

### 2. Create a Virtual Environment

```bash
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
```

### 3. Install Dependencies

```bash
pip install -r requirements.txt
```

### 4. Download the Dataset

The project uses the Kaggle dataset: [Machine Predictive Maintenance Classification](https://www.kaggle.com/datasets/shivamb/machine-predictive-maintenance-classification/data)

- Download the dataset from Kaggle
- Extract it to a `data/` directory in the project root
- Or set up Kaggle API credentials:

```bash
pip install kaggle
kaggle datasets download -d shivamb/machine-predictive-maintenance-classification
unzip machine-predictive-maintenance-classification.zip -d data/
```

### 5. Run the Application

```bash
uvicorn app:app --reload
```


## Preserving README.md for Hugging Face Spaces

**Important:** The `README.md` file contains critical Hugging Face Spaces configuration metadata (YAML front matter). When updating the project:

1. **Never overwrite or delete `README.md`**
2. Keep the YAML header intact:
   ```yaml
   ---
   title: Predictive Machine
   emoji: 🚨
   colorFrom: pink
   colorTo: indigo
   sdk: docker
   pinned: true
   license: apache-2.0
   short_description: Predictive Machine Copilot for Asah by Dicoding x Accenture
   datasets: [https://www.kaggle.com/datasets/shivamb/machine-predictive-maintenance-classification/data]
   ---
   ```
3. Use this `SETUP.md` file for development documentation instead
4. If you need to update README.md content, only modify the area AFTER the closing `---`

## Docker Deployment

### Build the Docker Image

```bash
docker build -t predictive-machine .
```

### Run the Container

```bash
docker run -p 7860:7860 predictive-machine
```

The application will be available at `http://localhost:7860`

## Project Structure

```
Predictive-Machine/
├── README.md              # Hugging Face Spaces config (DO NOT OVERWRITE)
├── SETUP.md              # This file - local setup instructions
├── Dockerfile            # Docker configuration
├── requirements.txt      # Python dependencies
├── app.py               # Main application
├── data/                # Dataset directory
├── models/              # Trained models
└── src/                 # Source code modules
```

## Development Workflow

1. Create a new branch for features:
   ```bash
   git checkout -b feature/your-feature-name
   ```

2. Make changes and test locally

3. Commit and push changes:
   ```bash
   git add .
   git commit -m "Description of changes"
   git push origin feature/your-feature-name
   ```

4. Create a pull request

5. Once merged, the changes will be reflected in the Hugging Face Spaces deployment

## Troubleshooting

### Dataset Download Issues
- Ensure you have Kaggle API credentials configured: `~/.kaggle/kaggle.json`
- Or download manually from Kaggle and place files in `data/` directory

### Dependency Conflicts
```bash
pip install --upgrade pip
pip install -r requirements.txt --force-reinstall
```

### Docker Build Issues
```bash
docker build --no-cache -t predictive-machine .
```

## License

This project is licensed under the Apache 2.0 License - see LICENSE file for details.

## Resources

- [Hugging Face Spaces Documentation](https://huggingface.co/docs/hub/spaces)
- [Hugging Face Spaces Config Reference](https://huggingface.co/docs/hub/spaces-config-reference)
- [Dataset: Machine Predictive Maintenance Classification](https://www.kaggle.com/datasets/shivamb/machine-predictive-maintenance-classification)