# Chroma Awards Entry Triage CLI

## PURPOSE
When the Chroma Awards — "the world's largest AI film and media competition" — opens Season 2
with "more resources, bigger prizes," submissions arrive as a messy CSV export from whatever
intake system the team happens to be using. This project is a Click + Pandas command-line tool
that gives an awards coordinator an instant read on the pile: how many entries land in each
category, how they spread across the theme pillars ("tell your story," "true colors," and the
rest), which creators submitted most, and which entries share a media URL by mistake.

## WHY THIS MATTERS
Big competitions are triage problems. Before judging panels can be assigned, someone has to
answer concrete questions: do we have enough documentaries to justify the category? Is one
theme pillar starved? Did a creator accidentally double-submit? Pandas turns those questions
into one-liners; Click turns them into a reproducible, scriptable tool instead of a notebook
stuck on one machine.

## HOW TO BUILD
Install Click and Pandas, then build a command group where each subcommand loads the CSV once
with `pd.read_csv` and applies a chain of filters. Expose `--category` and `--theme` as
repeatable options and a `--top N` for leaderboards.

```python
import click, pandas as pd

@click.group()
def cli(): ...

@cli.command()
@click.argument("csv_path", type=click.Path(exists=True))
@click.option("--theme", multiple=True)
@click.option("--top", default=5, type=int)
def summarize(csv_path, theme, top):
    df = pd.read_csv(csv_path)
    if theme:
        df = df[df["theme"].isin(theme)]
    click.echo(df.groupby("category").size().sort_values(ascending=False).head(top))
```

Add `duplicates` and `creators` subcommands for the same loaded frame.

## WHEN TO USE IN PRODUCTION
Reach for it for recurring batch reporting on any tabular submission export — awards, grants,
hackathons, hiring funnels. It is scriptable and cron-friendly. Do **not** use it for interactive
exploration on huge (multi-GB) files: Pandas loads everything into memory, so switch to
Polars/DuckDB, or for real-time dashboards use the web/dashboard projects instead.

## HOW IT HELPS STUDENTS
Students learn idiomatic Click command design, Pandas filtering and `groupby`, and the habit of
separating data loading from reporting — transferable to any analytics-heavy backend role.

## STARTER CODE
`starter/main.py` contains a working Click group with `summarize`, `duplicates`, and `creators`
subcommands and a small sample loader. `# TODO` markers flag where to add CSV column validation.
