Kiln

        Every AI app, terminal and bridge on this computer runs its own
        Kiln session.  While this session has the printer reserved, the
        others can still check its status and camera and send an
        emergency stop, but their other commands to it are refused, naming
        who reserved it.  The reservation ends when it is released, when
        ``hold_minutes`` run out, or when this session exits; call again to
        renew it.  It never lets anyone use a printer their plan would not
        (one printer at a time below Kiln Business).

        Args:
            printer_name: Printer to reserve.
            holder: A name for who reserved it (for example the app),
                shown to the sessions that are refused.
            hold_minutes: How long it lasts (1 to 1440, default 30).
            timeout_seconds: How long to wait if another session has it
                (default 0: answer at once with who has it; at most 120).
        

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.

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

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

Args:
    session_id: Target session ID.
    name: Human-readable rule name.
    trigger: Trigger type -- one of: temp_exceeds, temp_below,
        temp_delta, feedrate_exceeds, flow_anomaly, position_limit,
        command_blocked, pattern_match, always, layer_change.
    action: Action to take -- one of: allow, block, modify, pause, alert.
    priority: Rule priority -- one of: critical, high, medium, low.
    threshold: Numeric threshold for trigger evaluation.
    threshold_max: Upper bound for range-based triggers.
    blocked_commands: List of G/M codes for command_blocked trigger.
    pattern: Regex pattern for pattern_match trigger.
    modify_params: Parameter overrides for modify action (e.g. {"F": 3000}).
    message: Human-readable explanation shown when rule fires.

        The flat-faced twin of ``add_mesh_fillet``: same CAD route, same
        edge selection, same reply.

        Literal: it bevels the edges you select at the distance you give
        (measured along each face from the edge).  An edge on a narrow
        face gets a smaller bevel or stays sharp, a hole's rim stays sharp
        unless selected, and ``edges.left_sharp`` gives every reason.

        A mesh with no CAD file behind it is refused, and a part made
        from an OpenSCAD script is bevelled in its script; each refusal
        says which.

        AGENT DISPLAY CONTRACT: a result carries a before|after self-check
        of the part.  Look at it and write what changed before calling
        the job done.

        :param file_path: The part: a STEP file, or a mesh converted from one.
        :param distance_mm: Bevel distance from the edge in mm (default 0.5).
        :param angle_threshold_deg: An edge is sharp when the surface
            turns at least this much across it (default 60).
        :param output_path: Output ``.stl`` path (defaults to
            ``<name>_chamfered.stl``); the CAD is written beside it.
        :param edges: Which edges; see ``add_mesh_fillet``.
        :param printer_id: The printer the part is for.
        :param nozzle_mm: The nozzle size, when it differs from the one
            Kiln has for the printer.
        :param layer_height_mm: The layer height it will print at.
        :param material: The material it will print in.
        :param plan_only: Return the plan and every edge's id without
            building anything.
        :returns: ``path``, ``step_path``, ``edges`` (finished, left
            sharp, cautions), ``sized_for``, ``volume_mm3`` and the
            measurements before and after; or a refusal saying why.

        Pass the part's STEP file (or a mesh Kiln converted from one that
        still sits beside it).  The CAD kernel rebuilds each face, so the
        result is a closed solid of the size geometry gives; it comes back
        as a mesh (``path``) and as CAD beside it (``step_path``), so the
        next edit starts from CAD again.

        Literal: it rounds the edges you select at the radius you give.
        Two things can change that, and the reply says so each time:

        * an edge on a narrow face gets a smaller radius (the face keeps
          one nozzle width of flat), or stays sharp when what is left
          would not show in a print;
        * a hole's rim stays sharp unless you select it.

        ``edges.left_sharp`` lists every selected edge left sharp, with
        its reason.  ``edges.cautions`` says what will print badly as
        asked: a finish on the bed or facing down whose surface overhangs
        past what the printer bridges, and by how much.

        A mesh with no CAD file behind it is refused: rounding on a mesh
        left an open surface and a bigger part on every part measured.  A
        part made from an OpenSCAD script is rounded in its script; the
        refusal names it.

        AGENT DISPLAY CONTRACT: a result carries a before|after self-check
        of the part.  Look at it and write what changed before calling
        the job done.

        :param file_path: The part: a STEP file, or a mesh converted from one.
        :param radius_mm: Fillet radius in mm (default 1.0).
        :param angle_threshold_deg: An edge is sharp when the surface
            turns at least this much across it (default 60).
        :param output_path: Output ``.stl`` path (defaults to
            ``<name>_filleted.stl``); the CAD is written beside it.
        :param edges: Which edges.  Empty or ``all``: every sharp edge.
            Words narrow it -- where the edge sits as the part prints
            (``vertical``, ``top``, ``bottom``, ``under``, ``sloped``) and
            which way the corner goes (``outside``, ``inside``);
            ``holes`` selects hole rims.  Combine with commas:
            ``top,outside``.  Or name edges by id: ``e12,e15`` (ids come
            from ``plan_only``).
        :param printer_id: The printer the part is for; sizes are limited
            by its nozzle and layer height.
        :param nozzle_mm: The nozzle size, when it differs from the one
            Kiln has for the printer.
        :param layer_height_mm: The layer height it will print at.
        :param material: The material it will print in.
        :param plan_only: Return the plan and every edge's id without
            building anything.
        :returns: ``path``, ``step_path``, ``edges`` (finished, left
            sharp, cautions), ``sized_for``, ``volume_mm3`` and the
            measurements before and after; or a refusal saying why.

        Validates the profile and saves it to this machine's override file
        (``~/.kiln/local_printer_overrides.json``; the older name
        ``community_profiles.json`` is still read).  Nothing saved here is
        uploaded, pooled or shared.

        An override may only TIGHTEN a curated limit.  A higher number is
        discarded in favour of Kiln's curated value, so this is the right
        tool for a printer Kiln has never heard of, or for holding your own
        machine BELOW the curated limits.

        It is the WRONG tool for "my hotend is upgraded".  Use
        ``select_printer_variant`` for that: it resolves to a ceiling Kiln
        has verified against the manufacturer, instead of one you typed.

        Values saved here are labelled owner-supplied in every profile
        readout — Kiln never presents them as its own verified numbers.

        For a printer Kiln has no number for, a limit above its generic
        floor needs two things.  A signed-in install (a free account:
        ``kiln_signin``), because Kiln vouches for ceilings it enforces
        and a ceiling nobody set is held to the floor.  And a PERSON's
        confirmation: Kiln shows a code on the screen of the machine it
        runs on, the person types it in the chat, you pass it to
        ``give_print_code``, then call this again with the same numbers.  Find the numbers on the maker's own spec
        page (maximum hotend and bed temperature, bed size) and say where
        they came from in ``notes``; never guess them, and never ask the
        person to type numbers they do not know.  The code is the
        confirmation; nothing you can call stands in for it.

        A Klipper printer that is set up here can state them itself.
        Leave ``profile`` out and Kiln reads the heater ceilings, travel
        and velocity limit off the printer's own configuration (through
        Moonraker), puts them in front of the person as ``proposal`` with
        the configuration lines they came from, and takes the same code.
        The saved limits are labelled as read from that printer.  The
        hotend and bed numbers are the board's shutdown points, and a
        hotend proposal above Kiln's generic floor carries a
        ``caution`` about PTFE-lined hotends: say it to the person
        before they confirm.  A printer that cannot state them (any
        other backend) says so and asks for ``profile``; a
        configuration that states only some of them hands those back
        in ``proposal`` for you to complete.

        Args:
            printer_model: Short identifier for the printer (e.g.
                ``"my_custom_corexy"``).
            profile: Dict containing at least ``max_hotend_temp``,
                ``max_bed_temp``, ``max_feedrate``, and ``build_volume``
                (a list of 3 positive numbers ``[X, Y, Z]``).  Optional
                fields: ``display_name``, ``max_chamber_temp``, ``min_safe_z``,
                ``max_volumetric_flow``, ``notes``.  Omit it to read the
                limits off the printer.
            printer_name: Which registered printer to read the limits
                off when ``profile`` is omitted; the default printer
                when empty.  Ignored when ``profile`` is given.
        

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.

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.

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.

        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.
        

        Returns feedback with specific constraints to add to the
        generation prompt to fix identified issues.

        Args:
            file_path: Path to the generated model file.
            original_prompt: The original generation prompt.
            failure_mode: Optional failure mode if the model was printed
                and failed (e.g. ``"adhesion"``, ``"spaghetti"``).
            max_overhang_angle: Maximum overhang angle in degrees.
            min_wall_thickness: Minimum wall thickness in mm.
            has_bridges: Whether the model has bridge features.
            has_floating_parts: Whether the model has disconnected parts.
            non_manifold: Whether the mesh is non-manifold.
        

        Goes beyond basic validation to compute volume, surface area,
        center of mass, overhang detection, connected components (floating
        parts), degenerate triangles, and ``mesh_check_score`` (0-100), a
        quick mesh check.  It is not the printability score: call
        ``analyze_printability`` for that grade.

        Use this after generating a model to understand its geometry and
        identify printability issues before sending to the slicer.

        For a STEP/STP CAD file this converts it first and every metric
        below is measured on Kiln's mesh copy — except an added ``exact``
        block, which carries the volume, surface area and envelope read
        from the CAD file's own surfaces.  Those two disagree slightly
        and the exact ones are the part's: quote ``exact`` when telling
        a user how big their CAD part is.  ``mesh_quality_scorecard``
        gives the same file a fuller intake report.

        A mesh of more than one body also gets ``body_pairs``: for each
        pair of bodies, nearest first, the smallest gap between them in
        mm and, where two overlap, the volume they share (they print
        fused).  It is what a print-in-place part (gears in a ring, a
        pin in its knuckles) is designed against.  Bodies are numbered
        as the fusion findings number them, and each one's centre, box
        and volume say which part it is.

        :param file_path: Path to a mesh (.stl, .obj, .glb, .3mf) or a CAD
            file (.step, .stp), which is converted automatically.
        :returns: Dict with full mesh analysis metrics, plus ``exact``
            for CAD input and ``body_pairs`` for a mesh of several bodies.
        

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

        Reports boundary edges (shared by 1 triangle), T-junction edges
        (shared by 3+ triangles), and manifold edges (shared by exactly 2).

        This is the diagnostic version of the manifold check -- use it
        to understand exactly how many edges are problematic before
        deciding whether to repair.

        A STEP/STP CAD file is converted first and the count is taken on
        the converted mesh, because a non-manifold edge is a defect of
        the triangles, not of the shape -- a STEP solid has none to be
        defective.  So on CAD input this measures KILN'S TESSELLATION,
        which is worth knowing (it says whether the conversion came out
        clean) and is not a finding about the user's file.  ``subject``
        says which artifact was measured and ``message`` says it in
        words.  AGENT CONTRACT: when ``subject`` is
        ``"kiln_tessellation"``, carry that attribution through to the
        user -- never report the count as a verdict on their CAD.

        :param file_path: Path to a mesh (.stl, .obj, .glb) or a
            STEP/STP CAD file.
        :returns: Dict with edge count breakdown, watertight status,
            ``subject``, ``message``, and (CAD only) ``converted_from``.
        

        Performs deep analysis of an STL or OBJ mesh including overhang
        detection, thin wall analysis, bridging assessment, bed adhesion
        surface estimation, and support volume estimation.  Returns one
        ``verdict`` (``ready``, ``prints_with_supports``, ``wont_print``
        or ``check``) with its sentence as ``message``, and the full
        ``report`` with actionable recommendations.  The report keeps a
        0-100 score and a letter grade for comparing versions of a part;
        tell the person the verdict, not the score.

        Pass ``material`` (and ``printer_id`` when a printer is
        registered) so the warping, thermal-stress, and adhesion checks
        run against the actual filament instead of generic PLA defaults.
        On the free tier those checks use conservative safe-floor
        thresholds; with Kiln Pro they are tuned to the specific
        material and printer.

        When the mesh turns out to have holes in it, the result also
        carries a ``fastener_advice`` block saying they were measured
        but not checked against the hardware meant to go in.  Kiln
        raises that once per session across every tool that can raise
        it, so a later analysis may omit the block even though the
        part has holes.  Read its ``agent_instruction`` before
        repeating any of it to the user.

        Args:
            file_path: Path to an STL or OBJ mesh file.
            nozzle_diameter: Printer nozzle diameter in mm.  Leave unset
                and name the printer: Kiln then checks for the nozzle on
                record for it, else the printer's own setting, else the
                model's stock size, and ``report.nozzle`` says which.
                With no printer named, the only printer Kiln knows of
                stands in; with none, the check assumes 0.4 and says so.
            layer_height: Print layer height in mm (default 0.2).
            max_overhang_angle: Maximum overhang angle in degrees before
                supports are needed.  Leave unset for the material's own
                limit (45 when none is known) — the value every other
                tool that reports this score uses, so the numbers agree.
            build_volume_x: Optional build volume X dimension in mm.
            build_volume_y: Optional build volume Y dimension in mm.
            build_volume_z: Optional build volume Z dimension in mm.
            material: Material ID for warping / thermal-stress / adhesion
                analysis (default ``"pla"``).
            printer_id: Optional registered printer whose real geometry
                and calibration should inform the analysis.
        

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.

        Uses heuristics based on error messages, print progress, and
        failure history to classify the failure type and generate an
        actionable recovery plan.

        With kiln-pro installed the answer can also carry
        ``nozzle_wear_hypothesis``: whether the printer's nozzle wear
        likely contributed.  That check is Kiln Pro; below it, a failure wear could
        explain carries ``nozzle_wear_hypothesis_gated`` saying so once.

        Args:
            progress: Print progress at failure (0.0 - 1.0).
            error_message: Error message from the printer or system.
            printer_name: Name of the printer that failed.
            job_id: Job ID of the failed print.
        

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

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.

        Parses parameters, modules, and library imports to understand
        the code's architecture. Use this before modifying code to know
        what modules exist and what each one does.

        Args:
            scad_code: OpenSCAD source code.
        

        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.
        

        Examines the mesh for warping risk factors: large flat surfaces that
        tend to curl at corners, tall/narrow geometry prone to thermal
        contraction pulling, and sharp base corners that lift. Cross-references
        with the material's known warping tendency (from thermal properties).

        Returns a risk assessment with:
        - risk_level: "low", "moderate", "high", or "critical"
        - large_flat_surfaces: detected flat areas prone to warping
        - height_to_base_ratio: geometry aspect ratio risk factor
        - material_warping_tendency: material's inherent warp behavior
        - recommendations: actionable mitigation advice, led by the brim
          or raft to use when the part calls for one
        - adhesion: the brim / raft decision for this part (width, raft,
          reason, slicer overrides) — the same one analyze_printability
          reports

        Args:
            file_path: Path to a mesh (.stl, .obj, .glb, .3mf) or a CAD
                file (.step, .stp), which is converted automatically.
            material: Material ID (e.g. "pla", "abs", "petg"). Defaults to PLA.
                Used to look up thermal warping tendency.
            printer_id: Optional registered printer whose real geometry
                and calibration should inform the analysis.

        Examples:
            analyze_warping_risk("/path/to/model.stl", material="abs")
            analyze_warping_risk("/path/to/plate.stl")  # defaults to PLA
        

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

        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.

        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
        versions.  Reinforcements that can't be auto-applied (like
        ``reorient``) are listed in ``skipped`` with guidance.

        Requires OpenSCAD for the base plate.

        AGENT DISPLAY CONTRACT: a result carries a before|after self-check
        of the part.  Look at it and write what changed before calling
        the job done.

        :param file_path: The part: an STL, or its STEP file.
        :param output_path: Output path (defaults to ``<name>_reinforced.stl``).
        :param fillet_radius_mm: Fillet radius for sharp corners (default 1.5).
        :param wall_thicken_mm: Amount to add to thin walls (default 0.6).
        :param base_height_mm: Height of stabilizing base plate (default 2.0).
        :param printer_id: The printer the part is for.
        :param nozzle_mm: The nozzle size, when it differs from the one
            Kiln has for the printer.
        :param layer_height_mm: The layer height it will print at.
        :param material: The material it will print in.
        :param fastener: The fastener the part's holes take, e.g.
            ``"M3"`` — pass only if the user actually named one.  Kiln
            does not read the part looking for screw holes.  Where the
            plan includes it, each hole that threads onto it is prepared
            for it as the corners are rounded; otherwise the holes are
            left as drawn and ``print_aware`` says so.
        :returns: Dict with before/after scores, applied/skipped reinforcements.

        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.
        

        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.
        

        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.
        

        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 its own group.
                * ``name`` (str, optional) -- label in slicer
                * ``color`` (str, optional) -- hex preview color
                * ``material`` (str, optional) -- filament label (also triggers
                  compatibility checks when passed to compose_multicolor_3mf)

            plate_width: Print plate X dimension in mm (default 256);
                replaced by the printer's own plate when ``printer_id``
                is given.
            plate_depth: Print plate Y dimension in mm (default 256);
                replaced by the printer's own plate when ``printer_id``
                is given.
            gap_mm: Minimum spacing between groups in mm.
            printer_id: Optional printer: a supported model id, or the
                name of a printer set up in Kiln.  When provided, its
                recorded plate size replaces the explicit dimensions.

        Returns:
            Dict with ``success``, ``parts`` list (each part has ``x``, ``y`` set),
            ``group_count``, ``fits_bed`` (``False`` when the rows run past
            the bed: the message then gives the layout's size, the bed's, and
            what to do, instead of the next step), ``bed_fit``, and
            ``message``.
        

        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 exceed
            the input's), per-zone ``watertight`` verdicts, AMS slot
            mapping, weight estimates, and optional 3MF path.

        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 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,
            AMS slot mapping, weight estimates, and optional 3MF path.

        Evaluates multiple rotations of the model, ranks them, and
        reports each candidate's bed contact, support volume, print
        height and overhang share.  Candidates come in the order Kiln
        ranks them for this account; each candidate's ``score`` is its
        bed-contact percentage, so a later candidate can score higher
        than the best.  ``message`` says what the best turn changes
        (support, overhangs, bed contact, height) or that the part
        already sits best.  With ``apply``, writes the reoriented mesh
        to ``output_path`` (a file already there is replaced).

        Args:
            file_path: Path to an STL or OBJ mesh file.
            candidates: Number of candidate orientations to evaluate
                (default 24).
            nozzle_diameter: Printer nozzle diameter in mm (default 0.4).
            apply: If True, apply the best orientation and write the
                reoriented STL to disk.
            output_path: Output path for the reoriented STL.  Only used
                when ``apply`` is True.  Defaults to
                ``<input>_oriented.stl``.
        

        Polls the provider until the job reaches a terminal state or the
        timeout is exceeded.  Useful for agents that want to block until
        a model is ready.

        Args:
            job_id: Job ID from ``generate_model``.
            provider: Provider that owns the job.
            timeout: Max seconds to wait for generation (default 600 = 10 min).
            poll_interval: Seconds between polls (default 10).
        

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.  A
finished print's ``hardware`` block names what goes in after the print.

        Creates a copy of the SQLite database.  By default, sensitive fields
        (API keys, access codes, payment refs) are replaced with "REDACTED"
        in the backup.

        Args:
            output_path: Destination file path.  Defaults to
                ``~/.kiln/backups/kiln-YYYYMMDD-HHMMSS.db``.
            redact: If ``True`` (default), redact credentials in the backup.
        

