You can copy and paste this version of the README.md file. This is the properly formatted version that includes all the original content with correct Markdown formatting:
# Qubee NLP
<div align="center">
[](https://pypi.org/project/qubee-nlp/)
[](https://pypi.org/project/qubee-nlp/)
[](https://opensource.org/licenses/MIT)
[](https://qubee-nlp.readthedocs.io)
[](https://github.com/afaanoromoo/qubee-nlp/actions/workflows/tests.yml)
[](https://codecov.io/gh/afaanoromoo/qubee-nlp)
[](https://pepy.tech/project/qubee-nlp)
**Natural Language Processing tools for Afaan Oromoo (Oromo language) using Qubee script**
[Installation](#installation) • [Quick Start](#quick-start) • [Documentation](https://qubee-nlp.readthedocs.io) • [Examples](examples/)
</div>
## Features
- **Text Validation**: Validate Qubee script text for Afaan Oromoo
- **Tokenization**: Word and sentence tokenization with context awareness
- **Normalization**: Text cleaning, diacritic handling, and standardization
- **Stemming**: Morphological analysis and stemming for Afaan Oromoo
- **POS Tagging**: Part-of-speech tagging framework
- **Syllabification**: Syllable segmentation based on Oromo phonotactics
- **Stopword Removal**: Language-specific stopword lists
- **Corpus Tools**: Corpus building, processing, and analysis
## Installation
### From PyPI (Recommended)
```bash
pip install qubee-nlp
From Source
git clone https://github.com/GUUTA/qubee-nlp.git
cd qubee-nlp
pip install -e .
For Development
git clone https://github.com/GUUTA/qubee-nlp.git
cd qubee-nlp
pip install -e .[dev] # Includes testing and development tools
Quick Start
from qubee_nlp import word_tokenize, sentence_tokenize
# Tokenize text
text = "Afaan Oromoo afaan guddaa dha."
tokens = word_tokenize(text)
print(tokens) # ['AFAAN', 'OROMOO', 'AFAAN', 'GUDDAA', 'DHA']
# Tokenize sentences
sentences = sentence_tokenize("Kuni kitaaba dha. Inni bareessaa dha.")
print(sentences) # ['KUNI KITAABA DHA.', 'INNI BAREESSAA DHA.']
Text Validation
from qubee_nlp import validate_qubee_text
is_valid, invalid_chars = validate_qubee_text("Afaan Oromoo")
print(is_valid) # True
print(invalid_chars) # []
Text Normalization
from qubee_nlp import normalize_qubee
text = " Áfáan Oromoo "
normalized = normalize_qubee(text)
print(normalized) # "AFAAN OROMOO"
Advanced Tokenization
from qubee_nlp import QubeeTokenizer
tokenizer = QubeeTokenizer(preserve_case=True)
tokens = tokenizer.tokenize("Afaan Oromoo")
print(tokens) # ['Afaan', 'Oromoo']
Stemming
from qubee_nlp.stemmer import QubeeStemmer
stemmer = QubeeStemmer()
stem = stemmer.stem("barreessuu")
print(stem) # "bar"
Documentation
Complete documentation is available at https://qubee-nlp.readthedocs.io
Examples
Check the examples directory for complete usage examples:
Command Line Interface
Qubee NLP includes a command-line interface:
# Analyze text
qubee-nlp analyze "Afaan Oromoo afaan guddaa dha."
# Tokenize file
qubee-nlp tokenize input.txt output.txt
# Validate text
qubee-nlp validate "Áfáan Órómóó"
# Get help
qubee-nlp --help
Qubee Alphabet
Qubee is the Latin-based alphabet used for writing Afaan Oromoo. The library supports:
- Vowels (5): A, E, I, O, U (with optional diacritics: á, é, í, ó, ú)
- Consonants (21): B, C, D, F, G, H, J, K, L, M, N, P, Q, R, S, T, V, W, X, Y, Z
- Digraphs: CH, DH, NY, PH, SH
- Special Characters: Apostrophe (') and hyphen (-) for words like "waa'ee"
Language Support
This library is specifically designed for Afaan Oromoo (Oromo language), which:
- Is a Cushitic language spoken by over 40 million people
- Uses the Qubee (Latin) script for writing
- Has rich morphology with agglutinative structure
- Is the most widely spoken Cushitic language
Development
Setting Up Development Environment
# Clone repository
git clone https://github.com/GUUTA/qubee-nlp.git
cd qubee-nlp
# Create virtual environment
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
# Install development dependencies
pip install -e .[dev]
# Install pre-commit hooks
pre-commit install
Running Tests
# Run all tests
pytest
# Run with coverage
pytest --cov=qubee_nlp
# Run specific test file
pytest tests/test_alphabet.py -v
# Run with parallel execution
pytest -n auto
Code Quality
# Format code
black src/qubee_nlp tests examples
# Lint code
flake8 src/qubee_nlp tests examples
# Type checking
mypy src/qubee_nlp
# Security check
bandit -r src/qubee_nlp
Building Documentation
# Install documentation dependencies
pip install -e .[docs]
# Build documentation
cd docs
make html
# View documentation
open _build/html/index.html # macOS
start _build/html/index.html # Windows
xdg-open _build/html/index.html # Linux
Contributing
We welcome contributions! Please see our Contributing Guide for details.
Ways to Contribute
- Report bugs: File issues on GitHub Issues
- Suggest features: Share ideas in Discussions
- Submit pull requests: Fix bugs or add features
- Improve documentation: Help make docs better
- Share examples: Create tutorials or examples
- Test the library: Try it out and give feedback
Development Workflow
- Fork the repository
- Create a feature branch
- Make your changes
- Run tests and linting
- Submit a pull request
Support
Community Support
- GitHub Discussions: For questions and discussions
- GitHub Issues: For bug reports and feature requests
- Documentation: For detailed guides and API reference
Professional Support
For commercial support, consulting, or custom development, please contact guutatesema@gmail.com.
Citation
If you use Qubee NLP in your research, please cite:
@software{qubee_nlp,
title = {Qubee NLP: Natural Language Processing for Afaan Oromoo},
author = {Guta Tesema Tufa, Qubee NLP Team},
year = {2025},
url = {https://github.com/GUUTA/qubee-nlp},
version = {0.1.0}
}
Related Projects
- Oromo Text Corpus: Collection of Afaan Oromoo texts
- Oromo Language Tools: Additional language tools
- Qubee Fonts: Fonts for Qubee script
License
This project is licensed under the MIT License - see the LICENSE file for details.
Acknowledgments
- The Afaan Oromoo language community
- Contributors and maintainers
- Early adopters and testers
- Open source community
Star History
Advanced Toolkit & Agent Skill
qubee_nlp.advanced adds preprocessing pipelines, corpus statistics, dataset quality checks, evaluation helpers, ML feature export and reproducibility manifests. See docs/api/advanced.md.
The qubee-nlp-skill/ folder is an installable AI-agent skill (Claude Code, Cursor, Codex, ...).
Metadata
Release files for qubee-nlp 0.2.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| qubee_nlp-0.2.2.tar.gz | 94.7 kB | Without provenance | Details for qubee_nlp-0.2.2.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| qubee_nlp-0.2.2-py3-none-any.whl | Python 3 | none | any | Details for qubee_nlp-0.2.2-py3-none-any.whl |
Total release size: 145.1 kB
Release files / qubee_nlp-0.2.2.tar.gz
| Download URL | qubee_nlp-0.2.2.tar.gz |
|---|---|
| Size | 94.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
29e522069841494cdec9759dca785319c1b1abeccc387f5f9dad7e8789e179e9
|
|
BLAKE2b-256 checksum How to use checksums |
d44e8cb1a36b1ecc5598d0fa1b38a57963ae41ef7eeaf3a726852aa1f0c8da92
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.15.2
|
Release files / qubee_nlp-0.2.2-py3-none-any.whl
| Download URL | qubee_nlp-0.2.2-py3-none-any.whl |
|---|---|
| Size | 50.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
b5d3cc8137c0b57a27d611697c8c0c7fc93c8db1f24f0dc76e0063fc30287c59
|
|
BLAKE2b-256 checksum How to use checksums |
310b6c45f3bc4a78b36343b35d12e7850ed73ca7f5581e19508ad3c47c16610c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.15.2
|
Security for qubee-nlp 0.2.2
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.