How zsq259/plan-over-graph works
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