pi-revit 0.3.1 → 0.4.0

package/src/Revit/Tools/SummarizeElements.cs

@@ -0,0 +1,87 @@
+using System.Text.Json;
+using System.Text.Json.Nodes;
+
+namespace RevitBridge.Tools;
+
+internal sealed class SummarizeElements : ITool
+{
+    private const int MaxElements = 10000;
+    public string Name => "summarize_elements";
+    public string Label => "Summarize Elements";
+    public string Tier => "advanced";
+    public string Description => "Count matching host-model elements grouped by category, type, level or one parameter value. Accepts get_elements category/class/level/type/filter scopes. At most 10,000 matches; narrow larger queries. Parameter grouping uses exact raw values, with a distinct missing-value group. Ambiguous display-name parameters are rejected. Counts cover the entire matching scope, not just the returned groups page.";
+    public object ParametersSchema
+    {
+        get
+        {
+            var query = ElementQueryScope.Schema();
+            return new
+            {
+                type = "object",
+                properties = new
+                {
+                    query,
+                    group_by = new { type = "string", @enum = new[] { "category", "typeName", "levelId", "parameter" } },
+                    parameter = new { type = "string", description = "Required for group_by=parameter. Name, built-in identity or guid:<GUID>." },
+                    type_parameter = new { type = "boolean", description = "Group by the parameter on the element type instead of the instance." },
+                    offset = new { type = "integer", minimum = 0 },
+                    limit = new { type = "integer", minimum = 1, maximum = 500 },
+                },
+                required = new[] { "group_by" },
+            };
+        }
+    }
+
+    public object Execute(JsonElement args, ToolContext context)
+    {
+        string groupBy = JsonArgs.GetString(args, "group_by") ?? "";
+        if (groupBy is not ("category" or "typeName" or "levelId" or "parameter")) throw new ArgumentException("Unknown group_by value.");
+        string? parameter = JsonArgs.GetString(args, "parameter");
+        if (groupBy == "parameter" && string.IsNullOrWhiteSpace(parameter)) throw new ArgumentException("parameter is required for parameter grouping.");
+        bool typeParameter = JsonArgs.GetBool(args, "type_parameter", false);
+        var query = ElementQueryScope.Parse(args);
+        JsonElement RunQuery() => JsonSerializer.SerializeToElement(((ToolOutput)new GetElements().Execute(JsonSerializer.SerializeToElement(query), context)!).Payload);
+        query["count_only"] = true;
+        var countResult = RunQuery();
+        int total = countResult.GetProperty("total_count").GetInt32();
+        object? warnings = countResult.TryGetProperty("warnings", out var queryWarnings) ? queryWarnings.Clone() : null;
+        if (total > MaxElements) throw new ArgumentException($"Query matches {total} elements; narrow the scope to at most {MaxElements}.");
+        query["count_only"] = false;
+        query["limit"] = 1000;
+        if (groupBy == "parameter")
+        {
+            query["parameter_names"] = new JsonArray(parameter);
+            query["include_type_parameters"] = typeParameter;
+        }
+        var counts = new Dictionary<string, (object? Value, bool Missing, int Count)>();
+        for (int position = 0; position < total; position += 1000)
+        {
+            query["offset"] = position;
+            foreach (var row in RunQuery().GetProperty("elements").EnumerateArray())
+            {
+                object? value = null;
+                bool missing = false;
+                if (groupBy == "parameter")
+                {
+                    var projection = row.GetProperty("parameters").EnumerateArray().FirstOrDefault(p => p.GetProperty("isType").GetBoolean() == typeParameter);
+                    missing = projection.ValueKind == JsonValueKind.Undefined || !projection.GetProperty("found").GetBoolean();
+                    if (!missing)
+                    {
+                        if (projection.GetProperty("ambiguous").GetBoolean()) throw new ArgumentException($"Parameter '{parameter}' is ambiguous on element {row.GetProperty("id")}; use a built-in identity or shared GUID.");
+                        value = projection.GetProperty("matches")[0].GetProperty("value").Clone();
+                    }
+                }
+                else if (row.TryGetProperty(groupBy, out var field)) value = field.Clone();
+                string key = (missing ? "missing:" : "value:") + JsonSerializer.Serialize(value);
+                counts[key] = counts.TryGetValue(key, out var previous) ? (value, missing, previous.Count + 1) : (value, missing, 1);
+            }
+        }
+        int offset = Math.Max(0, JsonArgs.GetInt(args, "offset", 0));
+        int limit = Math.Clamp(JsonArgs.GetInt(args, "limit", 100), 1, 500);
+        var groups = counts.OrderByDescending(pair => pair.Value.Count).ThenBy(pair => pair.Key, StringComparer.Ordinal).Skip(offset).Take(limit)
+            .Select(pair => new { value = pair.Value.Value, missing = pair.Value.Missing, count = pair.Value.Count }).ToArray();
+        return new { total_elements = total, total_groups = counts.Count, group_by = groupBy, parameter, type_parameter = typeParameter,
+            numeric_values = "Revit internal units", warnings, offset, returned_count = groups.Length,
+            next_offset = offset + groups.Length < counts.Count ? (int?)(offset + groups.Length) : null, groups };
+    }
+}

