> ## Documentation Index
> Fetch the complete documentation index at: https://docs.myspellchecker.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuration

> Configure SpellChecker behavior with SpellCheckerConfig, including presets, thresholds, and algorithm settings.

The `SpellChecker` behavior is controlled by the `SpellCheckerConfig` object. You can adjust performance thresholds, toggle features, and fine-tune algorithm sensitivity through nested configuration classes.

## Usage

The easiest way to configure the spell checker is using `ConfigPresets` with the `SpellCheckerBuilder`.

```python theme={null}
from myspellchecker.core.builder import SpellCheckerBuilder, ConfigPresets

# Use a preset
checker = (
    SpellCheckerBuilder()
    .with_config(ConfigPresets.ACCURATE)
    .build()
)

# Customize specific options on top of a preset
config = ConfigPresets.DEFAULT
config.max_suggestions = 10

checker = (
    SpellCheckerBuilder()
    .with_config(config)
    .with_phonetic(False)  # Override phonetic setting
    .build()
)
```

## Configuration Presets

| Preset                   | Description                                                                                                         |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------- |
| `ConfigPresets.DEFAULT`  | Balanced configuration suitable for most use cases.                                                                 |
| `ConfigPresets.FAST`     | Optimized for speed. Disables context checking and reduces search depth.                                            |
| `ConfigPresets.ACCURATE` | Optimized for quality. Max edit distance 3, strict thresholds.                                                      |
| `ConfigPresets.MINIMAL`  | Dictionary-only checking. Disables phonetic, context, NER, and rule-based validation. Lowest resource usage.        |
| `ConfigPresets.STRICT`   | Sensitive thresholds that catch more potential errors. May increase false positives. Suitable for formal documents. |

## Configuration Profiles

For environment-specific configurations, use `get_profile()` which returns fully-configured `SpellCheckerConfig` objects tuned for specific use cases.

```python theme={null}
from myspellchecker.core.config import get_profile

# Use a profile directly
config = get_profile("production")

# Available profiles
config = get_profile("development")  # Fast iteration, minimal validation
config = get_profile("production")   # Balanced accuracy and performance (default)
config = get_profile("testing")      # Deterministic, reproducible results
config = get_profile("fast")         # Maximum speed, reduced accuracy
config = get_profile("accurate")     # Maximum accuracy, slower performance
```

| Profile       | POS Tagger  | Context | NER | Semantic   | Zawgyi | Key Tuning                                            |
| ------------- | ----------- | ------- | --- | ---------- | ------ | ----------------------------------------------------- |
| `development` | rule\_based | Off     | Off | Off        | On     | Small caches, `prefix_length=5`                       |
| `production`  | viterbi     | On      | On  | Refinement | On     | Standard caches, `prefix_length=7`                    |
| `testing`     | rule\_based | On      | On  | Off        | On     | Small caches for determinism                          |
| `fast`        | rule\_based | Off     | Off | Off        | Off    | `max_edit_distance=1`, `count_threshold=200`          |
| `accurate`    | viterbi     | On      | On  | Proactive  | On     | `max_edit_distance=3`, `beam_width=100`, large caches |

<Note>
  `ConfigPresets` (from `SpellCheckerBuilder`) and `get_profile()` are **separate configuration systems**. Presets are simpler toggles; profiles provide fully-tuned configurations including SymSpell, N-gram, POS tagger, and provider settings.
</Note>

## Configuration Files

You can load configuration from a YAML file instead of code. This is useful for deploying the spell checker in different environments.

**Load Order:**

1. Explicit path loaded via `ConfigLoader().load(config_file="path/to/config.yml")`.
2. `myspellchecker.yaml`, `myspellchecker.yml`, or `myspellchecker.json` in the current directory.
3. `~/.config/myspellchecker/myspellchecker.yaml`, `myspellchecker.yml`, or `myspellchecker.json` (User global config).

**Example `myspellchecker.yaml`:**

```yaml theme={null}
preset: accurate
max_suggestions: 10
use_phonetic: true

symspell:
  prefix_length: 10
```

## Configuration Parameters

### General Settings

<ResponseField name="max_edit_distance" type="int" default="2">
  Maximum edit distance for suggestions (1-3). Higher values find more suggestions but are slower.
</ResponseField>

<ResponseField name="max_suggestions" type="int" default="5">
  Maximum number of correction suggestions to return per error.
</ResponseField>

<ResponseField name="max_text_length" type="int" default="100000">
  Maximum input text length in characters. Prevents resource exhaustion on very large inputs.
