Building a Financial AI That Can Show Its Work

The Technical Architecture Behind Ask Linc

How Ask Linc combines financial integrations, semantic retrieval, deterministic computation, provenance, and LLM reasoning without letting the model become the system of record

Abstract

Large language models are remarkably good at interpretation. They are much less reliable as databases, calculators, or authorities on rapidly changing facts.

That distinction becomes especially important in personal finance.

A financial assistant may need to answer questions such as:

• Can I afford this house without derailing retirement?
• Why did my spending increase?
• How much of my portfolio is actually exposed to international equities?
• Can I retire at 60 instead of 65?
• Should I pay down this loan or keep more cash?
• What changes if mortgage rates move?

Answering those questions requires more than connecting an LLM to a bank account. It requires combining private financial data, investment data, market data, public information, historical datasets, user-provided assumptions, and deterministic calculations while preserving the provenance and freshness of every important number.

Ask Linc was designed around a simple architectural rule:

The model can reason about financial facts. It does not get to define them.

The application owns data access, identity, normalization, arithmetic, scenario execution, provenance, and validation. The language model owns semantic interpretation: understanding what the user is asking, determining which evidence is relevant, explaining results, identifying tradeoffs, and communicating them clearly.

This whitepaper describes how that separation works in practice.

1. The Core Architectural Problem

The naive architecture for an AI financial application looks something like this:

Connect accounts → collect JSON → put JSON in the prompt → ask the model for an answer.

It works surprisingly well in demos.

It also creates several difficult production problems.

Which balance is authoritative when a brokerage provider reports both an account balance and individual holdings? Is a transfer income? Is a negative checking balance negative cash or debt? If a home valuation is 20 days old while bank balances are two minutes old, what does “current as of” mean? What happens when one brokerage connection fails while three bank connections succeed? What if the model calculates net worth differently from the dashboard? What if it sees $1.2 million in a prior assistant message and repeats it as if it came from the user’s accounts?

These are not primarily prompting problems. They are data architecture problems.

Ask Linc therefore treats the LLM as the final reasoning layer in a larger financial system. The backend is an Express/TypeScript application, the frontend uses Next.js, PostgreSQL and Prisma provide persistence, and a set of provider adapters, canonical financial services, context-planning components, deterministic scenario engines, and response validators sit between raw external data and the model.

At a high level, the production path looks like this:

Financial providers
        │
        ▼
Ingestion + normalization
        │
        ▼
Canonical financial snapshot
        │
        ├──────────────► Deterministic calculations
        │                         │
        ▼                         ▼
Semantic context planning ◄── Scenario engines
        │
        ▼
Allowlisted evidence / data packs
        │
        ├──────────────► Live public retrieval when needed
        │
        ▼
Canonical fact pack
        │
        ▼
LLM interpretation
        │
        ▼
Deterministic response grounding
        │
        ▼
User-facing answer + “Show the Math” evidence

The important part is not any individual model or provider. It is the boundaries between them.

2. Provider Diversity at the Edge, Semantic Uniformity at the Core

Ask Linc integrates with many different systems because no single provider contains the data necessary for meaningful financial reasoning.

The current architecture includes Plaid for banking data and liabilities, SnapTrade for brokerage data, FRED for economic benchmarks, Massive for yield-curve and inflation-expectation data, Financial Modeling Prep for fund metadata and look-through exposure, Tiingo for prices and market news, RentCast for home valuations, Brave Search for current public information, and historical Shiller and Kenneth French datasets for retirement analysis. Operational integrations include Stripe, MailerLite, Resend, and Sentry.

But the application deliberately does not expose those providers directly to the inference layer.

The source catalog itself is an application contract. Each data source declares a provider, category, applicable subscription tiers, cache duration, and whether the underlying source should be considered live. For example, connected balances and transactions have much shorter cache horizons than FMP fund metadata or property valuations.

That seems like operational plumbing, but it turns out to be central to AI correctness.

A model should not need to know that one provider refreshes every five minutes while another changes monthly. The application should know that.

3. The Financial Truth Layer

One of the most consequential design decisions in Ask Linc is the existence of an explicit financial truth contract.

The contract defines what user-facing financial numbers actually mean. Provider adapters, persistence, API endpoints, the frontend, retirement analytics, and the LLM are all expected to consume those definitions rather than creating local interpretations.

