Creating A Specification After the Fact Using AI

Introduction

Protocol specifications are normally written before independent implementations are attempted. The specification is the common contract: it tells each implementer what must be sent, what must be accepted, what may be rejected, and what behavior is expected. Reticulum and LXMF present a different problem: much of the “protocol” must be inferred from a working Python implementation. That is like asking a contractor to derive the building code from a finished house down the street.

A House Is Not a Building Code

Imagine you want to build a house in the year 1908.  If you build a house, you probably should use an architect who then designs your house according to the applicable building codes where your house will be located.  The house is designed to meet the building codes.

Your architect and contractor normally have building codes to reference to make sure your house meets standards.  But suppose they did not, they only have an “reference implementation”, e.g. the house down the street that you like and want to duplicate?  They’re told they have to use the house down the street as an implementation of what the unspecified codes are.

So this house & building codes metaphor is where a software developer might feel when attempting to create an implementation of a “protocol” when all he has to work with is an existing code base instead of specifications.  It’s not impossible, but the developer certainly will have his work cut out for him.

My Current Problem: Understanding Reticulum’s LXMF Implementation Protocol

I’ve been focused with the Reticulum “protocol” and implementing it in C++ using Chad Attermann’s microReticulum.  microReticulum is Reticulum written in C++ instead of using the Python scripting language where Reticulum was conceived and remains.  Reticulum was in beta ¹ development until May, 2025.

Using Python on a microcomputer such as a LilyGo T-Beam SUPREME would not be a wise decision; the ESP32-S processor is usually coded in C++² as housing a Python interpreter in the small memory space of the T-Beam would be challenging, at best. I never gave much thought about Reticulum being called a protocol and assumed somewhere buried in the extensive documentation there was a specification for the protocol.

I had assumed that when something was called a protocol, there would be a specification document somewhere behind it. That assumption was wrong. There is no specification.  In Reticulum’s case, the term “protocol” is being used in a more implementation-centered sense: the authoritative behavior is embodied in the Python code base and accompanying manual. If one wants to create a C++, Rust, Java, or other independent implementation, one must study the Python implementation and infer the required behavior in order to make the migrated code conform.

I’ve been using microReticulum now for several weeks and testing and came to the realization I was using Reticulum’s LINK protocol to send messages back and forth among the various T-Beams.  As I ran into problems, I realized the error of my decision to use the LINK “protocol”.  I have since learned that the current practice for Reticulum clients is to use the LXMF (Lightweight Extensible Message Format) “protocol” ³.  So now I really wanted to see a specification so I could understand precisely what would be needed to accomplish T-Beams talking to one another and just how they handle reaching out and communicating.  How would they exchange messages?  That’s when I learned about what I think of a protocol being, i.e. something with a specification such as RFC 9110 (infra), vs. “reference implementation” protocol.  I was not familiar with the term “reference implementation” as I assumed the use of the term protocol meant there was an underlying specification.  “My bad.” ⁴

Protocols With Specifications

HTTP

Here is an example of a protocol that has a specification: Hypertext Transfer Protocol (“HTTP”).

HTTP is the application-level protocol that lets web clients and servers exchange requests and responses: a browser asks for a resource, and a server replies with status, headers, and content. Unlike a code base where “the implementation is the protocol,” HTTP has formal specifications maintained through the IETF [Internet Engineering Task Force] RFC [Request for Comments] process. RFC 9110 “HTTP Semantics” defines HTTP’s common semantics: methods such as GET and POST, status codes, header fields, caching concepts, URI schemes, and the rules shared across HTTP versions. RFC 9112 then specifies the HTTP/1.1 wire format: message syntax, parsing, connection handling, and related security concerns.

