avenir-mcp 0.1.0__tar.gz

avenir_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mathieu Beal
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

avenir_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,142 @@
+Metadata-Version: 2.4
+Name: avenir-mcp
+Version: 0.1.0
+Summary: An unofficial MCP server for YNAB: budgets, spending and transaction classification, built for agents.
+Author: Mathieu Beal
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/mathbeal/avenir-mcp
+Project-URL: Documentation, https://mathbeal.github.io/avenir-mcp/
+Project-URL: Repository, https://github.com/mathbeal/avenir-mcp
+Project-URL: Issues, https://github.com/mathbeal/avenir-mcp/issues
+Project-URL: Changelog, https://github.com/mathbeal/avenir-mcp/blob/main/CHANGELOG.md
+Keywords: mcp,model-context-protocol,ynab,budget,personal-finance,agents
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: OS Independent
+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 :: Office/Business :: Financial
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastmcp==4.0.9
+Requires-Dist: httpx<1,>=0.28.1
+Requires-Dist: pydantic<3,>=2.13
+Requires-Dist: mcp<3,>=2.2.0
+Requires-Dist: mcp-types<3,>=2.2.0
+Requires-Dist: starlette<2,>=1.7.0
+Dynamic: license-file
+
+# avenir-mcp — an unofficial MCP server for YNAB
+
+[![quality](https://github.com/mathbeal/avenir-mcp/actions/workflows/quality.yml/badge.svg)](https://github.com/mathbeal/avenir-mcp/actions/workflows/quality.yml)
+[![MCP Inspector](https://github.com/mathbeal/avenir-mcp/actions/workflows/inspector.yml/badge.svg)](https://github.com/mathbeal/avenir-mcp/actions/workflows/inspector.yml)
+[![docs](https://github.com/mathbeal/avenir-mcp/actions/workflows/docs.yml/badge.svg)](https://mathbeal.github.io/avenir-mcp/)
+
+[![python](https://img.shields.io/badge/python-3.12%20%7C%203.13%20%7C%203.14-blue)](https://mathbeal.github.io/avenir-mcp/project/development/#the-checks)
+[![coverage](https://img.shields.io/badge/coverage-100%25%20lines%20and%20branches-brightgreen)](https://mathbeal.github.io/avenir-mcp/project/development/#the-checks)
+[![types](https://img.shields.io/badge/types-mypy%20strict-blue)](https://mathbeal.github.io/avenir-mcp/project/development/#the-checks)
+[![docstrings](https://img.shields.io/badge/docstrings-Google%20style%2C%20ruff-blue)](https://mathbeal.github.io/avenir-mcp/project/development/#the-checks)
+[![code style](https://img.shields.io/badge/code%20style-black-000000)](https://mathbeal.github.io/avenir-mcp/project/development/#the-checks)
+[![licence](https://img.shields.io/badge/licence-MIT-blue)](https://github.com/mathbeal/avenir-mcp/blob/main/LICENSE)
+
+> 🇬🇧 **avenir-mcp** (*avenir* is French for *the future*) lets an AI agent read your YNAB budget
+> and help you plan what comes next.
+>
+> 🇫🇷 **avenir-mcp** permet à un agent IA de lire votre budget YNAB et de vous aider
+> à préparer la suite.
+
+Ask Claude — or any [MCP](https://modelcontextprotocol.io) client — about your budget
+in plain words: where the money went, what still needs a category, whether an account
+matches the bank, when money would run out. Every change is previewed, confirmed by
+you, and can be undone.
+
+**📖 Documentation: <https://mathbeal.github.io/avenir-mcp/>**
+
+> **Unofficial project.** We are not affiliated, associated, or in any way officially
+> connected with YNAB or any of its subsidiaries or affiliates. YNAB and You Need A Budget
+> are registered trademarks of YNAB, named here only to say which service avenir-mcp works
+> with.
+>
+> avenir-mcp is for **personal use on your own machine, with your own YNAB token**. Running it
+> as a public or shared server is not supported. It is provided as is, without warranty,
+> and is not financial advice: you remain responsible for the changes you confirm. See the
+> [legal notice](https://mathbeal.github.io/avenir-mcp/project/legal/).
+
+## Why avenir-mcp
+
+- **Tools for tasks, not endpoints.** Classify a month of transactions, reconcile an
+  account, forecast your balance: one tool each, not a wrapper of YNAB's API.
+- **Read-only by default.** Tools that change your budget exist only when you enable
+  them.
+- **Preview, confirm, undo.** Every write shows what will change and waits for your
+  yes; `undo_operation` reverts it.
+- **Answers an agent can read.** Currency units, short typed answers, pagination,
+  errors that say what to fix, bank text treated as untrusted.
+- **Verified.** 100 % line and branch coverage, and an evaluation where a real agent
+  works on an invented plan: 17/17 tasks.
+
+## Install
+
+You need [uv](https://docs.astral.sh/uv/) and a YNAB personal access token
+(YNAB → Account Settings → Developer Settings → New Token).
+
+```bash
+# Claude Code
+claude mcp add avenir-mcp --env YNAB_API_KEY=your-token --env AVENIR_MCP_WRITE=1 -- uvx avenir-mcp
+```
+
+```jsonc
+// Claude Desktop, Cursor: the mcpServers block of the client's configuration
+{
+  "mcpServers": {
+    "avenir-mcp": {
+      "command": "uvx",
+      "args": ["avenir-mcp"],
+      "env": { "YNAB_API_KEY": "your-token", "AVENIR_MCP_WRITE": "1" }
+    }
+  }
+}
+```
+
+Drop `AVENIR_MCP_WRITE` to stay read-only. Other clients and every option:
+[Install](https://mathbeal.github.io/avenir-mcp/getting-started/install/) ·
+[Configuration](https://mathbeal.github.io/avenir-mcp/reference/configuration/).
+
+## What you can ask
+
+| You ask | avenir-mcp |
+|---|---|
+| "Which category is overspent this month?" | `get_monthly_summary` — totals and overspent categories |
+| "Categorise what is pending." | `suggest_categories`, then `apply_categories` after your yes |
+| "Split this receipt: 81.15 groceries, 5.25 household." | `split_transaction` — one transaction across categories, after your yes |
+| "Which transaction is my 86.40 receipt from the 12th?" | `find_transactions` — by dates, exact amount and account, categorised or not |
+| "My bank shows 3,440.80. Does YNAB agree?" | `reconcile_account` — explains the gap, changes nothing until it matches |
+| "Will I go below zero before December?" | `forecast_balance` — month by month, with its assumptions |
+| "Move 30 from Tennis to Restaurants." | `set_category_budget`, previewed and undoable |
+| "Undo that." | `undo_operation` |
+
+Walk-throughs with real answers: [Use cases](https://mathbeal.github.io/avenir-mcp/use-cases/classify/).
+Every tool, resource and prompt: [Reference](https://mathbeal.github.io/avenir-mcp/reference/tools/).
+
+## Development
+
+```bash
+git clone https://github.com/mathbeal/avenir-mcp && cd avenir-mcp
+uv sync
+just check        # lint, types, tests at 100 % coverage, vocabulary, lockfile
+just docs-serve   # the documentation, live
+just evaluate     # a real agent on the demo budget (uses your Claude plan)
+```
+
+Read [AGENTS.md](AGENTS.md) and [CONTRIBUTING.md](CONTRIBUTING.md) before opening a
+pull request. Security reports: [SECURITY.md](SECURITY.md).
+
+## Licence
+
+MIT.

avenir_mcp-0.1.0/README.md

@@ -0,0 +1,108 @@
+# avenir-mcp — an unofficial MCP server for YNAB
+
+[![quality](https://github.com/mathbeal/avenir-mcp/actions/workflows/quality.yml/badge.svg)](https://github.com/mathbeal/avenir-mcp/actions/workflows/quality.yml)
+[![MCP Inspector](https://github.com/mathbeal/avenir-mcp/actions/workflows/inspector.yml/badge.svg)](https://github.com/mathbeal/avenir-mcp/actions/workflows/inspector.yml)
+[![docs](https://github.com/mathbeal/avenir-mcp/actions/workflows/docs.yml/badge.svg)](https://mathbeal.github.io/avenir-mcp/)
+
+[![python](https://img.shields.io/badge/python-3.12%20%7C%203.13%20%7C%203.14-blue)](https://mathbeal.github.io/avenir-mcp/project/development/#the-checks)
+[![coverage](https://img.shields.io/badge/coverage-100%25%20lines%20and%20branches-brightgreen)](https://mathbeal.github.io/avenir-mcp/project/development/#the-checks)
+[![types](https://img.shields.io/badge/types-mypy%20strict-blue)](https://mathbeal.github.io/avenir-mcp/project/development/#the-checks)
+[![docstrings](https://img.shields.io/badge/docstrings-Google%20style%2C%20ruff-blue)](https://mathbeal.github.io/avenir-mcp/project/development/#the-checks)
+[![code style](https://img.shields.io/badge/code%20style-black-000000)](https://mathbeal.github.io/avenir-mcp/project/development/#the-checks)
+[![licence](https://img.shields.io/badge/licence-MIT-blue)](https://github.com/mathbeal/avenir-mcp/blob/main/LICENSE)
+
+> 🇬🇧 **avenir-mcp** (*avenir* is French for *the future*) lets an AI agent read your YNAB budget
+> and help you plan what comes next.
+>
+> 🇫🇷 **avenir-mcp** permet à un agent IA de lire votre budget YNAB et de vous aider
+> à préparer la suite.
+
+Ask Claude — or any [MCP](https://modelcontextprotocol.io) client — about your budget
+in plain words: where the money went, what still needs a category, whether an account
+matches the bank, when money would run out. Every change is previewed, confirmed by
+you, and can be undone.
+
+**📖 Documentation: <https://mathbeal.github.io/avenir-mcp/>**
+
+> **Unofficial project.** We are not affiliated, associated, or in any way officially
+> connected with YNAB or any of its subsidiaries or affiliates. YNAB and You Need A Budget
+> are registered trademarks of YNAB, named here only to say which service avenir-mcp works
+> with.
+>
+> avenir-mcp is for **personal use on your own machine, with your own YNAB token**. Running it
+> as a public or shared server is not supported. It is provided as is, without warranty,
+> and is not financial advice: you remain responsible for the changes you confirm. See the
+> [legal notice](https://mathbeal.github.io/avenir-mcp/project/legal/).
+
+## Why avenir-mcp
+
+- **Tools for tasks, not endpoints.** Classify a month of transactions, reconcile an
+  account, forecast your balance: one tool each, not a wrapper of YNAB's API.
+- **Read-only by default.** Tools that change your budget exist only when you enable
+  them.
+- **Preview, confirm, undo.** Every write shows what will change and waits for your
+  yes; `undo_operation` reverts it.
+- **Answers an agent can read.** Currency units, short typed answers, pagination,
+  errors that say what to fix, bank text treated as untrusted.
+- **Verified.** 100 % line and branch coverage, and an evaluation where a real agent
+  works on an invented plan: 17/17 tasks.
+
+## Install
+
+You need [uv](https://docs.astral.sh/uv/) and a YNAB personal access token
+(YNAB → Account Settings → Developer Settings → New Token).
+
+```bash
+# Claude Code
+claude mcp add avenir-mcp --env YNAB_API_KEY=your-token --env AVENIR_MCP_WRITE=1 -- uvx avenir-mcp
+```
+
+```jsonc
+// Claude Desktop, Cursor: the mcpServers block of the client's configuration
+{
+  "mcpServers": {
+    "avenir-mcp": {
+      "command": "uvx",
+      "args": ["avenir-mcp"],
+      "env": { "YNAB_API_KEY": "your-token", "AVENIR_MCP_WRITE": "1" }
+    }
+  }
+}
+```
+
+Drop `AVENIR_MCP_WRITE` to stay read-only. Other clients and every option:
+[Install](https://mathbeal.github.io/avenir-mcp/getting-started/install/) ·
+[Configuration](https://mathbeal.github.io/avenir-mcp/reference/configuration/).
+
+## What you can ask
+
+| You ask | avenir-mcp |
+|---|---|
+| "Which category is overspent this month?" | `get_monthly_summary` — totals and overspent categories |
+| "Categorise what is pending." | `suggest_categories`, then `apply_categories` after your yes |
+| "Split this receipt: 81.15 groceries, 5.25 household." | `split_transaction` — one transaction across categories, after your yes |
+| "Which transaction is my 86.40 receipt from the 12th?" | `find_transactions` — by dates, exact amount and account, categorised or not |
+| "My bank shows 3,440.80. Does YNAB agree?" | `reconcile_account` — explains the gap, changes nothing until it matches |
+| "Will I go below zero before December?" | `forecast_balance` — month by month, with its assumptions |
+| "Move 30 from Tennis to Restaurants." | `set_category_budget`, previewed and undoable |
+| "Undo that." | `undo_operation` |
+
+Walk-throughs with real answers: [Use cases](https://mathbeal.github.io/avenir-mcp/use-cases/classify/).
+Every tool, resource and prompt: [Reference](https://mathbeal.github.io/avenir-mcp/reference/tools/).
+
+## Development
+
+```bash
+git clone https://github.com/mathbeal/avenir-mcp && cd avenir-mcp
+uv sync
+just check        # lint, types, tests at 100 % coverage, vocabulary, lockfile
+just docs-serve   # the documentation, live
+just evaluate     # a real agent on the demo budget (uses your Claude plan)
+```
+
+Read [AGENTS.md](AGENTS.md) and [CONTRIBUTING.md](CONTRIBUTING.md) before opening a
+pull request. Security reports: [SECURITY.md](SECURITY.md).
+
+## Licence
+
+MIT.

avenir_mcp-0.1.0/avenir_mcp/__init__.py

@@ -0,0 +1,3 @@
+"""avenir-mcp — an MCP server for YNAB, built for agents."""
+
+__version__ = "0.1.0"

avenir_mcp-0.1.0/avenir_mcp/__main__.py

@@ -0,0 +1,5 @@
+"""Allow `python -m avenir_mcp`."""
+
+from avenir_mcp.server import main
+
+main()

avenir_mcp-0.1.0/avenir_mcp/amounts.py

@@ -0,0 +1,20 @@
+"""Amounts an agent may pass: finite, and within what a household budget can hold."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+from pydantic import Field  # pylint: disable=import-error
+
+MAX_AMOUNT = 1_000_000_000
+
+Amount = Annotated[
+    float,
+    Field(
+        allow_inf_nan=False,
+        ge=-MAX_AMOUNT,
+        le=MAX_AMOUNT,
+        description="In currency units, negative for money out; at most a billion either way.",
+    ),
+]
+"""An amount in currency units, checked by the tool's argument schema before any call."""

avenir_mcp-0.1.0/avenir_mcp/analytics.py

@@ -0,0 +1,299 @@
+"""Financial analytics computed from YNAB data — pure functions, no I/O."""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from avenir_mcp import client
+from avenir_mcp.model import Model
+
+logger = logging.getLogger(__name__)
+
+
+class BudgetUsage(Model):
+    """How much of a category's budget was used in a month."""
+
+    id: str
+    """YNAB id of the category."""
+    name: str
+    """Category name."""
+    group: str
+    """Name of the category's group, e.g. Fun for Tennis."""
+    budgeted: float
+    """Amount assigned to the category this month."""
+    actual: float
+    """Amount spent this month, as a positive number."""
+    balance: float
+    """What is left: budgeted minus spent, plus what was carried over; negative when overspent."""
+    utilization_pct: float
+    """Spent as a share of budgeted, in percent; above 100 means overspent, 0 when nothing
+    is budgeted."""
+
+
+def budget_vs_actual(
+    month_categories: list[dict[str, Any]],
+) -> list[BudgetUsage]:
+    """Compute budget-vs-actual for each category in a given month.
+
+    Args:
+        month_categories: List of YNAB category dicts for a specific month,
+            each containing ``budgeted`` and ``activity`` in milliunits.
+
+    Returns:
+        One usage per usable category, amounts in currency units.
+
+    Examples:
+        >>> cat = {"id": "c1", "name": "Rent", "budgeted": 500000,
+        ...        "activity": -400000, "balance": 100000}
+        >>> budget_vs_actual([cat])[0].utilization_pct
+        80.0
+    """
+    results: list[BudgetUsage] = []
+    for cat in filter(_usable, month_categories):
+        budgeted_mu = cat.get("budgeted", 0)
+        activity_mu = cat.get("activity", 0)
+        balance_mu = cat.get("balance", 0)
+        budgeted = client.milliunit_to_amount(budgeted_mu)
+        actual = client.milliunit_to_amount(abs(activity_mu))
+        balance = client.milliunit_to_amount(balance_mu)
+
+        if budgeted_mu == 0:
+            utilization_pct = 0.0
+        else:
+            utilization_pct = round(actual / budgeted * 100, 1)
+
+        results.append(
+            BudgetUsage(
+                id=cat.get("id", ""),
+                name=cat.get("name", ""),
+                group=cat.get("category_group_name", ""),
+                budgeted=budgeted,
+                actual=actual,
+                balance=balance,
+                utilization_pct=utilization_pct,
+            )
+        )
+    return results
+
+
+class MonthSpending(Model):
+    """What a category spent in one month."""
+
+    month: str
+    """First day of the month, YYYY-MM-01."""
+    amount: float
+    """Amount spent, as a positive number in currency units."""
+
+
+def spending_trends(
+    months_data: list[tuple[str, list[dict[str, Any]]]],
+) -> dict[str, list[MonthSpending]]:
+    """Build a time-series of spending per category across multiple months.
+
+    Args:
+        months_data: List of ``(month_label, month_categories)`` tuples,
+            ordered chronologically.  Each element is a ``(str, list)`` pair
+            where the string is an ISO month label and the list is the output of
+            :func:`client.get_month_categories`.
+
+    Returns:
+        Dict mapping category name to its spending, month by month in chronological
+        order.
+
+    Examples:
+        >>> cats = [{"id": "c1", "name": "AWS", "budgeted": 0, "activity": -100000, "balance": 0}]
+        >>> spending_trends([("2026-01-01", cats)])["AWS"]
+        [MonthSpending(month='2026-01-01', amount=100.0)]
+    """
+    trends: dict[str, list[MonthSpending]] = {}
+    for month_label, categories in months_data:
+        for cat in filter(_usable, categories):
+            name = cat.get("name", "")
+            if not name:
+                continue
+            amount = client.milliunit_to_amount(abs(cat.get("activity", 0)))
+            if name not in trends:
+                trends[name] = []
+            trends[name].append(MonthSpending(month=month_label, amount=amount))
+    return trends
+
+
+class PayeeTotal(Model):
+    """What was spent with one payee."""
+
+    payee_name: str
+    """Payee name; Unknown when the transactions have none."""
+    total: float
+    """Total spent, as a positive number in currency units."""
+    count: int
+    """Number of transactions."""
+
+
+def top_payees(
+    transactions: list[dict[str, Any]],
+    limit: int = 10,
+) -> list[PayeeTotal]:
+    """Aggregate transactions by payee and return the top spenders.
+
+    Args:
+        transactions: List of YNAB transaction dicts with ``payee_name``
+            and ``amount`` fields (amounts are in milliunits, negative = expense).
+        limit: Maximum number of payees to return (default 10).
+
+    Returns:
+        The payees, the biggest spending first.
+
+    Examples:
+        >>> txs = [
+        ...     {"payee_name": "AWS", "amount": -50000},
+        ...     {"payee_name": "AWS", "amount": -30000},
+        ...     {"payee_name": "Loyer", "amount": -500000},
+        ... ]
+        >>> top_payees(txs, limit=1)[0].payee_name
+        'Loyer'
+    """
+    totals: dict[str, dict[str, Any]] = {}
+    for tx in transactions:
+        payee = tx.get("payee_name") or "Unknown"
+        amount_mu = tx.get("amount", 0)
+        if payee not in totals:
+            totals[payee] = {"total_mu": 0, "count": 0}
+        totals[payee]["total_mu"] += abs(amount_mu)
+        totals[payee]["count"] += 1
+
+    sorted_payees = sorted(totals.items(), key=lambda kv: kv[1]["total_mu"], reverse=True)
+    return [
+        PayeeTotal(
+            payee_name=name,
+            total=client.milliunit_to_amount(data["total_mu"]),
+            count=data["count"],
+        )
+        for name, data in sorted_payees[:limit]
+    ]
+
+
+_INTERNAL_GROUP = "Internal Master Category"
+
+
+class Overspent(Model):
+    """A category whose available balance is negative."""
+
+    category_id: str
+    """YNAB id of the category."""
+    name: str
+    """Category name."""
+    group: str
+    """Name of the category's group."""
+    balance: float
+    """Available balance, negative: the amount overspent, in currency units."""
+
+
+class MonthOverview(Model):
+    """A month's totals and the categories that need attention."""
+
+    month: str
+    """First day of the month, YYYY-MM-01."""
+    income: float
+    """Money received in the month and assigned to Ready to Assign."""
+    budgeted: float
+    """Total assigned to categories in the month."""
+    activity: float
+    """Total spent (negative) and received in categories during the month."""
+    ready_to_assign: float
+    """Money not yet given a job; negative when more was assigned than received."""
+    age_of_money: int | None
+    """Days between receiving money and spending it, as YNAB computes it; null when unknown."""
+    overspent: list[Overspent]
+    """Categories whose available balance is negative this month."""
+
+
+class CategoryBalance(Model):
+    """One category's month in currency units."""
+
+    category_id: str
+    """YNAB id of the category."""
+    name: str
+    """Category name."""
+    group: str
+    """Name of the category's group."""
+    budgeted: float
+    """Amount assigned to the category this month."""
+    activity: float
+    """Amount spent (negative) or received in the category this month."""
+    balance: float
+    """Available at the end of the month: carried over, plus budgeted, plus activity."""
+
+
+def _usable(cat: dict[str, Any]) -> bool:
+    """Tell whether a category counts as the user's spending.
+
+    Args:
+        cat: A YNAB category.
+
+    Returns:
+        True when it is visible, not deleted, and not one of YNAB's internal categories.
+    """
+    return (
+        not cat.get("hidden")
+        and not cat.get("deleted")
+        and cat.get("category_group_name") != _INTERNAL_GROUP
+    )
+
+
+def month_overview(month: dict[str, Any]) -> MonthOverview:
+    """Summarise a YNAB month: totals in currency units and overspent categories.
+
+    Args:
+        month: A YNAB month, as returned by :func:`client.get_month`.
+
+    Returns:
+        The month's totals and the usable categories whose balance is negative.
+    """
+    amount = client.milliunit_to_amount
+    return MonthOverview(
+        month=month["month"],
+        income=amount(month.get("income", 0)),
+        budgeted=amount(month.get("budgeted", 0)),
+        activity=amount(month.get("activity", 0)),
+        ready_to_assign=amount(month.get("to_be_budgeted", 0)),
+        age_of_money=month.get("age_of_money"),
+        overspent=[
+            Overspent(
+                category_id=cat["id"],
+                name=cat["name"],
+                group=cat.get("category_group_name", ""),
+                balance=amount(cat["balance"]),
+            )
+            for cat in month.get("categories", [])
+            if _usable(cat) and cat.get("balance", 0) < 0
+        ],
+    )
+
+
+def category_balances(
+    categories: list[dict[str, Any]], include_empty: bool = False
+) -> list[CategoryBalance]:
+    """Give one line per usable category of a month.
+
+    Args:
+        categories: The month's YNAB categories, amounts in milliunits.
+        include_empty: Also list categories with nothing budgeted, spent or available.
+
+    Returns:
+        Each category's budgeted, activity and balance, in currency units.
+    """
+    amount = client.milliunit_to_amount
+    return [
+        CategoryBalance(
+            category_id=cat["id"],
+            name=cat["name"],
+            group=cat.get("category_group_name", ""),
+            budgeted=amount(cat.get("budgeted", 0)),
+            activity=amount(cat.get("activity", 0)),
+            balance=amount(cat.get("balance", 0)),
+        )
+        for cat in categories
+        if _usable(cat)
+        and (include_empty or any(cat.get(key, 0) for key in ("budgeted", "activity", "balance")))
+    ]