Better decorator names

[liamhuber]

@ligerzero-ai and I had the chance to chat today. When I asked him where pain points are, one of the things that came up was that new users often struggle with the fact that macro-defining functions are not being run when the macro is run -- they expect them to be more like @as_function_node behaves.

Now, since macros are always just going to run their graph at runtime, I think it's necessary to maintain that the macro decorators are placed on their recipe -- but I absolutely agree we can and should make this distinction clearer by more distinctive and informative decorator names.

Right now, I'm thinking

• @as_function_node --> @as_node_function
• @as_macro_node --> @as_macro_recipe
• @as_dataclass_node --> @as_dataclass_node

Any other ideas? @samwaseda you have contact with new users too, any suggestions from your end?

[samwaseda]

I don't have a strong opinion or any particular feedback. I personally would like you and @jan-janssen to come up with a way to synchronize this kind of stuff as much as possible.

[jan-janssen]

I am a big fan of short names, how about @node, @macro and @dataclass ?

[liamhuber]

I am a big fan of short names, how about @node, @macro and @dataclass ?

Currently the shorter names (those without a prefix) allow users to instantly obtain a node instance, where those with prefixes give a class, i.e. @as_function_node gives the new class, function_node(...) gives the instance.

The _node suffix is there to remind users that even though things look like a function, they're getting back a node class/object. I am content to drop it.

I am happy to then shorten to @as_macro to @macro if we purge the instance-returning functions. I am totally fine with this. As far as I know, everyone is always using it in the format of defining a node class and then using that.

@dataclass is a non-starter because this is already how a vanilla python dataclass is defined.

@node is appealing, except that macros are also nodes. This is necessary to have nested composability. So I would be fuly behind this change if Macro and Function didn't both inherit from Node, but I don't have a better idea for the name of Node than "Node" -- in fact, I rather think it's an excellent name. So here I'd rather be verbose than misleading.

That would leave us with @function_node, @macro, and @dataclass_node. I'm not sure anyone is happy with that.

What about @node and @recipe, where @node implicitly parses functions as function nodes and classes as dataclass nodes, and @recipe parses functions as macro nodes?

[jan-janssen]

I liked the combination of @node and @recipe. I am just wondering if macro is a more commonly used term than recipe. How about @node and @node_parser ? This highlights that the both decorators generate nodes.

[liamhuber]

Super, nice we are converging so quickly, and I like this much better than my original idea.

I agree "recipe" is probably not so broadly used. Nonetheless, this is a term I picked up at the PMD meeting last fall, and I liked it. Even if it's not as popular yet, I'm motivated to start pushing it on people so that we start fostering mental clarity on the distinction between a prospective intention graph, and a retrospective has-results graph. What about @macro_recipe?

[jan-janssen]

How about @node_recipe ? I like the use of the same prefix so the user already knows it is a decorator to generate a node, yet it is a special one. Alternatively we could also use a special parameter like @node(convert_to_recipe=True).

[liamhuber]

I still prefer @macro_recipe as I think it should be sufficiently clear that macros are also nodes, but I could live with @node_recipe too. I'd prefer to avoid the parameters as there are already other parameters these decorators can (all) take, and also then we might as well go back to very long function names.

@samwaseda @ligerzero-ai -- @jan-janssen and I have converged to @node for both functions and dataclasses (implicitly parseable by function vs class as the subject) and @node_recipe or @macro_recipe for macros. Is this palatable to you? Any alterations or preferences?

[liamhuber]

Ah, I just thought of something annoying. If we call a decorator @node and want to expose it in the top-level API, then this will conflict with any main-level module named node. This is not a deal-breaker for me, but there is already such a module so I need to first think of a different name for that.