A programmer writing an HTTP server in C, Java, Perl, Python, or C++ is not supposed to reverse-engineer Apache, nginx, curl, or Firefox and call that the protocol; the programmer codes against the specification. In that sense, the specification is the contract: it says what conforming implementations must send, must accept, may reject, and may extend. The house-building analogy is close: an as-built house can reveal many design choices, but it is a poor substitute for the building code, drawings, tolerances, and inspection criteria that tell everyone else how to build a compatible, and safe, inspectable structure that complies with current codes.

Other Protocols

See also these protocols and their specifications:

• File Transfer Protocol ⁵, or FTP, for transferring files between client and server systems;
• Domain Name System ⁶, or DNS, for resolving names such as example.com into network addresses;
• Simple Mail Transfer Protocol ⁷, or SMTP, for transporting email between mail servers;
• Internet Message Access Protocol ⁸, or IMAP , for accessing and managing email stored on a mail server;
• Secure Shell ⁹, or SSH, for secure remote login and command execution; and
• Transport Layer Security ¹⁰, or TLS, for encrypting and authenticating network communications.

Each of these is implemented by many independent programs, but the programs are expected to interoperate because they code to published specifications rather than to one favored source tree.

(My sensitivity to this problem probably comes from years of documentation work with structured markup when I worked at the world’s largest database company supporting the Applications Division documentation, we migrated from HTML ¹¹ to XML to use Arbortext XML Editor in the early 2000s with the Oracle Internet File System (iFS) rebranded as Content Management Software Development Kit (CMSDK), most other XML¹² authoring houses used Documentum built atop an Oracle database, and then in around 2020, we migrated from Arbortext to Oxygen Editor, so XML became my lingua franca.)

An AI Solution

GitHub user thatSFguy employed a very clever solution for the problem of deriving a specification from the code base implementation of the Reticulum “protocol”. thatSFguy’s project is to come up with a specification for Reticulum.  His answer was to have Anthropic’s Claude, an artificial intelligence tool, digest the Reticulum code base and then create a specification.

This diagram sums up what AI does:

So I referenced thatSFguy‘s project and asked ChatGPT, could I do the same for the LXMF “protocol”.  The answer was “yes [indeedy].”  And ChatGPT provided me a prompt to provide Codex along with a sequence of three tasks to assure a stable and thoughtful progression.  I have staged the results on my Forgejo project LXMF-specification.

For example, here’s a preliminary table Codex created after the first task — this would be the heart of the specification.

Still to do is verifying “test vectors” ¹³ and then processing changes to the mainline Python code and updating this derived specification.

Conclusion

The goal is not to criticize an implementation that works. A finished house can be beautiful, and a Python implementation can be elegant. The problem appears when others are asked to build compatible structures from the example alone. A specification turns observed behavior into a contract. My 40 years being a lawyer makes contracts ingrained into my nature. Test vectors then make that contract executable: same input, same output, independent implementation. That is where AI may be genuinely useful—not as an oracle, but as a disciplined assistant for reading code, extracting rules, identifying ambiguities, and helping turn “look at the source” into something other implementers can build against.