Args:
    printer_name: Target printer.  Omit for the default printer.

        Uses OpenSCAD's boolean engine to compute:
        - **union**: combine multiple bodies into one
        - **difference**: subtract subsequent bodies from the first
        - **intersection**: keep only the overlapping region

        Requires OpenSCAD installed on the system.

        **Use cases:**
        - Subtract a cylinder from a block to create a hole
        - Combine multiple parts into a single printable body
        - Create complex shapes from simple primitives

        :param operation: ``"union"``, ``"difference"``, or ``"intersection"``.
        :param file_paths: List of STL file paths (minimum 2).
        :param output_path: Output path (defaults to a temp file).
        :returns: Dict with result path, operation, and triangle count.

        Args:
            browse_type: One of "popular", "newest", or "featured".
            page: Page number (1-based, default 1).
            per_page: Results per page (default 10, max 100).
            category: Optional category slug (e.g. "3d-printing", "art");
                ``list_model_categories`` lists the slugs.  When given,
                ``browse_type`` is ignored and the category's models are
                listed instead.

        Returns model summaries similar to ``search_models``.
        

        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.
        

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.

        Returns an enhanced prompt with OpenSCAD-specific instructions that
        guide AI to produce well-structured parametric code with named
        variables, descriptive comments, and material-aware design limits.

        Use this instead of build_generation_prompt when you want the AI to
        generate editable OpenSCAD code rather than a mesh file.

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

        Args:
            file_path: Path to the design file to cache.
            label: Human-readable label for the cached design.
            material: Intended material for this design.
        

        Stores the STL/3MF file in the design cache and attaches the
        OpenSCAD source code and generation prompt so the design can
        be re-generated or tweaked later.

        Args:
            file_path: Path to the design file (STL, 3MF, etc.).
            scad_source: OpenSCAD source code that produced this file.
            generation_prompt: The prompt used to generate the design.
            provider: Generation provider name (e.g. "openscad", "gemini").
            tags: Optional tags for search.
            filament_type: Material type (e.g. "PLA", "PETG").
        

        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.
        

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.

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: 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 ``get_print_before_edit``).

        Args:
            session_id: The session_id to cancel.
            reason: Optional reason for the cancellation.
        

        Only orders that have not started printing can be cancelled.

        Args:
            order_id: The order ID to cancel.
        

