# Read-Only AI Personal Finance Assistant: A Technical Design

1. Why Personal Finance Is a High-Value Scenario for a Conversational Assistant

The pain points of traditional bookkeeping and reconciliation tools are obvious: manual entry, fixed report dimensions, and anomaly discovery that depends on humans reading through transaction histories. What users actually want to ask is rarely a combination of filter conditions. It is a colloquial request, such as “where did my money go this month,” “are there any charges I don’t remember,” or “what does APR mean, and how much interest did I actually pay this year.”

A conversational assistant has three advantages here: a natural language entry point lowers the barrier to querying; it can explain terminology, translating concepts such as annual percentage rate, daily interest calculation, and minimum payment into plain language; and it can explain code and generate visualizations, turning conclusions directly into charts, calendars, or dashboards.

The financial domain, however, has one hard constraint: once a conclusion about money is wrong, the cost far outweighs a loss of experience. The design focus of the whole system must therefore be front-loaded onto “boundaries” and “verifiability,” not conversational fluency.

2. First-Principle Constraint: Make “Read-Only” an Architecture-Level Capability

2.1 Least Privilege Is Topology, Not a Declaration

Read-only should be implemented by making the “write” path physically nonexistent, rather than constraining model behavior through prompts. Available engineering measures include:

• Connect only read-only data authorization; the system carries no capability for transfers, payments, or automatic debits.
• Credentials are held by an independent credential-management component. The application layer only obtains short-lived tokens whose scope is limited to “read account balances and transaction details.”
• The query gateway enforces an explicit allowlist. Any call outside the allowlist is rejected outright and triggers an alert.
• Full-chain audit: who, at what time, with what identity, read which segment of data, and generated which conclusion.

2.2 Authorization and Token Lifecycle (Illustrative)

The code below is used only to illustrate the design idea and does not represent any real API definition:

# Pseudocode: tokens retain only read scopes; write capability never enters the system
def issue_readonly_token(user_id: str, account_ids: list[str]):
    scope = "balance:read transactions:read"   # explicit allowlist, no write/transfer
    return token_service.mint(
        subject=user_id,
        scope=scope,
        audience=["aggregation-gateway"],
        resources=[f"account:{a}" for a in account_ids],
        ttl_seconds=900,                      # short-lived, refreshed periodically
        binding="user_consent_grant"          # bound to the user consent event
    )

Three supporting disciplines apply: tokens must not be written to ordinary business logs; authorization is revoked immediately when it expires or the user unlinks, followed by consistency cleanup; and any path that “reads results and reassembles them into a write request” should be treated as a design defect.

3. Data Layer: Turn Transactions into Computable Structures

3.1 Unified Transaction Model

The model outputs analytical conclusions, and those conclusions must be built on one consistent semantic definition. A recommended minimal transaction model:

-- Illustrative schema
CREATE TABLE txn (
  txn_id        STRING,      -- idempotency key: institution-side unique transaction ID
  account_id    STRING,
  merchant_raw  STRING,      -- raw merchant name
  merchant_key  STRING,      -- normalized merchant identifier
  mcc           STRING,      -- merchant category code, primary basis for classification
  category      STRING,      -- spending category
  amount_minor  BIGINT,      -- integer amount in minor currency units (cents), avoiding floating-point error
  direction     STRING,      -- debit / credit
  currency      STRING,
  posted_at     TIMESTAMP,
  status        STRING,      -- pending / posted / reversed
  balance_after BIGINT       -- balance after the transaction, used for cross-validation
);

Two details that are easy to overlook but affect the correctness of conclusions: amounts must be stored as integers in the smallest currency unit, and floating point is forbidden in aggregation paths; pending and reversed must be explicitly modeled, otherwise “this month’s spending” will drift as settlement status changes.

3.2 Sync Pipeline

• Pull jobs are written to a message queue, partitioned by account to guarantee ordered processing within the same account.
• Idempotent writes are keyed on txn_id, so repeated pulls do not produce duplicate rows.
• Raw payloads are retained in object storage for traceability, while the normalized views used for analytics live in columnar storage.
• Data freshness is exposed as a first-class metric to monitoring and alerting, avoiding “conclusions based on a stale snapshot.”

4. Semantic Layer: Make the Model Query Data, Not Invent Data

This is the core dividing line of the whole solution. Letting the model freely generate SQL and execute it introduces risks: metric drift (treating a refund as spending), scope escape (reading across accounts), and, most dangerously, the model “filling in” a number when no data exists.

The recommended layering is “tool calling + deterministic computation”:

TOOLS = [
  {"name": "list_accounts",        "desc": "list authorized read-only accounts",                 "readonly": True},
  {"name": "query_transactions",    "desc": "filter transactions by time/merchant/category; account scope enforced", "readonly": True},
  {"name": "aggregate_spend",       "desc": "aggregate spend by category/week/month; metrics fixed server-side", "readonly": True},
  {"name": "detect_recurring_fees", "desc": "identify recurring charges and amount changes",       "readonly": True},
  {"name": "compute_interest",      "desc": "compute total interest using the daily accrual basis", "readonly": True},
  {"name": "render_chart",          "desc": "generate a chart spec, not rendered image pixels",    "readonly": True},
]