</ResponseField>

<ResponseField name="use_phonetic" type="bool" default="True">
  Enable phonetic matching (Myanmar Soundex-like) for finding sound-alike corrections.
</ResponseField>

<ResponseField name="use_context_checker" type="bool" default="True">
  Enable N-gram context validation for detecting real-word errors.
</ResponseField>

<ResponseField name="use_ner" type="bool" default="True">
  Enable Named Entity Recognition heuristics to skip proper names.
</ResponseField>

<ResponseField name="use_rule_based_validation" type="bool" default="True">
  Enable algorithmic syllable structure checks.
</ResponseField>

<ResponseField name="word_engine" type="str" default="myword">
  Word segmentation engine: `"myword"`, `"crf"`, or `"transformer"`.
</ResponseField>

<ResponseField name="seg_model" type="str | None" default="None">
  Custom model name or path for transformer word segmentation. Only used when `word_engine="transformer"`. Defaults to `chuuhtetnaing/myanmar-text-segmentation-model`.
</ResponseField>

<ResponseField name="seg_device" type="int" default="-1">
  Device for transformer word segmentation inference. `-1` for CPU, `0+` for GPU index. Only used when `word_engine="transformer"`.
</ResponseField>

<ResponseField name="fallback_to_empty_provider" type="bool" default="False">
  Silently use empty provider if database not found (instead of raising error).
</ResponseField>

### Nested Configuration Objects

<ResponseField name="symspell" type="SymSpellConfig">
  SymSpell algorithm configuration (edit distance, prefix length, beam width).
</ResponseField>

<ResponseField name="ngram_context" type="NgramContextConfig">
  N-gram context checker configuration (thresholds, smoothing, scoring weights).
</ResponseField>

<ResponseField name="phonetic" type="PhoneticConfig">
  Phonetic matching configuration (code length, suggestion thresholds).
</ResponseField>

<ResponseField name="semantic" type="SemanticConfig">
  Semantic model configuration (model path, tokenizer, inference settings).
</ResponseField>

<ResponseField name="pos_tagger" type="POSTaggerConfig">
  POS tagger configuration (tagger type, model name, device).
</ResponseField>

<ResponseField name="joint" type="JointConfig">
  Joint segmentation-tagging configuration (beam width, emission weight).
</ResponseField>

<ResponseField name="validation" type="ValidationConfig">
  Validation behavior configuration (confidence thresholds, feature toggles).
</ResponseField>

<ResponseField name="provider_config" type="ProviderConfig">
  Provider caching and query configuration (cache size, timeout).
</ResponseField>

<ResponseField name="cache" type="AlgorithmCacheConfig">
  Unified cache size configuration for all algorithm lookup caches.
</ResponseField>

<ResponseField name="ranker" type="RankerConfig">
  Suggestion ranking weights and strategy selection.
</ResponseField>

<ResponseField name="frequency_guards" type="FrequencyGuardConfig">
  Centralized frequency thresholds that suppress false positives across validators (colloquial, homophone, N-gram, semantic).
</ResponseField>

<ResponseField name="compound_resolver" type="CompoundResolverConfig">
  Compound word synthesis and broken compound detection settings.
</ResponseField>

<ResponseField name="reduplication" type="ReduplicationConfig">
  Reduplication validation settings for AABB/ABAB patterns.
</ResponseField>

<ResponseField name="neural_reranker" type="NeuralRerankerConfig">
  Neural suggestion re-ranking model configuration (MLP with ONNX).
</ResponseField>

<ResponseField name="broken_compound_strategy" type="BrokenCompoundStrategyConfig">
  Broken compound detection strategy thresholds and confidence.
</ResponseField>

<ResponseField name="token_refinement" type="TokenRefinementConfig">
  Token boundary refinement scoring (exposes hidden errors in merged tokens).
</ResponseField>

<ResponseField name="ner" type="NERConfig" default="None">
  NER model configuration. When provided with `enabled=True`, uses specified NER model.
</ResponseField>

### SymSpell Settings

Controlled via the `symspell` attribute (`SymSpellConfig`).

