swarm-agent README

The project's README from github.com/lyt2003-yt/swarm-agent. As one markdown file: README.md.

SwarmAgent

中文文档

A conversational drone-swarm choreography agent built on the ReAct paradigm, running on top of a deployed SwarmGPT service. It turns natural-language requests ("choreograph this song, make the second section gentler") into validated swarm trajectories — and ships a 1.5B distilled Qwen model (LoRA adapter) that replaces the cloud teacher for choreography planning.

Zero third-party dependencies for the core agent (pure Python stdlib); no changes to the upstream swarmGPT repo required.

Architecture

User (CLI / Web UI)
   │
   ▼
Reasoning (agent.py) ── LLM planner: swarmgpt-qwen (Ollama, format=json_schema hard constraint)
   │  {"thought","action","args"}      falls back to a deterministic state machine on failure
   ▼
Act (tools.py) ── HTTP calls to the existing SwarmGPT API (127.0.0.1:8000)
   │  list_songs / list_models / generate_choreography /
   │  best_of_n_choreography / refine_choreography / get_playback_summary
   ▼
Observation (observation.py) ── rule-based validator
   │  {pass, score, issues[], suggested_next_action}
   └────────────── feedback to Reasoning ──────────────┘

Repository layout

Path Contents
agent.py / tools.py / observation.py ReAct loop, tool wrappers, rule-based validator
main.py CLI entry point (interactive & one-shot)
webui/ Web chat UI (Vue 3 frontend + FastAPI server)
distill/ Distillation pipeline: teacher data collection, SFT (QLoRA), DPO
distill/ckpt/lora_adapter/ Open-sourced distilled model — LoRA adapter for Qwen/Qwen2.5-1.5B-Instruct
eval/ Evaluation harness, configs, and report

Prerequisites (services you need running)

Service Port Start
SwarmGPT API 8000 cd swarmGPT && pixi run api
Ollama 11434 ollama serve
(optional) Bailian proxy 8355 python3 ../bailian_proxy.py

A swarmgpt-qwen model should be registered in Ollama (qwen2.5:7b + 32k ctx, see the Modelfile in the parent project). The planner backend is configurable — see below.

Usage

cd swarmAgent
python3 main.py              # interactive chat
python3 main.py --once "Generate choreography for Crazyflie Drones Theme (short)"

Example prompts:

After a successful generation, open http://127.0.0.1:8000 for the 3D playback (latest job). The webui/ directory provides a standalone chat + playback web interface (python3 webui/server.py).

Configuration (config.json)

Key Description
planner_model Planner model (Ollama tag)
choreo_provider / choreo_model Choreography backend (ollama / openai via Bailian proxy)
best_of_n Best-of-N sample count (4 recommended locally, 2–4 for cloud)
max_iters Max ReAct iterations (runaway guard)

Distilled model (LoRA adapter)

distill/ckpt/lora_adapter/ contains a QLoRA adapter (r=8, alpha=16) distilled from a cloud teacher (Qwen-Max via Bailian) onto Qwen2.5-1.5B-Instruct, trained on the agent's own session logs (distill/sft_train.jsonl) plus DPO pairs (distill/dpo_pairs.jsonl). It runs on a 6 GB GPU.

import torch
from transformers import AutoModelForCausalLM, AutoTokenizer
from peft import PeftModel

base = AutoModelForCausalLM.from_pretrained(
    "Qwen/Qwen2.5-1.5B-Instruct", torch_dtype=torch.float16, device_map="auto")
model = PeftModel.from_pretrained(base, "distill/ckpt/lora_adapter")
tokenizer = AutoTokenizer.from_pretrained("distill/ckpt/lora_adapter")

To reproduce training (scripts in distill/):

python distill/gen_teacher_data.py    # 1. collect teacher demonstrations
python distill/prepare_sft.py         # 2. build SFT dataset
python distill/train_lora.py          # 3. QLoRA SFT
python distill/collect_dpo_pairs.py   # 4. collect DPO preference pairs
python distill/train_dpo.py           # 5. DPO alignment

Evaluation

eval/ contains the baseline harness (run_eval.py, analyze.py) measuring single-shot success rate, Best-of-N marginal returns, and failure-mode distribution across local and cloud models. See eval/report.md for results.

Logging & data flywheel

logs/session_*.jsonl (gitignored) records every thought/action/observation — the training data source for SFT/DPO distillation.

License & acknowledgements

Built on top of the SwarmGPT project. The distilled adapter is derived from Qwen2.5-1.5B-Instruct — please comply with the Qwen license.

swarm-agent (lyt2003-yt/swarm-agent)

Searching Database…

190 ·GitHub
Swarm-agent
这是什么？SwarmAgent 是一个对话式智能体，能把“给这首歌编舞，让第二段柔和一点”这样的自然语言请求转换成经过验证的无人机集群轨迹；它基于 ReAct 范式构建，运行在单独部署的 SwarmGPT 服务之上。
它只是 CLI 工具，还是也有聊天界面？它是一个 Python CLI 智能体（main.py，支持交互式或一次性运行），还附带一个独立的 Vue 3 + FastAPI 网页聊天界面，可 3D 回放生成的编舞。
怎么让它跑起来？先启动 SwarmGPT API（“cd swarmGPT && pixi run api”，端口 8000）和 Ollama（“ollama serve”，端口 11434），并在 Ollama 中注册“swarmgpt-qwen”模型，然后运行 main.py 使用 CLI，或运行“python3 webui/server.py”使用网页界面。
智能体本身需要额外安装 Python 包吗？核心智能体零第三方依赖，纯 Python 标准库即可运行，但要真正生成编舞，你仍需要一个运行中的 SwarmGPT API 和一个 Ollama 实例（其中注册了 swarmgpt-qwen 模型，即 qwen2.5:7b，32k 上下文）。
在使用之前最大的坑是什么？它不是独立工具——必须先把上游 SwarmGPT 项目单独部署并运行起来，再加上 Ollama 提供规划器模型服务，智能体才能生成任何轨迹。
SwarmGPT 是什么？为什么需要单独运行它？SwarmGPT 是实际生成并验证集群轨迹的上游服务；SwarmAgent 是基于 ReAct 的客户端，调用它的 API（端口 8000）把聊天请求转换成无人机编舞。
我让它为一首歌编舞时，“Best-of-N sampling”起什么作用？规划器生成多个候选轨迹（bestofn 数量，本地推荐 4 个），应用安全过滤，给它们打分，然后自动挑选最好的一个。
为什么附带蒸馏的 1.5B 模型，而不是总是调用云端教师模型？从 Qwen-Max 蒸馏而来的 LoRA 适配器（QLoRA，r=8/alpha=16）让编舞规划可以在本地 6 GB GPU 上运行，不必依赖付费云 API，同时通过智能体自身的日志对齐教师模型的行为。
蒸馏模型的训练数据从哪里来？每一次 ReAct 思考/动作/观察都会记录到 logs/session.jsonl，再供给 sfttrain.jsonl 和 dpopairs.jsonl——一个自生成的数据飞轮，用于 SFT/DPO 蒸馏流水线。
What are similar projects?unsloth, Soup, ruflo, litgpt, airllm, LlamaFactory, strands-decider, self-operating-computer
Which topics is it in?drones, swarm-intelligence, dpo, qlora, lora, robotics, fastapi, agent-framework, autonomous-agents, qwen, evaluation, fine-tuning
Creator
lyt2003-yt
Size
16.8 MB
Stars
190
Updated
CommitAug 21
Age
1mo
Commits · 90 Days