losalamos.tools.build_budget

Build transfer notes from a budget seed configuration.

Reads a config file and one or more budget (batch) files, builds the in-memory Budget collection, optionally prints the equivalent analysis, and optionally writes the notes to disk.

Usage

python -m losalamos.tools.build_budget --config <config_file>

Config file

The config file can be TOML, YAML, or JSON.

Required keys

• name — budget name, used as the note filename prefix.

• year — budget year (integer).

• budgets — list of paths to batch files.

Optional keys

• duration — number of years to cover (default 1).

• folder — output folder path. When absent or null, notes are built in memory only and not written.

• split — write inflows and outflows into separate subfolders (default false).

• equivalent — print the equivalent analysis after building (default false).

TOML

name     = "HouseBudget"
year     = 2027
duration = 1
folder   = "/vault/budget/house"
split    = false
equivalent = true

budgets = [
    "/seeds/house_contracts.toml",
    "/seeds/house_income.toml",
]

YAML

name:     HouseBudget
year:     2027
duration: 1
folder:   /vault/budget/house
split:    false
equivalent: true

budgets:
  - /seeds/house_contracts.yaml
  - /seeds/house_income.yaml

JSON

{
  "name": "HouseBudget",
  "year": 2027,
  "duration": 1,
  "folder": "/vault/budget/house",
  "split": false,
  "equivalent": true,
  "budgets": [
    "/seeds/house_contracts.json",
    "/seeds/house_income.json"
  ]
}

Budget file

A budget file holds one or more batches. Each batch has a defaults block and a transfers list. Entry-level keys override defaults.

TOML

[[batch]]
[batch.defaults]
commitment = "contracts"
recurrence = "1 month"
currency   = "BRL"
account    = "BB-001"
payer      = "Person Name"
direction  = "outflow"

[[batch.transfers]]
value    = 1000.00
receiver = "Landlord Co"
day      = 5

[[batch.transfers]]
value    = 500.00
receiver = "Internet Provider"
day      = 15


[[batch]]
[batch.defaults]
commitment = "income"
recurrence = "1 month"
currency   = "BRL"
account    = "BB-001"
receiver   = "Person Name"
direction  = "inflow"

[[batch.transfers]]
value = 5000.00
payer = "Employer Co"
day   = 5

YAML

batch:
  - defaults:
      commitment: contracts
      recurrence: 1 month
      currency:   BRL
      account:    BB-001
      payer:      Person Name
      direction:  outflow
    transfers:
      - value:    1000.00
        receiver: Landlord Co
        day:      5
      - value:    500.00
        receiver: Internet Provider
        day:      15

  - defaults:
      commitment: income
      recurrence: 1 month
      currency:   BRL
      account:    BB-001
      receiver:   Person Name
      direction:  inflow
    transfers:
      - value: 5000.00
        payer: Employer Co
        day:   5

JSON

[
  {
    "defaults": {
      "commitment": "contracts",
      "recurrence": "1 month",
      "currency": "BRL",
      "account": "BB-001",
      "payer": "Person Name",
      "direction": "outflow"
    },
    "transfers": [
      {"value": 1000.00, "receiver": "Landlord Co",      "day": 5},
      {"value":  500.00, "receiver": "Internet Provider", "day": 15}
    ]
  },
  {
    "defaults": {
      "commitment": "income",
      "recurrence": "1 month",
      "currency": "BRL",
      "account": "BB-001",
      "receiver": "Person Name",
      "direction": "inflow"
    },
    "transfers": [
      {"value": 5000.00, "payer": "Employer Co", "day": 5}
    ]
  }
]

Functions

build_budget(config_path)

Build a Budget from a config file.

losalamos.tools.build_budget.build_budget(config_path: Path) → Budget

Build a Budget from a config file.

Loads the config, resolves and merges all batch files listed under budgets, builds the in-memory collection, optionally prints the equivalent analysis, and optionally saves notes to disk.

Parameters:

config_path (pathlib.Path) – Path to the config file (TOML, YAML, or JSON).

Raises:

ValueError – If required config keys are missing or a batch file cannot be parsed.

Returns:

The populated Budget instance.

Return type:

Budget