This prevents a subtle but common failure mode in financial software: five parts of the application independently implementing “net worth,” “monthly spending,” or “investment value.”

Account identity

Accounts are identified by immutable provider identity, not by human-readable similarity.

Conceptually:

(ownerId, source, sourceConnectionId, sourceAccountId)

An account name, mask, institution, balance, type, or subtype is an attribute. It is not identity.

That means two accounts called “Individual Brokerage” with identical balances are not automatically merged. Cross-provider deduplication needs explicit evidence.

This is particularly important when aggregating Plaid and SnapTrade, where the same institution may surface data through different APIs.

Transaction semantics

Provider-native amounts are not treated as canonical cash flow.

Ask Linc distinguishes the original provider value from a normalized user-perspective cash-flow value. It also uses transaction classification—not merely the sign of an amount—to decide whether something represents income, spending, a refund, a transfer, an investment trade, or an unresolved adjustment.

Transfers are not income. Buying an ETF is not household spending. A refund should reduce spending. Pending transactions do not become historical actuals simply because they are present in an API response.

This matters because an LLM handed raw transaction arrays will happily create mathematically coherent answers from semantically incorrect inputs.

The right fix is upstream.

Unknown is not zero

Ask Linc also treats missing data as an explicit state.

An unknown home value is null, not $0.

An investment denominated in an unsupported currency is omitted and flagged, rather than silently converted to zero.

A partially itemized brokerage account is not assumed to contain nothing beyond its visible holdings.

These distinctions propagate into snapshot quality and ultimately into what the model is allowed to say.

4. Reconciling Financial Providers Before Reasoning

One example illustrates why this canonical layer matters.

Investment providers often expose both:

1. an institution-reported account balance, and
2. a list of individual holdings.

Those values frequently disagree.

If Ask Linc simply adds both, it double-counts the portfolio. If it uses only holdings, it may understate an employer plan whose API only itemizes part of the account.

The canonical rule is therefore that the account total is based on the greater usable value between the institution-reported balance and the deduplicated holdings value. Holdings describe composition; the account balance describes total value. Any positive balance that cannot be explained by individual holdings remains in net worth but is explicitly classified as Not itemized rather than being assigned to a guessed asset class.

That distinction becomes even more important in retirement modeling.

An unidentified residual balance can legitimately count toward net worth, but it cannot safely be assigned an expected historical return. So position-level simulation excludes it and reports the modeled and unmodeled value separately.

This is a recurring architectural theme in Ask Linc:

When information is incomplete, preserve the known value while refusing to invent the missing semantics.

5. Freshness Is Part of Financial Truth

A financial snapshot has more than one timestamp.

Ask Linc distinguishes:

• computedAt — when Ask Linc performed the calculation.
• asOf — the oldest underlying expiring source observation used in that calculation.
• status — whether the resulting snapshot is current, stale, partial, or unavailable.

Recomputing an old observation today does not make the underlying information current today.

This sounds obvious, but it is easy to lose once caching, asynchronous providers, scheduled refreshes, and retries enter the system.

A useful consequence is that the model receives not only a number, but enough quality information to qualify the number correctly.

The broader rule is:

Freshness belongs to evidence, not to the request that happened to retrieve it.

6. Ask Linc’s RAG Is an Evidence Router, Not a Prompt-Stuffing Pipeline

“RAG” often means:

documents → embeddings → vector search → top-k chunks → prompt

Ask Linc uses a different model.

Its primary retrieval problem is not finding semantically similar documents. It is deciding which types of evidence a financial decision requires.

The current system uses a two-pass semantic context planner. No production data-pack choice is made by matching keywords or regular expressions.

First pass: semantic preflight

An OpenAI context-planning model reads the current question together with both sides of the recent active conversation.

It returns structured output describing which allowlisted data packs appear necessary, whether independent validation is appropriate, any explicitly stated scenario inputs, supported scenario plans, and up to three self-contained public search queries.

The planner does not get authority to fetch arbitrary information or calculate financial outcomes.

Application code validates its output.

Unknown pack IDs are rejected. Dependencies are expanded deterministically. Scenario IDs must exist in the application-owned registry. Search queries must satisfy the application’s public-search contract.

Second pass: the answering model audits its own evidence

