v1.1.1 — Fix duplicate-guess throttle behavior

v1.1.1 — Bug Fix Release

Bug Fixes

• Fixed an issue where guesses that previously returned a WAIT (throttle) response were incorrectly treated as permanent duplicates after the cooldown TTL expired.
  Now, WAIT responses are ignored during duplicate detection once the throttle window has passed, allowing the guess to be properly evaluated.
  Thanks @tanzimfh for the great catch and contribution!

• Improved cache semantics so only guesses with real evaluations (TOO_LOW, TOO_HIGH, INCORRECT, CORRECT, COMPLETED) are treated as duplicates.

Notes

• No breaking changes.
• This is a pure bug-fix release and is a drop-in upgrade from v1.1.0.
• If you encountered the “blocked due to repeated guess” issue, updating to v1.1.1 resolves it.

elf v1.1.0 — User-Agent improvements and input helper fixes

elf v1.1.0

Small improvements and refinements to make elf more reliable and user friendly during Advent of Code.

Improvements

User-Agent Handling (thanks @NotTheEconomist 🎅)

• Cleaned up the internal User-Agent validation logic.
• Sanitizes newline and whitespace characters before validation.
• Improves warnings and error paths when AOC_USER_AGENT is missing or invalid.
• Ensures elf always sends a correctly formatted, compliant User-Agent header.

File Input Helpers

• Improved read_input():

  • Uses is_file() instead of exists() for safer checks.
  • Clearer error messages that include the full path.
  • More robust behavior when reading local input files.

Documentation

• Updated README to show how to save puzzle inputs to files.
• Added a new section describing AOC_USER_AGENT and how to configure it.

Happy coding, and good luck on this year's puzzles! 🎄

elf v1.0.0 First Public Release

🎄 v1.0.0 First Public Release

What is elf

elf is a fast and modern CLI and Python helper library for Advent of Code. It provides a clean interface for fetching inputs, submitting answers, viewing leaderboards, and tracking your progress. It includes:

• Cached puzzle input fetching
• Safe answer submission with guardrails
• Private leaderboard support with table, JSON, or Pydantic output
• Star status and AoC++ badge display
• Guess history viewer
• Quick browser opening for puzzles or inputs
• Both a CLI (elf) and a Python API (import elf)

Why this release

Advent of Code begins December 1. After years of refining a personal helper tool for my own solving, I am releasing elf publicly so that others can benefit. It is built for casual solvers, automation workflows, leaderboard racers, and those who want a clean and modern Python interface to AoC.

Highlights

• Input fetching with automatic caching
• Answer submission guardrails for safety and cooldown awareness
• Private leaderboard access in table, JSON, or model form
• Star calendar and status views
• Guess history tracking
• Cross platform support with minimal dependencies

Installation

Using uv (recommended):

uv tool install elf

Using pip:

pip install elf

Requirements

• Python 3.11 or newer
• AOC_SESSION environment variable set for most commands

Quick Start

# Fetch input for today or first available
elf input

# Submit an answer  
elf answer 2025 1 1 12345

# View a private leaderboard  
elf leaderboard 2025 1234567 --view-key <VIEW_KEY>

# Show your star status  
elf status

# Open today's puzzle in the browser  
elf open

Thanks

Special thanks to Eric Wastl for creating Advent of Code and inspiring a global tradition each December.

Thank you to @solos for donating the elf package name on PyPI.