Three implementation points:

1. The model is responsible only for intent parsing and parameter filling. Aggregation rules, metric definitions, and calculation formulas all move down into fixed server-side code, and parameters are validated against a schema before execution.
2. The tool layer enforces row-level scope. Account IDs are injected from the session context and model-reported account parameters are not accepted, structurally eliminating scope escape.
3. Numeric computation is never performed by the model. The model only “explains the metric and cites the result”—for example, restating an interest total returned by the service in natural language rather than computing it in its head.

5. Algorithmic Implementation for Typical Scenarios

5.1 Monthly Cash Flow Summary

When a user asks “where did my money go this month,” the execution chain is: determine the time range (including cross-month attribution rules) → pull posted transactions within that range → perform two-level classification by mcc and normalized merchant → compute the amount and share of each category → compare with the same period last month.

For the classification strategy, use merchant category codes as the primary signal with keyword rules as a supplement, and list the portion that cannot be classified separately rather than forcing it into “Other.” When the unclassified share is too high, the assistant should proactively state that share—which is itself useful information.

5.2 Anomalous Charge Detection

The truly valuable answer is not “how much did I spend this month” but “what looks wrong.” Three categories of high-value signal:

# 1) Duplicate charges: same merchant + same amount, occurring multiple times within a time window
def find_duplicate_charges(txns, window_days=3, tol_minor=0):
    groups = defaultdict(list)
    for t in txns:
        if t.direction == "debit" and t.status == "posted":
            groups[(t.merchant_key, t.amount_minor)].append(t)
    hits = []
    for (_, amount), items in groups.items():
        items.sort(key=lambda x: x.posted_at)
        for a, b in zip(items, items[1:]):
            if 0 <= (b.posted_at - a.posted_at).days <= window_days and abs(a.amount_minor - amount) <= tol_minor:
                hits.append({"merchant": a.merchant_key, "amount": amount, "txns": [a.txn_id, b.txn_id]})
    return hits
# 2) Silent price hikes: for a recurring merchant, the recent 30-day average is noticeably above the prior 90-day average
def find_silent_price_hikes(txns, today, rise_ratio=0.10, min_samples=3):
    flags = []
    by_merchant = defaultdict(list)
    for t in txns:
        if t.direction == "debit" and t.status == "posted":
            by_merchant[t.merchant_key].append(t)
    for merchant, items in by_merchant.items():
        recent = [t.amount_minor for t in items if (today - t.posted_at).days <= 30]
        prior  = [t.amount_minor for t in items if 30 < (today - t.posted_at).days <= 120]
        if len(recent) >= min_samples and len(prior) >= min_samples:
            base = sum(prior) / len(prior)
            if base > 0 and (sum(recent) / len(recent)) >= base * (1 + rise_ratio):
                flags.append({"merchant": merchant, "prior_avg": round(base), "recent_avg": round(sum(recent)/len(recent))})
    return flags

The third category typically takes the form of scattered “service fees,” “account maintenance fees,” and “foreign transaction fees.” These are characterized by small amounts, vague descriptions, and low frequency, so a human would almost never notice them. The value of such rules lies in coverage, not in the size of any single charge.

From an engineering standpoint: make thresholds (time window, rise ratio, minimum sample count) configurable and bring them under monitoring. A hit rate that is too high means the thresholds are too loose and will drown the user’s attention in noise.

5.3 Macro Assessment and Interest Statistics

Faced with “am I spending more than I earn,” the correct approach is to aggregate by direction: on the income side, total the credits and exclude internal transfers; on the spending side, total the debits and deduct repayments, investment transfers, and other non-consumption items; then report net cash flow and savings rate, while stating the metric definitions and exclusions so the user knows how the conclusion was reached.

Faced with “what does APR mean, and how much interest did I pay this year,” the assistant should first explain the concept, then hand the calculation to deterministic code. Taking daily accrual as an example:

def interest_minor(principal_minor: int, apr_bps: int, days: int, basis: int = 365) -> int:
    """
    Simple interest, daily accrual: interest = principal x APR x days / accrual basis
    principal_minor: principal, in minor units (cents)
    apr_bps:         annual percentage rate, in basis points (1/10000), e.g. 18.99% => 1899
    """
    return principal_minor * apr_bps * days // (basis * 10000)

Metric differences that must be made explicit to the user include: the accrual basis (365 or 360 days), whether daily compounding applies, the billing cycle and interest-free period, and the conversion of installment fees into an effective annual rate. Without clear metric definitions, the same number can differ considerably across algorithms.

6. Output Layer: Charts, Calendars, and Custom Dashboards

For requests such as “generate a weekly spending chart” or “generate a calendar of bills due,” the correct output is a structured specification rather than a directly rendered bitmap, so the user can keep adjusting it.

