Installation Guide

This guide covers all installation methods for mySpellChecker, from basic pip installation to development setup with all optional features.

This guide covers all installation methods for mySpellChecker, from basic pip installation to development setup with all optional features.

Basic Installation

Using pip (Recommended)

pip install myspellchecker

This installs the core library with all essential features:

• Syllable validation
• Word validation with SymSpell
• Context checking with N-grams
• SQLite dictionary provider
• CLI tools

Verify Installation

import myspellchecker
print(myspellchecker.__version__)

# Or via CLI
myspellchecker --help

Dictionary Database

mySpellChecker requires a dictionary database for spell checking. No bundled database is included — you must build one first.

Providing a Database

Pass the database path explicitly:

• Use SQLiteProvider(database_path="/path/to/db.db")
• Or use CLI flag: myspellchecker check --db /path/to/db.db
• Or set in config file: database: /path/to/db.db
• Or set environment variable: MYSPELL_DATABASE_PATH (via ConfigLoader)

Building a Sample Database

# Build sample database for testing
myspellchecker build --sample

Building from Corpus

# Build from your own corpus
myspellchecker build --input corpus.txt --output dictionary.db

See Data Pipeline for detailed dictionary building instructions.

Installation Options

With AI/Semantic Features

For deep learning-based context checking:

pip install myspellchecker[ai]

This adds:

• ONNX Runtime for semantic model inference
• Tokenizers library for fast text tokenization
• Pre-trained semantic models support

With Transformer POS Tagger

For highest accuracy POS tagging (~93%):

pip install myspellchecker[transformers]

This adds:

• PyTorch
• Hugging Face Transformers
• Pre-trained Myanmar POS models support

Full Installation

Install complete AI features (Semantic + Transformer POS):

pip install myspellchecker[ai-full]

Combines: ai + transformers

Development Installation

For contributors and developers:

pip install myspellchecker[dev]

This adds:

• pytest and testing tools
• ruff for linting/formatting
• mypy for type checking
• Note: Cython is automatically installed as a build dependency, not part of the [dev] extra.

Platform-Specific Instructions

Linux (Ubuntu/Debian)

# Install Python and build tools
sudo apt update
sudo apt install python3-dev python3-pip build-essential

# Install mySpellChecker
pip install myspellchecker

Linux (RHEL/CentOS/Fedora)

# Install Python and build tools
sudo dnf install python3-devel python3-pip gcc gcc-c++

# Install mySpellChecker
pip install myspellchecker

macOS

# Using Homebrew
brew install python

# For OpenMP parallelization support (optional but recommended)
brew install libomp

# Install mySpellChecker
pip install myspellchecker

Note: Without libomp, Cython extensions will compile without parallel processing. The library will still work but batch processing will be single-threaded.

Windows

# Ensure Python is installed and in PATH
python --version

# Install Visual Studio Build Tools for Cython (if needed)
# Download from: https://visualstudio.microsoft.com/visual-cpp-build-tools/

# Install mySpellChecker
pip install myspellchecker

Virtual Environment Setup

We recommend using a virtual environment:

Using venv

# Create virtual environment
python -m venv myspell-env

# Activate (Linux/macOS)
source myspell-env/bin/activate

# Activate (Windows)
myspell-env\Scripts\activate

# Install
pip install myspellchecker

Using conda

# Create conda environment
conda create -n myspell python=3.11

# Activate
conda activate myspell

# Install
pip install myspellchecker

Using Poetry

# Add to project
poetry add myspellchecker

# With optional features
poetry add myspellchecker[ai,transformers]

Building from Source

For development or to get the latest features:

Clone and Install

# Clone repository
git clone https://github.com/thettwe/my-spellchecker.git
cd my-spellchecker

# Create virtual environment
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# Install in development mode
pip install -e ".[dev]"

# Build Cython extensions
python setup.py build_ext --inplace

Development Dependencies

The development installation includes:

