AGENT.md

statement-normalizer for agents

Machine interface for the statement-normalizer CLI. Deterministic and dependency-free: the same input always yields the same output.

Command

statement-normalizer <file|-> [--format FMT] [--currency USD] [--no-dedup]
                     [--invert-amounts] [--merge] [--csv] [--json-errors]

• Read from stdin with -. Format is auto-detected from content/extension; force it with --format (one of csv, ofx, text, mt940, camt053, camt052, qif).
• Default output is normalized transaction JSON on stdout.

Input

Raw statement bytes/text on stdin (-) or a file path. No network, no keys.

Output (stdout, JSON)

A single statement object (one input) or {"statements": [...]} (multiple):

{
  "account_id": null,
  "currency": "USD",
  "source_format": "csv",
  "transaction_count": 2,
  "transactions": [
    {"date": "2024-01-05", "amount": "-42.00", "description": "Coffee Shop",
     "txn_type": "debit", "currency": "USD", "balance": null, "fitid": null,
     "account_id": null, "source_format": "csv"}
  ],
  "source_file": "-"
}

• amount is a signed decimal string; money leaving the account is negative.
• date is YYYY-MM-DD. Amounts and dates are locale-independent.

Errors

With --json-errors, a failure prints a JSON envelope to stderr and exits non-zero (success output on stdout is unchanged):

{"ok": false, "error": {"type": "parse_error", "message": "input does not look like MT940"}}

error.type is parse_error (could not parse the input) or input_error (file missing/unreadable).

Exit codes (stable)

code	meaning
0	success
1	parse or input error
2	usage error (bad flags/arguments)

Backs the MCP tool

normalize_bank_statement in maxed-mcp, which pipes content to statement-normalizer - --json-errors.