### Install Pygarble from PyPI

Source: https://github.com/brightertiger/pygarble/blob/main/docs/installation.md

Install the core Pygarble library using pip.

```bash
pip install pygarble
```

--------------------------------

### Clone Repository, Install Dependencies, and Run Tests

Source: https://github.com/brightertiger/pygarble/blob/main/README.md

Instructions for setting up the development environment by cloning the repository, installing the package in editable mode with development dependencies, and running the test suite.

```bash
git clone https://github.com/brightertiger/pygarble.git
cd pygarble
pip install -e ".[dev]"
pytest tests/ -v
```

--------------------------------

### Install Dependencies

Source: https://github.com/brightertiger/pygarble/blob/main/docs/contributing.md

Install project dependencies, including development requirements and the project in editable mode.

```bash
pip install -r requirements.txt
pip install -r requirements-dev.txt
pip install -e .
```

--------------------------------

### Verify Pygarble Installation

Source: https://github.com/brightertiger/pygarble/blob/main/docs/installation.md

Verify the installation by importing EnsembleDetector and running predictions on sample strings.

```python
from pygarble import EnsembleDetector

detector = EnsembleDetector()
print(detector.predict("Hello world"))  # False
print(detector.predict("asdfghjkl"))    # True
```

--------------------------------

### Development Installation of Pygarble

Source: https://github.com/brightertiger/pygarble/blob/main/docs/installation.md

Install Pygarble in development mode from a git repository, including development dependencies.

```bash
git clone https://github.com/brightertiger/pygarble.git
cd pygarble
pip install -e ".[dev]"
```

--------------------------------

### EnsembleDetector Usage Examples

Source: https://github.com/brightertiger/pygarble/blob/main/docs/api.md

Shows different ways to initialize EnsembleDetector, including using default strategies, custom strategies, and specific voting modes like 'any' for high recall.

```python
# Default ensemble
detector = EnsembleDetector()

# Custom strategies
detector = EnsembleDetector(
    strategies=[Strategy.MARKOV_CHAIN, Strategy.KEYBOARD_PATTERN]
)

# High recall mode
detector = EnsembleDetector(voting="any")
```

--------------------------------

### Real-World Example: Encoding Corruption Detection

Source: https://github.com/brightertiger/pygarble/blob/main/examples/getting_started.ipynb

This example demonstrates detecting encoding corruption, specifically mojibake, using the MOJIBAKE strategy. It processes a list of strings, some of which are intentionally corrupted.

```python
# Scenario 2: Detecting encoding corruption in a data pipeline
print("=== Encoding Corruption Detection ===")

mojibake_detector = GarbleDetector(Strategy.MOJIBAKE)

records = [
    "Caf\u00c3\u00a9 au lait",         # Mojibake: UTF-8 bytes misread as Latin-1
    "Caf\u00e9 au lait",               # Correct: proper UTF-8
    "na\u00c3\u00afve",                # Mojibake
    "naive",                            # Correct
    "r\u00c3\u00a9sum\u00c3\u00a9",   # Mojibake
    "r\u00e9sum\u00e9",               # Correct
]

for text in records:
    is_corrupted = mojibake_detector.predict(text)
    status = "CORRUPTED" if is_corrupted else "OK"
    print(f"  [{status:>9s}] {text}")
```

--------------------------------

### Install Pygarble with Spellchecker Dependency

Source: https://github.com/brightertiger/pygarble/blob/main/docs/installation.md

Install Pygarble with the optional spellchecker dependency for ENGLISH_WORD_VALIDATION.

```bash
pip install pygarble[spellchecker]
```

--------------------------------

### Example Strategy Implementation

Source: https://github.com/brightertiger/pygarble/blob/main/docs/contributing.md

Implement a new detection strategy by inheriting from `BaseStrategy` and overriding prediction methods. Ensure the strategy is registered in the `Strategy` enum and the strategy map.

```python
from .base import BaseStrategy

class MyCustomStrategy(BaseStrategy):
    def _predict_impl(self, text: str) -> bool:
        # Implement your detection logic
        return False

    def _predict_proba_impl(self, text: str) -> float:
        # Return probability score (0.0 to 1.0)
        return 0.0
```

--------------------------------

### Using Individual Strategies

Source: https://github.com/brightertiger/pygarble/blob/main/README.md

Instantiate GarbleDetector with a specific Strategy for targeted detection. Examples include MARKOV_CHAIN for general use, BIGRAM_PROBABILITY for high precision, MOJIBAKE for encoding errors, and UNICODE_SCRIPT for homoglyph attacks.

```python
from pygarble import GarbleDetector, Strategy

# Markov chain - best overall performance
detector = GarbleDetector(Strategy.MARKOV_CHAIN)
detector.predict("the quick brown fox")  # False
detector.predict("xkqzjwpmv")            # True

# High precision - zero false positives
detector = GarbleDetector(Strategy.BIGRAM_PROBABILITY)
detector.predict("hello world")          # False
detector.predict("qxjjxz")               # True (impossible: qx, jj, xz)

# Encoding corruption detection
detector = GarbleDetector(Strategy.MOJIBAKE)
detector.predict("Café")                 # False - valid UTF-8
detector.predict("Café")                # True - mojibake

# Homoglyph attack detection
detector = GarbleDetector(Strategy.UNICODE_SCRIPT)
detector.predict("paypal")               # False - all Latin
detector.predict("pаypal")               # True - Cyrillic 'а'
```

--------------------------------

### GarbleDetector Usage Example

Source: https://github.com/brightertiger/pygarble/blob/main/docs/api.md

Demonstrates how to use GarbleDetector to predict if text is garbled or its probability. Handles single strings and lists of strings.

```python
detector = GarbleDetector(Strategy.MARKOV_CHAIN, threshold=0.5)

detector.predict("hello")           # False
detector.predict("xkqzj")           # True
detector.predict_proba("hello")     # 0.1
detector.predict(["a", "b", "c"])   # [False, False, False]
```

--------------------------------

### Assessing Text Quality with EnsembleDetector

Source: https://github.com/brightertiger/pygarble/blob/main/examples/getting_started.ipynb

