Kiln

Get printer state, temperatures, job progress, and capabilities. Returns a JSON object with: - ``printer``: connection status, operational state, tool/bed temperatures - ``job``: current file name, completion percentage, elapsed and remaining time - ``capabilities``: what this printer backend supports (``full`` only) Use this as the first call to understand what the printer is doing. Args: printer_name: Target printer. Omit for the default printer. detail: ``"full"`` (default) for everything, or ``"lite"`` for frequent polling during a print — same field names, but ``capabilities`` is omitted and ``printer`` is trimmed to the readings that actually move. Both levels carry every warning. ``detail`` exists so polling and inspection share ONE vocabulary. The retired ``print_status_lite`` returned the same numbers under different names (``completion_pct``, ``hotend_temp``), which is why clients grew defensive key-alias lists to read either shape.

One-shot print status report (human-readable text: progress, temps, speed, cost, ETA). Use for quick status checks. Returns a fixed-format text report with progress, temps, speed, errors, cost estimate, camera snapshot, and health commentary. For structured data + AI vision inspection, use ``monitor_print_vision``. For persistent background monitoring, use ``watch_print``. This is the text report from the computer the printer is attached to. When Kiln's hosted connector is also connected, ``monitor_printer`` there is the door for the inline live monitor and camera; call that one to show the person a live panel. The report's closing ``Live monitor:`` line says whether a panel came with THIS result or where the live monitor is instead — repeat it as written. :param printer_name: Target printer name. Omit for the default printer. :param include_snapshot: Whether to capture and save a camera snapshot. :param brief_id: Optional saved-goal id from ``design_session``. When the brief resolves, the report appends a single ``Goal:`` line with the design's duty and environment — so the agent watching a print can answer "is this the right design for the goal?" without a separate lookup. Best-effort: a missing kiln-pro install or an unresolvable brief silently skips the line. :param show_panel: Open the inline live monitor panel again even though one opened by an earlier call is still live above. Pass only when the person asks to see the panel again; the report itself is unchanged. Read by the inline monitor's result hook (``kiln.local_monitor``), not here. INLINE LIVE MONITOR: in apps that draw MCP Apps panels, this tool's result also carries Kiln's inline print monitor — a live panel with progress, temperatures, and the camera while a print runs. The result's own 'Live monitor:' line says whether that panel is open here, attached b

List all G-code files available on the printer. Handles FTPS directory listing (Bambu), REST file API (OctoPrint/Moonraker) automatically. Returns a JSON array of file objects, each containing: - ``name``: file name - ``path``: full path on the printer - ``size_bytes``: file size (may be null) - ``date``: upload timestamp as Unix epoch (may be null) When G-code metadata is available, files may also include: - ``material``, ``estimated_time_seconds``, ``tool_temp``, ``bed_temp``, ``slicer``, ``layer_height``, ``filament_used_mm`` Use this to discover which files are ready to print. Pass a file's ``name`` or ``path`` to ``start_print`` to begin printing it. For detailed metadata on a specific file, use ``analyze_print_file()``.

無需輸入參數。

Upload a local G-code file to the printer. Handles FTPS (Bambu), REST multipart upload (OctoPrint/Moonraker), and serial file transfer automatically. Args: file_path: Absolute path to the print file on the local filesystem. The file must exist and be readable. Accepted extensions follow the TARGET PRINTER, not one fixed list — ``printer_status()`` reports them per machine, and a Bambu declares ``.3mf`` FIRST because that is the only thing it will start a print from. Bare ``.gcode`` / ``.gco`` / ``.g`` is right for OctoPrint, Moonraker, PrusaLink and Duet; on a Bambu it has no start block and is refused before anything is sent (wrap it with ``wrap_gcode_as_3mf`` first). When ``slice_model`` produced the file, upload the path it names in ``recommended_upload_path`` and do not choose between its outputs by hand — it already knows the printer. printer_name: Which printer to upload to. Omit for the default printer. The G-code dialect scan and the bed-fit gate follow the named machine too, so the bytes are checked against the bed they are actually going to. After a successful upload the file will appear in ``printer_files()`` and can be started with ``start_print()``.

Confirm and execute a pending file upload. When ``KILN_CONFIRM_UPLOAD`` is enabled, ``upload_file()`` returns a confirmation token instead of uploading immediately. Pass that token here to proceed with the upload. Args: token: The confirmation token returned by ``upload_file()``.

Analyze a G-code file on the printer and extract its metadata. Reads the file header to extract slicer-embedded metadata such as material type, estimated print time, temperatures, layer height, and filament usage. This is especially useful when filenames are meaningless (e.g. ``test5112.gcode``) and the agent needs to understand what a file will print. .. note:: For multi-object .gcode.3mf files, also consider using ``list_plate_objects()`` to see individual objects on the plate. Args: filename: Name or path of the file as shown by ``printer_files()``. Returns a JSON object with: - ``filename``: the file name - ``metadata``: extracted metadata (material, time, temps, slicer, etc.) - ``has_metadata``: whether any metadata was found

Delete a G-code file from the printer's storage. Args: file_path: Path of the file as shown by ``printer_files()``. This is irreversible -- the file cannot be recovered once deleted.

Start printing a file already uploaded to the printer (file must exist on printer). ``version_id`` / ``design_id`` / ``branch_id`` name the kept design the file came from, when there is one, so the print's record lands on that version's history; a file that is not a Kiln design passes none. Use ``upload_file`` first, or use ``slice_and_print`` / ``run_quick_print`` to slice + upload + print in one step. Automatically runs pre-flight safety checks before starting. If any check fails the print is blocked and the check results are returned so the agent can diagnose and fix the issue. Args: file_name: Name or path of the file as shown by ``printer_files()``. use_ams: AMS filament feeding mode (Bambu only). Tri-state: - ``"auto"`` (default): auto-detect AMS by probing the printer. If an AMS is connected with loaded trays, enables AMS automatically and selects the first loaded slot if no ``ams_mapping`` is provided. Falls back to external spool if no AMS is detected. - ``"true"``: Force AMS on. Use when you know AMS is connected. - ``"false"``: Force AMS off. Use external spool. ams_mapping: The tray each extruder feeds from (Bambu only), by the printer's own tray id: ``unit * 4 + slot`` on a chained unit (unit B's first slot is 4), the unit id itself on an AMS HT (HT-A is 128). ``ams_status()`` lists each tray's ``tray_id`` and its Studio name (``B1``, ``HT-A``). Defaults to ``[0]`` when AMS feeding is on and ``[]`` (external spool) when it is off. Use ``-1`` for unused positions. timelapse: Record a timelapse video (Bambu only). Default ``False``. bed_leveling: Run automatic bed leveling before print (Bambu only). Default ``True``. Set ``False`` to skip for reprints (~2 min saved). flow_cal

Cancel the currently running print job. Sends cancel via MQTT (Bambu) or REST API (OctoPrint/Moonraker) automatically. The printer must have an active job (printing or paused). :param printer_name: Which printer to stop. Omit for the default printer. Any registered printer can be stopped. :param preserve_temperatures: When ``True``, re-asserts the pre-cancel hotend + bed (+ chamber, if expected_chamber_target is provided) targets immediately after the cancel command, so the printer does NOT cool down. Use this when you plan to swap in a different file (e.g., a mid-print decoration resume 3MF) and need bed adhesion + nozzle temperature held across the cancel-then- start-print transition. Without this, Bambu firmware defaults to cooling on cancel, which can warp the existing part or kill bed adhesion on a partial print you're about to resume. Default ``False`` preserves legacy behaviour (cool down to idle). :param expected_tool_target: Optional caller-supplied tool target to preserve. When provided AND ``preserve_temperatures=True``, this overrides the introspected ``state.tool_temp_target``. Useful when the printer was paused and the firmware has already cleared the target (so a fresh state read returns 0) but the caller knows what the pre-pause target was. :param expected_bed_target: Bed target in Celsius to restore with ``preserve_temperatures=True``, overriding the printer's reported target; pass it when that reported target has already dropped to 0 (after a long pause) so the bed is still restored. :param expected_chamber_target: Optional chamber target (M141) to re-assert via raw G-code. Not all printers expose chamber heating via the adapter API, so this is sent as a raw M141 command best-effort. Pass ``None`` to skip chamber preservation. WARNING:

Send calibration commands directly to the printer adapter. For a full guided calibration pipeline (home + bed level + intelligence guidance), use ``run_calibrate`` instead. This tool sends raw calibration commands via MQTT (Bambu) or G-code (OctoPrint/Moonraker) automatically. The printer must be idle — calibration cannot run during a print. Available options (printer-specific -- not all printers support all): - ``"bed_leveling"``: Auto bed mesh probing and Z offset calibration - ``"vibration"``: Input shaper / vibration compensation tuning - ``"flow"``: Extrusion flow / first-layer inspection calibration - ``"all"``: Run all available calibration routines When no options specified, defaults to bed leveling only. Bambu printers support all options. OctoPrint/Moonraker support ``bed_leveling`` and ``vibration``. Other printers may not support remote calibration. :param options: Which routines to run: ``"bed_leveling"``, ``"vibration"``, ``"flow"`` or ``"all"``, as a list. Omitted, bed leveling only.

Trigger an emergency stop on one or all printers. Sends the strongest stop each printer accepts: Moonraker's emergency-stop endpoint; ``M112`` on OctoPrint, Duet and USB-serial printers; a cancel plus ``M112`` on Elegoo; a job cancel on Prusa Link, which has no raw G-code endpoint; and on Bambu the print-stop command, a heater cut and ``M112``. Creality printers use whichever of these their connection is. Unlike ``cancel_print``, this is not meant to allow a graceful cooldown. Only the Bambu stop is read back: its ``success`` means the printer reported the job ended. On every other printer ``success`` means the stop command was delivered, not that anything was observed. ``success`` is False for any printer whose stop failed or could not be confirmed; when stopping all printers, ``not_confirmed_stopped`` lists each one with the reason. Tell the user to stop those at the machine; calling this tool again for them is safe. Use only in genuine safety emergencies (thermal runaway, collision, spaghetti failure threatening the hotend, etc.). WARNING: After an emergency stop the printer typically requires a power cycle or firmware restart before it can print again. Args: printer_name: Specific printer to stop. If None, stops ALL printers. reason: Reason code, one of ``user_request`` (default), ``thermal_runaway``, ``collision_detected``, ``material_jam``, ``power_anomaly``, ``software_fault``, ``interlock_breach``, ``agent_request``; any other value is refused. source: Trigger source label for audit context. note: Optional operator note.

Get the emergency stop latch status for one printer or the entire fleet. Returns whether an emergency stop is active and whether the printer is locked from printing operations. When an e-stop is active, all print commands are blocked until ``clear_emergency_stop()`` is called with an acknowledgement note. :param printer_name: Query a specific printer, or omit for all printers. :param include_unlatched: When True, include printers that have no active latch. Defaults to False (only active latches). :returns: Latch state per printer: ``active`` (bool), ``reason``, ``source``, ``timestamp``, and whether critical interlocks prevent clearing. See also: ``emergency_stop()``, ``clear_emergency_stop()``.

Clear a latched error on the PRINTER so it will accept prints again. Different from ``clear_emergency_stop``, which releases Kiln's own safety latch. This one acknowledges an error the FIRMWARE is holding — the state the machine itself reports — after which pre-flight checks pass again. Reach for it when ``printer_status`` reports ``error`` and the printer's own screen looks fine. That combination is not a Kiln bug; the firmware really is still reporting the fault, and on some machines dismissing the on-screen message clears the notification without clearing the state. Before this existed there was no way out of that from Kiln at all — only a power cycle — so one bad print locked the machine out of every later one. What it does NOT do is fix the cause. A printer that halted for a real fault will halt again the moment it retries, which is the honest outcome: this reconciles Kiln with the machine, it does not overrule the machine. Nothing is cleared while a print is running. :param printer_name: Target printer. Omit for the default printer. :returns: Whether the acknowledgement was sent, plus the printer state read back afterwards so the caller can see whether it took. See also: ``printer_status()``, ``preflight_check()``, ``emergency_stop()``.

Acknowledge and clear a printer's emergency stop latch. This is a safety-critical operation. The latch may be blocked from clearing if critical interlocks are still active (e.g. thermal sensor failure). Call ``emergency_status()`` first to check whether clearing is possible. :param printer_name: Printer whose latch to clear. :param acknowledgement_note: Free-text note explaining why the e-stop is being cleared (required -- cannot be empty). :param acknowledged_by: Identity of the person or system clearing the latch (default ``"operator"``). :returns: Updated latch state, or an error if critical interlocks prevent clearing. See also: ``emergency_status()``, ``emergency_stop()``.

Briefly override the pre-print impossibility gate for ONE printer. Kiln refuses a print that physically cannot succeed on the target printer — geometry that exceeds the build volume (the nozzle would crash) or a material whose minimum nozzle temperature exceeds the printer's hotend ceiling (it cannot melt the filament). Those are hard physical limits, not warnings, so a normal print call is blocked. It also refuses a file sliced for one nozzle size when the printer's own setting says another is fitted, and a part too big for the bed of the model the printer reports itself as when that differs from the model it was set up as; this override covers both. This is the human's "I understand — print it anyway" escape hatch, e.g. when you are deliberately sending the file to a *different* printer than the one connected. It grants a short, per-printer override that lets the NEXT otherwise-blocked print through, then expires. Safety: classified ``confirm`` (see ``data/tool_safety.json``). An autonomous agent cannot self-approve it — the confirmation layer keeps a human in the loop, exactly like ``emergency_stop``. Designing and slicing any size is never blocked; only the final print-to-hardware step is. :param printer_id: Printer model to override (e.g. ``"bambu_a1"``). Empty resolves to the active printer. :param ttl_minutes: Minutes the override stays active (default 5, max 60). :returns: Grant confirmation, or a confirmation-required challenge.

Trip emergency stop from an external hardware bridge. Designed for physical input devices (ESP32, PLC, wired push buttons) that call this endpoint over HTTP to trigger a software e-stop. This is different from ``emergency_stop()`` which is for agent/software- initiated stops. If ``KILN_ESTOP_INPUT_TOKEN`` is configured, the request must include a matching ``token`` or it will be rejected. :param printer_name: Printer to emergency-stop. :param input_name: Label for the input source (default ``"external_button"``). :param token: Authorization token -- required when ``KILN_ESTOP_INPUT_TOKEN`` is set. :param note: Optional free-text note describing the trigger reason. See also: ``emergency_stop()``, ``emergency_status()``.

Pause the currently running print job. What happens next is decided partly by the printer's own firmware, and it differs a lot between machines: some lift the nozzle and park the head, others leave it resting on the part. Check ``printer_status`` before saying where the head is. While the print is paused Kiln holds the temperatures that matter: - The bed stays at its pre-pause target for the whole pause, so the part stays stuck down and can be resumed. - The nozzle is not left sitting hot over the part. If the printer lowers it by itself (a Bambu A1 sets about 90°C at once), Kiln leaves that alone. If the printer would keep it at full heat, Kiln switches it off 45 seconds into the pause, so a quick look costs nothing. - ``resume_print`` heats the nozzle back to the print's temperature and waits for it before the print continues, so a resume never pushes plastic through a cold nozzle. A temperature the person sets during the pause is the one kept. An emergency stop ends the hold. On a printer Kiln cannot set temperatures on (Prusa Link) the printer's own pause behaviour applies. Args: keep_temps: When ``True`` (default), the bed is held at its pre-pause target for the whole pause and the nozzle is not left sitting hot over the part (switched off shortly into the pause unless the printer lowers it itself); ``resume_print`` reheats it. ``False`` leaves both heaters to the printer. printer_name: Which printer to pause. Omit for the default printer. Each paused machine gets its own hold. leave_nozzle: The person will work the filament during this pause: load new filament after a runout, clear a clog. Kiln then never switches the nozzle off, and leaves it to them and the printer. The bed is still held. Use ``resume_print()`` to continu

Abandon one or more failed objects on a multi-object plate, mid-print. When one part on a full plate fails — spaghetti, a knocked-loose object, a detached corner — this tells the printer to stop printing just those objects and finish the rest of the plate. One bad part no longer scraps the whole run. A Kiln Pro feature. The identifier is backend-specific — pass it as a string, Kiln routes it: * **Bambu** — the ``label_id`` from ``list_plate_objects`` (e.g. ``"757"``). * **Klipper / Moonraker / Creality** — the object NAME the slicer labelled (e.g. ``"Part1"``); the file must have been sliced with object labelling. * **OctoPrint** — the zero-based ``M486`` object index (needs firmware M486 support). Discover Bambu ids first:: list_plate_objects("my_plate.gcode.3mf") # -> objects[].label_id Printer support (honest): Bambu and any Klipper/Moonraker printer can skip (Voron, RatRig, Qidi, and Klipper-based Creality and Elegoo Neptune / OrangeStorm); Marlin printers via OctoPrint or direct USB can if the firmware speaks M486. Prusa via Prusa Link can't be skipped remotely — an API limitation, not the printer (it can cancel objects from its own screen). The Elegoo SDCP protocol (e.g. Centauri Carbon) has no skip command. A Klipper printer on a non-Klipper connection just needs reconnecting as Moonraker. AGENT DISPLAY CONTRACT: skipping is IRREVERSIBLE for the objects named — confirm the exact objects with the user before calling, and only while a multi-object plate is actively printing. Skips are cumulative: an object already skipped stays skipped. Args: object_ids: Object identifiers to abandon, as strings: on Bambu the ``label_id`` from ``list_plate_objects`` (e.g. ``"757"``); on Klipper/Moonraker/Creality the object name the slicer labelled (e.g. ``"Part1"``); on OctoPrint the zero-based M486 object index

Resume a paused print job. The printer must currently be in a paused state. Resuming will return the nozzle to its previous position and continue extruding. Kiln checks afterwards that the resume actually took, so a printer that silently ignored the command reports a failure instead of a cheerful "Print resumed." A print paused at a planned hardware stop (a pause written into the file so a nut, a magnet or a bearing can go in) is refused with ``code: "HARDWARE_NOT_CONFIRMED"`` and a ``hardware`` block saying what goes in. Tell the person, wait for them to say every piece is in and sits level with or below the top of the print, then resume with ``hardware_confirmed=true``. Never pass it on your own judgement. Args: force: Send the resume even when Kiln believes the printer is not paused. Use this when the printer's own screen disagrees with what Kiln reports — a printer can report ``RUNNING`` with perfectly fresh telemetry while standing still, and without this the wrong state word would leave you unable to recover the print. printer_name: Which printer to resume. Omit for the default printer. Pass the same name you paused with. hardware_confirmed: The person has said every piece of hardware for this stop is in and sits level with or below the top of the print. Only on their word.

