🖨️ Bambu Studio AI

Request → Collect Info → Search/Generate → Analyze(11pt) → [Colorize] → Preview(chat) → Open BS → [User Slices in BS] → Confirm → Print → Monitor

Pre-check: If config.json does not exist → run First-Time Setup before any operation.

At the start of each turn: If handling a print request, re-read the Pipeline Checklist and Compliance Rules. Ensure you are not skipping any MUST step.

---

⛔ COMPLIANCE RULES — Follow Strictly

Before every action, verify you are not violating these rules:

Rule	Meaning
MUST	Non-negotiable. Skip = failure.
NEVER

Forbidden. Doing it = failure. |
| WAIT | Do not proceed until user responds. |

NEVER Do These

• - ❌ NEVER skip Information Collection — Always ask: model source (search/generate), dimensions (if generating), single/multi-color, material
• ❌ NEVER generate without dimensions — MUST ask "How big? e.g., 80mm tall" before INLINECODE1
• ❌ NEVER skip analyze — Every model MUST go through INLINECODE2
• ❌ NEVER skip preview — MUST send preview image/GIF to chat before opening Bambu Studio. User must SEE the model.
• ❌ NEVER skip Bambu Studio confirmation — MUST open in BS, tell user to inspect, WAIT for explicit "looks good" / "print it"
• ❌ NEVER auto-print — No bambu.py print without user confirmation. AI models have errors.
• ❌ NEVER skip model source choice — MUST ask user: search vs generate vs not sure (default: search first)

MUST Do These (in order)

1. 1. Collect info → Ask model source, dimensions (if generate), colors, material
2. Get model → Search or generate per user choice
3. Analyze → analyze.py --orient --repair on every model
4. Preview to chat → preview.py --views turntable → send image/GIF to user
5. Open Bambu Studio → open -a "BambuStudio" model.3mf (or model.stl/obj)
6. User slices in Bambu Studio → Tell user to slice, inspect, and confirm
7. Wait for confirmation → Do not proceed until user says ready
8. Print → Only after confirmation

Note: slice.py (CLI slicing via OrcaSlicer) is optional — only use if user explicitly requests CLI slicing. The default is for users to slice in Bambu Studio themselves, where they can adjust supports, infill, and other settings visually.

Pipeline Checklist (verify before claiming done)

[ ] Info collected (source, dimensions, colors, material)
[ ] Model obtained (search/generate/download)
[ ] analyze.py --orient --repair run
[ ] Preview image/GIF sent to chat
[ ] Opened in Bambu Studio
[ ] User sliced + inspected in Bambu Studio
[ ] User confirmed "looks good" / "print it"
[ ] Print started (only after confirmation)

---

Quick Reference

I want to...	Command
Printer status	INLINECODE8
Print progress

