{"id":50486824,"url":"https://github.com/systemslibrarian/cipher-detective-ai","last_synced_at":"2026-06-01T23:02:34.708Z","repository":{"id":356573390,"uuid":"1233141147","full_name":"systemslibrarian/cipher-detective-ai","owner":"systemslibrarian","description":null,"archived":false,"fork":false,"pushed_at":"2026-05-08T18:21:37.000Z","size":5049,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-08T18:39:20.049Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/systemslibrarian.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-08T16:27:23.000Z","updated_at":"2026-05-08T18:21:41.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/systemslibrarian/cipher-detective-ai","commit_stats":null,"previous_names":["systemslibrarian/cipher-detective-ai"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/systemslibrarian/cipher-detective-ai","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/systemslibrarian%2Fcipher-detective-ai","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/systemslibrarian%2Fcipher-detective-ai/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/systemslibrarian%2Fcipher-detective-ai/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/systemslibrarian%2Fcipher-detective-ai/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/systemslibrarian","download_url":"https://codeload.github.com/systemslibrarian/cipher-detective-ai/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/systemslibrarian%2Fcipher-detective-ai/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33797128,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-01T02:00:06.963Z","response_time":115,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-01T23:02:34.165Z","updated_at":"2026-06-01T23:02:34.703Z","avatar_url":"https://github.com/systemslibrarian.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"---\ntitle: Cipher Detective AI\nemoji: 🕵️‍♂️\ncolorFrom: indigo\ncolorTo: yellow\nsdk: gradio\nsdk_version: 4.44.0\napp_file: app.py\npinned: false\nlicense: mit\ntags:\n  - cryptography\n  - cryptanalysis\n  - classical-ciphers\n  - cipher\n  - transformers\n  - text-classification\n  - cybersecurity-education\n  - gradio\n  - nlp\n  - machine-learning\n  - python\n  - substitution-cipher\n  - vigenere\n  - caesar-cipher\n  - educational\n---\n\n# 🕵️‍♂️ Cipher Detective AI\n\n\u003e **See the pattern. Test the hypothesis. Break the weak cipher. Respect the strong ones.**\n\nCipher Detective AI is an **educational** classical-cryptanalysis exhibit. It detects and decodes **81 historical cipher types** — from Caesar and Vigenère to Rail-Fence, Columnar, Playfair, and more — using a transparent heuristic engine and an optional fine-tuned Transformer classifier. It teaches how weak historical ciphers leak patterns, how cryptanalysis actually works, and **why modern cryptography is fundamentally different.**\n\nIt is built as a Hugging Face-native triple:\n\n| Artifact | Repo                                              | Role                                         |\n|----------|-------------------------------------------------------------|----------------------------------------------|\n| Space    | [systemslibrarian/cipher-detective-ai](https://huggingface.co/spaces/systemslibrarian/cipher-detective-ai) | Live interactive exhibit (this app) |\n| Dataset  | [systemslibrarian/classical-cipher-corpus](https://huggingface.co/datasets/systemslibrarian/classical-cipher-corpus) | Labeled classical-cipher examples |\n| Model    | [systemslibrarian/cipher-detective-classifier](https://huggingface.co/systemslibrarian/cipher-detective-classifier) | Small Transformer classifier |\n\n**This is not an offensive tool.** It does not break modern encryption, recover passwords, or bypass access controls. See [`docs/educational-boundary.md`](docs/educational-boundary.md).\n\n---\n\n## ✨ Demo\n\n\u003e Open the live Space to try it: \u003chttps://huggingface.co/spaces/systemslibrarian/cipher-detective-ai\u003e\n\u003e Static screenshots live in [`screenshots/`](screenshots/) once captured (the\n\u003e README intentionally avoids broken `\u003cimg\u003e` tags before they exist).\n\n---\n\n## 🧭 Modes\n\nThe Gradio Space ships with **seven** tabs:\n\n1. **Detect** — paste ciphertext, get a classification, confidence, and a full evidence report (frequency, IoC, entropy, Caesar/Affine candidates, Kasiski/Friedman indicators, transposition signal). One-click random examples.\n2. **Evidence Notebook** — see the raw evidence without a verdict — useful for teaching step-by-step cryptanalysis.\n3. **Challenge** — generate practice ciphertexts (Caesar, Atbash, Vigenère, Rail-Fence, Columnar, Affine, Substitution) at chosen difficulty.\n4. **Try Decode** — ten decryption methods with automatic English-quality scoring:\n   - *Auto modes (no key needed):* auto-best-Caesar, auto-best-Affine, auto-Vigenère (Kasiski + Friedman), auto-rail-fence (brute-force rails 2–15)\n   - *Keyed modes:* Caesar/ROT, Atbash, Vigenère, Beaufort, Affine, Columnar transposition\n5. **Compare Mode** — run the **transparent heuristic baseline** and the **Transformer classifier** side-by-side, with disagreement analysis.\n6. **Solve Substitution** — hill-climbing solver for monoalphabetic substitution using a blended bigram + trigram log-probability score. Educational only — converges on ~120+ letters of English.\n7. **About** — project background, educational boundaries, and links.\n\n---\n\n## 🚀 Run locally\n\n```bash\ngit clone https://github.com/systemslibrarian/cipher-detective-ai.git\ncd cipher-detective-ai\npython -m venv .venv \u0026\u0026 source .venv/bin/activate\npip install -r requirements.txt\npython app.py\n```\n\nThe Space will be at \u003chttp://localhost:7860\u003e.\n\nTo attach a trained Transformer classifier:\n\n```bash\nexport CIPHER_MODEL_ID=systemslibrarian/cipher-detective-classifier   # or a local folder path\npython app.py\n```\n\nIf the model can't be loaded, the app **always** falls back to the transparent heuristic baseline.\n\n---\n\n## 🧪 Tests\n\n```bash\npip install -r requirements-dev.txt\npytest\n```\n\nCoverage spans cipher round-trips, edge cases (empty / non-alpha input), feature signals (IoC, entropy, Kasiski, Friedman, transposition), the heuristic classifier, and the dataset generator schema.\n\n---\n\n## 🗂️ Generate the dataset\n\nQuick demo (5,000 rows):\n\n```bash\npython scripts/generate_dataset.py --out data/cipher_examples.jsonl --n 5000 --seed 42\n```\n\nPublic-release size (50,000 rows):\n\n```bash\npython scripts/generate_dataset.py --out data/cipher_examples.jsonl --n 50000 --seed 42\n```\n\nEach row includes `id`, `text`, `ciphertext`, `plaintext`, `label`, `cipher`, `key`, `difficulty`, `language`, `text_length`, `attack_methods`, and `educational_note` — see [`hf_cards/dataset_README.md`](hf_cards/dataset_README.md).\n\n---\n\n## 🧠 Train the model\n\n```bash\npython scripts/train_transformer.py \\\n  --data data/cipher_examples.jsonl \\\n  --model distilbert-base-uncased \\\n  --out cipher_model \\\n  --epochs 3\n```\n\nOutputs land in `cipher_model/`:\n\n- model + tokenizer\n- `training_metrics.json` (accuracy, macro precision/recall/F1)\n- `label_mapping.json` (`label2id` / `id2label`)\n\nTo upload to the Hub afterwards:\n\n```bash\nhuggingface-cli login\nhuggingface-cli upload systemslibrarian/cipher-detective-classifier ./cipher_model\n```\n\n---\n\n## 📊 Evaluate\n\nHeuristic baseline only:\n\n```bash\npython scripts/evaluate_baseline.py --data data/cipher_examples.jsonl --out reports/baseline_metrics.json\n```\n\nCompare heuristic vs Transformer:\n\n```bash\npython scripts/evaluate_baseline.py \\\n  --data data/cipher_examples.jsonl \\\n  --model cipher_model \\\n  --out reports/baseline_metrics.json\n```\n\nReport includes accuracy, macro F1, per-class precision/recall/F1, confusion matrix, and the dataset's label distribution.\n\n---\n\n## 🏷️ Labels\n\nThe classifier covers **81 cipher classes**, including:\n\n`plaintext`, `caesar_rot`, `atbash`, `vigenere`, `beaufort`, `rail_fence`, `columnar`, `affine`, `substitution`, `playfair`, `four_square`, `two_square`, `hill_cipher`, `bifid`, `trifid`, `adfgx`, `adfgvx`, `enigma`, `lorenz`, `morse_code`, `tap_code`, `navajo_code`, `pigpen`, `baconian`, `polybius`, `straddling_checkerboard`, `chaocipher`, `nihilist`, `porta`, `rot13`, `rot47`, `gronsfeld`, `running_key`, `autokey`, `one_time_pad`, `venona_pad_reuse`, `voynich`, `babington`, and more.\n\nSee [`data/cipher_examples.jsonl`](data/cipher_examples.jsonl) for the full label distribution.\n\n---\n\n## 🛣️ Roadmap\n\n- [ ] Publish `classical-cipher-corpus` dataset (50k rows).\n- [ ] Train and publish `cipher-detective-classifier`.\n- [ ] Add `screenshots/` images.\n- [x] Hill-climbing solver demo for monoalphabetic substitution (educational only).\n- [x] Per-length and per-difficulty evaluation buckets.\n- [x] Vigenère auto-solver (Kasiski + Friedman key-length estimation).\n- [x] Rail-fence and columnar transposition decoders.\n- [x] Beaufort cipher support (encrypt + decrypt).\n- [x] Bigram + trigram blended scoring for hill climber.\n- [x] GitHub Actions → Hugging Face Space auto-sync on every push.\n- [ ] Calibration plot (heuristic confidence vs accuracy).\n- [ ] Multilingual plaintext sources (clearly labeled).\n- [ ] Linked exhibit pages from Cipher Museum / Crypto Lab.\n\nSee [`CHANGELOG.md`](CHANGELOG.md) for what's already shipped.\n\n---\n\n## 🌐 Ecosystem\n\nCipher Detective AI is part of a broader cryptography-education path:\n\n- **Cipher Museum** — curated history of ciphers _(link placeholder)_\n- **Crypto Compare** — algorithm comparisons _(link placeholder)_\n- **Crypto Lab** — hands-on experimentation _(link placeholder)_\n- **Meow Decoder** — friendly entry point _(link placeholder)_\n\nSee [`docs/ecosystem.md`](docs/ecosystem.md).\n\n---\n\n## 🛡️ Educational boundary\n\nThis project teaches classical cryptanalysis. It is **not** designed to:\n\n- break modern encryption (AES, ChaCha20, RSA, ECC, TLS, age, PGP),\n- recover passwords or password hashes,\n- bypass access controls or DRM,\n- support surveillance or unauthorized access,\n- make claims about real-world cryptographic security.\n\nModern cryptography depends on vetted primitives, protocols, key management, implementation correctness, metadata handling, and an honest threat model. None of the techniques shown here apply to it. See [`docs/educational-boundary.md`](docs/educational-boundary.md).\n\n---\n\n## 🤝 Contributing\n\nSee [`CONTRIBUTING.md`](CONTRIBUTING.md). Honest, transparent, education-first contributions are very welcome.\n\n## 🔐 Security\n\nSee [`SECURITY.md`](SECURITY.md) for how to report a vulnerability.\n\n## 📜 License\n\nMIT — see [`LICENSE`](LICENSE).\n\n## 📚 Citation\n\nIf you use this in teaching or writing, see [`CITATION.cff`](CITATION.cff).\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsystemslibrarian%2Fcipher-detective-ai","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsystemslibrarian%2Fcipher-detective-ai","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsystemslibrarian%2Fcipher-detective-ai/lists"}