Skip to main content

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

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

  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

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

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

Star History Chart


Made with ❤️ for the Afaan Oromoo language community
```

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)

Source distribution for qubee-nlp 0.2.2
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)

Table of built distributions (wheels) for qubee-nlp 0.2.2
File Interpreter ABI Platform Actions
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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page