Metadata-Version: 2.4
Name: modelco
Version: 1.1.0
Summary: LLM collaboration
Author-email: Shangbin Feng <shangbin@cs.washington.edu>
License-Expression: MIT
Project-URL: Homepage, https://github.com/BunsenFeng/model_collaboration
Project-URL: Issues, https://github.com/BunsenFeng/model_collaboration/issues
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: accelerate==1.14.0
Requires-Dist: aiohttp==3.12.14
Requires-Dist: aiosignal==1.4.0
Requires-Dist: attrs==25.3.0
Requires-Dist: certifi==2025.6.15
Requires-Dist: charset-normalizer==3.4.2
Requires-Dist: datasets==5.0.1
Requires-Dist: dill==0.3.8
Requires-Dist: filelock==3.18.0
Requires-Dist: frozenlist==1.7.0
Requires-Dist: fsspec==2025.3.0
Requires-Dist: huggingface-hub==1.27.0
Requires-Dist: idna==3.10
Requires-Dist: jinja2==3.1.6
Requires-Dist: markupsafe==3.0.2
Requires-Dist: mergekit==0.1.4
Requires-Dist: multidict==6.6.3
Requires-Dist: multiprocess==0.70.16
Requires-Dist: nevergrad
Requires-Dist: numpy==2.2.6
Requires-Dist: openai==1.93.2
Requires-Dist: packaging==25.0
Requires-Dist: pandas==2.3.1
Requires-Dist: pillow==11.2.1
Requires-Dist: protobuf==6.31.1
Requires-Dist: psutil==7.0.0
Requires-Dist: pyarrow==25.0.1
Requires-Dist: python-dateutil==2.9.0.post0
Requires-Dist: pytz==2025.2
Requires-Dist: pyyaml==6.0.2
Requires-Dist: rdkit==2026.3.5
Requires-Dist: regex==2026.5.9
Requires-Dist: requests==2.32.4
Requires-Dist: safetensors==0.8.0
Requires-Dist: scipy==1.15.3
Requires-Dist: six==1.17.0
Requires-Dist: sympy==1.14.0
Requires-Dist: tenacity==9.1.2
Requires-Dist: tokenizers==0.22.2
Requires-Dist: torch==2.7.1
Requires-Dist: torch-geometric==2.7.0
Requires-Dist: torchaudio==2.7.1
Requires-Dist: torchvision==0.22.1
Requires-Dist: tqdm==4.67.1
Requires-Dist: transformers==5.15.0
Requires-Dist: triton==3.3.1
Requires-Dist: trl==1.10.0
Requires-Dist: typing-extensions==4.14.0
Requires-Dist: typing-inspection==0.4.1
Requires-Dist: urllib3==2.5.0
Requires-Dist: wcwidth==0.2.13
Requires-Dist: xxhash==3.5.0
Requires-Dist: yarl==1.20.1
Requires-Dist: wandb==0.27.2
Dynamic: license-file

<div align="center">
  <img src="docs/MoCo.png" alt="MoCo Logo" width="200">
</div>

## MoCo: A One-Stop Shop for Model Collaboration Research

`MoCo` is a toolkit for **Mo**del **Co**llaboration research, where multiple language models collaborate and complement each other for compositional AI systems.

