# zsq259/plan-over-graph architecture

> Architecture diagram of the GitHub repository zsq259/plan-over-graph, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/zsq259/plan-over-graph
- Repository: https://github.com/zsq259/plan-over-graph

## Overview

##### Project type and purpose
- This is a research toolkit for “Plan-over-Graph,” a paradigm that decomposes textual tasks into subtasks, builds an abstract task graph, and generates parallel execution schedules with LLMs. It bundles data-generation scripts, model wrappers, agent modules, evaluation scripts, and plotting utilities to reproduce the experiments in the paper.

##### File structure
- Top-level directories:
- examples/ – sample inputs
- script/ – bash wrappers for data generation, testing, and analysis
- src/ – Python source code, subdivided into:
– agent/ (core pipeline modules, LLM wrappers, environment, subtask abstractions)
– gen_data/ (synthetic graph & task generators)
– analyse/ (metrics calculators and plotters)
– utils/ (logging and helper functions)
- template/ – prompt templates for abstract-task planning and rule extraction
- Configuration and dependency files: requirements.txt, shell scripts under script/analyse and script/gen_data.

##### Key insights from README
- Two-stage pipeline:
1. Synthetic graph/task generation & two-stage training on these graphs
2. Extraction of abstract task graphs from real text, then parallel schedule generation
- Supports both API-based (OpenAI GPT) and open-source LLMs (LLaMA, Qwen).
- Evaluation scripts produce results in result/ and performance plots using matplotlib etc.

