Document and object tools

add_to_group(doc_name: str, group: str, members: list[str]) -> list[TextContent | ImageContent]

Move existing objects into a group.

Group and members accept either object names or take_snapshot uids.

Args:
    doc_name: Document containing the objects.
    group: Group name or uid.
    members: List of object names / uids to move into the group.

create_document(name: str) -> list[TextContent]

Create a new document in Parashell.

Args:
    name: The name of the document to create.

create_group(doc_name: str, name: str, members: list[str] | None = None, parent: str | None = None) -> list[TextContent | ImageContent]

Create an App::DocumentObjectGroup and optionally populate it.

Groups are a lightweight container - useful for organizing a flat object
list into Base / Column / PlanetSystem.Earth / etc. and for applying a
single placement to a whole sub-assembly.

Members and parent accept either object names or take_snapshot uids.

Args:
    doc_name: Document to create the group in.
    name: Name for the new group.
    members: Optional list of objects to move into the group at creation.
    parent: Optional parent group/container the new group should live inside.

create_object(doc_name: str, obj_type: str, obj_name: str, transaction_id: str, analysis_name: str | None = None, obj_properties: dict[str, Any] = None) -> list[TextContent | ImageContent]

Create a new object in Parashell. Object type starts with 'Part::', 'Draft::', 'PartDesign::', or 'Fem::'.

Every model edit must run inside an open transaction. Open one with
transaction_create first, pass its id here, then transaction_apply to persist
or transaction_cancel to roll back.

Args:
    doc_name: The name of the document to create the object in.
    obj_type: The type of the object to create (e.g. 'Part::Box', 'Part::Cylinder', 'Draft::Circle').
    obj_name: The name of the object to create.
    transaction_id: Id of the open transaction returned by transaction_create.
    analysis_name: Optional FEM analysis container name to add the object to.
    obj_properties: The properties of the object to create.

create_objects(doc_name: str, items: list[dict[str, Any]], recompute: bool = True) -> list[TextContent | ImageContent]

Batch-create many objects in a single call.

Each entry in 'items' has the same shape as create_object's parameters:
    {
      "Name": "Tier1",                  optional, auto-generated when omitted
      "Type": "Part::Box",              required, Parashell TypeId
      "Properties": {                   optional, applied via the same setter
          "Length": 50,
          "Width": 50,
          "Height": 10,
          "Placement": {"Base": {"x": 0, "y": 0, "z": 100}}
      },
      "Analysis": "MyFEMAnalysis"       optional FEM container
    }

The whole list is processed inside a single GUI task, so the recompute happens
once at the end (set recompute=False to defer entirely). Errors on individual
items don't abort the batch - they are reported in the 'errors' array with the
item index, attempted name, and message.

Args:
    doc_name: Document to create objects in.
    items: List of object specs.
    recompute: Whether to recompute the document at the end. Default True.

create_pattern(doc_name: str, source_object: str, kind: Literal['circular', 'linear', 'grid'], count: int, params: dict[str, Any] | None = None, copy_mode: Literal['duplicate', 'link'] = 'duplicate', name_prefix: str | None = None, recompute: bool = True) -> list[TextContent | ImageContent]

Place N copies of a source object in a circular, linear, or grid pattern.

Pattern kinds and their params:

  - "circular":
      {"center": [x, y, z],          default [0, 0, 0]
       "axis":   [x, y, z],          default [0, 0, 1]
       "total_angle_deg": 360,       360 = full circle, e.g. 90 for quarter sweep
       "full_circle": true,          when true, count divides 360 exactly
       "include_first": true}        when false, first instance is skipped

  - "linear":
      {"direction": [x, y, z],       default [1, 0, 0]
       "spacing": 50.0,              distance between adjacent copies in mm
       "length": 200.0}              alternative to 'spacing': total span

  - "grid":
      {"u_axis": [1, 0, 0],          row direction
       "v_axis": [0, 1, 0],          column direction
       "cols": 4,                    columns per row
       "rows": 3,                    number of rows
       "spacing_x": 50,
       "spacing_y": 50}              count is ignored when rows*cols is given

copy_mode controls how the copies are produced:
  - "duplicate": creates an independent Part::Feature for each copy with a
    deep-copied shape. Best for permanent geometry like gear teeth, planet
    arms, sun rays.
  - "link": creates an App::Link to the source for each copy. Edits to the
    source propagate to every copy. Best for orbital tracks or instances
    that should share a master.

Source can be referenced by name or take_snapshot uid.

Args:
    doc_name: Document containing the source.
    source_object: Object name or uid.
    kind: "circular", "linear", or "grid".
    count: Number of copies. For circular full circles this becomes the
           division count.
    params: Pattern-specific params (see above).
    copy_mode: "duplicate" or "link".
    name_prefix: Optional prefix for new object names. Defaults to
                 "<source>_<kind>_".
    recompute: Whether to recompute after placement. Default True.