python3 scripts/bambu.py progress | | Printer hardware info | python3 scripts/bambu.py info | | Start a print | python3 scripts/bambu.py print <file> --confirmed | | Pause / Resume / Cancel | python3 scripts/bambu.py pause\|resume\|cancel | | Speed mode | python3 scripts/bambu.py speed silent\|standard\|sport\|ludicrous | | Light on/off | python3 scripts/bambu.py light on\|off | | AMS filament info | python3 scripts/bambu.py ams | | Camera snapshot | python3 scripts/bambu.py snapshot | | Send G-code | python3 scripts/bambu.py gcode "G28" | | Notification | python3 scripts/bambu.py notify --message "done" | | Generate 3D (text) | python3 scripts/generate.py text "desc" --wait --height 80 (--raw skips auto-enhancement; --height sets target mm, default auto 80mm) | | Generate 3D (image) | python3 scripts/generate.py image photo.jpg --wait --height 80 (auto: validate, bg-remove, prompt enhance; --no-bg-remove / --raw to skip) | | Download model | python3 scripts/generate.py download <task_id> --height 80 | | Analyze model | python3 scripts/analyze.py model.stl --height 80 --orient --repair --material PLA (always exports _scaled file when --height is used) | | Keep main only (remove fragments) | python3 scripts/analyze.py model.stl --repair --keep-main | | Multi-color | python3 scripts/colorize model.glb --height 80 --max_colors 8 -o out.obj (tunable: --min-pct, --no-merge, --island-size, --smooth, --bambu-map) | | Slice (optional CLI) | python3 scripts/slice.py model.stl --orient --arrange --quality fine | | Slice (specific setup, optional) | python3 scripts/slice.py model.stl --printer A1 --filament "Bambu PETG Basic" | | List slicer profiles | python3 scripts/slice.py --list-profiles | | Preview (quick) | python3 scripts/preview.py model.stl (--height 80 to verify dimensions) | | Preview (HQ Blender) | python3 scripts/preview.py model.stl --hq | | Search models | python3 scripts/search.py "phone stand" --limit 5 | | Monitor print | python3 scripts/monitor.py --auto-pause | | Check deps | python3 scripts/doctor.py | | Parametric box | python3 scripts/parametric.py box 30 20 10 -o box.stl | | Parametric cylinder | python3 scripts/parametric.py cylinder --radius 5 --height 20 -o cyl.stl | | Parametric bracket | python3 scripts/parametric.py bracket --width 30 --height 40 --thickness 3 --hole-diameter 3.2 -o bracket.stl | | Parametric plate with holes | python3 scripts/parametric.py plate-with-holes --width 60 --depth 40 --holes 4 --hole-diameter 3.2 --hole-spacing 25 -o plate.stl | | Parametric enclosure | python3 scripts/parametric.py enclosure --width 60 --depth 40 --height 30 --wall 2 --lid -o case.stl | | Parametric CSG (complex) | python3 scripts/parametric.py csg spec.json -o assembly.stl |

All scripts support --help. generate.py auto-enhances prompts and limits size to printer build volume.

---

Overall Flow

CODEBLOCK1

---

Step 1: Information Collection

Gate: Before ANY search/generate/download, you MUST complete this step.

Collect before proceeding:

Model requirements:

• - What to print (object description)
• Target dimensions — MUST ask before generating ("How big? e.g., 80mm tall")
• Style / appearance (optional)

Print parameters:

• - Single-color or multi-color (AMS)
• Material (default: PLA)
• Quality: draft / standard / fine / extra (optional)
• Purpose: functional or decorative (optional, affects walls + infill)

Model source — ask user:

"Do you want me to:

1. 1. 🔎 Search online — existing models, usually higher quality
2. 🎨 AI generate — custom model from scratch
3. 🤷 Not sure — I'll search first, generate if nothing fits"

Default: search first. Common objects (phone stand, hook, vase) almost always exist online.

Decision flow: User says "search" / "generate" / "not sure" → If "not sure" → search first → if no good results → offer generate.

Auto-routing (agent determines path based on description):

Signal in user's description	Route to	Examples
Specific dimensions / tolerances / fit	Parametric (Workflow F)	"M3 screw hole", "inner diameter 40mm", "press fit"
Standard interfaces / mounting

Parametric (Workflow F) | "USB-C cutout", "GoPro mount", "VESA mount" |
| Functional part keywords | Parametric (Workflow F) | "bracket", "hinge", "hook", "clip", "gear", "mount", "enclosure", "stand" |
| Characters / figurines / organic | AI Generate (Workflow B/C) | "pikachu", "dragon", "bust", "sculpture" |
| Decorative / artistic | AI Generate (Workflow B/C) | "vase", "lamp shade", "desk ornament" |
| Photo reference | Image-to-3D (Workflow E) | user sends image file or URL |

When the description clearly matches functional/precision signals, skip the source question and route directly to Workflow F. If ambiguous (e.g., "phone stand" — could be searched or parametric), default to search first.

---

Step 2: Model Source (Decision Point 1)

Gate: Before this step, you MUST have asked user: "Search, generate, or not sure?" Default: search first.

Workflow A — Internet Search (preferred)

1. 1. search.py "query" --limit 5 → MakerWorld, Printables, Thingiverse, Thangs
2. Present results with name, source, URL
3. User selects → download → validate format (STL/OBJ/3MF)
4. → Model Processing

If no good results → offer AI generate.

Workflow B — AI Generate (single-color)

Checkpoint before generate: Did you ask for dimensions? If not, ask now.

