Envelop budgeting

[Ramblurr]

I've been using beancount+fava for over a year now with great success.

However having started my personal finance journey with envelop budgeting, and later on the various iterations of YNAB before it became a hosted service, I really miss the month-by-month budgeting to interface that YNAB made famous (example from YNAB4).

I want to implement this interface into my beancount+fava workflow, but the question is how/where the extra data should be stored. Martin does not see budgeting as a core-feature for beancount, which I understand and respect. I've toyed with fava's budget feature, but just find myself missing this particular interface. The workflow of allocating all your available funds to a budget on a month by month basis is very powerful. Being able to visualize the budgets in that tabular view and tweak the numbers slightly and receive instant feedback is exactly what I am missing.

The key change that this interface would introduce to the current status quo is the creation of novel data from an interface rather than from editing the ledger file directly. The fact that beancount and fava are read-only tools is very powerful, and I'm hesitant to upset this state of affairs. (edit: I forgot that fava does in fact allow editing of the beancount file from within itself, so perhaps this isn't such a terrible idea?)

I want to get the fava community's feedback on how best to implement this budgeting tool. Fava already presents a great API for reading/querying transactions from the ledger and provides a core set of primitives that the budgeting tool could build on.

Should such a tool be implemented in fava? Or should it be entirely separate? Could it be structured as some sort of optional addon/plugin module? Perhaps the answer is that I shouldn't build it on fava at all, and do it separately as another external tool.

As for data persistence, I think introducing a companion file is the best method, rather than shoehorn it into beancount. This would involve a workflow where one works with beancount/fava on their existing .beancount file while also maintaining a new .budget file alongside. Whether this is a plain text file with a new format, or a structured file such as sqlite, remains an open question.

That said, fava's custom budget directive could work to power the budget interface. But then after making changes in the budget UI, how to propagate those changed directive lines back to the beancount ledger? The tool could output a patch file that you apply to your ledger, or simply output a block of budget transactions to be copy/pasted.

Very curious to hear your thoughts!

[yagebu]

This is basically a duplicate of #650, see also #375 (comment) for how this could be implemented.

Basically you'll need to build a Beancount plugin that auto-generates transactions to wire expenses through your budget accounts. Allocating your budget would just mean writing a transaction distributing your income to budget accounts. A report for the budgets could be part of Fava or and extension to Fava (once #924 is merged).

[MacGyverNL]

I'm in the same situation as @Ramblurr and the lack of non-resetting envelope budgeting is what's keeping me from switching to sensible systems like BeanCount or GnuCash. I vehemently dislike the approach of keeping a bunch of envelop budget accounts as though they actually exist as "real" accounts, and I've been thinking a bit on why that is. Classically, you'd withdraw the money from accounts, put them in envelopes, and that's where the money would actually physically be. If that's what you do, then having them as accounts makes total sense.

However, for me, the innovation that made it so easy to use YNAB was that these envelopes do not need to physically exist; for budgeting, it does not matter precisely where the assets live, the only consideration is whether the asset is easily accessible (think checking vs long-term deposit accounts). This means that these envelope budgets are orthogonal to asset accounts. Taking money out of the asset accounts to fill the budgets in that case is not an accurate reflection of reality.

The solution proposed by some GnuCash users is to have a separate set of accounts registering budgets. This registers budgets as liability accounts and has a "budgeted money" asset account totaling your other assets. Budgeting is then the act of increasing the liability in a budget, and increasing the asset in "budgeted money" equally. Expending money from normal asset accounts then needs additional postings decreasing the budgeted liability and similarly decreasing the amount of "budgeted money". Because this balances out to 0 it doesn't actually cause a problem, but conceptually it's doubling your cashflow and, at least in GnuCash, the duplicated data entry is insane.

Of course, one could do the same thing in BeanCount. In fact, I'd say that in BeanCount a user could even make this a bit more elegant by representing real assets as e.g. "EUR" and "budgeted assets" as "EUR_BUDGET", effectively introducing a "shadow-coin" for every "real coin" that enters the books, but ensuring these don't accidentally mix. But that still leaves you with a bunch of "real" accounts and, basically, "double" in- and out-flow.

Ledger's solution of using virtual balanced transactions on virtual accounts, which you can filter out for an account statement, and leave in for a budget statement, is okay-ish, but only because it is easy to do automated entry. Basically, it achieves orthogonality by the use of virtual accounts. I'm still not entirely happy because it still pretends that "budgeting" means actually moving assets. But BeanCount will afaik never have virtual accounts, so that doesn't really matter anyway.