This example shows how to use the EnsembleDetector to assess the quality of scraped or OCR'd text. It processes a list of sample texts and categorizes them as HIGH or LOW quality based on the detector's prediction and probability.

```python
# Scenario 4: Quality check on scraped/OCR'd text
print("=== Text Quality Assessment ===")

# Use ensemble for robust detection
ensemble = EnsembleDetector()

scraped_texts = [
    "The annual report shows strong growth in Q4.",
    "xhfk23 sld#@ fgn!! kd0x nvm@ plw$$",
    "Scientists discover new species in the Amazon rainforest.",
    "asd asd asd asd asd asd",
    "Revenue increased by 15% compared to last year.",
]

for text in scraped_texts:
    is_garbled = ensemble.predict(text)
    prob = ensemble.predict_proba(text)
    quality = "LOW" if is_garbled else "HIGH"
    display = text if len(text) <= 55 else text[:52] + '...'
    print(f"  [Quality: {quality:>4s}] (prob: {prob:.2f}) {display}")
```

--------------------------------

### Quick Start with EnsembleDetector

Source: https://github.com/brightertiger/pygarble/blob/main/README.md

Use the default EnsembleDetector for recommended accuracy. It predicts whether text is valid or gibberish and can provide probability scores. Supports batch processing of multiple texts.

```python
from pygarble import GarbleDetector, EnsembleDetector, Strategy

# Recommended: Use the default ensemble (99.5% precision)
detector = EnsembleDetector()
detector.predict("Hello world")      # False - valid text
detector.predict("asdfghjkl")        # True - keyboard mashing
detector.predict("qxzjkwp")          # True - impossible letter combinations

# Get probability scores (0.0 = valid, 1.0 = gibberish)
detector.predict_proba("Hello world")  # ~0.1
detector.predict_proba("xkqzjwp")      # ~0.9

# Batch processing
texts = ["Hello world", "asdfghjkl", "Normal sentence here"]
results = detector.predict(texts)      # [False, True, False]
```

--------------------------------

### Real-World Example: Form Input Validation

Source: https://github.com/brightertiger/pygarble/blob/main/examples/getting_started.ipynb

This snippet shows how to use Pygarble to filter potentially garbled user input in form submissions. It uses the Markov Chain strategy to identify and reject suspicious entries.

```python
# Scenario 1: Filtering user input / form submissions
print("=== Form Input Validation ===")

detector = GarbleDetector(Strategy.MARKOV_CHAIN)

form_submissions = [
    "John Smith",
    "I need help with my account",
    "asdfasdfasdf",
    "Please reset my password",
    "jkljkljkl qweqweqwe",
    "My order number is 12345",
]

for text in form_submissions:
    is_garbled = detector.predict(text)
    status = "REJECTED" if is_garbled else "OK"
    print(f"  [{status:>8s}] {text}")
```

--------------------------------

### Predicting Garbled Text with Detector

Source: https://github.com/brightertiger/pygarble/blob/main/examples/getting_started.ipynb

Use the `predict` and `predict_proba` methods to get binary predictions and probability scores for a list of texts. Ensure your input `texts` is a list.

```python
predictions = detector.predict(texts)
probabilities = detector.predict_proba(texts)

print(f"{ 'Text':<30s} {'Garbled?':>8s} {'Probability':>11s}")
print("-" * 55)
for text, pred, prob in zip(texts, predictions, probabilities):
    print(f"{text:<30s} {'Yes' if pred else 'No':>8s} {prob:>10.4f}")
```

--------------------------------

### Get Probability Scores for Garbled Text

Source: https://github.com/brightertiger/pygarble/blob/main/examples/getting_started.ipynb

Initializes a GarbleDetector with a specific strategy and then iterates through a list of texts to predict the probability of each text being garbled. This is useful for nuanced detection beyond a simple binary classification.

```python
detector = GarbleDetector(Strategy.MARKOV_CHAIN)

texts = [
    "The quick brown fox jumps over the lazy dog",
    "Natural language processing is fascinating",
    "supercalifragilisticexpialidocious",  # unusual but pronounceable
    "qwertyuiop",                          # keyboard mashing
    "xzqkjhfbvn",                          # random characters
]

print(f"{ 'Text':<50s} {'Probability':>11s}  {'Garbled?':>8s}")
print("-" * 75)
for text in texts:
    proba = detector.predict_proba(text)
    label = detector.predict(text)
    display = text if len(text) <= 48 else text[:45] + '...'
    print(f"{display:<50s} {proba:>10.4f}   {'Yes' if label else 'No':>7s}")
```

--------------------------------

### Set Up Virtual Environment

Source: https://github.com/brightertiger/pygarble/blob/main/docs/contributing.md

Create and activate a virtual environment for project dependencies. Use `venv\Scripts\activate` on Windows.

```bash
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
```

--------------------------------

### Run Linting and Formatting

Source: https://github.com/brightertiger/pygarble/blob/main/docs/contributing.md

Apply code style checks and formatting using flake8, black, and mypy.

```bash
flake8 pygarble/
black pygarble/
mypy pygarble/
```

--------------------------------

### EnsembleDetector Class Initialization and Methods

Source: https://github.com/brightertiger/pygarble/blob/main/README.md

Demonstrates initializing the `EnsembleDetector` with a list of strategies and various voting mechanisms. The methods for prediction are the same as `GarbleDetector`.

```python
EnsembleDetector(
    strategies: List[Strategy] = None,  # Default: high-precision mix
    threshold: float = 0.5,
    voting: str = "majority",           # "majority", "any", "all", "average", "weighted"
    weights: List[float] = None,        # Required if voting="weighted"
)

# Methods (same as GarbleDetector)
detector.predict(text)
detector.predict_proba(text)
```

--------------------------------

### List All Available Strategies

Source: https://github.com/brightertiger/pygarble/blob/main/examples/getting_started.ipynb

Iterates through a dictionary of strategies categorized by type and prints each strategy's name and value. This helps in understanding the different detection methods available.