<Expandable title="SymSpellConfig fields" defaultOpen>
  <ResponseField name="prefix_length" type="int" default="10">
    Prefix length for indexing. Lower = smaller index but slower lookups.
  </ResponseField>

  <ResponseField name="count_threshold" type="int" default="50">
    Minimum frequency for a word to be considered valid.
  </ResponseField>

  <ResponseField name="max_word_length" type="int" default="15">
    Max word length for compound segmentation.
  </ResponseField>

  <ResponseField name="compound_lookup_count" type="int" default="3">
    Suggestions per word in compound check.
  </ResponseField>

  <ResponseField name="beam_width" type="int" default="25">
    Beam width for compound segmentation dynamic programming.
  </ResponseField>

  <ResponseField name="damerau_cache_size" type="int" default="4096">
    LRU cache size for edit distance calculations.
  </ResponseField>

  <ResponseField name="phonetic_bonus_weight" type="float" default="0.4">
    Weight for phonetic similarity bonus in suggestion ranking.
  </ResponseField>

  <ResponseField name="skip_init" type="bool" default="False">
    Skip SymSpell initialization (for POS-only use cases).
  </ResponseField>

  <ResponseField name="known_word_frequency_threshold" type="int" default="100">
    Minimum frequency to consider a word "known" for SymSpell lookups.
  </ResponseField>

  <ResponseField name="use_weighted_distance" type="bool" default="True">
    Use Myanmar-weighted edit distance for better Myanmar-specific scoring.
  </ResponseField>

  <ResponseField name="use_syllable_distance" type="bool" default="True">
    Enable syllable-aware edit distance.
  </ResponseField>

  <ResponseField name="use_myanmar_variants" type="bool" default="True">
    Enable Myanmar variant candidate generation.
  </ResponseField>

  <ResponseField name="myanmar_variant_max_candidates" type="int" default="20">
    Maximum Myanmar variant candidates per lookup (1-100).
  </ResponseField>

  <ResponseField name="compound_max_suggestions" type="int" default="5">
    Maximum suggestions for compound queries.
  </ResponseField>

  <ResponseField name="frequency_denominator" type="float" default="10000.0">
    Denominator for frequency bonus calculation.
  </ResponseField>
</Expandable>

### Context & N-gram Settings

Controlled via the `ngram_context` attribute (`NgramContextConfig`).

<Expandable title="NgramContextConfig fields">
  <ResponseField name="bigram_threshold" type="float" default="0.0001">
    Probability below which a bigram is flagged as suspicious.
  </ResponseField>

  <ResponseField name="trigram_threshold" type="float" default="0.0001">
    Probability below which a trigram is flagged as suspicious.
  </ResponseField>

  <ResponseField name="fourgram_threshold" type="float" default="0.0001">
    Probability below which a 4-gram is flagged as suspicious.
  </ResponseField>

  <ResponseField name="fivegram_threshold" type="float" default="0.0001">
    Probability below which a 5-gram is flagged as suspicious.
  </ResponseField>

  <ResponseField name="right_context_threshold" type="float" default="0.001">
    Probability threshold for right context to rescue a word.
  </ResponseField>

  <ResponseField name="edit_distance_weight" type="float" default="0.6">
    Weight for edit distance in scoring context candidates.
  </ResponseField>

  <ResponseField name="probability_weight" type="float" default="0.4">
    Weight for probability in scoring context candidates.
  </ResponseField>

  <ResponseField name="edit_distance" type="int" default="2">
    Max edit distance for context-based corrections.
  </ResponseField>

  <ResponseField name="candidate_limit" type="int" default="50">
    Max candidates to evaluate in context search.
  </ResponseField>

  <ResponseField name="use_smoothing" type="bool" default="True">
    Enable probability smoothing for sparse N-gram data.
  </ResponseField>

  <ResponseField name="smoothing_strategy" type="str" default="stupid_backoff">
    Smoothing strategy: `"none"`, `"stupid_backoff"`, or `"add_k"`.
  </ResponseField>

  <ResponseField name="backoff_weight" type="float" default="0.4">
    Weight for Stupid Backoff smoothing.
  </ResponseField>

  <ResponseField name="add_k_smoothing" type="float" default="0.0">
    Add-k smoothing constant (used when `smoothing_strategy="add_k"`).
  </ResponseField>

  <ResponseField name="max_suggestions" type="int" default="5">
    Maximum context-aware suggestions.
  </ResponseField>

  <ResponseField name="pos_score_weight" type="float" default="0.2">
    Weight for POS influence in scoring.
  </ResponseField>

  <ResponseField name="unigram_denominator" type="float" default="500000000.0">
    Denominator for unigram probability estimation.
  </ResponseField>

  <ResponseField name="min_unigram_threshold" type="int" default="5">
    Minimum frequency for a word to be considered valid in unseen contexts.
  </ResponseField>
