Returns a comprehensive 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

Use this as the first call to understand what the printer is doing.
For lightweight polling during prints, use ``print_status_lite`` instead
(fewer tokens, accepts printer name).

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

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

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()``.

Handles FTPS (Bambu), REST multipart upload (OctoPrint/Moonraker), and
serial file transfer automatically.

Args:
    file_path: Absolute path to the G-code file on the local filesystem.
        The file must exist, be readable, and have a recognised extension
        (.gcode, .gco, or .g).

After a successful upload the file will appear in ``printer_files()`` and
can be started with ``start_print()``.

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()``.

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

Args:
    file_path: Path of the file as shown by ``printer_files()``.

This is irreversible -- the file cannot be recovered once deleted.

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"`` / ``True``: Force AMS on.  Use when you know AMS
          is connected.
        - ``"false"`` / ``False``: Force AMS off.  Use external spool.

    ams_mapping: Slot mapping per extruder (Bambu only).  Default
        ``[0]``.  Use ``[-1]`` for unused slots.  Check ``ams_status()``
        to see which slots have filament.
    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_cali: Run flow calibration (Bambu only).  Default ``True``.
    vibration_cali: Run vibration/resonance calibration (Bambu only).
        Default ``True``.
    layer_inspect: Enable first-layer lidar inspection pause (Bambu only).
        Default ``False``.
    nozzle_clog_detect: Enable nozzle clumping / blob detection by
        probing (Bambu only).  Default ``True``.  Set ``False`` to
        bypass HMS 0300-8014 errors on models that trigger false
        positives (thin first-layer geometry, certain grip/case models).
        Disables the A1/A1-mini eddy-current clump probe (first after
        the layer-3 walls, then once per ~8 g of filament; A1 series only).
    bed_type: Bed surface type (Bambu only).  Default ``"auto"``.
    plate_number: Plate index in multi-plate 3MF files (Bambu only).
        Default ``1``.
    resume_from_paused: When ``True``, the pre-flight ``printer_idle``
        check accepts ``paused`` as a valid state.  Use this when
        starting a resume-mode 3MF (mid-print decoration swap):
        the printer is paused, you upload the resume 3MF, and then
        ``start_print`` it with this flag.  The file is treated as
        a fresh print from the firmware's POV — the resume gcode
        carries its own preamble (heat → safety lift → home X/Y →
        travel → descend to resume Z).  Default ``False``.

        Auto-detected for files whose name contains ``_resume_``
        (case-insensitive) or starts with ``transformed_resume`` /
        ``original_resume`` — these are the conventional names
        produced by ``decorate_during_print`` and ``revert_mid_print``.
    skip_preheat_reassert: When the file is a resume-mode 3MF, the
        tool re-asserts the printer's pre-start hotend + bed targets
        immediately after the MQTT start command, because Bambu's
        resume 3MFs strip the M140/M190 pre-heat block (the original
        print already heated the bed) and the firmware's
        cool-on-new-job policy will otherwise drop the bed to 0
        before the resume preamble executes.  Set ``True`` to
        disable this safety net.  Default ``False``.

Sends cancel via MQTT (Bambu) or REST API (OctoPrint/Moonraker)
automatically.

The printer must have an active job (printing or paused).

: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: Same as above, for the bed.  This is
    the primary fix for Bambu A1 long-pause-then-cancel: the bed
    target sometimes reads back as 0 from MQTT cache after a long
    pause, and without an explicit override the cancel preservation
    skips the bed restore.
: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: Cancellation is irreversible -- the print cannot be resumed
from where it left off UNLESS a resume-mode 3MF has been pre-staged
(see ``decorate_during_print`` and ``revert_mid_print``).

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.

Sends M112 (emergency stop), turns off heaters, and disables steppers.
Unlike ``cancel_print``, this does **not** allow a graceful cooldown —
all motion ceases instantly.

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 (e.g. ``user_request``, ``thermal_runaway``).
    source: Trigger source label for audit context.
    note: Optional operator note.

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()``.

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()``.

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.

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.

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()``.

Pausing lifts the nozzle and parks the head.

Heater behaviour during pause varies by firmware:

  - Bambu A1 / A1 mini: the firmware drops the **hotend** target
    ~3-5 minutes into a pause regardless of slicer settings (bed
    target survives).  An untreated 25-min pause cools the nozzle
    from 220°C to ~90°C, which means the resume can't extrude
    until you re-heat — and bed adhesion can fail in the meantime.
  - Bambu X1/P1 series: typically holds both targets, but a long
    idle can still trigger cooldown.
  - OctoPrint / Moonraker / Klipper: depends on firmware config;
    most hold targets across pause.

To fight this, ``pause_print`` spawns a best-effort daemon thread
that re-asserts the pre-pause hotend + bed targets every 2 minutes
until the printer leaves the PAUSED state (resume, cancel, error,
or manual button press).  This is enabled by default.

