How lyang36/imo25 works
Project Type and Purpose
• This is a CLI-based open-source tool (a master-worker system) for solving IMO problems in parallel using Google’s Gemini API.
• It comprises two main executable components:
• agent.py: one AI “worker” that reads a problem, calls the Gemini API, and logs its reasoning and results
• run_parallel.py: the “master” orchestrator that launches multiple agent workers concurrently, gathers their logs, and reports summary statistics
File Structure Analysis
• Top-level:
• code/ — contains the core Python scripts (agent.py, run_parallel.py)
• problems/ — text files for each IMO problem input
• run_logs/ — directories of per-agent log files produced by run_parallel.py
• README.md, IMO25.pdf — documentation
• No web frontend, no database; this is purely a batch/CLI compute workflow.
• run_parallel.py likely uses multiprocessing or concurrent.futures to implement a master–worker pattern.
Key Insights from README
• Master–worker (parallel agents) pattern
• Agents call external Google Gemini API via HTTP (requests)
• Inputs: problem text files; Outputs: console logs or per-agent log files
• Environment config via .env or env var (GOOGLE_API_KEY)
Components
a. Main Components
1. CLI Interface
• User invokes either agent.py or run_parallel.py with arguments
2. Master Orchestrator (run_parallel.py)
• Parses arguments (num-agents, timeout, log dir, prompts)
• Spawns worker processes (agents)
• Monitors timeouts and collects success/failure statuses
• Emits final summary
3. Worker Agent (agent.py)
• Reads a problem file from problems/
• Constructs prompts and calls Gemini API over HTTPS
• Parses API response, searches for “Found a correct solution…”
• Emits detailed reasoning and result to console or log file
4. External Service
• Google Gemini API (model endpoint)
5. File System
• problems/ input store
• run_logs/ output store
• .env or env vars for API key
b. Relationships and Data Flow
• CLI → Master Orchestrator: pass arguments
• Master → Worker Agents: dispatch tasks (problem.txt, prompts, timeout)
• Worker Agent → Gemini API: send HTTP request, receive solution text
• Worker Agent → Logs Folder: write per-agent log
• Master Orchestrator → Aggregated Summary: reads logs or in-memory statuses
c. Architectural Patterns and Principles
• Master-Worker concurrency for parallelism
• Single responsibility: agent.py handles one problem; run_parallel.py handles orchestration
• Externalized configuration (API key) via environment
• File-based I/O for inputs and logs
d. Key Technologies and Libraries
• Python ≥3.7
• requests (HTTP client for Gemini API)
• multiprocessing or concurrent.futures (parallelism)
• dotenv or os.environ for API key
• Standard library logging or print statements