SATCN – Spelling and Text Correction Normalizer

Privacy-first, GPU-accelerated text correction pipeline for preprocessing long-form documents before TTS playback.

🚀 3.6x faster with GPU acceleration • 🎯 100% test accuracy • 🔒 Completely offline • 🎨 Modern GUI

SATCN Pipeline GUI - Configure filters, view real-time logs, process documents

SATCN LLM GUI - Model management, HuggingFace downloader, GPU-accelerated correction

SATCN is a privacy-first document correction tool that runs entirely on your machine:

graph LR
    A[📄 Input Document] --> B[🔍 Parse]
    B --> C[✅ Grammar Check]
    C --> D[📝 Spell Check]
    D --> E[🎙️ TTS Normalize]
    E --> F[✨ Clean Output]

Input → Parse → Grammar → Spelling → TTS Normalization → Output

Choose the engine that fits your needs:

Supported Formats: Markdown (.md), EPUB (.epub), Plain Text (.txt)

Before installing SATCN, ensure you have:

Check your Python version:

python --version  # Should show 3.11.x or 3.12.x

📖 Detailed installation instructions: INSTALLATION.md 🔧 Troubleshooting: TROUBLESHOOTING.md

# 1️⃣ Clone the repository
git clone https://github.com/hebbihebb/SATCN.git
cd SATCN

# 2️⃣ Install base package
pip install -e .

# 3️⃣ Choose your installation extras:

Installation Options:

# ⭐ Recommended: GRMR-V3 (best quality + GPU support)
pip install -e ".[grmr]"

# 🔬 Experimental: T5 transformer support
pip install -e ".[t5]"

# 🎨 GUI interface (CustomTkinter)
pip install -e ".[gui]"

# 🛠️ Development tools (pytest, ruff, black)
pip install -e ".[dev]"

# 🎁 Everything at once
pip install -e ".[all]"

# 📝 Process a document (default: rule-based correction)
satcn input.md

# ⭐ Use GRMR-V3 AI model (recommended)
satcn --use-grmr input.md

# 🔄 Hybrid mode (AI + spell-check + rules)
satcn --use-grmr --grmr-mode hybrid input.epub

# 📍 Specify custom model path
satcn --use-grmr --grmr-model-path /path/to/model.gguf input.md

# 🔬 Use T5 transformer model
satcn --use-t5 --grmr-mode replace input.md

# 🎯 Fail-fast mode (stop on first error)
satcn --use-grmr --fail-fast input.md

Output: Creates {input_name}_corrected.{ext} in the same directory

Model Path Resolution: GRMR-V3 models are automatically discovered from:

• Explicit path via --grmr-model-path
• Environment variable: SATCN_GRMR_MODEL_PATH
• Config file: ~/.satcn/llm_gui_config.json
• Virtual environment: .venv/.GRMR-V3-Q4B-GGUF/
• Current directory: .GRMR-V3-Q4B-GGUF/
• User config: ~/.satcn/models/

# 🎨 Launch main Pipeline GUI
satcn-gui
# Alternative: python -m satcn.gui.satcn_gui

# 🤖 Launch LLM Model GUI (for model management)
python launchers/launch_llm_gui.py

# 🪟 Windows users: Double-click launcher files
# - launchers/launch_satcn_gui.bat
# - launchers/launch_llm_gui.bat

SATCN provides two powerful GUI applications for different workflows:

The main GUI for document processing with full pipeline control.

satcn-gui
# or
python -m satcn.gui.satcn_gui

💾 Configuration: Auto-saved to ~/.config/satcn/gui_config.json

New addition focusing on LLM model management and HuggingFace integration.

python launchers/launch_llm_gui.py
# Windows: launchers/launch_llm_gui.bat

💾 Configuration: Auto-saved to ~/.config/satcn/llm_gui_config.json 📚 Documentation: See docs/LLM_GUI_README.md for detailed guide

Unlock 3.6x faster processing with NVIDIA CUDA support!

# 1️⃣ Run automated CUDA build (~38 minutes)
.\install_llama_cpp_cuda.ps1

# 2️⃣ Add CUDA to PATH
$env:PATH = "C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v13.0\bin\x64;$env:PATH"

# 3️⃣ Verify GPU detection
python scripts/check_cuda.py

# 4️⃣ Run with GPU acceleration
satcn --use-grmr input.md

