{"id":14181727,"url":"https://github.com/wbbeyourself/MAC-SQL","last_synced_at":"2025-08-07T14:31:02.646Z","repository":{"id":213278300,"uuid":"733015849","full_name":"wbbeyourself/MAC-SQL","owner":"wbbeyourself","description":"MAC-SQL: A Multi-Agent Collaborative Framework for Text-to-SQL","archived":false,"fork":false,"pushed_at":"2024-06-27T07:35:21.000Z","size":356,"stargazers_count":139,"open_issues_count":2,"forks_count":11,"subscribers_count":5,"default_branch":"main","last_synced_at":"2024-06-27T08:51:31.919Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://arxiv.org/abs/2312.11242","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/wbbeyourself.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-12-18T11:24:08.000Z","updated_at":"2024-06-27T02:27:50.000Z","dependencies_parsed_at":"2024-01-07T07:24:40.027Z","dependency_job_id":"8415a61a-d736-4026-bf73-87e630e3e168","html_url":"https://github.com/wbbeyourself/MAC-SQL","commit_stats":null,"previous_names":["wbbeyourself/mac-sql"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wbbeyourself%2FMAC-SQL","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wbbeyourself%2FMAC-SQL/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wbbeyourself%2FMAC-SQL/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wbbeyourself%2FMAC-SQL/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/wbbeyourself","download_url":"https://codeload.github.com/wbbeyourself/MAC-SQL/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":215857678,"owners_count":15940684,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-18T11:04:11.450Z","updated_at":"2025-08-07T14:31:02.587Z","avatar_url":"https://github.com/wbbeyourself.png","language":"Python","funding_links":[],"categories":["💬 Classic Model"],"sub_categories":[],"readme":"## 📖Introduction\n\nThis is the official repository for the paper [\"MAC-SQL: A Multi-Agent Collaborative Framework for Text-to-SQL\"](https://arxiv.org/abs/2312.11242).\n\nIn this paper, we propose a multi-agent collaborative Text-to-SQL framework MAC-SQL, which comprises three agents: the **Selector**, the **Decomposer**, and the **Refiner**.\n\n\u003cimg src=\"./assets/framework.jpg\" align=\"middle\" width=\"95%\"\u003e\n\n\n# 🔥 Updates\n- [**2024.11**] \u003cimg class=\"img-fluid instilogo p-1\" src=\"assets/new.gif\" style=\"height: 1.0em;\" alt=\"New\"\u003eOur work has been accepted by \u003cspan style=\"color: red;\"\u003eCOLING 2025\u003c/span\u003e [conference paper version](https://aclanthology.org/2025.coling-main.36/). Welcome to cite this paper version.\n- [**2024.04**] We have updated the `sql-llama-instruct-v0.5.jsonl` and training scripts in `training_scripts` dir of this project. Please check it out.Download the `sql-llama-data.zip` from [Baidu Dsik](https://pan.baidu.com/s/1yaEBsSN894O7MlBrckciKw?pwd=htwt) or [Google Drive](https://drive.google.com/file/d/1_3s88Op1PCZo50RsHcx5m2Bj_n05PPn4/view?usp=sharing).\nUnzip `sql-llama-data.zip` and get the data dir, which contains sql-llama-instruct-v0.5.jsonl (3375 instances).\n- [**2024.04**] We have updated the [SQL-Llama-v0.5](https://huggingface.co/IceKingBing) model and data.zip (update dev_gold_schema.json in bird and spider) The download links of the updated data are available on [Baidu Disk](https://pan.baidu.com/s/1jU2li3d-enhzswx8VdNYdg?pwd=hfmk) and [Google Drive](https://drive.google.com/file/d/1kkkNJSmJkZKeZyDFUDG7c4mnkxsrr-om/view?usp=sharing).\n- [**2024.02**] We have updated the paper, with updates mainly focusing on experiments and framework details, check it out! [link](https://arxiv.org/abs/2312.11242).\n- [**2023.12**] We have updated the paper, with updates mainly focusing on the title, abstract, introduction, some details, and appendix. In addition, we give some bad case examples on `bad_cases` folder, check it out!\n- [**2023.12**] We released our first version [paper](https://arxiv.org/abs/2312.11242), [code](https://github.com/wbbeyourself/MAC-SQL). Check it out!\n\n\n\n## ⚡Environment\n\n1. Config your local environment.\n\n```bash\nconda create -n macsql python=3.9 -y\nconda activate macsql\npip install -r requirements.txt\npython -c \"import nltk; nltk.download('punkt')\"\n```\n\nNote: we use `openai==0.28.1`, which use `openai.ChatCompletion.create` to call api.\n\n2. Edit openai config at **core/api_config.py**, and set related environment variables of Azure OpenAI API.\n\nCurrently, we use `gpt-4-1106-preview` (128k version) by default, which is 2.5 times less expensive than the `gpt-4 (8k)` on average.\n\n```bash\nexport OPENAI_API_BASE=\"YOUR_OPENAI_API_BASE\"\nexport OPENAI_API_KEY=\"YOUR_OPENAI_API_KEY\"\n```\n\n## 🔧 Data Preparation\n\nIn order to prepare the data more quickly, I have packaged the files including the databases of the BIRD dataset and the Spider dataset into `data.zip` and uploaded them. \nAll files were downloaded on December 19, 2023, ensuring they are the latest version at that moment. \nThe download links are available on [Baidu Disk](https://pan.baidu.com/s/1jU2li3d-enhzswx8VdNYdg?pwd=hfmk) and [Google Drive](https://drive.google.com/file/d/1kkkNJSmJkZKeZyDFUDG7c4mnkxsrr-om/view?usp=sharing)(update on 2024-04-22).\n\nAfter downloading the `data.zip` file, you should delete the existing data folder in the project directory and replace it with the unzipped data folder from `data.zip`.\n\n\n## 🚀 Run\n\nThe run script will first run 5 examples in Spider to check environment.\nYou should open code comments for different usage.\n\n- `run.sh` for Linux/Mac OS\n- `run.bat` for Windows OS\n\nFor SQL execution demo, you can use `app_bird.py` or `app_spider.py` to get the execution result of your SQL query.\n\n```bash\ncd ./scripts\npython app_bird.py\npython app_spider.py\n```\n\nIf occur error `/bin/bash^M: bad interpreter` in Linux, use `sed -i -e 's/\\r$//' run.sh` to solve it.\n\n## 📝Evaluation Dataset\n\nWe evaluate our method on both BIRD dataset and Spider dataset.\n\nEX: Execution Accuracy(%)\n\nVES: Valid Efficiency Score(%)\n\nRefer to our paper for the details.\n\n\n## 🫡Run SQL-Llama\n\nDownload the [SQL-Llama](https://huggingface.co/IceKingBing)(current v0.5 version) and follow the [SQL-Llama-deployment.md](SQL-Llama-deployment.md) to deploy.\n\nUncomment the `MODEL_NAME = 'CodeLlama-7b-hf'` in `core/api_config.py` to set the global model and comment other `MODEL_NAME = xxx` lines.\n\nUncomment the `export OPENAI_API_BASE='http://0.0.0.0:8000/v1'` in `run.sh` to set the local model api base.\n\nThen, run `run.sh` to start your local inference.\n\n\n## 🌟 Project Structure\n\n```txt\n├─data # store datasets and databases\n|  ├─spider\n|  ├─bird\n├─core\n|  ├─agents.py       # define three agents class\n|  ├─api_config.py   # OpenAI API ENV config\n|  ├─chat_manager.py # manage the communication between agents\n|  ├─const.py        # prompt templates and CONST values\n|  ├─llm.py          # api call function and log print\n|  ├─utils.py        # utils function\n├─scripts            # sqlite execution flask demo\n|  ├─app_bird.py\n|  ├─app_spider.py\n|  ├─templates\n├─evaluation # evaluation scripts\n|  ├─evaluation_bird_ex.py\n|  ├─evaluation_bird_ves.py\n|  ├─evaluation_spider.py\n├─bad_cases\n|  ├─badcase_BIRD(dev)_examples.xlsx\n|  └badcase_Spider(dev)_examples.xlsx\n├─evaluation_bird_ex_ves.sh # bird evaluation script\n├─README.md\n├─requirements.txt\n├─run.py # main run script\n├─run.sh # generation and evaluation script\n```\n\n\n## 💬Citation\n\n\nIf you find our work is helpful, please cite as:\n\n```text\n@inproceedings{macsql-2025,\n  title={MAC-SQL: A Multi-Agent Collaborative Framework for Text-to-SQL},\n  author={Wang, Bing and Ren, Changyu and Yang, Jian and Liang, Xinnian and Bai, Jiaqi and Chai, Linzheng and Yan, Zhao and Zhang, Qian-Wen and Yin, Di and Sun, Xing and others},\n  booktitle={Proceedings of the 31st International Conference on Computational Linguistics},\n  pages={540--557},\n  year={2025}\n}\n```\n\n## 👍Contributing\n\n\nWe welcome contributions and suggestions!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwbbeyourself%2FMAC-SQL","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwbbeyourself%2FMAC-SQL","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwbbeyourself%2FMAC-SQL/lists"}