One sentence into that readme I can tell you that yes, it most definitely counts as slop.
I get that it’s an early prototype and not all the design choices are made yet, but I struggle with “I can’t afford human-readable documentation yet”. Isn’t human readable documentation important for efficiently planning and deciding what you want to build? I feel like I can’t afford not to have human readable docs and plans while the project is taking shape
Related, if a user can prompt an agent to translate to a human-readable summary, wouldn’t it be better to just do this in place? Sure, models can deal with noisy LLM outputs but shouldn’t a document that’s easier for humans also be easier for bots?
Yes, it would probably be better to have something like that if you're struggling to plan and decide. In my particular case this has been a project that I have dreamt about and tinkered with for at least 15 years now. Most of the work I'm doing is just refinement of existing ideas what were already codified in other projects I've built.
Why don't I do this in place? The amount of churn is utterly incredible as ideas are refined and taken to the limit. These agents are getting quite good, but they regularly make the silliest of mistakes. You actually have to be extremely cautious about what you document because it often has a way of becoming "doctrine" to the agents. In fact, one of the most difficult parts of working on this project has been that the foundational properties cause the agents to lock down behavior WAY too early.
This is a frequent pattern among AI users. What causes it?
I think it's because it makes them seem...smarter? More technical? But they can't describe who it's for or what the actual design is without consulting an AI.
Given that you stated your readme is for bots, given that you expect our own AI to interpret it based on your evidence, how do I, as a human, go about evaluating this project without just writing it off as slop from the linked evidence?
What is the starting off point for a human, not an AI agent, to evaluate this?
And to be clear if the answer is to just download arbitrary code onto my machine and run it, that’s not good enough given the increase in attacks from AI projects and fake recruiters telling you to just run it bro. I’ve already had to pass on multiple interviews despite being unemployed because the human/ai on the other side demanded root access or for me to run arbitrary code onto my machine as part of their process.
That said, the maths library might just be the best thing to start with because it's mostly stable, relatively simple, and virtually every other part of the project depends on it in some way. If graphics are more your jam then maybe check out the SDF VM project and associated documents. All rendering goes through a single instruction set that is implemented via a shader pipeline that allows arbitrary scenes to be defined without shader recompilation. The project is essentially multiple compilers wearing a trench coat so there's a little bit of something for everyone... like two fully implemented emulators of the brick variety, including peripherals.
If you're adventurous and want to have your favorite LLM give the project a review in a sandbox then I think that'd be neat! Especially considering that they would have absolutely no problem driving everything themselves through STDIN. Though I totally understand if that's not something you're keen on doing considering the state of things today. Either way, cheers!
https://github.com/ByteTerrace/Puck/blob/main/src/Puck.Maths...
Some of us aren't just slopping it up like @theo and all the other AI influencers are, as I developed nearly every single line of this by hand over the span of the past decade. Agents recently became capable of factchecking it and helped find bugs that my other unit testing never caught. Software engineering has never been more alive!
https://gist.github.com/Kittoes0124/6827d08e457c1c8b790422af...
This is a snippet I wrote years ago to help me study different formulations of the equation ((1 + √5) / 2). There was this thing I could "see" in there that would allow me index into these sequences, and whole families of others, in O(1) time. The problem is that I still don't know enough maths to derive the exact object that I want from the nonsense that I have.
https://github.com/ByteTerrace/Puck/blob/main/src/Puck.Maths...
This is the reformulation of that snippet into a proper object, distilled using Fable and Sol. Unlike BinaryIntegerFunctions, I didn't write a line of this and I'm quite happy with that. It's been a slog for so long... being able to let these agents toil away at all the off-by-one type noise is just nice. I get to focus on an actual product for once instead of manufacturing every single nut and bolt myself.
A form of recursion is also doing a lot of heavy lifting because the emulators are their own separate deterministic engines that are dynamically plumbed into the primary loop. This not only allows us to embed diegetic devices (as in, you can literally pick up a glowing brick in the world, hold it to your face, and play it), but also validates that the primary loop is coded accurately because the outer loop runs at X Hz while humble bricks must run at ~59.7275 Hz. Pacing inaccuracies in the main loop cause us to fail the brick suites that we test against. This concept of having features reinforce one another is applied as often as possible.
The obsession with determinism goes so far that both the DirectX and Vulkan backends are validated against each other for pixel level differences. If they differ more than the expected maximum then code is refactored until the drift is back within acceptable range.