Skip to content

Use composite file physical properties endpoint - #257

Open
JordanNoone wants to merge 6 commits into
mainfrom
codex/use-composite-physical-properties
Open

Use composite file physical properties endpoint#257
JordanNoone wants to merge 6 commits into
mainfrom
codex/use-composite-physical-properties

Conversation

@JordanNoone

@JordanNoone JordanNoone commented Aug 30, 2026

Copy link
Copy Markdown
Contributor

Summary

  • replace the aggregate CAD physical-properties tool five API operations with one create_file_physical_properties request
  • request volume, mass, surface area, center of mass, and bounding box from the same imported representation and in the caller requested units
  • add optional render=true support that returns isometric, front, right, and top PNGs from the same analysis operation
  • download completed render artifacts concurrently through the generated authenticated SDK endpoint and publish each view once in the same MCP result
  • reuse the shared bounded async-operation resolver so queued, uploaded, and in_progress results poll the same operation ID without resubmitting work
  • preserve completed measurements and images when an individual property, render stage, or artifact download fails
  • return property_statuses, privacy-safe property_errors, render status/artifacts, delivered views, and per-view delivery errors
  • remove the aggregate tool CAD-to-STL conversion and local trimesh bounding-box pass

Deployment dependency

This PR is intentionally draft. It depends on KittyCAD/api#4491 merging and deploying, followed by a generated kittycad Python SDK release containing create_file_physical_properties, get_file_physical_properties_render, the render models, and the FilePhysicalProperties async result variant.

The currently released SDK is 1.5.0 and does not contain those methods. This branch therefore uses guarded generated-method boundaries and does not fall back to raw HTTP or the legacy five-call sequence. Before marking ready, bump the minimum SDK version and lockfile to the release containing API #4491, replace the temporary structural result boundary with generated result types, and run the live composite render test.

Do not merge or release this MCP change before the API endpoint and compatible SDK are available.

Behavior

  • exactly one composite analysis request is submitted per aggregate tool call
  • async polling never resubmits the source file
  • render=false remains the default and performs no image downloads
  • render=true returns structured measurements plus labeled inline PNG content in one MCP response
  • authenticated artifact URLs remain in the structured report; image bytes are fetched immediately and emitted only once
  • terminal worker failures retain the operation ID and sanitized error detail
  • individual property and render-delivery failures do not erase successful values
  • bounding-box output now uses unit_length, matching center of mass
  • center-of-mass expectations follow the deployed KittyCAD coordinate-frame contract from KittyCAD/api#4486

Validation

  • ZOO_API_TOKEN=dummy uv run pytest tests/test_server.py -k "calculate_cad_physical_properties or polls_async_operation or surfaces_async_worker_failure or rejects_wrong_async_result_variant or bounds_async_polling" -q - 11 passed
  • ZOO_API_TOKEN=dummy uv run pytest -m "not live" --ignore=tests/test_server.py -q - 153 passed, 1 skipped, 6 deselected
  • uv run ruff check - passed
  • uv run ruff format --check - passed
  • tool-schema check confirms optional render=false input and preserved structured output schema
  • local ty check has the same 73 unresolved kcl extension attributes on unchanged main; no new diagnostics point to this change

Closes #254.

Related: KittyCAD/api#4491, KittyCAD/api#4507, #253.

@JordanNoone
JordanNoone marked this pull request as ready for review August 30, 2026 03:11
@JordanNoone
JordanNoone requested a review from r-barton as a code owner August 30, 2026 03:11
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Use the composite file physical-properties endpoint for CAD analysis

2 participants