ask-ai-bookkeeping

Ask AI Bookkeeping

Answer accounting questions from confirmed transactions, and clearly state the time range, filter conditions, and statistical basis together.

When to trigger

• "How much was spent on dining in July?"
• "How much did the Osaka trip cost in total, list both yen and RMB"
• "Which reimbursements haven't arrived yet?"
• "What are this month's income, expenses, and balance?"
• "What are the last 10 Alipay transactions?"
• "What proportion of this month's income do rent plus utilities account for?"

Shared entry point

Run high-frequency queries directly:

python3 "$AI_BOOKKEEPING_HOME/scripts/bookkeeping.py" \
  --config "/absolute/path/to/config.json" \
  ask "用户问题"

When a fixed baseline time for "this month" is needed, pass in --now。

Query process

1. Identify the time range. If the user did not specify a time and the result would clearly be affected by the range, ask first; "this month" uses the configured time zone.
2. Identify filter items: transaction type, category, merchant, payment account, project ledger, currency, reimbursement status.
3. Call ask. The returned result must retain:
   • scope: time and time zone.
   • filters: the filter conditions actually used.
   • total and the base currency.
   • Original-currency totals, applicable to travel and foreign-currency queries.
   • Matched transactions and their count.
   • basis: the treatment basis for refunds, transfers, and reimbursements.
4. For compound questions, you may use list --month YYYY-MM to read the details of the same range and then aggregate. When calculating, use personal_amount、cash_in、cash_out and transaction_type, and do not recalculate from natural-language amounts.
5. Start the answer with a one-sentence conclusion, then give 2 to 5 items of composition or anomalies. Amounts are uniformly kept to two decimal places.

Common bases

• "How much was spent": total personal consumption, expenses minus refunds, excluding reimbursable portions and amounts payable by others.
• "How much income": real income, excluding refunds, reimbursements received, borrowings, and account transfers.
• "How much cash is left / change": cash inflow minus cash outflow; transfers move between two accounts.
• "How much did the trip cost": filter by project ledger, give the base-currency total, and list separately by original currency.
• "Pending reimbursement": originally advanced reimbursable amount minus confirmed received amount.
• "Balance": answer only when the account opening balances and all account transactions are complete; if conditions are insufficient, say so directly.

Boundaries and error prevention

• By default, exclude pending-confirmation and voided transactions.
• When the user asks "why", list the composition details or category summary, not just a single total.
• When the time or object is ambiguous, ask only one most critical question.
• When the query result is empty, state the actual filter conditions; do not speculate that the user never recorded it.
• When foreign currency lacks an exchange rate, list it as a data quality issue; do not guess an exchange rate on the spot.
• Reimbursements, refunds, and transfers strictly follow the unified basis to avoid counting cash inflows as income.
• This is a personal financial record and analysis tool; it does not give return promises, tax conclusions, or investment instructions.

Answer examples

2026 年 7 月餐饮个人净支出 200.00 元，共 2 笔：消费 300.00 元，退款 100.00 元。
范围：2026-07-01 至 2026-08-01；已排除待确认和已撤销流水。