🐄 USACO Training Tool

A command-line tool for practicing USACO problems locally — no browser, no distractions.

════════════════════════════════════════════════════════════════════════
                       🐄  USACO TRAINING TOOL
                  Practice problems from USACO contests
════════════════════════════════════════════════════════════════════════

  Problem: Cowntagion
════════════════════════════════════════════════════════════════════════
  Contest  : December 2020
  Division : Silver
  Topics   : trees, greedy, BFS
  URL      : http://usaco.org/index.php?page=viewproblem2&cpid=1068

────────────────────────────────────────────────────────────────────────
  PROBLEM STATEMENT
────────────────────────────────────────────────────────────────────────
  Farmer John has N farms (1≤N≤100,000) connected by N-1 roads
  forming a tree. Farm 1 starts with one sick cow...

---

Features

• Filter problems by division, topic, and year range
• Random selection — never shows the same problem twice in a row
• Timer mode — track how long your solve takes
• Mark solved — saves your progress locally to progress.json
• Open in browser — jump straight to the official USACO problem page
• Progress history — view all solved problems grouped by division
• Zero dependencies — pure Python standard library, nothing to install

---

Quickstart

Requirements: Python 3.10 or later

# 1. Clone the repo
git clone https://github.com/Frostand/usaco-trainer.git
cd usaco-trainer

# 2. Run it
python main.py

That's it. No pip install, no virtual environment needed.

---

Usage

When you run main.py, you'll be walked through a short setup:

1. Pick a division     → Bronze / Silver / Gold / Platinum
2. Enter a topic       → e.g. "graphs", "DP", "greedy"  (optional)
3. Set a year range    → e.g. 2018–2022  (optional)

A random matching problem is then displayed. After reading, you choose what to do next:

Key	Action
1	Next random problem (same filters)
2	Start / stop a timer
3	Mark problem as solved
4	Open in browser
5	View solved history
6	New search (change filters)
7	Quit

---

Project Structure

usaco-trainer/
├── main.py          # Entry point — run this
├── data_loader.py   # Loads and validates problems.json
├── filter.py        # Filtering and random selection logic
├── display.py       # All terminal output and formatting
├── progress.py      # Saves your solved problems locally
├── problems.json    # The problem dataset (add your own!)
└── README.md

---

Adding Problems

Edit problems.json and append objects in this format:

{
  "id": "dec23_silver_1",
  "name": "Problem Name",
  "year": 2023,
  "contest": "December",
  "division": "Silver",
  "tags": ["graphs", "BFS"],
  "url": "http://usaco.org/index.php?page=viewproblem2&cpid=XXXX",
  "statement": "Full problem statement here...",
  "sample_input": "3\n1 2 3",
  "sample_output": "6",
  "sample_explanation": "Optional explanation of the sample."
}

Valid divisions: Bronze · Silver · Gold · Platinum
Valid contests: December · January · February · US Open

The official problem archive lives at usaco.org.
USACO Guide is great for finding problems by topic.

---

Progress Tracking

When you mark problems as solved, a progress.json file is created in the project folder. This file is listed in .gitignore so your personal progress stays local and doesn't get committed.

To reset your progress, simply delete progress.json.

---

Contributing

Contributions welcome! The most helpful thing you can do is add more problems to problems.json.

1. Fork the repo
2. Add problems following the format above
3. Open a pull request

Please make sure each problem has accurate sample I/O copied from the official USACO site.

---

License

MIT — free to use, modify, and share.

---

Built for competitive programmers who want to grind USACO problems without leaving the terminal.

---

Project Structure

usaco_trainer/
├── main.py          # Entry point — run this
├── data_loader.py   # Loads and validates problems.json
├── filter.py        # Filtering and random selection logic
├── display.py       # All terminal formatting and prompts
├── progress.py      # Saves your solved problems locally
├── problems.json    # The problem dataset (edit to add more!)
└── README.md        # This file

---

How to Run

Requirements: Python 3.10 or later (uses list[dict] type hints)

# Navigate into the folder
cd usaco_trainer

# Run the tool
python main.py

That's it — no external libraries required. Pure Python standard library.

---

How to Use

1. Pick your division: Bronze, Silver, Gold, or Platinum
2. Enter a topic (optional): e.g. graphs, DP, greedy
3. Set a year range (optional): e.g. 2018–2022
4. A random matching problem is shown in your terminal
5. After reading the problem, choose what to do next:
   • 1 → Next problem (same filters)
   • 2 → Start a timer to track your solve time
   • 3 → Mark the problem as solved
   • 4 → Open it in your browser on usaco.org
   • 5 → View all problems you've solved so far
   • 6 → Start a new search with different filters
   • 7 → Quit

---

Adding More Problems

Edit problems.json and add objects in this format:

{
  "id": "unique_id_here",
  "name": "Problem Name",
  "year": 2023,
  "contest": "December",
  "division": "Silver",
  "tags": ["graphs", "BFS"],
  "url": "http://usaco.org/...",
  "statement": "Full problem statement text here...",
  "sample_input": "3\n1 2 3",
  "sample_output": "6",
  "sample_explanation": "Sum of 1+2+3 = 6 (optional field)"
}

Valid divisions: Bronze, Silver, Gold, Platinum Valid contests: December, January, February, US Open

---

Solved Progress

When you mark problems as solved, they're saved in progress.json (auto-created in the same folder). This file is human-readable JSON — you can delete entries to "unsolve" problems if needed.

---

Tips for Growing the Dataset

• The official USACO problem archive is at: http://usaco.org/index.php?page=contests
• Problems are publicly available; copy statements manually into the JSON
• Community sites like USACO Guide (https://usaco.guide) tag problems by topic

---

Common Issues

Problem	Fix
FileNotFoundError	Make sure problems.json is in the same folder as main.py
python: command not found	Try python3 main.py instead
Terminal looks garbled	Resize your terminal to at least 72 columns wide