Macro Packs
A macro is a function on the application server. The model writes one short call, and the server expands it into ordinary A2UI components before anything reaches the renderer. When we package our macros to share them, we call the bundle a macro pack.
What is a macro?
The model writes the call, such as a line chart with a few numbers. The server runs the macro, which builds the whole tree of components, so the model writes about a kilobyte or less where the finished message runs to several thousand bytes or more. Because the expansion happens on the server, the client has nothing to register when the components come from the Basic Catalog. The d3 pack page shows the measured sizes for six examples.
Macro expansion is part of the official A2UI project: its Python agent SDK has a macros module, in its transformers package, with a @macro decorator and a MacroExpander class.
Two targets: the Basic Catalog and a custom catalog
Basic Catalog target (what our macros do today)
The macro call expands to Basic Catalog components: a Card, Text, and an Image that carries the drawing as an SVG, with Row and Button when the example has controls. The examples on the d3 pack page list the exact components of each. Because everything in the message is a Basic Catalog component, any renderer that supports the Basic Catalog can show it.
Custom catalog target (planned, not built)
In a custom catalog the same call would expand to our own components (atoms) in place of the Image, so the client draws the chart itself. Our d3 atoms take the same inputs as the d3 pack's macros where an atom exists. None of our macros emits atoms today: every message they send names the Basic Catalog and nothing else, and there is no demo of the custom target yet.
From macros to macro packs
We write macros one at a time. When we package a set of them together with their tests, licence and notices, we share the set as a macro pack. We have two so far.
- The d3 pack27 macros: d3-style charts plus Connect Four, a brick builder, availability and a latency ledger, each drawn as an SVG in Python.
- The architecture packOne macro, arch_motion: an architecture diagram with a wide and a narrow view and motion that plays once.
Status
- Both packs are private and cannot be installed today.
- Our code is under the MIT licence.
- The d3 pack's charts are our own Python re-implementations. They are not pixel-identical to d3.
- The pack source is 414,274 bytes of Python in 45 files (the d3pack and archpack packages, measured when this page was built).
Some macros port or follow these d3 modules; their licences and copyright notices are kept with our code:
- d3-array 3.2.4 (ISC): Copyright 2010-2023 Mike Bostock
- d3-hierarchy 3.1.2 (ISC): Copyright 2010-2021 Mike Bostock
- d3-chord 3.0.1 (ISC): Copyright 2010-2021 Mike Bostock
- d3-shape 3.2.0 (ISC): Copyright 2010-2022 Mike Bostock
- d3-contour 4.0.2 (ISC): Copyright 2012-2023 Mike Bostock
- d3-delaunay 6.0.4 (ISC): Copyright 2018-2021 Observable, Inc.; Copyright 2021 Mapbox
- d3-sankey 0.12.3 (BSD-3-Clause): Copyright 2015, Mike Bostock