Tool	Purpose
pytest	Testing framework
pytest-cov	Coverage reporting
pytest-benchmark	Performance benchmarks
ruff	Linting and formatting
mypy	Static type checking

Note: Cython is automatically installed as a build-system dependency (specified in pyproject.toml build requirements), not as part of the [dev] extra.

Running Tests

# Run all tests
pytest tests/

# Run with coverage
pytest tests/ --cov=myspellchecker --cov-report=html

# Run specific test category
pytest tests/ -m unit
pytest tests/ -m integration

Cython Extension Compilation

Cython extensions provide significant performance improvements. They’re automatically compiled during installation, but if you modify .pyx files:

# Rebuild extensions
python setup.py build_ext --inplace

Troubleshooting Cython Build

Missing C++ Compiler:

# Linux
sudo apt install build-essential

# macOS
xcode-select --install

# Windows
# Install Visual Studio Build Tools

OpenMP Not Found (macOS):

brew install libomp

If OpenMP installation fails, the library will compile with single-threaded extensions (graceful degradation).

Verifying Installation

Run this script to verify all components are installed correctly:

from myspellchecker import SpellChecker
from myspellchecker.providers import SQLiteProvider

# Check core installation
print("Core library: OK")

# Check provider
try:
    provider = SQLiteProvider()  # Will warn if no database path is configured
    print("SQLite Provider: OK")
except Exception as e:
    print(f"SQLite Provider: WARNING - {e}")

# Check Cython extensions
try:
    from myspellchecker.text.normalize_c import remove_zero_width_chars
    print("Cython extensions: OK")
except ImportError:
    print("Cython extensions: NOT AVAILABLE (install from wheel or compile)")

# Check AI features
try:
    import onnxruntime
    print("AI features (ONNX): OK")
except ImportError:
    print("AI features (ONNX): NOT INSTALLED")

# Check transformer features
try:
    import transformers
    print("Transformer POS: OK")
except ImportError:
    print("Transformer POS: NOT INSTALLED")

# Check DuckDB (core dependency for build pipeline)
try:
    import duckdb
    print(f"DuckDB: OK (version {duckdb.__version__})")
except ImportError:
    print("DuckDB: MISSING (required core dependency - reinstall myspellchecker)")

Common Issues

Issue: “No module named ‘myspellchecker’”

Solution: Ensure you’re in the correct virtual environment:

which python  # Should show your venv path
pip show myspellchecker  # Should show installation info

Issue: “Database not found”

Solution: Build or download a dictionary database:

myspellchecker build --sample

Issue: “Cython extension failed to compile”

Solution: Install a C++ compiler:

# Linux
sudo apt install build-essential

# macOS
xcode-select --install

Cython extensions provide performance improvements but are not strictly required. The library falls back to pure Python implementations if Cython is unavailable.

Issue: “OpenMP not found” (macOS)

Solution: Install libomp:

brew install libomp

This is optional - the library works without OpenMP but uses single-threaded processing.

Docker Installation

For containerized deployments, mySpellChecker provides Docker support with multi-stage builds.

Quick Start with Docker Compose

# Clone the repository
git clone https://github.com/thettwe/my-spellchecker.git
cd my-spellchecker

# Start the API server
docker compose up api

# The API is now available at http://localhost:8000

Available Docker Services

Service	Command	Description
api	docker compose up api	Production API server
dev	docker compose --profile dev up dev	Development with hot reload
cli	docker compose --profile cli run --rm cli check "မြန်မာစာ"	CLI tool
test	docker compose --profile test run --rm test	Run tests
api-gpu	docker compose --profile gpu up api-gpu	GPU-enabled API

Building Docker Images

# Build production image
docker build --target runtime -t myspellchecker:latest .

# Build CLI-only image
docker build --target cli -t myspellchecker:cli .

For detailed Docker configuration, see the Docker Guide.

Next Steps

• Dictionary Building - Build a dictionary database (required before spell checking)
• Quick Start - Learn the basics in 5 minutes
• Configuration - Customize behavior