Args:
    keep_temps: When ``True`` (default), capture the pre-pause tool
        and bed targets and re-assert them every ~2 minutes via a
        background daemon thread.  Set ``False`` to skip the
        keep-alive (legacy behaviour — printer may cool during long
        pauses).  The keep-alive thread is idempotent: repeat
        pause/resume cycles do not compound threads.

Use ``resume_print()`` to continue from where the print left off.
The keep-alive thread is automatically stopped on resume or cancel.

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: Backend-specific object identifiers to abandon (see above).
    plate_number: Which plate the ids came from (1-based, default 1).
        Recorded for context; the ids are what the printer acts on.

Returns:
    Dict with the skipped objects and a confirmation message, or an error
    dict if no print is active or the printer can't skip objects.

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.

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.

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.

The ``tray_now`` field usually shows which tray is currently active
(``"255"`` means none / external spool on X1/P1-style reports).  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 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.

Args:
    profile: Speed profile name — one of ``"silent"`` (50% speed,
        quiet), ``"standard"`` (100%, default), ``"sport"`` (124%,
        faster), or ``"ludicrous"`` (166%, maximum speed).

Sport and Ludicrous modes automatically increase nozzle temperature
to prevent under-extrusion at higher flow rates.

Use ``printer_status()`` to see the current speed profile in the
response's ``printer.speed_profile`` field.

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()``.

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"``.
        Defaults to ``"on"``.

Use this to improve camera visibility, signal print completion
(flashing), or turn lights off for overnight prints.

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
(https://github.com/prusa3d/Prusa-Link/issues/832). Elegoo's resin/MSLA
printers (Saturn, Mars) have no part-cooling fan and are 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. Defaults to ``100``.

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.

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 (default 220 for PLA).
    bed_temp: Bed temperature in °C (default 65 for PLA).
    filament_type: Filament type string — ``"PLA"``, ``"PETG"``,
        ``"ABS"``, etc.
    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).

Returns a dict with ``output_path`` pointing to the generated 3MF.
Use ``upload_file()`` to send it to the printer, then ``start_print()``
to begin printing.

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.

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.

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.

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

Args:
    file_path: Optional path to a local G-code file to validate before
        upload.  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`` — only ``idle`` is accepted.

Call this before ``start_print()`` to catch problems early.  The result
includes a ``ready`` boolean and detailed per-check breakdowns.

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.

Call this AFTER rendering a preview (``visualize_model`` /
``preview_generated_model``) and showing it to the user.  The user
approves → you call this tool → you pass the returned token as
``preview_token`` to ``start_print`` or ``fulfillment_order``.

