# Advanced Result Caching (State-Aware)

## Overview
Aura features a persistent, context-aware result cache designed to eliminate redundant processing. When a voice command is recognized and matches a rule, Aura checks if the exact same result has been generated before under the same circumstances. If a match is found, Aura bypasses expensive operations like **LanguageTool grammar checks** or **Ollama LLM generation**, delivering the result with near-zero latency.

## Key Features
- **Context-Aware:** The cache is specific to the active window title. A command said in "LibreOffice" can have a different cached result than the same command in "Terminal."
- **Self-Healing (Auto-Invalidation):** The cache automatically expires if you modify the underlying rule file (`.py` map). 
- **Privacy First:** All cached results are stored in a local SQLite database (`data/_aura_result_cache.db`).
- **Zero Maintenance:** For most users, this works entirely in the background without configuration.

## How it Works
The system generates a unique `cache_id` based on three variables:
1. **The Rule Output:** The text generated by the map.
2. **The Language:** The current active language code (e.g., `de-DE`).
3. **The Active Window:** The title of the window currently in focus.

### Validity Logic
The cache ensures that you never receive "stale" information. It uses two types of validity checks:

| Type | Name | Logic | Use Case |
| :--- | :--- | :--- | :--- |
| **Type 0** | **File Auto-Sync** | Uses the modification time (`mtime`) of the map file. | **Standard.** If you edit your Sandbox or Map, all associated cache entries are instantly invalidated. |
| **Type 1** | **Manual Timestamp** | Uses a fixed `timestamp` provided in the rule attributes. | **Developer.** Hardcode a version/timestamp to force or maintain a specific result state. |

## Rule Configuration Examples

You can control caching behavior directly within your `FUZZY_MAP_pre.py` or `FUZZY_MAP.py` files.

### 1. Default Behavior (Automatic Caching)
By default, caching is enabled and uses the file's modification time.
```python
# No extra attributes needed. 
# If this file is saved, the cache for this rule refreshes.
('Bold', r'^make it bold$', 100)
```

### 2. Disabling Cache
If a command produces dynamic data (like the current time or a random joke), you should disable the cache.
```python
('Current Time', r'^what time is it$', 100, {
    'cache': False 
})
```

### 3. Manual Timestamp (Fixed Versioning)
If you want the cache to persist regardless of file edits (unless you change the version), use a manual timestamp.
```python
('Stable Command', r'^run complex task$', 100, {
    'timestamp': '2026-05-09-v1'
})
```

## Performance Impact
- **Cache Miss:** Standard processing (0.05s - 5.0s depending on LLM usage).
- **Cache Hit:** Instant processing.

This mechanism is commands or corrected typos are returned instantly without straining the CPU.