Python/FastAPI backend for the AI Cipher Decoder project. Hosts the cipher engine, the cryptanalysis solvers, and the chatbot orchestration layer that powers the frontend.
Pairs with the ai-cipher-decoder-frontend repo, which provides the UI. This backend can also be run and tested entirely on its own via its API endpoints.
- Cipher engine (
app/ciphers/) — deterministic encrypt/decrypt for each supported cipher when the key is known: Caesar, Atbash, Affine, Vigenère, Hill, Nihilist, Baconian, Porta, Pollux, Morbit, Fractionated Morse, and keyed Aristocrat/Patristocrat. - Cryptanalysis solvers (
app/solvers/) — cracks ciphertext without a known key using frequency analysis, quadgram scoring, and hill-climbing/simulated annealing search:- Aristocrat/Patristocrat substitution solver
- Vigenère solver (Kasiski examination + Index of Coincidence)
- Xenocrypt (Spanish-language) solver
- Cryptarithm solver (
app/solvers/cryptarithm_solver.py) — solves letter-arithmetic puzzles (e.g.SEND + MORE = MONEY) using constraint-satisfaction search over possible letter-to-digit assignments, rather than language-frequency techniques. - Chatbot orchestration (
app/chatbot/) — wraps the cipher and solver functions as tools the Anthropic API can call, so a user can type something like "decrypt this Caesar cipher: KHOOR ZRUOG" in plain English and get back both the answer and an explanation of the steps. - REST API (
app/routes/) — the endpoints the frontend calls to hit all of the above.
ai-cipher-decoder-backend/
├── app/
│ ├── main.py # FastAPI entrypoint, CORS setup, route registration
│ ├── config.py # env vars / settings
│ │
│ ├── ciphers/ # deterministic cipher engine
│ │ ├── base.py # shared helpers (mod26 math, text cleaning, alphabet utils)
│ │ ├── caesar.py
│ │ ├── atbash.py
│ │ ├── affine.py
│ │ ├── vigenere.py
│ │ ├── hill.py # matrix math (uses numpy)
│ │ ├── nihilist.py
│ │ ├── baconian.py
│ │ ├── porta.py
│ │ ├── pollux.py
│ │ ├── morbit.py
│ │ ├── fractionated_morse.py
│ │ ├── aristocrat.py # keyed encrypt/decrypt only
│ │ └── registry.py # maps cipher name -> functions; used by routes + chatbot tools
│ │
│ ├── solvers/ # cryptanalysis / auto-crack engine
│ │ ├── quadgram_scorer.py # loads frequency table, scores text
│ │ ├── hill_climb.py # simulated annealing / hill-climbing search
│ │ ├── aristocrat_solver.py # substitution cracker (hill_climb + scorer)
│ │ ├── vigenere_solver.py # Kasiski + IoC + column frequency analysis
│ │ ├── xenocrypt_solver.py # Spanish-language variant
│ │ └── cryptarithm_solver.py # constraint-satisfaction solver for letter-arithmetic puzzles
│ │
│ ├── data/ # frequency tables & corpora (needed at runtime)
│ │ ├── english_quadgrams.txt
│ │ ├── spanish_quadgrams.txt
│ │ └── practice_texts/ # sample plaintexts for generating practice ciphertext
│ │
│ ├── chatbot/ # Anthropic API integration
│ │ ├── client.py # Anthropic API client setup
│ │ ├── tools.py # tool/function-calling definitions wrapping ciphers + solvers
│ │ └── orchestrator.py # handles a chat turn: intent -> tool call -> explanation
│ │
│ ├── routes/
│ │ ├── cipher_routes.py # /encrypt, /decrypt
│ │ ├── solver_routes.py # /solve (auto-crack)
│ │ ├── cryptarithm_routes.py # /cryptarithm (solve letter-arithmetic puzzles)
│ │ └── chat_routes.py # /chat
│ │
│ └── tests/
│ ├── test_ciphers.py
│ ├── test_solvers.py
│ └── test_cryptarithm.py
│
├── requirements.txt
├── .env.example
├── .gitignore
└── README.md
git clone <this-repo-url>
cd ai-cipher-decoder-backend
python -m venv venv
source venv/bin/activate # Windows: venv\Scripts\activate
pip install -r requirements.txt
cp .env.example .env
# then open .env and add your ANTHROPIC_API_KEY
uvicorn app.main:app --reloadThe API will be running at http://localhost:8000. Interactive docs (auto-generated by FastAPI) are available at http://localhost:8000/docs.
| Variable | Description |
|---|---|
ANTHROPIC_API_KEY |
API key used by the chatbot orchestration layer to call Claude |
| Endpoint | Method | Description |
|---|---|---|
/encrypt |
POST | Encrypt plaintext with a given cipher + key |
/decrypt |
POST | Decrypt ciphertext with a given cipher + key |
/solve |
POST | Auto-crack ciphertext with no key (Aristocrat, Vigenère, Xenocrypt) |
/cryptarithm |
POST | Solve a letter-arithmetic puzzle (e.g. SEND + MORE = MONEY), returns the digit mapping |
/chat |
POST | Send a natural-language message; chatbot picks the right tool and responds |
Full request/response schemas are viewable at /docs once the server is running.
pytest app/tests/The solvers require frequency data to score candidate decryptions:
app/data/english_quadgrams.txt— English quadgram frequencies, used by the Aristocrat and Vigenère solversapp/data/spanish_quadgrams.txt— Spanish quadgram frequencies, used by the Xenocrypt solver
Source for these: practicalcryptography.com.
- Python 3.11+
- FastAPI
- Uvicorn
- NumPy (matrix math for Hill cipher)
- Anthropic API (chatbot orchestration)
- Frontend repo:
ai-cipher-decoder-frontend— plain HTML/CSS/JS UI that consumes this API