Set the target temperature for the hotend (tool) and/or heated bed. Args: tool_temp: Target hotend temperature in Celsius. Pass ``0`` to turn the heater off. Omit or pass ``null`` to leave unchanged. bed_temp: Target bed temperature in Celsius. Pass ``0`` to turn the heater off. Omit or pass ``null`` to leave unchanged. printer_name: Which printer to heat. Omit for the default printer. The safety ceiling follows the named machine; a printer with no declared model is held to the generic floor — set its model with ``set_printer_model`` (or ``add_safety_profile``) when that floor refuses a temperature. At least one of ``tool_temp`` or ``bed_temp`` must be provided. Common PLA temperatures: tool 200-210C, bed 60C. Common PETG temperatures: tool 230-250C, bed 80-85C. Common ABS temperatures: tool 240-260C, bed 100-110C. Branch on ``outcome`` — one field, three values, the same shape ``start_print`` uses for ``print_start``: - ``"confirmed"``: the printer, in a report AFTER the command, shows the effect. Reported per heater under ``tool`` and ``bed``. - ``"accepted"``: the command was sent and not refused, and the printer has not shown the effect yet. Normal on a quiet printer. Read ``printer_status()`` before building on it. - ``"failed"``: the printer's interface refused the command. ``accepted`` (the boolean) keeps its old meaning: sent, not refused. It is never proof the printer acted. ``success`` is ``False`` only for ``"failed"``.

Full AMS hardware dump — all trays, humidity, RFID (Bambu Lab only). For just the currently-active material, use ``get_active_material`` instead. For Kiln's software material tracker, use ``get_material``. Returns what's loaded in each AMS tray: filament type, color, remaining percentage, RFID tag, temperature ranges, and humidity. Each tray carries its unit's own ``slot`` (0-3), the printer's ``tray_id`` for it (``unit * 4 + slot`` on a chained unit, the unit id itself on an AMS HT) and Studio's ``name`` (``A1``…``D4``, ``HT-A``); each unit carries its ``name`` (``A``, ``HT-B``). ``feeding`` is the tray feeding the nozzle -- ``{tray_id, unit, slot, name, source}``, or ``None`` when nothing feeds -- and ``feeding_source`` says which field of the printer's report it came from. The raw ``tray_now`` is kept as sent: ``"254"`` is the external spool, ``"255"`` no tray. A1 / AMS Lite reports may keep ``tray_now`` at ``"255"`` while exposing loaded AMS trays and selected/target tray fields such as ``tray_pre`` or ``tray_tar``. The ``ams_exist_bits`` and ``tray_exist_bits`` fields are bitmasks showing which AMS units and trays are physically present. Use this to check filament levels before printing, verify the correct material is loaded, or select the right ``ams_mapping`` for ``start_print()``. This dump carries no fault line of its own. To follow a print, poll ``printer_status(detail="lite")``: it reports the run state and every fault code under ``faults``. A fault the printer stops for on a watched print also rides this and every other tool result as ``printer_fault`` while it stands.

無需輸入參數。

Discover Creality CFS/CFS-C status through local Moonraker. This is the Creality counterpart to ``ams_status()``, but the public protocol is not equivalent to Bambu AMS. Creality documents CFS control through Creality Print and printer UI; Kiln therefore performs read-only Moonraker discovery (`/printer/objects/list`, candidate object queries, and `/printer/gcode/help`) and reports any visible CFS slots/macros. The response includes ``hardware_unverified=True`` and ``active_slot_control_supported=False`` until slot load/unload/mapping commands are validated against real Creality hardware or official API docs.

無需輸入參數。

Set the print speed: a preset by name, or a percentage of the sliced speed. One door for both ways a printer takes a speed. Give exactly one of: Args: profile: A preset — ``"silent"`` (50%), ``"standard"`` (100%), ``"sport"`` (124%) or ``"ludicrous"`` (166%). Bambu Lab printers only; sport and ludicrous raise the nozzle temperature to keep up with the flow. percent: The speed as a percentage of the speed the file was sliced at — the feedrate override every FDM firmware has (100 is the sliced speed; 10 to 300 is accepted). A Bambu takes only its four presets, so the nearest one is set and the answer says which (``preset``, ``percent_actual``). printer_name: Which printer. Omit for the default printer. Nothing here judges whether a speed suits THIS printer or THIS layer: Kiln's served ``set_speed_percent`` and ``set_speed_schedule`` do that and hand the checked value here. Use ``printer_status()`` to see the current speed profile in ``printer.speed_profile``. Branch on ``outcome`` — one field, three values, the same shape ``start_print`` uses for ``print_start``: - ``"confirmed"``: the printer, in a report AFTER the command, shows the effect. For a Bambu, the reported speed level moved. - ``"accepted"``: the command was sent and not refused, and the printer has not shown the effect yet. Normal on a quiet printer. Read ``printer_status()`` before building on it. - ``"failed"``: the printer's interface refused the command. ``accepted`` (the boolean) keeps its old meaning: sent, not refused. It is never proof the printer acted. ``success`` is ``False`` only for ``"failed"``.

Run, report or stop a layer-based speed schedule on this computer. A schedule is a list of ``{"from_layer", "to_layer", "speed_percent"}`` segments. With ``action="run"`` it starts on the printer that is printing now, replacing a schedule already running for that printer: the printer is asked which layer it is on every few seconds and each segment's speed is set once, as the print reaches it. It stops on its own when the print ends, when the printer is found running a different print, or on ``action="stop"`` (the printer stays at the last speed set). ``action="status"`` reports what has been applied so far. Only the schedule's shape is checked here. Which speeds suit this printer and which layers a speed is unsafe on is decided by Kiln's served ``set_speed_schedule``, which hands the checked schedule here. Args: schedule: The segments to run (``action="run"`` only): a list of 1 to 64 ``{"from_layer": int, "to_layer": int, "speed_percent": int}`` entries, ``speed_percent`` within 10-300. printer_name: Which printer. Omit for the default printer. action: ``"run"`` (default), ``"status"`` or ``"stop"``.

Get the current speed profile (Bambu Lab printers only). Returns the active speed profile with: - ``level``: numeric level 1–4 - ``name``: profile name — ``"silent"`` (50%), ``"standard"`` (100%), ``"sport"`` (124%), or ``"ludicrous"`` (166%) - ``speed_magnitude``: actual speed multiplier percentage reported by the printer firmware Use this to check the current speed before adjusting it with ``set_speed_profile()``.

無需輸入參數。

Control the printer's LED lights (Bambu Lab printers only). Args: node: Which light to control — ``"chamber_light"`` (main illumination) or ``"work_light"`` (nozzle area). Defaults to ``"chamber_light"``. mode: Light mode — ``"on"``, ``"off"``, or ``"flashing"``. Required: a call that arrives without it is refused rather than turned on (the same rule as ``set_fan``'s ``percent``). Use this to improve camera visibility, signal print completion (flashing), or turn lights off for overnight prints. Branch on ``outcome`` — one field, three values, the same shape ``start_print`` uses for ``print_start``: - ``"confirmed"``: the printer, in a report AFTER the command, shows the effect. For a Bambu, the light report lists that node in that mode. - ``"accepted"``: the command was sent and not refused, and the printer has not shown the effect yet. Normal on a quiet printer. Read ``printer_status()`` before building on it. - ``"failed"``: the printer's interface refused the command. ``accepted`` (the boolean) keeps its old meaning: sent, not refused. It is never proof the printer acted. ``success`` is ``False`` only for ``"failed"``.

Set the speed of a printer fan. ``percent`` has no default on purpose. Measured 2026-09-18 on an A1: a call meant to turn the fan OFF reached Kiln with no ``percent`` at all (the caller's own argument name had been dropped before the request arrived), the old default of 100 ran the fan flat out, and the answer confirmed it. A setpoint the caller did not send is refused, never guessed. Supported on Bambu Lab, OctoPrint, Moonraker/Klipper printers, and Elegoo's Centauri Carbon (FDM). Prusa Link has no raw G-code endpoint, so fan control isn't available there (a known limitation of Prusa Link itself). An Elegoo machine with no part-cooling fan is refused. Args: node: Which fan to set. ``"part"`` (part-cooling / model fan, the one that cools each layer) works on every supported printer. ``"aux"`` (auxiliary / big fan) and ``"chamber"`` (chamber / exhaust fan) are Bambu-only — generic Marlin/Klipper firmware has no standard auxiliary or chamber fan Kiln can address without knowing that machine's own G-code macros. Defaults to ``"part"``. percent: Fan speed 0-100. ``0`` turns the fan off, ``100`` is full speed. Required. Use this to add cooling for bridges and overhangs (part fan), or — on Bambu — pull heat with the auxiliary fan or run the chamber/exhaust fan for materials like ABS/ASA. The Bambu chamber fan only exists on enclosed models — X1 Carbon, X1E, P1S, P2S, H2S — not on open-frame models (A1, A1 Mini, A2L, P1P), where a chamber command is a no-op. The printer's own thermal management may override a manual fan speed during a print. Branch on ``outcome`` — one field, three values, the same shape ``start_print`` uses for ``print_start``: - ``"confirmed"``: the printer, in a report AFTER the command, shows the effect. For a Bambu, that fan's reported level matches. - ``"accepted"

Wrap raw PrusaSlicer G-code in a Bambu-compatible 3MF (Bambu Lab only). Bambu printers require the proprietary BambuStudio start/end sequences (motor enable, AMS load, extrusion calibration) to function correctly. This tool takes PrusaSlicer G-code output and packages it into a 3MF that the printer will accept. Args: gcode_path: Absolute path to a PrusaSlicer ``.gcode`` file on the local filesystem. The file must have been sliced with ``--use-relative-e-distances`` and empty start/end G-code. hotend_temp: Hotend temperature in °C for the start sequence. Omitted, the temperature the G-code itself first heats to. bed_temp: Bed temperature in °C, likewise. filament_type: Filament type string — ``"PLA"``, ``"PETG"``, ``"ABS"``, etc. Omitted, the type the slicer wrote into the G-code (every Kiln slice carries the material it was weighed as). The response's ``filament_type`` is what the printer is told, in Bambu's own vocabulary. source_3mf_path: Optional path to a source 3MF to copy thumbnails and geometry from. num_filaments: Number of filaments (>1 for multi-color prints). filament_colors: List of hex color strings per filament (e.g. ``["#898989FF", "#161616FF"]``). filament_types: List of filament type strings per filament (e.g. ``["PLA", "PLA"]``). thumbnail_path: Optional path to a PNG image to embed as the 3MF thumbnail (shown on the printer's display). stl_path: Optional path to the source STL file. When provided, a thumbnail is auto-generated from the model geometry via OpenSCAD (512x512, shown on the Bambu printer screen). bed_type: The plate fitted: ``"textured_plate"``, ``"hot_plate"`` (smooth PEI), ``"cool_plate"``, ``"eng_plate"`` or ``"supertack_plate"``. Omitted or e

Get the bed mesh / probe data (OctoPrint and Moonraker only). Returns the probed bed leveling mesh including: - ``probed_matrix``: 2D array of Z-offset measurements across the bed - ``mesh_min`` / ``mesh_max``: bounding coordinates of the probed area - ``variance``: overall variance of the mesh (lower = flatter bed) Use this to diagnose first-layer adhesion issues. High variance or significant dips/peaks indicate a warped bed or loose leveling screws. Not supported on Bambu Lab printers — Bambu handles bed leveling internally and does not expose mesh data.

無需輸入參數。

Get the filament runout sensor status (OctoPrint and Moonraker only). Returns sensor information including: - ``detected``: whether filament is currently detected by the sensor - ``sensor_enabled``: whether the runout sensor is active Use this to verify filament is loaded before starting a print on non-Bambu printers. For Bambu Lab printers, use ``ams_status()`` instead — it provides per-tray filament presence, type, color, and remaining percentage.

無需輸入參數。

Get the current nozzle / tool-head XYZ position (Moonraker and Serial). Returns a dict with at least ``x``, ``y``, ``z`` coordinates in mm relative to the printer's home position. Some printers also report ``e`` (extruder position). Use this for: - Verifying the printer has been homed (coordinates are valid only after homing) - Calibration sequences that need to know the current position - Move planning when issuing manual jog commands Not all adapters support this — returns an error if position data is not available.

無需輸入參數。

Run pre-print safety checks to verify the printer is ready. Checks performed: - Printer is connected and operational - Printer is not currently printing - No error flags are set - Temperatures are within safe limits - (Optional) Material loaded matches expected material - (Optional) Local G-code file is valid and readable - (Optional) Remote file exists on the printer - (Optional) For a model file (STL, OBJ, 3MF, STEP, GLB), whether the part prints: this fails exactly where the print door would refuse the file, and passes wherever the door would print it. - Multi-material: what unit the printer carries (AMS, a Klipper MMU) and, with ``file_path``, whether the file's filaments are loaded. Advisory for a unit Kiln drives (the print gate decides at start); a FAILURE when a multi-filament file needs more colours than a unit Kiln does not drive has loaded — that print comes out wrong and nothing downstream stops it. Absent for a single-feed printer; a read that failed is reported as such, never as "no unit". Args: file_path: Optional path to a local print file (``.gcode``, ``.gco``, ``.g`` or ``.3mf``) to validate before upload; a model file (STL, OBJ, STEP) fails the ``file_valid`` check. If omitted, only printer-state checks are performed. expected_material: Optional material type (e.g. "PLA", "ABS", "PETG"). If provided and a material is loaded, checks for a mismatch. remote_file: Optional filename to verify exists on the printer. If provided, checks the printer's file list for a matching file. accept_paused: When ``True``, the ``printer_idle`` check accepts the ``paused`` state in addition to ``idle``. Used by ``start_print(resume_from_paused=True)`` for mid-print resume 3MFs (which start from a paused-state printer). Default ``False

Send raw G-code commands directly to the printer. Args: commands: One or more G-code commands separated by newlines or spaces. Examples: ``"G28"`` (home all axes), ``"G28\nG1 Z10 F300"`` (home then move Z up 10mm), ``"M104 S200"`` (set hotend to 200C). dry_run: When ``True``, run the full validation pipeline (auth, rate-limit, G-code safety) but do **not** actually send commands to the printer. Returns what *would* have been sent. The commands are sent sequentially in order. The printer must be connected (unless ``dry_run`` is ``True``). G-code is validated before sending. Commands that exceed temperature limits or modify firmware settings are blocked. Use ``validate_gcode`` to preview what would be allowed without actually sending. Raw G-code has no general read-back, so ``outcome`` here is ``"accepted"`` whenever the command was sent: the printer took the bytes, and whether it EXECUTED them is not reported. Observe the printer (``printer_status()``, or the machine itself) before building on a G-code send. ``"failed"`` means the transport refused it.

Issue a preview-confirmation token for a file about to be printed. Call this AFTER the user has seen the print, and say WHICH door showed it — ``door`` is required and is checked against what this server itself recorded, never taken on your word: 1. ``door="stage"`` — the inline 3D stage (the MCP Apps panel that opens on a make, which the user can orbit). This is the first and best option. Accepted only when the panel actually fetched the geometry for this file (or for the design mesh it was sliced from). 2. ``door="url"`` — a hosted viewer link. Use it when this host draws no panel. Accepted only when ``show_on_stage(file_path)`` issued a ``viewer_url`` for this file that is still live (its result carries one on a host that draws no panel, while the machine is signed in). 3. ``door="png"`` — the stage's own still (``visualize_model`` with ``renderer`` ``stage`` or ``stage_paint``). The total fallback. Accepted only when such a render is on record AND the stage is unavailable for a reason the server can name AND the link door refused for a reason it recorded. A raw ``openscad`` render is inspection-only and is refused; a PNG claim on a host that draws the stage is refused and told to open the stage. The user approves → you call this tool → you pass the returned token as ``preview_token`` to ``start_print`` (or any other tool that starts a print) or ``fulfillment_order``. Without a valid token those tools refuse (unless ``KILN_SKIP_PREVIEW_GATE=1``). This is the deepest safety gate that prevents an agent from sending a print to the physical printer without the user ever seeing what's about to be printed. Tokens are single-use and expire after ``ttl_seconds`` (default 600 seconds / 10 minutes). Scoped to the specific file hash and optionally to a specific printer_id so a token for one file can't be

Execute a previously requested action that requires confirmation. When ``KILN_CONFIRM_MODE`` is enabled, destructive tools (safety level ``"confirm"`` or ``"emergency"``) return a confirmation token instead of executing immediately. Pass that token here to proceed. Args: token: The confirmation token returned by the original tool call.

Get live status of all fleet printers (state, temps, connection — current snapshot). The multi-machine view is a fleet feature. For ONE printer — which is the single-printer experience at every tier — use ``printer_status`` (``detail="lite"`` for the cheap version), ``printer_snapshot`` or ``monitor_print``; each takes a ``printer_name`` and none of them is tier-gated, so any machine you own can be inspected and stopped whatever your licence. For historical analytics (success rates, throughput), use ``fleet_analytics``. Returns a list of printer snapshots including name, backend type, connection status, operational state, and temperatures. Printers that fail to respond are reported as offline rather than raising. A printer the person marked with ``set_machine_repair`` carries a ``repair`` block (needs repair since, or repaired at and what), and ``needs_repair_printers`` lists the ones out of service: routing does not choose them, though they may read as idle. Args: by_site: Also group the same printers by the site each one is at (``update_printer_site``; printers with no site fall under ``"unassigned"``). When the plan includes it the answer adds ``sites`` (per site: ``printers``, ``count``, ``idle``, ``busy``, ``needs_repair``) and ``site_count``; otherwise the flat answer comes back with one ``note``, never a refusal. If no printers are registered yet, the current adapter (from env config) is auto-registered as "default".

Register a new printer in the fleet. Registering is free at every tier and always has been — what the fleet tier sells is running printers in PARALLEL, enforced when a print starts, not when a machine is added. So owning a second printer and using them one at a time is a supported setup on Free and Pro: the registration succeeds and the reply notes the concurrency limit. Free and Pro run 1 printer at a time. Driving several at once starts at Business; the reply says how many printers your plan includes. Args: name: Unique human-readable name (e.g. "voron-350", "bambu-x1c"). A name holding the printer's address, serial or another identifier is held before anything is saved (code ``NAME_HOLDS_IDENTIFIER``): the reply says what is in it and carries ``suggested_name``. Offer that to the person, then call again with the name they choose. printer_type: Backend type -- "octoprint", "moonraker", "bambu", "creality", "elegoo", "prusalink", "duet", or "usb". "serial" is accepted as a legacy alias for "usb". host: Base URL or IP address of the printer. For USB printers, this is the port path (e.g. "/dev/ttyUSB0", "COM3"). api_key: The printer's credential: an API key (OctoPrint, Prusa Link, a Moonraker or Creality printer with its login turned on), a Bambu Lab printer's LAN access code, or a Duet's machine password. For OctoPrint it can be left out: Kiln asks OctoPrint for a key and the reply (code ``AWAITING_APPROVAL``) carries ``approve_url``, a page where the person clicks Allow. Give them that link, then call again with the same arguments; the request stays open for ten minutes. serial: A Bambu Lab printer's serial number (``discover_printers`` reads it off the network), or an Elegoo printer's mainboard id

Tell Kiln which printer model a saved printer is -- by name, or from a slicer file. Kiln checks every print against the bed it will land on and the temperatures the machine can take, and slices with the model's own profile. All three are read from the printer's model. With no model set, those checks are SKIPPED. Use this as soon as ``kiln_health`` or a log says the model is not configured. Two ways to say it -- give exactly one: * ``printer_model``: any name the catalogue recognises (``"Bambu Lab A1"``, ``"bambu_a1"``, ``"MK4"``, ``"K1 Max"``). * ``slicer_file``: a project the user saved from Bambu Studio, OrcaSlicer or PrusaSlicer (File > Save Project), or a printer settings file exported from one. It already names the printer it was set up for. Ask a new user for one instead of asking them to look up a model key. A printer that is NOT in Kiln's catalogue is recorded as the person names it, with its make (``printer_make="Prusa"``, ``printer_model="Core One L"`` is saved as ``prusa_core_one_l``) and held to Kiln's generic limits; never substitute a near catalogue model the person did not name. A slicer file sets such a printer up more fully: it states the bed, so Kiln also lays slices out on it and measures designs against it. Either way Kiln has no tuned profile for it and will not move its head. A model outside the catalogue with no make (none given, and none implied by the connection) is refused (``UNKNOWN_MODEL``, with the closest matches); ask who makes it. Such a printer's bed is recorded here too, and its first print waits for it (``PRINTER_BED_UNKNOWN``): look up the bed size its maker publishes (spec page or manual), show the person the size and the page, and when they say it is right pass ``bed_mm``, ``bed_source`` and ``bed_confirmed=True``. Never guess the size and never ask the person to know it. A catalogue printe

Get recent events from the Kiln event bus. Args: limit: Maximum number of events to return (default 20, max 100). type: Filter by event type prefix (e.g. ``"print"`` matches ``print.started``, ``print.completed``; ``"job"`` matches ``job.submitted``, ``job.completed``). Omit for all events. Returns events covering job lifecycle, printer state changes, safety warnings, and more.

Get the current plan and whether this machine's sign-in still holds it. Returns the active tier (free/pro/business/enterprise), whether it is valid, its expiration date, and how it was resolved (``oauth`` for a Kiln account sign-in, ``default`` for none). No authentication required. When the tier comes from a sign-in session (``source`` is ``"oauth"``), the answer also carries ``session_state``. If that session has lapsed, ``is_valid`` is ``false`` and ``action_required`` says how to fix it — surface that line to the user verbatim, because every hosted call will fail until they do.

無需輸入參數。

Retired: license keys no longer unlock Kiln. Sign in instead. Kiln stopped taking license keys on 2026-11-01; a plan reaches a machine only through the Kiln account it is signed in to. This tool saves nothing and reads nothing it is sent: it answers with the sign-in steps, so an agent or an old script that still calls it learns the way in. Show the user ``error`` as written, then sign them in (``kiln_signin``). Args: key: Ignored. Kept so an older call still gets this answer.

Restart the Kiln MCP server process. Replaces the current process with a fresh instance using ``os.execve``. The exec keeps the stdio pipe, so the MCP client sees no disconnect and repeats no ``initialize`` handshake; the fresh process takes up the handshake this connection already made, so the client's next call simply works. The client keeps the tool list it cached when it connected: tools the new code adds reach it when it reconnects. The result's ``keeps_connection`` says whether the handshake was handed on. WHAT A RESTART REFRESHES depends on how this server was launched, and the result says which happened. A launcher script that exported ``KILN_SERVE_WRAPPER`` is re-entered whole, so whatever that script does before serving — syncing code, healing installs — runs again. Without it the restart re-execs ``python -m kiln serve`` in place: a fresh process over however this interpreter resolves ``kiln``, which picks up edits to those files but runs no launcher logic. (Measured 2026-08-19: an operator launcher synced two runtime clones on every start, and a restart through this tool silently skipped the sync — the served code was two revisions stale while the restart reported success.) Use after installing or updating kiln-pro plugins, changing environment variables, or modifying server code — avoids the need to fully restart the MCP client application. :param clean_env: When ``True`` (default), strips ``KILN_PRINTER_*`` environment variables from the child process if ``~/.kiln/config.yaml`` has a printer configured. This defeats the "ghost env" footgun where a stale ``KILN_PRINTER_API_KEY`` inherited from a past shell session silently shadows config.yaml edits for the lifetime of the MCP parent process. Without this, every edit to config.yaml looks like it does nothing and the printer rejects MQTT auth with

Return the current autonomy tier and constraints. Shows the autonomy level (0 = confirm all, 1 = pre-screened, 2 = full trust) and any Level 1 constraints that are configured. Call this early in a session to understand how much freedom you have.

無需輸入參數。

Set the autonomy tier (0, 1, or 2). Level 0 (Confirm All): Every confirm-level tool requires approval. Level 1 (Pre-screened): Confirm-level tools allowed if constraints pass. Level 2 (Full Trust): All tools allowed except emergency-level. Changing this updates the config file. Requires human confirmation because it affects how much control the agent has. :param level: The tier to set: ``0`` confirm all, ``1`` pre-screened, ``2`` full trust.

Check whether the agent may execute a tool without human confirmation. Pass the tool name, its safety level, and optional operation context (material, time, temperatures) to get a decision. Use this before calling confirm-level tools to decide whether to proceed or ask. :param tool_name: The tool the agent wants to call, by name. :param safety_level: That tool's safety level: ``"safe"``, ``"guarded"``, ``"confirm"`` or ``"emergency"``. :param material: Material the operation would print in, when it prints. :param estimated_time_seconds: How long the operation would run, in seconds; ``0`` when unknown. :param tool_temp: Hotend temperature the operation would set, in °C; ``0`` when it sets none. :param bed_temp: Bed temperature the operation would set, in °C; ``0`` when it sets none.

Show which 3D model marketplaces are connected and available. Returns the list of connected marketplace sources and their capabilities (search, download support, etc.). Configure marketplaces via environment variables. **See also:** ``marketplace_status`` for per-credential diagnostics, or ``marketplace_diagnostics`` for live connectivity probes. **Safety note:** Community-uploaded models are unverified. Always review model dimensions and preview prints before starting. Proven, popular models with high download counts are safer choices than untested uploads.

無需輸入參數。

Download model file(s) from any marketplace and upload to a printer. **Community models are unverified.** This tool downloads and uploads but does NOT start printing automatically. You must call ``start_print`` separately after reviewing the uploaded file. 3D printers are delicate hardware — misconfigured or malformed models can cause physical damage. When ``file_id`` is provided, downloads and uploads that single file. When ``model_id`` is provided without ``file_id``, downloads and uploads all printable files (.stl, .gcode, .3mf, .glb) for the model. A GLB goes to the printer as an STL beside it, never as a GLB; the upload's ``conversion`` names the original, which stays on disk. Args: file_id: File ID (from ``model_files`` results). For Thingiverse this is a numeric ID; for MyMiniFactory it's the file ID string. If omitted and ``model_id`` is given, all printable files are downloaded and uploaded. source: Which marketplace to download from — "thingiverse" (default) or "myminifactory". Cults3D does not support direct downloads. printer_name: Target printer name. Omit to use the default printer. model_id: Model/thing ID. When ``file_id`` is omitted, all printable files for this model are downloaded and uploaded. After uploading, review the model and call ``start_print`` to begin.

Rotate a 3D model file (STL or 3MF) by specified angles before slicing. Useful for improving print quality — rotating a tall narrow part 45° around the Z axis can reduce toolhead-induced wobble and ringing artifacts. Args: input_path: Path to the STL or 3MF file to rotate. rotation_z: Rotation around Z axis in degrees (most common — rotates on the build plate). rotation_x: Rotation around X axis in degrees. rotation_y: Rotation around Y axis in degrees. output_path: Where to save the rotated file. Defaults to ``<input>_rotated.<ext>``. Returns dict with ``output_path`` (path to rotated file) and ``rotations_applied``. Pair with ``reslice_with_overrides`` to re-slice the rotated model with adjusted settings (e.g., stronger brim after rotation). INLINE 3D STAGE: on success this tool opens Kiln's interactive 3D stage — an inline viewer panel the user can orbit, zoom, and turn over — in hosts that render MCP Apps panels (Kiln's hosted connection attaches a browser stage link for hosts that don't). Oversized meshes are decimated automatically for the stage; the PNG preview is the floor, not the whole experience.

Check if a model's orientation is stable for printing. Analyzes the height-to-base ratio and warns if the model is likely to wobble or fail mid-print. Suggests reorientation if needed. :param model_path: Path to the STL or OBJ model file. :returns: Dict with stability assessment.

Capture a webcam snapshot from the printer. Handles TLS+JPEG camera protocol (Bambu A1/P1), MJPEG stream capture (OctoPrint/Moonraker), and RTSPS (Bambu X1) automatically. A camera the user registered for the printer (``register_printer`` with ``camera_snapshot_url`` / ``camera_stream_url``) is used instead of the printer's own; ``camera_source`` in the reply says which one answered. :param printer_name: Target printer name. Omit for the default printer. :param save_path: Optional path to save the image file. If omitted, the image is returned as a base64-encoded string.

List built-in filament material profiles (density, cost, temps). Returns Kiln's bundled material database — NOT what is physically loaded. For loaded material, use ``get_material`` (software tracker) or ``get_active_material`` (live AMS hardware query).

無需輸入參數。

Record which filament material is loaded in a printer. This writes down a CLAIM, not a measurement: nothing verifies the spool, and the record keeps saying the same thing after a filament swap. Kiln stamps it ``determined_by: user_reported`` and every reader says so, so never report the recorded material back as confirmed or sensed. Args: printer_name: Target printer name. material: Material type (PLA, PETG, ABS, etc.). color: Optional filament color. spool_id: Optional ID of a tracked spool (see ``list_spools``). Linking one is what lets Kiln count that spool down as this printer prints from it. tool_index: Extruder index for multi-tool printers (default 0). On a printer with a multi-material unit, the tray's id as ``ams_status`` reports it.

Get material loaded in a printer (from Kiln's software tracker). Returns what the user/agent told Kiln is loaded via ``set_material``. For live AMS hardware reading (Bambu Lab), use ``get_active_material``. Args: printer_name: Target printer. Omit for the default printer.

Check whether the material Kiln has on record matches what a print expects. Answers about Kiln's material RECORD, which normally holds what a person or agent typed via ``set_material`` — not a sensor reading. Three answers, and the third one matters: ``match: true`` (the record agrees), ``match: false`` (it disagrees — worth stopping for), and ``match: null`` (nothing is recorded for this printer, so this is neither a match nor a mismatch and the spool needs an eye on it). ``sensed`` says whether a machine reported the material; when it is false, the material is on record, not confirmed, and the answer should say so. Args: expected_material: The material the print file requires. printer_name: Target printer. Omit to resolve the active printer.

List all tracked filament spools in inventory. ``remaining_grams`` is what Kiln believes is left on each spool, and ``remaining_determined_by`` says who set it: ``inferred`` is Kiln's own count (what the spool held, less what the prints Kiln started were sliced to use), ``observed`` is the printer's reading of a spool it can measure, ``user_reported`` is what the person said. A count misses prints started outside Kiln, so report a counted figure as Kiln's count, never as a measurement. When the person says the figure is wrong, correct it with ``add_spool(spool_id=..., remaining_grams=...)``; when they say a spool is used up, ``remove_spool``.

無需輸入參數。

Add a filament spool to inventory, or correct how much is left on one. To ADD a spool, give its ``material``. ``remaining_grams`` is what is left on a spool that is not new; left out, the spool is full. To CORRECT a spool already on record, pass its ``spool_id`` (from ``list_spools``) with ``remaining_grams``: the person says they have more left than Kiln shows, or less. Only the amount changes. Kiln counts a spool down as the prints it starts use it, and a count drifts, so the person's word wins. ``remaining_grams=0`` records the spool as used up and keeps it on the list; ``remove_spool`` takes it off. Args: material: Material type (PLA, PETG, ABS, etc.). Required to add. color: Filament color. brand: Manufacturer brand. weight_grams: Total spool weight in grams (default 1000). cost_usd: Cost of the spool in USD. remaining_grams: Grams left on the spool. spool_id: A spool already on record whose remaining amount to set.

Remove a filament spool from inventory. When the person says a spool is used up, finished or gone, remove it here (``list_spools`` gives its id) so Kiln stops treating it as filament they have. If they have more or less left than Kiln shows, correct the figure with ``add_spool(spool_id=..., remaining_grams=...)`` instead. A used-up spool is not a reason to suggest buying filament: say nothing about that unless the person asks. Args: spool_id: The spool's unique identifier.

Check bed leveling status and whether leveling is needed. Args: printer_name: Target printer. Omit for the default printer.

Trigger a bed leveling / mesh probe on the printer. Sends the configured G-code command (G29 or BED_MESH_CALIBRATE) to the printer. Args: printer_name: Target printer. Omit for the default printer.

Configure automatic bed leveling policy for a printer. Args: enabled: Enable/disable auto-leveling checks. max_prints: Trigger leveling after this many prints. max_hours: Trigger leveling after this many hours. gcode_command: G-code command to send (G29 or BED_MESH_CALIBRATE). printer_name: Target printer. Omit for the default printer.

Control the local live-video relay for the print monitor. ONE connection to the printer's camera, re-served as an MJPEG stream on this machine so every viewer shares it. Reads an HTTP MJPEG webcam (OctoPrint, Moonraker, a camera you registered) or a Bambu A1 / P1 camera's own port-6000 feed. The reply's ``capability`` says whether this printer can be relayed and, when not, why — an X1 / P2S / H2 camera streams RTSPS, which the relay does not carry (snapshots still work). ``stream`` carries the frame's age and the measured frame rate: ``live`` is false when the picture may be frozen. Local-only: the relay reads the camera over your LAN and serves on loopback, so on the hosted server it says so instead of starting. Snapshots (``printer_snapshot``, ``monitor_print``) are unchanged. A refused start on a printer type that has a camera check carries ``check_available: true``; ``action="check"`` then looks at what that printer's likely camera addresses actually serve. Args: printer_name: Target printer. Omit for the default printer. action: One of ``"start"``, ``"stop"``, ``"status"``, or ``"check"``. ``"check"`` runs only when asked: it tries each address this printer type's camera is known to answer on, on the printer's own host, with one GET each (a printer that gives out its camera address on request is asked for it first, as a start does), and replies with ``checks`` (what each served — a live stream, a still, a WebRTC page, a web page, an error, or nothing — and where the address comes from), a ``summary`` and a ``next_step``. It registers nothing; when it finds a live stream, ``next_step`` says how to register that address as the printer's camera. Local-only, like ``"start"``. port: Local port for the stream server (default 8081).

List all discovered plugins and their status.

無需輸入參數。

Register a webhook endpoint to receive Kiln event notifications. Args: url: The HTTPS URL that will receive POST requests with event payloads. events: Optional list of event types to subscribe to (e.g. ["job.completed", "print.failed"]). If omitted, all events are sent. secret: Optional shared secret for HMAC-SHA256 payload signing. description: Human-readable label for this endpoint. Returns the registered endpoint ID. Use ``list_webhooks`` to see all endpoints and ``delete_webhook`` to remove one.

List all registered webhook endpoints. Returns endpoint details including URL, subscribed events, and delivery statistics.

無需輸入參數。

Delete a registered webhook endpoint. Args: endpoint_id: The endpoint ID returned by ``register_webhook``. Once deleted, the endpoint will no longer receive event notifications.

Wait for the current print to finish and return the final status. Polls the printer (or a specific queued job) until it reaches a terminal state: completed, failed, cancelled, or the timeout is exceeded. This lets agents fire-and-forget a print and pick up the result later without managing their own polling loop. A host that runs tools in the background (the MCP tasks extension) gets a task back instead of a blocked call: keep working, and the host says when the wait returns. There one call can wait as long as the plan needs, up to the whole print. Closing that app ends the wait, never the print. Args: job_id: Optional job ID from ``submit_job()``. When provided, tracks that specific job through the queue/scheduler. When omitted, monitors the printer directly for idle/error state. timeout: Maximum seconds to wait (default 7200 = 2 hours). poll_interval: Seconds between status checks (default 15). brief_id: Optional saved-goal id from ``design_session``. When the brief resolves, the terminal-outcome response gains a ``design_goal`` block with the design's duty / environment / safety notes — so the agent surfacing the print result can answer "did this match the goal?" without a separate lookup. Best-effort: missing kiln-pro silently skips. Returns a dict with ``outcome`` (completed / failed / cancelled / timeout), final printer state, elapsed time, completion percentage history, and (when ``brief_id`` resolves) a ``design_goal`` block. A print carrying a hardware plan (pauses written in for nuts, magnets or bearings) also returns early with ``outcome: "hardware_stop"`` and a ``hardware`` block: when a stop is a few minutes away, when the printer has stopped for the parts, and when it went past a stop without stopping. Tell the person what the block says, then wait again.

Compare local printing cost vs. outsourced manufacturing. Runs a local cost estimate and (if Craftcloud is configured) fetches a fulfillment quote, then returns a side-by-side comparison to help agents recommend the best option. Args: file_path: Path to the G-code file (for local) or model file (STL/3MF for fulfillment). If a G-code file is provided, only local estimate is returned. material: Filament material for the local estimate (PLA, PETG, …). Leave empty to use what the file was sliced for, PLA when it names nothing. When Kiln's servers answer, the local estimate also carries a ``cost_intelligence`` field; what it holds depends on the tier. fulfillment_material_id: Material ID from ``fulfillment_materials`` for the outsourced quote. If omitted, the fulfillment quote is skipped. quantity: Number of copies for fulfillment (default 1). electricity_rate: Cost per kWh in USD (default 0.12). printer_wattage: Printer power consumption in watts (default 200). shipping_country: ISO country code for fulfillment shipping. printer_id: Optional registered printer the local print is for; passed on with the file when kiln-pro is asked.

Analyze a failed print job and suggest possible causes and fixes. Examines the job record, related events (retries, errors, progress), and printer state at the time of failure to produce a diagnosis. Args: job_id: The failed job's ID from ``job_history`` or ``job_status``. Returns a structured analysis with likely causes, observed symptoms, and recommended next steps.

Still pictures of any 3D file from multiple camera angles — the still door, not the 3D stage. FOR THE PERSON'S LOOK BEFORE A PRINT, OPEN THE STAGE: ``show_on_stage(file_path)`` puts a file that already exists — a mesh, or the sliced print file — on Kiln's interactive 3D stage, which the print gate asks for first (``issue_preview_token(door="stage")``). These renders are for checking a model yourself. When the user is signed in the result also carries a browser stage link (``viewer_url``), the door for a host that draws no panel. INSPECTION-ONLY UNLESS THE STAGE DREW IT: the result's ``renderer`` says which look these pixels are. ``stage`` (the stage photographed) and ``stage_paint`` (the stage's look painted) are accepted by ``issue_preview_token(door="png")`` for print sign-off; a raw ``openscad`` render is not — it has no plate and none of the stage's lighting, and a person once approved the wrong colours from one. Use it to inspect, and sign off from the stage, the viewer link, or a stage still. Universal visualization tool that works with ANY 3D file — STL, 3MF, OBJ, or SCAD. Returns PNG images from 6 angles: isometric, front, right, top, bottom, and back. **Colored 3MF support:** Multicolor 3MF files (with per-face color groups from BambuStudio, PrusaSlicer, or procedural textures) are automatically rendered with per-face colors — no slicer needed to see what the multicolor print will look like. Colorless 3MF and STL/OBJ files render in uniform color via OpenSCAD as before. Dark models get an adaptive lighter background for visibility. Each view includes a ``quality_score`` and ``dark_material`` flag. Use this to check a model from all sides — after each change, and before printing. **When to use this vs other preview tools:** - ``show_on_stage`` — the interactive 3D stage on an existing file; what the person turns over before a print - ``visualize_model`` — still renders of any file,

Render 2-4 models side by side in a single comparison image. General-purpose visual diff tool — compare any 3D models at the same camera angle in one image. Each model is rendered individually then stitched together with labels. **Use cases:** - Texture or decoration variants (compare 3 pattern options) - Design iterations (before vs after) - Material color comparisons - Parameter sweeps (small / medium / large) Returns a single PNG image path that can be displayed inline. Supports 2-4 models per comparison. When 4 models are provided they are arranged in a 2x2 grid; otherwise a single row. Args: paths: 2-4 file paths (STL, 3MF, OBJ, or SCAD). labels: Custom labels for each model. Defaults to A, B, C, D. angle: Camera angle for all renders. One of ``isometric``, ``front``, ``right``, ``top``, ``bottom``, ``back``. width: Per-model image width in pixels (default 800). height: Per-model image height in pixels (default 600). colors: Optional hex color per model (e.g. ``["#F72323", "#2323F7"]``).

Get the feedback loop history for a generated model. Returns iteration data, whether the design was resolved, and which iteration produced the best result. Args: model_id: Model/job ID from a generation job.

List every parametric part Kiln can build, with full parameters. These are ready-made, print-verified FUNCTIONAL PARTS — brackets, bins, stands, cases, hooks, jigs, clamps, plumbing and garden parts — that render locally through OpenSCAD. They are FREE and need no AI provider or API key. Whenever a user wants a functional part to their own dimensions, check here before writing OpenSCAD from scratch. Each template includes: - Every parameter with its default, unit, and description - Pre-validated OpenSCAD (prints without supports) - Category and a one-line description of the job it does Prefer ``find_design_templates(use_case)`` when you know what the user is making — it searches this library by use case and ranks matches, instead of returning all of them. Then call ``generate_from_template(template_id, {...})`` to render a printable STL.

無需輸入參數。

Build a printable STL from a parametric part, to the user's dimensions. This is how Kiln makes a FUNCTIONAL PART without writing any OpenSCAD: pick a template, pass the dimensions the user gave you, and get a print-ready STL. It runs LOCALLY through OpenSCAD — free, no AI provider, no API key, and every template in the library is print-verified at its default, minimum, and maximum parameters. Reach for this the moment a user describes a functional part they need in specific sizes ("a bracket for a 200 mm shelf", "a bin that fits my 80 mm drawer", "a clip for an 8 mm cable"). Find the template with ``find_design_templates(use_case)``, read its parameters with ``get_design_template_info(id)`` or ``list_design_templates()``, then call this. Only PARAMETRIC PARTS work here. The design PATTERNS returned by ``find_design_templates`` with ``generatable: false`` (snap fits, living hinges, press fits) are guidance for OpenSCAD you write yourself — this tool rejects them. For AI-assisted parameter inference plus structural analysis, use ``smart_generate_from_template``. When the kiln-pro package is installed (Pro+ tier), the result MAY carry an ``intent`` block describing the geometric assertions the template parameters implied, and a sidecar ``<mesh>.intent.json`` is written next to the produced STL. Free / public installs see the result unchanged. When you pass a parameter that sizes a hole for real hardware (a screw or bolt hole, a bore, a dowel or pin hole, a magnet pocket), the result carries a ``fastener_advice`` block saying the part was built to your number and nothing sized it for a named fastener. Kiln raises that once per session across every tool that can raise it, so a later build may omit the block even though it qualifies. Read its ``agent_instruction`` before repeating any of it to the user. Args: brief_id: The saved goal's

List named objects on the build plate of a Bambu .gcode.3mf file. Parses the plate metadata embedded in .gcode.3mf files exported by Bambu Studio or OrcaSlicer. Returns every object that was on the plate when the file was sliced, with its name, bounding box, area, and layer height. Works even when the 3MF contains NO mesh geometry (common for .gcode.3mf exports). Bambu Studio supports multiple plates (plate_1, plate_2, etc.). Use ``plate_number`` to select which plate to inspect. The response includes a ``plates_available`` field listing all plate numbers found in the archive. Use this to discover which parts are in a multi-object file before calling ``extract_plate_object`` to isolate one — or, if a part fails mid-print, to get its ``label_id`` for ``skip_print_objects`` so you can abandon just that object and save the rest of the plate. :param file_path: Path to the .3mf or .gcode.3mf file. :param plate_number: Which plate to inspect (1-based, default 1). :returns: Dict with ``objects`` list (each with a ``label_id`` that ``skip_print_objects`` consumes), plate metadata (bed type, filament colours, nozzle diameter, sequential print flag), and ``plates_available``.

Extract a single object's G-code from a multi-object Bambu .gcode.3mf. When a .gcode.3mf contains multiple objects (e.g. a lid and a body), this tool extracts ONLY the G-code for the requested object, producing a standalone .gcode file that can be printed directly. The machine start-up (homing, levelling, heating) and end (cool-down, park) sequences are preserved. Only the per-layer toolpath sections for other objects are removed. Bambu Studio supports multiple plates (plate_1, plate_2, etc.). Use ``plate_number`` to select which plate to extract from. Object matching is case-insensitive and supports partial names: ``"cap"`` will match ``"TreatHolder - cap.stl"``. Use ``list_plate_objects`` first to see available object names. :param file_path: Path to the .gcode.3mf file. :param object_name: Name (or partial name) of the object to extract. :param output_dir: Directory for the output .gcode file. Defaults to the same directory as the input file. :param plate_number: Which plate to extract from (1-based, default 1). :returns: Dict with output path, matched object info, and line counts.

Extract a single object from a multi-object .gcode.3mf and print it. This is a compound workflow tool that performs the complete pipeline in one call: 1. **Extract** the requested object's G-code (``extract_plate_object``) 2. **Upload** the extracted G-code to the printer (``upload_file``) 3. **Preflight + Start** the print (``start_print``, which runs its own preflight safety check) Bambu Studio supports multiple plates (plate_1, plate_2, etc.). Use ``plate_number`` to select which plate to extract and print from. Object matching is case-insensitive and supports partial names: ``"cap"`` matches ``"TreatHolder - cap.stl"``. Use ``list_plate_objects`` first if you want to preview what's available before committing to a print. :param file_path: Path to the .gcode.3mf file. :param object_name: Name (or partial name) of the object to print. :param use_ams: AMS mode — ``"auto"``, ``"true"``, or ``"false"``. :param ams_mapping: The tray per extruder by the printer's tray id (e.g. ``[0]`` for slot A1, ``[5]`` for B2; see ``ams_status``). :param bed_leveling: Run bed leveling before print. :param flow_cali: Run flow calibration before print. :param vibration_cali: Run vibration calibration before print. :param bed_type: Bed surface type (Bambu only): ``"auto"``, ``"textured_plate"``, ``"hot_plate"`` (smooth PEI), ``"cool_plate"``, ``"eng_plate"`` or ``"supertack_plate"``. :param plate_number: Which plate to extract from (1-based, default 1). :param printer_name: Which printer to print on. Omit for the default printer. Both steps are aimed at it, so the object is uploaded to and started on the same machine. :returns: Dict with extraction info and print start status. :param preview_token: Token from ``issue_preview_token`` proving the object was shown to the person before printing. Required beside their go-ahead: a

Identify where a model file came from. A file Kiln downloaded from a marketplace or a generator answers from the note Kiln left beside it, in any format (``came_from`` says it in a sentence). Otherwise a .3mf or .gcode.3mf answers from its embedded metadata: MakerWorld metadata and generic 3MF metadata (Title, Designer, Application, License, etc.). Returns the model title, designer, model URL (if available), slicer application name, and a list of objects on the plate. Use this when you need to trace a file back to its source — for example, to find the original STL files on MakerWorld when the .gcode.3mf only contains pre-sliced G-code without mesh geometry. :param file_path: Path to the .3mf or .gcode.3mf file. :returns: Dict with source marketplace, model URL, designer info, and plate object names.

Validate OpenSCAD code without generating geometry. Compiles the code and returns structured error/warning information with line numbers. Use this to check code before calling generate_model with OpenSCAD. :param scad_code: OpenSCAD source code to validate — the same parameter name ``compile_scad`` / ``analyze_scad_code`` / ``tweak_and_compile_scad`` take, so a session that has been compiling can validate without learning a second spelling. :param code: Alias of ``scad_code`` kept for callers that learned it. :returns: Dict with ``valid``, ``errors``, and ``warnings``.

Predict common 3D printing failure modes from mesh geometry. Analyzes the mesh for thin walls, long unsupported bridges, severe overhangs, top-heavy geometry, small features, and non-manifold issues. Returns a risk score (0-100) and per-failure details with fix suggestions. The thin-wall floor follows the nozzle: two lines of it, so 0.8 mm for a 0.4 mm nozzle and 1.2 mm for a 0.6. The answer says which nozzle it was judged for and where that size came from. :param file_path: Path to mesh file (.stl, .obj, .glb, or .3mf). :param min_wall_mm: Minimum printable wall thickness. Leave it out to use two lines of the nozzle. :param max_bridge_mm: Maximum unsupported bridge length (default 15). :param max_overhang_deg: Maximum overhang angle before failure (default 55). :param printer_id: The printer the part is for. Left out, the only printer Kiln knows of stands in. :param nozzle_mm: The nozzle fitted, when you know it. Left out, the nozzle on record for the printer, then the printer's own setting, then its stock size. :returns: Dict with verdict, risk score, failure list, the wall floor used and the nozzle it was judged for.

Search the template library by natural-language description. Fuzzy keyword matching against template IDs, descriptions, categories, and tags. Returns scored matches ranked by relevance. :param query: Natural-language search string (e.g. "phone stand", "hook"). :param max_results: Maximum number of results (default 10). :param category_filter: Optional category to limit results (e.g. "hardware"). :returns: Dict with matches list, each containing template_id, score, description, and category.

End-to-end pipeline: description → template → STL → analysis → GCode. One-call pipeline that: 1. Searches templates for best match 2. Generates STL via OpenSCAD 3. Runs structural risk analysis 4. Estimates weight 5. Slices to G-code (if slicer available) :param brief_id: The saved goal's id from ``design_session``, so this make is recorded against the goal and checked against it. Empty when there is no goal. :param description: Natural-language design description. :param output_dir: Directory for output files (uses tempdir if empty). :param material: Material the slice is set for -- temperatures, melt rate and cooling -- and weighed as. :param printer_model: Printer model for slicer profile lookup. :param infill_percent: Infill percentage for weight estimation. :returns: Dict with paths to SCAD, STL, G-code files, weight, risks. :param placement: Where the part goes when the plate still holds the last print: ``[x, y]`` in mm, a named region (``"front-left"``, ``"centre"``, …) or ``"keep"``. Omitted, an occupied plate refuses at the slice step and lists the spots that would work. INLINE 3D STAGE: on success this tool opens Kiln's interactive 3D stage — an inline viewer panel the user can orbit, zoom, and turn over — in hosts that render MCP Apps panels (Kiln's hosted connection attaches a browser stage link for hosts that don't). Oversized meshes are decimated automatically for the stage; the PNG preview is the floor, not the whole experience. MAKE DOORS: `design_session`, Kiln's front door for making an object, is not installed here (signed in to Kiln it runs on Kiln's servers). On this install `compile_scad` IS the make → preview → iterate loop: make it, show the preview, iterate.

Merge multiple STL files into a single mesh (supports positional offsets). Use this when you need to position parts relative to each other. For simple concatenation without positioning, ``merge_mesh_files`` also works. Combines triangle data from multiple STL files into one output file. Optionally translates each part to a specified position before merging. :param file_paths: JSON array of STL file paths. :param output_path: Where to write the merged STL. :param positions: Optional JSON array of {"x", "y", "z"} offsets per file. :returns: Dict with output_path, total_triangles, bounding_box. INLINE 3D STAGE: on success this tool opens Kiln's interactive 3D stage — an inline viewer panel the user can orbit, zoom, and turn over — in hosts that render MCP Apps panels (Kiln's hosted connection attaches a browser stage link for hosts that don't). Oversized meshes are decimated automatically for the stage; the PNG preview is the floor, not the whole experience.

Compose a multi-color / multi-material .3mf from multiple STL files. Creates a **single .3mf, ready to slice**, containing all parts with per-part AMS/extruder slot assignments. This is the correct way to hand a multi-color design to a slicer — it receives one file, not multiple. It is a model, not a sliced plate, so no printer starts it as it stands: slice it first. ``fits_bed`` says whether the plate fits the bed it was composed for; when it does not, the message says by how much and what to do, and does not offer it for printing. Parts whose bodies touch or overlap are one print: they become ONE object with a part per input, and where two overlap the smaller part is printed. Parts placed apart stay separate objects. Compatible with: * **BambuStudio / OrcaSlicer / Bambu A1, X1, P1 + AMS** — read ``Metadata/model_settings.config`` * **PrusaSlicer / MMU** — reads ``Metadata/Slic3r_PE_model.config`` * **Cura** and any 3MF-capable slicer Typical two-color workflow:: # 1. Export body STL (main color, e.g. grey PLA) # 2. Export accent STL (second color, same coordinate origin) # 3. Compose: result = compose_multicolor_3mf(parts=[ {"stl_path": "/tmp/body.stl", "extruder": 1, "name": "body", "color": "#AAAAAA", "material": "PLA Grey"}, {"stl_path": "/tmp/qr_pads.stl", "extruder": 2, "name": "qr_code", "color": "#111111", "material": "PLA Black"}, ]) # 4. Slice and print (or slice_model to look at the slice first): slice_and_print(result["output_path"]) Args: parts: List of part dicts. Each dict requires: * ``stl_path`` (str) — absolute path to the STL for this part * ``extruder`` (int) — 1-indexed AMS slot (1 = AMS tray 1 on Bambu); omitted, 1 Optional per-part keys: * ``name`` (str) — label shown in the slicer object

Get recent print history with success/failure tracking. Args: printer_name: Filter by printer name, or all printers if omitted. status: Filter by status (``"completed"`` or ``"failed"``). limit: Maximum records to return (default 20). The response declares its own SCOPE. These are the prints THIS machine recorded — another computer running Kiln keeps its own history — and ``scope.local.total_records`` gives the store's full matching count when ``limit`` truncated the page.

Get aggregate statistics for a printer: total prints, success rate, average duration. Args: printer_name: Name of the printer to get stats for.

Add notes to a completed print record (e.g., quality observations, issues). Args: job_id: The job ID of the print to annotate. notes: The annotation text to attach.

Export a safety profile as a shareable JSON object. Returns the full safety limits for a printer model in a format suitable for sharing with other users. Looks up community profiles first, then falls back to bundled profiles. Args: printer_model: Printer model identifier (e.g. ``"ender3"``, ``"bambu_x1c"``).

Get printer-specific slicer settings for a material you have already chosen. Use AFTER selecting a material — returns hotend/bed temps, fan speed, and tips tuned to a specific printer model. For help choosing which material to use, see ``recommend_material`` or ``recommend_design_material``. Args: printer_id: Printer model identifier. material: Material name (e.g. ``"PLA"``, ``"PETG"``, ``"ABS"``, ``"TPU"``).

Diagnose a printer issue by searching the known failure modes database. Describe the symptom (e.g. ``"under-extrusion"``, ``"layer shifting"``, ``"stringing"``) and get possible causes and fixes specific to your printer model. On Bambu Lab printers you can also pass ``hms_code`` — the HMS error code the printer's screen or app shows (e.g. ``"0300_1A00_0002_0001"``, in any separator or case). The response echoes the normalized code and a link to Bambu's HMS wiki page for it. With Kiln Pro the response also carries a decoded cause, fix, and severity for the code. Two things in ``symptom`` are read as exact signals rather than as words, and both narrow the answer sharply, so say them if you know them: * a fault code anywhere in the text (``"1200-8007"``, ``"12008007"``); * which step of a load/unload wizard failed (``"fails at step 5"``). Every code the call names -- in ``hms_code`` or anywhere in ``symptom``, so two codes read off ``printer_status`` fit in one call -- is read through the same reader ``printer_status`` uses and returned under ``fault_readings`` (code, namespace, reading, and the fix when Kiln has one). When the printer's playbook carries none of the codes named, the response says so in ``codes_without_a_playbook`` rather than answering the codes with word matches alone. A step number is the most useful sentence a user can offer about a load failure: the response's ``load_step_reading`` says whether that step is upstream of the melt zone, which rules a nozzle clog in or out before anyone unscrews anything. Args: printer_id: Printer model identifier. symptom: Description of the problem. Optional when ``hms_code`` is given. hms_code: Optional Bambu HMS error code to look up.

Full print pipeline: validate + slice + safety-check + upload + print (recommended one-shot tool). Preferred over ``slice_and_print`` — adds mesh-level pre-print validation, G-code safety validation, and auto-detected bundled slicer profiles. For custom slicer parameter overrides, use ``run_reslice_and_print`` instead. The full quick-print pipeline: 1. Validate mesh (printability, manifold, walls, bridges, bed-fit) 2. Resolve slicer profile (bundled, by printer_id) 3. Slice the (possibly auto-repaired) mesh to G-code 4. Safety-validate the G-code against printer limits 5. Upload G-code to the printer 6. Run preflight checks (always — cannot be skipped) 7. Start printing Args: model_path: Path to input model (STL, 3MF, STEP, OBJ). printer_name: Registered printer name in fleet. printer_id: Printer model ID for auto-profile selection (e.g. ``"ender3"``, ``"bambu_x1c"``, ``"klipper_generic"``). profile_path: Explicit slicer profile. Overrides printer_id auto-selection. material: Filament material (e.g. ``"PLA"``). It sets the slice's temperatures, melt rate and cooling, its density weighs the print (omitted: the spool the printer reports loaded, then PLA — the slice step says which), and AMS auto-routing prefers a loaded tray whose type matches. use_ams: AMS feeding mode (Bambu): ``"auto"`` (default — detect and route to a loaded tray), ``"true"``, or ``"false"``. ams_mapping: Explicit AMS slot mapping as a JSON array string, e.g. ``"[0]"`` or ``"[0, 2]"``. Overrides auto-selection. skip_validation: Bypass the mesh-level pre-print validation step. Defaults to False — designs are pre-tested for printability before they reach the printer. Use True for already-validated inputs or pre-sliced 3MFs the validator can't introspect. pr

Reslice with custom slicer overrides + print (use for retries with adjusted settings). Use this when you need to tweak slicer parameters (speed, brim, infill, temps). For standard prints without overrides, use ``run_quick_print`` instead. One-shot pipeline: validate mesh → resolve profile with overrides → slice → safety check → upload to printer → start print. The overrides parameter is a JSON string of PrusaSlicer INI key-value pairs: {"brim_width": "8", "perimeter_speed": "30", "fill_density": "25%"} Common override keys: Adhesion: brim_width (mm), skirts (count) Temperature: temperature, bed_temperature (degrees C) Speed: perimeter_speed, infill_speed, first_layer_speed (mm/s) Structure: fill_density (%), fill_pattern, layer_height (mm) Support: support_material (0/1) Requires PrusaSlicer or OrcaSlicer installed locally. The printer must be idle and connected. Args: model_path: Path to input model (STL, 3MF, STEP, OBJ). printer_name: Registered printer name in fleet. printer_id: Printer model ID for auto-profile selection (e.g. ``"ender3"``, ``"bambu_x1c"``, ``"klipper_generic"``). overrides: JSON string of PrusaSlicer INI key-value pairs to override. profile_path: Explicit slicer profile. Overrides printer_id auto-selection. slicer_path: Explicit path to the slicer binary. material: Filament material (e.g. ``"PLA"``). It sets the slice's temperatures, melt rate and cooling -- a setting you also pass in ``overrides`` stays yours -- and its density weighs the print (omitted: the spool the printer reports loaded, then PLA — the slice step says which). For fully-auto raw-gcode reslices, AMS routing prefers a loaded tray of this material. (3MF plates carry their own filament map, so routing defers to the adapter there.) use_ams: Ena

Print multiple copies of a model arranged on one build plate. Automatically arranges copies in a grid with spacing so they don't overlap, slices the plate as a single job, and prints. Uses PrusaSlicer's ``--duplicate`` flag when available (handles placement, collision avoidance, and travel optimization). Falls back to STL mesh duplication for OrcaSlicer or when fine control is needed. Copies that do not all fit the bed are refused, saying so, never sliced short. With ``fill=True`` (an STL, 1 to 50 copies) Kiln places as many copies as fit on the plate as it stands, up to ``copies``, beside anything already there, and never refuses because fewer fit: the result says how many it placed (``copies_placed``). The copies that did not fit are queued on the same printer (``queued_job_id``) and print as the next plate once this one is taken off and the plate is said to be clear, plate after plate until all are done; ``cancel_queued_job`` stops the rest. How many fit is answered on every tier; placing copies beside a part still on the plate is a kiln-pro feature. Requires a slicer (PrusaSlicer or OrcaSlicer) installed locally. The printer must be idle and connected. Args: model_path: Path to input model (STL, OBJ). copies: Number of copies to print (2-20; with ``fill``, at most this many, 1-50). printer_name: Registered printer name in fleet. printer_id: Printer model ID for auto-profile selection. spacing_mm: Gap between copies in mm (default 10). overrides: JSON string of slicer parameter overrides. slicer_path: Explicit path to the slicer binary. fill: Place as many copies as fit on the plate as it stands. preview_token: Token from ``issue_preview_token`` proving this model was shown to the person before printing. Required beside their go-ahead: a print is shown to its owner before it st

Full calibration pipeline: home + bed level + printer-specific guidance (recommended). Higher-level than ``calibrate_direct`` — orchestrates the full sequence and returns intelligence-based calibration tips. Performs physical calibration steps (homing, auto bed leveling) and returns printer-specific calibration guidance from the intelligence database. Args: printer_name: Registered printer name. printer_id: Printer model ID for calibration guidance.

Prepare a benchmark print: validate → slice → upload → report stats. Slices a model with the printer's profile and uploads it, then reports printer stats from history. The print is NOT started automatically — benchmarks should be manually observed. Args: model_path: Path to benchmark model (STL). printer_name: Registered printer name. printer_id: Printer model ID for profile selection. profile_path: Explicit slicer profile path. skip_validation: Bypass the pre-print mesh validation step. Defaults to False — user-supplied benchmark meshes are pre-tested for printability. Set to True for known-good fixed reference benchmark models.

Find substitute filament materials when your preferred material is unavailable (returns ranked list). Checks a built-in knowledge base of FDM filament compatibility and returns ranked alternatives with trade-off descriptions. For a single best match, use ``get_best_material_substitute`` instead. Args: material: The original filament material (e.g. "PLA", "PETG", "ABS"). reason: Optional filter — only return substitutions matching this reason (unavailable, cost, strength, finish_quality, heat_resistance, lead_time). min_score: Minimum compatibility score threshold (0.0–1.0).

Get the single best substitute for a filament material (quick shortcut). Returns one top-ranked alternative. For a full ranked list with trade-off details and filtering, use ``find_material_substitute`` instead. Args: material: The original filament material (e.g. "PLA", "PETG").

Get a material's public safety and printing-property profile. Returns the public thermal, chemical-safety, and process-design floor. Deeper engineering questions are answered one at a time by Kiln's servers. Args: material_id: Material key (e.g. ``"petg"``, ``"tpu"``, ``"cf_pla"``). Case-insensitive.

Check if a printer supports one specific material. Returns compatibility status (``"compatible"`` or ``"needs_upgrade"``), required hardware upgrades (enclosure, hardened nozzle, dry box, etc.), and material-specific notes for the printer. **See also:** ``check_printer_material_compatibility`` for the same check with design-intelligence context and alternative suggestions. Args: printer_id: Printer model identifier (e.g. ``"bambu_a1"``, ``"ender3"``, ``"prusa_mk4"``). material_id: Material to check (e.g. ``"petg"``). Required; an empty value is refused.

Compare two materials using a fixed public safety/process field set. Use this when deciding between materials for a project (e.g. PLA vs PETG for an outdoor bracket) or when switching materials for a reprint. Deeper engineering trade-offs are answered one question at a time by Kiln's servers. Args: material_a: First material (e.g. ``"pla"``). material_b: Second material (e.g. ``"petg"``).

The slicer settings a material gets on a printer: temperatures, melt rate, cooling. Every slicing door applies these itself when it is told the material -- ``material=`` on ``slice_model``, ``slice_and_print``, ``reslice_with_overrides``, ``run_quick_print``, ``run_reslice_and_print`` and ``kiln slice`` -- so naming the material is all a slice needs. This tool shows what that will be and why, from the same resolver (:mod:`kiln.slicer_material`): a product's own figures when you name one (``"bambu_tpu_95a"``), else Kiln's settings for the material on this printer, else the middle of the material's range, never above what the printer is rated for. The melt-rate ceiling (``filament_max_volumetric_speed``) slows every feature of the print to suit the material, the outer wall and the first layer included. Its ``overrides`` can still be passed to ``reslice_with_overrides`` to pin them; a setting passed that way is the caller's, and a slice leaves it alone. Example:: build_material_overrides("tpu", "bambu_a1") # overrides: temperature 225, bed_temperature 50, max_fan_speed 50, ... Args: material_id: Material (``"petg"``, ``"tpu"``, ``"PA-CF"``) or a product (``"bambu_tpu_95a"``). printer_id: Printer model, for its own settings and limits. Omitted, the material's own.

Reprint a model with a different material — the slice is set for it. One-shot convenience tool: reslices the model for the new material (its temperatures, melt rate and cooling, from the same resolver every slice uses -- see ``build_material_overrides``), merges any extra overrides you provide, runs a safety check, uploads to the printer, and starts the print. The file is labelled and weighed as the new material. Use this when you want to reprint an existing model in a different material (e.g. PLA → PETG for outdoor durability, or PLA → TPU for flexibility). The tool handles all the slicer parameter changes automatically. Example: "Reprint my grip extension in PETG instead of PLA":: reprint_with_material( file_path="/path/to/grip_extension.stl", material_id="petg", printer_name="my_bambu", printer_id="bambu_a1", use_ams=True, ams_mapping="[1]", # PETG is in slot A2 (tray id 1) ) Requires PrusaSlicer or OrcaSlicer installed locally. Args: file_path: Path to the model file (STL, 3MF, STEP, OBJ). material_id: Target material (e.g. ``"petg"``, ``"tpu"``). printer_name: Registered printer name in fleet. If omitted, uses the default printer. printer_id: Printer model ID for profile selection (e.g. ``"bambu_a1"``, ``"ender3"``). extra_overrides: Optional JSON string of additional slicer overrides to merge on top of the material defaults (e.g. ``'{"fill_density": "30%"}'``). use_ams: Enable AMS filament feeding (Bambu printers). ams_mapping: JSON string of AMS slot indices (e.g. ``"[1]"``). Maps each extruder/filament to an AMS tray position. preview_token: Token from ``issue_preview_token`` proving this model was shown to the person before printing. Required beside their go-ahead: a pr

Smart one-shot material-switch reprint — finds the model, detects the right AMS slot, adjusts slicer settings, and prints. This is the highest-level reprinting tool. Give it a file name (or partial name) and a target material, and it handles everything: 1. **Find the model**: Searches print history for the file name, then searches common local directories for the source STL/3MF/STEP file. 2. **Check AMS**: Reads AMS tray status to find which slot has the target material loaded. Auto-selects the matching slot. 3. **Build overrides**: Generates material-specific slicer overrides (temperature, speed, retraction) for the target material. 4. **Reslice + print**: Reslices the model with new settings and starts the print with the correct AMS mapping. Example: "Reprint my grip extension in PETG":: smart_reprint( file_name="grip_extension", material_id="petg", printer_name="my_bambu", printer_id="bambu_a1", ) The tool will find ``grip_extension.stl`` on disk, detect that PETG is loaded in AMS slot 1, adjust temps/speeds for PETG, reslice, and start printing — all in one call. Saved-goal carry-forward: when the source model on disk has a ``<file>.intent.json`` sidecar tagged with a saved goal, that goal's id is auto-recovered and surfaced as ``brief_id`` in the result so downstream ``record_print_outcome`` correctly links the reprint back to the goal. Pass ``brief_id="..."`` explicitly to override the sidecar derivation (rare — useful for one-off re-attributions). Args: file_name: Full or partial file name to search for (e.g. ``"grip_extension"`` or ``"grip_extension.stl"``). Searched in print history first, then in local directories. material_id: Target material (e.g. ``"petg"``, ``"tpu"``). printer_name: Registered printer name in fleet. printer_i

Print multiple objects in different materials/colors on one build plate. **Only a printer Kiln drives can make this print** — today a Bambu with an AMS. At any other printer (a Klipper MMU Kiln can read but not route, or a single-feed machine) a multi-filament plate is REFUSED before slicing with code ``MULTI_MATERIAL_NOT_DRIVEN``: the objects would all come out in one filament. The refusal carries what Kiln saw on the printer (``multi_material``) and the composed file (``multi_material_3mf``), so the user can slice it in a slicer that drives their unit. A single-filament plate is never refused. Takes a JSON array of objects, each with a model file and material assignment. Builds a multi-material 3MF file with per-object filament assignments, slices it, auto-maps materials to AMS slots, and prints. This is how you print "object A in red PLA, object B in black PETG" in a single print job. Example: Print a bracket in PETG and a cover in PLA:: multi_material_print( objects_json='[ {"file_path": "/path/to/bracket.stl", "material_id": "petg"}, {"file_path": "/path/to/cover.stl", "material_id": "pla"} ]', printer_name="my_bambu", printer_id="bambu_a1", ) Each object in the JSON array supports: - ``file_path`` (required): Path to STL/OBJ/GLB mesh file. - ``material_id`` (required): Material identifier (e.g. ``"petg"``). - ``name`` (optional): Display name for the object. - ``color`` (optional): Hex color override (e.g. ``"#FF0000"``). - ``group`` (optional): Objects sharing a group index are placed coincident (for meshes that share one coordinate space, like a body and its inlay). By default every object is its own group and gets its own spot on the plate. The tool automatically: 1. Looks up each material's properties (temps, col

Merge separately-sliced gcode files into one multi-tool gcode. Uses a batched strategy that minimises tool changes for multi-color prints. Parts with overlapping Z ranges are printed in tool order within the overlap zone, then remaining layers continue above. This is the key step between slicing individual parts and wrapping as a Bambu 3MF. The merged gcode contains T0/T1/... tool change commands that ``wrap_gcode_as_3mf`` converts to M620/M621 AMS load sequences. **Precondition:** Parts must be **XY-disjoint** (non-overlapping footprints on the build plate). The batched merge prints each tool's layers independently in the overlap zone — overlapping XY regions will cause collisions. Args: parts: JSON array of part objects. Each must have: - ``gcode_path``: Path to the sliced ``.gcode`` file. - ``tool_index``: Tool number (0, 1, ...) for AMS mapping. - ``name``: Human-readable name (e.g. ``"body_grey"``). Example:: [ {"gcode_path": "/path/body.gcode", "tool_index": 0, "name": "body"}, {"gcode_path": "/path/qr.gcode", "tool_index": 1, "name": "qr_pads"} ] output_path: Output file path. Defaults to a temp directory. Returns a dict with ``output_path``, merge phases, layer count, and estimated print time.

Print multiple copies of the same model, each in a different AMS color. **Only a printer Kiln drives can make this print** — today a Bambu with an AMS. At any other printer the copies are REFUSED before slicing with code ``MULTI_MATERIAL_NOT_DRIVEN`` (every copy would print in one colour; the slot map below is a Bambu instruction). The refusal carries what Kiln saw on the printer (``multi_material``) and the composed plate (``multi_material_3mf``) for slicing elsewhere. Takes a single model file and produces a multi-color print where each copy uses a different AMS filament slot. Perfect for "print 4 lids in 4 different colors" workflows. **Auto-detect mode** (default): omit *copies*, *ams_slots*, and *colors* — the tool queries the AMS, finds all loaded trays matching *material*, and prints one copy per loaded tray. **Manual mode**: specify *ams_slots* (and optionally *colors*) to choose exactly which AMS trays to use and how many copies. Requires PrusaSlicer or OrcaSlicer installed locally. The printer must be idle and have an AMS with loaded filament. The emitted 3MF (``multi_color_3mf`` in the result) also opens in Bambu Studio, which keeps the per-copy colors but re-derives print settings itself — the result's ``slicer_note`` explains this; relay it to the user when handing over the file. :param model_path: Path to the model file (STL or OBJ). :param copies: Number of copies. Auto-detected from AMS if omitted. :param ams_slots: The tray each copy prints from, by the printer's own tray id (``unit * 4 + slot`` on a chained unit, the unit id on an AMS HT; ``ams_status`` lists each tray's ``tray_id``). E.g. ``[0, 1, 2, 3]`` for all 4 AMS Lite trays, ``[0, 5]`` for A1 and B2. :param colors: Hex color strings per copy for slicer preview. E.g. ``["#FF0000", "#00FF00", "#0000FF", "#FFFF00"]``. Auto-read from AMS if omitted.

Extract metadata from a 3D printing file (.gcode, .3mf, .stl, .ufp). Parses file headers for estimated print time, layer count, filament usage, dimensions, slicer info, and material hints — without re-slicing. A project saved from Bambu Studio, OrcaSlicer or PrusaSlicer also gives the printer, nozzle size, layer height and material it was set up for; hand the same file to ``set_printer_model`` to set a saved printer up from it. .. note:: For multi-object .gcode.3mf files, also consider using ``list_plate_objects()`` to see individual objects on the plate. Args: file_path: Path to the print file.

Save a checkpoint during an active print for accurate resume. The checkpoint is keyed by ``(printer_name, job_id)`` and read automatically by :func:`detect_print_failure` so that the resulting :class:`FailureReport` carries known-good Z / layer / temps. The resume planner uses this for accurate ``resume_z_mm`` instead of estimating from ``z_per_layer * resume_layer`` — meaningfully more accurate when the print uses variable-layer-height slicing. Args: printer_name: Name of the printer running the job. job_id: Unique job identifier. z_height: Current Z height in mm. layer_number: Current layer number (0-based). hotend_temp: Hotend temperature at checkpoint time (Celsius). bed_temp: Bed temperature at checkpoint time (Celsius). filament_used_mm: Filament consumed so far in mm. fan_speed_pct: Part-cooling fan speed (0-100); omitted, 0. flow_rate_pct: Flow-rate multiplier in percent; omitted, 100.

Plan a recovery strategy from a printer + job + failure type. Convenience wrapper that synthesizes a :class:`FailureReport` from the supplied args (using the latest checkpoint for the printer/job when available) and runs it through the same planner used by ``plan_failure_recovery``. **Which recovery tool to use:** - Have a printer_name + job_id from a failed print? → ``plan_print_recovery`` (this tool) - Have a failure_id from ``detect_print_failure``? → ``plan_failure_recovery`` Args: printer_name: Name of the printer that failed. job_id: The failed job's identifier. failure_type: Type of failure (thermal_runaway, layer_shift, adhesion_failure, filament_runout, nozzle_clog, communication_loss, power_loss, blob_detected, spaghetti, stringing, warping). Defaults to ``communication_loss``. part_attached: Your word on whether the half-printed part is still stuck to the plate (true / false). Left out, a resume Kiln would build is held back and the plan says so. try_untested_resume: Opt this printer in to a resume Kiln has not yet seen work on its model; Kiln learns from how it goes.

Execute firmware-level print resume for OctoPrint+Marlin printers. After a power loss or failure, this tool positions the printer at the last known checkpoint and prepares it to resume printing. Uses Marlin M413 power-loss recovery protocol: homes X/Y (never Z), re-heats bed then hotend, sets Z position from checkpoint, primes the nozzle, and restores fan/flow settings. A Kiln Pro feature. Without it, the printer's own power-loss recovery can continue a print run from its own memory card; a print OctoPrint streamed over USB cannot be continued by the printer itself. The printer will be positioned and ready after this call. Use start_print with a re-sliced file (starting at the target layer) or let the printer resume from its own recovery buffer. Only works with OctoPrint printers running Marlin firmware. Moonraker/Klipper printers should use Klipper's SAVE_VARIABLE system instead (not yet supported). Args: printer_name: Name of the printer to resume on. job_id: The failed job's identifier (for checkpoint lookup). z_height_mm: Z height to resume from (from checkpoint). hotend_temp_c: Hotend temperature to restore. bed_temp_c: Bed temperature to restore. file_name: Original file name (for logging/tracking). layer_number: Layer number to resume from (informational). fan_speed_pct: Fan speed to restore (0-100). flow_rate_pct: Flow rate multiplier to restore (default 100). prime_length_mm: Filament to extrude for nozzle priming (mm). z_clearance_mm: How far above the part to raise the nozzle (mm).

Run a comprehensive health check on a printer. Monitors hotend/bed temperature stability, print progress, and detects anomalies like temperature drift or unexpected shutdowns. Args: printer_name: Name of the printer to check.

Start continuous background health monitoring for a printer. Runs periodic checks covering connectivity, temperature stability, print job health (layer progress stalls, error codes), and active error detection. Alerts are generated when anomalies are found. Kiln keeps a live watch on as many machines at once as your plan runs — one on Free and Pro. Checking a printer yourself is not a watch and is never limited: ``printer_status``, ``monitor_print`` and ``printer_snapshot`` answer for any machine at any tier, and so does stopping one. :param printer_name: Printer to monitor. :param interval_seconds: Seconds between health checks (default 30). See also: ``stop_printer_health_monitoring()``, ``check_printer_health()``, ``printer_status()``.

Stop background health monitoring for a printer. Cancels the periodic health-check loop started by ``start_printer_health_monitoring()``. Active alerts are cleared. Monitoring can be restarted at any time by calling ``start_printer_health_monitoring()`` again. :param printer_name: Printer to stop monitoring.

Analyze a webcam snapshot for print monitoring quality. Checks image brightness, variance, resolution, and format to determine if the snapshot is usable for print monitoring. Args: file_path: Path to the snapshot image file.

Read back the newest quote ``fulfillment_quote`` cached for a file. Quotes are kept for a while after they are fetched, so a decision made a few minutes later needs no second provider call. An expired quote is not returned; fetch a fresh one with ``fulfillment_quote``. Args: file_path: Path to the design file the quote was fetched for. provider: Provider name as it appears in a ``fulfillment_quote`` result (e.g. ``"craftcloud"``), used to find the cached quote. material: Material id the quote was fetched for (from ``fulfillment_materials``).

List persisted snapshots from the database. Returns metadata for snapshots captured during print monitoring, timelapses, or manual captures. Use this to review print history visually or correlate snapshots with print outcomes. Args: printer_name: Filter by printer name. job_id: Filter by job or timelapse ID. phase: Filter by capture phase as the monitor records it: ``"first_layers"``, ``"mid_print"``, ``"final_layers"`` or ``"unknown"``. limit: Maximum records to return (default 20).

Analyze local print history trends for a printer. Uses only data already stored in the local database — nothing leaves the machine. Returns health score, failure rate trends, duration trends, recurring failure modes, and material reliability. Args: printer_name: Printer to analyze. lookback_days: How far back to look (default 30 days).

Check if the printer's chamber temperature is safe for a material. Reads the current chamber temperature from the connected printer and checks it against material-specific thermal limits. Warns about conditions like: - Chamber too hot for PLA (softening risk) - Chamber too cold for ABS/ASA (warping risk) - Thermal runaway (exceeds printer safety profile max) - Cool-down advisory after a high-temp print All checks are local — no data leaves the machine. Args: material: Filament material type (e.g. "PLA", "ABS", "PETG"). If not provided, only checks against printer max.

Put any image, text, or pattern onto a 3D model surface. For repeating patterns (wood grain, camo, honeycomb) that tile across the entire surface, use ``apply_geometric_texture`` or ``apply_procedural_texture`` instead. This tool is for one-off content placement (logos, text, images). Takes a model and content (image file, text string, SVG) and returns a new STL with the content embossed or debossed onto the surface. Automatically detects the best face for placement and scales content to fit. Single-color coin-relief style — no multi-material needed. **Content types** (auto-detected from *content* string): - **Image file** (PNG/JPG/SVG): ``"/path/to/photo.jpg"`` - **Text**: ``"text:KILN"`` or ``"text:Hello World"`` **Image styles** for raster images: - "auto" — a logo/wordmark/line-art image routes to "stencil" (crisp traced strokes); a photo is sculpted and Kiln picks the look from the photo and the part, saying why in relief.chosen_because - "coin" — a sunk relief, the subject rising to the rim plane - "cameo" — the same relief raised on the face (emboss) - "etched" — edges first, for a small part - "sketch" — engraved contour lines, one layer deep (was "portrait") - "medallion" — a coin with a rim ring; "photo" and "composite" mean "coin" - "stencil" (alias "logo") — the mark's ink is traced into vector strokes and carved directly: crisp edges, no background tile, correct orientation. The right choice for brand logos. **Examples**:: decorate_surface(model_path="coaster.stl", content="photo.jpg", mode="deboss", depth_mm=1.5, image_style="coin") decorate_surface(model_path="keychain.stl", content="text:KILN", face="top", depth_mm=0.5) Requires OpenSCAD installed locally for compilation. :param model_path: Path to the base model (STL or OBJ). :param content: What to p

Detect geometric regions in a 3D model that affect slicing. Analyzes model geometry to identify overhangs, bridges, thin walls, top/bottom surfaces, fine details, and curved surfaces. Each region gets optimized slicing parameters in the adaptive plan. Args: model_path: Path to an STL or 3MF file for analysis. model_stats: Pre-computed geometry statistics dict (from slicer preview or external tool). Keys include ``height_mm``, ``overhangs``, ``bridges``, ``thin_walls``, etc. Provide either ``model_path`` or ``model_stats`` (or both — ``model_stats`` takes precedence).

Get material-specific slicing constraints for adaptive slicing. Returns layer height limits, bridge/overhang parameters, fan speeds, and other material-tuned values used by the adaptive slicer. Args: material: Material name — PLA, PETG, ABS, TPU, ASA, Nylon, PC, PVA, or HIPS. nozzle_diameter_mm: Nozzle diameter in mm (affects layer height limits). Leave unset for the only printer Kiln knows of, else 0.4; the reply's ``nozzle`` says which.

Generate a per-layer adaptive slicing plan. Creates a layer-by-layer plan with variable heights, speeds, and cooling based on detected geometry regions and material constraints. Args: regions: List of region dicts (as ``analyze_model_geometry`` returns them): ``region_type`` (one of fine_detail, standard, bulk, overhang, bridge, top_surface, bottom_surface, thin_wall, curved_surface, support_contact), ``z_start_mm``, ``z_end_mm`` and ``area_pct``. material: Material name (PLA, PETG, ABS, etc.). model_height_mm: Total model height in mm. model_name: Optional model name for record keeping. printer: Optional printer identifier. nozzle_diameter_mm: Nozzle diameter in mm. Leave unset for the nozzle Kiln has for ``printer`` (or the only printer it knows of), else 0.4; the reply's ``nozzle`` says which. mode: Adaptive strategy — "balanced" (default), "quality_first", "speed_first", or "material_optimized".

Export an adaptive slicing plan as slicer-compatible configuration. Converts a plan to the target slicer's format — PrusaSlicer and OrcaSlicer use variable layer height data, Cura uses adaptive layers plugin format. Args: plan_data: Plan dict from ``generate_adaptive_slicing_plan``. slicer: Target slicer — "prusaslicer", "orcaslicer", "cura", or "generic".

Compare adaptive plan time savings vs uniform layer height. Shows layer count reduction, estimated time savings, and percentage improvement. Args: plan_data: Plan dict from ``generate_adaptive_slicing_plan``. uniform_height_mm: Reference uniform layer height for comparison (default 0.2mm).

All-in-one adaptive slicing: analyze geometry + generate plan. Convenience tool that combines geometry analysis and plan generation in a single call. Ideal when you have basic model info and want a quick adaptive plan without multiple tool calls. Args: material: Material name (PLA, PETG, ABS, etc.). model_height_mm: Total model height in mm. model_name: Optional model name. nozzle_diameter_mm: Nozzle diameter in mm. Leave unset for the nozzle Kiln has for ``printer`` (or the only printer it knows of), else 0.4; the reply's ``nozzle`` says which. mode: Adaptive strategy — "balanced", "quality_first", "speed_first", or "material_optimized". printer: Optional printer identifier. regions: Optional list of region dicts. If omitted, a default STANDARD region spanning the full height is used.

List all materials with adaptive slicing profiles. Returns material names with their key slicing constraints (layer height limits, bridge parameters, overhang angles).

無需輸入參數。

Generate a human-readable summary of an adaptive slicing plan. Args: plan_data: Plan dict from ``generate_adaptive_slicing_plan`` or ``quick_adaptive_plan``. Returns a structured summary with key metrics and region breakdown.

Start or stop an AMS 2 Pro / AMS HT active dry cycle. Bambu printers with an AMS 2 Pro or AMS HT dry filament in place. This controls that dryer. To START (``mode=1``): set ``temp_c`` (drying temperature), ``duration_min`` (> 0), and ``cooling_temp_c`` -- which must be >= 45, or the printer silently ignores the command. A start is checked against the unit's own ceiling (AMS 2 Pro 65 C, AMS HT 85 C) before it is sent; when Kiln cannot run that check, nothing is sent and the answer says why. To STOP (``mode=0``): only ``ams_id`` is needed, and a stop is always sent. Only Bambu printers with an AMS 2 Pro / AMS HT support this; other printers and plain AMS / AMS Lite units return an error. :param ams_id: AMS unit index (0-based). :param mode: 1 to start drying, 0 to stop. :param duration_min: Dry-cycle length in minutes (> 0 to start). :param temp_c: Drying temperature in C (required to start). A value above the unit's own drying ceiling is refused, never lowered; the refusal names the ceiling. :param cooling_temp_c: Cooldown temperature in C (>= 45 to start). :param humidity: Target relative humidity in percent, when the unit supports a humidity target. :param rotate_tray: Whether the unit turns the spool during the cycle (``True``/``False``); leave unset to keep the unit's own setting. :param printer_name: Target printer. Omit for the default printer. :returns: Dict with the dispatched command and a status message.

Create a new empty assembly. Returns the assembly state as a JSON-serialisable dict that must be passed back to subsequent assembly tools. Args: name: Human-readable name for the assembly.

Add a part to an existing assembly. Parses the assembly from its JSON representation, appends the new part, and returns the updated assembly state. Args: assembly_json: JSON string of the current assembly state (as returned by create_assembly or a previous tool call). part_id: Unique identifier for this part within the assembly. file_path: Path to the STL/OBJ mesh file for the part. position_x: X position offset in mm (default 0.0). position_y: Y position offset in mm (default 0.0). position_z: Z position offset in mm (default 0.0). material: Filament material for the part (default ``"PLA"``). role: Structural role of the part (default ``"structural"``).

Add a mating interface between two parts in an assembly. Defines how two parts connect (joint type and clearance), which is used during validation and clearance checking. For screw/anchor-based joints, ``fastener`` may provide an explicit hardware spec so downstream manuals and BOM tools do not have to guess from clearance alone. Args: assembly_json: JSON string of the current assembly state. part_a_id: ID of the first part in the interface. part_b_id: ID of the second part in the interface. joint_type: Type of joint (default ``"clearance_fit"``). clearance_mm: Clearance gap in mm (default 0.2). For ``"interference_fit"`` pass a NEGATIVE value (the part is intentionally larger than its socket); interference geometry is the entire point. magnet_polarity_aligned: Only meaningful when ``joint_type == "magnetic"``. ``True`` declares the designer has confirmed which poles face each other in each magnet pocket; ``None`` means unknown. Downstream tooling refuses to ship a hand-wavy "make sure they pull together" instruction when polarity is unknown. fastener: Optional FastenerSpec as a dict or JSON object string. Supported keys include ``size``, ``family``, ``length_mm``, ``length_range_mm``, ``head_type``, ``drive_type``, ``surface_type``, ``quantity_per_interface``, and ``notes``.

Validate an assembly for correctness and printability. Runs clearance checks and joint validations on the assembly, returning the validated assembly state with results populated. Args: assembly_json: JSON string of the current assembly state. printer_id: Optional printer model id (e.g. ``"bambu_a1"``). With it, each joint that drives a screw into a printed part gains a ``screw_hole`` block (compensated hole diameter, thread engagement, install-torque ceiling, lead-in chamfer) tuned for that machine where Kiln has data, else a generic starting point. Omit it for the plain validation.

Check clearances between all mating parts in an assembly. Returns a list of clearance check results indicating whether each interface meets its clearance requirements. Args: assembly_json: JSON string of the current assembly state. default_clearance_mm: Default clearance gap in mm to use when an interface does not specify one (default 0.2).

Compose all assembly parts into a single output STL file. Merges the individual part meshes according to their positions and writes the combined model to ``output_path``. Args: assembly_json: JSON string of the current assembly state. output_path: File path where the composed STL will be written. INLINE 3D STAGE: on success this tool opens Kiln's interactive 3D stage — an inline viewer panel the user can orbit, zoom, and turn over — in hosts that render MCP Apps panels (Kiln's hosted connection attaches a browser stage link for hosts that don't). Oversized meshes are decimated automatically for the stage; the PNG preview is the floor, not the whole experience.

Get recommended clearance settings for a joint type and material pairing. Returns clearance recommendations based on the joint type and the materials of the two mating parts. When ``printer_id`` is supplied AND kiln-pro is installed, the response narrows the clearance range by the user's calibration tier (HIGH halves it, MEDIUM shaves ~10%, LOW and UNKNOWN leave it unchanged) and attaches a ``calibration_used`` block documenting the source. Args: joint_type: Type of joint (e.g. ``"clearance_fit"``, ``"press_fit"``, ``"snap_fit"``). material_a: Material of the first part (default ``"PLA"``). material_b: Material of the second part (default ``"PLA"``). printer_id: Optional printer identifier (e.g. ``"bambu_a1"``). For a joint whose parts MOVE, omitting it resolves the user's active printer rather than answering generically — pass it only to ask about a machine that is not the one they are set up on. For every other joint type, omitting it keeps the historic flat-range behaviour. mating: Optional shape hint for joints whose parts MOVE against each other (``"clearance_fit"``, ``"loose"``): ``"pin_in_bore"`` for a shaft or pin turning in a hole, ``"slot"`` for a tongue sliding in a groove, ``"planar_face"`` for two flat faces sliding, or ``"gear_flank"`` for meshing teeth. Omitted, the round-joint case is assumed, the reading that errs loose rather than tight. Ignored for joints that do not move.

Start a Kiln sign-in via OAuth. Returns a URL the user can open in their browser to sign in with Google / Apple / GitHub. Relay the ``verification_uri`` to the user and then call ``kiln_signin_poll(device_code)`` every few seconds until the status is no longer ``"pending"``. Response fields (all strings unless noted): * ``verification_uri`` — URL to open in the browser; the ``user_code`` is already embedded as a query param so the user typically doesn't have to type anything. * ``user_code`` — the short human-readable code (``KLN-ABCD-EFGH``); show it only as a fallback in case the verification URL didn't pre-fill it. * ``device_code`` — secret; pass to ``kiln_signin_poll``, never show to the user. * ``interval`` (int) — seconds to wait between polls (default 2). * ``expires_in`` (int) — seconds the code is valid for (900 = 15 minutes). A free Kiln account adds a cloud design library with share links plus the free monthly allowance of Kiln's hosted tools. Free tier — no license key required; this is the very first call an unauthenticated user makes.

無需輸入參數。

Check whether a sign-in started by ``kiln_signin`` is done. Call this repeatedly (every ``interval`` seconds) with the ``device_code`` that ``kiln_signin`` returned. Each call is a single HTTP round-trip (it does NOT block), so the agent stays responsive and the user sees progress. Returns ``{"status": "pending" | "success" | "denied" | "expired", ...}``. * ``pending`` — user hasn't finished in the browser yet; wait ``interval`` seconds and call again. * ``success`` — tokens have been written to ``~/.kiln/auth_tokens.json`` (mode 0600); the response also echoes ``email`` and ``tier``. Every other Kiln tool picks up the new session automatically. * ``denied`` — user cancelled in the browser. * ``expired`` — the device_code timed out (15 min window); call ``kiln_signin`` again for a fresh code. Free tier — no license key required. :param device_code: The ``device_code`` that ``kiln_signin`` returned for this sign-in.

Add a 3D model file to the local cache for reuse across jobs. Copies the file into ``~/.kiln/model_cache/`` and stores metadata (source, prompt, tags, dimensions) in the database. Duplicate files are detected automatically by SHA-256 hash. Args: file_path: Path to the model file on disk. source: Origin — ``"thingiverse"``, ``"myminifactory"``, ``"meshy"``, ``"openscad"``, ``"upload"``, etc. source_id: Marketplace thing ID or generation job ID. prompt: For generated models, the text prompt used. tags: Comma-separated tags (e.g. ``"benchy,calibration,test"``). dimensions: JSON object with bounding box in mm, e.g. ``'{"x": 60, "y": 31, "z": 48}'``. metadata: Optional JSON object with extra data.

Search the local model cache by name, source, tags, or prompt text. Args: query: Free-text search against file name, prompt, and tags. source: Filter by source (e.g. ``"thingiverse"``). tags: Comma-separated tags to filter by. limit: Maximum results (default 20). The response declares its ``scope``: this cache is local to this machine, so the count is what THIS install has cached, not everything the user has ever downloaded or generated.

Return details for a specific cached model. Args: cache_id: The unique cache ID of the model.

List all models in the local cache, newest first. Args: limit: Maximum results (default 50). offset: Number of entries to skip for pagination. The response declares its ``scope``: this cache is local to this machine, so the count is what THIS install has cached, not everything the user has ever downloaded or generated. It is also a page — ``limit``/``offset`` bound it further.

Remove a model from the local cache (file and metadata). Args: cache_id: The unique cache ID of the model to delete.

Cache a 3D design file for faster access and version tracking. Args: file_path: Path to the design file to cache. label: Human-readable label for the cached design. material: Intended material for this design.

List cached designs, optionally filtered by material. Args: material: Filter by material (e.g. "PLA", "PETG"). limit: Maximum number of results. Most recently used designs come first. The response declares its ``scope``: which store was read. The cache is local-only at every tier (regenerable files, no cloud copy), so a complete local read is the whole cache.

Retrieve a cached design by ID. Args: design_id: The cached design's identifier.

Get the current cloud sync status.

無需輸入參數。

Trigger an immediate cloud sync cycle.

無需輸入參數。

Configure and start cloud sync. Args: cloud_url: Base URL of the cloud sync endpoint. api_key: API key for authentication. interval: Sync interval in seconds (default 60).

Split a 3D model into horizontal color zones by Z-height. Divides the model's height into N equal bands. Faces that cross a band edge are cut exactly at it, so the line where two colors meet is the straight horizontal line the bands name — never a sawtooth of whole faces, on any tessellation. The cut faces are capped at the band planes, so each zone of a closed model is itself a closed solid ready to slice. Produces separate STL files per zone and (if available) a multicolor 3MF ready for AMS/MMU printers. Zero cloud dependencies — pure geometry. Says whether its colours are on the printer, as ``colour_availability`` (absent when Kiln cannot see what is loaded). Relay its ``say`` as written and add nothing about filament: never suggest buying filament unless the person asks for one or says yes to the offer in ``say``. On a yes, call ``find_closest_filaments`` with these colours and the print's material. :param input_path: Path to a binary STL file. :param num_colors: Number of color zones (default 4). :param color_palette: List of hex colors (e.g. ``["#FF0000", "#00FF00"]``). Defaults to white/red/black/grey. :param material: Optional material the part will be printed in (e.g. ``"PETG"``). A spool on record in a clearly different material is then not named as one to load. :param printer_id: Optional supported printer model id. Names the bed the composed 3MF is placed on, so a model sitting off the plate is centred on the machine's real bed rather than an assumed 256mm one. :returns: Dict with zone STL paths, hex colors, face counts (boundary faces are cut and capped, so counts can excee

Split a 3D model into color zones by geometric region. Supports multiple assignment methods: - ``"z_height"``: horizontal bands by Z-height (default) — faces crossing a band edge are cut exactly at it and the cuts are capped, so the color boundary is a straight line on any tessellation and each zone of a closed model is itself a closed solid ready to slice - ``"normal"``: group by face normal direction (top / bottom / sides) - ``"random"``: random face assignment for artistic prints The 3MF takes whichever form actually prints: z_height bands become one closed solid per color; normal/random colorings follow the surface, so the mesh stays ONE watertight object with the colors painted per triangle — slicers that support color import (BambuStudio, OrcaSlicer) offer to map each color to a filament on open. Zero cloud dependencies — pure geometry. Says whether its colours are on the printer, as ``colour_availability`` (absent when Kiln cannot see what is loaded). Relay its ``say`` as written and add nothing about filament: never suggest buying filament unless the person asks for one or says yes to the offer in ``say``. On a yes, call ``find_closest_filaments`` with these colours and the print's material. :param input_path: Path to a binary STL file. :param num_colors: Number of color zones (default 4). :param method: Assignment method — ``"z_height"``, ``"normal"``, or ``"random"``. :param color_palette: List of hex colors. Defaults to white/red/black/grey. :param material: Optional material the part will be printed in (e.g. ``"PETG"``). A spool on record in a

Paint exactly the faces a decoration carve created (Pro-free). A deboss/emboss records which output triangles it created — recess floors and side-walls — in a face-provenance sidecar beside the decorated mesh. This tool paints THOSE faces and nothing else, so a debossed logo with a closed outline (any mark with enclosed regions) colors only its carved strokes: the untouched surface island inside the outline stays the body color, where crease-angle segmentation would have "filled the logo in". Use after any decoration door (``decorate_surface``, ``apply_decoration``, ``apply_decoration_preset``, ``smart_decorate``, ``batch_decorate``…) — they all record the sidecar. For meshes with no sidecar (older files, hand-made carves), fall back to ``segment_mesh_regions`` + ``paint_mesh_regions``. Writes a painted 3MF (one watertight object, per-triangle colors) via the same composer ``paint_mesh_regions`` uses, so the output slices identically. A successful paint is also written back into the carve's face record (color, target, output file) so the design's provenance says "carved, then painted" — ``paint_recorded`` in the result reports whether that write-back landed. Says whether its colours are on the printer, as ``colour_availability`` (absent when Kiln cannot see what is loaded). Relay its ``say`` as written and add nothing about filament: never suggest buying filament unless the person asks for one or says yes to the offer in ``say``. On a yes, call ``find_closest_filaments`` with these colours and the print's material. :param model_path: The decorated mesh (STL/OBJ/3MF) whose ``<mesh>.decoration_faces.j

Preview the complete price breakdown — including tax — before placing an order. Terms §7 contract: "Preview the tax for any order with the ``tax_estimate`` tool before placing it. We display the full fee + tax breakdown before charging. No hidden fees." This tool fulfills that contract by returning the same line items the order will commit to at charge time. Per Terms §7 tax is computed on the orchestration fee ONLY — never on the manufacturer's quoted total. The manufacturer is responsible for any taxes on their own charges. Two calling shapes are supported: 1. **Canonical preview** (recommended): pass ``manufacturer_quote_usd`` and the tool returns the full breakdown — ``manufacturer_quote``, ``orchestration_fee``, ``tax_on_fee``, ``total`` — so the agent can show the user the exact line items that match the eventual charge. This is the shape Terms §7 commits to. 2. **Tax-only legacy** (compatibility): pass ``fee_amount`` with no ``manufacturer_quote_usd`` and the tool returns the older ``{tax: {...}}`` shape, useful for callers that already know the fee and only want the tax line. Args: fee_amount: Legacy — the platform fee amount (from the quote's ``kiln_fee``). Used only when ``manufacturer_quote_usd`` is omitted. jurisdiction: Where the buyer is located (e.g. ``"US-CA"``, ``"DE"``, ``"AU"``). Use ``tax_jurisdictions`` to see all supported codes. When empty in canonical-preview mode, no tax is applied (preview shows manuf + fee only). business_tax_id: If the buyer is a business, their tax ID

List all 22 supported regions so the agent can match the user's location. Returns jurisdiction codes, tax types, and rates for the US (8 states), EU (7 countries), UK, Canada (4 provinces), Australia, and Japan. Pass the matching code to ``fulfillment_order`` or ``tax_estimate`` to include tax in the price breakdown.

無需輸入參數。

Look up tax details for a specific region (rate, type, B2B exemptions). Args: code: Jurisdiction code (e.g. "US-CA", "DE", "GB", "AU"). Use ``tax_jurisdictions`` to browse all codes.

Get crypto wallet addresses to tip/donate to the Kiln project. Kiln is free, open-source software. This tool returns wallet addresses (with ENS/SNS domains) where users can send tips in SOL, ETH, USDC, or other tokens to support development. No payment is required -- Kiln is fully functional without donating.

無需輸入參數。

Get the guided onboarding workflow for users without a 3D printer. Returns a step-by-step guide covering model discovery/generation, material recommendations, pricing, ordering, and delivery tracking. Perfect for first-time users who want to manufacture a custom part.

無需輸入參數。

Validate and normalize a shipping address for fulfillment orders. Args: street: Street address (e.g. "123 Main St"). city: City name. country: ISO 3166-1 alpha-2 country code (e.g. "US", "GB", "DE"). state: State/province (recommended for US addresses). postal_code: ZIP/postal code (validated per country format). Checks required fields, validates postal codes per country (US ZIP, Canadian postal, UK postcode), and returns warnings for missing optional fields. Use the ``normalized`` address in the response when placing fulfillment orders.

Suggest a material when ordering a print from a fulfillment provider. Use this when routing a print job to a fulfillment provider and need to pick the right material + technology for the order. **Which material tool to use:** - Ordering a print from a service? → ``suggest_material_for_order`` (this tool) - Designing a part and need engineering specs? → ``recommend_design_material`` - Quick intent-based pick for your own printer? → ``recommend_material`` Args: use_case: What the part is for. Options: decorative, functional, mechanical, prototype, miniature, jewelry, enclosure, wearable, outdoor, food_safe. budget: Price preference: "budget", "mid", or "premium". Empty = any. need_weather_resistant: Only recommend weather-resistant materials. need_food_safe: Only recommend food-safe materials. need_high_detail: Prefer high-detail materials (SLA/MJF). need_high_strength: Prefer high-strength materials (SLS/MJF). Returns ranked material recommendations with technology, reasoning, price tier, and which fulfillment provider to use.

Get an instant price estimate before requesting a full quote. Args: technology: Manufacturing technology: FDM, SLA, SLS, MJF, or DMLS. volume_cm3: Part volume in cubic centimeters (if known). dimensions_x_mm: Bounding box X dimension in mm (alternative to volume). dimensions_y_mm: Bounding box Y dimension in mm. dimensions_z_mm: Bounding box Z dimension in mm. quantity: Number of copies (default 1). Returns a low/high price range based on typical per-cm3 pricing for the technology. For exact pricing, use ``fulfillment_quote`` with a real model file. Either ``volume_cm3`` or all three dimension parameters must be provided.

Estimate order-to-delivery timeline with per-stage breakdown. Args: technology: Manufacturing technology (FDM, SLA, SLS, MJF, DMLS). shipping_days: Known shipping days from a quote (optional). quantity: Number of copies (larger quantities add production time). country: Destination country code for shipping estimate fallback. Returns a stage-by-stage timeline (order confirmation, production, quality check, packaging, shipping) with estimated days per stage and a total delivery date.

List all countries supported for fulfillment shipping. Returns ISO country codes and full names for all 23+ countries where Kiln fulfillment providers can ship manufactured parts.

無需輸入參數。

Encrypt and store a credential (API key, webhook secret, etc.). The value is encrypted at rest using PBKDF2 + XOR stream encryption. Only metadata is returned — the plaintext is never exposed. Args: credential_type: Type of credential (api_key, webhook_secret, stripe_key, marketplace_token, printer_password). value: The plaintext secret to store. label: Human-readable description.

List all stored credentials (metadata only, no plaintext).

無需輸入參數。

Decrypt and return a stored credential. Args: credential_id: The credential's unique identifier.

Save a proven decoration to the library for reuse on future models. Captures the content file (heightmap, SVG, image), settings (depth, mode, material), and processing pipeline from the ``.kiln_recipe.json`` sidecar so the exact same decoration can be applied to new models with ``apply_decoration``. :param name: Human-readable name (e.g. "Ash Portrait"). :param model_path: Path to the model that was just decorated. :param content_type: Content type — ``photo``, ``svg``, ``qr``, ``text``, or ``auto`` (detect from file extension). :param source_path: Path to the original input file (photo, SVG). :param content_data: For QR: the data string. For text: the text. :param depth_mm: Decoration depth in mm (0 = auto from recipe). :param mode: ``emboss`` or ``deboss``. Omitted, the recipe sidecar's mode is used when it has one, else ``emboss``. :param image_style: Image processing style (coin, portrait, etc.). Omitted, the recipe sidecar's style is used when it has one, else ``auto``. :param material: Material used (e.g. PLA, PETG). Omitted, the recipe sidecar's material is used when it has one, else PLA. :param tags: Comma-separated tags for filtering. :returns: Dict with saved decoration details and library path.

List all saved decorations in the library. Browse the decoration library to find reusable decorations. Filter by content type, category, or tag. :param content_type: Filter by type — ``photo``, ``svg``, ``qr``, ``text``, ``procedural_texture``, ``ai_texture`` (empty = show all). :param category: Filter by category — ``surface`` (photo/svg/qr/text) or ``texture`` (procedural/AI textures). Empty = show all. :param tag: Filter by tag (empty = show all). :returns: Dict with decoration count and list. This is the decoration LIBRARY: keyed by name, and it ADAPTS — each recorded success stores proven settings for THAT material, so applying picks the depth and mode your prints proved for whatever you are printing in now. It keeps no version history. Kiln's other kind of saved decoration is a decoration PRESET (kiln-pro; what the web's /decorations pages show): keyed by an id because it has versions, branches and signed releases, and applied at the exact settings its version recorded rather than adapting to the material. Listed by ``list_decoration_presets``, applied by ``apply_decoration_preset``. The library adapts, the preset remembers — if what you want isn't here, look there. The response declares its own SCOPE. The library is local-only at every tier — the web's /decorations pages are the decoration PRESET store above, not a cloud copy of this one — so a complete local read here is the whole library, and ``scope`` says exactly that.

Apply a saved decoration to a new model — proven settings, one call. Loads a previously saved decoration and applies it to the target model using the exact settings that worked before. Automatically resolves depth, mode, and image style from the proven recipe. This is the magic tool — decorations that took many iterations to perfect can be replayed on any model in one call. :param name: Decoration name or slug. :param model_path: Path to the target model (STL or OBJ). :param material: Override material (empty = use proven or detect from printer). :param face: Which face to decorate: ``auto`` (largest flat face), ``top``, ``bottom``, ``front``, ``back``, ``left``, ``right``, or ``wall`` (wrapped round an upright round wall). :param printer_id: Registered printer name (as ``printer_status`` lists it) whose loaded spool decides the material when ``material`` is empty. Omit to use the decoration's proven material. :returns: Dict with decorated model path and settings used. INLINE 3D STAGE: on success this tool opens Kiln's interactive 3D stage — an inline viewer panel the user can orbit, zoom, and turn over — in hosts that render MCP Apps panels (Kiln's hosted connection attaches a browser stage link for hosts that don't). Oversized meshes are decimated automatically for the stage; the PNG preview is the floor, not the whole experience.

Get full details about a saved decoration. Shows the decoration's proven settings, content paths, tags, processing pipeline, and library location. :param name: Decoration name or slug. :returns: Dict with full decoration details and file paths.

Check your decoration quota — how many decorations you've used this month. A free account has a monthly decoration allowance (the reply says how many are left); Pro has no monthly limit. Returns used count, limit, remaining, tier, and current month.

無需輸入參數。

Record a successful print with a saved decoration (Kiln Pro). After a decoration prints well, call this with the settings that worked. ``apply_decoration`` then replays them on that material. :param name: Decoration name or slug. :param material: Material used (e.g. ``"PLA"``, ``"PETG"``). :param depth_mm: Depth in mm that printed well. :param mode: ``"emboss"`` or ``"deboss"``. :param image_style: Image style that worked (e.g. ``"coin"``). :param source_job_id: The print's job id when known: the same print reported twice (here and through ``record_print_outcome``) counts once. :returns: Dict with the updated decoration.

Create a new version of a saved decoration, archiving the current one (Kiln Pro). Use this when tuning a decoration -- a new depth, mode, style or content file -- and the previous version stays available for ``rollback_decoration``. :param name: Decoration name or slug. :param content_path: New content file (empty = keep current). :param depth_mm: New depth in mm (0 = keep current). :param mode: New mode, ``emboss`` or ``deboss`` (empty = keep current). :param image_style: New image style (empty = keep current). :param notes: Free-text notes for this iteration. :returns: Dict with the new version and what changed.

Get every version of a saved decoration (Kiln Pro). Each version with when it was made, what changed, the materials it has printed well on and its print count. :param name: Decoration name or slug. :returns: Dict with the version history and the current version.

Restore an earlier version of a saved decoration (Kiln Pro). The current version is archived and the earlier one comes back as a NEW version number, so history is never rewritten. :param name: Decoration name or slug. :param version: Version number to restore. :returns: Dict with the restored decoration.

Analyze an STL mesh for structural weak points. Goes beyond printability to find **structural** risks: - **thin_neck**: narrow cross-sections that will snap under load - **stress_concentration**: abrupt section changes that focus stress - **cantilever**: unsupported overhanging geometry - **sharp_corner**: sharp inside (concave) corners, where cracks start; outside edges never count - **insufficient_base**: topple risk from height-to-base ratio - **weak_layer_adhesion**: overhangs in structurally critical areas Returns risk locations as (x, y, z) coordinates in mm so agents can reason about *where* problems are, not just *that* they exist. A file smaller than anything a printer makes (a scene exported in metres) is answered with ``units_question`` and no risk: the counts are ``None`` until its size is settled. :param file_path: Path to the STL file. :param min_cross_section_mm2: Minimum safe cross-section area. Leave unset for Kiln's own threshold. :param sharp_angle_threshold_deg: How far the surface must turn inward across an edge, in degrees, for an inside corner to count as sharp. Leave unset for Kiln's own threshold, the same for every caller. :returns: Dict with ``risks`` list, each containing location, severity, and description.

Recommend specific reinforcements for an STL mesh. Analyzes geometry to find structural risks, then generates actionable recommendations with **specific locations** and what each one does for the part: - **gusset**: triangular support at cantilever bases - **fillet**: smooth transitions at stress concentrations - **thicken_wall**: add material at thin necks - **add_base**: widen the base for stability - **reorient**: change print orientation for layer strength Each recommendation includes the coordinates where the reinforcement should be applied and which Kiln tool to use (e.g., ``add_mesh_fillet()``). A file smaller than anything a printer makes is answered with ``units_question`` and no recommendation. :param file_path: Path to the STL file. :param min_cross_section_mm2: Minimum safe cross-section area. Leave unset for Kiln's own threshold. :returns: Dict with ``reinforcements`` list.

Analyze load-bearing characteristics of a mesh from its geometry. Infers structural behavior by analyzing surface normals, shape type, and cross-section distribution: - **primary_load_axis**: which direction the part resists force - **load_surfaces**: which surfaces bear load (with area fractions) - **weak_axis**: the most vulnerable direction for failure - **recommended_print_orientation**: how to orient for maximum strength - **layer_direction_concern**: how FDM layers affect structural integrity This is the difference between "PLA is good for prototypes" (lookup) and "this bracket should be printed on its side because the load path crosses layer boundaries" (geometric reasoning). :param file_path: Path to the STL file. :returns: Dict with load analysis.

Generate a complete structural improvement plan for a design. The **full design reasoning pipeline** — combines risk analysis, reinforcement recommendations, and load analysis into one actionable report. Its ``summary`` names the risks found, the worst first, and the first thing to do; the overall structural score (0-100, A-F grade) stays in the report for comparing versions of the part. This is the tool that makes Kiln a **design advisor**, not just a geometry validator. It answers: "This bracket needs a gusset at the load point" — not just "the part has thin walls." The plan includes: 1. **Risks**: all structural weak points with locations and severity 2. **Reinforcements**: specific fixes and what each does for the part 3. **Load analysis**: how the part handles forces, best print orientation 4. **Summary**: the risks named, and a score for comparing versions :param file_path: Path to the STL file. :param min_cross_section_mm2: Minimum safe cross-section area. Leave unset for Kiln's own threshold. :param sharp_angle_threshold_deg: How far the surface must turn inward across an edge, in degrees, for an inside corner to count as sharp. Leave unset for Kiln's own threshold, the same for every caller. :returns: Complete improvement plan as dict.

Analyze a part for structural risks, then auto-apply fixes. This is the **one-step design hardening tool** — it runs the full structural analysis pipeline, then applies every applicable fix: - **Thin necks** → thickened walls (+material at narrow sections) - **Sharp inside corners** → rounded, so the load spreads (outside edges are left as they are) - **Insufficient base** → a base plate wide enough that the part no longer reads as a tipping risk Each fix is kept only if the part it makes carries no more structural risk than the part before it; one that would is left out and listed in ``skipped`` with what it would have added. Cantilevers are listed in ``skipped`` with where to add a rib (``locations_mm``): Kiln knows where an overhang is, not which wall carries it, so it does not place one. Thickening and edge rounding are done on the part's CAD file, so pass its STEP file when there is one (or a mesh Kiln converted from one that still sits beside it). When every fix applied was a CAD one the result carries ``step_path``, the reinforced part as CAD. On a mesh with no CAD file, edge rounding is skipped with the reason. Edge rounding is sized for the printer: name it (or the nozzle, layer height and material) and each rounded edge keeps one nozzle width of flat beside it. Each rounded entry's ``edges`` lists what was finished, what stayed sharp and why, and ``cautions`` for edges that will print badly; ``print_aware`` sums it up. Choosing the finish edge by edge for the printer and material is a Kiln Pro feature. ``summary`` says which structural risks the part had and which remain; ``before_score`` / ``after_score`` compare the two

Infer optimal slicer settings from structural analysis. Bridges the gap between **design analysis** and **print success**. Analyzes the mesh for structural risks, then recommends concrete slicer parameters (perimeters, infill, supports, brim, layer height) tuned to compensate for the design's weaknesses. **Examples of what it catches:** - Thin neck detected → increase perimeters to 4+ - Cantilever overhangs → enable tree supports - High center of gravity → add brim for bed adhesion - Stress concentrations → switch to gyroid infill at 50%+ - Sharp corners → fine layer height for detail Material-specific: defaults vary by PLA/PETG/ABS/Nylon/TPU/ASA/PC. :param file_path: Path to the STL file. :param material: Filament type (PLA, PETG, ABS, Nylon, TPU, ASA, PC). :returns: Dict with perimeters, infill, supports, brim, layer height, orientation, special notes, and confidence level.

Ask which generation method to use for a design idea (triage tool — call FIRST). Analyzes the design prompt and recommends: - Which generation approach to use (template, OpenSCAD, or AI) - Which template matches (if any) - Material recommendations - Key constraints to consider - Estimated complexity :param prompt: Text description of the desired object. :param printer_model: Optional printer model for constraints. :param material: Optional material the user has already named ("for ABS") — tunes the constraint analysis to it. :returns: Dict with recommendations.

Pack multiple STL files onto a virtual build plate. Uses greedy bottom-left bin-packing (largest parts first) to efficiently arrange parts with configurable spacing. Reports which parts fit, which overflow, and plate utilization. Supports printing multiple copies of parts via the copies parameter. :param file_paths: JSON array of file paths, e.g. ``["/tmp/a.stl", "/tmp/b.stl"]``. :param plate_width_mm: Build plate width in mm (default 256). :param plate_depth_mm: Build plate depth in mm (default 256). :param spacing_mm: Minimum gap between parts in mm (default 5). :param copies: Optional JSON dict of filename->count, e.g. ``{"part.stl": 3}``. :param printer_id: Optional supported printer model id, or the name of a printer set up in Kiln. When provided, printer intelligence supplies the plate size. Keep passing it downstream — a later ``compose_multicolor_3mf`` without it judges the layout against a 256mm default plate. :returns: Dict with arranged_parts, overflow_parts, plate_utilization, summary.

Calculate non-overlapping XY positions for multiple parts on a print plate. Use this **before** :func:`compose_multicolor_3mf` when you have multiple separate objects (e.g., two coasters) to print in one job. Parts that share the same ``group`` index are treated as a multi-color unit and placed at the *same* XY position (they overlap intentionally). Returns a list of positioned part specs ready to pass directly to ``compose_multicolor_3mf`` — pass the SAME ``printer_id`` to that call: the composer re-centres a group it judges off ITS plate (256mm by default), so composing a layout packed for a different bed without the printer undoes this placement. Arrangement strategy (free tier): simple left-to-right row layout. For maximum plate density (2D bin-packing), use kiln-pro. Example -- two coasters, each with a body + QR layer:: positioned = auto_arrange_parts_on_plate(part_specs=[ {"stl_path": "/tmp/c1_body.stl", "extruder": 1, "group": 0, "material": "PLA Grey"}, {"stl_path": "/tmp/c1_qr.stl", "extruder": 2, "group": 0, "material": "PLA Black"}, {"stl_path": "/tmp/c2_body.stl", "extruder": 1, "group": 1, "material": "PLA Grey"}, {"stl_path": "/tmp/c2_qr.stl", "extruder": 2, "group": 1, "material": "PLA Black"}, ], plate_width=256, plate_depth=256, gap_mm=5) # -> each part now has "x", "y" set; pass to compose_multicolor_3mf Args: part_specs: List of dicts, each with: * ``stl_path`` (str) -- absolute path to the STL * ``extruder`` (int) -- 1-indexed AMS slot * ``group`` (int, optional) -- parts sharing a group get the same XY position (multi-color unit). Default: each part is i

Find the structurally strongest version of a parametric template. Sweeps each template parameter across its [min, max] range at evenly spaced sample points, generates every combination via OpenSCAD, runs structural analysis on each variant, and returns the configuration with the highest structural score. Use this when you want to **automatically** find optimal dimensions for a functional part -- e.g. "what wall thickness and bracket height give the strongest shelf bracket?" :param template_id: Template ID from the design template library. :param samples_per_param: Sample points per parameter (default 3). :param max_variants: Maximum total variants to test (default 27). :param constraints: JSON string of constraints, e.g. ``{"max_width_mm": 100, "max_height_mm": 50}``. :param output_dir: Directory for generated STLs (temp dir if empty). :returns: Dict with best_params, best_score, best_grade, best_stl_path, variants_tested, all_scores, and summary. INLINE 3D STAGE: on success this tool opens Kiln's interactive 3D stage — an inline viewer panel the user can orbit, zoom, and turn over — in hosts that render MCP Apps panels (Kiln's hosted connection attaches a browser stage link for hosts that don't). Oversized meshes are decimated automatically for the stage; the PNG preview is the floor, not the whole experience. MAKE DOORS: `design_session`, Kiln's front door for making an object, is not installed here (signed in to Kiln it runs on Kiln's servers). On this install `compile_scad` IS the make → preview → iterate loop: make it, show the preview, iterate.

Solve parametric constraints to find valid template parameters. Given a template and constraints (min/max/equals/ratio), iteratively adjusts parameters to satisfy all constraints while staying within the template's declared parameter ranges. :param template_id: Template identifier (e.g., "shelf_bracket"). :param constraints: JSON object mapping param names to constraint dicts. Example: ``{"width": {"min": 20, "max": 50}, "height": {"equals": 30}}`` Supported keys: min, max, equals, ratio (e.g. ``{"ratio": ["width", 0.5]}``). :returns: Dict with solved_params, satisfied/violated constraints, plus ``dof`` (how many parameters no constraint pinned), ``free`` (one sentence per unpinned parameter and the value it was left at) and ``defaults_applied``. Tell the person what was left free rather than silently accepting a default: ``min``/``max`` bound a parameter without choosing it.

Automated design iteration: generate -> validate -> improve -> regenerate. Runs a closed loop that generates a model, validates it for printability issues, and if issues are found, improves the prompt and regenerates. Stops when the model passes validation or max_iterations is reached. Returns the best result. :param prompt: Text description or OpenSCAD code. :param provider: Generation provider (default ``"openscad"``). :param max_iterations: Maximum improvement attempts (1-5). :param material: Optional material for design intelligence. :param printer_model: Optional printer model for constraints. :param brief_id: The saved goal's id from ``design_session``, so the best iteration is recorded against the goal and checked against it, including against any picture kept on the goal (``reference_check``). Empty when there is no goal. :returns: Dict with the best result and iteration history. INLINE 3D STAGE: on success this tool opens Kiln's interactive 3D stage — an inline viewer panel the user can orbit, zoom, and turn over — in hosts that render MCP Apps panels (Kiln's hosted connection attaches a browser stage link for hosts that don't). Oversized meshes are decimated automatically for the stage; the PNG preview is the floor, not the whole experience. MAKE DOORS: `design_session`, Kiln's front door for making an object, is not installed here (signed in to Kiln it runs on Kiln's servers). On this install `compile_scad` IS the make → preview → iterate loop: make it, show the preview, iterate.

Auto-rotate a mesh to minimize overhangs and maximize bed contact. Tests multiple candidate orientations and picks the one with the fewest overhangs and the most bed contact. Re-orients the mesh and places it flat on the build plate (z_min = 0). ``printability_score`` / ``printability_grade`` are the chosen orientation's score from ``analyze_printability`` itself, judged for ``material`` and ``printer_id`` — pass the same ones you gave ``analyze_printability`` and the two numbers match. :param file_path: Path to the STL file. :param output_path: Output path. Defaults to overwriting the input. :param material: Material the score is judged for (default ``"pla"``). :param printer_id: Optional printer the score is judged for. :returns: Dict with rotation angles, overhang stats, the printability score and grade, and new dimensions. INLINE 3D STAGE: on success this tool opens Kiln's interactive 3D stage — an inline viewer panel the user can orbit, zoom, and turn over — in hosts that render MCP Apps panels (Kiln's hosted connection attaches a browser stage link for hosts that don't). Oversized meshes are decimated automatically for the stage; the PNG preview is the floor, not the whole experience.

Single-call print readiness check with optional auto-repair. Checks the mesh is sound (parseable, manifold, no floating regions, no degenerate triangles, fits the build plate) and reads ``analyze_printability``'s verdict, which knows a short ceiling bridges. ``can_print`` is true only when the mesh is sound and Kiln's verdict lets the part print, the same verdict the print pipeline refuses on. ``verdict`` is ``ready_to_print``, ``printable_with_supports``, ``check_before_printing`` (the verdict asks for a check; it still prints, with a warning), ``wont_print`` (sound, but it won't print as it is) or ``needs_fixes`` (a mesh fault, named in ``issues``). ``validate_and_prepare`` runs the full pre-print pipeline. With ``auto_fix=True``, automatically repairs degenerate triangles, closes holes, and removes floating regions. :param file_path: Path to mesh file. :param auto_fix: Attempt automatic repairs (default False). :param output_path: Where to write the fixed file. :param bed_x_mm: Build plate X dimension (default 256). :param bed_y_mm: Build plate Y dimension (default 256). :param bed_z_mm: Build plate Z dimension (default 256). :param printer_id: Optional supported printer model id, or the name of a printer set up in Kiln. When provided, printer intelligence supplies the build volume. :param material: Material the supports verdict and the ``printability_score`` are judged for (default ``"pla"``) — ``analyze_printability``'s own, so the two agree. :returns: Dict with can_print verdict, issues, and actions taken.

Estimate support material needed for a mesh. Analyzes overhang triangles and projects them to the build plate to estimate the volume and weight of support material required. :param file_path: Path to a mesh (.stl, .obj, .glb, .3mf) or a CAD file (.step, .stp), which is converted automatically. :returns: Dict with support volume (mm³), weight (g), and overhang stats.

Re-execute the full build pipeline from a saved design recipe. Two modes, chosen by what the recipe carries — the result names which one ran: - **Parametric** (the recipe has OpenSCAD source): the geometry is RE-DERIVED. The recipe's numeric parameters are applied to the source and recompiled, so wall thicknesses and fastener holes come out exactly as designed. To resize a parametric design, change the parameter — with ``update_scad_parameter`` on the source, or on the recipe's parameters — and rebuild. Never scale the mesh instead: it scales every feature with the body, so a 3mm wall becomes 3.6mm and a 3.4mm M3 clearance hole becomes 4.08mm — no longer the fit it was dimensioned for. - **Mesh** (no source): the recorded part meshes are re-sliced exactly as they are. A geometry change needs a mesh edit first (``rescale_model``, ``thicken_mesh_walls``, ...), then a rebuild. Every parameter is itemized as applied, absent from the source, or skipped with a reason — an edit this tool cannot honor is reported, never silently dropped. The artifact is a print-ready 3MF where a Bambu printer is registered and the merged G-code otherwise (send that with ``upload_file``); ``wrapped`` says which one you got. When the render pipeline is available this also returns an inline preview of the rebuilt design; display that image to the user rather than summarizing it. The rebuild itself never depends on it. Example: rebuild_design("prints/bracket/") :param recipe_path: The design directory, or the recipe file. :param brief_id: Optional saved-goal id. When supplied it is recorded on the recipe before the re

Analyze a functional requirement and return technical recommendations. This is the internal-lookup tool that resolves a natural-language requirement into material recommendations, applicable design patterns, dimensional constraints, print orientation rules, and expert guidance notes. For the user-facing flow — capturing what a user is making at the duty / environment / materials / safety layer and producing a saved goal that drives generation, the audit, and the post-print review — call ``design_session(verb="start", idea="...")`` first. That tool internally calls this one for technical lookups; agents calling ``analyze_design_requirements`` directly should treat it as a pre-design analysis pass, not the user-facing entry point. Examples: "shelf bracket that holds 10 lbs of books" "outdoor planter that holds water" "phone mount for car dashboard, survives summer heat" "snap-fit enclosure for a Raspberry Pi" "flexible phone case that absorbs drops" "cookie cutter, food safe" "decorative vase, looks premium" Args: requirements: Natural language description of what the object needs to do — functional needs, environment, loads, etc. material: Optional material override (e.g. "petg"). If not provided, the system recommends the best material.

Build a design-aware generation prompt for original 3D creation. This is the best pre-generation tool for original designs. It takes a natural-language idea and appends manufacturing constraints, printer-fit limits, and material guidance so text-to-3D backends receive a prompt grounded in real printability constraints. When provider is specified, the prompt length is optimized for that backend. Use provider="openscad" for maximum constraint injection (100K chars), "meshy" for lean prompts (600 chars), or omit for the default limit. Args: requirements: Natural language description of the desired part. material: Optional material override (e.g. "petg"). printer_model: Optional printer model ID (e.g. "bambu_a1"). provider: Optional generation provider (e.g. "openscad", "meshy", "gemini"). Controls prompt length budget.

Run a ruthless audit of an original design before printing. Combines design briefing, prompt enhancement, mesh validation, printability scoring, orientation analysis, advanced diagnostics, and regeneration feedback into a single report. Use this after generating or modeling a new part to answer: "Is this genuinely ready to print, and if not, what exact changes should the agent make next?" Args: file_path: Path to STL or OBJ file. requirements: Functional requirements the design must satisfy. material: Optional material constraint (e.g. "petg"). printer_model: Optional printer model ID (e.g. "bambu_a1"). build_volume_x: Build volume X in mm. Pass all three of X, Y and Z to override the printer's build volume; any one left out means all three are ignored. build_volume_y: Build volume Y in mm. Pass all three of X, Y and Z to override the printer's build volume; any one left out means all three are ignored. build_volume_z: Build volume Z in mm. Pass all three of X, Y and Z to override the printer's build volume; any one left out means all three are ignored. nozzle_diameter: Nozzle diameter in mm. Leave unset for the nozzle Kiln has for ``printer_model``, else the stock size; the report says which it used. layer_height: Layer height in mm. max_overhang_angle: Supportless overhang threshold in degrees.

Compatibility lookup for a material's public design floor. Returns the same public safety and process fields as ``get_material_properties``. For deeper engineering guidance, ask one specific question with ``answer_material_question``. Args: material: Material ID (for example ``"pla"`` or ``"petg"``).

List public material identifiers and safety/process summaries. The list is sourced only from public Kiln data and does not include optional engineering enrichment.

無需輸入參數。

Recommend material for engineering/functional parts (strength, heat, environment). Analyzes functional requirements and recommends the optimal material considering mechanical needs, environmental exposure, printer capabilities, and ease of printing. Returns the top recommendation with reasoning, warnings, and alternatives. **Which material tool to use:** - Designing a part and need engineering specs? → ``recommend_design_material`` (this tool) - Quick intent-based pick for your own printer? → ``recommend_material`` - Ordering a print from a service? → ``suggest_material_for_order`` Args: requirements: What the object needs to do (e.g. "hold 5 kg of books on an outdoor shelf"). printer_has_enclosure: Whether the printer has an enclosed build chamber (needed for ABS, ASA, Nylon, PC). printer_has_direct_drive: Whether the printer has a direct drive extruder (needed for TPU). max_hotend_temp_c: Maximum hotend temperature in Celsius.

Estimate safe structural load for a cantilevered section. The figure is Kiln Pro's, worked out for this one part -- strength, sag and the arm's own weight, for any length of arm and size of section; below Pro the answer says the load was not checked. A part whose arm cannot hold its own weight gets no figure: ``load_checked`` is false and ``message`` says why. When the figure cannot be had (offline, signed out, no answer) the answer says why and that the part is unchecked. Args: material: Material ID (e.g. "petg", "nylon", "polycarbonate"). cross_section_mm2: Effective load-bearing cross section in mm^2. cantilever_length_mm: Cantilever length in mm. load_across_layers: True when the load pulls the layer interfaces apart (load along the build/Z direction — the WEAK direction for FDM, so the figure is lower). False when the load acts within the layer planes (e.g. a bracket printed lying flat — the strong direction). If unsure, leave True: it is the conservative default.

Check whether a material is compatible with an environment, and optionally whether it meets the rules the part must meet. Args: material: Material ID from the design knowledge base. environment: Natural language environment description. requirements: Optional rules to check the material against before printing: any of ``food_safe``, ``reach``, ``rohs``, ``flame_retardant``, ``uv``. The answer comes back under ``rule_checks``: the material's warnings always, and a meets / does-not-meet verdict with its reason where the plan includes it; when the check cannot be made, ``rule_checks.checked`` is false and no requirement is called met.

Look up one design template by id — parametric part or pattern. Resolves an id from EITHER library and says which it came from, so a caller never has to know in advance: * a PARAMETRIC PART (``generatable: true``) comes back with its full parameter list — names, defaults, and units — which is what you need to fill in the user's own dimensions and call ``generate_from_template``. * a DESIGN PATTERN (``generatable: false``) comes back with its use cases, material compatibility, and print orientation. Patterns are guidance for OpenSCAD you write yourself; ``generate_from_template`` does not accept them. Args: template: Template identifier, from either library — e.g. "shelf_bracket" (part) or "snap_fit_cantilever" (pattern). Use ``find_design_templates`` to search.

Browse the whole design-template library, both kinds. Returns every PARAMETRIC PART Kiln can render on its own — brackets, bins, stands, cases, hooks, jigs, clamps, plumbing and garden parts — followed by the DESIGN PATTERNS that are guidance rather than geometry. Every entry carries a ``generatable`` flag and the call to make next. The parametric parts are FREE and need no AI provider: they compile locally through OpenSCAD. Reach for one whenever a user wants a functional part to their own dimensions, and offer it before writing OpenSCAD from scratch — it is faster and every part in the library is print-verified. Use ``find_design_templates(use_case)`` to search rather than reading the whole catalog.

無需輸入參數。

Find a ready-made parametric part for what the user is making. CALL THIS FIRST whenever a user asks for a FUNCTIONAL PART to their own dimensions — a bracket that holds a shelf, a bin that fits a drawer, a clip for an 8 mm cable, a case for a board, an adapter between two hose sizes. Kiln ships a library of print-verified parametric parts; offering one is faster and more reliable than writing OpenSCAD from scratch, it is FREE, and it needs no AI provider or API key. Do not wait to be asked whether a template exists — search, and if something fits, offer it. Ranked best match first, across both libraries: * ``generatable: true`` — a PARAMETRIC PART. The result carries its parameters, so you can fill in the user's dimensions and call ``generate_from_template(template_id, {...})`` to render a printable STL. * ``generatable: false`` — a DESIGN PATTERN (snap fit, living hinge, press fit). Guidance for OpenSCAD you write yourself; ``generate_from_template`` does not accept it. No match is a normal answer, not a failure — fall back to writing OpenSCAD and compiling with ``compile_scad``. Args: use_case: What the user is making, in their words — e.g. "shelf bracket", "storage bin", "cable clip", "enclosure", "gear train", "hose adapter".

Identify which functional requirements apply to a design task. Scans natural language for requirement triggers (load bearing, watertight, outdoor, food safe, heat resistant, flexible, impact resistant, precision, aesthetic) and returns matched constraint sets with rules and guidance. Use this to understand WHAT constraints apply before getting the full design brief. Args: description: What the object needs to do (e.g. "outdoor hook that holds a heavy hanging planter").