```python
strategies_by_category = {
    "Character-level statistics": [
        Strategy.ENTROPY_BASED,
        Strategy.LETTER_FREQUENCY,
        Strategy.CHARACTER_FREQUENCY,
        Strategy.COMPRESSION_RATIO,
    ],
    "N-gram / sequence analysis": [
        Strategy.MARKOV_CHAIN,
        Strategy.BIGRAM_PROBABILITY,
        Strategy.NGRAM_FREQUENCY,
        Strategy.RARE_TRIGRAM,
    ],
    "Phonotactic / pronunciation": [
        Strategy.PRONOUNCEABILITY,
        Strategy.CONSONANT_SEQUENCE,
        Strategy.VOWEL_RATIO,
        Strategy.VOWEL_PATTERN,
    ],
    "Word-level analysis": [
        Strategy.WORD_LOOKUP,
        Strategy.WORD_LENGTH,
        Strategy.FUNCTION_WORD_DENSITY,
        Strategy.AFFIX_DETECTION,
        Strategy.ZIPF_CONFORMITY,
        Strategy.WORD_COLLOCATION,
    ],
    "Pattern detection": [
        Strategy.KEYBOARD_PATTERN,
        Strategy.LETTER_POSITION,
        Strategy.REPETITION,
        Strategy.PATTERN_MATCHING,
    ],
    "Encoding / Unicode": [
        Strategy.MOJIBAKE,
        Strategy.UNICODE_SCRIPT,
        Strategy.HEX_STRING,
    ],
    "Other": [
        Strategy.SYMBOL_RATIO,
        Strategy.STATISTICAL_ANALYSIS,
    ],
}

for category, strats in strategies_by_category.items():
    print(f"\n{category}:")
    for s in strats:
        print(f"  Strategy.{s.name:<25s} ({s.value})")
```

--------------------------------

### Clone Repository

Source: https://github.com/brightertiger/pygarble/blob/main/docs/contributing.md

Clone the pygarble repository locally to begin development.

```bash
git clone https://github.com/brightertiger/pygarble.git
cd pygarble
```

--------------------------------

### GarbleDetector Class Initialization and Methods

Source: https://github.com/brightertiger/pygarble/blob/main/README.md

Shows how to initialize the `GarbleDetector` with a specific strategy and probability threshold. It also lists the available methods for prediction.

```python
GarbleDetector(
    strategy: Strategy,
    threshold: float = 0.5,    # Probability threshold for predict() 
    **kwargs                   # Strategy-specific parameters
)

# Methods
detector.predict(text)         # Returns bool or List[bool]
detector.predict_proba(text)   # Returns float or List[float] (0.0-1.0)
```

--------------------------------

### Configuring EnsembleDetector

Source: https://github.com/brightertiger/pygarble/blob/main/README.md

Create an EnsembleDetector with default settings or customize the strategies and voting mechanism. Different voting modes like 'any', 'all', 'majority', and 'average' offer trade-offs between recall and precision.

```python
from pygarble import EnsembleDetector, Strategy

# Default ensemble (recommended)
# Uses: MARKOV_CHAIN, WORD_LOOKUP, NGRAM_FREQUENCY, BIGRAM_PROBABILITY, LETTER_POSITION
# Voting: majority
detector = EnsembleDetector()

# Custom strategies
detector = EnsembleDetector(
    strategies=[
        Strategy.MARKOV_CHAIN,
        Strategy.BIGRAM_PROBABILITY,
        Strategy.KEYBOARD_PATTERN,
    ]
)

# Different voting modes
detector = EnsembleDetector(voting="any")       # High recall - flag if ANY strategy detects
detector = EnsembleDetector(voting="all")       # High precision - flag only if ALL agree
detector = EnsembleDetector(voting="majority")  # Balanced (default)
detector = EnsembleDetector(voting="average")   # Average probabilities
```

--------------------------------

### Using Individual Strategies

Source: https://github.com/brightertiger/pygarble/blob/main/docs/quickstart.md

Employ specific strategies like Markov Chain, Bigram Probability, Mojibake, or Unicode Script for tailored detection needs.

```python
from pygarble import GarbleDetector, Strategy

# Best overall performance
detector = GarbleDetector(Strategy.MARKOV_CHAIN)
detector.predict("hello world")   # False
detector.predict("xkqzjwpmv")     # True

# Zero false positives
detector = GarbleDetector(Strategy.BIGRAM_PROBABILITY)
detector.predict("hello world")   # False
detector.predict("qxjjxz")        # True

# Detect encoding corruption
detector = GarbleDetector(Strategy.MOJIBAKE)
detector.predict("Café")          # False - valid UTF-8
detector.predict("Café")         # True - mojibake

# Detect homoglyph attacks
detector = GarbleDetector(Strategy.UNICODE_SCRIPT)
detector.predict("paypal")        # False - all Latin
detector.predict("pаypal")        # True - Cyrillic 'а'
```

--------------------------------

### Push to Fork

Source: https://github.com/brightertiger/pygarble/blob/main/docs/contributing.md

Push your feature branch to your fork on GitHub.

```bash
git push origin feature/amazing-feature
```

--------------------------------

### EnsembleDetector Initialization

Source: https://github.com/brightertiger/pygarble/blob/main/docs/api.md

Initialize EnsembleDetector with a list of strategies, an optional threshold, and a voting mode. Weights can be provided for weighted voting.

```python
from pygarble import EnsembleDetector, Strategy

EnsembleDetector(
    strategies: List[Strategy] = None,
    threshold: float = 0.5,
    voting: str = "majority",
    weights: List[float] = None,
)
```

--------------------------------

### Creating a Custom Ensemble

Source: https://github.com/brightertiger/pygarble/blob/main/docs/quickstart.md

Build a custom EnsembleDetector by selecting specific strategies and configuring the voting mode.

```python
from pygarble import EnsembleDetector, Strategy

# Pick your strategies
detector = EnsembleDetector(
    strategies=[
        Strategy.MARKOV_CHAIN,
        Strategy.BIGRAM_PROBABILITY,
        Strategy.KEYBOARD_PATTERN,
    ]
)

# Change voting mode
detector = EnsembleDetector(voting="any")       # High recall
detector = EnsembleDetector(voting="all")       # High precision
detector = EnsembleDetector(voting="majority")  # Balanced (default)
```

