Skip to content

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

2 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 

Repository files navigation

AI Cipher Decoder — Backend

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.

What this backend does

  1. 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.
  2. 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
  3. 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.
  4. 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.
  5. REST API (app/routes/) — the endpoints the frontend calls to hit all of the above.

Project structure

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

Setup

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 --reload

The API will be running at http://localhost:8000. Interactive docs (auto-generated by FastAPI) are available at http://localhost:8000/docs.

Environment variables

Variable Description
ANTHROPIC_API_KEY API key used by the chatbot orchestration layer to call Claude

API overview

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.

Running tests

pytest app/tests/

Data dependencies

The solvers require frequency data to score candidate decryptions:

  • app/data/english_quadgrams.txt — English quadgram frequencies, used by the Aristocrat and Vigenère solvers
  • app/data/spanish_quadgrams.txt — Spanish quadgram frequencies, used by the Xenocrypt solver

Source for these: practicalcryptography.com.

Tech stack

  • Python 3.11+
  • FastAPI
  • Uvicorn
  • NumPy (matrix math for Hill cipher)
  • Anthropic API (chatbot orchestration)

Related

  • Frontend repo: ai-cipher-decoder-frontend — plain HTML/CSS/JS UI that consumes this API

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors