pi-revit 0.1.0

package/src/Revit/Tools/SetParameters.cs

@@ -0,0 +1,382 @@
+using System.Globalization;
+using System.Text.Json;
+using Autodesk.Revit.DB;
+
+namespace RevitBridge.Tools
+{
+    /// <summary>
+    /// Generic bulk parameter write — and the home for rename (parameter 'Name',
+    /// falling back to the Element.Name property when the parameter is read-only,
+    /// unit handling). Owns one Transaction("set_parameters") per call: partial success
+    /// commits and reports the failed updates; total failure rolls back. Values
+    /// are storage-type validated; numeric values convert from the given forge
+    /// unit (or the document's display units for the parameter's spec) to
+    /// internal units.
+    /// </summary>
+    internal sealed class SetParameters : ITool
+    {
+        private const int MaxUpdates = 200;
+
+        public string Name => "set_parameters";
+        public string Label => "Set Parameters";
+        public string Description => "Write parameter values on elements — also the home for rename: parameter 'Name' covers levels, views, sheets, types, etc. (falls back to the element's Name property when the Name parameter is read-only). updates apply in ONE transaction: partial success commits and lists the failures; if every update fails the transaction is rolled back and nothing changes. parameter accepts a display name (Comments, Mark, Name), a BuiltInParameter enum name (e.g. ALL_MODEL_MARK), or guid:<GUID> for a shared parameter; type parameters live on the element type, so pass the type's id. Values are validated against the parameter's storage type; numeric values are interpreted in the document's display units for that parameter unless 'unit' (e.g. millimeters, feet, squareMeters) is given.";
+        public bool Write => true;
+
+        public object ParametersSchema => new
+        {
+            type = "object",
+            properties = new
+            {
+                updates = new
+                {
+                    type = "array",
+                    description = "Parameter writes to apply in one transaction (1-200 per call).",
+                    items = new
+                    {
+                        type = "object",
+                        properties = new
+                        {
+                            element_id = new { type = "integer", description = "Target element id (use the type id for type parameters)." },
+                            parameter = new { type = "string", description = "Parameter display name (e.g. Comments, Mark, Name), BuiltInParameter enum name (e.g. ALL_MODEL_MARK), or guid:<GUID> for a shared parameter." },
+                            value = new { description = "New value: string, number, or boolean (yes/no parameters). Empty string clears a text parameter." },
+                            unit = new { type = "string", description = "Unit of a numeric value, e.g. millimeters, meters, feet, inches, squareMeters, degrees. Default: the document's display units for that parameter." },
+                        },
+                        required = new[] { "element_id", "parameter", "value" },
+                    },
+                },
+            },
+            required = new[] { "updates" },
+        };
+
+        public string? PromptSnippet => "Write element parameter values in bulk, including renames via the 'Name' parameter.";
+        public IReadOnlyList<string>? PromptGuidelines => new[]
+        {
+            "Use set_parameters for parameter writes and renames (parameter 'Name'); pass 'unit' with numeric values unless the document's display units are intended.",
+            "set_parameters commits partial successes — always check the failed list in its result instead of assuming every update applied.",
+        };
+
+        public object? Execute(JsonElement args, ToolContext context)
+        {
+            var doc = context.Document ?? throw new NoActiveDocumentException();
+            var updates = ParseUpdates(args);
+
+            var succeeded = new List<Dictionary<string, object?>>();
+            var failed = new List<Dictionary<string, object?>>();
+
+            using var transaction = new Transaction(doc, "set_parameters");
+            if (transaction.Start() != TransactionStatus.Started)
+                throw new InvalidOperationException("Unable to start the set_parameters transaction.");
+
+            try
+            {
+                foreach (var update in updates)
+                {
+                    try
+                    {
+                        string? newDisplayValue = Apply(doc, update);
+                        succeeded.Add(new Dictionary<string, object?>
+                        {
+                            ["id"] = update.ElementId,
+                            ["parameter"] = update.ParameterInput,
+                            ["newDisplayValue"] = newDisplayValue,
+                        });
+                    }
+                    catch (Exception ex)
+                    {
+                        failed.Add(new Dictionary<string, object?>
+                        {
+                            ["id"] = update.ElementId,
+                            ["parameter"] = update.ParameterInput,
+                            ["reason"] = ex.Message,
+                        });
+                    }
+                }
+
+                if (succeeded.Count > 0)
+                {
+                    if (transaction.Commit() != TransactionStatus.Committed)
+                        throw new InvalidOperationException("The set_parameters transaction failed to commit; no changes were saved.");
+                }
+                else
+                {
+                    transaction.RollBack();
+                }
+            }
+            catch
+            {
+                if (transaction.GetStatus() == TransactionStatus.Started)
+                    transaction.RollBack();
+                throw;
+            }
+
+            int elementCount = succeeded.Select(row => row["id"]).Distinct().Count();
+            string failureSample = failed.Count > 0
+                ? $" First failure: element {failed[0]["id"]} '{failed[0]["parameter"]}': {failed[0]["reason"]}"
+                : string.Empty;
+            string compact = failed.Count == 0
+                ? $"Updated {succeeded.Count} parameter value(s) on {elementCount} element(s)."
+                : succeeded.Count == 0
+                    ? $"No updates applied; all {failed.Count} failed — transaction rolled back.{failureSample}"
+                    : $"Updated {succeeded.Count} parameter value(s) on {elementCount} element(s); {failed.Count} failed.{failureSample}";
+
+            return new ToolOutput(new
+            {
+                updated = succeeded.Count,
+                committed = succeeded.Count > 0,
+                succeeded,
+                failed,
+            }, compact);
+        }
+
+        // ------------------------------------------------------------- application
+
+        /// <summary>Applies one update; returns the new display value or throws with the per-update reason.</summary>
+        private static string? Apply(Document doc, Update update)
+        {
+            var element = doc.GetElement(new ElementId(update.ElementId))
+                ?? throw new InvalidOperationException($"Element {update.ElementId} not found.");
+
+            var parameter = FindParameter(element, update);
+            bool nameTarget = string.Equals(update.ParameterInput, "Name", StringComparison.OrdinalIgnoreCase)
+                || string.Equals(parameter?.Definition?.Name, "Name", StringComparison.OrdinalIgnoreCase);
+
+            if (parameter is null)
+            {
+                if (nameTarget)
+                    return SetElementName(element, update);
+                throw new InvalidOperationException($"Parameter '{update.ParameterInput}' not found on element {update.ElementId} ('{element.Name}'). Type parameters live on the element type — pass its id instead.");
+            }
+
+            if (parameter.IsReadOnly)
+            {
+                if (nameTarget)
+                    return SetElementName(element, update);
+                throw new InvalidOperationException($"Parameter '{parameter.Definition?.Name}' is read-only on element {update.ElementId}.");
+            }
+
+            bool accepted = parameter.StorageType switch
+            {
+                StorageType.String => parameter.Set(ValueAsString(update.Value)),
+                StorageType.Double => parameter.Set(ToInternalUnits(doc, parameter, RequireDouble(parameter, update.Value), update.Unit)),
+                StorageType.Integer => parameter.Set(RequireInt(parameter, update.Value)),
+                StorageType.ElementId => parameter.Set(new ElementId(RequireLong(parameter, update.Value))),
+                _ => throw new InvalidOperationException($"Parameter '{parameter.Definition?.Name}' has storage type None and cannot be set."),
+            };
+
+            if (!accepted)
+            {
+                if (nameTarget)
+                    return SetElementName(element, update);
+                throw new InvalidOperationException($"Revit rejected the value for '{parameter.Definition?.Name}' on element {update.ElementId} (Parameter.Set returned false).");
+            }
+            return DescribeNewValue(parameter) ?? ValueAsString(update.Value);
+        }
+
+        /// <summary>Rename fallback: the Element.Name property setter.</summary>
+        private static string SetElementName(Element element, Update update)
+        {
+            string name = ValueAsString(update.Value);
+            if (string.IsNullOrWhiteSpace(name))
+                throw new InvalidOperationException("Renaming needs a non-empty string value.");
+            element.Name = name;
+            return name;
+        }
+
+        private static Parameter? FindParameter(Element element, Update update)
+        {
+            if (update.BuiltIn is { } builtIn)
+                return element.get_Parameter(builtIn);
+            if (update.SharedGuid is { } guid)
+                return element.get_Parameter(guid);
+
+            var direct = element.LookupParameter(update.ParameterInput);
+            if (direct != null)
+                return direct;
+            foreach (Parameter parameter in element.Parameters)
+            {
+                if (string.Equals(parameter.Definition?.Name, update.ParameterInput, StringComparison.OrdinalIgnoreCase))
+                    return parameter;
+            }
+            return null;
+        }
+
+        private static string? DescribeNewValue(Parameter parameter)
+        {
+            try
+            {
+                return parameter.StorageType == StorageType.String ? parameter.AsString() : parameter.AsValueString();
+            }
+            catch
+            {
+                return null;
+            }
+        }
+
+        /// <summary>Converts a user-supplied numeric value to internal units using the
+        /// explicit unit, or the document's display units for the parameter's spec.</summary>
+        private static double ToInternalUnits(Document doc, Parameter parameter, double value, string? unitInput)
+        {
+            ForgeTypeId? spec = null;
+            try
+            {
+                spec = parameter.Definition?.GetDataType();
+            }
+            catch
+            {
+                // Treat as unitless below.
+            }
+
+            bool measurable = false;
+            try
+            {
+                measurable = spec != null && UnitUtils.IsMeasurableSpec(spec);
+            }
+            catch
+            {
+                // Treat as unitless below.
+            }
+
+            if (!measurable || spec is null)
+            {
+                if (!string.IsNullOrWhiteSpace(unitInput))
+                    throw new InvalidOperationException($"Parameter '{parameter.Definition?.Name}' is unitless; remove unit '{unitInput}'.");
+                return value;
+            }
+
+            ForgeTypeId unit;
+            if (!string.IsNullOrWhiteSpace(unitInput))
+            {
+                unit = UnitResolver.Resolve(unitInput);
+                if (!UnitUtils.IsValidUnit(spec, unit))
+                    throw new InvalidOperationException($"Unit '{unitInput}' does not fit parameter '{parameter.Definition?.Name}' (spec {UnitResolver.ShortName(spec)}); the document displays it in {UnitResolver.ShortName(doc.GetUnits().GetFormatOptions(spec).GetUnitTypeId())}.");
+            }
+            else
+            {
+                unit = doc.GetUnits().GetFormatOptions(spec).GetUnitTypeId();
+            }
+            return UnitUtils.ConvertToInternalUnits(value, unit);
+        }
+
+        // ------------------------------------------------------------ value typing
+
+        private static double RequireDouble(Parameter parameter, JsonElement value)
+        {
+            if (value.ValueKind == JsonValueKind.Number && value.TryGetDouble(out double fromNumber))
+                return fromNumber;
+            if (value.ValueKind == JsonValueKind.String
+                && double.TryParse(value.GetString(), NumberStyles.Float, CultureInfo.InvariantCulture, out double fromString))
+                return fromString;
+            throw new InvalidOperationException($"Parameter '{parameter.Definition?.Name}' stores a number; got {value.GetRawText()}.");
+        }
+
+        private static int RequireInt(Parameter parameter, JsonElement value)
+        {
+            if (value.ValueKind == JsonValueKind.Number && value.TryGetInt32(out int fromNumber))
+                return fromNumber;
+            if (value.ValueKind == JsonValueKind.True)
+                return 1;
+            if (value.ValueKind == JsonValueKind.False)
+                return 0;
+            if (value.ValueKind == JsonValueKind.String)
+            {
+                string text = value.GetString()?.Trim() ?? string.Empty;
+                if (int.TryParse(text, NumberStyles.Integer, CultureInfo.InvariantCulture, out int fromString))
+                    return fromString;
+                if (string.Equals(text, "yes", StringComparison.OrdinalIgnoreCase) || string.Equals(text, "true", StringComparison.OrdinalIgnoreCase))
+                    return 1;
+                if (string.Equals(text, "no", StringComparison.OrdinalIgnoreCase) || string.Equals(text, "false", StringComparison.OrdinalIgnoreCase))
+                    return 0;
+            }
+            throw new InvalidOperationException($"Parameter '{parameter.Definition?.Name}' stores an integer (yes/no parameters take true/false); got {value.GetRawText()}.");
+        }
+
+        private static long RequireLong(Parameter parameter, JsonElement value)
+        {
+            if (value.ValueKind == JsonValueKind.Number && value.TryGetInt64(out long fromNumber))
+                return fromNumber;
+            if (value.ValueKind == JsonValueKind.String
+                && long.TryParse(value.GetString(), NumberStyles.Integer, CultureInfo.InvariantCulture, out long fromString))
+                return fromString;
+            throw new InvalidOperationException($"Parameter '{parameter.Definition?.Name}' stores an element id; pass the id as an integer. Got {value.GetRawText()}.");
+        }
+
+        private static string ValueAsString(JsonElement value) => value.ValueKind switch
+        {
+            JsonValueKind.String => value.GetString() ?? string.Empty,
+            JsonValueKind.True => "true",
+            JsonValueKind.False => "false",
+            JsonValueKind.Null or JsonValueKind.Undefined => string.Empty,
+            _ => value.GetRawText(),
+        };
+
+        // ---------------------------------------------------------------- parsing
+
+        private sealed class Update
+        {
+            public required long ElementId { get; init; }
+            public required string ParameterInput { get; init; }
+            public JsonElement Value { get; init; }
+            public string? Unit { get; init; }
+            public BuiltInParameter? BuiltIn { get; init; }
+            public Guid? SharedGuid { get; init; }
+        }
+
+        private static List<Update> ParseUpdates(JsonElement args)
+        {
+            if (args.ValueKind != JsonValueKind.Object || !args.TryGetProperty("updates", out var updatesElement) || updatesElement.ValueKind != JsonValueKind.Array)
+                throw new ArgumentException("Missing or invalid required field: updates must be an array of { element_id, parameter, value, unit? } objects.");
+
+            var updates = new List<Update>(updatesElement.GetArrayLength());
+            foreach (var item in updatesElement.EnumerateArray())
+            {
+                if (item.ValueKind != JsonValueKind.Object)
+                    throw new ArgumentException("Each update must be an object with element_id, parameter, and value.");
+
+                long elementId = JsonArgs.GetLong(item, "element_id")
+                    ?? throw new ArgumentException("Each update needs an integer element_id.");
+                string parameterInput = (JsonArgs.GetString(item, "parameter") ?? string.Empty).Trim();
+                if (parameterInput.Length == 0)
+                    throw new ArgumentException($"The update for element {elementId} needs a parameter name.");
+                if (!item.TryGetProperty("value", out var value))
+                    throw new ArgumentException($"The update for element {elementId} ('{parameterInput}') needs a value.");
+
+                BuiltInParameter? builtIn = null;
+                Guid? sharedGuid = null;
+                if (parameterInput.StartsWith("guid:", StringComparison.OrdinalIgnoreCase))
+                {
+                    sharedGuid = Guid.TryParse(parameterInput["guid:".Length..], out var guid)
+                        ? guid
+                        : throw new ArgumentException($"Invalid shared parameter guid: {parameterInput}");
+                }
+                else
+                {
+                    string enumName = parameterInput.StartsWith("BuiltInParameter.", StringComparison.OrdinalIgnoreCase)
+                        ? parameterInput["BuiltInParameter.".Length..]
+                        : parameterInput;
+                    // BuiltInParameter names are SHOUTY_SNAKE_CASE; require an underscore or
+                    // all-caps so plain display names like "Comments" never collide.
+                    bool looksLikeEnumName = enumName.Length > 0 && char.IsLetter(enumName[0]) && !enumName.Contains(' ')
+                        && (enumName.Contains('_') || enumName.All(c => !char.IsLetter(c) || char.IsUpper(c)));
+                    if (looksLikeEnumName && Enum.TryParse<BuiltInParameter>(enumName, true, out var parsed) && parsed != BuiltInParameter.INVALID)
+                        builtIn = parsed;
+                }
+
+                updates.Add(new Update
+                {
+                    ElementId = elementId,
+                    ParameterInput = parameterInput,
+                    Value = value,
+                    Unit = JsonArgs.GetString(item, "unit"),
+                    BuiltIn = builtIn,
+                    SharedGuid = sharedGuid,
+                });
+            }
+
+            if (updates.Count == 0)
+                throw new ArgumentException("updates must contain at least one update.");
+            if (updates.Count > MaxUpdates)
+                throw new ArgumentException($"Too many updates ({updates.Count}); max {MaxUpdates} per call. Apply them in batches.");
+            return updates;
+        }
+    }
+}

