136 lines
5.0 KiB
Markdown
136 lines
5.0 KiB
Markdown
|
# FireflyService III AI categorization
|
|||
|
|
|||
|
This project allows you to automatically categorize your expenses by using OpenAI.
|
|||
|
|
|||
|
It provides a webhook that you can set up to be called every time a new expense is added.
|
|||
|
|
|||
|
It will then generate a prompt for OpenAI, including your existing categories, the recipient and the description of the
|
|||
|
transaction.
|
|||
|
|
|||
|
OpenAI will, based on that prompt, guess the category for the transaction.
|
|||
|
|
|||
|
If it is one of your existing categories, the tool will set the category on the transaction and also add a tag to the
|
|||
|
transaction.
|
|||
|
|
|||
|
If it cannot detect the category, it will not update anything.
|
|||
|
|
|||
|
## Installation
|
|||
|
|
|||
|
### 1. Get a Firefly Personal Access Token
|
|||
|
|
|||
|
You can generate your own Personal Access Token on the Profile page. Login to your Firefly III instance, go to
|
|||
|
"Options" > "Profile" > "OAuth" and find "Personal Access Tokens". Create a new Personal Access Token by clicking on
|
|||
|
"Create New Token". Give it a recognizable name and press "Create". The Personal Access Token is pretty long. Use a tool
|
|||
|
like Notepad++ or Visual Studio Code to copy-and-paste it.
|
|||
|
|
|||
|
![Step 1](docs/img/pat1.png)
|
|||
|
![Step 2](docs/img/pat2.png)
|
|||
|
![Step 3](docs/img/pat3.png)
|
|||
|
|
|||
|
### 2. Get an OpenAI API Key
|
|||
|
|
|||
|
The project needs to be configured with your OpenAI account's secret key.
|
|||
|
|
|||
|
- Sign up for an account by going to the OpenAI website (https://platform.openai.com)
|
|||
|
- Once an account is created, visit the API keys page at https://platform.openai.com/account/api-keys.
|
|||
|
- Create a new key by clicking the "Create new secret key" button.
|
|||
|
|
|||
|
When an API key is created you'll be able to copy the secret key and use it.
|
|||
|
|
|||
|
![OpenAI screenshot](docs/img/openai-key.png)
|
|||
|
|
|||
|
Note: OpenAI currently provides 18$ free credits for 3 months which is great since you won’t have to provide your
|
|||
|
payment details to begin interacting with the API for the first time.
|
|||
|
|
|||
|
### 3. Start the application via Docker
|
|||
|
|
|||
|
#### 3.1 Docker Compose
|
|||
|
|
|||
|
Create a new file `docker-compose.yml` with this content (or add to existing docker-compose file):
|
|||
|
|
|||
|
```yaml
|
|||
|
version: '3.3'
|
|||
|
|
|||
|
services:
|
|||
|
categorizer:
|
|||
|
image: bahuma20/firefly-iii-ai-categorize:latest
|
|||
|
restart: always
|
|||
|
ports:
|
|||
|
- "3000:3000"
|
|||
|
environment:
|
|||
|
FIREFLY_URL: "https://firefly.example.com"
|
|||
|
FIREFLY_PERSONAL_TOKEN: "eyabc123..."
|
|||
|
OPENAI_API_KEY: "sk-abc123..."
|
|||
|
```
|
|||
|
|
|||
|
Make sure to set the environment variables correctly.
|
|||
|
|
|||
|
Run `docker-compose up -d`.
|
|||
|
|
|||
|
Now the application is running and accessible at port 3000.
|
|||
|
|
|||
|
#### 3.2 Manually via Docker
|
|||
|
|
|||
|
Run this Docker command to start the application container. Edit the environment variables to match the credentials
|
|||
|
created before.
|
|||
|
|
|||
|
```shell
|
|||
|
docker run -d \
|
|||
|
-p 3000:3000 \
|
|||
|
-e FIREFLY_URL=https://firefly.example.com \
|
|||
|
-e FIREFLY_PERSONAL_TOKEN=eyabc123... \
|
|||
|
-e OPENAI_API_KEY=sk-abc123... \
|
|||
|
bahuma20/firefly-iii-ai-categorize:latest
|
|||
|
```
|
|||
|
|
|||
|
### 4. Set up the webhook
|
|||
|
|
|||
|
After starting your container, you have to set up the webhook in Firefly that will automatically trigger the
|
|||
|
categorization everytime a new transaction comes in.
|
|||
|
|
|||
|
- Login to your Firefly instance
|
|||
|
- In the sidebar go to "Automation" > "Webhooks"
|
|||
|
- Click "Create new webhook"
|
|||
|
- Give the webhook a title. For example "AI Categorizer"
|
|||
|
- Set "Trigger" to "After transaction creation" (should be the default)
|
|||
|
- Set "Response" to "Transaction details" (should be the default)
|
|||
|
- Set "Delivery" to "JSON" (should be the default)
|
|||
|
- Set "URL" to the URL where the application is reachable + "/webhook". For example if you are using docker-compose your
|
|||
|
URL could look like this: `http://categorizer:3000/webhook`
|
|||
|
- Click "Submit"
|
|||
|
|
|||
|
![Step 1](docs/img/webhook1.png)
|
|||
|
![Step 2](docs/img/webhook2.png)
|
|||
|
![Step 3](docs/img/webhook3.png)
|
|||
|
|
|||
|
Now you are ready and every new withdrawal transaction should be automatically categorized by OpenAI.
|
|||
|
|
|||
|
## User Interface
|
|||
|
|
|||
|
The application comes with a minimal UI that allows you to monitor the classification queue and see the OpenAI prompts
|
|||
|
and responses. This UI is disabled by default.
|
|||
|
|
|||
|
To enable this UI set the environment variable `ENABLE_UI` to `true`.
|
|||
|
|
|||
|
After a restart of the application the UI can be accessed at `http://localhost:3000/` (or any other URL that allows you
|
|||
|
to reach the container).
|
|||
|
|
|||
|
## Adjust Tag name
|
|||
|
|
|||
|
The application automatically sets the tag "AI categorized" on every transaction that was processed and a category could
|
|||
|
be guessed.
|
|||
|
|
|||
|
You can configure the name of this tag by setting the environment variable `FIREFLY_TAG` accordingly.
|
|||
|
|
|||
|
## Running on a different port
|
|||
|
|
|||
|
If you have to run the application on a different port than the default port `3000` set the environment variable `PORT`.
|
|||
|
|
|||
|
## Full list of environment variables
|
|||
|
|
|||
|
- `FIREFLY_URL`: The URL to your Firefly III instance. Example: `https://firefly.example.com`. (required)
|
|||
|
- `FIREFLY_PERSONAL_TOKEN`: A Firefly III Personal Access Token. (required)
|
|||
|
- `OPENAI_API_KEY`: The OpenAI API Key to authenticate against OpenAI. (required)
|
|||
|
- `ENABLE_UI`: If the user interface should be enabled. (Default: `false`)
|
|||
|
- `FIREFLY_TAG`: The tag to assign to the processed transactions. (Default: `AI categorized`)
|
|||
|
- `PORT`: The port where the application listens. (Default: `3000`)
|