1. 1. First-time disclaimer (once): "AI models depend on provider + prompt. NOT production-ready — always review in Bambu Studio."
2. Confirm dimensions — MUST have before INLINECODE54
3. INLINECODE55 → auto-enhances, auto-scales to exact target
4. INLINECODE56 → send GIF to chat (verifies dimensions)
5. → Model Processing

Workflow C — AI Generate (multi-color)

Checkpoint before generate: Did you ask for dimensions? If not, ask now.
Do NOT ask user to specify colors upfront — AI textures determine the colors. Colorize will auto-detect them.

1. 1. Same disclaimer as B
2. Confirm dimensions only — "What size do you want?" is the only required question

- Colors are auto-detected from AI texture, NOT user-specified - If user volunteers color preferences (e.g., "only 3 colors"), note for colorize params

1. 3. generate.py text "prompt" --wait --height <mm> → textured GLB (scaled to target height)
2. INLINECODE58 → vertex-color OBJ + colormap.txt
3. INLINECODE59
4. Send ONE consolidated report (MUST include all of the following in a single message):

Multi-color report template:
> ## 🎨 [Model Name] Multi-Color Preview
>
> 📷 [attach _preview.png AND turntable.gif]
>
> | # | Color | Hex | % | Suggested Filament | ΔE |
> |---|-------|-----|---|--------------------|----|
> | 1 | yellow | #FFD700 | 58% | PLA Basic Yellow | 3.2 |
> | 2 | brown | #8B4513 | 22% | PLA Basic Brown | 5.1 |
> | ... | | | | | |
>
> N colors detected, AMS compatible. Ready to proceed?
> - Want fewer colors → I'll re-run with --max_colors N
> - Want to adjust → tell me what to change
> - Looks good → I'll open in Bambu Studio

1. 7. WAIT for user response. If user requests changes → re-run colorize → show updated report
2. When user approves → Model Processing

⚠️ BS import may fail to detect vertex colors — see Step 4 for import procedure.

Colorize tuning (only if user requests adjustments):

Parameter	Default	Effect
INLINECODE61	8	Maximum colors (hard limit ≤8 for AMS)
INLINECODE62

0.1 | Min family % threshold (0=keep all, 5=aggressive filter) |
| --no-merge | off | Disable family group exclusion (all 12 families independent) |
| --island-size N | 1000 | Remove isolated patches < N pixels (0=disabled) |
| --smooth N | 5 | Majority vote boundary passes (0=raw, higher=smoother) |
| --bambu-map | on | Output colormap.txt with suggested Bambu filaments (CIELAB match) |

Workflow D — User-Provided File

1. 1. Validate format (STL/OBJ/3MF/GLB), convert if needed
2. → Model Processing

Workflow E — Image to 3D

Trigger: User provides a photo, image file, or image URL to generate a 3D model from.

Checkpoint: Did you ask for dimensions? If not, ask now. Do NOT ask for colors — they come from the image.

1. 1. Same disclaimer as B
2. Confirm dimensions only
3. Save image to workspace (if from chat) or note the file path/URL
4. INLINECODE67 (auto: validate, remove background, enhance prompt)

- To skip background removal: add --no-bg-remove - To skip prompt enhancement: add --raw

1. 5. Auto-detect single vs multi-color:

- If downloaded GLB has texture → run colorize (same as Workflow C steps 4-6, send consolidated multi-color report) - If no texture → single-color path (same as Workflow B steps 4-5)

1. 6. Preview + report to user → WAIT for approval
2. When user approves → Model Processing

Tips for best results:

• - Clean product photos on plain/white background work best
• Single object, centered, well-lit
• Multiple angles of the same object are NOT supported (single image only)
• If background removal hurts the result, re-run with INLINECODE70

Workflow F — Parametric (functional parts)

Trigger: User requests a part with precise dimensions, standard interfaces (screw holes, mounts), or functional keywords (bracket, hinge, enclosure). See auto-routing table in Step 1.

Checkpoint: MUST have exact dimensions in mm. Do NOT accept vague sizes like "about 80mm" — ask for precise values.