Before it can answer, the primary Claude model is required to call a constrained request_data_packs tool.

It can say, in effect:

I can answer this, but I also need individual account details and current mortgage-rate information.

What it cannot say is:

Give me arbitrary database table X.

The model sees the allowlisted vocabulary. Application code still owns access.

The second pass can widen context but cannot remove already-selected packs, bypass dependencies, create new calculator types, or perform arithmetic on behalf of the application.

This gives Ask Linc a useful separation of responsibility:

The model decides what something means. The application decides what that meaning is allowed to access.

7. Data Packs as an AI Data-Access Boundary

Optional context is represented using a small, hard-coded catalog of data packs.

The current packs are:

Aggregate financial truth—net worth, cash, debt, investment total, asset allocation, category totals, and average cash flow—is deliberately not optional. Those values are inexpensive and foundational enough to remain available to the reasoning layer.

The catalog is intentionally code-reviewed instead of dynamically generated by a model.

That has several benefits simultaneously.

It reduces context size. It avoids unnecessary provider calls. It creates a security boundary around sensitive data. It makes model behavior measurable. And it gives the team a comprehensible dependency graph rather than an open-ended agent with database access.

For an AI product, a typed data pack starts looking surprisingly similar to a capability.

8. Live Search Without Sending the User’s Prompt to Search

The search_context pack is Ask Linc’s closest analogue to conventional live-web RAG.

But even here the application does not simply forward the user’s message to a search engine.

The semantic planner and primary-model audit produce one to three standalone public queries. A valid query must make sense without the private conversation, remain within length limits, avoid obvious account/card/SSN/email identifiers, declare its purpose, and optionally request an explicit freshness window.

Only those validated queries are sent to Brave.

If planning fails, Ask Linc does not use the raw prompt as a fallback search query. Search fails closed.

That is an important privacy pattern for any application combining private context with public retrieval.

The retrieval system also caches each query-and-freshness combination independently for 30 minutes, records whether the answer came from cache or the provider, preserves failures on a per-query basis, keeps successful sibling queries if one fails, and de-duplicates final results by URL.

The underlying Brave integration includes request pacing, bounded retries, concurrency-safe rate limiting, and explicit handling of 429 backpressure so one provider quota event cannot create an unbounded interactive queue.

This makes the “R” in RAG a production subsystem rather than a library call.

9. Structured Market Context Is Different From Search

Ask Linc also deliberately distinguishes known structured feeds from open-ended retrieval.

If the question requires a mortgage benchmark, the system can retrieve a structured FRED observation.

If it requires the Treasury yield curve or inflation expectations, Massive supplies structured market data.

Tiingo provides current investment prices and structured market news, while FMP provides security and fund metadata. Massive’s market aggregation, for example, collects SPY market bars, Treasury yields, and inflation expectations as separate provider calls.

Tiingo separately supplies adjusted price history, IEX quotes, and market-news data used for both connected investment enrichment and broader market context.

A search engine is therefore not the universal data interface.

When the application already knows the shape, semantics, and authoritative source for a fact, it uses a structured integration.

Search is reserved for evidence whose domain is inherently open-ended: laws, current limits, rules, benefits, rates, current external facts, and similar information.

10. Calculation Is Not Inference

This is the most important boundary in the Ask Linc architecture.

LLMs do not compute authoritative financial results.

Net worth, cash, debt, investment totals, monthly income and expenses, savings rates, portfolio allocation, retirement survival rates, depletion percentiles, withdrawal rates, and registered what-if calculations are produced in normal application code.

The model receives the result.

Its role is to explain what the result means.

For example:

Application:
Monthly income                 $12,400
Monthly expenses                $8,900
Operating cash flow             $3,500
Savings rate                     28.2%

LLM:
“Your current spending leaves meaningful monthly capacity,
but the house scenario consumes most of that buffer...”

The model is useful because the second part is contextual.

It is dangerous if it becomes responsible for the first part.

This is not an assertion that modern LLMs cannot perform arithmetic. They can.

The issue is that important financial calculations need deterministic behavior, testability, versioning, provenance, edge-case handling, and repeatability.

A calculator function can provide those things.

A generative model should not be asked to emulate one.

11. Scenario Modeling: Let the Model Specify the Question, Not Solve It

The same principle applies to “what if?” questions.

