Hackbeanpot Project

This backend powers the AI-driven carnival layout generator. It receives form data, asks the Gemini API to propose layouts, and returns structured layout data for the frontend to render.

1. The user fills out a form (event info + attractions).
2. The backend turns that into a clean request for the AI.
3. The AI responds with 2-3 layout options.
4. The backend returns those options to the frontend.

No drag-and-drop, no manual placement. Just input -> AI -> map.

• Client sends a request to the layout endpoint.
• The request is validated by Pydantic models.
• The layout planner builds constraints and a prompt.
• The Gemini client calls the API and gets a response.
• The backend returns layout options to the client.

The Carnival Layout Generator collects information about your event and attractions to create optimized layouts.

When the user submits a form, we collect the basic event details:

For each attraction (ride, food stall, game booth, stage, seating, utility, etc.), we collect:

You don't have to specify these—we calculate them from the venue dimensions:

• Restroom Facilities: 1 per acre (e.g., 5 acres = 5 restrooms)
• First Aid Stations: 1 per 2 acres (e.g., 5 acres = 3 stations)
• Security/Staff Stations: 1 per 1.5 acres (e.g., 5 acres = 4 stations)
• Utility Placement: Optimal locations for restrooms, first aid, and security

Endpoint: POST /api/v1/layouts/generate-maps

What it does: Takes your event and attraction data, uses AI to optimize placement, and returns 3 layout options.

Request body: Follows the schema shown above (event setup + attractions list)

Response:

{
  "success": true,
  "maps": [
    {
      "id": 1,
      "name": "Classic Flow Layout",
      "description": "Traditional carnival setup with entrance focus",
      "layout_text": "🎪 ASCII map of the layout...",
      "reasoning": "High-popularity attractions positioned near entrance..."
    },
    {
      "id": 2,
      "name": "Central Hub Layout",
      "description": "Circular radial design with central gathering space",
      "layout_text": "🎪 ASCII map of the layout...",
      "reasoning": "Radial layout encourages natural exploration..."
    },
    {
      "id": 3,
      "name": "Linear Journey Path",
      "description": "Guided path through themed zones",
      "layout_text": "🎪 ASCII map of the layout...",
      "reasoning": "Linear path guides visitors through distinct zones..."
    }
  ],
  "message": "Generated 3 carnival layouts for Summer Fair 2026 with 8 total attractions across 3 types"
}

The system enforces smart limits to keep requests reasonable:

• ✅ Event name: 1-255 characters
• ✅ Daily attendance: > 0 (up to 1 million)
• ✅ Venue width/length: > 0 feet (up to 100,000, whole numbers only for grid mapping)
• ✅ Popularity: Must be 1-5
• ✅ Dimensions: Must be > 0 feet, < 10,000 feet (whole numbers only for grid mapping)
• ✅ Attraction types: Max 100 different types
• ✅ Total units: Max 1,000 individual attractions across all types
• ✅ At least 1 attraction required

Endpoint: GET /api/v1/layouts/status

What it does: Checks if the Gemini API is configured and reachable.

Response:

{
  "gemini_configured": true,
  "gemini_reachable": true,
  "api_ready": true,
  "message": "Service is operational"
}

1. Copy env template:
   • Make a new file named .env in backend/.
   • Copy the contents of .env.example into it.
   • Add your Gemini API key.
2. Install Python packages:
   • Use pip install -r backend/requirements.txt.
3. Run the server:
   • Use uvicorn app.main:app --reload from inside backend/.
4. Open the API docs in your browser:
   • http://localhost:8000/docs

1. Install test tools:
   • Use pip install -r backend/requirements.txt.
2. Run tests from the repo root:
   • Use pytest backend/tests.

• backend/: Python backend root
• backend/app/: FastAPI app code
• backend/app/api/: API routes (HTTP endpoints)
• backend/app/core/: settings and logging setup
• backend/app/schemas/: request/response models
• backend/app/services/: business logic and Gemini integration
• backend/app/utils/: constants and validation helpers
• backend/tests/: backend tests

• backend/app/main.py: FastAPI app entry point and router wiring
• backend/app/api/layouts.py: layout generation endpoints
• backend/app/schemas/layout.py: layout request/response models
• backend/app/services/gemini_client.py: Gemini API wrapper
• backend/app/services/layout_planner.py: prompt and constraint builder
• backend/app/services/exporter.py: export hooks (PNG/PDF)
• backend/.env.example: sample environment variables
• backend/requirements.txt: Python dependencies

• If Gemini is not hooked up yet, we can return stubbed layout data.
• The frontend can render layouts as SVG or canvas based on the response.
• This repo currently focuses only on layout generation, not ticketing or payments.

The backend requires these environment variables. Copy .env.example to .env and configure:

Quick setup:

# 1. Install dependencies
cd backend
pip install -r requirements.txt

# 2. Copy the example file
cp .env.example .env

# 3. Edit .env and add your Gemini API key
# Get your key from: https://makersuite.google.com/app/apikey

# 4. Test your configuration
python test_config.py

# 5. Run the server
uvicorn app.main:app --reload

Important: Never commit your .env file! It contains sensitive API keys.

1. Go to Google AI Studio
2. Click "Get API Key" or "Create API Key"
3. Sign in with your Google account if prompted
4. Click "Create API key in new project" (or select an existing project)
5. Copy the generated API key (starts with AIza...)

⚠️ Important: Keep your API key secret! Never commit it to Git.

1. Navigate to the backend/ folder in your terminal:

   cd backend

2. Copy the example environment file:

   # On Mac/Linux
   cp .env.example .env
   
   # On Windows
   copy .env.example .env

3. Open .env in your text editor and add your key:

   GEMINI_API_KEY=AIzaSyYourActualKeyHere123456789

1. Start the backend server:

   cd backend
   py -m uvicorn app.main:app --reload

2. Look for this message in the terminal:

   🔑 Validating Gemini API key...
   ✅ Gemini API key is valid!

3. If you see an error, double-check:
   • Your .env file is in the backend/ folder
   • The key is copied correctly (no extra spaces)
   • You have internet connection

"GEMINI_API_KEY not found"

• Make sure .env file exists in backend/ folder
• Check that the variable name is exactly GEMINI_API_KEY=

"Rate limit exceeded"

• Gemini has free tier limits (60 requests/minute)
• Wait a minute and try again
• Consider upgrading your plan for higher limits

"Invalid API key"

• Generate a new key at Google AI Studio
• Make sure you copied the entire key

• 60 requests per minute
• 1,500 requests per day
• Should be plenty for hackathon testing!

For more info: Gemini API Documentation