# yiwenai/autosat architecture

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

- Interactive diagram: https://gitdiagram.com/yiwenai/autosat
- Repository: https://github.com/yiwenai/autosat

## Overview

##### Project Type and Purpose
- AutoSAT is an open-source tool (Multi-Agent Version) for automatically optimizing heuristics in SAT solvers using Large Language Models (LLMs). It orchestrates multiple agents (advisor, coder, evaluator) to generate, execute, and evaluate heuristic functions against SAT instances.

##### High-Level File Structure Analysis
- Top-level:
- Dockerfile, setup.py, requirements.txt – build/deployment support
- main_MultiAgent.py & evaluate.py – CLI entry points for training and testing
- autosat/ – core Python package
- data/ – scripts and templates to generate CNF instances
- examples/ – sample configs, prompts, and solver code
- autosat/ subpackages:
- agent/ – agent base classes and implementations (assistant_agent, executor_agent, common_agent)
- llm_api/ – abstraction over LLM API calls
- execution/ – execution_worker that compiles/runs SAT solvers with generated heuristics
- evaluation/ – evaluate.py for computing PAR-2, #solved, etc.
- trainer/ – orchestrates multi-agent training loops
- utils.py – shared utilities

##### Key Insights from README
- Two main workflows:
a. Training via main_MultiAgent.py with multi-agent loops (iteration_num, batch_size, agent_type, etc.)
b. Evaluation via evaluate.py (runs final heuristics on a test set)
- Data generation scripts live in data/ and create CNF instances for training/evaluation
- Examples folder holds prompts, configs, and baseline solver code (EasySAT variants)

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "CLI Launcher"
        A1["main_MultiAgent.py"]:::controlBlue
        A2["evaluate.py"]:::controlBlue
    end

    subgraph "Configuration Store"
        C1["config.yaml"]:::dataGrey
        C2["eval_config.yaml"]:::dataGrey
    end

    B1["Multi-Agent Orchestrator\n(sat_trainer.py)"]:::controlBlue
    B2["Base Trainer Logic\n(base_trainer.py)"]:::controlBlue

    subgraph "Agents & API"
        subgraph "Agents"
            AG0["BaseAgent\n(base_agent.py)"]:::agentGreen
            AG1["AdvisorAgent\n(assistant_agent.py)"]:::agentGreen
            AG2["CoderAgent\n(common_agent.py)"]:::agentGreen
            AG3["EvaluatorAgent\n(executor_agent.py)"]:::agentGreen
        end
        API["LLM API Interface\n(base_api.py)"]:::agentGreen
    end

    D1["Execution Worker\n(execution_worker.py)"]:::execOrange

    subgraph "Evaluation Engine"
        E1["Evaluation Engine\n(evaluate.py)"]:::execOrange
    end

    DS["Dataset\n(CNF Instances)"]:::dataGrey
    DG["Data Generation Scripts\ndata/"]:::dataGrey
    EX["Sample Solver Code & Prompts\n(examples/EasySAT/)"]:::dataGrey

    RS1["Temp Prompts\n(intermediate JSONs)"]:::dataGrey
    RS2["final_result.json"]:::dataGrey

    LLM["External LLM Provider"]:::dataGrey

    %% Connections
    A1 -->|"loads config"| C1
    A2 -->|"loads config"| C2

    A1 -->|"start training"| B1
    A2 -->|"start evaluation"| E1

    B1 -->|"uses base logic"| B2
    B1 -->|"dispatch prompts"| AG1
    B1 -->|"dispatch prompts"| AG2
    B1 -->|"dispatch prompts"| AG3

    AG1 -->|"calls API with prompt"| API
    AG2 -->|"calls API with prompt"| API
    AG3 -->|"calls API with prompt"| API

    API -->|"returns heuristics"| AG1
    API -->|"returns heuristics"| AG2
    API -->|"returns heuristics"| AG3

    AG2 -->|"heuristic code"| D1
    D1 -->|"runs on"| DS
    D1 -->|"sends raw results"| E1

    E1 -->|"feedback metrics"| B1

    B1 -->|"store intermediates"| RS1
    B1 -->|"store final"| RS2

    A2 -->|"load final results"| RS2
    A2 -->|"run final evaluation"| E1
    E1 -->|"write eval JSON"| RS2

    DG -->|"generate CNFs for"| DS
    EX -.->|"baseline code used by"| D1
    LLM -.->|"alternative backend for"| API

    %% Click Events
    click A1 "https://github.com/yiwenai/autosat/blob/master/main_MultiAgent.py"
    click A2 "https://github.com/yiwenai/autosat/blob/master/evaluate.py"
    click C1 "https://github.com/yiwenai/autosat/blob/master/examples/EasySAT/config.yaml"
    click C2 "https://github.com/yiwenai/autosat/blob/master/examples/EasySAT/eval_config.yaml"
    click B1 "https://github.com/yiwenai/autosat/blob/master/autosat/trainer/sat_trainer.py"
    click B2 "https://github.com/yiwenai/autosat/blob/master/autosat/trainer/base_trainer.py"
    click AG1 "https://github.com/yiwenai/autosat/blob/master/autosat/agent/assistant_agent.py"
    click AG2 "https://github.com/yiwenai/autosat/blob/master/autosat/agent/common_agent.py"
    click AG3 "https://github.com/yiwenai/autosat/blob/master/autosat/agent/executor_agent.py"
    click AG0 "https://github.com/yiwenai/autosat/blob/master/autosat/agent/base_agent.py"
    click API "https://github.com/yiwenai/autosat/blob/master/autosat/llm_api/base_api.py"
    click D1 "https://github.com/yiwenai/autosat/blob/master/autosat/execution/execution_worker.py"
    click E1 "https://github.com/yiwenai/autosat/blob/master/autosat/evaluation/evaluate.py"
    click DG "https://github.com/yiwenai/autosat/tree/master/data/"
    click EX "https://github.com/yiwenai/autosat/tree/master/examples/EasySAT/"

    %% Styles
    classDef controlBlue fill:#cce5ff,stroke:#004085,color:#004085
    classDef agentGreen fill:#d4edda,stroke:#155724,color:#155724
    classDef execOrange fill:#ffe5b4,stroke:#e69500,color:#e69500
    classDef dataGrey fill:#e2e3e5,stroke:#6c757d,color:#6c757d
```