Without a valid token, ``start_print`` refuses to execute (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 reused to approve a different file.

Args:
    file_path: Path to the file to be printed (STL, 3MF, or .gcode).
        Hashed to bind the token to specific bytes.  If the file
        changes between issuing and using the token, the token is
        rejected.
    printer_id: Optional printer model ID to scope the token to a
        specific printer.  When set, using the token with a different
        printer will be rejected.
    ttl_seconds: Lifetime of the token (default 600).

Returns:
    Dict with ``token`` and ``expires_at`` (unix timestamp).

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.

For historical analytics (success rates, throughput), use ``fleet_analytics``.
For grouping by physical location, use ``fleet_status_by_site``.
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.

If no printers are registered yet, the current adapter (from env config)
is auto-registered as "default".

Free tier allows up to 2 printers with independent control.
Pro tier unlocks unlimited printers with fleet orchestration.

Args:
    name: Unique human-readable name (e.g. "voron-350", "bambu-x1c").
    printer_type: Backend type -- "octoprint", "moonraker", "bambu",
        "creality", "elegoo", "prusalink", or "serial".
    host: Base URL or IP address of the printer.  For serial printers,
        this is the port path (e.g. "/dev/ttyUSB0", "COM3").
    api_key: API key (required for OctoPrint and Bambu, optional for
        Moonraker/Creality, unused for serial).  For Bambu printers
        this is the LAN Access Code.
    serial: Printer serial number (required for Bambu printers).
    verify_ssl: Whether to verify SSL certificates (default True).
        Set to False for printers using self-signed certificates.
        For Bambu, True maps to TLS pin mode and False maps to
        insecure mode.
    printer_model: Optional safety/profile key (e.g. "k1_max").
    persist: Save the printer to ``~/.kiln/config.yaml`` so future MCP
        sessions load the same printer. Default ``True``.
    verify_connection: For Bambu printers, immediately query AMS status
        after registration and return a proof summary. Default ``True``.

Once registered the printer appears in ``fleet_status()`` and can be
targeted by ``submit_job()``.

Manufacturing bureaus use projects to allocate printer time, material
costs, and fulfillment fees to specific client engagements.

Args:
    name: Project name (e.g. ``"Widget Batch 42"``).
    client: Client or cost-center identifier.
    description: Optional project description.
    budget: Optional budget cap in the configured currency.

Requires Enterprise license.

Args:
    project_id: The project ID returned by ``create_project``.
    category: Cost category — ``"material"``, ``"printer_time"``,
        ``"fulfillment_fee"``, ``"labor"``, or ``"other"``.
    amount: Cost amount in the configured currency.
    description: What this cost entry is for.
    printer_name: Optional printer that incurred the cost.
    job_id: Optional job ID for traceability.

Requires Enterprise license.

Returns total costs, per-category breakdown, and budget utilization
for a given project.

Args:
    project_id: The project ID returned by ``create_project``.

Requires Enterprise license.

Aggregates costs across all projects for a given client identifier,
useful for invoicing and chargeback.

Args:
    client: Client or cost-center identifier.

Requires Enterprise license.

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.

Writes the key to ``~/.kiln/license`` and returns the resolved
tier info.  Use ``license_status`` to check the current tier first.

Args:
    key: License key string (format: ``kiln_pro_...`` or ``kiln_biz_...``).

Opens a payment page.  After completing payment, the license key can
be retrieved with ``kiln upgrade --session <session_id>`` in the CLI.

Args:
    tier: ``"pro"``, ``"business"``, or ``"enterprise"``.
    billing: ``"monthly"`` or ``"annual"``.
    email: Pre-fill the checkout email field (optional).

Replaces the current process with a fresh instance using
``os.execve``.  The MCP client (Claude Code, etc.) should detect
the connection drop and automatically reconnect, picking up any
code changes made since the last startup.

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 no hint why.  Set to ``False`` to
    preserve the full env (useful for CI or pure env-driven workflows
    where config.yaml is absent or deliberately overridden).
:returns: Confirmation that the restart is imminent, plus the list
    of env vars that were stripped (for debugging transparency).
    The connection will drop within ~0.5 seconds.

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.

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.

**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) for the model.

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.

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

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.

Handles TLS+JPEG camera protocol (Bambu A1/P1), MJPEG stream capture
(OctoPrint/Moonraker), and RTSPS (Bambu X1) automatically.

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

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

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.
    tool_index: Extruder index for multi-tool printers (default 0).

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.

Args:
    expected_material: The material the print file requires.
    printer_name: Target printer.  Omit for the default printer.

Args:
    material: Material type (PLA, PETG, ABS, etc.).
    color: Filament color.
    brand: Manufacturer brand.
    weight_grams: Total spool weight in grams (default 1000).
    cost_usd: Cost of the spool in USD.

Args:
    spool_id: The spool's unique identifier.

Args:
    printer_name: Target printer.  Omit for the default 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.

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.

Args:
    printer_name: Target printer.  Omit for the default printer.
    action: One of ``"start"``, ``"stop"``, or ``"status"``.
    port: Local port for the stream server (default 8081).

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.

Args:
    endpoint_id: The endpoint ID returned by ``register_webhook``.

Once deleted, the endpoint will no longer receive event notifications.

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.

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.

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 local estimate (PLA, PETG, etc.).
    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.

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.

This tool is a thin wrapper around ``visualize_model`` with a single
isometric angle.  Prefer ``visualize_model`` directly for multi-angle
previews with proper auto-framing.

Args:
    file_path: Path to an ``.stl``, ``.3mf``, ``.obj``, or ``.scad`` file.
    width: Image width in pixels (default 800).
    height: Image height in pixels (default 600).
    color: Hex color for the model (e.g. ``"#F72323"``).

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 BEFORE printing to verify the model looks correct from all
sides.  Both agents and humans should review the output.

**When to use this vs other preview tools:**
- ``visualize_model`` — any file, 6 angles, universal (USE THIS ONE)
- ``preview_generated_model`` — after AI generation, includes bottom check
- ``render_model_preview`` — single angle, quick check

Args:
    file_path: Path to an STL, 3MF, OBJ, or SCAD file.
    angles: Optional subset of angles to render. Valid values:
        ``isometric``, ``front``, ``right``, ``top``, ``bottom``, ``back``.
        Defaults to all 6.
    width: Image width in pixels (default 800).
    height: Image height in pixels (default 600).
    color: Hex color for the model (e.g. ``"#F72323"`` for red).
        Defaults to neutral grey.  Pass the filament color to see
        a realistic preview matching the printed result.
        Ignored for colored 3MF files (per-face colors used instead).

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"]``).

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.

Templates provide ready-to-use OpenSCAD code with customizable
parameters.  Use ``generate_from_template`` to render one into
a printable STL.

