Moket Help

A guide for AI agents

This page is part of the Moket skill: it is written for AI agents, which read it as Markdown. Values in angle brackets in the examples stand for ids an agent gets from Moket.

Working with plans ​

Every change in Moket, by a person, Moket AI or an agent, is a command on the document's Command Bus. You never edit a document directly: you propose a plan with preview_plan, Moket builds it, measures it and shows it to the user, and it applies when it is safe and the user's approvals allow it. This guide is how to do that well on any document. The guides for parts, sketches, assemblies, mechanisms and drawings say what to put in the plans.

Look before you change ​

  1. Read the document first: inspect_document on a part, inspect_assembly on an assembly, inspect_drawing on a drawing. They give the parameters, the history or the components, what is broken and the revision.
  2. Then read what the request involves: get_feature for a feature's full parameters, get_sketch for a sketch, query_geometry for faces and edges with their topological names, measure for sizes and distances, get_view for a drawing view's edges.
  3. When the user says "this" or "these", call get_selection: it gives what they selected, with names.
  4. Before using a command or feature type for the first time in a conversation, read it with describe_commands ({"types":["core.hole","joint.create"]}): its JSON Schema and notes are the exact shape Moket accepts. It answers for the document you call it on: drawing commands on a drawing, assembly commands on an assembly.

A plan ​

preview_plan takes a short summary, steps with labels a person understands, and the commands of each step. All steps are previewed together as one transaction: it must rebuild without errors, or nothing changes.

json
{
  "summary": "Plate 120 x 80 x 6 with four corner holes",
  "steps": [
    {
      "label": "Parameters",
      "commands": [
        {
          "type": "parameter.create",
          "id": "$width",
          "name": "width",
          "expression": "120 mm"
        },
        {
          "type": "parameter.create",
          "id": "$depth",
          "name": "depth",
          "expression": "80 mm"
        },
        {
          "type": "parameter.create",
          "id": "$thickness",
          "name": "thickness",
          "expression": "6 mm"
        }
      ]
    },
    {
      "label": "Plate",
      "commands": [
        {
          "type": "sketch.template",
          "id": "$outline",
          "name": "Outline",
          "template": {
            "kind": "rectangle",
            "width": "width",
            "depth": "depth"
          }
        },
        {
          "type": "feature.create",
          "id": "$base",
          "featureType": "core.extrude",
          "name": "Plate",
          "params": {
            "sketch": "$outline",
            "operation": "new",
            "body": "$plate",
            "distance": "thickness",
            "direction": "normal"
          }
        }
      ]
    }
  ],
  "checks": [
    {
      "label": "Plate volume",
      "quantity": "volume",
      "a": { "kind": "body", "body": "$plate" },
      "min": 57000,
      "max": 58000
    }
  ]
}
  • Ids and placeholders. New entities need ids. Write placeholders that start with $ ("$base", "$holes"); Moket gives each a UUID and returns the mapping in ids. Use the real ids in later plans. Placeholders work anywhere in the plan: inside topological names ("f($base:end)" is the end face of the extrude $base), in checks ({"kind":"body","body":"$plate"}), as configuration column keys.
  • Values have units. Write "24 mm", "45 deg", "0.5 in"; a bare number is in the document's units. Expressions can use parameters: "width - 2 * margin".
  • Parameters for what a person would change. Thicknesses, diameters, spacing, counts get named parameters; reuse the document's existing ones instead of repeating a number.
  • Names for people. Name the document with document.rename when you make a new one, and give features and components names a person would use ("Mounting holes", not "Hole 3").
  • Never invent a topological name. Face and edge names come from query_geometry, measure, get_selection or get_view, or are built from your own placeholders in the forms the feature notes give. Never edit one.

Checks ​

Add a check for every limit the user states or implies: a minimum wall, an edge distance, a mass, no interference. Moket measures them on the previewed geometry and shows the results; a plan that fails one waits for the user.

  • Parts: distance (between a and b, mm), angle (degrees), radius, length (an edge), area (a face, mm²), volume (a body, mm³), mass (a body, g). Items are {"kind":"body","body":<id>} or {"kind":"face"|"edge","name":<topological name>}.
  • Assemblies, without items: interference (overlapping volume, "max":0 for none) and dof ("min":1,"max":1 for exactly one free motion).

Never claim a measurement you did not get from a tool.

When it applies ​

A previewed plan that rebuilds, passes every check and loses no reference applies at once (its answer says autoApplied), unless the user asked to approve that kind of change: every change, deleting or suppressing, or changing what is already there. Anything else waits for the user to click Apply (waitsForApply says why). So:

  • Never preview a plan that does more than the user asked: it may apply right away.
  • When the request cannot be met as stated, preview nothing, explain why with the numbers you measured, and offer concrete options.
  • After a plan applies, say briefly what changed. When it waits, say what it does and that it waits for the user.
  • A new preview replaces the one before it.

When a preview fails ​

  1. Read its problems: each names the step, the command or feature and what went wrong.
  2. Fix the plan and preview again. After three failed attempts, stop and explain what blocks you.
  3. Never change a value the user asked for, or anything they did not ask to change, to make a plan pass.
  4. If a call fails without an answer (a timeout or a network error), the plan may still have applied: inspect the document and compare its revision before you send it again.

Tell Moket's team ​

When a tool or command behaves differently from its description or notes, when you need something Moket cannot do, or when a description misled you, send it once with send_feedback (what you did, what happened, what you expected), then go on with the task. Not for the user's own design questions, and never with the user's private data.

Answering the user ​

Answers are short and in the user's language. Mention values with units. Do not paste JSON or repeat every step: the user sees the plan. Notes in square brackets in the conversation tell you what the user did with a plan (applied, discarded, changed by hand).

Moket Help