Alexandria Library

Introduction

Alexandria Library is a component library for Grasshopper, Rhino 8’s visual scripting environment. Each component is a self-contained GhPython or C# script that addresses one parametric-design problem — gridding a boundary, remapping values, folding a panel, exporting parameters to a CSV file. There is no compiled plugin: every component ships as a Grasshopper User Object, a single .ghuser file installed by dropping it into Grasshopper’s own User Object folder, with no plugin build or Yak package involved.

Each of those User Objects is a thin bridge. It carries only the component’s docstring and ghenv metadata; at solve time it locates this repository on disk and executes the matching scripts/<domain>/*.py file directly. An installed component therefore always runs whatever is currently in scripts/, which makes that folder the single source of truth for every component’s behaviour.

The library spans nine domains, summarised below. Individual component behaviour is documented by domain under Component Reference; the full source is public in the repository.

Counted from scripts/ by tools/build.py whenever this page is rebuilt. The packaged count trails the component count because a User Object is written from a live Grasshopper canvas rather than by the build, so a component stays unpackaged until someone runs UserObjMkr against it.

Repository Structure

The repository is organised as follows; paths are given relative to the repository root.

Installation

The library is distributed as Grasshopper User Objects, not a compiled plugin, and is installed as follows. The order matters: step four is the one that is easy to miss and the one that produces the only common failure.

1. Clone or download this repository to a local folder and keep it intact — the folder containing scripts/ and CLAUDE.md must remain in place, since every component locates it at solve time (see step four). Move it later and re-run RepoPath.
2. Copy every .ghuser file from grasshopper/userobjects/ into Grasshopper’s own User Object folder. Find that folder from Grasshopper’s File > Special Folders > User Object Folder menu — its exact location is OS- and install-specific, so use the menu rather than a hardcoded path.
3. Restart Rhino, or reload the Grasshopper ribbon. The components appear under the Alexandria tab, grouped into panels by domain: Document, Fabrication, Folding, Geometry, Grid, Math, Pattern, Signage, Utility. Within a panel they are further grouped into sections, separated by a rule.
4. Drop the RepoPath component onto a canvas, give it the path to the folder cloned in step one, and press its button. It records that path once, for every component on every canvas — so a definition saved anywhere on disk can find the library. Components resolve the library in three ways, and the first that answers wins: the ALEXANDRIA_REPO_ROOT environment variable, the path recorded by RepoPath, then walking up from the open .gh file for a folder holding both scripts/ and CLAUDE.md. A canvas that satisfies none of the three fails at solve time saying so.

Component Reference

Every component follows the header contract recorded in documentation/development.md, and everything below is generated from those headers, so this section cannot drift from the code it documents. The nine domains map one-to-one to a scripts/<domain> folder and to a panel of the Alexandria ribbon; the names beside each domain are its ribbon sections.

Open a domain to see each of its components drawn as a schematic — input ports on the left, the component in the centre, output ports on the right, or a note in place of outputs where the component’s result is a side effect. Ports are listed in the order they must appear on the component, and each port’s type label states its data access: a plain type is item access, “List of” is list access, “Tree of” is tree access.

Development Notes

scripts/<domain>/*.py is the source of truth, and it is also what actually runs: there is no compiled plugin to rebuild. Editing a script’s logic is live the next time its component solves.

Editing a script’s header, however, does not automatically update the installed User Object. The header is copied into ui_shells/ and baked into the packaged .ghuser, so a header change takes three further steps: re-run tools/build.py to regenerate the bridges and this page, paste the updated bridge onto a canvas, and re-package it with the UserObjMkr component, which reads every ribbon detail back out of the script itself.

Port names, types and tooltips come from the same header. Each script reads its own header at solve time and writes the description of every port it recognises by name, so a port’s tooltip in Grasshopper is the line that documents it here. Adding or renaming a port is still a manual step on the component itself — Grasshopper owns the parameter list, not the script.

Two components sit outside the bridge. ClusterCrack is C#, which the generator does not handle. RepoPath is the component that tells the others where the library is, so it cannot depend on finding it. Both carry their source inline in their own .ghuser and are packaged by pasting the script itself onto a canvas rather than a bridge.

The build enforces the contract rather than trusting it: a script with a malformed header, an unknown data type, an undescribed port, a duplicated name or a ribbon section that is not in the registry stops the build with the file named. There is no automated test suite beyond that; behaviour is verified by hand in Grasshopper. Conventions for AI coding tools working in this repository are recorded in CLAUDE.md.

Reference

• Design Standards The type scale, palette, rule weights and document conventions this page is built from — rendered in the design itself.
• Alexandria Library The source repository: every script, every packaged User Object, and the tool that keeps them in step.
• documentation/user-guide.md Installing the library, the ribbon layout, reading a component’s ports, the parameter CSV workflow, and what to do when a component cannot find the library.
• documentation/architecture.md How the three layers fit together, which changes are live and which are baked into the packaged User Object, and where each fact is declared.
• documentation/development.md How to change or add a component: the header contract, naming, ribbon sections, the icon set, and the rules this page follows.
• documentation/components.md The same component reference as this page, as tables with icons — generated from the scripts alongside it.
• documentation/changelog.md What changed and when, newest first. Behaviour changes that affect an existing canvas are recorded here.
• tools/build.py The one build step: it regenerates the bridges, the component reference and this page’s generated sections from scripts/.
• CLAUDE.md Repository notes for AI coding agents. Load-bearing at solve time as well: a component looking for the library looks for a folder holding both scripts/ and this file.