record-ai-bookkeeping

Record AI Bookkeeping

Break the user's single sentence into one or more verifiable transactions and write them into the unified ledger.

When to trigger

• "Record an entry: today's lunch 46, Alipay"
• "Morning coffee 18, noon noodles 32, evening taxi 56, all via Alipay"
• "Today I paid 260 for a meal with Xiao Wang, of which 130 is reimbursed by the company"
• "Transfer 3000 from CMB to Alipay"
• "Osaka dinner 4200 yen, exchange rate 0.049, Visa"
• "This order was refunded 80 / reimbursement received 130"
• "The amount just now was wrong / undo the last entry / restore that entry"

Shared entry point

All operations go through the shared script, and the configuration path stays consistent within this session:

python3 "$AI_BOOKKEEPING_HOME/scripts/bookkeeping.py" \
  --config "/absolute/path/to/config.json" record "用户原话"

Add transaction

1. Keep the user's original words, message source, and a stable message ID. The message ID is used to prevent duplicate writes on retries.

2. First run the command without --commit , and read the amount, currency, type, category, account, date, ledger, confidence, and follow-up questions in the preview.

3. Check item by item:

   • The amount must be greater than 0.
   • Foreign currency must have a confirmed exchange rate for that transaction.
   • A refund must be linked to the original expense.
   • A reimbursement received must be linked to the original advance.
   • A transfer must have a payment account and a receiving account.
   • Cumulative refunds and cumulative reimbursements received must not exceed the original transaction limit.

4. When the user has explicitly said "record/enter/help me record", there is only one small-amount CNY transaction, the confidence is at least 0.85, and there are no follow-up questions, you may submit directly.

5. In the following cases, show a preview first and wait for confirmation:

   • Multiple transactions in a batch.
   • The amount reaches the large-amount threshold in the configuration.
   • Foreign currency, refunds, reimbursements, transfers, borrowing, or repayment.
   • The date, account, amount, exchange rate, or linked transaction is incomplete.
   • The category may have two reasonable interpretations.

6. After confirmation, submit with exactly the same input and message ID:

   python3 "$AI_BOOKKEEPING_HOME/scripts/bookkeeping.py" \
     --config "/absolute/path/to/config.json" \
     record "用户原话" \
     --source-message-id "稳定消息 ID" \
     --commit
   

7. After submission, verify the returned created_count、duplicate_count and transaction ID, then reply with a one-sentence receipt.

Open-ended expressions

The built-in parser covers examples/natural-language.md high-frequency sentence patterns. When encountering more free-form expressions, first organize them into structured JSON, with fields referring to schema/transactions.schema.json, then preview:

python3 "$AI_BOOKKEEPING_HOME/scripts/bookkeeping.py" \
  --config "/absolute/path/to/config.json" record-json input.json

After the user confirms, append --commit. Do not fabricate amounts, dates, exchange rates, accounts, or linked IDs.

Modify, undo, and restore

Modify basic fields:

python3 "$AI_BOOKKEEPING_HOME/scripts/bookkeeping.py" \
  --config "/absolute/path/to/config.json" \
  update "BK-..." '{"amount":"38"}' --reason "用户纠正金额"

After the amount, type, currency, exchange rate, or reimbursable amount changes, the system recalculates the base currency amount, cash flow, and personal consumption. Derived amounts cannot be changed directly.

Undo and restore:

python3 "$AI_BOOKKEEPING_HOME/scripts/bookkeeping.py" --config "/absolute/path/to/config.json" undo "BK-..."
python3 "$AI_BOOKKEEPING_HOME/scripts/bookkeeping.py" --config "/absolute/path/to/config.json" restore "BK-..."

"Undo the last entry" without a transaction ID will undo the most recent valid transaction. The reply must include the transaction ID, amount, and status of the operated transaction.

Categorization principles

• Prefer existing secondary categories and the user's historical habits.
• Travel expenses are recorded into the specific project ledger, while retaining consumption categories such as dining, transportation, and accommodation.
• Mark rent, utilities, insurance, subscriptions, etc. as fixed or flexible, then mark necessity.
• Refunds follow the category, ledger, and consumption attributes of the original expense.
• For reimbursed out-of-pocket personal expenses, only retain the portion ultimately borne by the user.

Boundaries and Exceptions

• When the same source message is submitted repeatedly, treat it as the same transaction and respond "already exists."
• When a unique original refund or reimbursement transaction cannot be found, ask only one minimal question.
• When the user says "change the transaction from just now," first show the key information of the most recent transaction before modifying it.
• Undo preserves history; physical deletion is prohibited.
• After a reimbursement receipt is undone or restored, re-verify the reimbursement status of the original advance payment.
• Categories manually locked by the user cannot be overridden by subsequent automatic categorization.

Receipt Format

已记 1 笔：7 月 1 日午饭 46.00 元，餐饮 / 午餐，支付宝。
流水 ID：BK-...

For batch entry, first give the total number of transactions and the total amount, then list the exceptions that need attention.