--------------------------------

### Run CI Checks Locally

Source: https://github.com/brightertiger/pygarble/blob/main/docs/contributing.md

Execute all continuous integration checks locally before committing.

```bash
./scripts/test_ci.sh
```

--------------------------------

### Run Tests

Source: https://github.com/brightertiger/pygarble/blob/main/docs/contributing.md

Execute the test suite using pytest.

```bash
pytest tests/
```

--------------------------------

### Displaying Garble Detection Probabilities

Source: https://github.com/brightertiger/pygarble/blob/main/examples/getting_started.ipynb

This snippet demonstrates how to print a header and then iterate through test cases, displaying the garble probability for each text across different strategies. It's useful for comparing the performance of various detection methods.

```python
header = f"{ 'Text':<25s}"
for s in compare_strategies:
    header += f" {s.value[:12]:>12s}"
print(header)
print("-" * len(header))

for text, expected in test_cases.items():
    display = text if len(text) <= 23 else text[:20] + '...'
    row = f"{display:<25s}"
    for s in compare_strategies:
        det = GarbleDetector(s)
        prob = det.predict_proba(text)
        row += f" {prob:>11.3f} "
    print(row)
```

--------------------------------

### Create Feature Branch

Source: https://github.com/brightertiger/pygarble/blob/main/docs/contributing.md

Create a new branch for your feature development.

```bash
git checkout -b feature/amazing-feature
```

--------------------------------

### Initialize EnsembleDetector with Weighted Voting

Source: https://github.com/brightertiger/pygarble/blob/main/README.md

Instantiate an `EnsembleDetector` to use multiple strategies with custom weights for their predictions. This is useful when certain strategies should have more influence on the final decision.

```python
detector = EnsembleDetector(
    strategies=[Strategy.MARKOV_CHAIN, Strategy.WORD_LOOKUP],
    voting="weighted",
    weights=[0.7, 0.3]
)
```

--------------------------------

### Import PyGarble Libraries

Source: https://github.com/brightertiger/pygarble/blob/main/examples/getting_started.ipynb

Import necessary classes from the pygarble library. This is typically done at the beginning of your script.

```python
import sys
sys.path.insert(0, '..')

from pygarble import GarbleDetector, Strategy, EnsembleDetector
```

--------------------------------

### Basic Text Garbling Detection

Source: https://github.com/brightertiger/pygarble/blob/main/examples/getting_started.ipynb

Demonstrates how to initialize a GarbleDetector with the Markov Chain strategy and use its predict method to classify text as either normal or garbled. This is useful for quick checks of text validity.

```python
# Create a detector using the Markov chain strategy (best overall performer)
detector = GarbleDetector(Strategy.MARKOV_CHAIN)

# Test normal English text
print("Normal text:")
print(f"  'Hello world'           -> garbled: {detector.predict('Hello world')}")
print(f"  'The quick brown fox'   -> garbled: {detector.predict('The quick brown fox')}")
print(f"  'Python is awesome'     -> garbled: {detector.predict('Python is awesome')}")

print("\nGarbled text:")
print(f"  'asdfghjkl'             -> garbled: {detector.predict('asdfghjkl')}")
print(f"  'xkcd qwfp zxcv'        -> garbled: {detector.predict('xkcd qwfp zxcv')}")
print(f"  'bvnmxzqwp'             -> garbled: {detector.predict('bvnmxzqwp')}")
```

--------------------------------

### Run Pygarble Tests

Source: https://github.com/brightertiger/pygarble/blob/main/docs/installation.md

Execute the test suite for Pygarble using pytest.

```bash
pytest tests/ -v
```

--------------------------------

### Custom Strategy Selection with EnsembleDetector

Source: https://github.com/brightertiger/pygarble/blob/main/docs/examples.md

Configure the EnsembleDetector with specific strategies and voting mechanisms to tailor detection for high precision or high recall use cases.

```python
from pygarble import EnsembleDetector, Strategy

# High precision (minimize false positives)
detector = EnsembleDetector(
    strategies=[
        Strategy.BIGRAM_PROBABILITY,
        Strategy.LETTER_POSITION,
        Strategy.RARE_TRIGRAM,
    ],
    voting="all"  # Only flag if ALL agree
)

# High recall (catch everything)
detector = EnsembleDetector(
    strategies=[
        Strategy.MARKOV_CHAIN,
        Strategy.KEYBOARD_PATTERN,
        Strategy.WORD_LOOKUP,
    ],
    voting="any"  # Flag if ANY detects
)
```

--------------------------------

### Default Ensemble Detection

Source: https://github.com/brightertiger/pygarble/blob/main/examples/getting_started.ipynb

Initialize `EnsembleDetector` with default settings for robust detection using multiple strategies and majority voting. This is suitable for general-purpose garbling detection.

```python
# Default ensemble: uses 5 high-precision strategies with majority voting
ensemble = EnsembleDetector()

test_texts = [
    "The cat sat on the mat",
    "asdfghjkl qwerty",
    "Python is great",
    "xzqkj bvnmw",
    "I love programming",
    "qqq zzz xxx jjj",
]

print("Default Ensemble (majority voting):")
print(f"{ 'Text':<30s} {'Garbled?':>8s} {'Probability':>11s}")
print("-" * 55)
for text in test_texts:
    pred = ensemble.predict(text)
    prob = ensemble.predict_proba(text)
    print(f"{text:<30s} {'Yes' if pred else 'No':>8s} {prob:>10.4f}")
```

--------------------------------

### Commit Changes

Source: https://github.com/brightertiger/pygarble/blob/main/docs/contributing.md

Commit your changes with a descriptive message.

```bash
git commit -m "Add amazing feature"
```

--------------------------------

### GarbleDetector Initialization

Source: https://github.com/brightertiger/pygarble/blob/main/docs/api.md

Initialize GarbleDetector with a specific strategy and optional threshold. Strategy-specific parameters can be passed via kwargs.

```python
from pygarble import GarbleDetector, Strategy

GarbleDetector(
    strategy: Strategy,
    threshold: float = 0.5,
    **kwargs
)
```

--------------------------------