package/src/Revit/Tools/ToolSupport.cs

@@ -259,4 +259,4 @@ namespace RevitBridge.Tools
         }
     }
 
-}
+}

package/src/Revit/Tools/TransformElements.cs

@@ -0,0 +1,58 @@
+using System.Text.Json;
+using Autodesk.Revit.DB;
+
+namespace RevitBridge.Tools;
+
+internal sealed class TransformElements : ITool
+{
+    public string Name => "transform_elements";
+    public string Label => "Transform Elements";
+    public string Tier => "advanced";
+    public bool Write => true;
+    public string Description => "Move, copy or rotate 1–200 elements together in the active document. Coordinates use the document internal origin and axes; unit is required. Rotation uses a right-handed axis and angle_degrees. The whole selection succeeds or rolls back as one step; pinned elements are never automatically unpinned. Revit may move constrained/hosted dependents too. preview=true validates commit then rolls back; any created IDs in a preview are temporary and must not be reused. Snapshots describe requested elements, not a complete dependent-change audit.";
+    public object ParametersSchema => new
+    {
+        type = "object", properties = new
+        {
+            action = new { type = "string", @enum = new[] { "move", "copy", "rotate" } },
+            element_ids = ModelEditInputs.IdsSchema,
+            unit = ModelEditInputs.LengthUnitSchema,
+            translation = ModelEditInputs.VectorSchema("Move/copy displacement [x,y,z] in unit."),
+            axis_origin = ModelEditInputs.VectorSchema("Rotation axis origin [x,y,z] in unit, relative to internal origin."),
+            axis_direction = ModelEditInputs.VectorSchema("Nonzero rotation axis direction [x,y,z], dimensionless."),
+            angle_degrees = new { type = "number", description = "Signed right-hand rotation angle in degrees." },
+            preview = ModelEditInputs.PreviewSchema,
+        }, required = new[] { "action", "element_ids", "unit" },
+    };
+
+    public object Execute(JsonElement args, ToolContext context)
+    {
+        var doc = context.Document ?? throw new NoActiveDocumentException();
+        var ids = ModelEditInputs.Ids(args);
+        string action = JsonArgs.GetString(args, "action") ?? "";
+        if (action is not ("move" or "copy" or "rotate")) throw new ArgumentException("action must be move, copy or rotate.");
+        double scale = ModelEditInputs.LengthScale(args);
+        XYZ? translation = action != "rotate" ? ModelEditInputs.Vector(args, "translation").Multiply(scale) : null;
+        XYZ? origin = action == "rotate" ? ModelEditInputs.Vector(args, "axis_origin").Multiply(scale) : null;
+        XYZ? direction = action == "rotate" ? ModelEditInputs.Vector(args, "axis_direction") : null;
+        double angle = action == "rotate" ? ModelEditInputs.Number(args, "angle_degrees") * Math.PI / 180 : 0;
+        if (direction != null && direction.GetLength() < 1e-12) throw new ArgumentException("axis_direction must be nonzero.");
+        var result = ModelEditBatch.Run(doc, Name, args, new[] { new ModelEditBatch.Step(
+            new() { ["action"] = action, ["element_ids"] = ids.Select(x => x.Value).ToArray() }, () =>
+            {
+                var elements = ids.Select(id => doc.GetElement(id) ?? throw new ArgumentException($"Element {id.Value} not found.")).ToArray();
+                if (action != "copy" && elements.Any(e => e.Pinned)) throw new ArgumentException("Selection contains pinned elements; no elements were unpinned.");
+                var before = elements.Select(ModelEditInputs.Snapshot).ToArray();
+                ICollection<ElementId> outputIds = ids;
+                if (action == "move") ElementTransformUtils.MoveElements(doc, ids, translation!);
+                else if (action == "copy") outputIds = ElementTransformUtils.CopyElements(doc, ids, translation!);
+                else ElementTransformUtils.RotateElements(doc, ids, Line.CreateUnbound(origin!, direction!.Normalize()), angle);
+                doc.Regenerate();
+                return new() { ["before"] = before, ["after"] = outputIds.Select(doc.GetElement).Where(e => e != null).Select(ModelEditInputs.Snapshot).ToArray(),
+                    ["created_ids"] = action == "copy" ? outputIds.Select(id => id.Value).ToArray() : Array.Empty<long>(),
+                    ["coordinate_system"] = "document_internal", ["snapshot_unit"] = "feet",
+                    ["created_ids_are_temporary"] = action == "copy" && JsonArgs.GetBool(args, "preview", false) };
+            }) });
+        return result.Payload;
+    }
+}

