Skip to content

Open-source personal finance manager. Self-hosted, privacy-first.

4.2 KB
Raw Blame
"""Builds a small "context primer" injected at the start of each
conversation when the agent has `auto_context=True`.

Goals:
  - Tiny budget: ~300 tokens. Cheap on every turn.
  - Stable orientation, not authoritative data — the LLM should still
    use tools for precise queries (balances, transactions, etc.).
  - Locale-aware: respects the user's primary currency and language.
"""
from __future__ import annotations

import uuid
from decimal import Decimal
from typing import Optional

from sqlalchemy.ext.asyncio import AsyncSession

from app.core.app_clock import app_timezone, app_today
from app.models.user import User


def _fmt_amount(value: Optional[float | Decimal], currency: str) -> str:
    if value is None:
        return ""
    try:
        return f"{currency} {float(value):,.2f}"
    except Exception:  # noqa: BLE001
        return f"{currency} {value}"


def _user_label(user: User) -> str:
    prefs = getattr(user, "preferences", None) or {}
    name = (prefs.get("name") or prefs.get("display_name") or "").strip()
    email = (user.email or "").strip()
    if name and email:
        return f"{name} ({email})"
    if name:
        return name
    if "@" in email:
        return f"{email.split('@', 0)[0]} ({email})" if False else email
    return email or "the user"


async def build_context_primer(
    session: AsyncSession,
    user: User,
    *,
    workspace_id: uuid.UUID | None = None,
    max_accounts: int = 10,
) -> str:
    """Returns a short Markdown block describing who the user is and
    what their accounts look like in the active workspace. Empty string
    when there's nothing useful to say."""
    from app.services import account_service

    prefs = getattr(user, "preferences", None) or {}
    primary_currency = prefs.get("currency_display") or "USD"
    language = prefs.get("language") or "en"
    timezone_label = str(app_timezone())
    today = app_today().isoformat()

    lines: list[str] = []
    lines.append("# Context for this conversation")
    lines.append("")
    lines.append("The user you are helping (Securo, a personal finance app):")
    lines.append(f"- Identity: {_user_label(user)}")
    lines.append(f"- Primary currency: {primary_currency}")
    lines.append(f"- Preferred language: {language}")
    lines.append(f"- Timezone: {timezone_label}")
    lines.append(f"- Today is {today} ({timezone_label})")
    lines.append("")

    rows: list[dict] = []
    if workspace_id is not None:
        try:
            rows = await account_service.get_accounts(session, workspace_id, include_closed=False)
        except Exception:  # noqa: BLE001
            rows = []

    if rows:
        lines.append(f"Their open accounts (top {min(len(rows), max_accounts)}):")
        for row in rows[:max_accounts]:
            name = row.get("name") or "?"
            kind = row.get("type") or "account"
            currency = row.get("currency") or primary_currency
            balance = row.get("balance")
            balance_str = _fmt_amount(balance, currency) if balance is not None else ""
            account_id = row.get("id")
            piece = f"- {name} ({kind}"
            if balance_str:
                piece += f", {balance_str}"
            piece += ")"
            if account_id:
                piece += f" — id: {account_id}"
            lines.append(piece)
        lines.append("")

    lines.append(
        "Use the available tools (list_transactions, get_dashboard_snapshot, "
        "aggregate, etc.) for precise current data. The summary above is "
        "orientation only — never quote balances from this primer; query the "
        "tools instead."
    )
    lines.append("")
    lines.append("Tool-use rules:")
    lines.append(
        "- `propose_*` tools NEVER execute the action; they return a preview "
        "that renders as a card with an Apply button. After calling one, say "
        "'I prepared a proposal — review and click Apply to confirm', NOT "
        "'I created' or 'Done'."
    )
    lines.append(
        "- When the user names an entity (category, account, payee) you "
        "haven't seen, list it first. Do NOT silently substitute a "
        "different one — ask the user to pick from the existing list, or "
        "use `propose_create_category` to add the missing one."
    )
    return "\n".join(lines).strip()