CALICO Spring 2026 Raffle

This repository contains the code used to run the official raffle for CALICO Spring 2026. It processes contest data, awards raffle tickets based on problem-solving performance, and draws winners reproducibly using a fixed random seed.

---

🧩 Overview

The raffle system works as follows:

1. Load contest data (scoreboard, team info, raffle preferences, etc.) from the data/ directory.
2. Compute ticket counts based on each team’s solves, ignoring disqualified teams.
3. Generate tickets for individual contestants, based on team performance and submitted preferences.
4. Run the raffle deterministically using a provided seed and prize inventory.
5. Write results (including ticket counts and winners) to the data/calico-sp26/processed/ directory.

---

📁 Project Structure

raffle-sp26/
├── data/
│   └── calico-sp26/
│       ├── raw/
│       │   ├── raffle_inventory.json
│       │   ├── raffle_seed.txt
│       │   ├── scoreboard.json
│       │   └── teams.json
│       └── processed/
│           ├── raffle_preferences_without_emails.json
│           ├── raffle_ticket_counts.json
│           └── raffle_winners.txt
├── scripts/
│   └── calico-sp26/
│       └── raffle/
│           ├── constants.py
│           ├── raffle_public.py  ← main entry point
│           ├── utils.py
├── requirements.txt
└── README.md

---

🚀 Setup and Usage

1. Install dependencies:

   pip install -r requirements.txt

2. Run the raffle:

   python scripts/calico-sp26/raffle/raffle_public.py

   This will:

   • Print progress and summary messages to the console.
   • Write outputs to data/calico-sp26/processed/raffle_ticket_counts.json and raffle_winners.txt.

3. Inspect results:

   • raffle_winners.txt → human-readable winner list.
   • raffle_ticket_counts.json → ticket distribution by team.

---

🧠 How It Works

• Tickets: Each team gets 10 tickets for their first solve and 1 for each additional solve.
• Eligibility: Disqualified teams are excluded.
• Raffle logic: Randomized and reproducible — the same seed will yield the same results.
• Prizes: Assigned according to contestants’ stated preferences, one win per contestant.

---

🧩 Example Output

After running the script, you’ll see a message like:

[INFO] Beginning raffle
[INFO] Ignoring total 3 disqualified teams
[INFO] Created total 820 tickets
[INFO] Awarded 45 prizes
[INFO] Winners message saved to /data/.../processed/raffle_winners.txt

Example snippet from raffle_winners.txt:

CALICOngratulations to the following CALICOntestants for winning the raffle!
1. **Jane Doe** from **Team Syntax Error** drew Logitech MX Master 3!
2. **Alex Kim** from **Team Overflow** drew Raspberry Pi 5!

---

🌱 Random Seed Source

The raffle’s random seed is exported directly from the #seed-sp26 channel in the official CALICO Community Discord. This ensures that the drawing process is transparent, verifiable, and reproducible — anyone with the same seed and data can reproduce the exact same set of winners.

The seed value is stored in:

data/calico-sp26/raw/raffle_seed.txt

and is automatically loaded by the raffle script at runtime.

---

🛠️ Developer Notes

• All paths and constants are centralized in scripts/calico-sp26/raffle/constants.py.
• Utility I/O functions (e.g., JSON/TXT loaders) are in scripts/calico-sp26/raffle/utils.py.
• To test changes, modify the data files under data/calico-sp26/raw/ and rerun the script.