Ask Linc currently has registered deterministic calculators for retirement-withdrawal planning and target-home affordability. The architecture is designed to add additional decision domains behind the same boundary.

Suppose a user asks:

What if I retire at 60 instead, spend $90,000 a year, and delay Social Security?

The semantic layer is good at recognizing that this is a retirement scenario and extracting the explicitly stated assumptions.

But it does not simulate the portfolio.

Instead:

Natural-language request
        ↓
Typed scenario plan
        ↓
Validate supported overrides
        ↓
Load required canonical data
        ↓
Application-owned calculator
        ↓
Scenario facts + assumption ledger
        ↓
LLM explanation

Each calculator definition owns its ID and version, required data packs, accepted override names and bounds, defaults, output schema, executor, unavailable-state behavior, fact projection, and deterministic disclosures.

A model cannot invent a new override field simply because it sounds financially reasonable.

Even more importantly, a numeric scenario override is accepted only if it remains traceable to wording the user actually supplied. An untraceable model-generated number is discarded before execution.

This transforms tool use from “the AI can run code” into something much narrower:

The AI can propose a typed invocation of code the application already trusts.

12. Why Retirement Modeling Is Offline

Retirement analysis is a particularly useful example of the separation.

Ask Linc’s historical stress-testing engine is deterministic and operates over checked-in historical market data derived from datasets including Robert Shiller’s market history and Kenneth French’s research datasets. The resulting normalized historical series is used locally rather than asking an LLM to estimate future portfolio behavior.

The engine runs historical withdrawal scenarios, inflation-adjusted spending policies, portfolio rebalancing, depletion analysis, and sustainable-withdrawal distributions in application code.

The LLM can then discuss questions such as:

• Which assumptions are driving the result?
• How sensitive is the plan to spending?
• What changes if retirement is delayed?
• Why is sequence-of-returns risk important here?

Those are reasoning questions.

The survival rate itself is not.

13. Canonical Facts: The Interface Between Computation and Language

After retrieval and deterministic calculation, Ask Linc does not hand the model an unstructured bag of data.

It builds a canonical fact pack.

A fact contains roughly this conceptual structure:

id
label
value
unit
displayability
optional caveat
provenance

Provenance can distinguish snapshot observations, deterministic calculations, user inputs, external context, scenario inputs, and scenario calculations. Calculated facts may include both the formula and the IDs of their input facts. Scenario facts can also identify the calculator and version that produced them.

For example:

{
  "id": "savings_rate",
  "label": "Savings rate",
  "value": 28.2258,
  "unit": "percent",
  "provenance": {
    "kind": "calculation",
    "formula": "(operating_cash_flow / average_monthly_income) * 100",
    "inputFactIds": [
      "average_monthly_operating_cash_flow",
      "average_monthly_income"
    ]
  }
}

This gives the model something more useful than raw data.

It gives it citable financial claims.

The fact-pack builder also limits which numbers can become displayable claims. Even numeric values extracted from text are parsed with contextual rules intended to distinguish a real financial value from identifiers such as “401(k)” or “S&P 500.”

14. Caveats Travel With the Number

Provenance is only useful if qualifications cannot get separated from the fact they qualify.

Ask Linc therefore allows canonical facts to carry caveats.

Suppose only 88% of a portfolio’s value could be mapped to supported asset classes for a retirement simulation.

The engine may still be able to calculate meaningful statistics over that 88%.

But “portfolio withdrawal rate” and “withdrawal rate over modeled holdings” do not mean exactly the same thing.

Rather than place a generic disclaimer at the bottom of the answer and hope the model remembers it, the limitation is attached to the canonical fact itself.

This is a more general design principle:

Metadata that changes the interpretation of a number should live with the number, not in prose surrounding the number.

15. The Model’s Output Is Not Trusted Just Because the Input Was Good

Grounding the input is necessary.

It is not sufficient.

A model can receive perfect data and still introduce a number during generation.

Ask Linc therefore validates the response after inference.

The model returns a structured object containing a summary, important key numbers, insights, and suggested actions. Server code then canonicalizes the structured numbers back onto the exact server-side fact definitions rather than trusting model-authored labels, units, or provenance.

Then Ask Linc validates not only structured numeric fields, but also monetary and percentage claims embedded in user-facing prose.

