Metadata-Version: 2.3
Name: fintl
Version: 0.1.3
Summary: Financial ETL CLI: parse, normalize, and explore your bank transaction data.
Keywords: finance,etl,banking,transactions,cli
Author: eschmidt42
Author-email: eschmidt42 <11818904+eschmidt42@users.noreply.github.com>
License: MIT
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business :: Financial
Requires-Dist: aiohttp>=3.13.4
Requires-Dist: altair>=6.0.0
Requires-Dist: beautifulsoup4>=4.14.3
Requires-Dist: chardet>=7.3.0
Requires-Dist: httpx>=0.28.1
Requires-Dist: instructor>=1.14.5
Requires-Dist: polars>=1.39.3
Requires-Dist: pydantic>=2.12.5
Requires-Dist: pydantic-settings>=2.13.1
Requires-Dist: python-dateutil>=2.9.0.post0
Requires-Dist: rich>=14.3.3
Requires-Dist: textual>=8.1.1
Requires-Dist: xlsxwriter>=3.2.9
Requires-Python: >=3.13
Project-URL: Homepage, https://github.com/eschmidt42/fintl
Project-URL: Repository, https://github.com/eschmidt42/fintl
Project-URL: Issues, https://github.com/eschmidt42/fintl/issues
Description-Content-Type: text/markdown

# `fintl`

[![CI](https://github.com/eschmidt42/fintl/actions/workflows/ci.yml/badge.svg)](https://github.com/eschmidt42/fintl/actions/workflows/ci.yml)
[![codecov](https://codecov.io/gh/eschmidt42/fintl/branch/main/graph/badge.svg?token=FM1L1A7BQ8)](https://codecov.io/gh/eschmidt42/fintl)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.13+](https://img.shields.io/badge/python-3.13+-blue.svg)](https://www.python.org/)
[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
[![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv)
[![ty](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ty/main/assets/badge/v0.json)](https://github.com/astral-sh/ty)

> Financial ETL CLI: parse, normalize, and explore your bank transaction data.

## TL;DR

This tool helps you process, visualize and search your balance and transaction information that you have exported from your bank accounts.

Currently supports DKB, Postbank, GLS and Scalable Capital Broker.

Supported file formats: CSV, HTML, and PNG. PNG parsing uses a local [ollama](https://ollama.com) instance with a multimodal model — opt-in via `fintl.toml` (required only for Scalable broker PNG statements; gracefully skipped when not configured).

**All your data stays on your machine. No need to trust another entity that is PSD2 certified.**

## How to install

### As a cli tool

```bash
uv tool install fintl
```

### As a dependency

From pypi

```bash
pip install fintl
```

or

```bash
uv add fintl
```

From a local repo

```bash
git clone https://github.com/eschmidt42/fintl.git
cd fintl
uv sync
uv tool install .
```

After installation, `fintl` should be available on your `PATH`:

```bash
which fintl
# e.g. /Users/YOURUSER/.local/bin/fintl
```

## How to use

1. Configure your `~/.config/petprojects/fintl.toml`. For details see [here](./src/fintl/cli/README.md#fintltoml).
2. Go to your bank account.
3. Select your service, e.g. Giro.
4. Export csv file or similar to `~/Downloads`, or directly your source dir for your bank / service.
5. Optionally, if you've stored your file in `~/Downloads`, run `cd ~/Downloads` followed by `fintl store` (uses your `fintl.toml` from step 1).
6. Optionally, if you want to process PNG screenshots via Ollama, start Ollama.
7. Run the etl via `fintl etl` (also uses your `fintl.toml` from step 1).
8. Upon success visualize / search your data via `fintl plot` or `fintl search`.

[Please see here and below](./src/fintl/cli/README.md#top-level-usage) for more usage details.

## Repo structure

* `src/fintl/accounts_etl/` — core ETL logic: schemas, parsers, registry, runner
* `src/fintl/cli/` — CLI entry point and subcommands (`etl`, `store`, `search`, `plot`)
* `tests/` — tests for packages of this repo

## Development

Run tests:

```bash
uv run pytest -n auto tests
```

Type check:

```bash
uv run ty check src
```

Lint, format, type check, test and all the other good stuff:

```bash
prek run --all-files
```

### Running Ollama integration tests

Tests that require a live Ollama instance are marked `ollama` and skipped by default. To run them, set `FINTL_OLLAMA_MODEL` to the name of a multimodal model you have pulled (e.g. `qwen3.5:27b`) and pass `-m ollama`:

```bash
FINTL_OLLAMA_MODEL=qwen3.5:27b uv run pytest -m ollama tests/
```

`FINTL_OLLAMA_BASE_URL` can optionally override the default `http://localhost:11434/v1`.

### Simulating CLI usage without real financial data

Set the `FINTL_CONFIG` env var to point at any TOML file instead of `~/.config/petprojects/fintl.toml`. A `dev-config.toml` is included at the repo root and wires all CLI commands to the fixture files under `tests/`.

To try the CLI commands, run:

```bash
mkdir /tmp/fintl-dev
```

Then you can run one of

```bash
rm -fr /tmp/fintl-dev/*
FINTL_CONFIG=dev-config.toml fintl etl
FINTL_CONFIG=dev-config.toml fintl plot
FINTL_CONFIG=dev-config.toml fintl store --from-dir <dir> --yes --copy
```

Output lands in `/tmp/fintl-dev`. Edit `dev-config.toml` locally to change providers, paths, or target directory.

Note: `FINTL_CONFIG=dev-config.toml fintl etl` is expected to produce one warning, failing to parse `Screenshot 2026-03-09 at 14.30.54.png`, because it in fact is an insufficient png file to parse the requested information from.

## Release

For release steps see [here](./docs/releases.md).
