🖨️ 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:

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 generate.py
• ❌ NEVER skip analyze — Every model MUST go through analyze.py --orient --repair
• ❌ 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. 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

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

Overall Flow

User Request
    │
    ▼
Information Collection
    │
    ▼
Decision 1: Model Source
    ├─ A: Internet Search (preferred default)
    ├─ B: AI Generate (single-color)
    ├─ C: AI Generate (multi-color)
    ├─ D: User-provided file
    ├─ E: Image to 3D
    └─ F: Parametric (functional parts — manifold3d)
    │
    ▼
Model Processing (analyze → repair → orient → [colorize])
    │
    ▼
Report Results to User
    │
    ▼
⛔ Open in Bambu Studio → User Inspects
    │
    ▼
User Confirms ("looks good" / "print it")
    │
    ▼
Decision 2: Print Method
    ├─ E: Auto Print (Developer Mode only, not recommended)
    └─ F: Manual Print (user handles in Bambu Studio)
    │
    ▼
Print Monitoring (both workflows, or on user request)

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. 🔎 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):

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. 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. First-time disclaimer (once): "AI models depend on provider + prompt. NOT production-ready — always review in Bambu Studio."
2. Confirm dimensions — MUST have before generate.py text
3. generate.py text "prompt" --wait --height <mm> → auto-enhances, auto-scales to exact target
4. preview.py model.stl --views turntable --height <mm> -o preview.gif → 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. 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

3. generate.py text "prompt" --wait --height <mm> → textured GLB (scaled to target height)

4. python3 scripts/colorize model.glb --height <mm> --max_colors 8 --bambu-map → vertex-color OBJ + _color_map.txt

5. preview.py model.obj --views turntable --height <mm> -o preview.gif

6. 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

7. WAIT for user response. If user requests changes → re-run colorize → show updated report

8. 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):

Workflow D — User-Provided File

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. Same disclaimer as B
2. Confirm dimensions only
3. Save image to workspace (if from chat) or note the file path/URL
4. python3 scripts/generate.py image photo.jpg --wait (auto: validate, remove background, enhance prompt)
   • To skip background removal: add --no-bg-remove
   • To skip prompt enhancement: add --raw
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)
6. Preview + report to user → WAIT for approval
7. 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 --no-bg-remove

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. 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
4. python3 scripts/parametric.py <command> [args] -o model.stl
5. preview.py model.stl --views turntable -o preview.gif → send GIF to chat
6. Report dimensions, volume, triangle count (printed by parametric.py)
7. WAIT for user approval — user may request dimension adjustments
8. If adjustments needed → modify command/spec, regenerate, re-preview
9. 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. 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
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!"

4. WAIT for explicit confirmation.

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

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. bambu.py print model.3mf --confirmed
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. 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?"

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):

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

Anomaly detection:

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. 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
4. 3D generation (optional) — Meshy, Tripo, Printpal, 3D AI Studio + API key
5. Notifications — macOS system notifications (automatic). Agent handles chat notifications via its own messaging tools.
6. Save — config.json + .secrets.json (chmod 600, git-ignored)
7. Verify (ask permission) — test connection, camera, AMS
8. 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, BAMBU_3D_PROVIDER

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

Common Agent Mistakes (self-check)

Common Issues

Known Limitations

Reference Documents

• references/model-specs.md — All 9 printer specifications
• references/manifold-examples.md — Parametric modeling API, tolerance tables, CSG patterns
• references/bambu_filament_colors.json — Bambu Lab 43-color palette (reference only, colorize v4 uses texture-native colors)
• references/bambu-mqtt-protocol.md — MQTT protocol
• references/bambu-cloud-api.md — Cloud API
• references/3d-generation-apis.md — Provider API endpoints
• references/3d-prompt-guide.md — Prompt engineering for 3D

License

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