🧩 XPHRASE GENERATION

Expressive phrase generator — strong, modern, and minimalist.
Built entirely in Python for CLI environments on Linux and Windows.

---

📑 Table of Contents

• 🧠 Project Overview
• 📜 Disclaimer
• 🌍 Interactive Web Version
• ✨ Features
• 📋 Requirements
• 💾 Installation
• 📟 Command Line Interface
• 🔐 Generation Rules
• 📚 Word Bank Specs
• 📊 XPhrase Calculation Methodology
• 📢 Reporting Issues
• 🐞 Reporting Bugs
• 🛡️ Security - Reporting a Vulnerability
• 🤝 Contributing
• 📝 Release Notes
• 📅 Changelog
• 💬 Contact
• 📄 License

---

🧠 Project Overview

XPhrase Generation is a multilingual phrase generator designed for command-line interface (CLI) usage.
It creates expressive, randomized phrases using words from Portuguese, English, and German, interlinked with special characters and digits. The principle of randomness enables the generation of over 12.6 trillion unique combinations by interconnecting words from three languages, along with the inclusion of special characters and numerical digits.

This project is:

• 💯 Written 100% in Python
• 🖥️ CLI-compatible for Linux and Windows
• 🌐 The CLI project has been fully converted to the web version of the HTML interface, maintaining the same phrase generation method, now accessible directly in your browser.

---

📜 Disclaimer

Do not attempt to memorize the passwords generated by this tool. Instead, use a reliable password manager, such as Bitwarden©, which I personally recommend. The only password you should memorize is the master password for your password manager's vault, created with a strong combination of uppercase and lowercase letters, numbers, and special characters. Enable two-factor authentication (2FA) whenever possible to enhance security. A great option for managing your 2FA is Ente Auth , a free, open-source, and cross-platform app that provides end-to-end encrypted backups. Ente Auth ensures your 2FA codes are secure and synced across devices, with externally audited encryption, offering robust protection for all your accounts that support 2FA.

---

🌍 Interactive Web Version

Experience the XPhrase Generation directly in your browser! The web version offers all the functionality of the Python script in an intuitive and responsive interface.

🚀 Access the Web Version

⚡ Interactive Demo

---

✨ Features

• Generates phrases with 3 to 21 words
• Words are randomly selected from Portuguese, English, and German word banks
• Each word is interlinked with:
  • At least one special character: !@#$%^&*()_+-=[]{}|;:,.<>?~\\
  • At least one digit: 0123456789