1. 1. Collect exact dimensions — width, height, depth, wall thickness, hole sizes, spacing
2. Identify standard interfaces: screw size (M3? M4?), mounting pattern, clearance vs press fit
3. Choose the right parametric.py command:

- Simple shapes → box, cylinder, sphere, extrude - L-brackets → bracket --width W --height H --thickness T --hole-diameter D - Mounting plates → plate-with-holes --width W --depth D --holes N --hole-diameter D --hole-spacing S - Enclosures → enclosure --width W --depth D --height H --wall T [--lid] - Complex assemblies → write a JSON spec, use csg spec.json

1. 4. INLINECODE80
2. INLINECODE81 → send GIF to chat
3. Report dimensions, volume, triangle count (printed by parametric.py)
4. WAIT for user approval — user may request dimension adjustments
5. If adjustments needed → modify command/spec, regenerate, re-preview
6. When user approves → Model Processing

Advantages over AI generation:

• - Exact dimensions (to 0.01mm precision)
• Guaranteed watertight mesh (no repair needed)
• Instant generation (no API call, no waiting)
• Free (no API credits consumed)
• Reproducible (same params = same output)

Limitations:

• - Geometric shapes only — no organic/artistic forms
• Single-color output (STL) — no vertex colors or textures

Reference: See references/manifold-examples.md for tolerance tables, CSG JSON patterns, and design rules.

---

Step 3: Model Processing

Gate: Before this step, you MUST have a model file (from search, generate, or user).

All models MUST go through this. No exceptions. NEVER skip analyze or preview.

Analysis (11-point check):

analyze.py model.stl --orient --repair --material PLA --purpose functional

Checks: dimensional tolerance, wall thickness, load direction, overhangs (>45°), print orientation, floating parts, layer height, infill rate, wall count, top layers, material compatibility. Also: watertight, manifold, build volume fit.

Auto-repair: Fix normals, fill holes, remove degenerate faces.

Auto-orient: Optimal stability, auto unit detection (meters→mm).

Report to user (MANDATORY):

• - Printability score (X/10)
• Warnings and issues
• Repairs performed
• Recommended settings (layer height, infill, walls, temps, supports)

Example: "Score 8/10. Repaired 58K non-manifold edges. Walls: 1.5mm ✅ Overhangs: 3.2% ✅ Recommended: 0.20mm layers, 20% infill, PLA 210°C."

Preview rendering (MANDATORY — NEVER skip):

preview.py model.stl --views turntable -o model_preview.gif

• - Single-color: renders STL/3MF with default blue material
• Multi-color: renders colorize'd OBJ with vertex colors
• MUST send the preview image/GIF to the chat — user cannot proceed without seeing it
• If turntable too slow, use --views perspective for a single image
• Checkpoint: Have you attached the preview to your message? If not, do it before opening BS

Optional CLI Slice (only if user explicitly requests):

slice.py model.stl --orient --arrange --quality standard

Auto-detects printer + nozzle. Quality: draft(0.24) / standard(0.20) / fine(0.12) / extra(0.08). Output: .3mf with G-code.

---

Step 4: User Confirmation

⛔ MANDATORY — NEVER SKIP

Gate: Before this step, you MUST have: (1) sent preview to chat.

1. 1. Open in Bambu Studio: open -a "BambuStudio" model.3mf (or .stl/.obj)
2. Multi-color OBJ — special import procedure (BS import is unstable):

- Always open via File → New Project → Import, NOT "Import to current plate" - After import: check color count in right panel — if BS shows 1 color instead of N: 1. Close BS completely, reopen, then import again 2. Or drag-and-drop the OBJ file into an empty BS window - If BS still refuses to recognize vertex colors → flag as BS import compatibility issue; do NOT re-run colorize

1. 3. Tell user to inspect and slice:

> "I've opened the model in Bambu Studio. Please: > - Check: does it look correct? Missing or deformed parts? > - Check: floating/disconnected pieces? > - Check: correct size? (check dimensions in bottom bar) > - For multi-color: verify the right panel shows the correct number of colors > - Slice in Bambu Studio (Ctrl+R / Cmd+R) and review: estimated time, filament usage, supports. > Let me know when ready!"

1. 4. WAIT for explicit confirmation.

