# codium-ai/alphacodium architecture

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

- Interactive diagram: https://gitdiagram.com/codium-ai/alphacodium
- Repository: https://github.com/codium-ai/alphacodium

## Overview

##### Project type and purpose
- This is a command-line, ML-driven code-generation pipeline (AlphaCodium) for competitive-programming problems.
- Purpose: orchestrate a multi-stage “flow engineering” process: read problem, generate candidate solutions via LLMs, run tests, self-reflect, fix code, choose best solution, and evaluate end-to-end.

##### File structure
- Top-level entrypoints (scripts invoked via `python -m`):
- solve_problem
- solve_dataset
- evaluate_dataset
- solve_my_problem
- `alpha_codium/`: core package
- `settings/`: config loader + `.toml` files
- `llm/` & `litellm/`: abstraction over LLM calls (OpenAI API, proxy, token handling)
- `gen/`: “generation” pipeline, with stages under `gen/stages/` (initial code gen, tests, fix, reflection, choose best, etc.)
- `code_contests/`: dataset provider, data prep, eval metrics, local execution runner
- `log/`: logging utilities
- `tests/`: unit tests for core eval and local execution
- `docs/`: MkDocs site for project documentation
- Ops files: `Dockerfile`, GitHub Actions CI, `requirements.txt`

##### README insights
- Multi-stage flow: solve → generate tests → run tests → fix code → reflect → choose best → repeat
- Configuration-driven: stages and model choice controlled via TOML
- DataProvider reads CodeContests dataset from filesystem
- Evaluation module computes pass@k and other metrics

- CLI Layer (entrypoint scripts)
- Config Loader (`settings/config_loader.py`)
- Generation Engine (`gen/` package + pipeline orchestrator)
- LLM Service Adapter (`llm/` and `litellm/`)
- Code Execution & Test Runner (`code_contests/eval/local_exec.py`)
- Dataset & Storage (CodeContests JSON files on disk)
- Evaluation & Metrics (`code_contests/eval/`, `evaluate_dataset` CLI)
- Logging & Artifacts (log files, outputs)
- External Services: OpenAI API

1. CLI → Config Loader → Generation Engine
2. Generation Engine → LLM Adapter → OpenAI API → LLM Adapter → Generation Engine
3. Generation Engine → Test Runner → Execution Sandbox → Results → Generation Engine
4. Generation Engine → Logging & File System (candidate code, logs)
5. CLI (evaluate_dataset) → Evaluation Module → Metrics → Logging/File System

c. Architectural patterns & principles:
- Pipeline pattern: each generation stage is a pluggable module (`gen/stages/*.py`)
- Configuration-driven: stages, prompts, model names defined in TOML
- Abstraction layer for LLM calls (`ai_invoker`, `ai_handler`)
- Separation of concerns: data prep, code generation, evaluation, logging

d. Key technologies/frameworks:
- Python 3.8+, TOML config, Pydantic-style structured output prompts
- OpenAI API (via `litellm.proxy`)
- Docker for reproducible environment
- GitHub Actions for CI
- MkDocs for documentation

