Odoo-Modules/docs/specs/2026-04-03-fusion-accounting-design.md

fusion_accounting -- AI Accounting Co-Pilot for Odoo 19

Module: fusion_accounting Version: 1.0 Odoo: 19.0 Enterprise Date: April 3, 2026 Status: Design Specification

---

1. Purpose

An Odoo 19 module that embeds an AI agent (Claude / GPT with tool-calling) into the Accounting menu. The agent can query, analyze, reconcile, audit, and report on every aspect of the accounting system through a conversational interface backed by a dashboard.

The module serves three user types: business owner (strategic oversight), office staff (daily processing), and external accountant (period-end work). It starts with tiered permissions (read-free, low-risk auto-approved, high-risk requires approval) and adapts over time by promoting tool+scenario combinations that achieve high approval rates.

---

2. Architecture

2.1 Component Overview

fusion_accounting (Odoo Module)
├── AI Service Layer
│   ├── Agent orchestrator (prompt + tool dispatch)
│   ├── Claude adapter (Anthropic API, tool-calling)
│   ├── GPT adapter (OpenAI API, function-calling)
│   └── Provider config (switchable via settings)
│
├── Tool Layer (73+ Odoo ORM wrappers across 12 domains)
│   ├── Each tool: name, description, parameters, tier, domain
│   ├── Registered in fusion.accounting.tool model
│   └── Callable by AI via orchestrator dispatch
│
├── Rules Engine (Fusion Rules)
│   ├── fusion.accounting.rule model
│   ├── Created by admin or AI (with approval)
│   ├── Applied before general AI reasoning
│   └── Versioned with rollback
│
├── Memory Layer
│   ├── fusion.accounting.match.history (every suggestion + outcome)
│   ├── fusion.accounting.session (chat sessions)
│   └── Confidence scoring per tool+scenario
│
├── Dashboard
│   ├── Health cards (bank recon, AR, AP, HST, audit, month-end)
│   ├── Action center (prioritized needs-attention + recent activity)
│   └── Chat panel (persistent, context-aware)
│
└── Odoo Integration
    ├── Menu: Accounting > Fusion AI
    ├── Cron: periodic audit scan on posted entries
    ├── Hook: post-action_post audit check (optional)
    └── Security: role-based tool access

2.2 Data Flow

User message or dashboard click enters the controller. The controller builds a prompt containing: the user message, active Fusion Rules, recent match history, current Odoo context (page, journal, period), and the tool definitions for the relevant domain(s). This prompt goes to the selected AI provider.

The AI responds with either a text message or one or more tool calls. Tool calls are dispatched to the tool layer, which executes ORM operations against Odoo. Results return to the AI for further reasoning or final response. Tier 3 tool calls are intercepted and presented to the user for approval before execution.

2.3 AI Provider Integration

Both Claude (Anthropic) and GPT (OpenAI) are supported via adapters that normalize the tool-calling interface.

• Claude: Uses tools parameter with input_schema per tool. Responses include tool_use content blocks.
• GPT: Uses functions parameter with JSON Schema per function. Responses include function_call in the message.
• Adapter pattern: Each adapter translates between the normalized internal tool format and the provider-specific format. Switching providers requires only changing a config setting.

API keys are stored in ir.config_parameter with the fusion_accounting. prefix.

---

3. Tool Catalog

3.1 Tool Tiers

Tier	Behavior	Examples
1 -- Free	Execute immediately, no approval. All read-only operations.	get_unreconciled_bank_lines, calculate_hst_balance, get_ar_aging
2 -- Auto-approved	Execute immediately, logged. Low-risk writes that annotate but don't change financial data.	flag_entry, set_audit_status, send_followup (draft)
3 -- Requires approval	AI proposes, user approves/rejects. Financial writes.	match_bank_line_to_payments, reconcile_payment_to_invoice, create_payroll_journal_entry

Tier promotion: when a Tier 3 tool+scenario combination reaches a configurable accuracy threshold (default 95%) over a minimum sample size (default 30 decisions), it is promoted to Tier 2. Promotions can be reverted by the admin.

3.2 Domain 1 -- Bank Reconciliation

