An advanced Python tool for automatic cipher detection and decryption using frequency analysis and pattern recognition. Supports both Caesar ciphers and substitution ciphers in English and French.
- Automatic Cipher Detection: Determines if text is encrypted based on frequency patterns
- Caesar Cipher Breaking: Tests all 26 possible shifts with language scoring
- Advanced Substitution Cipher Analysis: Multiple intelligent methods including:
- Frequency analysis (English & French)
- Expert pattern recognition
- Word pattern analysis
- Iterative optimization
- 🤖 AI-Powered Refinement: Gemini AI post-processing to perfect decoded text
- Simple Frequency Viewer: Standalone tool for letter frequency analysis and visualization
- Language Pattern Comparison: Compare text patterns with English and French frequencies
- Bilingual Support: Handles both English and French texts
- Interactive CLI: Easy-to-use command-line interface
- Visualization: Optional frequency graphs using matplotlib
git clone https://github.com/Iskandeur/decipher.git
cd decipher
pip install -r requirements.txtFor advanced AI-powered cipher solving, the tool can integrate with Google Gemini AI:
# 1. Copy the example file and add your API key
cp .env.example .env
# Then edit .env with your actual API key
# 2. The tool will automatically load the API key from .env
# AI support is optional - the tool works fully without itNote: The .env file is automatically ignored by git for security. Get your API key from Google AI Studio.
# Analyze a cipher from command line
python cipher_analyzer.py "WKH TXLFN EURZQ IRA MXPSV RYHU WKH ODCB GRJ"
# Analyze a cipher from file
python cipher_analyzer.py -f encrypted_text.txt
# Run demo with sample Caesar cipher
python cipher_analyzer.py --demo
# Show frequency graph
python cipher_analyzer.py --demo -g
# Use the frequency viewer for detailed analysis
python frequency_viewer.py "sample text here"
python frequency_viewer.py -f sample_texts/english_sample.txt
# Enable AI assistance for complex ciphers
python cipher_analyzer.py "complex cipher text" --ai$ python cipher_analyzer.py "WKH TXLFN EURZQ IRA MXPSV RYHU WKH ODCB GRJ"
✅ BEST TRANSLATION (Caesar Cipher (English)):
THE QUICK BROWN FOX JUMPS OVER THE LAZY DOG
Caesar Shift: 3$ python cipher_analyzer.py "complex substitution cipher" --ai
🔬 Advanced substitution analysis...
🎯 Expert manual analysis...
Expert result preview: c etait oge qmorgee d avril frmide et claire...
🤖 Gemini AI refinement...
AI refinement preview: c etait une chargee d avril froide et claire...
Readability improvement: 6 → 8 readable words
✅ BEST TRANSLATION (Expert Manual Analysis + AI Refinement):
c etait une chargee d avril froide et claire les barrières s'engageaient$ python cipher_analyzer.py -f test_french_cipher.txt
✅ BEST TRANSLATION (Expert Manual Analysis):
c etait oge qmorgee d avril frmide et claire les bmrlmxes smggaiegt...
Confidence Score: 7682.1
Detected Language: French$ python frequency_viewer.py "The quick brown fox jumps over the lazy dog"
🔍 LUKIN E NIMI KON - Frequency Viewer
==================================================
Analyzing: The quick brown fox jumps over the lazy dog
📊 FREQUENCY ANALYSIS
============================================================
Total letters analyzed: 35
Letter | Count | Percentage | English Expected | French Expected
------------------------------------------------------------
o | 4 | 11.4% | 7.5% | 5.4%
u | 3 | 8.6% | 2.8% | 6.3%
r | 3 | 8.6% | 6.0% | 6.6%
h | 2 | 5.7% | 6.1% | 0.9%
e | 2 | 5.7% | 12.7% | 14.7%
🎯 LANGUAGE SIMILARITY SCORES
==============================
English similarity: -156.8
French similarity: -189.2
→ Text appears more similar to English patternsusage: cipher_analyzer.py [-h] [-f FILE] [-g] [-l {auto,english,french}] [--demo] [--freq-only] [--ai] [text]
positional arguments:
text Text to analyze (or use --file)
options:
-h, --help show this help message and exit
-f FILE, --file FILE Read text from file
-g, --graph Show frequency graph
-l {auto,english,french}, --language {auto,english,french}
Target language for analysis (default: auto-detect)
--demo Run with demo Caesar cipher
--freq-only Show only frequency analysis (no decryption)
--ai Enable Gemini AI refinement to perfect decoded text
usage: frequency_viewer.py [-h] [-f FILE] [--no-graph] [--no-table] [--version] [text]
positional arguments:
text Text to analyze (or use --file)
options:
-h, --help show this help message and exit
-f FILE, --file FILE
Read text from file
--no-graph Skip showing the comparison graph
--no-table Skip showing the frequency table
--version show program's version number and exit
The tool analyzes letter frequency patterns and word readability to determine if text appears encrypted.
- Tests all 26 possible shifts
- Scores results against English and French frequency patterns
- Returns the most linguistically coherent result
The tool employs multiple sophisticated methods:
- Frequency Analysis: Maps most frequent cipher letters to expected language frequencies
- Expert Pattern Recognition: Uses proven linguistic patterns (e.g., "ju" → "le" in French)
- Word Pattern Analysis: Identifies common word structures and endings
- Iterative Optimization: Refines mappings through systematic testing
- 🤖 AI Refinement: Gemini AI conservatively fixes obvious letter errors while preserving original structure and meaning
Automatically detects whether the source text is English or French based on:
- Letter frequency patterns
- Common word recognition
- Language-specific patterns
decipher/
├── cipher_analyzer.py # Main cipher analysis tool
├── frequency_viewer.py # Standalone frequency analysis tool
├── manual_decoder.py # Specialized decoder for complex ciphers
├── sample_texts/ # Sample text files for testing
│ ├── english_sample.txt # English text example
│ ├── french_sample.txt # French text example
│ └── cipher_sample.txt # Encrypted text example
├── requirements.txt # Python dependencies
└── README.md # This file
- Caesar Cipher: Simple shift cipher (ROT-N)
- Substitution Cipher: Each letter mapped to another letter
- English: Full frequency analysis and word pattern recognition
- French: Specialized patterns for French linguistic structures
The tool uses a multi-factor scoring system:
- Letter frequency similarity to expected language patterns
- Word recognition bonuses
- Language-specific pattern bonuses
- Linguistic coherence scoring
- Python 3.6+
- matplotlib (for frequency graphs)
- google-genai (for AI-powered text refinement, optional)
- python-dotenv (for environment variable management)
- Standard library: argparse, collections, string, sys
- English: ~95% accuracy for texts >20 characters
- French: ~90% accuracy for texts >20 characters
- Simple substitutions: ~80% for texts >100 characters
- Complex substitutions: ~60% with expert patterns
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
This project is licensed under the MIT License - see the LICENSE file for details.
- Educational: Learn about cryptography and frequency analysis
- Historical: Analyze historical encrypted documents
- Puzzles: Solve cryptographic puzzles and challenges
- Research: Study linguistic patterns in different languages
- Works best with longer texts (>50 characters)
- Modern encryption methods are not supported
- Performance depends on text quality and language consistency
- Some substitution ciphers may require manual refinement
- AI features require internet connection and valid API key
- Support for additional languages (German, Spanish, Italian)
- Polyalphabetic cipher support (Vigenère)
- Web interface
- Statistical analysis reports
- Machine learning improvements
Made with ❤️ for cryptography enthusiasts