Each template includes:
- Customizable parameters with defaults, ranges, and descriptions
- Pre-validated OpenSCAD code (prints without supports)
- Category and description

Use when you know which template and parameter values to use. For AI-assisted
parameter inference + structural analysis, use ``smart_generate_from_template``.
Renders the template's OpenSCAD code with custom parameter values
into a printable STL.  Use ``list_design_templates`` to see
available templates and their parameters.

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.  See https://kiln3d.com for tier details.

Args:
    template_id: Template ID from ``list_design_templates``.
    parameters: Optional dict of parameter overrides
        (e.g., ``{"phone_width": 80, "angle": 70}``).

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

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.

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: AMS slot mapping (e.g. ``[0]`` for slot 1).
: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 — ``"auto"``, ``"textured_plate"``,
    ``"cool_plate"``, or ``"engineering_plate"`` (Bambu only).
:param plate_number: Which plate to extract from (1-based, default 1).
:returns: Dict with extraction info and print start status.

Reads embedded metadata to determine the original marketplace source.
Supports 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.

Compiles the code and returns structured error/warning information
with line numbers.  Use this to check code before calling
generate_model with OpenSCAD.

:param code: OpenSCAD source code to validate.
:returns: Dict with ``valid``, ``errors``, and ``warnings``.

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.

:param file_path: Path to mesh file (.stl, .obj, or .glb).
:param min_wall_mm: Minimum printable wall thickness (default 0.8).
:param max_bridge_mm: Maximum unsupported bridge length (default 15).
:param max_overhang_deg: Maximum overhang angle before failure (default 55).
:returns: Dict with verdict, risk score, and failure list.

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.

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 description: Natural-language design description.
:param output_dir: Directory for output files (uses tempdir if empty).
:param material: Material for weight estimation and slicing.
: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.

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.

Creates a **single print-ready .3mf** containing all parts with per-part
AMS/extruder slot assignments.  This is the correct way to send a
multi-color design to any FDM printer — the printer receives one file,
not multiple.

Compatible with:
* **BambuStudio / Bambu A1, X1, P1 + AMS** — reads ``Metadata/model_settings.config``
* **PrusaSlicer / MMU** — reads ``slic3rpe:extruder`` on each ``<item>``
* **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. Upload and print:
    upload_file(result["output_path"])
    start_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)

        Optional per-part keys:

        * ``name`` (str) — label shown in the slicer object list
        * ``color`` (str) — hex preview color e.g. ``"#AAAAAA"`` (display only)
        * ``material`` (str) — filament label e.g. ``"PLA Grey"`` (display only)

    output_path: Where to write the .3mf.  Defaults to a temp file whose
        path is returned in the result.

Returns:
    Dict with ``success``, ``output_path``, ``parts``, ``total_triangles``,
    ``total_vertices``, ``extruder_map``, and ``message``.

For fleet setups where you need to update a specific printer by name
or pin a target version, use ``update_printer_firmware`` instead.
For Moonraker printers, this triggers the Klipper update manager.
For OctoPrint printers, this uses the Software Update plugin.

Args:
    component: Optional component name to update (e.g. ``"klipper"``,
        ``"moonraker"``).  If omitted, all components with available
        updates will be upgraded.

The printer must not be actively printing.  Check ``firmware_status``
first to see which updates are available.

For fleet setups where you need to rollback a specific printer by name
or target a specific version, use ``rollback_printer_firmware`` instead.
Only supported on Moonraker printers.  The component must have a
known rollback version (check ``firmware_status``).

Args:
    component: Name of the component to roll back (e.g. ``"klipper"``).

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

Args:
    printer_name: Name of the printer to get stats for.

Args:
    job_id: The job ID of the print to annotate.
    notes: The annotation text to attach.

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"``).

This is the knowledge base that helps you make informed decisions about
print settings, troubleshooting, and calibration without trial-and-error.

Args:
    printer_id: Printer model identifier (e.g. ``"ender3"``,
        ``"bambu_x1c"``, ``"voron_2"``).

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"``).

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 (https://kiln3d.com/pricing)
the response also carries a decoded cause, fix, and severity for the code.

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.

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 hint (e.g. ``"PLA"``).  When set, 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.

On Bambu AMS printers the response carries ``ams_selection``
(``{slot, type, color}``) naming the tray actually used — routing is
never silent.

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 hint (e.g. ``"PLA"``).  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: Enable AMS filament feeding (Bambu printers). If omitted,
        auto-detected from 3MF metadata.
    ams_mapping: JSON string of AMS slot indices (e.g. ``"[0, 2]"``).
        Maps each extruder/filament to an AMS tray position.
    skip_validation: Bypass the mesh-level pre-print validation step.
        Defaults to False — designs are pre-tested for printability
        before they reach the printer.

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.

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

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.

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.