Upload README.md with huggingface_hub

README.md

@@ -0,0 +1,213 @@
+# Explore–Execute Chain (E2C)
+
+This repository provides the implementation of our paper:
+**Explore–Execute Chain: Towards an Efficient Structured Reasoning Paradigm**
+*Kaisen Yang, Lixuan He, Rushi Shah, Kaicheng Yang, Qinwei Ma, Dianbo Liu, Alex Lamb*
+
+> *Under review at ICLR 2026*
+
+---
+
+## 📖 Overview
+
+Large Language Models (LLMs) often intertwine high-level planning with low-level execution, limiting both efficiency and interpretability.
+The **Explore–Execute Chain (E2C)** framework addresses this challenge by **decoupling reasoning into two distinct stages**:
+
+1. **Exploration** — Generate lightweight reasoning sketches (plans).
+2. **Execution** — Select one or a few promising plans and execute them faithfully.
+
+This separation offers multiple benefits:
+
+* **Efficiency** — Short explorations reduce computation while preserving reasoning coverage.
+* **Interpretability** — Exploration traces are explicit and auditable.
+* **Adaptability** — Exploration can be domain-adapted with minimal supervision.
+
+---
+
+## 📝 Current Progress
+
+**Released**
+
+* ✅ Public release of **datasets** and **pretrained models**
+
+**Ongoing**
+
+* 🔄 Exploring more diverse **exploration strategies** and more reliable **execution mechanisms**
+* 🔄 Cleaning and organizing **experimental code** for broader reproducibility
+
+Stay tuned for further updates as we expand features and experiments.
+
+---
+
+## 🚀 Key Features
+
+* **Two-stage training pipeline**:
+
+  * **E2C-SFT** — Supervised fine-tuning on synthetic exploration–execution pairs.
+  * **E2C-RL** — Reinforcement learning with token-level weighting tailored to exploration.
+
+* **Efficient domain adaptation (EF-SFT)** — Adapt models with exploration-only data at minimal cost.
+
+* **Test-time scaling** — Sample multiple explorations and aggregate them via clustering or LLM-based fusion.
+
+* **Extensive benchmarks**:
+
+  * **Mathematical reasoning**: AIME’24/25, MATH500, Olympiad, Minerva.
+  * **Medical reasoning**: MedQA, MedMCQA, MMLU medical subsets.
+
+---
+
+## 📂 Repository Structure
+
+```
+.
+├── data/           # Dataset preparation scripts and instructions
+├── e2c/            # Core E2C framework
+│   ├── sft/        # Supervised fine-tuning (E2C-SFT, EF-SFT)
+│   ├── rl/         # Reinforcement learning (E2C-RL, GRPO baseline)
+│   └── inference/  # Test-time scaling and evaluation
+├── prompts/        # Prompt templates
+├── scripts/        # Training / evaluation entrypoints
+└── README.md
+```
+
+---
+
+## ⚙️ Setup
+
+### Requirements
+
+See `e2c/verl/README.md` for details.
+
+* Python 3.9+
+* PyTorch ≥ 2.0
+* HuggingFace Transformers
+* sentence-transformers
+* Additional packages in `requirements.txt`
+
+Install dependencies via:
+
+```bash
+pip install -r requirements.txt
+```
+
+---
+
+## 📥 Model Download
+
+Pretrained and fine-tuned E2C models are available on Hugging Face.
+
+```python
+from transformers import AutoModelForCausalLM, AutoTokenizer
+
+model_name = "your-org/e2c-model"
+tokenizer = AutoTokenizer.from_pretrained(model_name)
+model = AutoModelForCausalLM.from_pretrained(model_name)
+```
+
+Or via CLI:
+
+```bash
+huggingface-cli download your-org/e2c-model
+```
+
+Replace `your-org/e2c-model` with the actual repository name.
+
+---
+
+## 🏋️ Training
+
+### Stage 1: Supervised Fine-Tuning (E2C-SFT)
+
+```bash
+bash e2c/sft/train_sft.sh
+```
+
+### Stage 2: Reinforcement Learning (E2C-RL)
+
+```bash
+bash e2c/rl/train_rl.sh
+```
+
+### Efficient Adaptation (EF-SFT)
+
+```bash
+bash e2c/sft/train_ef_sft.sh
+```
+
+---
+
+## 🔍 Evaluation
+
+Run evaluation and test-time scaling:
+
+```bash
+bash e2c/inference/evaluate.sh
+```
+
+Supported strategies include:
+
+* **E2C-Select (Self LM-Judge)**
+* **E2C-Select (Semantic Cluster)**
+* **E2C-SC (Self-Consistency)**
+* **E2C-RP (Random Plan)**
+
+---
+
+## 📊 Results
+
+E2C consistently improves over GRPO baselines with reduced cost.
+
+* On **AIME’24**, Qwen3-4B + E2C-(SFT+RL) yields **+8.7% accuracy gain** over GRPO.
+* On **medical reasoning**, EF-SFT adapts with only **3.5% of training tokens**, surpassing standard SFT.
+
+See the paper for detailed results and ablations.
+
+---
+
+## 🙏 Credits
+
+This work builds upon the **VERL** framework, which has been instrumental for training and experimentation.
+We thank the authors for releasing such a powerful and flexible platform.
+
+---
+
+## 📌 Notes
+
+* This repository is **work in progress**; some datasets and scripts are placeholders.
+* Full reproduction may require additional setup.
+* Hyperparameters and prompt templates are provided in the paper appendices.
+* We are still improving the training process and codebase for better usability.
+
+---
+
+## 📜 Citation
+
+If you use this work, please cite:
+
+**BibTeX**
+
+```bibtex
+@inproceedings{yang2026explore,
+  title={Explore--Execute Chain: Towards an Efficient Structured Reasoning Paradigm},
+  author={Yang, Kaisen and He, Lixuan and Shah, Rushi and Yang, Kaicheng and Ma, Qinwei and Liu, Dianbo and Lamb, Alex},
+  booktitle={International Conference on Learning Representations (ICLR)},
+  year={2026},
+  note={under review}
+}
+```
+
+**APA**
+
+> Yang, K., He, L., Shah, R., Yang, K., Ma, Q., Liu, D., & Lamb, A. (2026). *Explore–Execute Chain: Towards an Efficient Structured Reasoning Paradigm*. International Conference on Learning Representations (ICLR). (Under review)
+
+**MLA**
+
+> Yang, Kaisen, et al. "Explore–Execute Chain: Towards an Efficient Structured Reasoning Paradigm." *International Conference on Learning Representations (ICLR)*, 2026. Under review.
+
+---
+
+## 🧾 License
+
+This project is licensed under the **MIT License**.
+See the [LICENSE](LICENSE) file for details.