While TruthInTheFlip Runs: Building a Fluent Command Line for the Not-Too-Distant Future
TruthInTheFlip is currently in the middle of a long simulation run.
Both IDQ quantum-random-number-generator modules are initialized and supplying entropy, and the present plan is simple: leave the simulation alone and let it accumulate data. There is little value in disturbing a successful multiweek run merely to create the appearance of activity.
That does not mean development has stopped.
Instead, I have been working on the infrastructure that will help inspect the results when the run is complete.
The immediate project is called TruthInTheFlip_CSV_Farm. Its purpose is to divide tracker data into segments, select report fields, and emit clean CSV that can be consumed directly by Python, Pandas, Matplotlib, or other analytical tools.
A command may eventually look something like this:
seg_report filename.tkr by_length 100000000000 total a.Best end.TrueZ
The C# application will remain responsible for understanding TruthInTheFlip’s tracker structures and producing accurate segment reports. Python can then concentrate on plotting and exploration without needing to understand the internal simulation model.
That alone would be useful, but the command-line layer growing out of the project has become interesting in its own right.
From Command Parsing to a Typed Function Graph
Most command-line parsers begin with strings.
They identify switches, consume positional arguments, convert values, and eventually populate an options object. This works, but it often creates a parallel program beside the real program:
-
application functions
-
command definitions
-
parsing rules
-
validation rules
-
help text
-
default descriptions
-
documentation
-
sometimes a second machine-readable tool schema
These pieces must then be kept synchronized.
FluentCommandLine takes a different approach. It begins with typed methods.
For example, a segment selector may be declared conceptually like this:
[FluentMethod("by_length")]
[KV_FA(FluentAttribute.Help, "Segment by length")]
public static SegSelector ByLength(
[KV_FA(FluentAttribute.Help, "Length of each segment")]
[KV_FA(FluentAttribute.Def, "100000000000")]
long length)
{
return new SegSelector(length);
}
A report command can then consume the type produced by that method:
[FluentMethod("seg_report")]
[KV_FA(FluentAttribute.Help, "Generate a report")]
public static ReportCommand SegmentReport(
string trackerPath,
SegSelector selector,
string[] fields)
{
return new ReportCommand(trackerPath, selector, fields);
}
The command line is therefore not interpreted as an arbitrary sequence of strings. It is interpreted as a composition of functions whose inputs and outputs are already known.
When the report command requires a SegSelector, the environment knows to look for a fluent method that produces a SegSelector. When by_length requires a long, the contextual parser registered for long is used.
The machine always knows what type it is looking for.
That produces a small but meaningful function graph:
seg_report
trackerPath: string
selector: SegSelector
by_length
length: long
fields: string[]
The textual command line is a path through that graph.
Deliberate Rather Than Magical
Reflection is involved, but the design is intentionally not based on broad or accidental discovery.
The application deliberately supplies:
-
the method modules to load
-
the return-specific registries
-
the contextual parsers for supported types
-
the result types permitted at the command-line root
-
the metadata used for help and defaults
A parameter of type long does not cause the parser to search through a collection of unrelated conversions and hope that something accepts the token. It calls the configured parser for long.
A parameter of type SegSelector is not treated as a string that will later be interpreted by the application. It is fulfilled by a registered fluent expression that produces a SegSelector.
This makes the language extensible without making it unpredictable.
For a domain-specific reporting application, the long parser might accept metric notation:
100M
100B
2T
Another application may retain strict integer parsing. If a program needs both meanings at once, it can introduce a semantic wrapper such as MetricLong, FlipCount, or SegmentLength.
The type system provides room to grow without forcing every program to carry every abstraction.
A Command Line That Describes Itself
Because the environment already knows the methods, parameter types, defaults, help text, and return relationships, it can generate its own documentation.
Current output is beginning to resemble this:
Available Commands
-help
Request this help.
seg_report trackerPath selector fields
Generate a report.
trackerPath <String> Path to tracker file
selector <SegSelector>
fields <String[]>
Argument Types
<SegSelector> — Selector for segmenting
by_length length
Segment by length.
length <Int64> default: "100000000000"
Configuration information can also preserve the structure of the parsed command:
Report command: seg_report trackerPath selector fields
Values:
trackerPath=filename.tkr
selector=<SegSelector> {
Selector for segmenting: by_length length
Values: length=100000000000
}
fields=[total, a, b, c]
This is more than formatted help text.
The parser retains a structured RegistryParseResult containing the selected method, its argument results, nested fluent expressions, arrays, defaults, and final produced value. The executable result and the account of how it was constructed are both available.
That opens the door to:
-
generated help
-
command listings
-
configuration reports
-
canonical command reconstruction
-
richer diagnostics
-
HTML or JSON documentation
-
shell completion
-
auditing and explanation
-
machine-readable tool descriptions
The same declarations that define the CLI can support all of these surfaces.
Why This May Be Useful for Agents
This self-description ability makes FluentCommandLine a particularly interesting fit for agent utilities.
An agent needs to know:
-
which actions exist
-
what parameters they require
-
which nested choices are valid
-
which defaults are available
-
how values should be represented
-
what was actually interpreted
-
why a requested operation failed
That is nearly the same information FluentCommandLine already needs to produce good human-facing help.
A future adapter could expose the environment as a neutral description model:
FluentEnvironment
Commands
Argument types
Methods
Parameters
Defaults
Help
Contextual parsers
From that model, separate renderers could generate both human documentation and agent tool schemas.
The important point is not that arbitrary methods become callable by an agent. That would be too broad and too difficult to reason about.
The application defines the permitted function graph deliberately. The agent sees only the operations the developer chose to register, under the same type and parsing rules used by the ordinary command line.
This could reduce one of the recurring forms of software plumbing: implementing an application operation, implementing a CLI wrapper for it, and then implementing yet another agent-tool wrapper that describes nearly the same operation again.
Once an application is organized as typed, composable functions, much of that interface can be derived rather than separately maintained.
A Future CrystalCatalyst Proving Ground
TruthInTheFlip is the first serious consumer, but I can already imagine a very different second one.
CrystalCatalyst has cross-platform clipboard support. An advanced clipboard utility could use commands such as:
clipboard set text/html string "<h1>Hello from the clipboard</h1>"
clipboard set text/plain file message.txt
clipboard get text/html
clipboard formats
That would test several new dimensions:
-
quoted strings
-
MIME types
-
file-backed content
-
standard-input content
-
binary and textual payloads
-
commands that retrieve data
-
platform-specific execution behind a portable command model
The command:
clipboard set text/html string "<h1>Hello from the clipboard</h1>"
is again a function graph expressed as readable text.
set consumes a MIME type and clipboard content. string produces clipboard content from a string. A file method could produce the same content abstraction from a path.
TruthInTheFlip exercises segment selectors, arrays, reporting metadata, and scientific output. CrystalCatalyst could exercise composition, files, markup, binary data, and platform services.
A shared framework becomes more trustworthy when unrelated applications stress different parts of it.
Toward JWCEssentials
FluentCommandLine is currently being developed beside TruthInTheFlip_CSV_Farm, where it can evolve against a real need without changing the established build contract of the running experiment.
In the not-too-distant future, I expect it to find a more permanent home in JWCEssentials.
That move should happen after the important contracts have been exercised:
-
deterministic cursor-based parsing
-
contextual type parsers
-
return-specific method registries
-
nested fluent expressions
-
array arguments
-
target-type-controlled root commands
-
generated help, list, and info output
-
stable diagnostics
-
tests covering parser invariants
The current application is therefore both a useful reporting tool and a proving ground for reusable technology.
Building While Waiting
There is something satisfying about this phase of the project.
TruthInTheFlip is doing what it needs to do: running, accumulating quantum entropy, and moving toward a larger body of evidence.
Meanwhile, the surrounding tools are becoming more capable.
When the simulation finishes, I do not merely want a large tracker file. I want a clean way to ask questions of it:
Segment it this way.
Show me these fields.
Return the result as CSV.
Plot the behavior.
Compare the regions.
Preserve exactly how the report was configured.
That immediate need has led to a more general idea: a typed command line that can describe itself, compose functions, support humans and scripts, and perhaps eventually make the production of agent utilities substantially easier.
It began as plumbing.
It is starting to look like infrastructure.