# lyang36/imo25 architecture

> Architecture diagram of the GitHub repository lyang36/imo25, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/lyang36/imo25
- Repository: https://github.com/lyang36/imo25

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Internal Components
    subgraph "Internal Components"
        direction TB
        CLI["CLI Interface"]:::internal
        RunParallel["run_parallel.py\n(Master Orchestrator)"]:::internal
        Agent["agent.py\n(Worker Agent)"]:::internal
        Summary["Summary Report"]:::internal
    end

    %% External Service
    subgraph "External Service"
        direction TB
        Gemini["Google Gemini API"]:::external
    end

    %% File System
    subgraph "File System"
        direction TB
        Problems["problems/"]:::fs
        RunLogs["run_logs/"]:::fs
        Env[".env / Env Vars"]:::fs
    end

    %% Documentation
    subgraph "Documentation"
        direction TB
        README["README.md"]:::fs
        PDF["IMO25.pdf"]:::fs
    end

    %% Connections
    CLI -->|"invoke with args"| RunParallel
    RunParallel -->|"spawn N× processes"| Agent
    RunParallel -->|"read problem files"| Problems
    RunParallel -->|"use API key"| Env
    Agent -->|"HTTP request/response"| Gemini
    Agent -->|"write log"| RunLogs
    Agent -->|"read problem"| Problems
    RunParallel -->|"collect statuses"| Summary
    Summary -->|"report to"| CLI

    %% Click Events
    click Agent "https://github.com/lyang36/imo25/blob/main/code/agent.py"
    click RunParallel "https://github.com/lyang36/imo25/blob/main/code/run_parallel.py"
    click Problems "https://github.com/lyang36/imo25/tree/main/problems/"
    click RunLogs "https://github.com/lyang36/imo25/tree/main/run_logs/"
    click README "https://github.com/lyang36/imo25/blob/main/README.md"
    click PDF "https://github.com/lyang36/imo25/blob/main/IMO25.pdf"

    %% Styles
    classDef internal fill:#D6EAF8,stroke:#1B4F72,color:#1B2631
    classDef external fill:#ABEBC6,stroke:#145A32,color:#0B5345
    classDef fs fill:#F9E79F,stroke:#B9770E,color:#784212
```