Tool	Tier	Odoo Method	Purpose
get_unreconciled_bank_lines	1	account.bank.statement.line.search_read(is_reconciled=False)	List unreconciled bank statement lines with filters
get_unreconciled_receipts	1	account.move.line.search_read(account_id=1122, reconciled=False)	List unreconciled Outstanding Receipts entries
match_bank_line_to_payments	3	account.bank.statement.line.set_line_bank_statement_line(move_line_ids)	Match a bank line to one or more payment journal items
auto_reconcile_bank_lines	3	account.bank.statement.line._try_auto_reconcile_statement_lines()	Run Odoo's built-in auto-reconciliation
apply_reconcile_model	3	account.reconcile.model._trigger_reconciliation_model(st_line)	Apply a specific reconciliation model/rule
unmatch_bank_line	3	account.bank.statement.line.action_unreconcile_entry()	Undo a reconciliation
get_reconcile_suggestions	1	account.reconcile.model.get_available_reconcile_model_per_statement_line()	Get Odoo's suggested reconciliation models
sum_payments_by_date	1	SQL aggregate on account.move.line	Sum card payments for a date range (Elavon batch matching)

3.3 Domain 2 -- HST/GST Management

Tool	Tier	Purpose
calculate_hst_balance	1	Net HST position (collected on 2005 minus ITCs on 2006) for a period
get_tax_report	1	Generate tax report via account.report generic tax handler
find_missing_tax_invoices	1	Invoices with taxable products but no tax applied
find_missing_itc_bills	1	Vendor bills without input tax credits
get_tax_return_status	1	Status of periodic tax returns via account.return
generate_tax_return	2	Refresh tax return data via account.return._generate_or_refresh_all_returns()
validate_tax_return	3	Mark tax return as validated

3.4 Domain 3 -- Accounts Receivable

Tool	Tier	Purpose
get_ar_aging	1	AR aging buckets (current, 30, 60, 90+)
get_overdue_invoices	1	Invoices past due with partner contact info
get_partner_balance	1	Single partner AR balance and open items
send_followup	2	Draft follow-up email via res.partner.execute_followup()
get_followup_report	1	HTML follow-up report for a partner
reconcile_payment_to_invoice	3	Match payment to invoice via account.move.line.reconcile()
get_unmatched_payments	1	Payments not matched to invoices

3.5 Domain 4 -- Accounts Payable

Tool	Tier	Purpose
get_ap_aging	1	AP aging buckets
find_duplicate_bills	1	Same vendor + amount + date within configurable window
match_bill_to_po	1	Cross-reference bill lines to PO lines
get_unpaid_bills	1	Vendor bills with outstanding balance
verify_bill_taxes	1	Check bill tax vs fiscal position expectation
get_payment_schedule	1	Bills sorted by due date for cash planning

3.6 Domain 5 -- Journal Review and Error Detection

Tool	Tier	Purpose
find_wrong_direction_balances	1	Accounts where balance direction contradicts account type
find_duplicate_entries	1	Entries with matching partner + amount + date + journal
find_wrong_account_entries	1	Product lines on unlikely accounts (e.g., revenue on tax account)
find_sequence_gaps	1	account.move records where made_sequence_gap = true
find_draft_entries	1	Draft entries that should have been posted or deleted
find_unreconciled_suspense	1	Suspense/clearing accounts with non-zero balance
verify_reconciliation_integrity	1	Check account.partial.reconcile consistency

3.7 Domain 6 -- Month-End / Year-End Close

Tool	Tier	Purpose
get_close_checklist	1	Aggregate all domain checks into a period close checklist
get_unreconciled_counts	1	Per-account count of unreconciled items
find_entries_in_locked_period	1	Entries after lock dates
get_accrual_status	1	Balance on accrual accounts (vacation, sick, etc.)
run_hash_integrity_check	1	res.company._check_hash_integrity()
get_period_summary	1	Trial balance for the closing period

3.8 Domain 7 -- Payroll Verification

Tool	Tier	Purpose
get_payroll_entries	1	Journal entries in payroll-related journals
compare_payroll_to_bank	1	Cross-reference payroll cheques to bank statement lines
verify_source_deductions	1	CPP + EI + tax calculation verification against CRA tables
get_cra_remittance_status	1	CRA payable balance vs payments made
find_unmatched_payroll_cheques	1	Bank cheques without matching payroll entry

3.9 Domain 8 -- Inventory and COGS