The grounding code understands common presentation behavior.

$996 can validly represent a canonical value of $995.57.

9% can validly represent 9.18%.

At the same time, the scanner distinguishes financial claims from numeric identifiers such as 401(k), S&P 500, Rule of 72, calendar years, ranges, magnitude suffixes, and common negative-language constructions such as a “$3,000 shortfall.”

This is essentially an application-level numeric firewall around the model.

16. Validation Is a Recovery System, Not Just a Rejection System

A naive validator has two states:

valid → return
invalid → fail

Ask Linc’s pipeline is more useful than that.

If the model cites a value that is unsupported by the current fact pack, the application first asks whether the problem may be missing evidence rather than hallucination.

The recovery path can load all remaining allowlisted context packs and re-check the original answer against the expanded canonical fact set.

If the value becomes grounded, the original answer can survive without another generation.

If issues remain, the active model receives validation feedback and gets one retry.

If the retry still contains ungrounded claims, server code attempts to salvage the grounded portions of the response. A generic unavailable response is the last resort, not the first.

This creates a useful hierarchy:

Generate
   ↓
Ground
   ↓
If unsupported: expand evidence
   ↓
Ground again
   ↓
If still unsupported: regenerate with feedback
   ↓
Ground again
   ↓
If still unsupported: remove unverifiable portions

This distinction is subtle.

Sometimes the model hallucinated.

Sometimes the retrieval planner under-fetched.

The validator should not assume those are the same failure.

17. Independent Model Review Is Separate From Fact Grounding

Ask Linc can optionally use Gemini as a secondary reviewer for sufficiently complex questions.

That check is intentionally distinct from deterministic fact validation.

The deterministic validator answers:

Does every financial claim have evidence?

The secondary reasoning reviewer can answer a different question:

Is the reasoning built around those valid facts sensible?

This avoids using another LLM to validate arithmetic the application can validate exactly.

It also means a secondary-model disagreement does not magically turn a grounded fact into an ungrounded one.

The architecture is therefore not “multiple LLMs vote on the answer.”

Different validators have different jobs.

18. Model Fallback Without Data Drift

Ask Linc currently uses Claude as the primary analysis model, with OpenAI available as a provider fallback.

The important architectural detail is not that there are two vendors.

It is that provider fallback happens after the context has been prepared.

If Claude becomes unavailable, OpenAI receives the same already-built system prompt and user context. The application does not re-fetch bank accounts, rerun RAG, reload market context, or recompute the snapshot merely because the inference vendor changed.

That prevents a subtle observability problem:

Claude request uses snapshot A
Claude fails
Providers refresh
OpenAI fallback uses snapshot B

Now provider comparison and debugging are impossible because the models never saw the same evidence.

Ask Linc instead treats the prepared context as an immutable input to that inference attempt.

This also makes changing model vendors substantially easier because the difficult part of the product is not encoded exclusively in one vendor’s prompt.

19. Partial Provider Failure Is a First-Class State

Real financial integrations fail.

Access tokens expire. One institution times out. A brokerage sync becomes temporarily disabled. A home-valuation provider cannot value an address. A metadata API does not cover a fund.

Ask Linc’s financial ingestion layer therefore distinguishes between failures that actually cost financial data and advisory failures where the data arrived but some metadata about the connection could not be verified.

That distinction exists because treating every provider warning as “partial financial data” can cause an otherwise complete snapshot to be discarded.

This is an important operational lesson for multi-provider AI systems:

Error severity should describe the effect on evidence, not merely the fact that an API emitted an error.

An AI answer should be degraded because data is missing—not because a provider produced a harmless warning somewhere in the same request.

20. “Show the Math” Is an Architectural Feature

Transparency is often implemented as UI copy:

Here’s why we recommended this.

Ask Linc takes a different approach.

The analysis pipeline records an evidence manifest containing canonical facts, calculation provenance, snapshot timestamps, context-planning decisions, search execution metadata, scenario executions, and operational measurements.

The product’s “Show the Math” experience is built from that evidence.

Importantly, the system does not need to persist the entire prompt, full financial snapshot, and raw model response simply to make an answer inspectable. It persists compact fact and evidence references and loads larger supporting evidence only when necessary.

This changes explainability from a model behavior into a system property.

A model can write an excellent explanation.

But the application should still be able to answer:

