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
What is this?SwarmAgent is a conversational agent that turns natural-language requests like 'choreograph this song, make the second section gentler' into validated drone-swarm trajectories, built on the ReAct paradigm and sitting on top of a separately deployed SwarmGPT service.
Is this just a CLI tool, or does it have a chat interface too?It is a Python CLI agent (main.py, interactive or one-shot) that also ships a standalone Vue 3 + FastAPI web chat UI with 3D playback of the generated choreography.
How do I get it running?Start the SwarmGPT API ('cd swarmGPT && pixi run api', port 8000) and Ollama ('ollama serve', port 11434) first, with a 'swarmgpt-qwen' model registered in Ollama, then run main.py for CLI use or 'python3 webui/server.py' for the web UI.
Does the agent itself need extra Python packages installed?The core agent has zero third-party dependencies and runs on pure Python stdlib, but you still need a running SwarmGPT API and an Ollama instance with a registered swarmgpt-qwen model (qwen2.5:7b, 32k context) to actually generate choreography.
What's the biggest catch before I can use it?It's not a standalone tool — you must have the upstream SwarmGPT project deployed and running separately, plus Ollama serving the planner model, before the agent can produce any trajectories.
What is SwarmGPT and why do I need it running separately?SwarmGPT is the upstream service that actually generates and validates swarm trajectories; SwarmAgent is a ReAct-based client that calls its API (port 8000) to turn chat requests into drone choreography.
What does 'Best-of-N sampling' do when I ask it to choreograph a song?The planner generates multiple candidate trajectories (bestofn count, 4 recommended locally), applies safety filtering, scores them, and picks the best one automatically.
Why ship a distilled 1.5B model instead of always calling the cloud teacher?The LoRA adapter (QLoRA, r=8/alpha=16) distilled from Qwen-Max lets choreography planning run on a local 6 GB GPU instead of depending on a paid cloud API, while matching the teacher's behavior from the agent's own logs.
Where does the training data for the distilled model come from?Every ReAct thought/action/observation is logged to logs/session.jsonl, which feeds sfttrain.jsonl and dpopairs.jsonl — a self-generated data flywheel used for the SFT/DPO distillation pipeline.
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