</Expandable>

### Phonetic Settings

Controlled via the `phonetic` attribute (`PhoneticConfig`).

<Expandable title="PhoneticConfig fields">
  <ResponseField name="max_code_length" type="int" default="10">
    Maximum length for phonetic codes.
  </ResponseField>

  <ResponseField name="suggestion_threshold_unseen" type="float" default="0.001">
    Threshold for unseen phonetic suggestions.
  </ResponseField>

  <ResponseField name="suggestion_threshold_improvement" type="float" default="0.01">
    Threshold for phonetic improvement.
  </ResponseField>

  <ResponseField name="suggestion_improvement_ratio" type="float" default="100.0">
    Improvement ratio for phonetic suggestions.
  </ResponseField>

  <ResponseField name="phonetic_bypass_threshold" type="float" default="0.85">
    Minimum similarity to bypass edit-distance cap.
  </ResponseField>

  <ResponseField name="phonetic_extra_distance" type="int" default="1">
    Extra edit distance allowed for high-similarity phonetic candidates.
  </ResponseField>
</Expandable>

### Semantic Model Settings

Controlled via the `semantic` attribute (`SemanticConfig`). Requires a [trained model](/guides/training).

<Expandable title="SemanticConfig fields">
  <ResponseField name="model_path" type="str | None" default="None">
    Path to your trained ONNX model file.
  </ResponseField>

  <ResponseField name="tokenizer_path" type="str | None" default="None">
    Path to tokenizer files or HuggingFace tokenizer directory.
  </ResponseField>

  <ResponseField name="num_threads" type="int" default="0">
    Number of threads for ONNX inference (CPU only). 0 = auto-detect (use all available cores, recommended).
  </ResponseField>

  <ResponseField name="predict_top_k" type="int" default="5">
    Top-K predictions for semantic suggestions.
  </ResponseField>

  <ResponseField name="check_top_k" type="int" default="10">
    Top-K tokens to check for semantic errors.
  </ResponseField>

  <ResponseField name="use_semantic_refinement" type="bool" default="True">
    Enable semantic refinement in error detection.
  </ResponseField>

  <ResponseField name="use_proactive_scanning" type="bool" default="False">
    Enable proactive AI-powered error scanning.
  </ResponseField>

  <ResponseField name="proactive_confidence_threshold" type="float" default="0.85">
    Confidence threshold for proactive error detection (0.0-1.0).
  </ResponseField>

  <ResponseField name="scoring_confidence_threshold" type="float" default="0.3">
    Confidence threshold for semantic scoring in suggestion ranking.
  </ResponseField>

  <ResponseField name="use_pytorch" type="bool" default="False">
    Force PyTorch backend instead of ONNX Runtime.
  </ResponseField>

  <ResponseField name="device" type="str" default="cpu">
    Device for model inference (`"cpu"` or `"cuda:0"`). PyTorch only.
  </ResponseField>

  <ResponseField name="validate_model_architecture" type="bool" default="True">
    Validate that loaded model has MLM architecture on load.
  </ResponseField>

  <ResponseField name="word_alignment_enabled" type="bool" default="True">
    Enable Myanmar word-aligned masking for BPE tokenizers.
  </ResponseField>

  <ResponseField name="logit_scale" type="float | None" default="None">
    Override for automatic logit scale detection. Set to a positive float to manually control logit normalization.
  </ResponseField>

  <ResponseField name="myanmar_text_ratio_threshold" type="float" default="0.5">
    Minimum ratio of Myanmar characters in text to enable semantic checking.
  </ResponseField>
</Expandable>

#### Proactive Semantic Scanning

When enabled, the spell checker will proactively scan sentences for semantic errors using a language model (XLM-RoBERTa, mDeBERTa, etc.). This can detect errors that traditional dictionary-based methods miss.

```python theme={null}
from myspellchecker.core.config import SpellCheckerConfig, SemanticConfig

config = SpellCheckerConfig(
    semantic=SemanticConfig(
        use_proactive_scanning=True,
        proactive_confidence_threshold=0.7,  # Higher = fewer false positives
    )
)
```

**Note**: Proactive scanning requires a trained model and may increase processing time.

### POS Tagger Settings

Controlled via the `pos_tagger` attribute (`POSTaggerConfig`).

