Redesigning schema generation

[iboB]

Too much time has already been spent on this...

The current solution is unpleasant.

• It instantiates default vars on every Object instance
• Child vector is allocated and filled every time
• It does not maintain potential constness of the input Dict
• There is some general clunkiness in using get/setValue
• Validation is obscure and not enforced on Return-s
• The project structure is bad, as in the schema lib is based off of nlohmann::json whereas our Dict will likely be modified

These all are fixable if we base the structure on something like https://github.com/alpaca-core/mini-reflect. Some problems will remain:

• Defining helper types is not yet clear
• Reusing the same type in the tree will multiply its reflection info

A redesign of mini-reflect is possible, where we separate the reflection info into instance-info and type-info. Then we wrap the fields in a template to properly instantiate (on-demand placement construct members would have to be implemented).

Anyway... we can go very very deep in this rabbit hole and design a super cool runtime (auto-)reflection library. This will take multiple days or maybe a couple of weeks. There are many use cases and edge cases to consider.

While the task is pretty cool, I think it's time to draw the line and just use something simpler.

I've considered three alternative approaches:

1. Flip it and codegen
   • Instead of building the schema from the C++ source, build the C++ source from the schema as a codegen step.
   • We will have to create our own tool for this, but it will be much less effort than doing the runtime auto-reflection path.
   • The tool may be handy if we decide to generate code for other languages as well
   • It may evolve into a library to be used in the doc front end
   • Everybody hates codegen, though
2. Visit fields like it's 1998
   • Create template visitFields methods for wrapped structs.
   • Some (not a lot) of code duplication will be present: declaring a field and then visiting it explicitly.
   • The code will be simple and clean, and immediately understandable by C++ programmers
   • This can solve all problems from above, but will introduce a new one: Fields will have to be copied to Dict and vice versa.
     • This is especially unpleasant for containers (vectors, maps, etc).
     • But it seems likely that we will only ever have very few of these and the allocation perf penalty will be small compared to other code. Params and Return's will likely be small besides member Blob-s, and Blob-s won't suffer from the above problem.
     • Mitigations to this are possible if we have Dict-based fields
   • Runtime reflection in and of itself will be lost, but note that we don't actually have a use case for this beyond converting to Dict and generating schema
3. Macros like it's 1988
   • When there's codegen is a solution to a problem, there's always an uglier, nastier macro-based alternative.
   • The only benefit here this is not external codegen
   • The macros will be nasty and will hide a lot of code
   • This will not be usable elsewhere
   • Yeah, we can disregard this option, but I did consider it

So far I'm leaning heavily towards 2, despite the copy implications.

[iboB]

One argument for option 1 came up when the documentation generation was discussed.

With option 1 one doesn't need to build the repo and a C++ build toolchain in order to obtain the usage schema as it's the source, rather than the product.

[iboB]

The strength of this argument got drastically reduced when we found out that Swift requires the entire build toolchain and a full build to generate docs

[iboB]

One more argument for option 1 is that the codegen can be used for other languages.

[iboB]

And more on this: schemas are essentially not bound to plugins, but instead live their own lives.

Multiple independent plugins should be able to support the same schema. For example a schema can be "LLM" with plugins llama.cpp and llamafile supporting it.

And more on this. A plugin should be able support multiple schemas.

[iboB]

It's resolved. Schemas are to be much more complex and the only reasonable way to handle the complexity would be option 1. Schemas are independent of code and plugins