qubee-nlp 0.1.1

Natural Language Processing tools for Afaan Oromoo (Oromo language) using Qubee script

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

[![PyPI version](https://img.shields.io/pypi/v/qubee-nlp.svg)](https://pypi.org/project/qubee-nlp/)
[![Python versions](https://img.shields.io/pypi/pyversions/qubee-nlp.svg)](https://pypi.org/project/qubee-nlp/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Documentation](https://img.shields.io/badge/docs-readthedocs-blue)](https://qubee-nlp.readthedocs.io)
[![Tests](https://github.com/afaanoromoo/qubee-nlp/actions/workflows/tests.yml/badge.svg)](https://github.com/afaanoromoo/qubee-nlp/actions/workflows/tests.yml)
[![Codecov](https://codecov.io/gh/afaanoromoo/qubee-nlp/branch/main/graph/badge.svg)](https://codecov.io/gh/afaanoromoo/qubee-nlp)
[![Downloads](https://static.pepy.tech/badge/qubee-nlp/month)](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

• API Reference
• Getting Started Guide
• Afaan Oromoo NLP Tutorial
• Examples

Examples

Check the examples directory for complete usage examples:

• Basic Usage
• Tokenization Examples
• Stemming Examples
• Advanced Features

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

1. Report bugs: File issues on GitHub Issues
2. Suggest features: Share ideas in Discussions
3. Submit pull requests: Fix bugs or add features
4. Improve documentation: Help make docs better
5. Share examples: Create tutorials or examples
6. Test the library: Try it out and give feedback

Development Workflow

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run tests and linting
5. 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 [e-mail].

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

---

Made with ❤️ for the Afaan Oromoo language community

```