kalpataru-introspect-feature-tree

name	kalpataru-introspect-feature-tree
description	Read and explore an existing SolidWorks part — its features, faces, edges, and topology. Use when the user wants you to modify or build on top of geometry that's already in the document.

Introspecting an existing part

When a part is already open and the user asks "add a hole here" or "what's the diameter of this shaft", you need to read the model first. Don't guess.

The one-shot summary

kalpataru_summary gives you the basics in a single call:

{
  bodies: 1,
  face_count: 14,
  edge_count: 24,
  vertex_count: 12,
  bounding_box: [-25, -25, 0, 25, 25, 50],
  mass: 0.196,
  material: "Plain Carbon Steel",
  features: ["Sketch1", "Boss-Extrude1", "Sketch2", "Cut-Extrude1", "Fillet1"]
}

The features list is just names. For more detail, call kalpataru_list_features.

Walking the feature tree

kalpataru_list_features returns each top-level feature:

[
  {name: "Boss-Extrude1", type: "Extrusion", params: {...}, status: "ok"},
  {name: "Cut-Extrude1",  type: "Extrusion", params: {...}, status: "ok"},
  {name: "Fillet1",       type: "Fillet",    params: {radius: "3mm"}, status: "ok"},
]

The order is the rebuild order. Earlier features are dependencies of later ones — modifying an early feature may break later ones.

Finding faces and edges

kalpataru_query_faces and kalpataru_query_edges filter by predicate:

# all planar faces of Boss-Extrude1
kalpataru_query_faces(surface="plane", of_feature="Boss-Extrude1")

# all cylindrical faces in the part
kalpataru_query_faces(surface="cylinder")

# the edges around face F3
kalpataru_query_edges(connected_to="F3")

# all straight edges
kalpataru_query_edges(curve="line")

# the edges of a feature (good for fillet candidates)
kalpataru_query_edges(of_feature="Cut-Extrude1")

# faces near a point in 3D space
kalpataru_query_faces(near=[0, 0, 25], near_radius=5)

Returned entities have:

• id — the stable handle to use in subsequent calls
• surface / curve — geometric type
• area, length, radius, diameter, centroid, normal — geometric properties
• connected_edges, connected_faces — adjacency
• owning_feature — which feature created it
• pick_point — a 3D point guaranteed to be ON the entity

Picking the right one when multiple match

Common patterns:

# Top face = planar face with highest Z centroid
planar = kalpataru_query_faces(surface="plane", of_feature="Boss-Extrude1")
top = max(planar, key=lambda f: f.centroid[2])

# Cylindrical hole = smallest-diameter cylindrical face
cylinders = kalpataru_query_faces(surface="cylinder")
hole = min(cylinders, key=lambda f: f.diameter)

# Outer edges = circular edges with largest radius
edges = kalpataru_query_edges(curve="circle")
outer = max(edges, key=lambda e: e.radius)

If you can't reliably disambiguate (3+ candidates with no clear winner), call kalpataru_request_selection and let the user click.

Inspecting a single entity in detail

kalpataru_inspect_entity("F3") returns every property the system knows about that face. Use it when you have an ID and want to know whether it's through, what its normal is, etc.

Don't cache entity IDs across topology changes

If you build a feature that adds/removes faces (fillet, shell, pattern, mirror, cut that splits the body), any face/edge IDs you captured before that feature are now stale. Re-query after.

What you cannot do (yet)

• Read sketch geometry from existing sketches (use kalpataru_list_features to see they exist, but their entities aren't exposed in v0.1.0)
• Get full BOM / configuration data
• Read assembly mate information