##### Diagramting elements
- Labels: clear component names (e.g., “LLM Adapter”)
- Blue rectangles for internal modules
- Orange parallelograms for CLI scripts

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI Layer
    subgraph "CLI Layer"
        SP["solve_problem"]:::cli
        SDs["solve_dataset"]:::cli
        ED["evaluate_dataset"]:::cli
        SM["solve_my_problem"]:::cli
    end

    %% Config Loader
    CL["Config Loader"]:::internal
    CT["configuration.toml"]:::storage

    %% Generation Engine
    subgraph "Generation Engine" 
        GE["Pipeline Orchestrator"]:::internal
        subgraph "Core Modules"
            CC["coding_competitor.py"]:::internal
            DS["dataset_solver.py"]:::internal
            Gens["generators.py"]:::internal
            Utils["utils.py"]:::internal
        end
        subgraph "Stages (iterative)"
            Stage1["initial_code_generation"]:::internal
            Stage2["run_tests"]:::internal
            Stage3["self_reflection"]:::internal
            Stage4["fix_code"]:::internal
            Stage5["choose_best_solution"]:::internal
        end
    end

    %% LLM Service Adapter
    subgraph "LLM Adapter"
        Invoker["ai_invoker.py"]:::internal
        Handler["ai_handler.py"]:::internal
        Tokener["token_handler.py"]:::internal
        ProxyTypes["_types.py"]:::internal
    end

    %% Code Execution & Test Runner
    subgraph "Execution & Test Runner"
        LocalExec["local_exec.py"]:::internal
        TestRunners["code_test_runners.py"]:::internal
        Tracer["tracer.py"]:::internal
    end

    %% Dataset & Storage
    subgraph "Dataset & Storage"
        Provider["provider.py"]:::internal
        Prep["prepare_and_clean_dataset.py"]:::internal
        YamlJson["yaml_vs_json.py"]:::internal
        DataFiles["Dataset Files"]:::storage
    end

    %% Evaluation & Metrics
    subgraph "Evaluation & Metrics"
        Metrics["code_contests_metric.py"]:::internal
        PassK["pass_at_k_evaluator.py"]:::internal
    end

    %% Logging & Artifacts
    LogsPkg["log/ utilities"]:::internal
    LogFile["example.log"]:::storage

    %% External Services
    OA["OpenAI API"]:::external

    %% Connections
    SP -->|invoke| CL
    SDs -->|invoke| CL
    SM -->|invoke| CL
    CL -->|"loads TOML"| GE
    CT -->|configures| GE

    GE -->|calls| Invoker
    Invoker -->|requests| OA
    OA -->|response| Handler
    Handler -->|returns| GE
    Tokener -->|auth| Invoker
    ProxyTypes -->|defines| Invoker

    GE -->|dispatch tests| LocalExec
    LocalExec -->|runs| TestRunners
    TestRunners -->|executes| Tracer
    Tracer -->|results| GE

    GE -->|reads/writes| LogsPkg
    GE -->|writes| LogFile

    Provider -->|supplies| GE
    Prep -->|prepares| DataFiles
    YamlJson -->|converts| DataFiles
    DataFiles -->|loaded by| Provider

    ED -->|invoke evaluation| Metrics
    Metrics -->|compute| PassK
    PassK -->|log metrics| LogFile

    %% Iterative loop
    Stage1 --> Stage2
    Stage2 --> Stage3
    Stage3 --> Stage4
    Stage4 --> Stage2
    Stage4 --> Stage5
    class Stage1,Stage2,Stage3,Stage4,Stage5 dashed

    %% Click Events
    click SP "https://github.com/codium-ai/alphacodium/blob/main/alpha_codium/solve_problem.py"
    click SDs "https://github.com/codium-ai/alphacodium/blob/main/alpha_codium/solve_dataset.py"
    click ED "https://github.com/codium-ai/alphacodium/blob/main/alpha_codium/evaluate_dataset.py"
    click SM "https://github.com/codium-ai/alphacodium/blob/main/alpha_codium/solve_my_problem.py"
    click CL "https://github.com/codium-ai/alphacodium/blob/main/alpha_codium/settings/config_loader.py"
    click CT "https://github.com/codium-ai/alphacodium/blob/main/alpha_codium/settings/configuration.toml"
    click CC "https://github.com/codium-ai/alphacodium/blob/main/alpha_codium/gen/coding_competitor.py"
    click DS "https://github.com/codium-ai/alphacodium/blob/main/alpha_codium/gen/dataset_solver.py"
    click Gens "https://github.com/codium-ai/alphacodium/blob/main/alpha_codium/gen/generators.py"
    click Utils "https://github.com/codium-ai/alphacodium/blob/main/alpha_codium/gen/utils.py"
    click Stage1 "https://github.com/codium-ai/alphacodium/blob/main/alpha_codium/gen/stages/run_initial_code_generation.py"
    click Stage2 "https://github.com/codium-ai/alphacodium/blob/main/alpha_codium/gen/stages/run_tests.py"
    click Stage3 "https://github.com/codium-ai/alphacodium/blob/main/alpha_codium/gen/stages/run_self_reflect.py"
    click Stage4 "https://github.com/codium-ai/alphacodium/blob/main/alpha_codium/gen/stages/run_fix_code_from_tests_failure.py"
    click Stage5 "https://github.com/codium-ai/alphacodium/blob/main/alpha_codium/gen/stages/run_choose_best_solution.py"
    click Invoker "https://github.com/codium-ai/alphacodium/blob/main/alpha_codium/llm/ai_invoker.py"
    click Handler "https://github.com/codium-ai/alphacodium/blob/main/alpha_codium/llm/ai_handler.py"
    click Tokener "https://github.com/codium-ai/alphacodium/blob/main/alpha_codium/llm/token_handler.py"
    click ProxyTypes "https://github.com/codium-ai/alphacodium/blob/main/alpha_codium/litellm/proxy/_types.py"
    click LocalExec "https://github.com/codium-ai/alphacodium/blob/main/alpha_codium/code_contests/eval/local_exec.py"
    click TestRunners "https://github.com/codium-ai/alphacodium/blob/main/alpha_codium/code_contests/eval/code_test_runners.py"
    click Tracer "https://github.com/codium-ai/alphacodium/blob/main/alpha_codium/code_contests/eval/tracer.py"
    click Provider "https://github.com/codium-ai/alphacodium/blob/main/alpha_codium/code_contests/data/provider.py"
    click Prep "https://github.com/codium-ai/alphacodium/blob/main/alpha_codium/code_contests/data/prepare_and_clean_dataset.py"
    click YamlJson "https://github.com/codium-ai/alphacodium/blob/main/alpha_codium/code_contests/data/yaml_vs_json.py"
    click Metrics "https://github.com/codium-ai/alphacodium/blob/main/alpha_codium/code_contests/eval/code_contests_metric.py"
    click PassK "https://github.com/codium-ai/alphacodium/blob/main/alpha_codium/code_contests/eval/pass_at_k_evaluator.py"
    click LogsPkg "https://github.com/codium-ai/alphacodium/tree/main/alpha_codium/log/"
    click LogFile "https://github.com/codium-ai/alphacodium/blob/main/alpha_codium/gen/example.log"

    %% Styles
    classDef cli fill:#f9d5b5,stroke:#e67e22,color:#2c3e50,stroke-width:2px
    classDef internal fill:#aed6f1,stroke:#2980b9,color:#1b2631,stroke-width:2px
    classDef storage fill:#abebc6,stroke:#27ae60,color:#1e3d22,stroke-width:2px
    classDef external fill:#e8daef,stroke:#8e44ad,color:#4a235a,stroke-width:2px
```