package/src/Revit/Tools/ToolSupport.cs

@@ -0,0 +1,261 @@
+using System.Text.Json;
+using Autodesk.Revit.DB;
+
+namespace RevitBridge.Tools
+{
+    /// <summary>
+    /// Resolves a user-facing category string (friendly alias, category display name,
+    /// or BuiltInCategory enum name like OST_Walls) to a category ElementId usable
+    /// with FilteredElementCollector.OfCategoryId. Shared by the query tools.
+    /// </summary>
+    internal static class CategoryResolver
+    {
+        private static readonly IReadOnlyDictionary<string, BuiltInCategory> Aliases = new Dictionary<string, BuiltInCategory>(StringComparer.OrdinalIgnoreCase)
+        {
+            ["wall"] = BuiltInCategory.OST_Walls,
+            ["walls"] = BuiltInCategory.OST_Walls,
+            ["door"] = BuiltInCategory.OST_Doors,
+            ["doors"] = BuiltInCategory.OST_Doors,
+            ["window"] = BuiltInCategory.OST_Windows,
+            ["windows"] = BuiltInCategory.OST_Windows,
+            ["floor"] = BuiltInCategory.OST_Floors,
+            ["floors"] = BuiltInCategory.OST_Floors,
+            ["room"] = BuiltInCategory.OST_Rooms,
+            ["rooms"] = BuiltInCategory.OST_Rooms,
+            ["area"] = BuiltInCategory.OST_Areas,
+            ["areas"] = BuiltInCategory.OST_Areas,
+            ["column"] = BuiltInCategory.OST_Columns,
+            ["columns"] = BuiltInCategory.OST_Columns,
+            ["roof"] = BuiltInCategory.OST_Roofs,
+            ["roofs"] = BuiltInCategory.OST_Roofs,
+            ["stair"] = BuiltInCategory.OST_Stairs,
+            ["stairs"] = BuiltInCategory.OST_Stairs,
+            ["ceiling"] = BuiltInCategory.OST_Ceilings,
+            ["ceilings"] = BuiltInCategory.OST_Ceilings,
+            ["furniture"] = BuiltInCategory.OST_Furniture,
+            ["pipe"] = BuiltInCategory.OST_PipeCurves,
+            ["pipes"] = BuiltInCategory.OST_PipeCurves,
+            ["duct"] = BuiltInCategory.OST_DuctCurves,
+            ["ducts"] = BuiltInCategory.OST_DuctCurves,
+            ["beam"] = BuiltInCategory.OST_StructuralFraming,
+            ["beams"] = BuiltInCategory.OST_StructuralFraming,
+            ["structural framing"] = BuiltInCategory.OST_StructuralFraming,
+            ["generic model"] = BuiltInCategory.OST_GenericModel,
+            ["generic models"] = BuiltInCategory.OST_GenericModel,
+            ["level"] = BuiltInCategory.OST_Levels,
+            ["levels"] = BuiltInCategory.OST_Levels,
+            ["grid"] = BuiltInCategory.OST_Grids,
+            ["grids"] = BuiltInCategory.OST_Grids,
+            ["sheet"] = BuiltInCategory.OST_Sheets,
+            ["sheets"] = BuiltInCategory.OST_Sheets,
+            ["view"] = BuiltInCategory.OST_Views,
+            ["views"] = BuiltInCategory.OST_Views,
+        };
+
+        public static ElementId Resolve(Document doc, string input)
+        {
+            string trimmed = input.Trim();
+            if (trimmed.Length == 0)
+                throw new ArgumentException("category must be a non-empty string.");
+
+            if (Aliases.TryGetValue(trimmed, out var alias))
+                return new ElementId(alias);
+            if (TryParseBuiltInCategory(trimmed, out var builtIn))
+                return new ElementId(builtIn);
+            if (TryParseBuiltInCategory("OST_" + trimmed.Replace(" ", string.Empty), out builtIn))
+                return new ElementId(builtIn);
+
+            foreach (Category category in doc.Settings.Categories)
+            {
+                if (string.Equals(category.Name, trimmed, StringComparison.OrdinalIgnoreCase))
+                    return category.Id;
+            }
+
+            throw new ArgumentException($"Unknown category: {input}. Use a BuiltInCategory enum name (e.g. OST_Walls) or a category display name as shown in Revit (e.g. Walls, Doors, Sheets, Views).");
+        }
+
+        private static bool TryParseBuiltInCategory(string text, out BuiltInCategory category)
+        {
+            category = BuiltInCategory.INVALID;
+            return text.Length > 0
+                && char.IsLetter(text[0])
+                && Enum.TryParse(text, true, out category)
+                && category != BuiltInCategory.INVALID;
+        }
+    }
+
+    /// <summary>
+    /// Resolves a Revit API class name ("Wall", "ViewSheet", "WallType", or a full
+    /// name like "Autodesk.Revit.DB.Mechanical.Duct") to its Type for OfClass filters.
+    /// </summary>
+    internal static class ElementClassResolver
+    {
+        private static readonly Lazy<IReadOnlyDictionary<string, Type>> BySimpleName = new(BuildSimpleNameMap);
+
+        public static Type Resolve(string input)
+        {
+            string trimmed = input.Trim();
+            var assembly = typeof(Element).Assembly;
+            Type? match = trimmed.Contains('.') ? assembly.GetType(trimmed, false, true) : null;
+            match ??= assembly.GetType("Autodesk.Revit.DB." + trimmed, false, true);
+            if (match is null)
+                BySimpleName.Value.TryGetValue(trimmed, out match);
+
+            if (match is null || !typeof(Element).IsAssignableFrom(match))
+                throw new ArgumentException($"Unknown Revit element class: {input}. Use an Element subclass from the Revit API (e.g. Wall, FamilyInstance, ViewSheet, Level, WallType) or a full name like Autodesk.Revit.DB.Mechanical.Duct.");
+            if (match == typeof(Element))
+                throw new ArgumentException("of_class must be a concrete Element subclass, not Element itself.");
+            return match;
+        }
+
+        private static IReadOnlyDictionary<string, Type> BuildSimpleNameMap()
+        {
+            Type[] types;
+            try
+            {
+                types = typeof(Element).Assembly.GetTypes();
+            }
+            catch (System.Reflection.ReflectionTypeLoadException ex)
+            {
+                types = ex.Types.OfType<Type>().ToArray();
+            }
+
+            var map = new Dictionary<string, Type>(StringComparer.OrdinalIgnoreCase);
+            foreach (var type in types)
+            {
+                if (!type.IsPublic || !typeof(Element).IsAssignableFrom(type))
+                    continue;
+                // Prefer the root Autodesk.Revit.DB namespace when simple names collide.
+                if (!map.TryGetValue(type.Name, out var existing) || (type.Namespace == "Autodesk.Revit.DB" && existing.Namespace != "Autodesk.Revit.DB"))
+                    map[type.Name] = type;
+            }
+            return map;
+        }
+    }
+
+    /// <summary>
+    /// Resolves friendly forge unit names ("millimeters", "squareMeters") or full forge
+    /// ids ("autodesk.unit.unit:millimeters-1.0.1") to UnitTypeId values, and back.
+    /// </summary>
+    internal static class UnitResolver
+    {
+        private static readonly Lazy<IReadOnlyDictionary<string, ForgeTypeId>> ByName = new(Build);
+
+        public static ForgeTypeId Resolve(string unit)
+        {
+            string trimmed = unit.Trim();
+            if (ByName.Value.TryGetValue(trimmed, out var match))
+                return match;
+            throw new ArgumentException($"Unknown unit: {unit}. Use a forge unit name like millimeters, meters, feet, inches, squareMeters, cubicFeet, degrees.");
+        }
+
+        /// <summary>"autodesk.unit.unit:millimeters-1.0.1" -> "millimeters".</summary>
+        public static string ShortName(ForgeTypeId unit)
+        {
+            string id = unit.TypeId ?? string.Empty;
+            int colon = id.IndexOf(':');
+            string tail = colon >= 0 ? id[(colon + 1)..] : id;
+            int dash = tail.IndexOf('-');
+            return dash >= 0 ? tail[..dash] : tail;
+        }
+
+        private static IReadOnlyDictionary<string, ForgeTypeId> Build()
+        {
+            var map = new Dictionary<string, ForgeTypeId>(StringComparer.OrdinalIgnoreCase);
+            foreach (ForgeTypeId unit in UnitUtils.GetAllUnits())
+            {
+                map[ShortName(unit)] = unit;
+                map[unit.TypeId] = unit;
+            }
+            return map;
+        }
+    }
+
+    /// <summary>Identity-only element row shared by the query tools.</summary>
+    internal static class ElementIdentity
+    {
+        public static readonly IReadOnlyList<string> Fields = new[] { "id", "name", "category", "typeName", "levelId" };
+
+        public static Dictionary<string, object?> Build(Document doc, Element element, IReadOnlyList<string> fields)
+        {
+            var row = new Dictionary<string, object?>(fields.Count);
+            foreach (string field in fields)
+            {
+                row[field] = field switch
+                {
+                    "id" => (object?)element.Id.Value,
+                    "name" => element.Name,
+                    "category" => element.Category?.Name,
+                    "typeName" => doc.GetElement(element.GetTypeId())?.Name,
+                    "levelId" => element.LevelId is { } levelId && levelId != ElementId.InvalidElementId ? levelId.Value : (long?)null,
+                    _ => null,
+                };
+            }
+            return row;
+        }
+    }
+
+    /// <summary>Small JsonElement argument readers shared by the tools.</summary>
+    internal static class JsonArgs
+    {
+        public static string? GetString(JsonElement args, string name)
+            => args.ValueKind == JsonValueKind.Object && args.TryGetProperty(name, out var value) && value.ValueKind == JsonValueKind.String
+                ? value.GetString()
+                : null;
+
+        public static bool GetBool(JsonElement args, string name, bool fallback)
+            => args.ValueKind == JsonValueKind.Object && args.TryGetProperty(name, out var value) && value.ValueKind is JsonValueKind.True or JsonValueKind.False
+                ? value.GetBoolean()
+                : fallback;
+
+        public static int GetInt(JsonElement args, string name, int fallback)
+            => args.ValueKind == JsonValueKind.Object && args.TryGetProperty(name, out var value) && value.ValueKind == JsonValueKind.Number && value.TryGetInt32(out int parsed)
+                ? parsed
+                : fallback;
+
+        public static long? GetLong(JsonElement args, string name)
+        {
+            if (args.ValueKind != JsonValueKind.Object || !args.TryGetProperty(name, out var value))
+                return null;
+            if (value.ValueKind == JsonValueKind.Number && value.TryGetInt64(out long fromNumber))
+                return fromNumber;
+            if (value.ValueKind == JsonValueKind.String && long.TryParse(value.GetString(), out long fromString))
+                return fromString;
+            return null;
+        }
+
+        public static List<long> GetLongArray(JsonElement args, string name)
+        {
+            if (args.ValueKind != JsonValueKind.Object || !args.TryGetProperty(name, out var value) || value.ValueKind != JsonValueKind.Array)
+                throw new ArgumentException($"Missing or invalid required field: {name} must be an array of element ids.");
+
+            var result = new List<long>(value.GetArrayLength());
+            foreach (var item in value.EnumerateArray())
+            {
+                if (item.ValueKind == JsonValueKind.Number && item.TryGetInt64(out long fromNumber))
+                    result.Add(fromNumber);
+                else if (item.ValueKind == JsonValueKind.String && long.TryParse(item.GetString(), out long fromString))
+                    result.Add(fromString);
+                else
+                    throw new ArgumentException($"{name} must contain only integer element ids.");
+            }
+            return result;
+        }
+
+        public static List<string>? GetStringArray(JsonElement args, string name)
+        {
+            if (args.ValueKind != JsonValueKind.Object || !args.TryGetProperty(name, out var value) || value.ValueKind != JsonValueKind.Array)
+                return null;
+
+            var result = new List<string>(value.GetArrayLength());
+            foreach (var item in value.EnumerateArray())
+            {
+                string? text = item.ValueKind == JsonValueKind.String ? item.GetString() : null;
+                if (string.IsNullOrWhiteSpace(text))
+                    throw new ArgumentException($"{name} must contain only non-empty strings.");
+                result.Add(text.Trim());
+            }
+            return result;
+        }
+    }
+}

package/workspace/AGENTS.md

@@ -0,0 +1,23 @@
+# 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; Revit 2025, 2026, or 2027 must be running with a project open
+(only `ping` and `search_api_docs` work without a document).
+
+## Conventions
+
+- One subfolder per Revit project under `Projects\`; start Pi from inside the project folder so
+  sessions, notes, and outputs stay scoped to that project.
+- Save exports, captured view PNGs, scripts, and analysis results inside the current project
+  folder (e.g. an `exports\` subfolder) — not in temp, not in the model's directory.
+- Keep per-project knowledge (naming conventions, known model quirks, decisions) in the project
+  folder's own `AGENTS.md` so every session starts informed.
+
+## Tool habits
+
+- Start unfamiliar models with `get_model_overview`; use `get_elements` for any listing or
+  counting; read parameter values with `get_element_details`.
+- 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.
+  A failed `execute_csharp` rolls back entirely and reports the error.