⛔ NEVER auto-print. AI models frequently have errors analysis can't fully catch.

1. 5. Ask print method:

- Direct automatic printing → Workflow E (Developer Mode only, not recommended) - Manual in Bambu Studio → Workflow F

---

Step 5: Print Execution (Decision Point 2)

Workflow E — Auto Print (Developer Mode only, not recommended)

⚠️ Requires Developer Mode ON. Bambu Studio and Bambu Handy will disconnect.

1. 1. INLINECODE85
2. Confirm: "Print started!"
3. → Monitoring

Workflow F — Manual Print

• - Model already open in Bambu Studio
• User adjusts settings and prints manually from BS/Handy

Print detection — two methods:

1. 1. Active listen (after model handoff): When agent opens a model in BS (Workflow B/C/D), immediately start a background MQTT listener (30 min window). If printer state changes to RUNNING → notify user and offer monitoring.

- Implementation: background exec running paho-mqtt subscribe loop, poll every 30s for state change - Auto-stop after 30 min if no print detected - On detection: "🖨️ I see you started printing [filename]! Want me to monitor with live updates and snapshots?"

1. 2. Heartbeat fallback: During regular heartbeats, check printer MQTT status. If RUNNING and not already monitoring → notify user.

• - If user accepts → Start Monitoring (Step 6)

---

Step 6: Print Monitoring

Trigger: Auto print (Workflow E), manual print (Workflow F), or user request. Requires LAN mode.

⚠️ Always ask: "Want me to monitor? Auto-pause on serious issues?"

Monitoring method: Direct MQTT subscription via paho-mqtt (NOT bambulabs_api — it has SSL issues).
Connect to {printer_ip}:8883, subscribe to device/{serial}/report, parse print messages.

Camera snapshots are MANDATORY during monitoring:

