# Gathering API

This is a Flask-based API that captures and validates form submissions from the gathering HTML form.

## Setup Instructions

### 1. Set up OpenAI API Key

Before running the API, set your OpenAI API key as an environment variable:

**Windows (PowerShell)**:
```powershell
$env:OPENAI_API_KEY = "your-api-key-here"
```

**Windows (Command Prompt)**:
```cmd
set OPENAI_API_KEY=your-api-key-here
```


**Linux/Mac**:
```bash
export OPENAI_API_KEY="your-api-key-here"
```

### 2. Install Python Dependencies

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

### 3. Run the API Server

```bash
python gathering.py
```

The server will start on `http://localhost:3000`

## API Endpoints

### 1. Submit Gathering Data
- **URL**: `/api/gathering`
- **Method**: `POST`
- **Content-Type**: `multipart/form-data`
- **Parameters**:
  - `gatheringType` (required): Selected gathering type
  - `participants` (required): Number of participants (integer)
  - `gender` (required): Gender selection
  - `ageRange` (required): Selected age range
  - `culturalContext` (required): Cultural/Regional context
  - `picture` (required): Image file
  - `objects` (optional): Text description of objects

**Response (Success)**:
```json
{
  "success": true,
  "message": "Data submitted successfully",
  "data": {
    "gatheringType": "Family",
    "participants": 20,
    "gender": "Both",
    "ageRange": "26-35",
    "culturalContext": "North Indian",
    "picture": "20231215_143022_photo.jpg",
    "pictureUrl": "/api/uploads/20231215_143022_photo.jpg",
    "objects": "Books and memorabilia",
    "submittedAt": "2023-12-15T14:30:22.123456",
    "gameSuggestions": "**1. Bollywood Charades**\n* **Justification:** Perfect for Indian culture enthusiasts, high-energy competitive activity\n* **Props:** Paper, pens, timer\n* **Instructions:** Teams take turns acting out Bollywood movie titles while others guess..."
  }
}
```

**Response (Validation Error)**:
```json
{
  "success": false,
  "message": "Validation failed",
  "errors": {
    "participants": "No. Of Participants must be a positive integer"
  }
}
```

### 2. Get All Submissions
- **URL**: `/api/submissions`
- **Method**: `GET`
- **Response**: Array of all submitted data

### 3. Download Uploaded Picture
- **URL**: `/api/uploads/<filename>`
- **Method**: `GET`

### 4. Health Check
- **URL**: `/api/health`
- **Method**: `GET`

## Features

✅ **Data Validation**
- Validates all required fields
- Checks for valid gathering types, genders, age ranges, and cultural contexts
- Validates participant count is a positive integer

✅ **File Upload Handling**
- Accepts only image files (JPG, PNG, GIF, WebP)
- Enforces 5MB file size limit
- Automatically timestamps filenames to prevent conflicts

✅ **AI-Powered Game Suggestions**
- Integrates with OpenAI API to generate 3 unique game recommendations
- Game suggestions are tailored to the gathering context, culture, and participants
- Suggestions include game titles, justifications, required props, and instructions
- Formatted as poster-style WhatsApp-friendly content

✅ **Data Storage**
- Saves submissions to `submissions.json`
- Stores uploaded images in `uploads/` folder
- Preserves all submission history with AI-generated suggestions

✅ **Error Handling**
- Comprehensive validation error messages
- Detailed HTTP status codes
- JSON-formatted responses for all endpoints

## File Structure

```
api/
├── gathering.py           # Main API file
├── requirements.txt       # Python dependencies
├── submissions.json       # Stored submissions (auto-created)
├── uploads/              # Uploaded images (auto-created)
└── README.md            # This file
```

## CORS Configuration

If you need to enable CORS for cross-origin requests, add this to `gathering.py`:

```python
from flask_cors import CORS

CORS(app)
```

And install the extension:
```bash
pip install flask-cors
```

## Environment Variables

- `OPENAI_API_KEY`: Your OpenAI API key (required for game suggestions)
  - Get your API key from: https://platform.openai.com/api-keys
  - Ensure your OpenAI account has sufficient credits

## Troubleshooting

**Port already in use**:
Change the port in the last line of `gathering.py`:
```python
app.run(debug=True, host='localhost', port=5000)  # Change 3000 to 5000
```

**Permission denied for uploads folder**:
Ensure the `api/` directory has write permissions.