Queue bookkeeping only: this marks the row cancelled and never sends
anything to a printer.  To STOP a job the machine has already
started, use ``cancel_print`` — that is the tool that talks to the
hardware.

Args:
    job_id: The job ID to cancel.

Only a job still in the QUEUED state can be cancelled here.  A job
that has reached the machine (starting, printing, or paused) is
refused with ``code="PRINT_IN_PROGRESS"`` rather than cancelled,
because marking the row cancelled would leave the queue claiming a
print had stopped while the printer carried on running it.

The bulk companion to ``cancel_queued_job`` (which cancels one job by id).
Cancels every job currently in the QUEUED state — clear a backed-up
queue in one call instead of cancelling one job at a time.

- ``printer_name``: limit the sweep to one printer's queued jobs; omit
  to clear every queued job.
- ``dry_run=True``: preview exactly which jobs WOULD be cancelled and
  change nothing.  Run this first when clearing a large queue.

Safety: this never cancels a running print.  Only jobs still in the
QUEUED state are cancelled; each job's status is re-checked immediately
before cancelling, so a job that has already started printing (or
finished, or was cancelled elsewhere) is skipped rather than
interrupted.  Use ``cancel_print`` to stop the job that is actually
running.  Each cancel emits the same ``JOB_CANCELLED`` event as
``cancel_queued_job``.

Returns ``{success, dry_run, count, cancelled, skipped, message}`` —
``count`` always equals ``len(cancelled)``; ``skipped`` is a list of
``{job_id, reason}`` for jobs that were not cancelled.
:param printer_name: Limit the sweep to one printer's queued jobs; omit to
    clear every queued job.