package/workspace/AGENTS.md

@@ -1,10 +1,10 @@
 # pi-revit workspace
 
 This folder tree is the working area for Pi + Revit sessions. The pi-revit tools talk to the
-Revit bridge add-in, targeting Revit 2025, 2026, and 2027. The 0.3.0 changes were
-tested live on Revit 2025. Bridge document tools require a project open; `ping` and
-`search_api_docs` work without a document. `read_revit_result` reads saved local
-results without contacting Revit.
+Revit bridge add-in, targeting Revit 2025, 2026, and 2027. The 0.3.0 changes were
+tested live on Revit 2025. Bridge document tools require a project open; `ping` and
+`search_api_docs` work without a document. `read_revit_result` reads saved local
+results without contacting Revit.
 
 ## File rules — where every file goes
 
@@ -16,57 +16,57 @@ Documents\pi-revit\
 ├─ AGENTS.md            <- this file
 ├─ pi-revit.cmd         <- double-click launcher
 └─ Models\
-   └─ <model title>--<identity hash>\  <- selected automatically for the exported document
-      ├─ model.txt      <- document identity/path marker written by the add-in
+   └─ <model title>--<identity hash>\  <- selected automatically for the exported document
+      ├─ model.txt      <- document identity/path marker written by the add-in
       ├─ exports\       <- export_documents output (its default)
       ├─ captures\      <- view snapshots worth keeping
       └─ scripts\       <- generated scripts and analysis for that model
 ```
 
 1. **Let exports sort themselves**: call `export_documents` without `output_dir` — files land
-   in an identity-derived model folder automatically. Treat the returned `outputDir`
-   and file paths as authoritative; do not derive the hash from the model title or
-   opaque `project.documentId`. Save As can change the destination. Existing title-only
-   folders remain untouched. Pass
+   in an identity-derived model folder automatically. Treat the returned `outputDir`
+   and file paths as authoritative; do not derive the hash from the model title or
+   opaque `project.documentId`. Save As can change the destination. Existing title-only
+   folders remain untouched. Pass
    `output_dir` only when the user names a different target.
 2. **Anything else you produce about a model goes into that model's folder**: view captures the
-   user wants to keep in that verified model folder's `captures` subfolder
-   (`capture_view` writes to temp), and scripts and analysis in its `scripts`
-   subfolder. For a default export, the model folder is the parent of returned
-   `outputDir`. If no folder has been established, identify it from existing model
-   markers or choose an explicit destination for the task; do not trigger an
-   unnecessary export or guess a title-only folder. Create subfolders on first use.
+   user wants to keep in that verified model folder's `captures` subfolder
+   (`capture_view` writes to temp), and scripts and analysis in its `scripts`
+   subfolder. For a default export, the model folder is the parent of returned
+   `outputDir`. If no folder has been established, identify it from existing model
+   markers or choose an explicit destination for the task; do not trigger an
+   unnecessary export or guess a title-only folder. Create subfolders on first use.
 3. **Never create files loose in the workspace root.** The root holds `AGENTS.md`,
    `pi-revit.cmd`, `Models\`, and Pi's own session data — nothing else, ever.
 
 ## Tool habits
 
-- Start unfamiliar models with `get_model_overview`; use `get_elements` for any listing or
-  counting; read parameter values with `get_element_details`.
-- Copy the intended model's `project.documentId` unchanged into `expected_document_id`
-  for `set_parameters`, `execute_csharp`, `export_documents`, `open_view`, and
-  selection/zoom changes. Any `manage_selection` call with `isolate_in_view: true`
-  also requires it, including action `get`. Pure reads may omit it; supplied IDs
-  are checked. Legacy `expected_document` titles alone do not satisfy the guard.
-  After a rejection, verify the intended model before refreshing its ID. Closing
-  and reopening a model or restarting Revit invalidates earlier IDs.
-- Before `execute_csharp`, verify unfamiliar API signatures with `search_api_docs`.
-- Write tools (`set_parameters`, `execute_csharp`) change the real model — state clearly what
-  was changed. `set_parameters` commits partial successes: always check its `failed` list.
-  Inspect `commitWarnings` and the actual transaction outcome. A failed
-  `execute_csharp` attempts rollback; do not assume rollback succeeded. A
-  `returnValueError` can follow a committed edit. Earlier UI actions and created
-  files can persist after failure. Read reported effects before retrying.
-- When a result returns `result_id`, use `read_revit_result` from offset zero and
-  follow `next_offset` until `has_more` is false. Join its `text` fragments in order;
-  offsets count UTF-16 code units. The returned absolute file path remains a
-  fallback for `read` after extension reload while the file exists. Tool query
-  pagination and limits still apply separately.
-
-## Upgrade notes
-
-After installing 0.3.0, deploy the matching add-in with Revit closed, restart Revit,
-and start a fresh Pi session to load the new tool schemas. Obtain a new overview
-before changing a document. Setup preserves existing `AGENTS.md`; older workspaces
-need these exact-ID, saved-result, and identity-derived folder rules merged into
-their existing instructions.
+- Start unfamiliar models with `get_model_overview`; use `get_elements` for any listing or
+  counting; read parameter values with `get_element_details`.
+- Copy the intended model's `project.documentId` unchanged into `expected_document_id`
+  for `set_parameters`, `execute_csharp`, `export_documents`, `open_view`, and
+  selection/zoom changes. Any `manage_selection` call with `isolate_in_view: true`
+  also requires it, including action `get`. Pure reads may omit it; supplied IDs
+  are checked. Legacy `expected_document` titles alone do not satisfy the guard.
+  After a rejection, verify the intended model before refreshing its ID. Closing
+  and reopening a model or restarting Revit invalidates earlier IDs.
+- Before `execute_csharp`, verify unfamiliar API signatures with `search_api_docs`.
+- Write tools (`set_parameters`, `execute_csharp`) change the real model — state clearly what
+  was changed. `set_parameters` commits partial successes: always check its `failed` list.
+  Inspect `commitWarnings` and the actual transaction outcome. A failed
+  `execute_csharp` attempts rollback; do not assume rollback succeeded. A
+  `returnValueError` can follow a committed edit. Earlier UI actions and created
+  files can persist after failure. Read reported effects before retrying.
+- When a result returns `result_id`, use `read_revit_result` from offset zero and
+  follow `next_offset` until `has_more` is false. Join its `text` fragments in order;
+  offsets count UTF-16 code units. The returned absolute file path remains a
+  fallback for `read` after extension reload while the file exists. Tool query
+  pagination and limits still apply separately.
+
+## Upgrade notes
+
+After installing 0.3.0, deploy the matching add-in with Revit closed, restart Revit,
+and start a fresh Pi session to load the new tool schemas. Obtain a new overview
+before changing a document. Setup preserves existing `AGENTS.md`; older workspaces
+need these exact-ID, saved-result, and identity-derived folder rules merged into
+their existing instructions.