delete_object(doc_name: str, obj_name: str, transaction_id: str) -> list[TextContent | ImageContent]

Delete an object from a Parashell document.

Every model edit must run inside an open transaction. Pass the id from
transaction_create; deletion is reversible via transaction_cancel until
transaction_apply persists it.

Args:
    doc_name: The name of the document containing the object.
    obj_name: The name of the object to delete.
    transaction_id: Id of the open transaction returned by transaction_create.

edit_object(doc_name: str, obj_name: str, obj_properties: dict[str, Any], transaction_id: str) -> list[TextContent | ImageContent]

Edit an object in Parashell.

Every model edit must run inside an open transaction. Pass the id from
transaction_create; the change is rolled back by transaction_cancel or
persisted by transaction_apply.

Args:
    doc_name: The name of the document containing the object.
    obj_name: The name of the object to edit.
    obj_properties: The properties to update on the object.
    transaction_id: Id of the open transaction returned by transaction_create.

get_parts_list() -> list[TextContent]

Get the list of parts available in the Parashell parts library addon.

insert_part_from_library(relative_path: str, transaction_id: str) -> list[TextContent | ImageContent]

Insert a part from the Parashell parts library addon.

Every model edit must run inside an open transaction. Pass the id from
transaction_create; persist with transaction_apply or roll back with
transaction_cancel.

Args:
    relative_path: Relative path of the part within the parts library directory.
    transaction_id: Id of the open transaction returned by transaction_create.

list_documents() -> list[TextContent]

Get the list of currently open documents in Parashell.

recompute_document(doc_name: str | None = None, force: bool = False, clear_redo: bool = False, soft_timeout: float | None = None, async_threshold: float | None = None) -> list[TextContent | ImageContent]

Recompute a document object-by-object in dependency order.

Re-evaluates parametric features along the topological dependency graph. Useful
after editing properties or geometry through execute_code or other tools where a
recompute has not been triggered automatically.

The response includes per-document health: how many objects were recomputed,
how many remain unhealthy after the pass, and the full health record for each
unhealthy object - including state flags, must_execute, and shape diagnostics
(is_null, is_valid, is_closed, volume, area, vertex/edge/face/solid counts,
and bounding box). Use check_objects for an on-demand scan that does not
trigger a recompute.

Args:
    doc_name: Document name to recompute. If omitted, recomputes every open document.
    force: Pass True to recompute every object regardless of touched state.
    clear_redo: Pass True to clear the document's undo/redo stack before recomputing.
    soft_timeout: Seconds before the pass gives up and returns a partial-progress
        report naming the object it stalled on. None uses the configured default.
    async_threshold: Seconds before the pass detaches into a background job and
        returns a job_id to poll with recompute_status. None uses the configured
        default.

status is one of "complete", "timed_out", "running", or "error".

- complete: results carries the per-document health report described above.
- timed_out: soft_timeout was hit; stuck_on names the object it stalled on and
  results holds the partial report.
- running: async_threshold was hit; job_id is returned for recompute_status
  polling while the recompute continues in the background.
- error: error carries the failure message.

recompute_status(job_id: str) -> list[TextContent | ImageContent]

Poll the status of an asynchronous recompute_document job.

Pass the job_id returned by recompute_document when a recompute exceeded the
async threshold. Reports progress (objects done, current object), the stalled
object on a soft timeout, or the final per-document result when complete.

Args:
    job_id: The job identifier returned by recompute_document.

status is one of "running", "timed_out", "complete", or "error".

- running: objects_recomputed / objects_total progress plus current_object.
- timed_out: stuck_on names the object the recompute stalled on.
- complete: results carries the final per-document health report.
- error: error carries the failure message, or the job_id was not found.

remove_from_group(doc_name: str, group: str, members: list[str]) -> list[TextContent | ImageContent]

Remove objects from a group without deleting them.

Args:
    doc_name: Document containing the objects.
    group: Group name or uid.
    members: List of object names / uids to remove from the group.

set_appearance(doc_name: str, targets: list[str], properties: dict[str, Any]) -> list[TextContent]

Apply a single set of ViewObject properties to many objects at once.

Replaces the per-object setattr loop for ShapeColor / Transparency /
Visibility / DisplayMode. Targets accept object names or take_snapshot uids.

Recognised properties:
  - ShapeColor / LineColor / PointColor: [r, g, b] or [r, g, b, a] in [0, 1].
  - Transparency: int 0..100.
  - LineWidth: float.
  - PointSize: float.
  - Visibility: bool.
  - DisplayMode: "Shaded", "Wireframe", "Flat Lines", "Hidden line", "Points", "As is".
  - Any other ViewObject property exposed by the underlying object - set
    verbatim if it exists, otherwise reported in 'errors'.

Args:
    doc_name: Document containing the targets.
    targets: List of object names or uids.
    properties: Dict of view properties to apply to every target.

part_design_polar_pattern() -> list[TextContent]

run polar pattern using its axis property