### Customizing Garble Detection Thresholds

Source: https://github.com/brightertiger/pygarble/blob/main/examples/getting_started.ipynb

Adjust the detection threshold for a specific strategy. This allows for tuning sensitivity to reduce false positives or catch more subtle garble. Strategy-specific parameters can also be passed.

```python
# Default threshold is 0.5
detector_default = GarbleDetector(Strategy.MARKOV_CHAIN)

# Stricter threshold (fewer false positives, may miss some garble)
detector_strict = GarbleDetector(Strategy.MARKOV_CHAIN, threshold=0.8)

# More lenient threshold (catches more garble, but more false positives)
detector_lenient = GarbleDetector(Strategy.MARKOV_CHAIN, threshold=0.3)

text = "qwerty"  # borderline case
proba = detector_default.predict_proba(text)
print(f"Text: '{text}'")
print(f"Probability: {proba:.4f}")
print(f"Default (0.5):  garbled={detector_default.predict(text)}")
print(f"Strict  (0.8):  garbled={detector_strict.predict(text)}")
print(f"Lenient (0.3):  garbled={detector_lenient.predict(text)}")
```

```python
# Strategy-specific parameters are passed as keyword arguments.
# For example, the word_lookup strategy accepts an unknown_threshold:
detector = GarbleDetector(
    Strategy.WORD_LOOKUP,
    unknown_threshold=0.7,  # require 70% unknown words to flag
)

print(f"'hello world':    garbled={detector.predict('hello world')}")
print(f"'xkrf plmq bvzt': garbled={detector.predict('xkrf plmq bvzt')}")
```

--------------------------------

### Basic Usage and Batch Processing with EnsembleDetector

Source: https://github.com/brightertiger/pygarble/blob/main/docs/index.md

Instantiate the default EnsembleDetector and use its predict method for single texts or batch processing. The detector returns True for gibberish and False for valid text.

```python
from pygarble import EnsembleDetector

# Recommended: Use the default ensemble
detector = EnsembleDetector()

detector.predict("Hello world")    # False - valid text
detector.predict("asdfghjkl")      # True - keyboard mashing
detector.predict("qxzjkwp")        # True - impossible letters

# Batch processing
texts = ["Hello world", "asdfghjkl", "Normal text"]
results = detector.predict(texts)  # [False, True, False]
```

--------------------------------

### Batch Process Texts with EnsembleDetector

Source: https://github.com/brightertiger/pygarble/blob/main/docs/examples.md

Efficiently process large datasets by sending multiple texts at once to the EnsembleDetector. This is suitable for handling thousands of texts simultaneously.

```python
from pygarble import EnsembleDetector

detector = EnsembleDetector()

# Process 10,000 texts at once
texts = ["sample text"] * 10000
results = detector.predict(texts)

garbled_count = sum(results)
print(f"Found {garbled_count} gibberish texts")
```

--------------------------------

### Basic Usage with EnsembleDetector

Source: https://github.com/brightertiger/pygarble/blob/main/docs/quickstart.md

Use EnsembleDetector for default gibberish detection on single or multiple texts. It also provides probability scores.

```python
from pygarble import EnsembleDetector

detector = EnsembleDetector()

# Check single text
detector.predict("Hello world")    # False - valid text
detector.predict("asdfghjkl")      # True - gibberish

# Check multiple texts
texts = ["Hello world", "asdfghjkl", "Normal sentence"]
results = detector.predict(texts)  # [False, True, False]

# Get probability scores (0.0 = valid, 1.0 = gibberish)
detector.predict_proba("Hello world")  # ~0.1
detector.predict_proba("xkqzjwp")      # ~0.9
```

--------------------------------

### Threshold Tuning for Sensitivity

Source: https://github.com/brightertiger/pygarble/blob/main/docs/examples.md

Obtain probability scores from the GarbleDetector and adjust the detection threshold to fine-tune sensitivity, balancing false positives and false negatives.

```python
from pygarble import GarbleDetector, Strategy

# Get probability scores first
detector = GarbleDetector(Strategy.MARKOV_CHAIN)

test_texts = [
    ("Hello world", False),      # Clearly valid
    ("xkqzjwpmv", True),         # Clearly gibberish
    ("asdfgh", True),            # Borderline
]

print("Probability scores:")
for text, _ in test_texts:
    prob = detector.predict_proba(text)
    print(f"  {text:20} -> {prob:.3f}")

# Then choose appropriate threshold
# Lower = more sensitive (more false positives)
# Higher = less sensitive (more false negatives)
```

--------------------------------

### Strategy Enum

Source: https://github.com/brightertiger/pygarble/blob/main/docs/api.md

Available detection strategies for Pygarble, categorized by precision and type.

```APIDOC
## Strategy Enum

Available detection strategies:

**High Precision (v0.5.0)**

- `BIGRAM_PROBABILITY` - Impossible letter pairs
- `LETTER_POSITION` - Invalid letter positions
- `CONSONANT_SEQUENCE` - Too many consonants
- `VOWEL_PATTERN` - Invalid vowel sequences
- `LETTER_FREQUENCY` - Abnormal letter distribution
- `RARE_TRIGRAM` - Impossible trigrams

**Core Strategies**

- `MARKOV_CHAIN` - Character Markov chain (recommended)
- `NGRAM_FREQUENCY` - Trigram frequency
- `WORD_LOOKUP` - 50K English dictionary
- `PRONOUNCEABILITY` - Phonotactic rules
- `KEYBOARD_PATTERN` - Keyboard sequences
- `ENTROPY_BASED` - Shannon entropy
- `VOWEL_RATIO` - Vowel/consonant ratio

**Specialized**

- `MOJIBAKE` - Encoding corruption
- `UNICODE_SCRIPT` - Homoglyph attacks
- `HEX_STRING` - Hash strings
- `SYMBOL_RATIO` - Excessive symbols
- `REPETITION` - Pattern repetition
- `COMPRESSION_RATIO` - Compression analysis

**Legacy**

- `CHARACTER_FREQUENCY`
- `WORD_LENGTH`
- `PATTERN_MATCHING`
- `STATISTICAL_ANALYSIS`
- `ENGLISH_WORD_VALIDATION` (requires pyspellchecker)
```

