Firefly III LLM Categorizer

✨ An intelligent automation script that categorizes and assigns destination accounts to your Firefly III transactions using OpenAI.

Features

• 🤖 AI-Powered: Uses OpenAI's LLMs to analyze transaction descriptions and determine the appropriate Expense Account or Category.
• 📚 Self-Learning Rules: Automatically creates and saves rules in a local JSON file based on AI decisions. Future transactions from the same merchant are processed locally without querying the AI, saving costs and time.
• ⚡ Batch Processing: Processes transactions in batches to optimize API usage.
• 🔍 Web Search Capable: Can optionally use SearxNG to search the web for obscure merchant names to make better decisions.
• 🧹 Data Normalization: Automatically cleans up transaction descriptions (removing prefixes like "PAYPAL *", "Stripe *", etc.) before processing.

Requirements & Limitations

• Platform: Linux
• AI Provider: Currently, only OpenAI is supported.
• Firefly III: A running instance of Firefly III.

Installation

1. Clone the repository

git clone https://github.com/constLiakos/Firefly-III-LLM-Categorizer
cd Firefly-III-LLM-Categorizer

2. Set up a virtual environment

It is recommended to use a virtual environment.

python3 -m venv venv
source venv/bin/activate

3. Install dependencies

pip install requests python-dotenv pydantic pydantic-settings langchain-openai langchain langchain-community langgraph jinja2

⚙️ Configuration

1. Copy the example environment file to create your production configuration:

   cp .env.example .env

2. Open .env and fill in your details.

🚀 How to Run

The source code is located in the src folder. You can run the script using the command line arguments below.

Basic Usage

To run the script, use python targeting the script file:

python src/main.py [options]

(Note: Replace main.py with the actual name of your python file if different).

Command Line Arguments

Argument	Description
--limit <number>	Limit the number of transactions to process (0 for unlimited).
--use-llm	Enable OpenAI processing for transactions not found in local rules.
--set-accounts	Attempt to resolve and assign missing destination accounts.
--set-categories	Attempt to resolve and assign missing categories.

Examples

1. Assign accounts using OpenAI, limited to 20 transactions:

python src/main.py --set-accounts --use-llm --limit 20

2. Assign both accounts and categories using OpenAI:

python src/main.py --set-accounts --set-categories --use-llm

3. Run using only existing local rules (no AI cost):

python src/main.py --set-accounts --set-categories

The Rules System

This tool aims to reduce AI costs over time.

1. Storage: Rules are stored in rules/rules.json.
2. Creation: When the LLM successfully categorizes a transaction, a new rule is written to this file mapping the normalized description to the specific Account or Category.
3. Execution: On subsequent runs, the script checks rules.json first. If a match is found, the update is applied locally, bypassing the OpenAI API call.

📄 License

This project is licensed under the MIT License.