• The last character of the final word is always uppercase
• Example of output for generating a phrase with eight words plus numeric and special characters:
  Note,8oxidar+6truly=3Chaos\1ressaca[3kind;1achtzehn_9descréditO

---

📋 Requirements

• Python 3.8+
• No external dependencies
• Works on:
  • ✅ Linux (Debian, Ubuntu, Arch, etc.)
  • ✅ Windows (PowerShell, CMD)

---

💾 Installation

1. No additional dependencies are required, as the project uses only Python standard libraries.
2. Ensure you have Python 3.8 or higher installed.
3. Clone the repository:

git clone https://github.com/gerivanc/xphrase.git
cd xphrase

---

📟 Command Line Interface

📦️ After installation, navigate to the directory where the XPhrase Generation repository folder was installed, then choose one of the following options to generate the phrases:

🧪 Mode 'PYTHONPATH='

5️⃣🔟 The parameter should be between 5 and 10 words long.

PYTHONPATH=src python src/xphrase/main.py --count 5

➖➕ Defines the minimum and maximum number of words to be generated in the sentence. --min and --max must be between 3-21 and min <= max.

PYTHONPATH=src python src/xphrase/main.py --min 5 --max 21

📋🔘 Interactive menu - generates unique and multiple phrases.

PYTHONPATH=src python src/xphrase/main.py --interactive

📦✨ Show which version of XPhrase Generation it is.

PYTHONPATH=src python src/xphrase/main.py --version

---

🧪 Mode 'echo PYTHONPATH='

5️⃣🔟 The parameter should be between 5 and 10 words long.

echo 'PYTHONPATH=src python src/xphrase/main.py "$@"' > xphrase.sh
chmod +x xphrase.sh
./xphrase.sh --count 10

➖➕ Defines the minimum and maximum number of words to be generated in the sentence. --min and --max must be between 3-21 and min <= max.

echo 'PYTHONPATH=src python src/xphrase/main.py "$@"' > xphrase.sh
chmod +x xphrase.sh
./xphrase.sh --min 5 --max 21

📋🔘 Interactive menu - generates unique and multiple phrases.

echo 'PYTHONPATH=src python src/xphrase/main.py "$@"' > xphrase.sh
chmod +x xphrase.sh
./xphrase.sh --interactive

📦✨ Show which version of XPhrase Generation it is.

echo 'PYTHONPATH=src python src/xphrase/main.py "$@"' > xphrase.sh
chmod +x xphrase.sh
./xphrase.sh --version

---

🧪 Mode './gerar'. Apply the script below before activating the './generate' mode to generate the phrases. Do this only on the first installation; after installation, navigate to the directory and generate the phrase using the function.:

cd xphrase
cat > gerar << 'EOF'
#!/usr/bin/env python3
import sys
sys.path.insert(0, 'src')
from xphrase.main import main
if __name__ == '__main__':
    main()
EOF

chmod +x gerar

📏✨ The parameter generates a single sentence with 8 words.

./gerar

5️⃣🔟 The parameter should be between 5 and 10 words long.

./gerar --count 7

➖➕ Defines the minimum and maximum number of words to be generated in the sentence. --min and --max must be between 3-21 and min <= max.

./gerar --min 5 --max 21

📋🔘 Interactive menu - generates unique and multiple phrases.

./gerar --interactive

📦✨ Show which version of XPhrase Generation it is.

./gerar --version

---

🧪 Mode './run.py'. Apply the script below before activating the './run.py' mode to generate the phrases. Do this only on the first installation; after installation, navigate to the directory and generate the phrase using the function.:

cd xphrase
cat > run.py << 'EOF'
#!/usr/bin/env python3
import sys
import os

sys.path.insert(0, os.path.join(os.path.dirname(__file__), 'src'))

from xphrase.main import main

if __name__ == '__main__':
    main()
EOF

chmod +x run.py

📏✨ The parameter generates a single sentence with 8 words.

./run.py

5️⃣🔟 The parameter should be between 5 and 10 words long.

./run.py --count 9

➖➕ Defines the minimum and maximum number of words to be generated in the sentence. --min and --max must be between 3-21 and min <= max.

./run.py --min 5 --max 21

📋🔘 Interactive menu - generates unique and multiple phrases.

./run.py --interactive

📦✨ Show which version of XPhrase Generation it is.

./run.py --version

---

🔐 Generation Rules

• Phrase length: 3 to 21 words
• Each word must include:
  • 1+ special character
  • 1+ digit
• Final word must end with a capital letter
• Language order is randomized

---

📚 Word Bank Specs

• It contains 4,000 specific words, selected from the vocabulary of three different languages.
• This project was created by selecting words to generate sentences in three languages: English, Portuguese, and German.
• All words are stored in separate .txt files inside the data/ folder.
• Words are randomly selected and mixed across languages.

Language	Word Count
English	1,334
Portuguese	1,333
German	1,333

---

📊 XPhrase Calculation Methodology

Generation phrase by Phrase Formation Rules:

For a phrase with ( n ) words (( 3 \leq n \leq 21 )):

1. Word Selection

• Each word is selected randomly with replacement from the pool of 4,000
• Language origin is random per word (uniform distribution across 3 languages)
• Order matters, repetitions allowed

2. Per-Word Modification

For each selected word:

• Insert at least one digit (0–9) → 10 options
• Insert at least one special character from:

  !@#$%^&*()_+-=[]{}|;:,.<>?~\\
  

  → 29 special characters
• Insertions occur between letters, before, or after the word
• Multiple insertions allowed (no upper limit per word)
• No fixed pattern — randomness ensures entropy

3. Inter-Word Linking

• Words are concatenated directly with their modifications
• No fixed separator between augmented words
• Example: davor,9Möglichkeit]3ThermometeR

4. Final Word Capitalization

• The last character of the final word must be a letter and is forced uppercase
• If the last character after modification is not a letter, a valid letter is appended and uppercased

See the XPHRASECALCULATION.md for details.

---

📢 REPORTING ISSUES

Help us improve XPhrase Generation by reporting bugs or suggesting enhancements to project. To report a bug, suggest a feature, or ask a question:

1. Go to the Issues tab.

2. Click New issue.

3. View the available options and select to: Report Bug and/or Report Issue. For security vulnerabilities, please follow our Security Policy.

---

🐞 REPORTING BUGS

If you encounter a bug in the XPhrase Generation, please report it using our dedicated Bug Report template. This template ensures that your report includes essential details, such as steps to reproduce, environment information, and logs, enabling us to address issues efficiently. For other types of contributions or inquiries, refer to our CONTRIBUTING.md.

---

🛡️ Security - Reporting a Vulnerability

For security vulnerabilities, follow the process in SECURITY.md instead of opening a public issue. We recommend using a password manager and enabling 2FA for enhanced security.

---

🤝 CONTRIBUTING

Contributions are welcome! Please follow the guidelines in CONTRIBUTING.md.

---

📝 RELEASE NOTES

See the RELEASE.md for detailed release notes for each version.

---

📅 CHANGELOG

See the CHANGELOG.md for a detailed history of changes to this project.

---

💬 CONTACT

E-mail: ask@gerivan.me
Location: Brazil
Feel free to reach out for collaboration or feedback!

---

📜 LICENSE

This repository is licensed under the MIT License.

---

Copyright © 2025 Gerivan Costa dos Santos

XPhrase Generation — Expressive phrases. Strong logic. Minimalist design © 2025