--------------------------------

### Custom Ensemble Detection with Voting Modes

Source: https://github.com/brightertiger/pygarble/blob/main/examples/getting_started.ipynb

Configure `EnsembleDetector` with specific strategies and voting modes ('majority', 'any', 'all', 'average') to tailor detection behavior. Use 'any' for high recall, 'all' for high precision, and 'majority' or 'average' for balanced results.

```python
# Custom ensemble with different voting modes
strategies = [
    Strategy.MARKOV_CHAIN,
    Strategy.PRONOUNCEABILITY,
    Strategy.NGRAM_FREQUENCY,
]

text = "xkrf plmq bvzt nwsd"

# Majority voting: more than half must agree
ens_majority = EnsembleDetector(strategies=strategies, voting="majority")
print(f"Majority voting: {ens_majority.predict(text)}")

# Any voting: if ANY strategy flags it, return True (high recall)
ens_any = EnsembleDetector(strategies=strategies, voting="any")
print(f"Any voting:      {ens_any.predict(text)}")

# All voting: ALL strategies must agree (high precision)
ens_all = EnsembleDetector(strategies=strategies, voting="all")
print(f"All voting:      {ens_all.predict(text)}")

# Average voting: average probability across strategies
ens_avg = EnsembleDetector(strategies=strategies, voting="average")
print(f"Average voting:  {ens_avg.predict(text)} (proba: {ens_avg.predict_proba(text):.4f})")
```

--------------------------------

### Keyboard Pattern Detection

Source: https://github.com/brightertiger/pygarble/blob/main/docs/strategies.md

Flags text that follows common keyboard layout patterns, such as sequential keys on a QWERTY or ASDF row.

```python
detector = GarbleDetector(Strategy.KEYBOARD_PATTERN)
detector.predict("asdfghjkl")     # True
detector.predict("hello world")   # False
```

--------------------------------

### Batch Process Texts for Garbled Detection

Source: https://github.com/brightertiger/pygarble/blob/main/examples/getting_started.ipynb

Demonstrates efficient processing of multiple texts by passing them as a list to the GarbleDetector. This method is more performant than individual calls to predict().

```python
detector = GarbleDetector(Strategy.MARKOV_CHAIN)

# Batch of texts to check
texts = [
    "Hello, how are you?",
    "asdfghjkl",
    "The weather is nice today",
    "xkrf plmq bvzt",
    "Python programming",
    "qzxjkvbw",
]
```

--------------------------------

### Detect Encoding Issues with GarbleDetector

Source: https://github.com/brightertiger/pygarble/blob/main/README.md

Utilize a `GarbleDetector` with the `MOJIBAKE` strategy to identify potential encoding issues in a list of documents.

```python
detector = GarbleDetector(Strategy.MOJIBAKE)

for text in documents:
    if detector.predict(text):
        print(f"Encoding issue detected: {text[:50]}...")
```

--------------------------------

### Clean Dataset with GarbleDetector (Markov Chain)

Source: https://github.com/brightertiger/pygarble/blob/main/docs/examples.md

Remove gibberish from a list of texts using the GarbleDetector with the MARKOV_CHAIN strategy. This is useful for cleaning raw data.

```python
from pygarble import GarbleDetector, Strategy

detector = GarbleDetector(Strategy.MARKOV_CHAIN)

raw_data = [
    "This is valid text",
    "asdfghjkl",
    "Another good sentence",
    "qxzjkwpmv",
    "Final valid text"
]

clean_data = [t for t in raw_data if not detector.predict(t)]
print(clean_data)
# ['This is valid text', 'Another good sentence', 'Final valid text']
```

--------------------------------

### Detect Phishing/Homoglyphs with GarbleDetector (Unicode Script)

Source: https://github.com/brightertiger/pygarble/blob/main/docs/examples.md

Identify lookalike characters in domain names that could be used for phishing, using the GarbleDetector with the UNICODE_SCRIPT strategy. This helps in detecting potentially malicious domains.

```python
from pygarble import GarbleDetector, Strategy

detector = GarbleDetector(Strategy.UNICODE_SCRIPT)

domains = [
    "paypal.com",      # Legitimate
    "pаypal.com",      # Cyrillic 'а'
    "google.com",      # Legitimate
    "gооgle.com",      # Cyrillic 'о'
    "apple.com",       # Legitimate
    "аpple.com",       # Cyrillic 'а'
]

for domain in domains:
    if detector.predict(domain):
        print(f"Warning: Possible phishing - {domain}")
```

--------------------------------

### Filter User Input with EnsembleDetector

Source: https://github.com/brightertiger/pygarble/blob/main/docs/examples.md

Validate user input to ensure it is not empty and does not contain gibberish before processing. This uses the EnsembleDetector for robust prediction.

```python
from pygarble import EnsembleDetector

detector = EnsembleDetector()

def validate_input(text):
    if not text or len(text.strip()) == 0:
        return "Input cannot be empty"
    if detector.predict(text):
        return "Please enter valid text"
    return None

# Usage
error = validate_input("Hello world")    # None - valid
error = validate_input("asdfghjkl")      # "Please enter valid text"
```

--------------------------------

### EnsembleDetector

Source: https://github.com/brightertiger/pygarble/blob/main/docs/api.md

Combines multiple strategies with voting to detect garbled text. It allows for flexible configuration of strategies, thresholds, and voting mechanisms.

```APIDOC
## EnsembleDetector

### Description
Combines multiple strategies with voting.

### Constructor
```python
EnsembleDetector(strategies: List[Strategy] = None, threshold: float = 0.5, voting: str = "majority", weights: List[float] = None)
```

### Parameters
#### Constructor Parameters
- `strategies` (List[Strategy]) - Optional - List of strategies (default: high-precision mix).
- `threshold` (float) - Optional - Probability threshold for `predict()`.
- `voting` (str) - Optional - Voting mode - “majority”, “any”, “all”, “average”, “weighted”. Defaults to "majority".
- `weights` (List[float]) - Optional - Weights for weighted voting (required if voting=”weighted”).

### Default Strategies
- MARKOV_CHAIN
- WORD_LOOKUP
- NGRAM_FREQUENCY
- BIGRAM_PROBABILITY
- LETTER_POSITION

### Voting Modes
- `majority`: Flag if >50% of strategies agree (default)
- `any`: Flag if ANY strategy detects (high recall)
- `all`: Flag only if ALL strategies agree (high precision)
- `average`: Average probability across strategies
- `weighted`: Weighted average with custom weights

### Example
```python
# Default ensemble
detector = EnsembleDetector()