However, I've come to believe that doing this type of budgeting by using (virtual) accounts is a dirty hack borne from the combination of desires to have
A) budgets in-line in the bookkeeping, and
B) everything fit the "pure" double-entry-accounting format.
Because of desire B, it's impossible to achieve true orthogonality without doubling the data-entry, because we need to use an entirely separate set of accounts to do the budgeting. I believe this is unnecessary.
"This type of budgeting is easily done using a spreadsheet" is a retort common, at least in GnuCash circles, to the desire of doing it in-line in the bookkeeping. And this is true, but it makes it unnecessarily hard to actually do the budgeting, because now you manually have to keep track of what transactions affect which budgets, etc. But it does tell us something about the nature of these budgets: their raison d'être is to limit expenses to real accounts.

Looking what an envelope budget actually budgets for, it's real expenses (and, in my case, transfers out of the "volatile assets" category to "long-term assets"). I believe it's entirely reasonable to say that the tree of real accounts is always at least as granular as the envelope budget. There's been some talk about "constraints" on (expense) accounts (https://groups.google.com/d/msg/beancount/kQMPTY5Q4ko/49hbQdyKCgAJ) and I also believe this is the way to go. It correctly captures the orthogonality of envelope budgeting without moving the money around in assets: it's only putting limits on the expenses. There's already the custom "budget" command, why not try prototyping a custom "constraint" command?

Following is a list of semantics I'm thinking of for an initial prototype. I'm basing the reasoning of envelope budgeting, but I believe it may be useful more generally.

1. It should be possible to set a constraint, overriding old constraints.
2. It should be possible to add to and subtract from a constraint, representing monthly / weekly / whateverly contributions to a large expected expense in the future. Semantically, this takes whatever is left at the end of the previous period, and sets a new constraint (leftovers + addition).
3. Every negative posting on a constrained account subtracts from the constraint.
4. Every positive posting on a constrained account adds to the constraint (e.g. voided transactions refill the budget).
5. Constraints on sub-accounts are added to constraints on higher-level accounts.
6. For an initial prototype, I don't think we need scheduling logic.
7. For an initial prototype, I don't think there would even have to be any true constraint logic (i.e. errors in bean-check and stuff like that); a simple report of the current constraint balance on an account would suffice.

Am I wrong in thinking that the only difference between this list and the current custom "budget" is point 2? (And 6, of course, because that scheduling logic already exists)

Additional semantics:
8. Optionally, the ability to mark asset- and equity-accounts as source for constraint-accounts and checking whether the equation (marked assets + marked equity = constraints) holds (i.e. implementing the "assign every asset" philosophy).

[polarmutex]

I am planning on taking on adding this feature to fava via extension. I am still in the early stages of the problem, but if you want to help and/or give thoughts to the problem i would take the help. Feel free to comment here or make an issue in my repo. I will try to update this issue on my progress

github repo

[polarmutex]

i just finished the initial prototype of this feature, would love comments/suggestions/contributions, see link in previous comment

[mateusrevoredo]

Hey @bryall this is pretty much the only feature missing for me to switch completely from YNAB to Beancount. I would love to help to get this released.

I've checked out the repo that you linked locally but I couldn't make it work with my sample data file that I generated.
I have zero experience with python but I've been a web developer for 9+ years and a YNAB user for roughly 6.

I ended up configuring fava and fava-envelope locally on PyCharm and I was able to debug and see the errors, but since the code is in a very preliminary stage with lots of blank TODOS all over. I didn't want to jump over and start trying to fix the code and end up designing things in a way that you did not intend to.

What's the best way to help?

[polarmutex]

@mateusrevoredo

Looking over most of the TODOs , many do not apply anymore. codebase needs to be cleaned up a bit

The plugin works for my beancount files, so you may be hitting some edge cases. Make sure you have a start date and budget accounts defined. I know the plugin will not load if there are no transactions after the start date.

Feel free to submit issues/pull requests to fix/improve the plugin. Or even subit issue to discuss direction of the plugin or how you want it to run. I coded this because I wanted this feature but there might be better ways to it or features I am not thinking of.

My next planned future additions are as follows:

• Include example beancount journal with pictures of the GUI
• write tests to help maintain plugin

As for my ways to help is documenting setup and checking for error condition to make sure the plugin always loads. Not sure if there is a way to report errors in fava.

[scauligi]

Contributing my solution to this as well.

It assumes a 1:1 correspondence between expense accounts and budget categories, and allows you to (re)budget by
adding explicit transactions transferring money between expense accounts; a plugin automatically applies tags to
these transactions so they can be easily filtered out for reports.