note

its 2025 and nobody actually writes their own documentation anymore xd i told ChatGPT what this thing does and it spat out the rest lmao if somethings wrong just pretend it isnt

fyi 100% of the actual raffle code was written by a human though (me)

-ryan

CALICO Spring 2025 Raffle

This repository contains the code used to run the official raffle for CALICO Spring 2025. 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 or withdrawn 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-sp25/processed/ directory.

---

📁 Project Structure

raffle-sp25/
├── data/
│   └── calico-sp25/
│       ├── 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-sp25/
│       ├── constants.py
│       ├── raffle_public.py  ← main entry point
│       ├── utils.py
│       └── __init__.py
├── requirements.txt
└── README.md

---

🚀 Setup and Usage

1. Install dependencies:

   pip install -r requirements.txt

2. Run the raffle:

   python scripts/calico-sp25/raffle_public.py

   This will:

   • Print progress and summary messages to the console.
   • Write outputs to data/calico-sp25/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.
   • raffle_inventory.json → remaining prize counts.

---

🧠 How It Works

• Tickets: Each team gets 10 tickets for their first solve and 1 for each additional solve.
• Eligibility: Disqualified or withdrawn 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 3 disqualified teams
[INFO] Created total 820 tickets
[INFO] Awarded 45 prizes
[INFO] Winners message saved to /data/.../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 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-sp25/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-sp25/constants.py.
• Utility I/O functions (e.g., JSON/TXT loaders) are in scripts/calico-sp25/utils.py.
• To test changes, modify the data files under data/calico-sp25/raw/ and rerun the script.