# Custom strategies
detector = EnsembleDetector(
    strategies=[Strategy.MARKOV_CHAIN, Strategy.KEYBOARD_PATTERN]
)

# High recall mode
detector = EnsembleDetector(voting="any")
```
```

--------------------------------

### Streaming/Real-time Detection with GarbleDetector

Source: https://github.com/brightertiger/pygarble/blob/main/docs/examples.md

Process text as it arrives in real-time using a fast strategy like BIGRAM_PROBABILITY with the GarbleDetector. This is ideal for applications with continuous data streams.

```python
from pygarble import GarbleDetector, Strategy

# Use a fast strategy
detector = GarbleDetector(Strategy.BIGRAM_PROBABILITY)

def process_message(message):
    if detector.predict(message):
        return {"status": "rejected", "reason": "invalid text"}
    return {"status": "accepted", "message": message}

# Process incoming messages
messages = ["Hello", "xqzjk", "World"]
for msg in messages:
    result = process_message(msg)
    print(f"{msg}: {result['status']}")
```

--------------------------------

### Detect Encoding Issues in Documents

Source: https://github.com/brightertiger/pygarble/blob/main/docs/quickstart.md

Utilize a Mojibake-specific GarbleDetector to iterate through documents and identify potential encoding problems.

```python
detector = GarbleDetector(Strategy.MOJIBAKE)
for text in documents:
    if detector.predict(text):
        print(f"Encoding issue: {text[:50]}")
```

--------------------------------

### Markov Chain Detection

Source: https://github.com/brightertiger/pygarble/blob/main/docs/strategies.md

Utilizes a character-level Markov chain trained on English text for overall performance in detecting garbled text.

```python
detector = GarbleDetector(Strategy.MARKOV_CHAIN)
detector.predict("hello world")   # False
detector.predict("xkqzjwpmv")     # True
```

--------------------------------

### Filter User Input with Pygarble

Source: https://github.com/brightertiger/pygarble/blob/main/docs/quickstart.md

Use an EnsembleDetector to validate user input, returning an error message if the input is detected as gibberish.

```python
detector = EnsembleDetector()

def validate_input(text):
    if detector.predict(text):
        return "Please enter valid text"
    return None
```

--------------------------------

### Detecting Homoglyph/Spoofing Attacks with Unicode Script

Source: https://github.com/brightertiger/pygarble/blob/main/examples/getting_started.ipynb

This snippet demonstrates how to use the UNICODE_SCRIPT strategy to detect potential spoofing attacks by identifying characters from different Unicode scripts within a string. It iterates through a list of URLs and names, printing their spoofing status and confidence probability.

```python
print("=== Homoglyph Detection ===")

script_detector = GarbleDetector(Strategy.UNICODE_SCRIPT)

urls_and_names = [
    "paypal",                   # Normal Latin
    "p\u0430ypal",             # Cyrillic 'a' (U+0430) mixed with Latin
    "google",                   # Normal Latin
    "g\u043eogle",             # Cyrillic 'o' (U+043E) mixed with Latin
    "apple",                    # Normal Latin
    "\u0430pple",              # Cyrillic 'a' at start
]

for text in urls_and_names:
    is_spoofed = script_detector.predict(text)
    prob = script_detector.predict_proba(text)
    status = "SPOOFED" if is_spoofed else "OK"
    # Show the actual Unicode codepoints
    codepoints = ' '.join(f'U+{ord(c):04X}' for c in text)
    print(f"  [{status:>7s}] '{text}' (prob: {prob:.2f})")
    print(f"           codepoints: {codepoints}")
```

--------------------------------

### Detect Too Many Consonants

Source: https://github.com/brightertiger/pygarble/blob/main/docs/strategies.md

Flags text that contains an excessive sequence of consonants, which is uncommon in standard English.

```python
# Detect too many consonants
detector = GarbleDetector(Strategy.CONSONANT_SEQUENCE)
detector.predict("bcdfghjk")      # True - too many consonants
```

--------------------------------

### Detect Encoding Issues (Mojibake) with GarbleDetector

Source: https://github.com/brightertiger/pygarble/blob/main/docs/examples.md

Identify mojibake, which are encoding corruption issues, in documents using the GarbleDetector with the MOJIBAKE strategy. This helps in finding texts with incorrect character encoding.

```python
from pygarble import GarbleDetector, Strategy

detector = GarbleDetector(Strategy.MOJIBAKE)

documents = [
    "Café au lait",           # Valid UTF-8
    "Café au lait",          # Mojibake
    "naïve résumé",           # Valid UTF-8
    "naïve résumé",       # Mojibake
]

for doc in documents:
    if detector.predict(doc):
        print(f"Encoding issue: {doc}")
```

--------------------------------

### Clean a Dataset with Pygarble

Source: https://github.com/brightertiger/pygarble/blob/main/docs/quickstart.md

Apply a GarbleDetector to filter out gibberish entries from a dataset, creating a cleaned list of valid texts.

```python
detector = GarbleDetector(Strategy.MARKOV_CHAIN)
clean_data = [t for t in raw_data if not detector.predict(t)]
```

--------------------------------

### Pronounceability Check

Source: https://github.com/brightertiger/pygarble/blob/main/docs/strategies.md

Assesses whether the text adheres to English phonotactic rules, checking for pronounceable letter combinations.

```python
detector = GarbleDetector(Strategy.PRONOUNCEABILITY)
detector.predict("strength")      # False - valid clusters
detector.predict("bvnk tspk")     # True - unpronounceable
```

--------------------------------

### Hex String Detection

Source: https://github.com/brightertiger/pygarble/blob/main/docs/strategies.md

