From 02c71bca0a243f254bf0e39420d8a47d13f2cead Mon Sep 17 00:00:00 2001
From: eureka928 <meobius123@gmail.com>
Date: Mon, 26 Jan 2026 10:41:14 +0100
Subject: [PATCH] Add AI Cache Management documentation

Document the AI cache reset feature including what it does, when to use it,
how to reset via UI, and cost implications.
---
 docs/hosting/ai.md | 63 ++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 63 insertions(+)

diff --git a/docs/hosting/ai.md b/docs/hosting/ai.md
index 7273ab1ab..23ab1c12f 100644
--- a/docs/hosting/ai.md
+++ b/docs/hosting/ai.md
@@ -287,6 +287,69 @@ For self-hosted deployments, you can configure AI settings through the web inter
 
 **Note:** Settings in the UI override environment variables. If you change settings in the UI, those values take precedence.
 
+## AI Cache Management
+
+Sure caches AI-generated results (like auto-categorization and merchant detection) to avoid redundant API calls and costs. However, there are situations where you may want to clear this cache.
+
+### What is the AI Cache?
+
+When AI rules process transactions, Sure stores:
+- **Enrichment records**: Which attributes were set by AI (category, merchant, etc.)
+- **Attribute locks**: Prevents rules from re-processing already-handled transactions
+
+This caching means:
+- Transactions won't be sent to the LLM repeatedly
+- Your API costs are minimized
+- Processing is faster on subsequent rule runs
+
+### When to Reset the AI Cache
+
+You might want to reset the cache when:
+
+1. **Switching LLM models**: Different models may produce better categorizations
+2. **Improving prompts**: After system updates with better prompts
+3. **Fixing miscategorizations**: When AI made systematic errors
+4. **Testing**: During development or evaluation of AI features
+
+> [!CAUTION]
+> Resetting the AI cache will cause all transactions to be re-processed by AI rules on the next run. This **will incur API costs** if using a cloud provider.
+
+### How to Reset the AI Cache
+
+**Via UI (Recommended):**
+1. Go to **Settings** → **Rules**
+2. Click the menu button (three dots)
+3. Select **Reset AI cache**
+4. Confirm the action
+
+The cache is cleared asynchronously in the background. You'll see a confirmation message when the process starts.
+
+**Automatic Reset:**
+The AI cache is automatically cleared for all users when the OpenAI model setting is changed. This ensures that the new model processes transactions fresh.
+
+### What Happens When Cache is Reset
+
+1. **AI-locked attributes are unlocked**: Transactions can be re-enriched
+2. **AI enrichment records are deleted**: The history of AI changes is cleared
+3. **User edits are preserved**: If you manually changed a category after AI set it, your change is kept
+
+### Cost Implications
+
+Before resetting the cache, consider:
+
+| Scenario | Approximate Cost |
+|----------|------------------|
+| 100 transactions | $0.05-0.20 |
+| 1,000 transactions | $0.50-2.00 |
+| 10,000 transactions | $5.00-20.00 |
+
+*Costs vary by model. Use `gpt-4o-mini` for lower costs.*
+
+**Tips to minimize costs:**
+- Use narrow rule filters before running AI actions
+- Reset cache only when necessary
+- Consider using local LLMs for bulk re-processing
+
 ## Observability with Langfuse
 
 Sure includes built-in support for [Langfuse](https://langfuse.com/), an open-source LLM observability platform.