Metadata-Version: 2.4
Name: beancount_blue
Version: 1.0.3
Summary: Set of useful plugins and extensions for Beancount and Fava.
Author-email: Mark Scannell <mescanne@gmail.com>
Project-URL: Homepage, https://mescanne.github.io/beancount-blue/
Project-URL: Repository, https://github.com/mescanne/beancount-blue
Project-URL: Documentation, https://mescanne.github.io/beancount-blue/
Keywords: python
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: <4.0,>=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: authlib>=1.4.1
Requires-Dist: beancount
Requires-Dist: beangulp>=0.2.0
Requires-Dist: fava>=1.30.13
Requires-Dist: httpx>=0.28.1
Requires-Dist: idna>=3.15
Requires-Dist: pydantic>=2.12.4
Requires-Dist: pydantic-settings
Requires-Dist: pymonzo>=2.2.1
Requires-Dist: python-dateutil
Requires-Dist: pyyaml>=6.0.2
Requires-Dist: joblib>=1.3.0
Requires-Dist: numpy>=1.26.0
Requires-Dist: scikit-learn>=1.4.0
Dynamic: license-file

# beancount-blue

[![Release](https://img.shields.io/github/v/release/mescanne/beancount-blue)](https://img.shields.io/github/v/release/mescanne/beancount-blue)
[![Build status](https://img.shields.io/github/actions/workflow/status/mescanne/beancount-blue/main.yml?branch=main)](https://github.com/mescanne/beancount-blue/actions/workflows/main.yml?query=branch%3Amain)
[![Commit activity](https://img.shields.io/github/commit-activity/m/mescanne/beancount-blue)](https://img.shields.io/github/commit-activity/m/mescanne/beancount-blue)

- **Github repository**: <https://github.com/mescanne/beancount-blue/>
- **Documentation** <https://mescanne.github.io/beancount-blue/>

`beancount-blue` is a collection of plugins for the [Beancount](https://beancount.github.io/docs/) plaintext accounting tool. These plugins provide additional functionality to help automate and streamline your bookkeeping.

## Plugins

This collection currently includes the following plugins:

- **[Amortize](https://mescanne.github.io/beancount-blue/modules/#beancount_blue.amortize)**: Amortize expenses over a specific period. For example, if you pay for a yearly subscription, you can use this plugin to spread the cost over 12 months.
- **[Tag](https://mescanne.github.io/beancount-blue/modules/#beancount_blue.tag)**: Automatically add tags to transactions based on the accounts they involve. This can help with tracking and reporting on specific categories of income or expenses.
- **[UK Capital Gains](https://mescanne.github.io/beancount-blue/modules/#beancount_blue.calc_gains)**: A flexible capital gains calculator that can be configured to handle different tax regulations.
- **[Clear Residual Lots](https://mescanne.github.io/beancount-blue/modules/#beancount_blue.clear_residual_lots)**: Automatically clear out small, leftover lots in investment accounts that can occur when using the `NONE` booking method. This helps keep your books clean and accurate.

## Importers & ML Prediction

This package also includes a native API importer framework for syncing transactions from real-world banks and APIs (Monzo, Starling, and TrueLayer). It features a built-in **Machine Learning Predictor** that leverages a scikit-learn Logistic Regression classifier (`SGDClassifier`) to automatically learn from your existing Beancount ledger and predict the correct counter-accounts and payees for new transactions.

See the [Importers Documentation](https://mescanne.github.io/beancount-blue/importer/) for detailed instructions on configuring the ML predictor, CLI usage, and specific bank implementations.

## Installation

To use these plugins, you first need to install this package:

```bash
pip install beancount-blue
```

Then, you can enable the plugins in your Beancount file by adding a line like this:

```beancount
plugin "beancount_blue.amortize" "{...}"
```

For more detailed instructions and configuration options, please see the [documentation](https://mescanne.github.io/beancount-blue/).

## Contributing

Contributions are welcome! If you have an idea for a new plugin or an improvement to an existing one, please open an issue or submit a pull request. See the [contributing guidelines](CONTRIBUTING.md) for more information.
