Metadata-Version: 2.4
Name: keybridge
Version: 1.0.0
Summary: Shared-space neural decipherment of historical simple and homophonic substitution ciphers
Author: Micaella Bruton, Meriem Beloucif, Beáta Megyesi
License: MIT
Project-URL: Homepage, https://github.com/mbruton0426/keybridge
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: LICENSE-CC-BY-4.0.txt
Requires-Dist: torch>=2.1
Requires-Dist: scikit-learn>=1.0
Requires-Dist: huggingface_hub>=0.20
Requires-Dist: datasets>=2.14
Requires-Dist: optuna>=3.0
Provides-Extra: search
Dynamic: license-file

# 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]* <!-- PLACEHOLDER -->

## Three ways to use it

| | What it does | Where it runs |
|-|--------------|---------------|
| **① Train a model for your key** | You provide a key and plaintext in the cipher's language; you get a trained model and, optionally, a draft decipherment of your transcription. | [Open in Colab](https://colab.research.google.com/github/mbruton0426/keybridge/blob/main/notebooks/1_train_your_own_model.ipynb) · [Guide](docs/TRAINING_GUIDE.md) |
| **② Read or scan a ciphertext** | Runs your transcription through one model, or all models in the shared collection. Ranks which keys it fits and which language the result reads like. | [Open in Colab](https://colab.research.google.com/github/mbruton0426/keybridge/blob/main/notebooks/2_read_or_scan_a_ciphertext.ipynb) · [Guide](docs/READING_AND_SCANNING_GUIDE.md) |
| **Local version** | The same as ① and ② from the command line, entirely on your own computer. It can run fully offline. | [Install and use](docs/LOCAL_INSTALL.md) |

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](docs/KEY_FORMAT.md)** and **[Transcription format](docs/TRANSCRIPTION_FORMAT.md)**.

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](docs/LOCAL_INSTALL.md#score-a-reading-against-the-key-research).

## 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](docs/LOCAL_INSTALL.md).

## Repository contents

| Folder | Contents |
|--------|----------|
| `notebooks/` | The two Colab notebooks (generated by `tools/build_notebooks.py`). |
| `src/keybridge/` | The Python package used by the notebooks and the command line. |
| `docs/` | Guides for users, and [setup notes for maintainers](docs/MAINTAINER_SETUP.md). |
| `examples/` | Example keys (Maximilian II, Copiale) and a synthetic transcription. |
| `tools/` | Scripts for building the notebooks and the language statistics. |
| `hf_collection_template/` | Template for the Hugging Face model collection. |
| `LICENSE`, `LICENSE-CC-BY-4.0.txt`, `CITATION.cff` | Licences and citation information. |

## Licence and citation

- **Code** (`src/`, `tools/`, `notebooks/`): [MIT licence](LICENSE).
- **Models, keys, language profiles and documentation:** [CC BY 4.0](LICENSE-CC-BY-4.0.txt).

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](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.