1. “The Reticulum Protocol is defined entirely and authoritatively by this reference implementation, and this manual. ” Source: https://reticulum.network/manual/whatis.html#current-status  On May 9, 2025, Reticulum moved out of “beta”.  Source: https://unsigned.io/articles/2025_05_09_The_End_Is_Nigh_For_The_Beta_Days.html
2. Running ordinary Python on a T-Beam would be challenging at best, and in the usual sense almost certainly the wrong tool for the job. A T-Beam is built around an ESP32-class microcontroller, not a Linux-style application processor. Depending on the board revision, it may have roughly hundreds of kilobytes of internal SRAM, a few megabytes of flash, and sometimes external PSRAM; one common T-Beam listing describes an ESP32 with 520 KB SRAM, 4 MB flash, and 4 MB PSRAM. That is generous for embedded firmware, but tiny compared with the memory environment expected by the normal desktop/server Python interpreter, CPython. There is a MicroPython port for ESP32 boards with at least 4 MiB of flash, but MicroPython is a deliberately reduced embedded Python environment, not the same thing as dropping a full Python runtime and an arbitrary Python code base onto the board. In practice, a T-Beam program that speaks LoRa, handles timing, watches memory allocation, manages radio buffers, and runs from battery is normally written as firmware in C or C++, or in a carefully constrained embedded runtime. This is another reason a protocol specification matters: if the only “specification” is a tree of Python scripts, then implementing the same behavior on a T-Beam requires reverse-engineering Python behavior into microcontroller-scale firmware rather than simply coding to a clear, language-neutral contract.

   Sources for footnotes: the T-Beam hardware class is ESP32-based, and one representative T-Beam listing gives 520 KB SRAM, 4 MB flash, and 4 MB PSRAM. (TinyTronics) MicroPython’s ESP32 firmware is aimed at ESP32 boards with 4 MiB or more of flash, including WROOM/WROVER-style modules. (MicroPython) MicroPython’s own constrained-device documentation emphasizes RAM limitations, heap fragmentation, and minimizing object creation/destruction on microcontrollers. (docs.micropython.org) Espressif describes the ESP32 as a Wi-Fi/Bluetooth SoC for IoT and embedded applications, able to operate as a standalone microcontroller or as a communications subsystem for another processor. (espressif.com)

   Contrast those resources with what an ordinary Python interpreter expects on a Gentoo Linux workstation. Even a do-nothing python3 -c 'pass' process commonly occupies several to tens of megabytes of resident RAM before it performs any useful work. A real Reticulum process then adds the Reticulum code, runtime objects, buffers, routing state, interface handling, and cryptographic machinery. On a workstation, that is usually trivial; on an ESP32-class T-Beam, where RAM and flash are measured in kilobytes and a few megabytes, the gap is not merely inconvenient. It is the difference between running a general-purpose operating-system process and writing tightly constrained embedded firmware.

   Rust is also moving into the ESP32 space, offering memory-safety advantages over C and C++ in some embedded contexts, though the ESP32 ecosystem is still heavily C/C++ centered.  See Reticulum-rs, a Rust implementation of the Reticulum Network Stack; esp-rs, Libraries, crates and examples for using Rust on Espressif SoC’s, and  YouTube video From Zero to ESP32 Bootloader in Embedded Rust by The Rusty Bits

3. “LXMF is a simple and flexible messaging format and delivery protocol that allows a wide variety of implementations, while using as little bandwidth as possible. It is built on top of Reticulum and offers zero-conf message routing, end-to-end encryption and Forward Secrecy, and can be transported over any kind of medium that Reticulum supports.” https://github.com/markqvist/LXMF
4. Informal idiom, see https://dictionary.cambridge.org/dictionary/english/my-bad.  Garner, B. (2016). my bad. In Garner’s Modern English Usage. : Oxford University Press. Retrieved 6 Jun. 2026, from https://www.oxfordreference.com/view/10.1093/acref/9780190491482.001.0001/acref-9780190491482-e-5299.
5. FTP — RFC 959, File Transfer Protocol. (RFC Editor)
6. DNS — RFC 1035, Domain Names — Implementation and Specification. (IETF Datatracker)
7. SMTP — RFC 5321, Simple Mail Transfer Protocol. (IETF Datatracker)
8. IMAP — RFC 9051, Internet Message Access Protocol Version 4rev2. (IETF Datatracker)
9. SSH — RFC 4251, The Secure Shell Protocol Architecture. (IETF Datatracker)
10. TLS — RFC 8446, The Transport Layer Security Protocol Version 1.3. (IETF Datatracker)
11. The HTML specification when printed to PDF is 1,061 pages.
12. XML is not a protocol; it is a markup language for representing structured information. More precisely, it is a meta-language: a set of rules for creating specialized markup languages or document formats. Protocols may use XML as their message format, but XML itself does not define how two machines communicate.
13. A test vector is a known input together with the exact expected output. It is used to prove that two independent implementations behave the same way.