keybridge: neural decipherment of historical simple and homophonic substitution ciphers

Archives hold many cipher keys whose ciphertexts have never been identified, and many ciphertexts whose keys are unknown. This tool helps connect the two. For a known key, it trains a small neural network on synthetic examples. That network then reads authentic ciphertexts written with the key, and fails visibly on ciphertexts written with other keys.

The method and its evaluation are described in: [citation to be added]

Three ways to use it

The Colab notebooks need only a Google account and a web browser. Nothing has to be installed, and no code has to be written. Keys and transcriptions are simple text files in one standard format (symbols separated by spaces): see Key file format and Transcription format.

For research use, keybridge evaluate scores a model's reading of an authentic ciphertext against its key (F1 with confidence intervals), as reported in the paper; see LOCAL_INSTALL.md.

What it can and cannot do

It can

• produce draft decipherments of transcribed ciphertexts written with a known key;
• help judge whether a ciphertext was written with a given key: text in the key comes out readable, text in another key comes out as nonsense;
• rank the keys in a collection by how well a ciphertext fits them, and say which language each output reads most like.

It cannot

• find an unknown key. A key, or at least the full table of which symbol means what, must already be known;
• replace expert review. All outputs are drafts, and the ranking scores have not yet been validated on real collections.

Cipher features that are not supported

The tool handles simple and homophonic substitution, where each cipher symbol stands for exactly one thing (a simple substitution cipher is the special case with one symbol per letter): a letter, a group of letters, a whole word (nomenclature), a word gap, a null, or a "repeat the previous letter" sign. The following are not supported:

• Codes written without separators. A transcription such as 067547700454, meaning the codes 0675 4770 0454, cannot be split correctly. Transcribe with spaces between codes.
• Symbols with several meanings (polyphones). Each symbol can stand for only one thing.
• Context-dependent rules. Symbols whose meaning depends on their position or on neighbouring symbols.
• Cancellation signs. Symbols that mean "ignore the previous symbol" or "delete the next symbol".
• Other cipher types. Polyalphabetic ciphers (where the key changes during the text), transposition, and codebooks that need more than a symbol-for-unit table.

Python users can imitate some of these with custom edits (see the guides).

Privacy

In Colab, files are processed on Google's servers for the length of a session, and are deleted when it ends unless you save them to Google Drive. Nothing is shared unless you choose to share a trained model. For full control, use the local version.

Repository contents

Licence and citation

• Code (src/, tools/, notebooks/): MIT licence.
• Models, keys, language profiles and documentation: CC BY 4.0.

You may use and adapt all of it for any purpose. If you use the tool, its models or its keys in your work, please cite the publication above. GitHub's "Cite this repository" button gives the reference (CITATION.cff). When you use a model from the shared collection, please also credit the original source of its key, given in the model's description.