pi-revit

name

pi-revit

description

Work with the open Autodesk Revit model through the Revit bridge tools (ping, get_model_overview, get_elements, get_element_details, get_element_types, manage_selection, open_view, set_parameters, search_api_docs, execute_csharp, capture_view, export_documents, get_model_health). Use when the user asks about the Revit project, its elements, parameters, selection, or wants to change, script, capture, or export the model.

Revit

Work with the live Revit model. The tools call a headless bridge add-in inside Revit (2025, 2026, or 2027); Revit must be running with a project open (only ping and search_api_docs work without a document).

Tool selection

Task	Tool
Bridge alive? Which Revit version?	ping
Orientation: project info, units, levels, grids, category counts	get_model_overview
List or count elements of ANY category (walls, doors, rooms, sheets, views, ...)	get_elements
Read parameter VALUES, location, bounding box, materials of specific elements	get_element_details
List element types / family symbols; "used vs merely loaded"	get_element_types
Read or change the user's selection; zoom; temporary isolate	manage_selection
Put a view or sheet on the user's screen (activate it)	open_view
Write parameter values; rename anything (levels, views, sheets, types)	set_parameters
Look up Revit API classes/members/signatures	search_api_docs
Everything else (create, delete, move, views, sheets, tagging, ...)	execute_csharp
PNG snapshot of a view (visual QA)	capture_view (advanced)
PDF/DWG/PNG/IFC file export	export_documents (advanced)
Warnings / model quality audit	get_model_health (advanced)

Workflow guidance:

• Call get_model_overview first when starting work on an unfamiliar model — one call returns project metadata, units, levels, grids, and category counts.
• get_elements is the listing/counting primitive (count_only: true for bare counts). It returns identity fields only (id, name, category, typeName, levelId); read parameter values with get_element_details. Prefer a category or of_class scope when filtering by a parameter's display name.
• The selection pipeline is get_elements -> ids -> manage_selection (action set); there is no inline filter on selection.
• set_parameters is the home for bulk parameter writes AND renames (the Name parameter covers levels, views, sheets, types). One transaction per batch; per-element failures are reported. Pass expected_document (the model title) when several models are open or the session is long — it makes the write fail cleanly instead of landing in a different active document.
• Parameter display names are LOCALIZED: in a non-English Revit UI, Mark is Kennzeichen (German), マーク (Japanese), etc. When a display-name lookup or parameter_names filter finds nothing, or the document may be non-English, use the language-independent BuiltInParameter enum name instead (e.g. ALL_MODEL_MARK for Mark, ALL_MODEL_INSTANCE_COMMENTS for Comments) — set_parameters, get_element_details.parameter_names, and get_elements filter rules all accept them, and get_element_details reports each parameter's builtInParameter name for discovery.
• Before writing execute_csharp code, verify unfamiliar classes/members with search_api_docs (works with no document open; first query builds the index and takes a few seconds). The top match carries its remarks, parameter docs, and returns inline, and every public API enum value is searchable — trust the result over guessing or web search; narrow the query to promote a different match into the top slot.
• export_documents files its output under Documents\pi-revit\Models\<model title>\exports automatically when output_dir is omitted — keyed to the exported document, so it lands right even across many models. Pass output_dir only when the user names a different target.

execute_csharp playbook

• Globals: doc (Document), uidoc (UIDocument), uiapp (UIApplication), and Dump(value) to record intermediates into the result's dumps[].
• The transaction is automatic: the whole script runs inside ONE backend-owned transaction — committed on success, rolled back on any exception. Do not open your own Transaction (sub-transactions are fine).
• Scripts must be fully synchronous: await/async is rejected at compile time; never block on Task.Result/.Wait().
• Return primitives, strings, or anonymous objects/lists; raw Revit API objects are projected to compact shapes (Element -> {id,name,category,typeName,levelId}, ElementId -> number, XYZ -> {x,y,z}).
• Lengths are internal units (decimal feet) — convert with UnitUtils.ConvertToInternalUnits/ConvertFromInternalUnits.
• Common pitfalls: call FamilySymbol.Activate() before NewFamilyInstance; use collector-level filtering (OfCategory/OfClass/WhereElementIsNotElementType) and bounded loops — the budget is 120s and Revit cannot be interrupted mid-script; modal dialogs are auto-dismissed and reported in suppressedDialogs.
• capture_view returns a filePath to a temp PNG, never image data — open it with the read tool to actually see it.

Failure modes

• Bridge not reachable ("Revit bridge is not available" / "Could not reach the Revit bridge"): Revit is not running or the add-in did not load. Ask the user to start Revit, then retry ping.
• HTTP 409 / "No active Revit document is open." (hasActiveDocument: false): Revit is running but no project is open. Ask the user to open a project, then retry. This fails immediately; do not wait or retry blindly.
• Timeout ("Revit did not answer within Ns", 30s default / 120s for execute_csharp, capture_view, export_documents): Revit is busy or showing a modal dialog. An already-started tool still runs to completion in Revit — verify model state (e.g. get_elements) before re-issuing a write.
• Cancelled: same caveat — the bridge cannot abort queued or running work, so verify model state before retrying a write tool.