:param dry_run: ``True`` previews exactly which jobs would be cancelled
    and changes nothing.  Run this first when clearing a large queue.

        Args:
            plan_id: The plan ID to cancel.
        

        Translates the model so it sits centered on the bed with its
        lowest point touching the build plate.

        :param file_path: Path to the STL file.
        :param bed_x_mm: Build plate X dimension (default 256).
        :param bed_y_mm: Build plate Y dimension (default 256).
        :param printer_id: Optional printer: a supported model id, or the
            name of a printer set up in Kiln.  When provided, its recorded
            bed size replaces the explicit dimensions.
        :param output_path: Output path (defaults to overwriting input).
        :returns: Dict with translation applied.

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.

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.

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

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.

        Works on Klipper (Moonraker), OctoPrint and Creality's
        Klipper-based printers.  Bambu Lab and Prusa Link printers manage
        their own firmware and answer ``UNSUPPORTED``.  Checking several
        machines in one call needs Kiln Business.

        Args:
            machine: The machine to check, by name.  Omitted, the machine
                Kiln is connected to.
            machines: Several machines to check in one call, by name.
                Each is reported on its own line.
            all_machines: Check every machine registered with Kiln.
        

        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.
        

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.

        When material is insufficient, says what the person can do with
        what they have: a spool on the shelf, a pause-and-swap.  Only
        when nothing they have will do does it end with one offer of
        help finding a filament.  Relay that offer as written and never
        suggest buying filament unless the person asks or says yes;
        then use ``find_closest_filaments``.  Suggestions that point at
        OTHER machines are a fleet-wide answer and need Kiln Business;
        the check itself — does THIS printer have enough — works on
        every tier.

        Args:
            printer_name: Name of the printer to check.
            required_grams: Amount of material needed in grams.
            material_type: Optional material type filter.
        

        Returns compatibility (yes/no), interface adhesion quality,
        notes on temperature management, and soluble support dissolution
        instructions when applicable.

        Use this when a user asks "can I print PLA with TPU?" or
        "what support material works with ABS?" or planning any
        multi-material / dual-extrusion print.

        Args:
            material_a: First material (e.g. "pla", "abs").
            material_b: Second material (e.g. "tpu", "hips", "pva").
        

        Use this whenever the user asks any tier / plan / subscription /
        paywall / access question — for example: "what tier am I on",
        "why does it say I need Pro", "do I have to pay for this",
        "what's my plan", "why isn't this Pro feature working", "did
        my subscription not activate", "what's the difference between
        Free and Pro", "I just paid but I'm still seeing free tier",
        "can I use the texture engine", "do I have access to fleet
        management", "what unlocks at Business", "how do I upgrade".

        Walks the live tier-resolution chain on the user's machine
        (OAuth session at ~/.kiln/auth_tokens.json → cached
        entitlement → free-tier fallback) and reports:

          - effective_tier: one of 'free', 'pro', 'business', 'enterprise'
          - resolution_chain: list of every step with which matched
          - matched_source: which step actually determined the tier
          - agent_summary: a plain-English one-liner you can show
            the user verbatim
          - pricing_url: link to send the user if they want to upgrade

        No arguments.  Free-tier safe — does NOT require a license
        to call.  Available to every user.

        JUST PAIRED, AND THE TIER LOOKS STALE?  Try this order, and do
        it yourself rather than handing the user a checklist:

          1. Call ``restart_server``.  This server caches what it
             resolved at startup, so a pairing that happened after it
             launched may simply not be visible to it yet.  A restart
             re-execs in place and is invisible to the user.
          2. Call this tool again.
          3. Only if the tier is STILL stale, ask the user to fully
             quit and reopen their AI app.  That is the one step they
             have to do by hand, so it is the last resort, not the
             first suggestion — and MCP clients differ (some reconnect
             to a restarted server on their own, some do not).

        Report the tier plainly whatever it turns out to be, Free
        included: pairing is not a purchase, and a free account that
        paired successfully must not be told it failed.

        Common interpretation:
          - effective_tier="free", matched_source="kiln_pro_install":
            kiln-pro not installed on this machine.  User can still
            use Pro features through Kiln's servers if signed in.
          - effective_tier="free", matched_source="default":
            kiln-pro installed but no auth — needs `kiln signin`.
          - effective_tier="pro" (or higher) with matched_source=
            "license_manager_resolve" and "oauth_session" matched=True
            in the chain: user is signed in via OAuth and the
            entitlement on file gives them this tier.

        Returns:
            dict with success/effective_tier/resolution_chain/
            matched_source/agent_summary/tier_rank/pricing_url.
        

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.

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.

        Returns compatibility status (compatible / needs_upgrade /
        not_compatible), any required hardware upgrades (enclosure,
        hardened nozzle, dry box), and practical notes.

        Use this when a user asks "can my Ender 3 print nylon?" or
        another specific printer/material question.

        Args:
            printer: Printer model ID (e.g. "ender3", "bambu_x1c",
                "prusa_mk4", "voron_2"). Use underscores, lowercase.
            material: Material to check (e.g. "nylon", "abs").
        

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.

        Unlike ``watch_print`` (which starts a background monitoring
        thread), this tool runs one check cycle and returns immediately.
        It is designed for quick "is the print OK right now?" queries
        from an agent without starting persistent background tasks.

        Checks performed:

        * **Printer connectivity** — is the printer online?
        * **Temperature** — are hot-end and bed within 15 °C of target?
        * **Print progress** — current completion, layer count, ETA.
        * **Error state** — any active firmware error codes.

        If *model_path* is supplied, adhesion risk is also evaluated via
        ``analyze_printability``.

        Args:
            printer_name: Named printer to query.  Omit for the default.
            model_path: Optional path to the model being printed.
                Enables geometry-based adhesion risk analysis.
            material: Filament material (e.g. ``"PLA"``, ``"ABS"``).
                Passed to adhesion analysis when *model_path* is provided.
            printer_id: Printer model ID (e.g. ``"bambu_a1"``).
                Used for printer-intelligence lookups.
        

        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.
        

        Returns a dict listing each backend (FreeCAD, Gmsh, the OCCT
        kernel, CadQuery) with its availability status and priority.
        If none is found,
        includes ``install_help`` (prose) and ``remedy`` (structured) —
        prefer ``remedy``: its ``actionable_by_caller`` flag tells you
        whether the user can fix this (``kiln install-step-backend``) or
        whether they're on a hosted server where they cannot.

        Call this before ``import_step_file`` to verify the system is
        ready for STEP conversion.
        

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

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

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

        ``stats`` covers this install: total records, unique models,
        printers, materials, and overall success rate.  ``community``
        adds the size of the shared pool everyone contributes to —
        counts only, available to anyone signed in.

        Works offline: the local numbers are always returned.
        

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

        Computes volume change, surface area change, dimension deltas,
        center-of-mass shift, the mesh-check delta, and an approximate
        Hausdorff distance showing how far the meshes differ spatially.

        Useful for verifying that a repair, rescale, or regeneration
        actually improved the model.

        :param file_a: Path to the reference (original) mesh.
        :param file_b: Path to the modified mesh.
        :returns: Dict with comparison metrics and ``meshes_identical`` flag.
        

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.

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

        Takes OpenSCAD source code OR a path to a .scad file, compiles
        it using the local OpenSCAD binary, and returns the path to the
        generated STL. Kiln's bundled BOSL2 and MCAD libraries are on
        OpenSCAD's library path (``include <BOSL2/std.scad>``).

        For surface() heightmap operations (photo emboss, lithophane),
        increase timeout to 600+ seconds.

        Kiln checks the compiled part is joined up.  A piece that floats
        with nothing under it is joined to nothing and prints as a loose
        part on supports, or not at all, so the make is REFUSED
        (``code: "FLOATING_PIECES"``; ``error`` names the pieces, how
        far they are from the nearest surface, and the fix): correct
        the geometry and compile again.  Separate parts that all sit on
        the bed are a plate and pass; a piece held inside the part (a
        ball in a cage, a pin in its knuckles) passes with a warning; a
        piece that touches the rest without overlapping it is named in
        ``warnings``.

        A compile where OpenSCAD could not find an included library, an
        imported file or a module is refused too: OpenSCAD leaves that
        part out and still exits cleanly, so the file would be missing
        pieces.  ``error`` names what was missing.

        Colour: pass ``color`` (a name such as ``"teal"`` or a hex) when
        the user asked for one, and the preview and the 3D stage show
        the part in it.  Left out, a single ``color("...")`` in the
        source is used.  It is how the part is SHOWN; it prints in
        whatever filament is loaded, and the result's ``color`` block
        says so.

        Round shapes: leave ``$fn`` out and Kiln cuts each curve by its
        size, writing that rule into the file it compiles.  Set ``$fn``
        only for a deliberate polygon (``$fn = 6`` for a hexagon).  A
        file that sets ``$fn``, ``$fa`` or ``$fs`` at the top compiles
        exactly as written, and the result's ``curve_resolution`` note
        says so.

        Named parts: a source may define each part as its own module and
        compose them in ``module main()``, drawing nothing at the top
        level; it compiles to ``main()``.  Kiln keeps generated designs
        this way, so a kept source compiles as it is.

        When you pass ``fastener``, the result carries a
        ``fastener_advice`` block saying the code compiled as written
        and nothing resized the hole for that fastener.  Kiln raises
        it once per session across every tool that can raise it.  Read
        its ``agent_instruction`` before repeating any of it.

        Args:
            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.
            scad_code: Valid OpenSCAD source code (provide this OR scad_path).
            scad_path: Path to a .scad file (provide this OR scad_code).
            timeout: Maximum compilation time in seconds (default 300).
            fastener: The fastener the user named, e.g. ``"M4"`` — pass
                only if they actually said one.  Kiln does NOT read your
                OpenSCAD looking for screw holes; guessing intent out of
                geometry would be wrong often. No argument, no advisory.
            color: The colour the user asked for, shown on the preview and
                the stage (a name or ``#rrggbb``).  Not a print setting.

        On failure (success=False) with ``alternative_printers`` and
        kiln-pro installed, the answer can carry a
        ``reroute_recommendation``: whether the failed job should
        move to one of those printers, and which.  Choosing between
        printers is Kiln Business; below
        it the answer says so once in ``reroute_recommendation_gated``.
        A failure that needs hands-on inspection of the printer is
        held where it is, in ``reroute_recommendation``, at every
        tier.  Recommendation only; the agent runs any move itself
        via ``submit_job`` / ``start_print``.

        Args:
            session_id: The session_id to complete.
            success: Whether the recovery was ultimately successful.
            notes: Final notes about the recovery outcome.
            alternative_printers: Optional other printers the job
                could move to (each with ``printer_id`` plus optional
                ``is_idle``, ``supported_materials``,
                ``build_volume_mm``, ``success_rate``).  Read only
                when ``success=False``.  Single-printer setups can
                omit this.
            completion_pct_at_failure: How far the failed print got
                (0.0–1.0); the recommendation weighs it.  Defaults
                to 0.
        

        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.

        Concatenates all triangle geometry from the input files into one
        output STL.  No boolean operations — bodies are simply combined.
        Useful for multi-part assemblies or adding components to a design.

        **See also:** ``merge_mesh_files`` for the same operation with
        a different parameter style, or ``merge_stl`` for positional
        offset support.

        :param file_paths: List of .stl/.obj/.glb file paths to merge.
        :param output_path: Path for the combined output STL.
        :returns: Dict with merge statistics.

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 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.
    plate_width: Print plate X dimension in mm (default 256 for legacy
        callers without a printer id).
    plate_depth: Print plate Y dimension in mm (default 256).
    material: Optional material the parts will be printed in (e.g.
        ``"PETG"``).  A spool on record in a clearly different
        material is then not named as one to load.
    printer_id: Optional supported printer model id.  When it resolves,
        its build volume overrides ``plate_width`` / ``plate_depth``.
        The composer centres an off-plate group on THIS plate, so name
        the printer whenever you know it — a group arranged for a
        larger or smaller bed and composed against the 256 default is
        re-centred onto a plate the machine does not have.

Returns:
    Dict with ``success``, ``output_path``, ``parts``, ``objects`` (build
    objects, after touching parts are joined), ``colours`` (extruder
    slots used), ``total_triangles``, ``total_vertices``, ``extruder_map``
    (which parts print from each slot), ``fits_bed`` (``False`` when the
    plate is bigger than its bed, ``None`` when it could not be measured),
    ``bed_fit`` (the sizes behind that verdict), and ``message``.  It also says
    whether the part 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.

        The **CAD-aware generation path** -- instead of asking text-to-mesh AI
        to guess at geometry, describe parts as a tree of primitives combined
        with boolean operations. Produces exact, deterministic, functional parts.

        **SAFETY DEFAULT (changed 2026-04-15):** ``center_on_bed=True`` is the
        default.  OpenSCAD primitives are natively centered on the model origin
        (``cylinder(h,r)`` produces geometry centered on X/Y = (0,0), which
        means half the geometry lives at NEGATIVE X/Y).  Sending such an STL
        to most FDM printers (Bambu, Prusa, Ender, Creality) — whose bed
        origin is the front-left corner — causes the nozzle to drive off-bed
        into the purge/wipe assembly on layer 1.  This happened once on a
        Bambu A1 (incident #0, 2026-04-15, nearly damaged the printer).

        With ``center_on_bed=True`` the output STL is translated so it sits
        centered on the build plate and its lowest point touches z=0.  Set
        ``center_on_bed=False`` only if your downstream flow expects
        origin-centered geometry (e.g. further CAD composition).

        **Operation format** -- each item is either a primitive or boolean:

        Primitive: ``{"type": "primitive", "shape": "<shape>",
        "params": {...}, "translate": [x,y,z], "rotate": [rx,ry,rz]}``

        Boolean: ``{"type": "boolean", "operation": "union|difference|intersection",
        "children": [op1, op2, ...]}``

        **Primitive shapes and params:**
        - cube: ``{"size": [x,y,z]}`` or ``{"size": scalar}``
        - cylinder: ``{"h": height, "r": radius}`` or ``{"h", "r1", "r2"}``
        - sphere: ``{"r": radius}``
        - cone: ``{"h": height, "r1": bottom_r, "r2": top_r}``
        - torus: ``{"major_r": ring_radius, "minor_r": tube_radius}``
        - wedge: ``{"width": w, "depth": d, "height": h}``
        - hex_prism: ``{"r": radius, "h": height}``  -- hexagonal (for nuts)
        - text: ``{"text": "string", "size": 10, "depth": 2}``
        - rounded_cube: ``{"size": [x,y,z], "radius": 1}``
        - pipe: ``{"h": height, "outer_r": 10, "inner_r": 8}``

        Requires OpenSCAD installed on the system.

        :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 operations: The part as a tree of operation dicts.  A
            primitive is ``{"type": "primitive", "shape": ..., "params": {...}}``
            with optional ``"translate": [x,y,z]`` and ``"rotate": [rx,ry,rz]``;
            shape is one of ``cube``, ``cylinder``, ``sphere``, ``cone``,
            ``torus``, ``wedge``, ``hex_prism``, ``text``, ``rounded_cube``,
            ``pipe``.  A boolean is ``{"type": "boolean", "children": [...]}``
            with ``"operation"`` ``union``, ``difference`` or ``intersection``.
            Shape params are listed in the tool description.
        :param output_path: Output path (defaults to temp file).
        :param center_on_bed: Translate output to bed-center (default True).
        :param bed_x_mm: Build plate X dimension for centering (default 256).
        :param bed_y_mm: Build plate Y dimension for centering (default 256).
        :param printer_id: Optional printer: a supported model id, or the
            name of a printer set up in Kiln.  When provided, its recorded
            bed size replaces the explicit dimensions.
        :returns: Dict with result path, SCAD code, triangle count, and
            (if centered) ``bed_centered=True`` + applied translation.

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 plans requiring human confirmation, transitions from
        ``awaiting_confirmation`` to ``executing``.

        Args:
            session_id: The session_id to confirm.
        

        A standing window is the person's "yes, for a while": inside it,
        prints start on the named printer without asking each time (each
        one still previewed first).  Only the person opens one — by
        picking "yes, and for the next…" in the approval dialog, or with
        ``kiln consent window`` at a terminal.  Nothing an agent can call
        opens or extends one.  Closing one is always allowed: see
        ``revoke_consent_window``.

        An entry with ``always: true`` is always allow: the person turned
        it on for one printer — at a terminal, or on their Kiln account
        page (``opened_via`` says which) — it has no end (``until`` is
        null), and prints there start without asking until it is turned
        off.  ``turned_off`` lists any that Kiln turned off itself in the
        last day because a different printer was set up under the name.

        Args:
            printer_name: Show only the window covering this printer.
                Omit for every open window.
        

        Adds an anonymous print record for community aggregation.
        Only geometric signatures and settings are stored — never
        file contents, user IDs, or file paths.

        Args:
            geometric_signature: Geometric signature from fingerprinting.
            printer_model: Printer model name.
            material: Material used.
            settings: The slicer settings the print used, as a flat
                name→value dict (e.g. ``{"layer_height_mm": 0.2,
                "infill_percent": 20, "nozzle_temp_c": 215}``).  Stored
                as given and hashed for matching; no key is required.
            outcome: ``"success"``, ``"failed"``, or ``"partial"``.
            quality_grade: One of ``"A"``, ``"B"``, ``"C"``, ``"D"``,
                ``"F"`` (default ``"B"``).
            failure_mode: Optional failure description.
            print_time_seconds: Print duration in seconds.
            job_id: The print's job id when known — it anchors the
                federation dedupe key, so a print that was also
                watched (or recorded via ``record_print_outcome``)
                ships to the community pool once, not twice.
            geometric_signature_v2: ``fingerprint_model``'s
                ``geometric_signature_v2``.  Pass it: it is what keeps
                this contribution from being averaged into a different
                design that shares the older signature.
        

        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.
        

        Provide ONE of ``model_path``, ``model_url``, or ``prompt``.
        Returns a quote with local and fulfillment options. Call
        ``print_service_quote`` with the order ID to confirm.

        Args:
            model_path: Local path to a 3D model file.
            model_url: URL to download a 3D model.
            prompt: Text prompt for AI model generation.
            material: Material type (default ``"pla"``).
            intent: Print intent — ``"strong"``, ``"pretty"``, or ``"cheap"``.
            quantity: Number of copies (default 1).
            color: Desired color (optional).
            prefer_local: Prefer local printing (default True).
            printer_name: Specific local printer name (optional).
            max_budget_usd: Maximum budget in USD (optional).
        

        Slices the mesh perpendicular to the chosen axis and returns
        contour polygons and cross-sectional area.  Useful for inspecting
        internal geometry (e.g., wall thickness, hole placement).

        :param file_path: Path to STL file.
        :param plane: Axis perpendicular to the cut -- "x", "y", or "z".
        :param offset_ratio: Fractional position 0.0-1.0 (default 0.5 = midpoint).
        :param offset_mm: If set, absolute position in mm (overrides offset_ratio).
        :returns: Dict with contour_count, contour_points, cross_section_area_mm2.
        

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 put on the surface — file path (PNG/JPG/SVG)
    or ``"text:..."`` for text.
:param face: Which face to decorate: ``"auto"`` (largest flat face),
    ``"top"``, ``"bottom"``, ``"front"``, ``"back"``, ``"left"``,
    ``"right"``, or ``"wall"`` (wraps text, an SVG logo or a line-art
    mark around the upright round wall of a cup, jar, vase or bowl;
    STL and deboss only; a photo relief goes on a flat face).  On
    ``"wall"``, *scale* is the letter height or mark width as a share
    of the wall, *absolute_size_mm* pins it exactly, and
    *offset_x/y_mm* / *placement* do not apply; the response reports
    the size and depth used.  Placement on ``top``/``bottom``/``front``
    is exact; on ``back`` content may land rotated 180°.
:param depth_mm: Emboss/deboss depth in mm.  ``0`` picks a depth for
    *material* and for the content (a photo relief is bounded by how
    much part sits under the face); the response reports the depth
    used.
:param mode: ``"deboss"`` (cut into surface) or ``"emboss"`` (raised).
:param scale: Fraction of the face to cover (0.1-1.0, default 0.7).
:param material: Material for depth auto-tuning (default ``"PLA"``).
:param content_type: Override auto-detection: ``"svg"``, ``"image"``,
    ``"text"``.  Default ``"auto"`` detects from *content*.
:param offset_x_mm: Placement offset from the face centre along the
    face's own WIDTH axis, in mm — positive slides the content
    toward the content's right.  Offsets are FACE-LOCAL: they are
    applied inside the face-aligning rotation, so they always move
    the art in the face plane, never along its normal.
:param offset_y_mm: Same, along the face's HEIGHT axis — positive
    slides the content toward the content's top.  Measured
    world-axis mapping per face: top +y, bottom −y, front +z,
    back −z.
:param image_style: Image preprocessing style: ``"auto"`` (a logo or
    line-art image is traced as ``"stencil"``; a photo is sculpted and
    the look chosen for it), ``"coin"``, ``"cameo"``, ``"etched"``,
    ``"sketch"``, ``"medallion"``, ``"stencil"`` (alias ``"logo"``).
    An unknown style is refused naming the accepted list.
:param placement: Named position preset for content placement.
    ``"center"`` (default), ``"top"``, ``"bottom"``, ``"top-rim"``,
    ``"bottom-rim"``.  Use ``"bottom"`` for text below a centered
    portrait on a coaster.  Manual ``offset_x/y_mm`` is added on
    top of the preset for fine-tuning.
:param svg_id: Target a specific SVG group by ``id`` attribute when using
    SVG ``import()`` fallback on OpenSCAD 2024+.  E.g. ``"icon"`` targets
    ``<g id="icon">``.  No effect on the native polygon path.
:param svg_layer: Target a specific SVG layer by ``layer`` attribute when
    using SVG ``import()`` fallback on OpenSCAD 2024+.  E.g.
    ``"foreground"`` targets a layer named ``foreground``.
:param template_id: Optional template ID (e.g. ``"nameplate"``), used
    for provenance tracking only.  To auto-fill ``face``, ``depth_mm``,
    ``mode``, ``scale``, and ``image_style`` from a template's curated
    decoration profile, call ``resolve_template_decoration()`` first
    (kiln-pro) and pass its results explicitly.
:returns: Dict with output STL path, preview info, and metadata.
:param absolute_size_mm: Exact letter height (text) or mark width (marks)
    in mm, overriding *scale*; ``0`` leaves *scale* in charge.

        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.
        

        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.
        

        Args:
            key: The key of the note to delete.
            scope: The scope namespace (default ``"global"``).
            printer_name: If provided, targets ``"printer:<name>"`` scope.
        

        Args:
            cache_id: The unique cache ID of the model to delete.
        

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

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

        Args:
            name: Profile name to delete.
        

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

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

        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.
        

        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.
        

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.

        Analyzes a base model to find recessed regions (circular or rectangular
        pockets) on top and bottom faces. Call this before compose_models or
        multi_material_print to know pocket dimensions for overlay geometry.

        :param file_path: Path to the STL file to analyze.
        :param min_depth_mm: Minimum pocket depth to report (default 0.3mm).
        :returns: Dict with pocket list, dimensions, and positions.
        

        Examines current telemetry data and optional historical snapshots
        to identify failure conditions such as thermal runaway, layer shift,
        filament runout, adhesion loss, nozzle clogs, and more.

        The readings passed here are judged, not announced: a failure
        found in them is kept (for ``plan_failure_recovery``) and marked
        ``readings_from: "caller"``, but no failure alert goes out and the
        printer's own print watchdog keeps running.  Only readings Kiln
        takes off the printer itself, while it watches a print, announce
        a failure.

        Args:
            printer_name: Identifier of the printer to analyze.
            telemetry: Current telemetry snapshot with keys like
                ``hotend_temp``, ``bed_temp``, ``connected``,
                ``filament_detected``, etc.
            telemetry_history: Optional list of recent telemetry snapshots
                for trend analysis (newest last).
            job_info: Optional current job metadata with keys like
                ``file_name``, ``layer``, ``total_layers``, ``z_mm``.

        Returns a failure report dict if a failure is detected, or a
        success dict with ``failure_detected: False`` if no failure found.
        

        Goes deeper than ``analyze_mesh_geometry`` (which focuses on printability
        scoring and overhang detection). Use this when you suspect mesh defects
        or when ``repair_mesh`` didn't fix the issue.

        Analyzes: self-intersections, inverted/inconsistent normals, degenerate
        (zero-area) faces, floating fragments, detailed hole reporting (count,
        size, location), and polygon count assessment for FDM printing.

        Returns a structured report with severity level, defect list, and
        actionable fix recommendations (specific MeshLab/Blender steps).

        Requires the optional ``trimesh`` package (``pip install trimesh``).
        Supports STL, 3MF, OBJ, PLY, OFF, GLB, and GLTF formats.  A 3MF
        holding several objects is read as one body — the report describes
        the whole plate.

        Use this BEFORE slicing to catch problems that would cause print
        failures or slicer errors.  Complements ``validate_generated_mesh``
        (basic checks) and ``analyze_printability`` (print-readiness scoring).

        Args:
            file_path: Path to a mesh file (STL, 3MF, OBJ, PLY, OFF, GLB,
                GLTF).
        

        Unlike ``analyze_print_failure`` (which requires a job_id and
        analyzes historical data), this tool works in real-time by
        reading the current printer state and optionally analyzing
        the model that was being printed.

        Combines printer temperature deltas, bed adhesion analysis,
        overhang geometry, material properties, and printer intelligence
        to produce a ranked diagnosis with actionable fixes.

        Args:
            printer_name: Printer to diagnose.  Omit for the default printer.
            model_path: Path to the model file that was being printed.
                Enables geometry-based diagnosis (adhesion, overhangs).
            material: Filament material (e.g. ``"ABS"``, ``"PLA"``).
            printer_id: Printer model ID (e.g. ``"bambu_a1"``).
                Enables printer-specific intelligence lookup.
        

        Version IDs are interpreted as ``<design_id>:<version_number>``
        (e.g. ``my-coaster:2``).  If no colon is present the string is
        treated as a plain version number and the tool will attempt to
        locate a design that contains that version.

        Args:
            version_id_a: The "from" version in ``design_id:N`` format.
            version_id_b: The "to" version in ``design_id:N`` format.

        Returns:
            A unified diff string showing changes from version A to B.
        

        Uses mDNS/Bonjour and HTTP subnet probing to find OctoPrint,
        Moonraker/Creality, Bambu Lab, Elegoo, and Prusa printers on
        the local network.

        Args:
            timeout: Maximum scan duration in seconds (default 5).

        Returns a list of discovered printers with host, port, type, and
        whether the API is reachable.  Each one also carries
        ``address`` -- pass it as ``register_printer``'s ``host``; it
        keeps the port the printer answered on -- and ``to_connect``:
        what the person still has to supply and where they find it
        (``still_needed``), and anything to switch on in the printer
        first (``first``).  Ask for exactly those, in plain words, then
        add the printer with ``register_printer``.  ``suggested_name``
        is a name for it with no address or serial in it; propose that
        name, and use the person's own name when they give one.
        

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

        The result says where the model came from (``came_from``: the
        provider and the prompt) and, when the provider was asked for a
        shape and not a size, that its numbers are not millimetres
        (``size_check``).  A note beside the file keeps where it came
        from, so the stage and design history can say so later.

        Args:
            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.
            job_id: Job ID of a completed generation job.
            provider: Provider that owns the job: ``"meshy"``, ``"gemini"``,
                ``"tripo3d"``, ``"stability"`` or ``"openscad"``.  Default
                ``"meshy"``.
            output_path: Directory to save the file.  Defaults to Kiln's
                own ``kiln_generated`` output folder.

        **Community models are unverified.** Always preview dimensions and
        validate the mesh (``validate_generated_mesh``) before printing.
        Models with high download counts and positive ratings are generally
        safer.  AI-generated or untested designs can damage delicate printer
        hardware — prefer proven blueprints when possible.

        Args:
            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.
            file_id: Numeric file ID (from ``model_files`` results).  If
                omitted and ``model_id`` is provided, downloads all files
                for the model.
            dest_dir: Local directory to save into.  Default: Kiln's own
                downloads folder in the temp directory (the reply names
                the path).
            file_name: Override the saved file name (single-file mode only).
                Defaults to the original name from the marketplace.
            model_id: Model/thing ID.  When ``file_id`` is omitted,
                all files for this model are downloaded.
            source: Marketplace source — ``"thingiverse"`` (default),
                ``"myminifactory"``, etc.
            download_all: When True, downloads all files for the model
                regardless of whether ``file_id`` is provided.

        A downloaded GLB is handed on as an STL beside it, because the
        stage, the slicer and printers cannot open a GLB: its
        ``local_path`` is the STL, and ``conversion`` names the
        original, which stays on disk (``conversion_failed`` says so
        when a GLB cannot be read).  The stage opens on the first
        downloaded file it can draw, and
        the result measures that file (``validation``, ``dimensions``;
        ``size_check`` when its size reads like a units mix-up) and says
        where the files came from (``came_from``: the marketplace and,
        when its listing could be read, the designer, license and page).
        A note beside each file keeps where it came from, so the stage
        and design history can say so later; ``show_on_stage(path)``
        opens any of the other files.  Then upload to a printer with
        ``upload_file`` and print with ``start_print``.

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

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.

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

        Enterprise feature. Reports whether encryption is active on
        this computer, whether the local encryption key is configured,
        and whether the cryptography library is installed.  On a
        machine where encryption at rest is not installed, it answers
        that encryption is not active here, in the same shape, and
        says what enables it.  ``account_files`` says, on every
        install, what is true of the print files kept in the person's
        Kiln account: Kiln's servers encrypt those with a key held
        there.  Local files on this computer are encrypted only when
        the local key is set and encryption is installed here.
        

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

        Works from dimensions alone — no file, no slicing, no generation
        needed.  Use this to answer "how long will it take?", "how much
        will it cost?", and "how much filament?" before committing to a
        design.

        **Two ways to specify dimensions:**

        1. **Direct dimensions** — provide ``width_mm``, ``depth_mm``,
           ``height_mm`` explicitly.
        2. **Template** — provide ``template_id`` (e.g. ``"phone_stand"``,
           ``"box_with_lid"``) and optional ``template_overrides`` to use
           the template's default dimensions.

        **Multi-material prints:** Pass comma-separated materials
        (e.g. ``"PLA,PLA"`` for two-color) with optional fractions
        (e.g. ``"0.85,0.15"`` for body + accent).  The tool estimates
        per-filament usage and tool change overhead automatically.

        Returns time estimate, per-filament weight/length/cost breakdown,
        electricity cost, total cost, and tool swap count.

        :param width_mm: Part width (X) in mm.  Required if no template.
        :param depth_mm: Part depth (Y) in mm.  Required if no template.
        :param height_mm: Part height (Z) in mm.  Required if no template.
        :param template_id: Design template ID (e.g. ``"phone_stand"``).
            Resolves dimensions from template defaults.  Overrides
            width/depth/height if provided.
        :param template_overrides: JSON string of template parameter
            overrides (e.g. ``'{"phone_width": 85}'``).
        :param materials: Comma-separated material names
            (e.g. ``"PLA"`` or ``"PLA,PLA"`` for two-color).
        :param material_fractions: Comma-separated volume fractions
            (e.g. ``"0.85,0.15"``).  Must match materials count and sum
            to 1.0.  Default: body gets 85%, accents split the rest.
        :param material_roles: Comma-separated role labels
            (e.g. ``"body,accent"``).  Default: auto-generated.
        :param infill_percent: Infill density override (0-100).
            Default: from printer profile or 20%.  Pass ``-1`` for auto.
        :param layer_height_mm: Layer height override.  ``0`` = auto.
        :param nozzle_mm: Nozzle diameter in mm.  Leave unset for the
            nozzle Kiln has for ``printer_id`` (or the only printer it
            knows of), else 0.4.
        :param wall_layers: Number of perimeter shells (default 3).
        :param printer_id: Printer model for speed/setting lookup
            (e.g. ``"bambu_a1"``, ``"prusa_mk4"``).
        :param tool_changer_addon: Optional multi-material add-on ID.
            Overrides the printer's built-in tool change timing.
            Examples: ``"creality_cfs"`` (K1 series),
            ``"mosaic_palette3"`` (universal), ``"coprint_kcm"``
            (Klipper printers), ``"chameleon_mk4"`` (universal),
            ``"elegoo_canvas"`` (Centauri Carbon 2).
            Use ``list_multi_material_addons`` to see all options.
        :param electricity_rate: Cost per kWh in USD (default 0.12).
        :param printer_wattage: Printer power in watts (default 200).
        

        For STL/OBJ files, use ``slice_and_estimate`` instead — it slices
        and estimates in one step.

        The slicer's own ``filament used`` totals are the filament
        figures when the file carries them; otherwise Kiln counts the
        extruding moves itself.  ``estimate.filament_source`` says which,
        and a ``warnings`` entry names both numbers when Kiln's count
        sits more than 5% from the slicer's total.

        Each filament is priced as the material the file was sliced
        for; ``estimate.filaments`` lists them and
        ``estimate.material_source`` says where the material came from.
        When Kiln's servers answer, the estimate also
        carries a ``cost_intelligence`` field; what it holds depends on
        the tier.

        Args:
            file_path: Path to the G-code file.
            material: Filament material (PLA, PETG, ABS, TPU, ASA, NYLON,
                PC, …).  Leave empty to use what the file was sliced
                for, PLA when it names nothing; a named material prices
                every filament.
            electricity_rate: Cost per kWh in USD (default 0.12).
            printer_wattage: Printer power consumption in watts (default 200).
            printer_id: Optional registered printer the print is for;
                passed on with the file when kiln-pro is asked.
        

        Computes filament weight, length, and cost based on mesh volume,
        infill percentage, wall shell count, and material density.  The
        walls are as wide as the nozzle, and the reply's ``nozzle`` says
        which size was used and where it came from.

        **See also:** ``estimate_print_cost_from_mesh`` for a richer
        estimate that includes support material, adhesion, and electricity.

        Supported materials: pla, petg, abs, tpu, asa, nylon, pc, pla+,
        carbon_fiber_pla.

        :param file_path: Path to mesh file (.stl, .obj, or .glb).
        :param material: Material type (default "pla").
        :param infill_pct: Interior fill percentage 0-100 (default 20).
        :param wall_layers: Number of perimeter shells (default 3).
        :param cost_per_kg: Override material cost in $/kg (0 = use default).
        :param nozzle_mm: Nozzle size in mm.  Left out, Kiln uses the
            nozzle of the only printer it knows of, else its default.
        :returns: Dict with weight, filament length, cost, and ``nozzle``.
        

        Divides the plastic the part needs by the rate a print head lays
        it down, plus per-layer overhead.  It is a planning figure for a
        printer it is not told about: ``range_seconds`` is how far a real
        slice has sat from it, and the printer is most of that spread.

        Unlike estimate_print_time (which slices the part with the
        printer's profile, and is the real answer when a slicer is
        installed), this works directly on mesh files before slicing.

        :param file_path: Path to a mesh (.stl, .obj, .glb, .3mf) or a CAD
            file (.step, .stp), which is converted automatically.
        :param layer_height_mm: Layer height for slicing.
        :param print_speed_mm_s: Average print speed in mm/s.
        :param material: Material hint (affects per-layer overhead).
        :returns: Dict with estimated time, its range, layer count,
            deposited plastic, assumptions, and note.
        

        Uses the divergence theorem to compute mesh volume, then applies
        material density, infill ratio, and shell fraction for a realistic
        weight estimate.

        :param file_path: Path to a mesh (.stl, .obj, .glb, .3mf) or a CAD
            file (.step, .stp), which is converted automatically.
        :param material: Material name (pla, abs, petg, tpu, nylon, etc.).
        :param infill_percent: Infill percentage 0-100 (default 20).
        :param wall_thickness_mm: Perimeter wall thickness in mm (default 1.2).
        :returns: Dict with volume, weight estimates, bounding box.
        

        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.
        

        Calculates material, support, adhesion, and electricity costs directly
        from mesh geometry — no G-code or slicing required. Includes a detailed
        cost breakdown and actionable recommendations to reduce cost.

        Supported materials: pla, pla+, petg, abs, tpu, asa, nylon, pc,
        cf-pla, silk-pla, hips, pva, pp, peek.

        Args:
            file_path: Path to a mesh (.stl, .obj, .glb, .3mf) or a CAD
                file (.step, .stp), which is converted automatically.
            material: Material type (default "pla").
            infill_percent: Interior fill percentage 0-100 (default 20).
            wall_layers: Number of perimeter shells (default 3).
            layer_height_mm: Layer height in mm (default 0.2).
            nozzle_mm: Nozzle diameter in mm.  Leave unset for the only
                printer Kiln knows of, else 0.4; ``nozzle`` in the reply
                says which.
            include_supports: Estimate support material cost (default False).
            support_density: Support infill percentage (default 15).
            adhesion_type: Bed adhesion type: "none", "brim", or "raft".
            electricity_rate: Electricity cost in $/kWh (default 0.12).
            printer_wattage: Printer power consumption in watts (default 200).
        

        Breaks a print into phases -- preparing, printing, cooling, and
        post-processing -- from how far it has got and how long it has
        run.  When the printer has finished enough prints Kiln started,
        ``learned_time_left`` says when this one should end by its own
        record (the slicer's time for the file, as this printer really
        prints it), beside the printer's own countdown.

        Supply ``elapsed_seconds``, ``total_layers``, and ``current_layer``
        when available; any omitted values will be read from the printer's
        live status.

        :param printer_name: Printer running the job.
        :param elapsed_seconds: Seconds elapsed since print start.  Omit to
            read from printer status.
        :param total_layers: Total layer count for the job.  Omit to read
            from printer/G-code metadata.
        :param current_layer: Current layer being printed.  Omit to read
            from printer status.

        See also: ``printer_status()``, ``get_print_outcomes()``.
        

        Slices the model and parses the G-code for print time, filament
        length/weight, and layer count.

        For **already-sliced** G-code files, pass the ``.gcode`` path
        directly — it will be parsed without re-slicing.

        Weight needs a filament density, which lives on a filament
        profile; Kiln's bundled profiles describe a PRINTER and name no
        filament, so pass ``material`` to get a weight.  Without it the
        weight is reported as absent rather than guessed — a key missing
        from the result means the slicer could not answer it, never that
        the answer is zero.

        **See also:** ``estimate_material_cost`` for weight and cost from
        a mesh with your own price per kg, and ``slice_and_estimate`` for
        a fuller analysis with printability scoring.

        :param file_path: Path to STL/3MF/OBJ or .gcode file.
        :param profile: Optional slicer profile path.
        :param printer_id: Optional printer model ID for bundled profile
            (e.g. ``"bambu_a1"``).  Used when no explicit profile is given.
        :param slicer_path: Optional explicit slicer binary path.
        :param material: Optional filament family (``"PLA"``, ``"PETG"``,
            …) used only as a density source for the weight.
        :returns: Dict with time, filament, and layer estimates.
        :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"``.  An
            estimate never refuses because of the plate: with no safe
            spot named the estimate is for the part on an empty plate
            and ``plate_note`` says so.  Not read for a ``.gcode`` input.
        

        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.
        

        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.
        

        Analyzes the mesh for overhangs and estimates the volume of
        support material needed to print the model in its current
        orientation.

        Args:
            file_path: Path to an STL or OBJ mesh file.
            max_overhang_angle: Maximum overhang angle in degrees
                before supports are needed (default 45).
        

        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.
        

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

        Enterprise feature. Returns the full audit log with optional filters
        for date range, tool name, action type, and session ID.

        Args:
            start_time: Unix timestamp lower bound (0 = no filter).
            end_time: Unix timestamp upper bound (0 = no filter).
            format: Output format, ``"json"`` or ``"csv"``.
            tool_name: Filter by MCP tool name.
            action: Filter by action: ``"executed"``, ``"blocked"``,
                ``"rate_limited"``, ``"auth_denied"``,
                ``"preflight_failed"`` or ``"dry_run"``.  Empty for all.
            session_id: Filter by agent session ID.
        

        Converts STL/OBJ/GLB to 3MF, a ZIP-based XML format used by
        PrusaSlicer, OrcaSlicer, and Bambu Studio.  3MF is more compact
        and supports metadata better than STL.

        :param file_path: Path to the input mesh file.
        :param output_path: Output 3MF path.  Auto-generated if empty.
        :returns: Dict with the output file path.
        

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

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.

        3MF files are ZIP archives containing XML mesh geometry.  This tool
        parses the embedded model, extracts all mesh objects, and writes a
        binary STL file ready for slicing, multi-copy printing, or further
        mesh operations.

        .. note::
            For extracting a single object's **G-code** from a multi-object
            Bambu .gcode.3mf file, use ``extract_plate_object`` instead.
            Use ``list_plate_objects`` to discover available objects.

        Works with both standard 3MF files and Bambu Studio .gcode.3mf files
        (which bundle both G-code and the source model).  When multiple
        objects exist they are merged into a single STL.

        :param file_path: Path to the .3mf or .gcode.3mf file.
        :param output_path: Output STL path (auto-generated if empty).
        :returns: Dict with output path, triangle/vertex counts, and dimensions.

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.

        Args:
            printer_name: Filter by printer name.
            failure_type: Filter by failure type.
            limit: Maximum records to return (default 20).

        The response declares its own SCOPE: these are the failures
        THIS machine recorded, and ``scope.local.total_records``
        gives the store's full matching count when ``limit``
        truncated the page.
        

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

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

        Returns printers with the matching material, sorted by
        remaining stock (most first).  Optionally filter by colour
        and minimum remaining grams.

        Args:
            material_type: Material type to find (e.g. ``"PLA"``).
            color: Optional colour filter.
            min_grams: Minimum remaining grams (default 0).
        

        Uses geometric signature matching and surface area / volume
        similarity to locate models with similar geometry.

        Args:
            file_hash: SHA-256 hash of the model file.
            geometric_signature: Geometric signature from fingerprinting.
            surface_area_mm2: Surface area in mm^2 (for fuzzy matching).
            volume_mm3: Volume in mm^3 (for fuzzy matching).
            complexity_score: Complexity (for fuzzy matching).
            limit: Maximum results (default 10).
            threshold: Similarity threshold 0.0-1.0 (default 0.8).
            geometric_signature_v2: ``fingerprint_model``'s
                ``geometric_signature_v2``.  Pass it: without it,
                models that merely share the older signature are
                reported as the same geometry.
        

        Reads the STL file and produces a fingerprint containing: SHA-256
        file hash, triangle/vertex counts, bounding box, surface area,
        volume, overhang ratio, complexity score, and TWO geometric
        signatures for similarity matching.

        ``geometric_signature_v2`` is the one to carry into
        ``record_print_dna`` / ``predict_print_settings`` /
        ``find_similar_prints`` / ``contribute_community_print``: it
        tells this design apart from a different one that happens to
        share the older ``geometric_signature``.  Pass both — the
        older key is what joins this print to history recorded before
        v2 existed.

        Args:
            file_path: Path to the STL file to fingerprint.
        

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

        Returns the current monitoring state, including any captured snapshots
        once monitoring is complete.  A fault the printer has stopped for
        rides this result as ``printer_fault`` (as it rides every tool
        result while Kiln's watchdog sees it standing); the monitor's own
        fields describe the first layer, not the machine's fault state.

        Args:
            monitor_id: The monitor ID returned by ``start_monitored_print``.
        

        For live printer status (current state/temps), use ``fleet_status``.
        Returns statistics for every registered printer including total prints,
        success rate, average print duration, and total print hours.  Also
        includes fleet-wide aggregate metrics.

        Requires Business license.
        

        This name reads nothing any more: it only points there.
        :param job_id: Ignored: this name reads nothing.  Use
            ``split_plan_status`` or ``job_status``.
        

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

        There is one fleet view.  ``fleet_status`` lists every printer;
        with ``by_site=True`` the same answer is also grouped by site,
        with each site's idle, busy and needs-repair printers.  This name
        answers nothing any more: it only points there, so an old guide
        or habit still leads somewhere.  It reads no printer.
        

        One copy or many, ``plan_multi_copy_split`` reads every printer's
        plate, plans which printers take the part and where, and queues it
        on the person's go, the printers running side by side.  For one
        print on one named printer, ``submit_job`` with ``printer_name``.
        This name queues nothing any more: it only points there, so an old
        guide or habit still leads somewhere.  It reads no printer.
        :param file_path: Ignored: this name queues nothing.  Use
            ``plan_multi_copy_split`` or ``submit_job``.
        :param printer_name: Ignored: this name queues nothing.
        :param material: Ignored: this name queues nothing.
        :param priority: Ignored: this name queues nothing.
        :param idempotency_key: Ignored: this name queues nothing.
        :param preview_token: Ignored: this name queues nothing.
        

        Lightweight overview of fleet capacity. For full printer details, use
        ``fleet_status``. For historical analytics, use ``fleet_analytics``.
        

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.

        Combines current stock with historical consumption rate to
        estimate remaining days and urgency level (ok/low/critical).

        Args:
            material_type: Material type to forecast (e.g. ``"PLA"``).
            days_ahead: Days of history for rate estimation (default 30).
        

        Args:
            order_id: Order ID to cancel.

        Only orders that have not yet shipped can be cancelled. When the
        print service has nothing to cancel (an unpaid order is never
        made) or cancels only on a written request, the error message
        says which and how; pass it on to the person as it is.