📝 Add README.md

Author: Paillat-dev

README.md

@@ -0,0 +1,135 @@
+# ESC Dramatic Unpause
+
+A [Eurovision Song Contest](https://en.wikipedia.org/wiki/Eurovision_Song_Contest) (ESC) scoring prediction system that helps calculate the final televoting scores to determine the winner before the last country's points are announced.
+
+## What is this?
+
+This tool helps predict Eurovision Song Contest results by combining jury scores with televoting scores. **The main goal is to skip the 20-30 seconds when the last country is about to receive their televoting points**.
+
+By entering all but one country's televoting scores, the system calculates what the final country's score must be, instantly revealing the winner without the suspense. It features:
+
+- Interactive score entry with a beautiful terminal UI
+- Automatic calculation of the final missing televoting score
+- Dramatic pause with spinner animation (because Eurovision needs drama!)
+- Winner announcement with celebration
+
+## Features
+
+- **Interactive CLI**: Enter televoting scores one by one with Rich's beautiful interface
+- **Smart Validation**: Prevents negative scores and validates input format
+- **Backtrack Support**: Go back and correct previous entries with 'b'
+- **Automatic Calculation**: Calculates the final country's televoting score based on ESC rules
+- **Dramatic Presentation**: Includes spinner animations and winner announcements
+- **Comprehensive Testing**: Full test suite with historical ESC data
+
+## Motive
+
+While the main goal of this project is the one described above, it was the occasion for me to learn how to create CLI apps in python (with Typer) and how to create beautiful terminal UIs (with Rich), with an original idea.
+
+## Requirements
+
+- Python 3.12 or higher
+- Dependencies are managed via [`uv`](https://github.com/astral-sh/uv)
+
+## Installation
+
+1. Clone the repository:
+```bash
+git clone h
+cd esc-drammatic-unpause
+```
+
+2. Install dependencies using `uv`:
+```bash
+uv sync
+```
+
+Or using pip:
+```bash
+pip install -e .
+```
+
+## Usage
+
+### Basic Usage
+
+Run the program with a jury scores file:
+
+```bash
+python -m src
+```
+
+### Custom Options
+
+```bash
+python -m src --jury-path your_jury_file.txt --participating-countries 37 --rest-of-world-vote
+```
+
+Available options:
+- `--jury-path`: Path to jury scores file (default: `jury.txt`)
+- `--participating-countries`: Number of participating countries (default: 37)
+- `--rest-of-world-vote` / `--no-rest-of-world-vote`: Include rest of world televote (default: enabled, introduced in 2023)
+
+### Jury File Format
+
+Create a text file with jury scores in the following format:
+```
+Country Name 123
+Another Country 456
+Switzerland 789
+```
+
+Each line should contain:
+- Country name (can include spaces)
+- Score (integer, separated by space)
+
+### Interactive Process
+
+1. The program displays current jury scores
+2. Enter televoting scores for each country (except the last one)
+3. Use 'b' to go back and correct previous entries
+4. Confirm your final entry
+5. Watch the dramatic pause...
+6. See the calculated final scores and winner announcement!
+
+## How It Works
+
+The system follows Eurovision scoring rules:
+
+1. **Jury Scores**: Pre-calculated professional jury points
+2. **Televoting Scores**: User enters N-1 country scores interactively
+3. **Final Calculation**: The last country's televoting score is automatically calculated based on:
+   - Total available points: (12+10+8+7+6+5+4+3+2+1) × voting countries
+   - Voting countries = participating countries (+ 1 rest of the world if enabled, introduced in 2023)
+   - Minus the sum of all entered televoting scores
+4. **Winner**: Country with highest combined jury + televoting score
+
+## Testing
+
+Run the test suite:
+
+```bash
+uv run pytest tests
+```
+
+The tests use [EurovisionAPI/dataset](https://github.com/EurovisionAPI/dataset.git) and test data from 2016 to 2025 included.
+
+The tests include:
+- Score calculation accuracy
+- File parsing functionality
+- CLI interface testing
+
+## Dependencies
+
+- **[Rich](https://rich.readthedocs.io/)**: Beautiful terminal UI, tables, and animations
+- **[Typer](https://typer.tiangolo.com/)**: Modern CLI framework
+- **[pytest](https://pytest.org/)**: Testing framework
+
+Development dependencies:
+- **basedpyright**: Type checking
+- **ruff**: Linting and formatting
+- **orjson**: Fast JSON parsing for tests
+
+## License
+
+This project is open source under the [MIT License](LICENSE).