<Expandable title="POSTaggerConfig fields">
  <ResponseField name="tagger_type" type="str" default="rule_based">
    Backend type: `"rule_based"`, `"transformer"`, `"viterbi"`, or `"custom"`.
  </ResponseField>

  <ResponseField name="model_name" type="str | None" default="None">
    HuggingFace model ID (for `transformer` type).
  </ResponseField>

  <ResponseField name="device" type="int" default="-1">
    Device ID: `-1` for CPU, `0+` for GPU index.
  </ResponseField>

  <ResponseField name="batch_size" type="int" default="32">
    Batch size for transformer inference.
  </ResponseField>

  <ResponseField name="use_morphology_fallback" type="bool" default="True">
    Use morphology analyzer for OOV words.
  </ResponseField>

  <ResponseField name="cache_size" type="int" default="10000">
    LRU cache size for rule-based tagger.
  </ResponseField>

  <ResponseField name="beam_width" type="int" default="10">
    Beam width for Viterbi decoding.
  </ResponseField>

  <ResponseField name="emission_weight" type="float" default="1.2">
    Emission probability weight for Viterbi.
  </ResponseField>

  <ResponseField name="min_prob" type="float" default="1e-10">
    Minimum probability threshold to prevent underflow.
  </ResponseField>

  <ResponseField name="hmm_params_path" type="str | None" default="None">
    Path to precomputed HMM parameters JSON for Viterbi tagger.
  </ResponseField>

  <ResponseField name="unknown_tag" type="str" default="UNK">
    Tag assigned to completely unknown words.
  </ResponseField>

  <ResponseField name="use_fp16" type="bool" default="True">
    Use float16 on GPU for transformer tagger (approximately 2x throughput).
  </ResponseField>

  <ResponseField name="use_torch_compile" type="bool" default="False">
    Use `torch.compile()` JIT optimization for transformer tagger.
  </ResponseField>
</Expandable>

### Validation & Error Detection Settings

Controlled via the `validation` attribute (`ValidationConfig`).

<Expandable title="ValidationConfig fields">
  <ResponseField name="syllable_error_confidence" type="float" default="1.0">
    Confidence score for syllable errors.
  </ResponseField>

  <ResponseField name="word_error_confidence" type="float" default="0.8">
    Confidence score for word errors.
  </ResponseField>

  <ResponseField name="use_zawgyi_detection" type="bool" default="True">
    Enable Zawgyi encoding detection.
  </ResponseField>

  <ResponseField name="use_zawgyi_conversion" type="bool" default="True">
    Enable automatic Zawgyi to Unicode conversion.
  </ResponseField>

  <ResponseField name="zawgyi_confidence_threshold" type="float" default="0.95">
    Confidence threshold for Zawgyi detection.
  </ResponseField>

  <ResponseField name="strict_validation" type="bool" default="True">
    Enable strict validation rules.
  </ResponseField>

  <ResponseField name="colloquial_strictness" type="str" default="lenient">
    Strictness for colloquial variants: `"strict"`, `"lenient"`, or `"off"`.
  </ResponseField>

  <ResponseField name="allow_extended_myanmar" type="bool" default="False">
    Allow Extended Myanmar characters for non-Burmese scripts (Shan, Mon, Karen).
  </ResponseField>

  <ResponseField name="raise_on_strategy_error" type="bool" default="False">
    Re-raise exceptions from validation strategies (useful for debugging).
  </ResponseField>

  <ResponseField name="homophone_confidence" type="float" default="0.8">
    Confidence for homophone validation strategy.
  </ResponseField>

  <ResponseField name="homophone_improvement_ratio" type="float" default="5.0">
    Minimum probability improvement ratio for homophones.
  </ResponseField>

  <ResponseField name="homophone_min_probability" type="float" default="0.001">
    Minimum N-gram probability threshold for homophone suggestions.
  </ResponseField>

  <ResponseField name="homophone_high_freq_threshold" type="int" default="1000">
    Word frequency above which stricter ratio applies.
  </ResponseField>

  <ResponseField name="homophone_high_freq_improvement_ratio" type="float" default="50.0">
    Improvement ratio required for high-frequency words.
  </ResponseField>

  <ResponseField name="semantic_min_word_length" type="int" default="2">
    Minimum word length for semantic validation.
  </ResponseField>

  <ResponseField name="use_homophone_detection" type="bool" default="True">
    Enable homophone detection in validation pipeline.
  </ResponseField>

  <ResponseField name="use_orthography_validation" type="bool" default="True">
    Enable orthography validation in validation pipeline.
  </ResponseField>

  <ResponseField name="use_confusable_semantic" type="bool" default="False">
    Enable MLM-enhanced confusable detection (requires semantic model).
  </ResponseField>

  <ResponseField name="use_reduplication_validation" type="bool" default="True">
    Enable reduplication pattern validation (AABB/ABAB).
  </ResponseField>

  <ResponseField name="use_compound_synthesis" type="bool" default="True">
    Enable compound word synthesis for OOV recovery.
  </ResponseField>

  <ResponseField name="use_broken_compound_detection" type="bool" default="True">
    Enable detection of incorrectly split compound words.
  </ResponseField>

  <ResponseField name="medial_confusion_confidence" type="float" default="0.85">
    Confidence for medial confusion (ျ vs ြ) errors.
  </ResponseField>

  <ResponseField name="orthography_confidence" type="float" default="0.9">
    Confidence for orthography validation errors.
  </ResponseField>

  <ResponseField name="tone_validation_confidence" type="float" default="0.5">
    Confidence for tone validation errors.
  </ResponseField>

  <ResponseField name="syntactic_validation_confidence" type="float" default="0.9">
    Confidence for syntactic validation errors.
  </ResponseField>

  <ResponseField name="pos_sequence_confidence" type="float" default="0.85">
    Confidence for POS sequence validation errors.
  </ResponseField>

  <ResponseField name="enable_strategy_timing" type="bool" default="False">
    Enable per-strategy timing instrumentation.
  </ResponseField>

  <ResponseField name="enable_strategy_debug" type="bool" default="False">
    Enable debug logging for individual validation strategies.
  </ResponseField>
