Metadata-Version: 2.4
Name: clario
Version: 0.1.1
Summary: Turn messy bank transaction exports into clean, explainable double-entry ledgers
Author-email: Benyamin <benyaminreiazifar@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/Antares-XB/clario
Project-URL: Issues, https://github.com/Antares-XB/clario/issues
Keywords: accounting,bookkeeping,ledger,cli,finance,claude
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business :: Financial :: Accounting
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.1
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.0
Provides-Extra: ai
Requires-Dist: anthropic>=0.34.0; extra == "ai"
Provides-Extra: dev
Requires-Dist: pytest>=7.4; extra == "dev"
Requires-Dist: pytest-cov>=4.1; extra == "dev"
Requires-Dist: ruff>=0.4; extra == "dev"
Requires-Dist: anthropic>=0.34.0; extra == "dev"
Dynamic: license-file

# clario

[![CI](https://github.com/Antares-XB/clario/actions/workflows/ci.yml/badge.svg)](https://github.com/Antares-XB/clario/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Python 3.9+](https://img.shields.io/badge/python-3.9%2B-blue.svg)](pyproject.toml)

Turn a messy bank transaction export into a clean, **explainable**
double-entry ledger — from the command line, in one step.

Personal finance tools either make you categorize every transaction by hand,
or hide the categorization behind an opaque "smart" algorithm you can't
inspect. clario takes a middle path: a transparent rule engine handles the
transactions you'd recognize instantly (rent, coffee, your paycheck), and an
optional Claude-powered fallback handles the rest — while always telling you
*why* it picked an account, so you can correct it and improve your rules
over time.

## Features

- **Deterministic first.** A small, editable YAML rule file does most of the
  work — no API calls, no surprises, fully offline.
- **Explainable AI fallback.** Pass `--use-ai` and clario asks Claude to
  categorize anything the rules missed, along with a one-sentence reason —
  it's a suggestion you can review, not a black box.
- **Plain-text, portable output.** Ledgers are written in a simple
  beancount/ledger-style double-entry format that's easy to read, diff, and
  version-control.
- **Spending reports.** `clario report` gives you per-category totals
  without needing to write a ledger file at all.
- **No lock-in.** No database, no account, no cloud sync — it reads a CSV
  and writes a text file.

## Installation

```bash
pip install clario
```

To use the `--use-ai` fallback, install the optional extra:

```bash
pip install "clario[ai]"
export ANTHROPIC_API_KEY="your-key-here"
```

(Or clone the repo and run `pip install -e ".[dev]"` for local development —
see [CONTRIBUTING.md](CONTRIBUTING.md).)

## Quickstart

Given a CSV export with `date`, `description`, and `amount` columns:

```csv
date,description,amount
2024-01-02,Whole Foods Market,-86.42
2024-01-05,Payroll Deposit,2450.00
2024-01-10,Monthly Rent Payment,-1200.00
```

Convert it to a ledger:

```bash
clario convert transactions.csv --output ledger.beancount
```

```
2024-01-02 * "Whole Foods Market"
  Assets:Checking                -86.42
  Expenses:Food:Groceries        86.42

2024-01-05 * "Payroll Deposit"
  Assets:Checking                2450.00
  Income:Salary                  -2450.00

2024-01-10 * "Monthly Rent Payment"
  Assets:Checking                -1200.00
  Expenses:Housing:Rent          1200.00
```

Or just see where your money went:

```bash
clario report transactions.csv
```

```
               Spending by category
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━┓
┃ Category                    ┃    Total ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━┩
│ Expenses:Food:Groceries     │   -86.42 │
│ Expenses:Housing:Rent       │ -1200.00 │
│ Income:Salary               │  2450.00 │
└──────────────────────────────┴──────────┘
```

Anything the default rules can't place falls into
`Expenses:Uncategorized`. Add a rule for it, or re-run with `--use-ai` to
have Claude suggest one:

```bash
clario convert transactions.csv --use-ai --output ledger.beancount
```

## Custom rules

Rules live in a plain YAML file — copy
[`examples/custom_rules.yaml`](examples/custom_rules.yaml) as a starting
point:

```yaml
- match: "trader joe"
  account: "Expenses:Food:Groceries"
- match: "shell|chevron|exxon"
  account: "Expenses:Transport:Fuel"
  regex: true
```

Rules are checked top to bottom; the first match wins. Use `regex: true`
when a plain substring match isn't enough.

```bash
clario convert transactions.csv --rules my_rules.yaml
```

## How categorization works

```mermaid
flowchart LR
    A[CSV transactions] --> B{Rule engine match?}
    B -- yes --> D[Assign account from rule]
    B -- no --> C{--use-ai set?}
    C -- yes --> E[Ask Claude for account + reasoning]
    C -- no --> F[Leave Uncategorized]
    D --> G[Render ledger]
    E --> G
    F --> G
```

The rule engine always runs first because it's free, instant, and fully
deterministic. Claude is only consulted for what's left over, and every
AI-suggested account is written into the ledger as a comment explaining the
reasoning, so nothing is categorized silently.

## Command reference

| Command | Description |
|---|---|
| `clario convert CSV_PATH` | Convert a CSV into a double-entry ledger. |
| `clario report CSV_PATH` | Print spending totals per category. |

Run `clario convert --help` or `clario report --help` for the full list of
options (`--output`, `--rules`, `--account`, `--use-ai`, `--model`,
`--api-key`).

## Development

```bash
git clone https://github.com/Antares-XB/clario.git
cd clario
pip install -e ".[dev]"
pytest --cov=clario --cov-report=term-missing
ruff check .
```

See [CONTRIBUTING.md](CONTRIBUTING.md) for details on the project layout
and how to add new default rules.

## Project layout

```
src/clario/
├── transactions.py   # CSV parsing into Transaction objects
├── rules.py           # Keyword/regex rule engine
├── claude_client.py    # Optional Claude-powered categorizer
├── categorizer.py     # Combines rules + AI, tracks match stats
├── ledger.py           # Double-entry rendering and category summaries
└── cli.py              # `clario convert` / `clario report` commands
```

## License

[MIT](LICENSE)