Technical report: [paper](https://arxiv.org/abs/2601.21257)

## Quick Start

### Environment Setup

We use [uv](https://github.com/astral-sh/uv) for package management.

```
uv venv --python 3.10 moco
source moco/bin/activate
uv pip install -r requirements.txt
```

The `nvidia-*-cu12` entries in `requirements.txt` are bundled CUDA wheels; skip them if your system already has CUDA drivers installed, or install `torch` via the PyTorch index instead (`uv pip install torch==2.7.1 --index-url https://download.pytorch.org/whl/cu126`).

<details>
<summary><b>Optional: NemotronH / Mamba model support</b> (click to expand)</summary>

If you plan to use NemotronH models, also install `causal-conv1d` and `mamba-ssm`:

```
uv pip install --no-build-isolation --no-deps git+https://github.com/Dao-AILab/causal-conv1d.git
uv pip install --no-build-isolation --no-deps git+https://github.com/state-spaces/mamba.git
```

If this crashes at runtime with `no kernel image is available for execution on the device` on GPUs like RTX 3090/A40/A10 or L40/L40S/RTX 4090, see `docs/user_readme.md` for why and how to fix it.

</details>

### Running Your First Collaboration

If you don't have 3 GPUs, go to `model_collaboration/test_config.json` and set `"gpu_ids": [0]`, `[0,1]`, or whatever you have; if your GPU is nice, increase `batch_size`.

```
python -m model_collaboration.main -c model_collaboration/test_config.json
```

You will see the outputs and evaluation results in the `model_collaboration/logs/` folder.

## Supported Methods
`MoCo` currently supports the following model collaboration algorithms, across [API-level, text-level, logit-level, and weight-level collaboration](https://arxiv.org/abs/2502.04506). We provide a sample config for each method in `examples/` and please check out `docs/user_readme.md` for more details about writing configs and the different collaboration methods implemented.

| **Method** | **Core Idea** | **Code** | **Sample Config** | **Doc** |
|------------|---------------|----------|-------------------|---------|
| API: Nudging | one model guides the decoding of another | [link](model_collaboration/method/api_nudging.py) | [link](examples/api_nudging.json) | [link](docs/user_readme.md#api-level-nudging) |
| API: Prompt Routing | prompt an LM to decide which model to use based on model descriptions | [link](model_collaboration/method/api_prompt_routing.py) | [link](examples/api_prompt_routing.json) | [link](docs/user_readme.md#api-level-prompt-routing) |
| API: Switch Generation | multiple LMs take turns to generate parts of the response | [link](model_collaboration/method/api_switch_generation.py) | [link](examples/api_switch_generation.json) | [link](docs/user_readme.md#api-level-switch-generation) |
| API: Trained Router | train an LM to route based on the dev set | [link](model_collaboration/method/api_trained_router.py) | [link](examples/api_trained_router.json) | [link](docs/user_readme.md#api-level-trained-router) |
| API: Graph Routing | train a graph neural network for routing | [link](model_collaboration/method/api_graph_routing.py) | [link](examples/api_graph_routing.json) | [link](docs/user_readme.md#api-level-graph-routing) |
| API: Cascade | use multiple models in a cascade to improve efficiency | [link](model_collaboration/method/api_cascade.py) | [link](examples/api_cascade.json) | [link](docs/user_readme.md#api-level-cascade) |
| API: Mentor Collab | a mentor model guides a smaller student model for generation | [link](model_collaboration/method/api_mentor_collab.py) | [link](examples/api_mentor_collab.json) | [link](docs/user_readme.md#api-level-mentorcollab) |
| API: Co-LLM | train LMs to defer to another model when uncertain | [link](model_collaboration/method/api_collm.py) | [link](examples/api_collm.json) | [link](docs/user_readme.md#api-level-collm) |
| Text: Multiagent Refine | multiple LMs refine each other's answers iteratively | [link](model_collaboration/method/text_multiagent_refine.py) | [link](examples/text_multiagent_refine.json) | [link](docs/user_readme.md#text-level-multiagent-refine) |
| Text: Mixture of Agents | all LMs propose candidates; dev-best LM aggregates into a final answer | [link](model_collaboration/method/text_moa.py) | [link](examples/text_moa.json) | [link](docs/user_readme.md#text-level-mixture-of-agents-moa) |
| Text: Multiagent Feedback | multiple LMs provide feedback to each other's answers | [link](model_collaboration/method/text_multiagent_feedback.py) | [link](examples/text_multiagent_feedback.json) | [link](docs/user_readme.md#text-level-multiagent-feedback) |
| Text: Knowledge Card | models generate knowledge paragraphs to assist each other | [link](model_collaboration/method/text_knowledge_card.py) | [link](examples/text_knowledge_card.json) | [link](docs/user_readme.md#text-level-knowledge-card) |
| Text: LLM Blender | use ranker and fuser LMs to combine multiple answers | [link](model_collaboration/method/text_llm_blender.py) | [link](examples/text_llm_blender.json) | [link](docs/user_readme.md#text-level-llm-blender) |
| Text: Heterogeneous Swarms | optimize a graph of multiple LLMs for collaboration | [link](model_collaboration/method/text_heterogeneous_swarms.py) | [link](examples/text_heterogeneous_swarms.json) | [link](docs/user_readme.md#text-level-heterogeneous-swarms) |
| Text: Majority Vote | majority vote | [link](model_collaboration/method/text_majority_vote.py) | [link](examples/text_majority_vote.json) | [link](docs/user_readme.md#text-level-majority-vote) |
| Text: Structured Interaction | execute a structured interaction protocol among LLMs | [link](model_collaboration/method/text_structure.py) | [link](examples/text_structure.json) | [link](docs/user_readme.md#text-level-structured-interaction) |
| Text: Multiagent Finetuning | multiple LLMs critique, debate, and refine via finetuning | [link](model_collaboration/method/text_multiagent_finetuning.py) | [link](examples/text_multiagent_finetuning.json) | [link](docs/user_readme.md#text-level-multiagent-finetuning) |
| Text: BBMAS | blackboard-based collaboration among LLMs | [link](model_collaboration/method/text_bbmas.py) | [link](examples/text_bbmas.json) | [link](docs/user_readme.md#text-level-blackboard-multi-agent-system-bbmas) |
| Text: Sparta Alignment | models compete and combat for collective alignment | [link](model_collaboration/method/text_sparta.py) | [link](examples/text_sparta.json) | [link](docs/user_readme.md#text-level-sparta) |
| Text: Stackelberg Alignment | extension of Sparta with adversarial instruction selection | [link](model_collaboration/method/text_sparta_stackelberg.py) | [link](examples/text_sparta_stackelberg.json) | [link](docs/user_readme.md#text-level-stackelberg) |
| Text: SLM-Mux  | Orchestraing small models | [link](model_collaboration/method/text_slm_mux.py) | [link](examples/text_slm_mux.json) | [link](docs/user_readme.md#text-level-slm-mux) |
| Text: AggLM | RL to train a solution aggregation model | [link](model_collaboration/method/text_agglm.py) | [link](examples/text_agglm.json) | [link](docs/user_readme.md#text-level-agglm) |
| Logit: Logit Fusion | merge the next-token logits from multiple models | [link](model_collaboration/method/logit_logit_fusion.py) | [link](examples/logit_logit_fusion.json) | [link](docs/user_readme.md#logit-level-logit-fusion) |
| Logit: Logit Contrastive | contrast the logits from best/worst models | [link](model_collaboration/method/logit_logit_contrastive.py) | [link](examples/logit_logit_contrastive.json) | [link](docs/user_readme.md#logit-level-logit-contrastive) |
| Weight: Greedy Soup | iteratively consider adding each model's weights from best to worst | [link](model_collaboration/method/weight_greedy_soup.py) | [link](examples/weight_greedy_soup.json) | [link](docs/user_readme.md#weight-level-greedy-soup) |
| Weight: Dare Ties | the dare-ties model merging algorithm | [link](model_collaboration/method/weight_dare_ties.py) | [link](examples/weight_dare_ties.json) | [link](docs/user_readme.md#weight-level-dare-ties) |
| Weight: Model Swarms | particle swarm optimization for models to search in the weight space | [link](model_collaboration/method/weight_model_swarms.py) | [link](examples/weight_model_swarms.json) | [link](docs/user_readme.md#weight-level-model-swarms) |
| Weight: LoraHub | gradient-free optimization of lora combinations | [link](model_collaboration/method/weight_lorahub.py) | [link](examples/weight_lorahub.json) | [link](docs/user_readme.md#weight-level-lorahub) |
| Weight: ExPO | model weight extrapolation | [link](model_collaboration/method/weight_expo.py) | [link](examples/weight_expo.json) | [link](docs/user_readme.md#weight-level-expo-model-extrapolation) |

Please note that MoCo does not aim to be a reproducibility study: we adapt the core ideas behind related papers and employ what works flexibly.

## Supported Data
`MoCo` comes with a lot of evaluation datasets built-in, and you are free to bring your own datasets, or even just generate responses only and take evaluation elsewhere. Essentially, change the `task` and `task_type` in the config to use diverse datasets. Check out [link](docs/eval_readme.md) for more details.

## Contributing to MoCo
We welcome contributions to `MoCo`!

If you are interested in contributing new model collaboration methods, check out [link](docs/developer_readme.md).

If you are interested in contributing new datasets, check out [link](docs/eval_readme.md).

If you have any suggestions, please open an issue.

## MoCo-supported projects

Scaling participation in modular AI systems: diverse participants contribute small specialized models that collaborate together, outperforming monolithic LLMs. [link](https://arxiv.org/abs/2606.07812)

Safety of model collaboration systems: what if one of the models is malicious? [link](https://arxiv.org/abs/2602.05176)

The single-multi evolution loop: multiple LMs collaborate, distill the collaborative system back into each individual model, and repeat for multi-LLM self-evolution. [link](https://arxiv.org/abs/2602.05182)

## Citation
If `MoCo` is helpful for you, please consider citing:

```
@inproceedings{feng2026one,
  title={When one llm drools, multi-llm collaboration rules},
  author={Feng, Shangbin and Ding, Wenxuan and Liu, Alisa and Wang, Zifeng and Shi, Weijia and Wang, Yike and Shen, Shannon Zejiang and Han, Xiaochuang and Lang, Hunter and Lee, Chen-Yu and others},
  booktitle={Proceedings of the 64th Annual Meeting of the Association for Computational Linguistics (Volume 1: Long Papers)},
  pages={17048--17063},
  year={2026}
}

@article{feng2026moco,
  title={MoCo: A One-Stop Shop for Model Collaboration Research},
  author={Feng, Shangbin and Bai, Yuyang and Yang, Ziyuan and Wang, Yike and Tan, Zhaoxuan and Yan, Jiajie and Lei, Zhenyu and Ding, Wenxuan and Shi, Weijia and Wang, Haojin and others},
  journal={arXiv preprint arXiv:2601.21257},
  year={2026}
}
```

Also, please cite the related papers for the methods you employed, as listed in `docs/user_readme.md`.

Have a nice day.
