README.md

---
title: Beer Game Experiment
emoji: 🍺
colorFrom: purple
colorTo: green
sdk: streamlit
sdk_version: 1.32.0
app_file: app.py
pinned: false
license: mit
python_version: "3.10"
---

# 🍺 Beer Game — Human & AI Collaboration

This is a **Beer Game experiment interface** built with **Streamlit** and hosted on Hugging Face Spaces.  
The goal is to study **human behaviour in supply chain decision-making** when collaborating with AI agents (Factory, Wholesaler, Retailer powered by OpenAI GPT-4o-mini).

---

## 🎮 Roles

- **Distributor**: Human participant — you control the order quantity each week.  
- **Factory / Wholesaler / Retailer**: AI agents making decisions using LLMs.

---

## 📊 Features

- Classic Beer Game settings:
  - 36 weeks simulation
  - 2-week shipping delay
  - 1-week information delay
  - Standard customer demand sequence (constant → shock → fluctuations)
- Human plays as Distributor, other roles are LLM agents.
- Logs saved **per participant** and automatically pushed to Hugging Face Datasets Hub.
- Simple Streamlit interface, deployable on Hugging Face Spaces.
- 
---

## 🛠️ Running the Experiment

### 1. On Hugging Face Spaces
1. Deploy this repo as a **Streamlit Space**.  
2. Add **Secrets** (Settings → Secrets):
   - `OPENAI_API_KEY` — your OpenAI API key  
   - Optional for S3 export:  
     - `AWS_ACCESS_KEY_ID`  
     - `AWS_SECRET_ACCESS_KEY`  
     - `S3_BUCKET`  
     - `S3_REGION` (default: `us-east-1`)  

3. Participants open the Space and either:
   - Enter a custom **participant ID**, or  
   - Use the **auto-generated ID** shown in the app.  

Example URL with participant ID:  

https://huggingface.co/spaces/<user>/<space>?participant_id=ABC123

---


### 2. Locally
```bash
pip install -r requirements.txt
streamlit run app.py