Detects strings that appear to be hexadecimal, commonly found in hashes (MD5, SHA) or UUIDs.

```python
detector = GarbleDetector(Strategy.HEX_STRING)
detector.predict("5d41402abc4b2a76b9719d911017c592")  # True
```

--------------------------------

### GarbleDetector

Source: https://github.com/brightertiger/pygarble/blob/main/docs/api.md

The main class for single-strategy detection. It allows for the detection of garbled text using a specified strategy and probability threshold.

```APIDOC
## GarbleDetector

### Description
The main class for single-strategy detection.

### Constructor
```python
GarbleDetector(strategy: Strategy, threshold: float = 0.5, **kwargs)
```

### Parameters
#### Constructor Parameters
- `strategy` (Strategy) - Required - The detection strategy to use (see Strategy enum).
- `threshold` (float) - Optional - Probability threshold for `predict()` (0.0-1.0). Defaults to 0.5.
- `**kwargs` - Optional - Strategy-specific parameters.

### Methods
- `predict(text)` - Returns `bool` or `List[bool]`
- `predict_proba(text)` - Returns `float` or `List[float]` (0.0-1.0)

### Example
```python
detector = GarbleDetector(Strategy.MARKOV_CHAIN, threshold=0.5)

detector.predict("hello")           # False
detector.predict("xkqzj")           # True
detector.predict_proba("hello")     # 0.1
detector.predict(["a", "b", "c"])   # [False, False, False]
```
```

--------------------------------

### Word Lookup Dictionary Validation

Source: https://github.com/brightertiger/pygarble/blob/main/docs/strategies.md

Validates words in the input text against an embedded dictionary of 50,000 English words.

```python
detector = GarbleDetector(Strategy.WORD_LOOKUP)
detector.predict("hello world")   # False
detector.predict("xyzzy plugh")   # True
```

--------------------------------

### Repetition Pattern Detection

Source: https://github.com/brightertiger/pygarble/blob/main/docs/strategies.md

Detects text that consists of repeating characters or simple patterns, which can be a sign of obfuscation.

```python
detector = GarbleDetector(Strategy.REPETITION)
detector.predict("ababababab")    # True
```

--------------------------------

### Mojibake Detection

Source: https://github.com/brightertiger/pygarble/blob/main/docs/strategies.md

Detects instances where UTF-8 encoded text has been incorrectly decoded as Latin-1, often resulting in garbled characters.

```python
detector = GarbleDetector(Strategy.MOJIBAKE)
detector.predict("Café")          # False - valid UTF-8
detector.predict("Café")         # True - mojibake
```

--------------------------------

### Detect Impossible Letter Pairs

Source: https://github.com/brightertiger/pygarble/blob/main/docs/strategies.md

Uses bigram probability to detect sequences of letters that are highly unlikely to appear together in English.

```python
from pygarble import GarbleDetector, Strategy

# Detect impossible letter pairs (qx, jj, xz)
detector = GarbleDetector(Strategy.BIGRAM_PROBABILITY)
detector.predict("qxjjxz")        # True
```

--------------------------------

### Detect Invalid Vowel Patterns

Source: https://github.com/brightertiger/pygarble/blob/main/docs/strategies.md

Identifies unusual or invalid sequences of vowels, such as excessive repetition, which can indicate garbled text.

```python
# Detect invalid vowel patterns
detector = GarbleDetector(Strategy.VOWEL_PATTERN)
detector.predict("aaaaaaa")       # True - repeated vowels
```

--------------------------------

### Adjusting Detection Threshold

Source: https://github.com/brightertiger/pygarble/blob/main/docs/quickstart.md

Modify the detection threshold for GarbleDetector to control sensitivity. Note that predict_proba() is unaffected.

```python
# Lower threshold = more sensitive (more false positives)
detector = GarbleDetector(Strategy.MARKOV_CHAIN, threshold=0.3)

# Higher threshold = less sensitive (more false negatives)
detector = GarbleDetector(Strategy.MARKOV_CHAIN, threshold=0.7)

# predict_proba() is not affected by threshold
detector.predict_proba("text")  # Returns 0.0-1.0
```

--------------------------------

### N-gram Frequency Analysis

Source: https://github.com/brightertiger/pygarble/blob/main/docs/strategies.md

Analyzes the frequency of trigrams (sequences of three characters) to determine if they are common in English.

```python
detector = GarbleDetector(Strategy.NGRAM_FREQUENCY)
detector.predict("the quick")     # False - common trigrams
detector.predict("xzqkjh")        # True - no common trigrams
```

--------------------------------

### Detect Impossible Trigrams

Source: https://github.com/brightertiger/pygarble/blob/main/docs/strategies.md

Identifies sequences of three characters (trigrams) that are highly improbable in English text.

```python
# Detect impossible trigrams
detector = GarbleDetector(Strategy.RARE_TRIGRAM)
detector.predict("jjjqqq")        # True
```

--------------------------------

### Symbol Ratio Detection

Source: https://github.com/brightertiger/pygarble/blob/main/docs/strategies.md

Identifies text that contains an unusually high proportion of symbols or numbers relative to letters.

```python
detector = GarbleDetector(Strategy.SYMBOL_RATIO)
detector.predict("!!!@@@###")     # True
```

--------------------------------

### Unicode Script Homoglyph Detection

Source: https://github.com/brightertiger/pygarble/blob/main/docs/strategies.md

Identifies potential homoglyph attacks by detecting non-Latin characters (e.g., Cyrillic, Greek) that resemble Latin characters.

```python
detector = GarbleDetector(Strategy.UNICODE_SCRIPT)
detector.predict("paypal")        # False - all Latin
detector.predict("pаypal")        # True - Cyrillic 'а'
```

--------------------------------

### Detect Abnormal Letter Distribution

Source: https://github.com/brightertiger/pygarble/blob/main/docs/strategies.md

Checks for text where rare letters dominate the distribution, suggesting it might not be natural English.

```python
# Detect abnormal letter distribution
detector = GarbleDetector(Strategy.LETTER_FREQUENCY)
detector.predict("qqqxxxzzz")     # True - rare letters dominate
```