Tool	Tier	Purpose
get_stock_valuation	1	Stock In Hand (1069) balance and layers
get_price_differences	1	Entries on account 5010 (PO price vs bill price)
get_cogs_ratio_by_category	1	COGS vs revenue per product category
find_unusual_adjustments	1	Large inventory adjustment entries
get_inventory_turnover	1	Sales vs average inventory

3.10 Domain 9 -- ADP Reconciliation

Tool	Tier	Purpose
get_adp_receivable_aging	1	Aging on account 1101 (ADP Receivable)
match_adp_payment_to_invoice	3	Match ADP deposit to ADP invoices
verify_adp_split	1	Customer portion + ADP portion = invoice total
find_adp_without_payment	1	ADP invoices without matching government deposit
get_adp_summary	1	Period summary of ADP billing vs collection

3.11 Domain 10 -- Financial Reporting

Tool	Tier	Purpose
get_profit_loss	1	P&L via account.report
get_balance_sheet	1	Balance sheet via account.report
get_trial_balance	1	Trial balance via account.report
get_cash_flow	1	Cash flow via account.report
compare_periods	1	Two period reports side by side
answer_financial_question	1	Natural language to ORM/SQL query
export_report	2	account.report.export_to_pdf() or export_to_xlsx()

3.12 Domain 11 -- Audit and Integrity

Tool	Tier	Purpose
audit_posted_entry	1	Run all entry-level checks on a single account.move
audit_account_balances	1	Run all account-level checks (wrong direction, stale items)
audit_tax_compliance	1	All tax checks (missing tax, wrong rate, exempt verification)
audit_reconciliation_integrity	1	Verify account.partial.reconcile / account.full.reconcile consistency
check_hash_chain	1	res.company._check_hash_integrity()
check_sequence_gaps	1	account.journal._query_has_sequence_holes()
flag_entry	2	Create chatter message on account.move with flag and recommendation
get_audit_status	1	account.audit.account.status per tax return
set_audit_status	2	Update review status (todo / reviewed / supervised / anomaly)
get_audit_trail	1	mail.message history for an account.move
run_full_audit	1	All checks across all domains for a period
get_audit_report	1	Summary of all findings with severity ratings

3.13 Domain 12 -- Payroll Management

Tool	Tier	Purpose
parse_payroll_summary	1	Read pasted/uploaded QBO or fusion_payroll data
create_payroll_journal_entry	3	account.move.create() with payroll debit/credit lines
get_payroll_schedule	1	Employee pay dates, amounts, history
match_payroll_cheques	3	Match bank cheques to payroll liabilities
verify_payroll_deductions	1	Check CPP/EI/tax against CRA rate tables
get_cra_remittance_due	1	Calculate CRA obligation vs payments made
prepare_cra_payment	3	Create CRA remittance payment entry
generate_t4	2	Trigger fusion_payroll T4 generation
generate_roe	2	Trigger fusion_payroll ROE generation
get_payroll_cost_report	1	Period summary by employee/department

Phase 1 (QBO bridge): tools work with pasted/uploaded payroll data. Phase 2 (fusion_payroll native): tools call fusion_payroll ORM methods directly.

---

4. Fusion Rules Engine

4.1 Rule Model

fusion.accounting.rule
├── name                    Char, required
├── rule_type               Selection: match / classify / audit / fee / routing / followup
├── description             Text (natural language, read by AI)
├── trigger_domain          Text/JSON (Odoo domain filter for matching records)
├── match_logic             Text (natural language matching instructions for AI)
├── match_code              Text (optional Python for deterministic matching)
├── fee_account_id          Many2one → account.account
├── write_off_account_id    Many2one → account.account
├── approval_tier           Selection: auto / needs_approval
├── created_by              Selection: admin / ai
├── confidence_score        Float (0.0 to 1.0)
├── total_uses              Integer
├── total_approved          Integer
├── total_rejected          Integer
├── promotion_threshold     Float (default 0.95)
├── min_sample_size         Integer (default 30)
├── active                  Boolean
├── version                 Integer
├── parent_rule_id          Many2one → self (version chain)
├── journal_ids             Many2many → account.journal
├── company_id              Many2one → res.company
├── notes                   Text

4.2 Rule Lifecycle

