ntnsndr/protocol-bicorder
1
0
Fork 0
Code Issues 2 Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit of Protocol Bicorder with json and txt set up

Browse Source
This commit is contained in:
Nathan Schneider
2025-10-21 15:21:40 -06:00
commit 9f46b3a2ac
5 changed files with 689 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

110
README.md Normal file
View File

@@ -0,0 +1,110 @@
# Protocol Bicorder
The Protocol Bicorder is a diagnostic tool for the study of protocols. It allows a human or machine user to evaluate protocol characteristics along a series of gradient scales.
The name is a tribute to the [tricorder](https://en.wikipedia.org/wiki/Tricorder), a fictional device in the Star Trek franchise that the characters can use to obtain all manner of empirical data about their surroundings.
## Using the bicorder
These instructions can guide humans or machines in utilizing the bicorder. The bicorder, foundationally, consists of a JSON file that may or may not have values filled out. A completed bicorder file should have all or most of the values filled out. Filling out the values can be done either manually, through editing the JSON file directly, or by using software that takes input in other forms and translates it to a JSON reading. These instructions are for editing the JSON file directly, but they should be useful with other interfaces as well.
The bicorder consists of three components:
* `metadata` about the current reading, including information about the protocol and its analyst
* `diagnostic` composed of sets of gradients that measure the analyst's interpretation of the protocol
* `analysis` that interprets the diagnostic data
### Metadata
There are several pieces of information that provide metadata about a given reading with the bicorder. More details about the data formats for each input are provided in `bicorder.schema.json`.
* `protocol`: Name of the protocol or brief description
* `analyst`: Name or other identifier of the analyst conducting the diagnostic
* `standpoint`: Describe, even at some length, the relationship between the analyst and the protocol, including any relevant context that could affect the diagnostic readings
* `timestamp`: A timestamp for when the reading occurred
### Diagnostic
To carry out the diagnostic, the analyst should consider the protocol from the perspective of one of the `gradients` at a time. The gradients invite the analyst to determine where the protocol lies between two terms.
This is inevitably an interpretive exercise, but do your best to identify the most accurate `value`, with `1` being closest to `term_left` and `9` being closest to `term_right`.
Choosing a `value` in the middle, such as `4`, can mean "a bit of both" or "neither."
### Analysis
The Analysis part of the bicorder is meant to be automated. Its `value` fields are based on calculations on the above gradients. Each analysis is also a gradient, whose value is derived from the gradients in the diagnostic. Each analysis has an `instructions` field that explains how to produce the `value` for that analysis.
## Interfaces
There are several ways to use the bicorder.
### Machine-readable JSON
The most basic way to use the bicorder is to simply edit a JSON file:
* Make a copy of `bicorder.json` with an appropriate file-name
* Fill out the `metadata` and `diagnostic` sections appropriately
* Based on the `diagnostic` inputs, process the `analysis` values following the relevant `instructions` fields
### ASCII chart
An ASCII chart can be generated from a JSON file. This can be useful as a human-readable output, or as a human-usable way to carry out a diagnostic. The included Python script works both for the `bicorder.json` template or for a completed JSON file with values added.
Usage:
`python ascii_bicorder.py [INPUT.json] [OUTPUT.txt]`
An example output file from the template is maintained at `bicorder.txt`.
### Human-usable web app
* Create an online tool for reporting a protocol
- Web app for fun that can be used with a mobile phone
- Include tooltips for descriptions
- Auto-analyze
- Enable it to produce a JSON printout
### Synthetic data analysis
* Experiment plan
- Have AIs fill it out with example protocols
- Review papers on synthetic datasets
- Perhaps use local models or campus Gemini---try two parallel processes with appropriate supervision. Find literature on this. Do parallel processes on both dataset generation and bicorder coding
- Make sure to include a broad range of protocols, reflecting diversity of cultures, mediums, and scales
- Data analysis of correlations
- Which gradients seem to travel together?
- Perhaps convert this or generate it in JSON so it is easily machine-ingestible
<!---
## To do
* Try data analysis
* Continue iterating on the bicorder design
* Develop the web app in a way that is tightly bound to the canonical JSON and schema
### Gradient citations
- implicit / explicit
- See Pomerantz book on Standards, p. 16: de facto and de jure
- Social / technical
- From Primavera's Protocol Art talk
- Kafka / Whitehead (Asparouhva)
- Measuring the extent to which the protocol imposes burdens on users as opposed to freeing them to focus on something else
- flock / swarm (Fernández)
- Measuring the degree of variation as opposed to uniformity the protocol enables
- soft / hard (Stark)
- dead / alive (Friend; Alston et al.; Walch)
- related especially to whether it is actively performed)
- insufficient / sufficient (Kittel & Shorin; Rao et al.)
- Measuring the extent to which the protocol as such solves the problems it is designed to solve, or whether it relies on external mechanisms
- tense / crystallized
- Marc-Antoine Parent countered the idea of "engineered arguments" (which assume ongoing tension) with "crystallized arguments" (which memorialize past tensions that are no longer active). For instance, English is tense, Arabic numerals are crystallized.
--->
## Authorship and licensing
Initiated by [Nathan Schneider](https://nathanschneider.info) and available for use under the [Hippocratic License](https://firstdonoharm.dev/) (do no harm!). Several AI assistants were utilized in developing this tool.
[![Hippocratic License HL3-CORE](https://img.shields.io/static/v1?label=Hippocratic%20License&message=HL3-CORE&labelColor=5e2751&color=bc8c3d)](https://firstdonoharm.dev/version/3/0/core.html)