budget.estimate

Overwrite accounts' budget amounts with figures from past transactions, as GnuCash's Estimate dialog does.

Fills the budget amounts of the accounts you name from what happened in the past, as GnuCash's Estimate dialog does. History periods follow the budget's own recurrence starting at startDate; the account's change over history period n becomes budget period n. With useAverage the change over all the history periods, divided by the number of periods, goes into every period. Each account's change includes its sub-accounts. Closing transactions are left out.

It overwrites every period of every account you name, set amounts included, so it is destructive. Figures are rounded to significantDigits (default 1) significant digits, but never to the left of the decimal point: 812.50 at 2 digits is 813, and 5.6789 at 1 digit is 6. A period with no change is a set zero.

Examples

Example: with a new, empty book open as book.gnucash.

JSON-RPC

Request:

{"jsonrpc":"2.0","id":1,"method":"account.create","params":{"name":"Checking","type":"BANK","commodity":"USD"}}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "…"
}

Request:

{"jsonrpc":"2.0","id":2,"method":"account.create","params":{"name":"Rent","type":"EXPENSE","commodity":"USD"}}

Response:

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": "…"
}

Request:

{"jsonrpc":"2.0","id":3,"method":"budget.create","params":{"name":"2024","numPeriods":3,"recurrence":{"mult":1,"periodType":"month","start":"2024-01-01"}}}

Response:

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": "…"
}

Request:

{"jsonrpc":"2.0","id":4,"method":"transaction.post","params":{"datePosted":"2024-01-05","description":"Rent","splits":[{"account":"Rent","value":"750.00"},{"account":"Checking","value":"-750.00"}]}}

Response:

{
  "jsonrpc": "2.0",
  "id": 4,
  "result": "…"
}

Request:

{"jsonrpc":"2.0","id":5,"method":"transaction.post","params":{"datePosted":"2024-02-05","description":"Rent","splits":[{"account":"Rent","value":"812.50"},{"account":"Checking","value":"-812.50"}]}}

Response:

{
  "jsonrpc": "2.0",
  "id": 5,
  "result": "…"
}

Request:

{"jsonrpc":"2.0","id":6,"method":"budget.estimate","params":{"budget":"00ed0000000000000000000000000003","accounts":["Rent"],"startDate":"2024-01-01","significantDigits":2}}

Response:

{
  "jsonrpc": "2.0",
  "id": 6,
  "result": {
    "amounts": [
      {
        "accountName": "Rent",
        "period": 0,
        "amount": {
          "num": "750",
          "denom": "1"
        },
        "…": "…"
      },
      {
        "period": 1,
        "amount": {
          "num": "813",
          "denom": "1"
        },
        "…": "…"
      },
      {
        "period": 2,
        "amount": {
          "num": "0",
          "denom": "1"
        },
        "…": "…"
      }
    ],
    "…": "…"
  }
}

Command line

red-ale exec --book book.gnucash --script - <<'EOF'
account.create {"name":"Checking","type":"BANK","commodity":"USD"}
account.create {"name":"Rent","type":"EXPENSE","commodity":"USD"}
budget.create {"name":"2024","numPeriods":3,"recurrence":{"mult":1,"periodType":"month","start":"2024-01-01"}}
transaction.post {"datePosted":"2024-01-05","description":"Rent","splits":[{"account":"Rent","value":"750.00"},{"account":"Checking","value":"-750.00"}]}
transaction.post {"datePosted":"2024-02-05","description":"Rent","splits":[{"account":"Rent","value":"812.50"},{"account":"Checking","value":"-812.50"}]}
budget.estimate {"budget":"00ed0000000000000000000000000003","accounts":["Rent"],"startDate":"2024-01-01","significantDigits":2}
EOF

It prints:

[
  "…",
  "…",
  "…",
  "…",
  "…",
  {
    "amounts": [
      {
        "accountName": "Rent",
        "period": 0,
        "amount": {
          "num": "750",
          "denom": "1"
        },
        "…": "…"
      },
      {
        "period": 1,
        "amount": {
          "num": "813",
          "denom": "1"
        },
        "…": "…"
      },
      {
        "period": 2,
        "amount": {
          "num": "0",
          "denom": "1"
        },
        "…": "…"
      }
    ],
    "…": "…"
  }
]

MCP tool call

Tool call:

{"name":"account.create","arguments":{"name":"Checking","type":"BANK","commodity":"USD"}}

Result:

{
  "content": [
    {
      "type": "text",
      "text": "\"…\""
    }
  ]
}

Tool call:

{"name":"account.create","arguments":{"name":"Rent","type":"EXPENSE","commodity":"USD"}}

Result:

{
  "content": [
    {
      "type": "text",
      "text": "\"…\""
    }
  ]
}

Tool call:

{"name":"budget.create","arguments":{"name":"2024","numPeriods":3,"recurrence":{"mult":1,"periodType":"month","start":"2024-01-01"}}}

Result:

{
  "content": [
    {
      "type": "text",
      "text": "\"…\""
    }
  ]
}

Tool call:

{"name":"transaction.post","arguments":{"datePosted":"2024-01-05","description":"Rent","splits":[{"account":"Rent","value":"750.00"},{"account":"Checking","value":"-750.00"}]}}

Result:

{
  "content": [
    {
      "type": "text",
      "text": "\"…\""
    }
  ]
}

Tool call:

{"name":"transaction.post","arguments":{"datePosted":"2024-02-05","description":"Rent","splits":[{"account":"Rent","value":"812.50"},{"account":"Checking","value":"-812.50"}]}}

Result:

{
  "content": [
    {
      "type": "text",
      "text": "\"…\""
    }
  ]
}

Tool call:

{"name":"budget.estimate","arguments":{"budget":"00ed0000000000000000000000000003","accounts":["Rent"],"startDate":"2024-01-01","significantDigits":2}}

Result:

{
  "structuredContent": {
    "amounts": [
      {
        "accountName": "Rent",
        "period": 0,
        "amount": {
          "num": "750",
          "denom": "1"
        },
        "…": "…"
      },
      {
        "period": 1,
        "amount": {
          "num": "813",
          "denom": "1"
        },
        "…": "…"
      },
      {
        "period": 2,
        "amount": {
          "num": "0",
          "denom": "1"
        },
        "…": "…"
      }
    ],
    "…": "…"
  }
}

Effect: destructive, on the Book.

Params

Params of budget.estimate.

budget (Guid, required): The budget.
accounts (array of AccountRef, required): The accounts to estimate, at least one; each from its own subtree.
startDate (Date, required): The start of history period 0; history periods follow the budget's recurrence from here.
significantDigits (integer (uint8)): Significant digits to round to, 1 to 12.
useAverage (boolean): Store the average over every history period in every period.

Result

The result of budget.estimate.

budget (Guid, required): The budget.
amounts (array of AmountInfo, required): Every amount written.