1. Creation: Admin creates via UI form, or AI proposes after detecting a pattern (3+ identical matches). AI-proposed rules start at Tier 3.
2. Application: During reconciliation or auditing, the AI loads active rules and applies them before general reasoning. Rules with match_code run deterministically; rules with only match_logic are interpreted by the AI.
3. Scoring: Each use updates total_uses and total_approved / total_rejected. Confidence score is recalculated.
4. Promotion: When confidence crosses promotion_threshold with at least min_sample_size decisions, approval_tier changes from needs_approval to auto.
5. Modification: Admin or AI (with approval) can edit. Changes increment version and create a new record linked via parent_rule_id. Confidence resets for the modified variant.
6. Rollback: Admin can deactivate current version and reactivate a previous version.

4.3 Rule Priority

During processing, rules are evaluated in order:

1. Admin-created rules (highest priority)
2. AI-created rules with auto-approval (proven patterns)
3. AI-created rules needing approval (proposed patterns)
4. No rule matches: AI reasons from scratch using tools

---

5. Match History and Learning

5.1 Match History Model

fusion.accounting.match.history
├── session_id              Many2one → fusion.accounting.session
├── tool_name               Char (which tool was called)
├── tool_params             Text/JSON (parameters passed)
├── tool_result             Text/JSON (result returned)
├── ai_reasoning            Text (AI's explanation for the match)
├── ai_confidence           Float (AI's self-assessed confidence)
├── rule_id                 Many2one → fusion.accounting.rule (if rule-based)
├── proposed_at             Datetime
├── decision                Selection: approved / rejected / pending
├── decided_at              Datetime
├── decided_by              Many2one → res.users
├── rejection_reason        Text (user's explanation if rejected)
├── correct_action          Text/JSON (what should have happened, if corrected)
├── bank_statement_line_id  Many2one → account.bank.statement.line
├── move_line_ids           Many2many → account.move.line
├── amount                  Monetary
├── partner_id              Many2one → res.partner

5.2 How Learning Works

The AI's system prompt includes the most recent N match history records (configurable, default 50) filtered to the current domain/scenario. This gives the AI context about:

• What patterns have been approved (do more of this)
• What was rejected and why (avoid this)
• Partner-specific quirks (e.g., "Shirley Ramsumair: label unreliable")
• Fee patterns (e.g., "Elavon: ~1.6% fee to 60545")
• Timing patterns (e.g., "weekend card batches combine Fri+Sat")

The AI does not have persistent memory across sessions beyond what is stored in match history and rules. Every session starts fresh with the system prompt + loaded history + loaded rules.

---

6. Dashboard

6.1 Location

Accounting menu > Fusion AI (submenu, next to Dashboard).

6.2 Layout

Top row: 6 health cards. Each shows a key metric with color coding (green/yellow/red). Clicking any card starts a relevant conversation in the chat panel.

Card	Metric	Source
Bank Reconciliation	Unmatched line count + total amount	account.bank.statement.line where is_reconciled = False
AR Outstanding	Total receivable + overdue count	account.move.line on AR account, amount_residual > 0
AP Due	Total payable + due this week	account.move.line on AP account, grouped by due date
HST Balance	Net HST (collected minus ITCs)	Balances on accounts 2005 and 2006
Audit Score	Score 0-100 + active flag count	Weighted composite of all audit checks
Month-End Status	Current period status + open items	Aggregate of close checklist items

Middle: two-column action center.

Left column: "Needs Attention" -- AI-prioritized list of actionable items. Re-ranked daily by the audit cron. Items are clickable to start the relevant conversation.

Right column: "Recent AI Activity" -- log of autonomous actions (Tier 2), pending approvals (Tier 3), and completed conversations. Provides transparency.

Bottom/Side: Chat panel. Persistent across navigation within the Accounting module. Shows conversation history for the current session. Supports text input, file upload (for QBO payroll summaries), and structured approval cards for Tier 3 actions.

6.3 Approval Cards

When the AI proposes a Tier 3 action, the chat displays a structured card:

┌─────────────────────────────────────────────┐
│ Match Proposal                    94% conf  │
│                                             │
│ Bank: Mar 4 elavon mrch svc      $697.61   │
│ ↔ 4 card payments (Mar 3)        $709.14   │
│ Fee to 60545 (Elavon Fee)         $11.53   │
│                                             │
│ AI: "Weekend daily batch, 1.6% fee"        │
│                                             │
│         [ Approve ]  [ Reject ]             │
└─────────────────────────────────────────────┘

Batch mode: multiple cards can be displayed at once with "Approve All" / "Reject All" buttons plus individual controls.

---

7. Security

7.1 Access Groups

Group	Dashboard	Chat (Read)	Chat (Tier 2)	Chat (Tier 3)	Rules	Config
fusion_accounting.group_user (Staff)	View	Yes	No	No	View	No
fusion_accounting.group_manager (Manager)	View	Yes	Yes	Yes	Create/Edit	No
fusion_accounting.group_admin (Admin)	View	Yes	Yes	Yes	Create/Edit	Yes

7.2 Tool-Level Security

Each tool definition includes required_groups. The AI adapter filters available tools based on the current user's groups before building the prompt. A staff user's AI session simply does not have access to write tools.

7.3 Audit Trail

All AI actions are logged in fusion.accounting.match.history with the user who approved, timestamp, and full context. This is in addition to Odoo's standard chatter/mail tracking on modified records.

---

8. Module Structure

/mnt/extra-addons/fusion_accounting/
├── __manifest__.py
├── __init__.py
├── models/
│   ├── __init__.py
│   ├── accounting_session.py         # Chat session model
│   ├── accounting_match_history.py   # Match history (approved/rejected)
│   ├── accounting_rule.py            # Fusion Rules
│   ├── accounting_tool.py            # Tool registry model
│   ├── accounting_config.py          # Settings (API keys, thresholds)
│   └── accounting_dashboard.py       # Dashboard computed fields
├── services/
│   ├── __init__.py
│   ├── agent.py                      # AI orchestrator (prompt assembly, tool dispatch loop)
│   ├── adapters/
│   │   ├── __init__.py
│   │   ├── claude.py                 # Anthropic Claude adapter
│   │   └── openai.py                 # OpenAI GPT adapter
│   ├── tools/
│   │   ├── __init__.py
│   │   ├── bank_reconciliation.py    # Domain 1 tools
│   │   ├── hst_management.py         # Domain 2 tools
│   │   ├── accounts_receivable.py    # Domain 3 tools
│   │   ├── accounts_payable.py       # Domain 4 tools
│   │   ├── journal_review.py         # Domain 5 tools
│   │   ├── month_end.py              # Domain 6 tools
│   │   ├── payroll.py                # Domain 7 + 12 tools
│   │   ├── inventory.py              # Domain 8 tools
│   │   ├── adp.py                    # Domain 9 tools
│   │   ├── reporting.py              # Domain 10 tools
│   │   └── audit.py                  # Domain 11 tools
│   ├── prompts/
│   │   ├── system_prompt.py          # Base system prompt
│   │   └── domain_prompts.py         # Per-domain context injections
│   └── scoring.py                    # Confidence scoring + tier promotion logic
├── controllers/
│   ├── __init__.py
│   └── chat_controller.py            # JSON endpoint for chat messages
├── wizards/
│   ├── __init__.py
│   └── rule_wizard.py                # Quick-create rule from chat suggestion
├── static/
│   └── src/
│       ├── components/
│       │   ├── dashboard/
│       │   │   ├── fusion_dashboard.js
│       │   │   ├── fusion_dashboard.xml
│       │   │   ├── health_card.js
│       │   │   └── health_card.xml
│       │   ├── chat/
│       │   │   ├── chat_panel.js
│       │   │   ├── chat_panel.xml
│       │   │   ├── approval_card.js
│       │   │   └── approval_card.xml
│       │   └── rules/
│       │       └── rule_form.js
│       └── scss/
│           ├── dashboard.scss
│           └── chat.scss
├── views/
│   ├── dashboard_views.xml
│   ├── session_views.xml
│   ├── rule_views.xml
│   ├── config_views.xml
│   ├── match_history_views.xml
│   └── menus.xml
├── security/
│   ├── security.xml                  # Groups
│   └── ir.model.access.csv          # Model access rules
├── data/
│   ├── cron.xml                      # Periodic audit scan cron
│   ├── tool_definitions.xml          # Seed tool registry
│   └── default_rules.xml            # Starter Fusion Rules
└── report/
    └── audit_report_template.xml     # PDF audit report

---

9. Implementation Phases

Phase 1: Foundation (estimated 2 weeks)

Build the module skeleton, AI service layer, and first 2 domains.

• Module skeleton: manifest, models, security, menu
• AI service: agent orchestrator, Claude adapter, GPT adapter
• Tool layer: Domain 1 (bank reconciliation) + Domain 5 (journal review)
• Controller: chat endpoint (JSON-RPC)
• Basic chat UI: simple text input/output in an Odoo form view (no OWL widget yet)
• Match history model + logging
• Test: reconcile a batch of bank lines via chat

Milestone: Can reconcile bank statement lines through conversation.

Phase 2: Rules + More Domains (estimated 2 weeks)

• Fusion Rules model + CRUD views
• AI rule proposal flow (detect pattern, suggest rule, user approves)
• Confidence scoring + tier promotion logic
• Domains 2 (HST), 3 (AR), 4 (AP)
• Approval card flow for Tier 3 actions

Milestone: Can prepare HST filing, chase overdue invoices, and auto-create matching rules.

Phase 3: Dashboard + Audit (estimated 2 weeks)

• OWL dashboard with health cards
• OWL chat panel (persistent side panel)
• Approval cards with approve/reject buttons
• Domain 11 (audit) with cron-based periodic scanning
• Domain 6 (month-end close)

Milestone: Dashboard shows accounting health at a glance. Audit cron flags issues automatically.

Phase 4: Remaining Domains + Polish (estimated 2 weeks)

• Domains 7-10 (payroll verification, inventory, ADP, reporting)
• Domain 12 (payroll management -- QBO bridge for Phase 1, fusion_payroll-ready)
• Export/report tools (PDF, XLSX)
• Batch approval mode
• Learning/adaptation refinements
• Documentation

Milestone: Full 12-domain AI accounting co-pilot operational.

---

10. Dependencies

Odoo Modules (required)

• account (core accounting)
• account_accountant (enterprise bank reconciliation)
• account_reports (enterprise reporting + tax returns + audit status)
• account_followup (AR follow-ups)
• mail (chatter integration for flagging)

Odoo Modules (optional, enhanced features if installed)

• account_budget (budget tools)
• account_asset (asset depreciation tools)
• account_batch_payment (batch payment tools)
• fusion_payroll (native payroll integration for Domain 12 Phase 2)
• fusion_poynt (Poynt terminal data for card payment matching)
• stock_account (inventory valuation tools)

External

• Anthropic API key (for Claude) OR OpenAI API key (for GPT) -- at least one required
• Python packages: anthropic, openai (installed in Odoo container)

---

11. Configuration

Settings page at: Accounting > Fusion AI > Configuration

Setting	Type	Default
AI Provider	Selection (claude / openai)	claude
Anthropic API Key	Char (password field)	--
OpenAI API Key	Char (password field)	--
Claude Model	Char	claude-sonnet-4-20250514
OpenAI Model	Char	gpt-4o
Tier 3 Promotion Threshold	Float	0.95
Tier 3 Min Sample Size	Integer	30
Audit Cron Frequency	Selection (daily / weekly / monthly)	daily
Match History in Prompt	Integer (recent N records)	50
Max Tool Calls Per Turn	Integer	20
Enable Post-Action Audit Hook	Boolean	False

---

12. Risks and Mitigations

Risk	Mitigation
AI calls wrong tool or wrong parameters	Tiered permissions; Tier 3 requires human approval; tool parameter validation in each tool function
AI hallucinates financial data	All data comes from Odoo ORM queries, not AI generation. AI reasons about data but cannot invent it.
Reconciliation error corrupts books	All reconciliation uses Odoo's native engine (set_line_bank_statement_line, reconcile). Reversible via action_unreconcile_entry.
API costs escalate	Token usage tracked per session. Max tool calls per turn limits runaway loops. Model selection (cheaper models for simple queries).
Learning from bad patterns	Confidence scoring requires minimum sample size. Admin can demote promoted tools. Rule versioning with rollback.
Sensitive data in API calls	Financial data sent to AI provider. Mitigate by using AI provider's data privacy agreements. No customer PII in tool descriptions. Partner names in transaction data are necessary for matching.