##### Main components
a. Data Generation Layer
- script/gen_data/*.sh and src/gen_data/*.py produce synthetic graphs and task datasets
- Output: JSON or structured graph files under data/
b. Agent Pipeline
- Model Wrappers: gpt_wrapper, llama_wrapper, qwen_wrapper (interfaces to LLMs)
- Modules:
- Extractor: parses text into nodes/edges
- Planner: builds abstract task graph representation
- Scheduler: computes parallel execution plan over graph
- Runner: simulates or dispatches subtasks
- Env: tt_env for testbed or simulated execution environment
- Control flow: text input → extractor → graph → planner → schedule → runner
c. Templates
- Prompt templates (template/*.py) feed into wrappers for consistent prompt engineering
d. Evaluation & Analysis
- script/test*.sh invoke agent pipeline on benchmark data
- src/analyse/*.py and script/analyse/*.sh compute token counts, performance, edge correlations, plot bars/curves
e. Utility Library
- src/utils/logger_config.py and utils.py provide logging, config loading, and common helpers

##### Relationships and data flow
- Data Generation → Agent Training & Inference
- Agent sends prompts through Wrappers to LLM APIs / local models
- Responses flow back into Planner & Scheduler
- Runner emits execution logs and subtask timings
- Logs feed into Analysis scripts → plots & statistics

##### Architectural patterns and design principles
- Modular, layer-based pipeline (separate data, model interface, core logic, analysis)
- Dependency inversion: core modules rely on abstract “model” interface, not concrete LLM
- Extensibility: swap in new LLMs by adding wrappers; add new analysis by dropping scripts into src/analyse
- Two-stage training & inference: synthetic graph generation vs. real-task extraction

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Generation Layer
    subgraph "Data Generation Layer"
        DG_sh1["convert_alpaca_form.sh"]:::script
        click DG_sh1 "https://github.com/zsq259/plan-over-graph/blob/main/script/gen_data/convert_alpaca_form.sh"
        DG_sh2["gen_abs_task.sh"]:::script
        click DG_sh2 "https://github.com/zsq259/plan-over-graph/blob/main/script/gen_data/gen_abs_task.sh"
        GD_py1["check_story.py"]:::core
        click GD_py1 "https://github.com/zsq259/plan-over-graph/blob/main/src/gen_data/check_story.py"
        GD_py2["convert_alpaca_form.py"]:::core
        click GD_py2 "https://github.com/zsq259/plan-over-graph/blob/main/src/gen_data/convert_alpaca_form.py"
        GD_py3["extract_rules.py"]:::core
        click GD_py3 "https://github.com/zsq259/plan-over-graph/blob/main/src/gen_data/extract_rules.py"
        GD_py4["gen_abs_task.py"]:::core
        click GD_py4 "https://github.com/zsq259/plan-over-graph/blob/main/src/gen_data/gen_abs_task.py"
        GD_py5["gen_specific_task.py"]:::core
        click GD_py5 "https://github.com/zsq259/plan-over-graph/blob/main/src/gen_data/gen_specific_task.py"
        GD_py6["std.py"]:::core
        click GD_py6 "https://github.com/zsq259/plan-over-graph/blob/main/src/gen_data/std.py"
        DataStore["data/ (JSON Graph)"]:::store
    end

    %% Agent Pipeline
    subgraph "Agent Pipeline"
        Entry["main.py"]:::core
        click Entry "https://github.com/zsq259/plan-over-graph/blob/main/src/agent/main.py"
        subgraph "Model Wrappers"
            W1["gpt_wrapper.py"]:::core
            click W1 "https://github.com/zsq259/plan-over-graph/blob/main/src/agent/model/gpt_wrapper.py"
            W2["llama_wrapper.py"]:::core
            click W2 "https://github.com/zsq259/plan-over-graph/blob/main/src/agent/model/llama_wrapper.py"
            W3["qwen_wrapper.py"]:::core
            click W3 "https://github.com/zsq259/plan-over-graph/blob/main/src/agent/model/qwen_wrapper.py"
            W4["model.py"]:::core
            click W4 "https://github.com/zsq259/plan-over-graph/blob/main/src/agent/model/model.py"
        end
        subgraph "Core Modules"
            M1["extractor.py"]:::core
            click M1 "https://github.com/zsq259/plan-over-graph/blob/main/src/agent/module/extractor.py"
            M2["planner.py"]:::core
            click M2 "https://github.com/zsq259/plan-over-graph/blob/main/src/agent/module/planner.py"
            M3["scheduler.py"]:::core
            click M3 "https://github.com/zsq259/plan-over-graph/blob/main/src/agent/module/scheduler.py"
            M4["runner.py"]:::core
            click M4 "https://github.com/zsq259/plan-over-graph/blob/main/src/agent/module/runner.py"
            M5["subtask.py"]:::core
            click M5 "https://github.com/zsq259/plan-over-graph/blob/main/src/agent/module/subtask.py"
        end
        subgraph "Execution Environment"
            Env["tt_env.py"]:::core
            click Env "https://github.com/zsq259/plan-over-graph/blob/main/src/agent/module/env/tt_env.py"
        end
        subgraph "Templates"
            T1["abstask_plan.py"]:::template
            click T1 "https://github.com/zsq259/plan-over-graph/blob/main/template/abstask_plan.py"
            T2["abstask_plan_coding.py"]:::template
            click T2 "https://github.com/zsq259/plan-over-graph/blob/main/template/abstask_plan_coding.py"
            T3["abstask_plan_ref.py"]:::template
            click T3 "https://github.com/zsq259/plan-over-graph/blob/main/template/abstask_plan_ref.py"
            T4["abstask_plan_ref_cot.py"]:::template
            click T4 "https://github.com/zsq259/plan-over-graph/blob/main/template/abstask_plan_ref_cot.py"
            T5["extract_rules.py"]:::template
            click T5 "https://github.com/zsq259/plan-over-graph/blob/main/template/extract_rules.py"
            T6["specific_task.py"]:::template
            click T6 "https://github.com/zsq259/plan-over-graph/blob/main/template/specific_task.py"
            T7["specific_task_plan.py"]:::template
            click T7 "https://github.com/zsq259/plan-over-graph/blob/main/template/specific_task_plan.py"
        end
        Logs["logs/ (CSV Logs)"]:::store
    end

    %% Evaluation & Analysis
    subgraph "Evaluation & Analysis"
        AS_sh1["edge_results.sh"]:::script
        click AS_sh1 "https://github.com/zsq259/plan-over-graph/blob/main/script/analyse/edge_results.sh"
        AS_sh2["overall_performance.sh"]:::script
        click AS_sh2 "https://github.com/zsq259/plan-over-graph/blob/main/script/analyse/overall_performance.sh"
        AS_sh3["parallel_sequencial.sh"]:::script
        click AS_sh3 "https://github.com/zsq259/plan-over-graph/blob/main/script/analyse/parallel_sequencial.sh"
        AS_sh4["plot_performance.sh"]:::script
        click AS_sh4 "https://github.com/zsq259/plan-over-graph/blob/main/script/analyse/plot_performance.sh"
        AN1["count_tokens.py"]:::core
        click AN1 "https://github.com/zsq259/plan-over-graph/blob/main/src/analyse/count_tokens.py"
        AN2["data_statistics.py"]:::core
        click AN2 "https://github.com/zsq259/plan-over-graph/blob/main/src/analyse/data_statistics.py"
        AN3["edge_corr_slope.py"]:::core
        click AN3 "https://github.com/zsq259/plan-over-graph/blob/main/src/analyse/edge_corr_slope.py"
        AN4["edge_performance.py"]:::core
        click AN4 "https://github.com/zsq259/plan-over-graph/blob/main/src/analyse/edge_performance.py"
        AN5["model_test_summary.py"]:::core
        click AN5 "https://github.com/zsq259/plan-over-graph/blob/main/src/analyse/model_test_summary.py"
        AN6["overall_performance.py"]:::core
        click AN6 "https://github.com/zsq259/plan-over-graph/blob/main/src/analyse/overall_performance.py"
        AN7["parallel_sequencial.py"]:::core
        click AN7 "https://github.com/zsq259/plan-over-graph/blob/main/src/analyse/parallel_sequencial.py"
        AN8["plot_performance.py"]:::core
        click AN8 "https://github.com/zsq259/plan-over-graph/blob/main/src/analyse/plot_performance.py"
        AN9["plot_performance_bar.py"]:::core
        click AN9 "https://github.com/zsq259/plan-over-graph/blob/main/src/analyse/plot_performance_bar.py"
        AN10["query_statistics.py"]:::core
        click AN10 "https://github.com/zsq259/plan-over-graph/blob/main/src/analyse/query_statistics.py"
        Results["results/ & Plots"]:::store
    end

    %% External Services
    API["OpenAI API"]:::external
    HF["Hugging Face Models"]:::external

    %% Data Flows
    DG_sh1 --> DataStore
    DG_sh2 --> DataStore
    GD_py1 --> DataStore
    GD_py2 --> DataStore
    GD_py3 --> DataStore
    GD_py4 --> DataStore
    GD_py5 --> DataStore
    GD_py6 --> DataStore

    DataStore --> Entry
    Entry --> W1
    Entry --> W2
    Entry --> W3
    W1 --> API
    API --> W1
    W2 --> HF
    W3 --> HF
    W4 --> W1
    W4 --> W2
    W4 --> W3

    W1 --> M1
    W2 --> M1
    W3 --> M1
    M1 --> M2
    M2 --> M3
    M3 --> M4
    M4 --> Env
    M4 --> Logs

    Logs --> AS_sh1
    Logs --> AS_sh2
    Logs --> AS_sh3
    Logs --> AS_sh4
    Logs --> AN1
    Logs --> AN2
    Logs --> AN3
    Logs --> AN4
    Logs --> AN5
    Logs --> AN6
    Logs --> AN7
    Logs --> AN8
    Logs --> AN9
    Logs --> AN10

    AS_sh1 --> Results
    AS_sh2 --> Results
    AS_sh3 --> Results
    AS_sh4 --> Results
    AN1 --> Results
    AN2 --> Results
    AN3 --> Results
    AN4 --> Results
    AN5 --> Results
    AN6 --> Results
    AN7 --> Results
    AN8 --> Results
    AN9 --> Results
    AN10 --> Results

    %% Templates connections
    T1 --> W1
    T2 --> W1
    T3 --> W1
    T4 --> W1
    T5 --> W1
    T6 --> W1
    T7 --> W1

    %% Styles
    classDef core fill:#ADD8E6,stroke:#000,color:#000;
    classDef script fill:#FFA500,stroke:#000,color:#000;
    classDef template fill:#FFA500,stroke:#000,color:#000;
    classDef store fill:#90EE90,stroke:#000,color:#000;
    classDef external fill:#DDA0DD,stroke:#000,color:#000;
```