📚 Detailed Guide: docs/GPU_SETUP_GUIDE.md 🔍 Troubleshooting: docs/GPU_ACCELERATION_STATUS.md

SATCN uses a modular pipeline architecture where each filter transforms a shared data structure:

# 🔧 Filter Protocol
class Filter:
    def process(self, data: dict) -> dict:
        """
        Transform text blocks while preserving metadata

        data = {
            'text_blocks': [
                {'content': str, 'metadata': dict},
                ...
            ],
            'tree': parsed_document_tree,
            'format': 'markdown' | 'epub',
            'filepath': str
        }
        """
        # Transform text_blocks, preserve metadata
        return modified_data

🎯 Design Principles:

• ✅ Metadata preservation - Round-trip document reconstruction
• ✅ Filter composability - Mix and match correction engines
• ✅ Error isolation - Fail-fast or continue-on-error modes
• ✅ Stateless processing - Each filter is independent

📈 Real-World Testing:

• ✅ Tested on 15,000+ word documents
• ✅ Maintains formatting and structure
• ✅ Preserves author voice and style
• ✅ Handles technical vocabulary correctly

1️⃣ Launch       2️⃣ Select File   3️⃣ Choose Engine   4️⃣ Run   5️⃣ Review
   GUI     →     Browse...    →    GRMR-V3      →   Process →  Output

satcn-gui
# or double-click: launchers/launch_satcn_gui.bat (Windows)

Your preferences are automatically saved and restored:

Comprehensive guides for setup, usage, and development:

SATCN has a comprehensive test suite with 100% pass rate:

# 🧪 Run all tests (unit + integration)
pytest

# 📦 Unit tests only
pytest tests/unit/

# 🔗 Integration tests
pytest tests/integration/

# 📈 Test coverage report
pytest --cov=src/satcn --cov-report=html

# ⭐ GRMR-V3 quality benchmark (51 tests, 100% expected)
python scripts/benchmark_grmr_quality.py

# 📊 GRMR-V3 vs T5 comparison
python scripts/benchmark_grmr_vs_t5.py

# 📄 Long document test (15K+ words, GPU recommended)
python scripts/test_long_document_gpu.py

# 🔬 Quantization comparison (Q4 vs Q8)
python scripts/compare_q4_vs_q8.py

# 🖥️ Check CUDA availability
python scripts/check_cuda.py

# ⚡ Quick GPU performance test
python scripts/quick_gpu_test.py

# 🔍 Detailed GPU diagnostics
python scripts/diagnose_gpu_performance.py

# ✅ Verify GPU acceleration
python scripts/verify_gpu_acceleration.py

tests/
├── unit/                    # Component-level tests
│   ├── test_markdown_parser.py
│   ├── test_grmr_v3_filter.py
│   ├── test_t5_corrector.py
│   └── ...
├── integration/             # End-to-end pipeline tests
│   └── test_pipeline.py
├── regression_corpus/       # Regression test data
│   ├── input*.md
│   └── golden*.md
└── samples/                 # Sample documents

Our core principles guide every decision:

We intentionally do not support:

• ❌ Real-time collaborative editing
• ❌ Cloud SaaS deployment
• ❌ Mobile apps
• ❌ Multi-user systems
• ❌ Online telemetry

Focus: Single-user, offline, batch document processing for TTS preparation.

We welcome contributions! Here's how to get involved:

# 1️⃣ Fork and clone
git clone https://github.com/YOUR_USERNAME/SATCN.git
cd SATCN

# 2️⃣ Install with dev dependencies
pip install -e ".[dev]"

# 3️⃣ Install pre-commit hooks
pre-commit install

# 4️⃣ Run tests
pytest

# 5️⃣ Make changes and test
# ... edit code ...
pytest
ruff check .
black --check .

• ✅ Code follows Black formatting
• ✅ Passes Ruff linting
• ✅ All tests pass (pytest)
• ✅ Quality benchmark still 100% (python scripts/benchmark_grmr_quality.py)
• ✅ Type hints where appropriate
• ✅ Docstrings for new functions
• ✅ Pre-commit hooks pass

MIT License - Free to use, modify, and distribute. See repository for full license details.

SATCN builds on excellent open-source projects and models:

Special thanks to the open-source community for making privacy-preserving AI accessible! 🎉