Oikonomi
========

Oikonomi fetches your bank account transactions and transforms them to the
format understood by the ledger plaintext accounting tool. During the
transformation step, Oikonomi learns to which ledger accounts your recurring
transactions belong. Subsequent transactions can then be transformed
automatically without user input.

Oikonomi uses the python-fints library to retrieve your bank account
transactions. This probably means that it only works with German banks.
To classify transactions, tf-idf and cosine similarity are used.

Think of Oikonomi as yet another fints2ledger program.


Components
----------

Oikonomi is split into three separate programs:
  * oiko, a Python program that fetches back account transactions
    and prints them as s-expressions.
  * nomi, a Rust program that consumes said S-expressions and turns them
    the transaction format understood by ledger.
  * oikonomi, a shell script that calls oiko and feeds its output to nomi.
    If you wish to further massage the s-expressions, modify this wrapper
    script as necessary.


Dependencies
------------------

oiko depends on the `python-fints` library.
nomi requires the Rust compiler `rustc`.


Build/Installation
------------------

Run `make` to build nomi.
Run `make install` to install the oiko, nomi and oikonomi to /usr/local/bin.
Conventional support for the Make variables PREFIX and DESTDIR is provided.


Configuration
-------------

First, set up ~/.config/oikonomi/oiko.conf. That file contains a list of
`key = value` assignments. The known keys are:
  * url -- refers to http FinTS endpoint of your bank
  * bank_id -- your bank's Bankleitzahl (BLZ)
  * user_id -- the username used for authentication with the FinTS service

The values associated with these keys need to be given as unquoted strings.

For example, the config file used to access ING might look like this:

  url = https://fints.ing.de/fints/
  bank_id = 50010517
  user_id = your_personal_login_name

Next, set up ~/.config/oikonomi/nomi.conf. This file consists of a series
of s-expressions.

Put `(general (min_confidence 75))` to configure the threshold that needs to
be reached in order for a guessed accound match to be accepted (more details
about this below).

Put `(accounts (123 "Assets:Checking") (456 "Assets:Savings"))` to list
your bank account numbers and associate them with the names known in your
ledger setup.

Thus, the full nomi.conf might look like this:
```
(general
  (min_confidence 75))

(accounts
  (123 "Assets:Checking")
  (456 "Assets:Savings"))
```


Usage
-----

Run `oikonomi --from DATE` to fetch and process bank account transactions
from the date, given in YYYY-MM-DD format. When run in that mode,
oikonomi will attempt to guess which ledger account the transactions should
best be associated with. A guess will only be accepted if the confidence level
is at least as indicated by the `min_confidence` settings in nomi.conf.

To be able to make these guesses, you would first have to have trained
oikonomi with your ledger account setup.
To do so, run `oikonomi --from DATE --learn`.
In learn mode, if oikonomi cannot make a sufficient guess about a transaction,
it will prompt for you to enter the desired transaction's purpose, associated
ledger account and a comment.

Reacting to these prompts by hitting ctrl-d will make oikonomi not record
any information.

oikonomi attempts to distinguish more relevant from less relevant tokens
from the description/makeup of the transaction by using tf-idf.
The database of recognized tokens is stored in
~/.local/share/oikonomi/tokens
and the database of associated acccounts is stored in
~/.local/share/oikonomi/accounts.

You may want to backup these from time to time in case oikonomi
messes up the database based on your unindended choices.


Shortcomings
------------

oikonomi was written to scratch the author's own itches which means it may not
work for you very well.

In particular, oikonomi makes no attempt at avoiding processing the same
bank account transactions multiple times, meaning it does not record
which transactions it already has seen.