{
  "chart": "bar",
  "title": "Spending distribution over the last 8 weeks",
  "x": {"field": "week_start", "type": "temporal"},
  "y": {"field": "amount_minor", "aggregate": "sum", "currency": "CNY"},
  "series": {"field": "category", "stacked": true},
  "notes": ["includes posted transactions, excludes internal transfers"],
  "source": ["aggregate_spend@2026-08-25T21:00:00Z"]
}

Dashboard design should revolve around four types of blocks: cash flow overview, category ranking, recurring charges list (with amount-change markers), and bills-due calendar (sorted by due date, with a flag for whether autopay applies). The source field in the spec is key, because it lets every chart be traced back to a specific calculation call and data timestamp.

7. Correctness and Verifiability: Engineering “It Might Be Wrong”

This is the most underestimated part of this kind of product. Five mechanisms are recommended:

1. Conclusion-level citation. Every monetary conclusion must carry a supporting list of transaction IDs that the user can expand in one click. A number without supporting detail is not allowed to appear in a reply.
2. Refuse to answer when data is insufficient. When the query range has no data, an account is unauthorized, or the snapshot is stale, state the status clearly instead of giving an estimate that looks plausible.
3. Metrics stated up front. Before a conclusion, give the time range, account scope, exclusions, and the rule for handling settlement status.
4. Graded uncertainty. Results from deterministic computation are labeled “based on data from authorized accounts”; inference-dependent conclusions (such as “this looks like a duplicate charge”) are labeled as pending confirmation, with a prompt to check against the institution’s official statement.
5. Mandatory cross-validation for important amounts. For conclusions involving interest, repayment, or investment returns, consistently advise the user to treat the official statement from the bank or card issuer as authoritative.

For evaluation, build a “golden statement set”: manually labeled account transaction histories covering edge cases such as cross-month attribution, refunds, foreign currency, installments, internal transfers, and pending-to-posted transitions. Run a regression on every rule or prompt change, and monitor the error rate of monetary conclusions in particular, rather than only looking at answer satisfaction.

8. Privacy, Security, and Compliance

• Minimal collection and retention: pull only the accounts and time ranges necessary for analysis, set a retention period for raw payloads with cleanup on expiry, and store derived metrics and raw transactions at separate tiers.
• Encryption in transit and at rest: encrypt the full chain in transit, encrypt data at rest, host keys and credentials independently, and follow least privilege and periodic rotation for access.
• Model-side boundaries: data sent to the inference engine is masked as needed, explicitly not used for training, and inference calls are not persisted to a general-purpose logging system.
• Isolation and audit: in multi-tenant scenarios, isolate at both the logical and storage levels; log all data access and conclusion generation so users can see “which data the assistant read.”
• Revocable permissions: access can be revoked instantly on unlinking, authorization expiry, or a risk-control trigger, followed by data consistency cleanup.

If this capability is delivered as a cloud service, the engineering implementation typically relies on several general-purpose capabilities: a container platform hosting query and inference services, a message queue for sync peak-shaving and ordering guarantees, object storage retaining raw payloads, columnar or analytical storage hosting the normalized views, logging with monitoring and alerting covering data freshness, rule hit rate, and latency metrics, and a key management component handling credential hosting and rotation. The specific choices should be evaluated against data scale, compliance requirements, and cost structure rather than decided uniformly.

9. Canary Rollout and Ramp-Up

• Roll out by population: ramp up low-risk scenarios first (read-only queries, terminology explanation, chart generation), and release anomaly-detection features later.
• Observable metrics: conclusion adoption rate, detail-expansion rate, rate of reconciliation against official statements, per-account query cost, P95 response time, and data freshness lag.
• Rollback switches: each analysis tool has an independent switch, so a problem can degrade that tool to “explain the metric only, give no conclusion.”
• Feedback loop: when a user marks a conclusion as “wrong,” it is automatically linked to the specific rule and threshold, for tuning rather than just manual appeasement.

10. Pre-Launch Checklist

1. Is write capability absent at the topology level, rather than only constrained by prompts?
2. Are amounts integers in minor currency units throughout, with floating point excluded from aggregation paths?
3. Are aggregation metrics fixed server-side, and can the model bypass the tools to produce a number directly?
4. Does the tool layer enforce row-level account scope, and can it reject model-reported account parameters?
5. Can every monetary conclusion be expanded to specific transactions, and does the system clearly refuse to answer when there is no data?
6. Are the handling rules for pending, reversed, refunds, and internal transfers explicitly defined?
7. Is there a golden statement set for regression, and is the error rate monitored separately?
8. Can access be revoked instantly on authorization expiry, unlinking, or a risk-control trigger?

11. Conclusion

The competitiveness of a personal finance assistant does not lie in “how much it can chat,” but in three things: whether the permission boundary is trustworthy, whether the calculation metrics are deterministic, and whether conclusions are verifiable. Only when read-only is made an architectural fact, numeric computation is pushed down into deterministic code, and every conclusion is bound to traceable detail, does conversational capability truly become a financial judgment users dare to rely on. Conversely, if the model is allowed to freely generate numbers and metrics are handled vaguely, even the smoothest interaction will erode trust over long-term use.