• Where did this number come from?
• What was its source date?
• Was it observed or calculated?
• What formula produced it?
• Which scenario assumptions were active?
• Which provider supplied the underlying evidence?
• Did retrieval come from cache?
• Did the primary planner initially request this data?
• Was more context loaded during validation?

That level of traceability becomes invaluable once an AI application moves beyond demos.

21. The Broader Architecture

Putting the pieces together, the current production reasoning path can be thought of as five planes.

Data plane

Plaid, SnapTrade, user-entered data, and external financial providers supply raw observations. Provider-specific identities and semantics are preserved at ingestion.

Truth plane

Application code converts those observations into canonical accounts, transactions, portfolios, cash flow, balance-sheet totals, source observations, and quality state.

Retrieval plane

Semantic planning decides which optional evidence the current financial decision requires. Data-pack allowlists and dependency expansion control access. Structured integrations and live search supply additional evidence only when needed.

Computation plane

Application-owned calculators produce financial metrics and scenario results. Every important output can become a canonical fact with provenance.

Inference plane

The model interprets the resulting facts, explains tradeoffs, and returns a structured answer. Application code then reasserts control by grounding the generated output against the fact pack.

That final reversal of control is intentional.

The model is powerful in the middle.

The application controls both ends.

22. What This Architecture Costs

None of this is free.

A pure prompt-driven implementation is much smaller.

Ask Linc instead has code for provider reconciliation, source-quality tracking, canonical snapshots, context-pack dependencies, semantic planning, search-query validation, calculator registries, canonical facts, prose-level numeric validation, evidence manifests, and recovery behavior.

That increases the surface area of the application.

It also moves complexity into places where conventional engineering techniques work.

A financial formula can have unit tests.

A calculator version can be pinned.

A data pack can have an explicit dependency.

A source can declare freshness semantics.

A model-produced scenario override can be schema-validated.

A canonical fact can identify its provenance.

A response can be mechanically checked.

The alternative is not zero complexity.

The alternative is hiding that complexity inside a nondeterministic prompt.

23. Patterns We Would Reuse in Other AI Products

Several lessons from Ask Linc are applicable well beyond financial technology.

1. Use models for semantic decisions, not deterministic ones. Determining that a question is about retirement is a strong LLM task. Calculating portfolio depletion is a software task.
2. Put a typed capability boundary between the model and private data. Let the model request transaction_details; do not let it compose arbitrary database queries.
3. Normalize provider semantics before inference. Multiple APIs describing the same domain will disagree. Resolve those disagreements once.
4. Make missing information a real state. unknown, stale, partial, and unavailable are more useful than inventing defaults or quietly converting everything to zero.
5. Retrieve semantically, execute deterministically. The model can identify the evidence or scenario necessary to answer a question while application code owns the actual retrieval and calculation.
6. Validate outputs, not just inputs. A grounded prompt does not guarantee a grounded response.
7. Attach provenance and limitations directly to facts. Do not rely on the model to remember which disclaimer belongs to which number.
8. Keep inference providers downstream from your product logic. A model change should not require rewriting financial truth, retrieval, or scenario calculations.
9. Treat retrieval plans as data. Persist which evidence was requested, what was actually loaded, whether it came from cache, and whether the model later needed more.
10. Build explainability underneath the model. The best “show your work” system is not a prompt asking the LLM to produce more prose. It is a record of the actual inputs and computations that produced the answer.

Conclusion

The most useful LLM architecture for finance turned out not to be the one that gives the model the most autonomy.

It is the one that gives the model the right autonomy.

Ask Linc allows language models to do what they are unusually good at: understanding intent, selecting relevant context, connecting facts, recognizing tradeoffs, and explaining complex financial situations in ordinary language.

The rest remains application code.

Providers supply observations.

A canonical financial layer defines their meaning.

Semantic RAG decides which evidence is relevant.

Data packs constrain access.

Deterministic engines perform calculations.

Canonical facts carry values, units, provenance, and limitations.

The model interprets them.

And deterministic validators check what the model says before the answer reaches the user.

The resulting architecture is more involved than connecting an LLM directly to financial APIs.

That is precisely the point.

For high-stakes AI products, the goal is not to make the model the application.

The goal is to build an application strong enough that the model can safely be the reasoning layer inside it.