</Expandable>

### Provider Settings

Controlled via the `provider_config` attribute (`ProviderConfig`).

| Parameter                 | Default  | Description                                                 |
| ------------------------- | -------- | ----------------------------------------------------------- |
| `cache_size`              | `1024`   | LRU cache size for database queries.                        |
| `pool_min_size`           | `1`      | Minimum connections in pool.                                |
| `pool_max_size`           | `5`      | Maximum connections in pool (smaller is better for SQLite). |
| `pool_timeout`            | `5.0`    | Connection checkout timeout in seconds.                     |
| `pool_max_connection_age` | `3600.0` | Max connection age before recreation (seconds).             |

#### Connection Pooling

Connection pooling manages SQLite database connections for better resource control and production safety. The library uses connection pooling by default to ensure robust production behavior.

**Benefits**:

* Resource control with hard connection limits
* Connection health monitoring and automatic recreation
* Observability through pool statistics
* Graceful degradation under load

**Pool size recommendations**:

* Keep `pool_max_size` small (2-5) to reduce lock contention
* Set `pool_min_size=1` for most cases
* Larger pools (>10) degrade performance due to lock contention

**Example configurations**:

```python theme={null}
from myspellchecker.core.config import SpellCheckerConfig, ProviderConfig

# Default configuration
config = SpellCheckerConfig(
    provider_config=ProviderConfig(
        pool_min_size=1,
        pool_max_size=5,
    )
)

# High-concurrency configuration
config = SpellCheckerConfig(
    provider_config=ProviderConfig(
        pool_min_size=2,
        pool_max_size=10,  # May impact performance
    )
)

# Custom timeout and connection age
config = SpellCheckerConfig(
    provider_config=ProviderConfig(
        pool_timeout=10.0,  # Wait up to 10s for connection
        pool_max_connection_age=7200.0,  # Recreate after 2 hours
    )
)
```

**Performance characteristics**:

* Pooling adds \~30-50% overhead compared to direct connections
* Overhead comes from queue operations, locking, and health checks
* Trade-off: Performance vs. resource control and production safety
* See `tests/test_connection_pool.py` for comprehensive test coverage

### Joint Segmentation-Tagging Settings

The `joint` parameter accepts a `JointConfig` object for unified word segmentation and POS tagging.

```python theme={null}
from myspellchecker.core.config import SpellCheckerConfig, JointConfig

config = SpellCheckerConfig(
    joint=JointConfig(
        enabled=True,
        beam_width=15,
    )
)
```

| Parameter                 | Default | Description                                     |
| ------------------------- | ------- | ----------------------------------------------- |
| `enabled`                 | `False` | Enable joint segmentation-tagging mode.         |
| `beam_width`              | `15`    | Number of hypotheses to keep per position.      |
| `max_word_length`         | `20`    | Maximum word length in characters.              |
| `emission_weight`         | `1.2`   | Weight for P(tag\|word) emission probabilities. |
| `word_score_weight`       | `1.0`   | Weight for word N-gram language model scores.   |
| `min_prob`                | `1e-10` | Minimum probability for smoothing.              |
| `use_morphology_fallback` | `True`  | Use morphology for OOV word tag guessing.       |

