# ファジーマップマクロとブラケットロジック

Aura は、「開始ルール」がトリガーされると、複数の前処理ルールを「FUZZY_MAP_pre.py」ファイル内でグループ化し、一貫したパイプラインとして順次実行することをサポートしています。このドキュメントでは、この機能の設計思想、構文、および実行フローについて説明します。

## 中心となる設計原則

1. **冗長性ゼロ**: グループ内のルールは標準の Python タプルのままです。
`('replacement_text', r'regex_pattern', しきい値, flags_and_options)`
2. **二重の使いやすさ**: グループ内の個々のルールは、完全に機能するスタンドアロン ルールです。グループがトリガーされない場合は、親ループで通常どおり評価されます。
3. **パッシブ終了マーカー**: グループの終了は、それ自体では決して一致しないパッシブ ルール エントリによって定義されます。これは純粋にパーサーの境界マーカーとして機能します。
4. **ハイブリッド フォールバック (一致しない場合に追加)**: グループがアクティブな場合、すべての内部ルールが出力に寄与する必要があります。内部ルールの正規表現がテキストと一致する場合、通常の置換が行われます。一致しない場合、置換テキストが現在のテキストにスペースを入れて追加されます。

---

## 構文と構造

マクロ グループは、`FUZZY_MAP_pre.py` の **Start Rule** と **End Rule** の間に一連の標準ルールをラップすることによって定義されます。

### 1. 開始ルール
開始ルールは、一致した場合にマクロをトリガーする標準ルールです。オプション辞書には「group_start」キーが含まれています。
```python
('replacement', r'start_pattern', 100, {'group_start': 'unique_group_name'})
```

### 2. 内部規則
内部ルールは、開始ルールの後に連続して配置される標準ルールです。特別なメタデータは必要ありません。
```python
('inner_replacement', r'inner_pattern', 100, {})
```

### 3. 終了ルール (パッシブマーカー)
終了ルールには、オプション ディクショナリに「None」置換、空のパターン、および「group_end」キーがあります。
```python
(None, r'', 100, {'group_end': 'unique_group_name'})
```

---

## 具体的な例

以下は、`FUZZY_MAP_pre.py` ファイルで定義された実際のテスト ケースです。

```python
FUZZY_MAP_pre = [
    # Start Rule: Triggers the group 'sandbox_test' when "start sandbox" matches
    ('Sandbox:', r'start\w* sandbox', 100, {'group_start': 'sandbox_test'}),
    
    # Inner Rule 1: Replaces "apfel" with "birne" if present
    ('birne', r'apfel', 100, {}),
    
    # Inner Rule 2: Replaces "banane" if present, otherwise appends "banane"
    ('banane', r'banane', 100, {}),
    
    # End Rule: Passive boundary marker
    (None, r'', 100, {'group_end': 'sandbox_test'}),
]
```

### 実行フローのシナリオ:

* **シナリオ A (トリガーされたマクロ)**:
* 入力: `「apfel でサンドボックスを開始」`
* 予想される流れ:
1. 開始ルールは `"start Sandbox"` と一致し、それを `"Sandbox:"` -> 現在のテキスト: `"Sandbox: mit apfel"` に置き換えます。
2. グループ「sandbox_test」がトリガーされます。
3. `"Sandbox: mit apfel"` で内部ルールを再帰的に実行します。
- 内部ルール 1 は `"apfel"` に一致し、`"birne"` に置き換えます -> 現在のテキスト: `"Sandbox: mit birne"`。
- 内部ルール 2 は `"banane"` に一致しません。グループがアクティブであるため、`"banane"` の追加にフォールバックします -> 現在のテキスト: `"Sandbox: mit birne banane"`。
4. 最終テキスト「Sandbox: mit birne banane」が返され、LanguageTool によって修正されます。
* 出力: `"サンドボックス: mit Birne Banane"`

* **シナリオ B (トリガーされないマクロ - 2 倍の使いやすさ)**:
* 入力: `「アイン・アプフェルとアイネ・キルシェ」`
* 予想される流れ:
1. 開始ルールが一致しません。グループ「sandbox_test」は非アクティブなままです。
2. ループは次のルールに進みます。
3. **内部ルール 1**: `"apfel"` に一致し、それを `"birne"` に置き換えます -> 現在のテキスト: `"ein birne und eine kirsche"`。
4. **内部ルール 2**: 一致しません。グループがトリガーされなかったため、ルールは通常のスタンドアロン ルールとして動作し、**何も追加されません**。
5. 終了ルールは無視されます。
* 出力: `"ein birne und eine kirsche"`

---

## 技術的な詳細 (内部)

* **分離再帰**: グループがトリガーされると、エンジンは `custom_rules=[inner_rule]` を指定して `process_text_in_background` を再帰的に呼び出します。これにより、各内部ルールが完全な同期パイプライン パス内で実行できるようになります。
* **パフォーマンスと安定性の保護策**:
* **シーケンス バイパス**: 内部再帰実行は、デッドロックや実行遅延を防ぐために「chunk_id」シーケンス キューをバイパスします。
* **I/O および TTS の抑制**: 再帰的実行により、中間ファイルの書き込みと TTS 音声出力が抑制され、最終的に安定したテキストのみが書き込まれ、読み上げられるようになります。
* **安定性の保護**: フォールバック追加中の無限の安定性ループを防ぐために、再帰的実行は 1 回の反復後に厳密に中断されます。
* **安全な終了**: 安定性チェックは、無限ループを防止するために最大反復回数 (「MAX_ITERATIONS_FOR_SAFETY」) に厳密に依存し、正規の遅いマクロ実行を途中で中止する可能性がある時間ベースのスロットルをバイパスします。
__CODE_BLOCK_4__