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

# AI-Powered Bank Reconciliation

> Guide to AI categorization, smart matching, anomaly detection, and the reconciliation dashboard

> **Cross-References:**
>
> * [Bank Reconciliation Wizard](/fa/bank-reconciliation-wizard-user-guide) - Base reconciliation workflow
> * [FA Module Settings](/fa/module-settings) - Configuration reference
> * [FA Security Considerations](/fa/security-considerations) - PHI/PII protection

***

## Overview

FA-28 extends the bank reconciliation module with AI-powered features that automate transaction categorization, suggest matches between bank and GL lines, detect anomalies, and provide a reconciliation dashboard. All AI features are **disabled by default** and create **draft journal entries only** — never auto-post.

### Feature Summary

| Feature           | Description                                                  | Permission Required        |
| ----------------- | ------------------------------------------------------------ | -------------------------- |
| AI Categorization | Suggests GL accounts for unmatched bank lines                | `fa.reconciliation.ai.use` |
| AI Smart Matching | Pairs unmatched bank lines with GL entries                   | `fa.reconciliation.ai.use` |
| Anomaly Detection | Flags duplicate payments, unusual amounts, unknown merchants | `fa.anomalies.view`        |
| AI Assistant      | Contextual help within reconciliation detail                 | `fa.reconciliation.ai.use` |
| Dashboard         | Aggregated reconciliation metrics and status                 | `fa.reconciliation.view`   |

***

## Enabling AI Features

### Prerequisites

* **Org Admin** or user with `fa.reconciliation.ai.configure` permission
* AI Gateway enabled (LOVABLE\_API\_KEY provisioned)

### Configuration

1. Navigate to **Finance > Settings**
2. Click the **Matching & AI** tab
3. Toggle features on/off:
   * **AI Categorization** — Automatically suggest GL accounts for bank lines
   * **AI Smart Matching** — Pair unmatched bank and GL lines using AI
   * **Anomaly Detection** — Flag suspicious transactions
4. Adjust confidence thresholds:
   * **Categorization Auto-Apply Threshold** (default: 0.85) — Suggestions above this create draft JEs automatically
   * **Matching Auto-Apply Threshold** (default: 0.90) — Matches above this are applied automatically
5. Click **Save**

***

## AI Transaction Categorization

When enabled, AI categorization runs automatically after the deterministic rule engine during Plaid sync. It processes unmatched bank lines that were not caught by existing rules.

### How It Works

1. Unmatched bank lines (no rule match, no existing JE) are batched
2. AI analyzes transaction descriptions, amounts, dates, and Plaid categories
3. Each line receives a suggested debit/credit account with a confidence score (0-1)
4. Lines above the auto-apply threshold get draft journal entries created automatically
5. Lines below the threshold show as suggestions for manual review

### Reviewing AI Suggestions

In the **Unmatched Bank Lines** table:

* Lines with AI suggestions show a **sparkle icon** and confidence percentage
* Hover to see the AI's reasoning
* Click **Accept** to create a draft journal entry
* Click **Create Rule** to create a reusable transaction rule from the suggestion
* Click **Reject** to clear the suggestion

### Security

* Only transaction descriptions, amounts, dates, and Plaid categories are sent to AI
* **No account numbers, names, SSNs, or other PHI/PII** are included in AI requests
* All created entries are drafts requiring manual posting

***

## AI Smart Matching

AI matching pairs unmatched bank lines with unmatched GL entries using pattern recognition.

### How It Works

1. After deterministic matching completes, AI analyzes remaining unmatched items
2. AI considers descriptions, amounts, dates, and patterns to suggest pairings
3. High-confidence matches (above threshold) are applied automatically as `ai_auto`
4. Lower-confidence suggestions appear as `ai_suggested` for manual review

### Reviewing Match Suggestions

In the **Unmatched Transactions** tab of reconciliation detail:

* AI-suggested matches appear in the **AI Match Suggestions** section
* Each shows the bank line, matched GL entry, confidence score, and reasoning
* Click **Accept** to confirm the match
* Click **Reject** to remove the suggestion
* Use **AI Match All (N)** button to bulk-accept all suggestions above 80% confidence

***

## Anomaly Detection

Statistical analysis flags potentially suspicious transactions.

### Detection Types

| Type              | Description                                             | Severity        |
| ----------------- | ------------------------------------------------------- | --------------- |
| Duplicate Payment | Same vendor + amount within 7 days                      | High (red)      |
| Unusual Amount    | >2 standard deviations from merchant historical average | Medium (yellow) |
| Unknown Merchant  | First-time merchant with no transaction history         | Low (blue)      |

### Viewing Anomalies

* Flagged transactions show a warning badge with severity color
* Hover for detailed anomaly information
* Anomaly scores range from 0-100 (higher = more suspicious)

***

## AI Reconciliation Assistant

The inline AI assistant provides contextual help within the reconciliation detail view.

### Using the Assistant

1. Open a reconciliation detail page
2. The AI assistant panel appears below the header (when enabled)
3. Type questions or use quick prompts:
   * "Why is this unmatched?"
   * "Show bank fees"
   * "Explain the difference"
4. The assistant has context about the reconciliation's balances, status, and discrepancies

### Privacy

* Only aggregated balances, counts, and descriptions are shared with AI
* No PHI/PII is included in assistant context

***

## Reconciliation Dashboard

The dashboard provides aggregated metrics across all reconciliations.

### Dashboard Cards

| Card                | Description                                                           |
| ------------------- | --------------------------------------------------------------------- |
| Status Distribution | Pie chart of reconciliation statuses (draft, in\_progress, completed) |
| Automation Rate     | Percentage of transactions matched automatically vs. manually         |
| Outstanding Items   | Count and total of unmatched bank and GL lines                        |
| Anomaly Alerts      | Number of flagged transactions requiring review                       |

### Accessing the Dashboard

* Navigate to **Finance > Reconciliations**
* The dashboard appears at the top of the page (collapsible)
* Click **Show/Hide Dashboard** to toggle visibility

***

## Troubleshooting

### AI Features Not Working

1. Verify AI features are enabled in **Finance > Settings > Matching & AI**
2. Confirm you have `fa.reconciliation.ai.use` permission
3. Check that the AI Gateway is provisioned (LOVABLE\_API\_KEY)
4. AI features degrade gracefully — the deterministic pipeline is unaffected

### No AI Suggestions Appearing

* AI only processes lines not already matched by rules or manual matching
* Check that bank lines exist without `rule_id` or `auto_journal_entry_id`
* AI categorization runs during Plaid sync; manual trigger available via hook

### Anomaly Scores Seem Incorrect

* Anomaly detection uses statistical analysis based on historical transaction data
* New organizations with limited history may see more "unknown merchant" flags
* Scores improve as more transaction history accumulates

***

## Related Documentation

* [Bank Reconciliation Wizard](/fa/bank-reconciliation-wizard-user-guide) - Base reconciliation workflow
* [Plaid Setup](/fa/PLAID_SETUP) - Bank connection configuration
* [FA Module Settings](/fa/module-settings) - All FA configuration options
* [FA Security](/fa/security-considerations) - Security and compliance

***

## Version History

### 1.0.0 (2026-02-16)

* Initial release: AI categorization, smart matching, anomaly detection, assistant, dashboard

***

**Last Updated:** 2026-02-16