See [Segmentation - Joint Mode](/algorithms/segmentation#joint-segmentation-and-pos-tagging) for detailed usage.

### Frequency Guard Settings

Controlled via the `frequency_guards` attribute (`FrequencyGuardConfig`). Centralized thresholds that suppress false positives across validators.

| Parameter                          | Default  | Description                                                     |
| ---------------------------------- | -------- | --------------------------------------------------------------- |
| `colloquial_high_freq_suppression` | `100000` | Suppress colloquial info for words above this frequency.        |
| `homophone_high_freq`              | `1000`   | Apply stricter homophone ratio above this frequency.            |
| `homophone_high_freq_ratio`        | `50.0`   | Improvement ratio required for high-frequency homophone words.  |
| `ngram_high_freq_guard`            | `5000`   | Suppress N-gram false positives for words above this frequency. |
| `semantic_high_freq_protection`    | `50000`  | Apply high-frequency logit diff threshold above this frequency. |

### Compound Resolver Settings

Controlled via the `compound_resolver` attribute (`CompoundResolverConfig`). Handles compound word synthesis for OOV recovery.

| Parameter                | Default | Description                                        |
| ------------------------ | ------- | -------------------------------------------------- |
| `min_morpheme_frequency` | `10`    | Minimum frequency per morpheme.                    |
| `max_parts`              | `4`     | Maximum compound splits (2-8).                     |
| `cache_size`             | `1024`  | LRU cache entries.                                 |
| `base_confidence`        | `0.85`  | Base confidence score for compound matches.        |
| `high_freq_boost`        | `0.05`  | Confidence boost if min morpheme frequency >= 100. |
| `medium_freq_boost`      | `0.03`  | Confidence boost if min morpheme frequency >= 50.  |
| `extra_parts_penalty`    | `0.05`  | Confidence penalty per extra part beyond 2.        |

### Reduplication Settings

Controlled via the `reduplication` attribute (`ReduplicationConfig`). Validates Myanmar reduplication patterns (AABB, ABAB, rhyme).

| Parameter                  | Default | Description                                               |
| -------------------------- | ------- | --------------------------------------------------------- |
| `min_base_frequency`       | `5`     | Minimum base word frequency for validation.               |
| `cache_size`               | `1024`  | LRU cache entries.                                        |
| `pattern_confidence_ab`    | `0.90`  | Confidence for AB simple doubling (e.g., ခဏခဏ).           |
| `pattern_confidence_aabb`  | `0.85`  | Confidence for AABB syllable doubling (e.g., သေသေချာချာ). |
| `pattern_confidence_abab`  | `0.85`  | Confidence for ABAB word repeat.                          |
| `pattern_confidence_rhyme` | `0.95`  | Confidence for rhyme reduplication patterns.              |

### Neural Reranker Settings

Controlled via the `neural_reranker` attribute (`NeuralRerankerConfig`). MLP-based suggestion re-ranking using ONNX.

| Parameter                  | Default | Description                                            |
| -------------------------- | ------- | ------------------------------------------------------ |
| `enabled`                  | `False` | Enable neural reranking (requires trained model).      |
| `model_path`               | `None`  | Path to ONNX reranker model.                           |
| `stats_path`               | `None`  | Path to normalization statistics JSON.                 |
| `confidence_gap_threshold` | `0.15`  | Skip reranking when top-2 confidence gap exceeds this. |
| `max_candidates`           | `20`    | Maximum candidates to score per error.                 |

### Broken Compound Strategy Settings

Controlled via the `broken_compound_strategy` attribute (`BrokenCompoundStrategyConfig`). Tunes the validation strategy that detects incorrectly split compound words.

| Parameter                | Default | Description                                             |
| ------------------------ | ------- | ------------------------------------------------------- |
| `rare_threshold`         | `2000`  | Frequency below which a word is considered rare.        |
| `compound_min_frequency` | `5000`  | Minimum compound frequency to flag broken compound.     |
| `compound_ratio`         | `5.0`   | Minimum ratio of compound\_freq / rare\_word\_freq.     |
| `confidence`             | `0.8`   | Default confidence for broken compound errors.          |
| `both_high_freq`         | `5000`  | Frequency guard for multi-syllable both-high compounds. |
| `min_compound_len`       | `4`     | Minimum compound length for both-high-freq guard.       |

### Token Refinement Settings

Controlled via the `token_refinement` attribute (`TokenRefinementConfig`). Tunes the validation-time token-lattice refinement pass that exposes hidden error spans in merged tokens (e.g., particle attachment, negation attachment).

| Parameter                      | Default    | Description                                         |
| ------------------------------ | ---------- | --------------------------------------------------- |
| `suffix_score_boost`           | `0.85`     | Score boost when suffix matches a known form.       |
| `known_part_score`             | `1.35`     | Score for known dictionary parts.                   |
| `unknown_long_part_penalty`    | `0.45`     | Penalty for unknown long parts.                     |
| `split_complexity_penalty`     | `0.30`     | Penalty for complex multi-part splits.              |
| `bigram_scale`                 | `120000.0` | Scaling factor for bigram probability contribution. |
| `min_token_len`                | `3`        | Minimum token length for refinement candidates.     |
| `keep_if_freq_at_least`        | `2000`     | Keep token if frequency is at least this value.     |
| `min_score_gain`               | `0.55`     | Minimum score improvement to accept a split.        |
| `lattice_max_paths`            | `2`        | Maximum lattice paths to consider.                  |
| `syllable_split_min_token_len` | `4`        | Minimum token length for syllable-level splitting.  |
| `syllable_split_max_syllables` | `6`        | Maximum syllables for syllable-level splitting.     |

***

## Integrated Features

The following features are automatically integrated into the validation pipeline. Most are enabled by default and work transparently.

### Particle Typo Detection

Automatically detects common Myanmar particle typos using `PARTICLE_TYPO_PATTERNS`. Examples:

* `တယ` → `တယ်` (statement ending, missing asat)
* `နဲ` → `နဲ့` (with, missing tone)
* `သလာ` → `သလား` (question, missing tone)

These patterns have 0.90-0.95 confidence and are checked during context validation.

### Medial Confusion Detection

Catches context-aware ျ vs ြ medial confusion using `MEDIAL_CONFUSION_PATTERNS`. For example:

* `ကြီး` vs `ကျီး` (big vs crow)
* `ပြု` vs `ပျု` (do vs -)

### Morphology OOV Recovery

For out-of-vocabulary (OOV) words, the system attempts to recover the root by stripping common suffixes:

* Verb suffixes: `သည်`, `ခဲ့`, `မည်`, `နေ`, etc.
* Noun suffixes: `များ`, `တို့`, etc.

This improves suggestion quality for inflected forms.

### POS Sequence Validation

Uses ViterbiTagger output to detect invalid POS sequences:

* V-V (consecutive verbs without particles)
* P-P (consecutive particles)
* Invalid tag sequences defined in `INVALID_POS_SEQUENCES`

### Question Detection

Identifies sentence types (question/statement) and validates question particle usage:

* Detects question words: `ဘာ`, `ဘယ်`, `ဘယ်လို`, etc.
* Validates question particles: `လား`, `လဲ`, `သလဲ`, etc.

### Unified Suggestion Ranking

Suggestions from different sources are ranked using `UnifiedRanker` with source-specific weights:

| Source               | Weight | Priority    |
| -------------------- | ------ | ----------- |
| `particle_typo`      | 1.2    | Highest     |
| `semantic`           | 1.15   | High        |
| `context`            | 1.15   | High        |
| `medial_confusion`   | 1.1    | Medium-High |
| `medial_swap`        | 1.0    | Base        |
| `question_structure` | 1.0    | Base        |
| `symspell`           | 1.0    | Base        |
| `compound`           | 0.95   | Medium      |
| `morphology`         | 0.9    | Medium      |
| `morpheme`           | 0.85   | Medium-Low  |
| `pos_sequence`       | 0.85   | Medium-Low  |

### Tone Disambiguation

The `ToneDisambiguator` provides context-aware correction for commonly confused Myanmar tone marks. Available via:

```python theme={null}
from myspellchecker.text.tone import ToneDisambiguator

disambiguator = ToneDisambiguator()
corrections = disambiguator.check_sentence(["word1", "word2", ...])
```

Handles ambiguous words like:

* `သား` (son, disambiguated by family context patterns)
* `ငါ` (I/me vs `ငါး` fish, detects missing visarga in numeral contexts)
* `ပဲ` (only vs bean)