• - Capture via RTSP: bambu.py snapshot (ffmpeg → rtsps://bblp:{code}@{ip}:322/streaming/live/1)
• Send snapshot with EVERY progress update to user
• Include snapshot in anomaly alerts

Default monitoring schedule (milestone-based, ~5 messages per print):

Event	Trigger	Action
Print start	State → RUNNING	Notify + 📸 snapshot
25% progress

mc_percent ≥ 25 | Status + 📸 snapshot |
| 50% progress | mc_percent ≥ 50 | Status + 📸 snapshot |
| 75% progress | mc_percent ≥ 75 | Status + 📸 snapshot |
| Print complete | State → FINISH/IDLE | Completion + 📸 final snapshot |
| Anomaly | Any time | Immediate alert + 📸 snapshot + auto-pause (if enabled) |

User can adjust frequency. Track reported milestones to avoid duplicates.

Anomaly detection:

Anomaly	Severity	Action
Progress stall >10min	Warning	Alert user + snapshot
Temperature anomaly

Critical | Alert + snapshot + auto-pause |
| Print failure/error | Critical | Alert + snapshot + auto-pause |
| Unexpected pause | Warning | Alert user + snapshot |
| Bed detachment | Critical | Auto-pause + alert + snapshot |
| Spaghetti | Critical | Auto-pause + alert + snapshot |

Status report format (send to user):

🖨️ Print Update — {filename}
📊 Progress: {percent}% | Layer {current}/{total}
⏱️ Remaining: {time}
🔥 Nozzle: {temp}°C | 🛏️ Bed: {temp}°C
📸 [attached snapshot]

---

First-Time Setup

Triggered when config.json doesn't exist. Conversational:

1. 1. Printer model — A1 Mini, A1, P1S, P2S, X1C, X1E, H2C, H2S, H2D
2. Connection — LAN (recommended: IP + serial + access code) or Cloud (email + password, limited)
3. Print mode — MUST explain clearly to user:

- Option A: Recommended (safe) — Agent generates model → opens in Bambu Studio → user slices, reviews, and prints manually. No special printer settings needed. - Option B: Full auto-print — Agent controls printer directly (start/stop/monitor via MQTT). Requires: - ⚠️ Developer Mode ON (printer touchscreen → Settings → LAN Only Mode → ON → Developer Mode → ON) - ⚠️ Bambu Studio and Bambu Handy will completely disconnect (no cloud, no remote monitoring) - ⚠️ Only LAN access (same network only) - Agent still ALWAYS shows preview before printing (never auto-prints without user confirmation) - Save choice as print_mode: "manual" or print_mode: "auto" in config.json

1. 4. 3D generation (optional) — Meshy, Tripo, Printpal, 3D AI Studio + API key
2. Notifications — macOS system notifications (automatic). Agent handles chat notifications via its own messaging tools.
3. Save — config.json + .secrets.json (chmod 600, git-ignored)
4. Verify (ask permission) — test connection, camera, AMS
5. Summary

---

Environment & Dependencies

Required: python3, pip3 (macOS recommended; core scripts work cross-platform)

pip3 install bambulabs-api bambu-lab-cloud-api requests trimesh numpy Pillow ddgs pygltflib cryptography paho-mqtt scipy

Optional (macOS): ffmpeg (camera), Bambu Studio (model preview + slicing), Blender 4.0+ (multi-color + HQ preview), OrcaSlicer (CLI slicing)

Env vars (override config.json): BAMBU_MODE, BAMBU_MODEL, BAMBU_EMAIL, BAMBU_IP, BAMBU_SERIAL, INLINECODE104

Secrets (.secrets.json, chmod 600): password, access_code, 3d_api_key. All user-provided, never shipped.

---

Common Agent Mistakes (self-check)

Mistake	Correct behavior
Skipping "search vs generate" question	MUST ask user first. Default: search.
Generating without dimensions

MUST ask "How big? e.g., 80mm tall" |
| Running generate.py then immediately opening BS | MUST run analyze.py and preview.py in between |
| Saying "I've prepared the model" without sending image | MUST attach preview GIF/image to the message |
| Opening Bambu Studio without user seeing preview | User must see preview in chat BEFORE you open BS |
| Proceeding to print without "looks good" | MUST wait for explicit user confirmation |
| Skipping analyze "because it's from search" | ALL models need analyze — search results can have issues too |
| Re-generating when model has 68 fragments | First check preview — AI meshes often report many "bodies" but look fine. Only use --keep-main if model is visually fragmented |

---

Common Issues

Problem	Fix
SSL handshake error (LAN)	Normal (self-signed certs). Handled automatically.
API method not found

pip3 install --upgrade bambulabs-api (v2.6.6+) |
| Can't connect (LAN) | LAN Mode ON + correct IP + same network |
| Cloud verification code | Wait for email, enter once. Token cached 90 days. |
| Camera timeout | Wake printer (tap screen), check IP. |
| AI model has holes/floating parts | Expected. Always run analyze.py --repair. |
| Tripo/ Meshy reports 68+ "bodies" | Usually harmless (non-manifold topology, not actual fragments). Check preview first — only use --keep-main if model is visually broken |
| BS imports multi-color OBJ as single color | Close BS → reopen → File > New Project > Import OBJ (not "Import to plate"). If still single-color after retry, this is a BS-side compatibility issue — do NOT re-run colorize |

---

Known Limitations

Feature	Status
Single-color pipeline	✅ Stable
Multi-color (colorize)

⚠️ Colorize pipeline stable; BS vertex-color OBJ import occasionally fails to detect colors — use File → New Project → Import, NOT "Import to plate" |
| CLI slicing | ✅ OrcaSlicer backend (BS CLI SEGFAULT in v2.5.0) |
| End-to-end auto-print | ✅ Works with Developer Mode ON (X.509 signed MQTT + FTP upload) |
| Parametric modeling | ✅ manifold3d — geometric/functional parts only, no organic forms. Single-color STL output. |

---

Reference Documents

• - references/model-specs.md — All 9 printer specifications
• INLINECODE114 — Parametric modeling API, tolerance tables, CSG patterns
• INLINECODE115 — Bambu Lab 43-color palette (reference only, colorize v4 uses texture-native colors)
• INLINECODE116 — MQTT protocol
• INLINECODE117 — Cloud API
• INLINECODE118 — Provider API endpoints
• INLINECODE119 — Prompt engineering for 3D

License

MIT · GitHub: https://github.com/heyixuan2/bambu-studio-ai