robofleet

Python SDK for coordinating a robot fleet (factory, warehouse, hotel) with a vision-language model such as Qwen3.8-27B, plus Bambu Lab 3D printer control.

site (zones, chargers, rules) + fleet state (robots, tasks, alerts) [+ camera images]
   -> briefing -> model -> checker -> plan
              \-> rule-based planner (fallback and baseline)

• The model proposes, code verifies. Every plan goes through a checker that drops made-up IDs, tasks that would drain a battery below reserve, and work sent to robots that are charging or in a fault state.
• Always has an answer. If the model is offline or returns garbage, the rule-based plan is used.
• Any model server. Works with a local llama-server, vLLM or OpenRouter, through the OpenAI-compatible API.
• No dependencies for the core. Printer support adds one (paho-mqtt).

Contents

• Requirements
• Install
• Quick start
• Connect a model (Qwen3.8-27B)
• Python API
• Describe your site
• 3D printer
• Command line reference
• Development

Requirements

Full model sizes and setup are in docs/MODEL_SETUP.md.

Install

pip install robofleet                # core
pip install "robofleet[printer]"     # with Bambu Lab printer support

Using a virtual environment is recommended:

python3 -m venv .venv
source .venv/bin/activate            # Windows: .venv\Scripts\activate
pip install "robofleet[printer]"

Latest development version from GitHub:

pip install "robofleet[printer] @ git+https://github.com/Sarthak-code360/vlm_robofleetSDK_qwen3.8_27b.git"

Quick start

No model needed. This runs the rule-based planner on the example warehouse:

git clone https://github.com/Sarthak-code360/vlm_robofleetSDK_qwen3.8_27b.git && cd vlm_robofleetSDK_qwen3.8_27b
pip install -e .
robofleet plan --site examples/warehouse/site.json --fleet examples/warehouse/fleet_state.json --offline

=== Rule-based baseline ===
  ASSIGN  T-901 -> RBT-003   (Nearest available robot (21 m).)
  ASSIGN  T-902 -> RBT-001   (Nearest available robot (0 m).)
  ASSIGN  T-903 -> RBT-002   (Nearest available robot (0 m).)

Then connect a model (next section) and drop --offline.

Connect a model (Qwen3.8-27B)

robofleet reads four environment variables:

Local on a Mac (24 GB+ Apple Silicon). Full guide and troubleshooting: docs/MODEL_SETUP.md.

brew install llama.cpp
python3 -m pip install -U huggingface_hub
hf download unsloth/Qwen3.8-27B-GGUF Qwen3.8-27B-UD-Q3_K_XL.gguf mmproj-F16.gguf --local-dir ~/models/qwen27b
sudo sysctl iogpu.wired_limit_mb=19456        # 24 GB Mac; resets on reboot

llama-server -m ~/models/qwen27b/Qwen3.8-27B-UD-Q3_K_XL.gguf --mmproj ~/models/qwen27b/mmproj-F16.gguf \
  -ngl 99 -c 8192 --flash-attn on --cache-type-k q8_0 --cache-type-v q8_0 --jinja --reasoning off --port 8000

In a second terminal:

export VLM_BASE_URL=http://localhost:8000/v1 VLM_MODEL=qwen VLM_THINKING=off
robofleet model-check "hi"

NVIDIA GPU with vLLM (40 GB+):

vllm serve Qwen/Qwen3.8-27B --quantization fp8 --max-model-len 16384 --port 8000 --api-key <key>
export VLM_BASE_URL=http://<gpu-host>:8000/v1 VLM_MODEL=Qwen/Qwen3.8-27B VLM_API_KEY=<key> VLM_THINKING=off

Hosted (no hardware needed):

export OPENROUTER_API_KEY=sk-or-...

Python API

from robofleet import Coordinator, ModelClient, load_json

site = load_json("examples/warehouse/site.json")
fleet = load_json("examples/warehouse/fleet_state.json")

model = ModelClient(base_url="http://localhost:8000/v1", model="qwen", thinking=False)
# or ModelClient.from_env(), or None for rules only

coordinator = Coordinator(site, model, log_path="logs/decisions.jsonl")
decision = coordinator.plan(fleet, images=["camera.jpg"])

decision.source     # "model" or "rules"
decision.plan       # checked plan: {"assignments": [...], "robot_messages": [...], "summary": "..."}
decision.rejected   # what the checker removed from the model's plan
decision.error      # why the model was not used, if it failed

Robot instructions the model may send: go_to_charger, pause, resume, go_to_zone.

Describe your site

Site file: fixed knowledge. type is free text, such as factory, warehouse or hotel, and the model's instructions use it.

{
  "name": "Demo warehouse",
  "type": "warehouse",
  "zones": {"Zone A3": {"x": 0, "y": 0}, "Loading Zone": {"x": 40, "y": 10}, "Charging Bay": {"x": 0, "y": 15}},
  "chargers": ["Charging Bay"],
  "rules": {"battery_reserve_pct": 20, "charge_threshold_pct": 25, "max_queued_tasks_per_robot": 1}
}

Fleet state: a live snapshot, built from your robots' telemetry before each plan() call.

{
  "robots": [{"id": "RBT-001", "zone": "Zone A3", "battery": 78, "status": "busy", "queued_tasks": []}],
  "pending_tasks": [{"id": "T-901", "type": "transport", "from_zone": "Loading Zone", "to_zone": "Zone A3",
                     "priority": "urgent", "battery_cost": 30}],
  "alerts": [{"source": "RBT-002 camera", "zone": "Zone A3", "text": "Spilled boxes blocking the aisle."}]
}

status is one of idle, busy, charging or fault. Robots that are charging or in fault never get tasks. Complete examples are in examples/warehouse/.

3D printer

The model picks one of your pre-sliced files and starts it on a Bambu Lab printer over the local network, after a person types PRINT. Setup, including LAN mode, the access code and slicing files, is in docs/PRINTER_SETUP.md.

pip install "robofleet[printer]"
cp examples/printer.example.json config/printer.json     # fill in ip, serial, access_code
robofleet printer status
robofleet printer ask "print the cube"

from robofleet import ModelClient, load_json
from robofleet.printers import BambuPrinter, choose_print_file, list_print_files

printer = BambuPrinter.from_config(load_json("config/printer.json")["printer"])
choice, _ = choose_print_file(ModelClient.from_env(), "print the cube", list_print_files("prints"))
print(choice["file"], printer.status()["gcode_state"])

Command line reference

robofleet plan --site FILE --fleet FILE [--image IMG ...] [--offline] [--show-briefing] [--log FILE]
robofleet model-check [MESSAGE]
robofleet printer status                    [--config config/printer.json]
robofleet printer list                      [--prints prints/]
robofleet printer ask REQUEST [--dry-run] [--yes]
robofleet printer job (--request TEXT | --stl FILE | --sliced FILE) [--dry-run] [--yes]

python -m robofleet ... works too. Add --help to any command for details.

Development

git clone https://github.com/Sarthak-code360/vlm_robofleetSDK_qwen3.8_27b.git && cd vlm_robofleetSDK_qwen3.8_27b
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[printer]"
python -m unittest discover -s tests -t .

See CONTRIBUTING.md for guidelines and docs/PUBLISHING.md for how releases reach PyPI.

Security

Never commit config/printer.json, API keys or .env files. They are git-ignored. See SECURITY.md.

License

MIT