babilonia.tools.cashflow#

Aggregate and analyze cash flow from standardized bank statements.

This script scans a target directory for standardized bank statement files (T1 canonical format), groups them by year, concatenates daily records, and produces daily, monthly, and annual cash flow reports using the CashFlow analysis engine.

For each year found, the script:

  • Loads all matching T1 statement files.

  • Concatenates and reorders columns into a canonical layout.

  • Buckets rows by their actual transaction year (Data), not by the folder/file they were physically stored in.

  • Writes a consolidated daily cash flow CSV.

  • Computes monthly and annual cash flow summaries.

  • Writes monthly and annual CSV reports.

  • Displays formatted previews in the terminal.

After yearly processing, the script merges all yearly outputs into global daily, monthly, and annual datasets for the full system.

Processing can be restricted to a single year or applied to all available years. Terminal output is structured to facilitate inspection and logging.

Note

Some statement types do not align with calendar-month/year boundaries. Nubank credit-card invoices, for example, are filed under the year of the invoice, but a given invoice’s transactions can legitimately spill into December of the previous year (the invoice closes a few days into the new month). Because of this, file discovery is folder/invoice based, but reporting buckets are always derived from the actual Data column, never from the folder a file happened to live in. All T1 files are loaded up front (regardless of --year) and rows are bucketed by their real transaction year afterward, so spillover transactions land in the correct year’s report instead of being split or duplicated across two years.

Script Examples#

The script is intended for command-line execution.

Minimal PowerShell example (Windows)

Save as run_cashflow.ps1 and execute from PowerShell.

# ! Warning -- change paths and parameters

# Paths
$REPO   = "C:\path\to\repo"
$SCRIPT = "$REPO\babilonia\tools\cashflow.py"
$DATA   = "C:\data\bank_statements"

# Parameters
$TYPE = "bb-cc"
$YEAR = 2024

# Run script
python $SCRIPT `
    --folder $DATA `
    --type $TYPE `
    --year $YEAR
Minimal shell example (Linux)

Save as run_cashflow.sh and execute from a terminal.

#!/usr/bin/env bash

# ! Warning -- change paths and parameters

# Paths
REPO="/path/to/repo"
SCRIPT="$REPO/babilonia/tools/cashflow.py"
DATA="/data/bank_statements"

# Parameters
TYPE="bb-cc"
YEAR=2024

# Run script
python "$SCRIPT" --folder "$DATA" --type "$TYPE" --year "$YEAR"

Expected Folder Structure#

The input data is expected to follow a simple hierarchical layout:

bb/                                 # Bank
└── cc/                             # Bank account
    ├── 2022/
    │   ├── EXTRATO_BB_CC_2022-01_T1.csv
    │   └── EXTRATO_BB_CC_2022-02_T1.csv
    ├── 2023/
    │   └── EXTRATO_BB_CC_2023-01_T1.csv
    └── 2024/
        ├── EXTRATO_BB_CC_2024-01_T1.csv
        └── EXTRATO_BB_CC_2024-02_T1.csv

Each *_T1.csv file represents a canonical (Tier 1) standardized bank statement.

During execution, the script generates consolidated and aggregated outputs:

bb/                                 # Bank
└── cc/                             # Bank account
    └── 2024/
        ├── CAIXA_BB_CC_2024_DIARIO.csv
        ├── CAIXA_BB_CC_2024_MENSAL.csv
        └── CAIXA_BB_CC_2024_ANUAL.csv

Global merged outputs (all years):

bb/                                 # Bank
└── cc/                             # Bank account
    ├── CAIXA_BB_CC_O_DIARIO.csv
    ├── CAIXA_BB_CC_O_MENSAL.csv
    └── CAIXA_BB_CC_O_ANUAL.csv

Data Levels#

  • Tier 1 (T1): Canonical, standardized statement files produced by the parsing stage.

  • Daily: Concatenated transaction-level data, bucketed by the real transaction year (from Data), not by source file/folder.

  • Monthly: Aggregated per month with cumulative fields.

  • Annual: Aggregated per year with cumulative fields.

The script does not modify input files; all outputs are written as new CSV files.

Functions

main()

babilonia.tools.cashflow.main()[source]#