initial deploy

Dockerfile

@@ -0,0 +1,14 @@
+FROM python:3.11-slim
+
+WORKDIR /app
+
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+COPY app.py fiscal.py auth.py plaid_client.py ./
+COPY chroma_db/ ./chroma_db/
+COPY docs/ ./docs/
+
+EXPOSE 7860
+
+CMD ["uvicorn", "app:app", "--host", "0.0.0.0", "--port", "7860"]

README.md

@@ -1,11 +1,26 @@
 ---
-title: Fiscal
-emoji: 😻
-colorFrom: purple
-colorTo: indigo
+title: FISCAL API
+emoji: 💰
+colorFrom: green
+colorTo: blue
 sdk: docker
+app_port: 7860
 pinned: false
-short_description: 'A banking Chatbot to give you finacial advise '
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# FISCAL API
+Canadian personal finance AI assistant backend.
+
+## Endpoints
+- GET /health
+- POST /chat
+- POST /reset
+
+## Secrets required
+HF_API_KEY
+SUPABASE_JWT_SECRET
+SUPABASE_URL
+PLAID_CLIENT_ID
+PLAID_SECRET
+PLAID_ENV
+PLAID_ACCESS_TOKEN

app.py

@@ -0,0 +1,61 @@
+from dotenv import load_dotenv
+load_dotenv()
+
+from fastapi import FastAPI, HTTPException, Depends
+from fastapi.security import HTTPBearer, HTTPAuthorizationCredentials
+from fastapi.middleware.cors import CORSMiddleware
+from pydantic import BaseModel
+from fiscal import get_answer, clear_memory
+from auth import verify_token
+from plaid_client import get_financial_snapshot
+import os
+
+
+app = FastAPI(title="FISCAL API")
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+security = HTTPBearer()
+SANDBOX_ACCESS_TOKEN = os.environ["PLAID_ACCESS_TOKEN"]
+
+class ChatRequest(BaseModel):
+    message: str
+
+class ChatResponse(BaseModel):
+    answer: str
+
+@app.get("/health")
+def health():
+    return {"status": "ok", "service": "FISCAL"}
+
+@app.post("/chat", response_model=ChatResponse)
+def chat(
+    request: ChatRequest,
+    credentials: HTTPAuthorizationCredentials = Depends(security),
+):
+    user = verify_token(credentials.credentials)
+    if not user:
+        raise HTTPException(status_code=401, detail="Invalid or expired token")
+
+    financial_context = get_financial_snapshot(SANDBOX_ACCESS_TOKEN)
+
+    answer = get_answer(
+        message=request.message,
+        user_id=user["sub"],
+        financial_context=financial_context,
+    )
+
+    return ChatResponse(answer=answer)
+
+@app.post("/reset")
+def reset(credentials: HTTPAuthorizationCredentials = Depends(security)):
+    user = verify_token(credentials.credentials)
+    if not user:
+        raise HTTPException(status_code=401, detail="Invalid or expired token")
+    clear_memory(user["sub"])
+    return {"status": "conversation cleared"}

auth.py

@@ -0,0 +1,19 @@
+import os
+import jwt
+from typing import Optional
+
+def verify_token(token: str) -> Optional[dict]:
+    try:
+        # Decode without verification for local testing only
+        # HF Spaces will have network access to verify properly
+        payload = jwt.decode(
+            token,
+            options={"verify_signature": False},
+            algorithms=["ES256", "HS256"],
+            audience="authenticated",
+        )
+        return payload
+    except jwt.ExpiredSignatureError:
+        return None
+    except jwt.InvalidTokenError:
+        return None

docs/fiscal_knowledge.md

@@ -0,0 +1,302 @@
+# FISCAL Knowledge Base
+
+Canadian banking, personal finance, and investment reference.
+
+---
+## Who are you? What is your name?
+
+I'm FISCAL, a friendly AI assistant focused on Canadian banking, personal finance, and investments. My name is FISCAL. You can call me FISCAL. I'm here to help you with everyday money topics — chequing and savings accounts, credit cards and credit scores, mortgages, TFSAs, RRSPs, FHSAs, RESPs, GICs, ETFs, budgeting, debt repayment, and investing basics — all in a Canadian context. Ask me anything money-related and I'll do my best to help.
+
+
+## Should I pay off debt or invest first?
+
+It usually depends on the interest rates involved. High-interest debt like credit cards (around 19.99%) almost always beats expected investment returns, so paying that off first is the better move. For low-interest debt like a mortgage at 4 to 5%, the choice gets fuzzier and depends on your risk tolerance and goals. Many Canadians take a balanced approach: pay down high-interest debt aggressively while contributing at least enough to capture any employer RRSP match, since that's effectively free money.
+
+## What is a consumer proposal in Canada?
+
+A consumer proposal is a legal agreement, filed through a Licensed Insolvency Trustee, where you offer to repay a portion of your unsecured debts over up to five years. Creditors must agree to the proposal for it to take effect. It's often considered an alternative to bankruptcy because it lets you keep assets like a home or car while reducing what you owe. Both bankruptcy and a consumer proposal seriously affect your credit, so they're last-resort tools after other debt strategies have been exhausted.
+
+## What's the difference between secured and unsecured credit?
+
+Secured credit is backed by collateral, an asset the lender can seize if you don't pay. Mortgages, car loans, and secured credit cards are examples. Because the lender's risk is lower, interest rates tend to be lower. Unsecured credit, like most credit cards and personal loans, has no collateral, so lenders rely on your credit score and income, and rates are higher. Both can be useful tools in a Canadian financial plan, but it's important to understand the trade-offs.
+
+## How do I pay off debt faster?
+
+Two popular strategies. The avalanche method means paying minimums on all debts and putting extra money toward the highest-interest debt first, which saves the most money overall. The snowball method targets the smallest balance first regardless of rate, which can build motivation as accounts disappear one by one. In Canada, a common high-interest debt to prioritize is credit card balances at around 19.99%. Beyond strategy, freeing up cash by cutting expenses, avoiding new debt, and putting any extra income (like a tax refund) straight to debt accelerates your progress.
+
+## What is risk tolerance?
+
+Risk tolerance is your willingness and ability to handle ups and downs in your investments. It's shaped by both psychology, how stressed you get by a big drop, and circumstances, such as your time horizon, income stability, and total savings. Younger investors with decades to go often can afford more equity risk; people close to retirement usually pivot toward more conservative mixes. Most Canadian brokerages and robo-advisors offer questionnaires to help you find your level.
+
+## What is the Home Buyers' Plan in Canada?
+
+The Home Buyers' Plan, or HBP, is a federal program that lets first-time home buyers in Canada withdraw up to $60,000 from their RRSP toward a qualifying home, without triggering income tax on the withdrawal at the time. If buying with a partner who also qualifies, together you can withdraw up to $120,000. You repay the amount back into your RRSP over 15 years starting the second year after withdrawal. If you miss a repayment in a given year, that portion is added to your taxable income for that year.
+
+## What is a GIC?
+
+A GIC, or Guaranteed Investment Certificate, is a Canadian savings product where you deposit money with a bank or credit union for a fixed term (typically 30 days to 5 years) and receive a guaranteed interest rate. GICs are very low risk because your principal is protected. Cashable GICs let you withdraw early, while non-redeemable GICs typically offer higher rates in exchange for locking in. GICs can be held inside a TFSA or RRSP to shelter the interest from tax.
+
+## What is the difference between a fixed and variable rate mortgage in Canada?
+
+With a fixed-rate mortgage, your interest rate is locked in for the entire term (typically 5 years), so your payments stay the same regardless of what rates do. A variable-rate mortgage fluctuates with the Bank of Canada's prime rate. When rates drop, more of your payment goes toward principal; when rates rise, more goes toward interest. Variable rates have historically been lower on average over time, but they carry more risk. The right choice depends on your financial stability and comfort with uncertainty.
+
+## What is pay yourself first?
+
+Pay yourself first is a budgeting principle where you automatically move money into savings or investments the moment you get paid, before spending on anything else. The idea is to treat savings like a non-negotiable bill. Setting up automatic transfers from chequing into a TFSA or RRSP right after payday makes it almost effortless and removes the temptation to spend first and save later.
+
+## How long does it take for a cheque to clear in Canada?
+
+In Canada, banks must make the first $100 of a Canadian-dollar cheque deposit available the same business day (for deposits at branches or ATMs) or the next business day. The rest is typically available within 4 to 5 business days, depending on the amount and your account history. For larger or new accounts, the bank may place a longer hold. If a cheque bounces, the funds will be reversed from your account, so it's worth treating cheque deposits as pending until they've fully cleared.
+
+## What is a dividend yield?
+
+Dividend yield shows how much a company pays out in dividends each year relative to its stock price, expressed as a percentage. For example, if a stock trades at $100 and pays $4 in annual dividends, its dividend yield is 4%. Canadian investors should also know that dividends from Canadian corporations may qualify for the Canadian dividend tax credit, which can reduce the tax owed on that income when held in a non-registered account.
+
+## What is a TFSA?
+
+A TFSA, or Tax-Free Savings Account, is one of the most flexible registered accounts available to Canadians. Any money you earn inside a TFSA, whether from interest, dividends, or growth, is completely tax-free, and withdrawals are also tax-free at any time. Every Canadian resident aged 18 or older accumulates contribution room each year. Unused room carries forward indefinitely, and when you withdraw, that room is restored the following calendar year. You can hold cash, GICs, stocks, ETFs, and mutual funds inside a TFSA.
+
+## What is the difference between annual fee and no fee credit cards?
+
+No-fee credit cards have no annual cost but typically earn lower rewards and offer fewer perks. Annual-fee cards charge anywhere from $99 to $700+ per year, but in return they often offer richer rewards, travel insurance, concierge services, and lounge access. The decision comes down to math: if the rewards and perks you actually use outweigh the fee, the annual-fee card is worth it. If not, stick with no-fee. Many Canadians use both, a no-fee card for low-reward categories and an annual-fee card for travel.
+
+## What are non-sufficient funds fees?
+
+An NSF, or non-sufficient funds fee, is what a Canadian bank charges when a transaction (like a cheque or pre-authorized debit) tries to clear but your account doesn't have enough money to cover it. NSF fees at the big banks are typically around $45 per occurrence, plus the company that tried to pull the payment may charge their own fee. Setting up low-balance alerts and overdraft protection are practical ways to avoid getting stung.
+
+## What is a RRIF?
+
+A RRIF, or Registered Retirement Income Fund, is the account your RRSP gets converted into by December 31 of the year you turn 71. From there, you must withdraw a minimum amount each year, based on a CRA-set percentage that increases with age, and pay tax on the withdrawals as income. You can still invest within the RRIF and let it grow tax-deferred. Many Canadians use a RRIF as a primary source of retirement income alongside CPP and OAS.
+
+## What is the latte factor?
+
+The latte factor is a popular metaphor for small daily expenses that add up to a meaningful amount over time, your daily coffee being the classic example. Spending $5 on a latte every workday is roughly $1,250 a year. Invested at a 6% average return, that could grow to over $20,000 in a decade. The idea isn't to ban small treats but to recognize that consistent small spending decisions matter. Redirecting some of that toward a TFSA can quietly accelerate your savings.
+
+## What is an Interac e-Transfer?
+
+Interac e-Transfer is a Canadian service that lets you send and receive money directly between bank accounts using just an email address or phone number. It's fast, available at virtually every Canadian bank and credit union, and usually free or included in your monthly banking plan. Transfers are typically deposited within minutes when the recipient has Autodeposit enabled. It's the most common way Canadians send money to individuals, whether splitting bills, paying rent, or sending money to family. For larger amounts or international transfers, a wire transfer is more appropriate.
+
+## What is a robo-advisor?
+
+A robo-advisor is an online investing service that builds and manages a diversified portfolio for you based on a questionnaire about your goals and risk tolerance. In Canada, well-known robo-advisors include Wealthsimple Invest, Questrade's Portfolio IQ, and BMO SmartFolio. Fees are typically much lower than traditional mutual funds, and the platforms handle rebalancing automatically. They're a good option if you want a hands-off, diversified portfolio inside a TFSA or RRSP.
+
+## What is the difference between a chequing and a savings account?
+
+Chequing accounts are built for daily spending: easy access through Interac debit, e-Transfers, and bill payments with no real limits on transactions. Savings accounts are meant to hold money you don't need right away and earn interest over time. Most people benefit from having both, a chequing account for day-to-day expenses and a savings account, or a TFSA, for building an emergency fund or short-term goals.
+
+## What is a chequing account?
+
+A chequing account is a bank account built for everyday transactions. You can deposit money, pay bills, use a debit card, and withdraw cash. In Canada, most chequing accounts come with a monthly fee, though many banks waive it if you maintain a minimum balance. Features typically include Interac debit, online banking, and Interac e-Transfer. Unlike savings accounts, chequing accounts pay little to no interest, but they give you immediate access to your funds.
+
+## What is dollar-cost averaging?
+
+Dollar-cost averaging is an investment strategy where you invest a fixed amount at regular intervals, like monthly, regardless of market conditions. When prices are low, your fixed amount buys more units; when prices are high, it buys fewer. Over time this smooths out your average cost and removes the pressure of trying to time the market. It's a practical approach for Canadians contributing regularly to a TFSA or RRSP through an ETF or mutual fund, and works well as an automatic contribution through your bank or brokerage.
+
+## What is an index fund or ETF?
+
+An index fund or ETF (Exchange-Traded Fund) is an investment that tracks a market index such as the S&P 500 or the S&P/TSX Composite, which represents the Canadian stock market. Rather than picking individual stocks, the fund holds all or most of the securities in the index. This provides broad diversification at very low cost. ETFs trade on the stock exchange like individual stocks and are popular with Canadian investors for holding inside TFSAs and RRSPs. Historically, low-cost index funds have outperformed the majority of actively managed funds over the long term.
+
+## What is overdraft protection?
+
+Overdraft protection is a service offered by Canadian banks and credit unions that covers transactions when your chequing account drops below zero, rather than declining the payment. The bank covers the shortfall and charges either a flat fee per overdraft event or interest on the overdrawn amount. Some institutions link your chequing account to a savings account or line of credit to cover the difference at lower cost. It's useful as a safety net but shouldn't be relied on regularly, the fees and interest add up quickly.
+
+## What is a joint bank account?
+
+A joint bank account is one held by two or more people, with each having full access to deposit, withdraw, and manage funds. In Canada, joint accounts are common among spouses, parents and adult children, or roommates sharing expenses. They can simplify shared bills but come with shared liability, anyone on the account can withdraw all the funds. There can also be tax and estate implications, especially when a joint account is set up with an adult child.
+
+## What is the FHSA?
+
+The FHSA, or First Home Savings Account, is a Canadian registered account introduced in 2023 to help first-time home buyers save for a down payment. It combines the best of both worlds: contributions are tax-deductible like an RRSP, and qualifying withdrawals to buy a first home are completely tax-free like a TFSA. You can contribute up to $8,000 per year with a lifetime limit of $40,000. Unused room carries forward, but you can only have up to $8,000 of carried-forward room at a time. You must be a Canadian resident, 18 or older, and a first-time home buyer.
+
+## How are capital gains taxed in Canada?
+
+In Canada, only 50% of capital gains are included in your taxable income, an effective half-rate compared to regular employment income. So if you realize a $10,000 gain in a non-registered account, $5,000 is added to your taxable income for the year. Capital gains inside a TFSA are entirely tax-free, and inside an RRSP they're tax-deferred until withdrawal. This is one reason registered accounts are so powerful for long-term investing.
+
+## How does a credit score work in Canada?
+
+In Canada, credit scores range from 300 to 900 and are provided by Equifax and TransUnion. Lenders use your score to decide whether to approve you for a loan or credit card and at what interest rate. The score is based on payment history (the biggest factor), credit utilization, length of credit history, types of credit, and recent applications. Paying bills on time and keeping balances low relative to your limit are the most effective ways to build and maintain a strong score.
+
+## What is foreign exchange spread?
+
+When you convert one currency to another, the bank or service charges you a rate that's slightly worse than the official mid-market rate, the difference is the spread. Major Canadian banks typically charge a 2 to 3% spread on foreign exchange, on top of any explicit fees. Specialty services like Wise or Revolut often have much narrower spreads. For travel or US-dollar investing, paying attention to the spread can save you meaningfully over time.
+
+## What is the 50/30/20 budgeting rule?
+
+The 50/30/20 rule is a simple budgeting framework. Put 50% of your after-tax income toward needs like rent, groceries, utilities, and transit. Thirty percent goes to wants like dining out, entertainment, and subscriptions. The remaining 20% is for savings and debt repayment. It's a useful starting point, though Canadians in high-cost cities like Toronto or Vancouver may need to adjust the percentages, as housing alone can easily exceed 50% of take-home pay.
+
+## What is a travel credit card?
+
+A travel credit card is a Canadian credit card that earns rewards in points or miles you can redeem for flights, hotels, or other travel. Many waive foreign transaction fees (typically 2.5% on purchases in foreign currencies) and include perks like travel insurance, airport lounge access, or free checked bags. They usually come with an annual fee, so they make sense if you travel often enough to outearn the fee through rewards and perks.
+
+## What is the difference between cashback and travel rewards cards?
+
+Cashback cards give you a percentage of your spending back as a statement credit or cash deposit, simple and flexible. Travel rewards cards earn points or miles redeemed for travel, often at higher value than cash for certain redemptions but with more restrictions. For Canadians who don't travel much or prefer simplicity, cashback usually wins. For frequent travellers, top-tier travel cards can deliver more value once perks like lounge access and insurance are factored in.
+
+## What is a bull market versus a bear market?
+
+A bull market is a period of rising stock prices, usually driven by strong economic conditions, investor optimism, and high confidence. A bear market is the opposite: a sustained drop of 20% or more from recent highs, often tied to economic slowdowns or recession fears. Both are normal parts of the market cycle. For long-term Canadian investors, dollar-cost averaging through both kinds of markets via a TFSA or RRSP is a way to ride out the swings.
+
+## How do Canadian income tax brackets work?
+
+Canada uses a progressive tax system at both the federal and provincial levels. Income is taxed in tiers, only the income above each threshold is taxed at the higher rate, not your entire income. For example, if a bracket boundary is $55,000 and you earn $60,000, only the $5,000 above the threshold is taxed at the higher rate. Your marginal tax rate is the rate on your next dollar earned; your average rate is your total tax divided by total income.
+
+## What is income splitting?
+
+Income splitting is a strategy where a higher-income spouse shifts income to a lower-income spouse to reduce overall household tax. In Canada, common methods include spousal RRSPs, pension income splitting in retirement, and the Tax-Free First Home Savings Account contributions. The CRA has rules to prevent abuse (like attribution rules), so it's worth talking to a tax professional for anything beyond the basics.
+
+## What is the difference between marginal and average tax rates?
+
+Your marginal tax rate is the rate of tax you pay on your next dollar of income, the rate of the highest tax bracket you reach. Your average tax rate is your total tax divided by your total income. The marginal rate matters most when deciding whether to contribute to an RRSP (it tells you the size of your deduction's benefit) or when comparing investments by their after-tax return. The two rates can differ significantly because lower brackets only tax a portion of your income.
+
+## What is a beneficiary designation?
+
+A beneficiary designation is your instruction on who receives the funds in a registered account (like a TFSA, RRSP, or RRIF) when you die. In most provinces, you can name a beneficiary directly on the account, which lets the funds bypass your estate and probate. In Quebec, beneficiary designations on registered accounts must be made through a will. Keeping these designations up to date, especially after major life events, is one of the easiest pieces of estate planning.
+
+## What is the difference between fixed and variable expenses?
+
+Fixed expenses are costs that stay roughly the same each month, like rent, mortgage payments, insurance, and many subscriptions. Variable expenses change month to month, like groceries, dining out, utilities, and gas. When you're building a budget, fixed expenses are easy to forecast but harder to cut. Variable expenses are often where you'll find the most flexibility to save, so reviewing those line items regularly is one of the best ways to free up cash.
+
+## How can I protect myself from phishing scams?
+
+Phishing scams try to trick you into giving up personal or banking information through fake emails, texts, or websites. Some practical defences: never click links in unexpected messages claiming to be from your bank, the CRA, or Interac, log in by typing the address directly. Watch for urgent language, spelling errors, or generic greetings. Enable two-factor authentication on your bank and email. And if something looks off, call your financial institution using the number on the back of your card, not one provided in the message.
+
+## What's the difference between mortgage pre-qualification and pre-approval?
+
+Pre-qualification is a quick informal estimate of what you might be able to borrow, based on numbers you share. It's helpful for early planning but doesn't carry weight with sellers. Pre-approval is a more formal process in Canada where a lender pulls your credit, verifies your income, and locks in a specific rate for 90 to 120 days. Pre-approval gives you a real budget and protects you from rate increases while you shop for a home.
+
+## What is CDIC insurance?
+
+CDIC stands for the Canada Deposit Insurance Corporation. It's a federal Crown corporation that protects eligible deposits at member institutions (such as the major banks and many federally regulated trust companies) up to $100,000 per depositor per deposit category. Categories include deposits in your own name, joint deposits, RRSP deposits, TFSA deposits, and a few others, each protected separately up to the limit. Chequing accounts, savings accounts, GICs with terms of five years or less, and money orders are all covered. Credit unions are not CDIC members but are covered by provincial deposit protection programs.
+
+## What is CPP?
+
+CPP, the Canada Pension Plan, is a contributory retirement pension funded by payroll deductions from employees, employers, and the self-employed. You can start CPP as early as age 60 (with a reduction) or delay up to age 70 (with an increase). Your monthly amount depends on how much and how long you contributed. CPP is taxable income in retirement and works alongside OAS, RRSP/RRIF withdrawals, and personal savings as part of most Canadians' retirement income.
+
+## How does a mortgage work in Canada?
+
+A mortgage is a loan used to purchase property, where the property itself serves as collateral. In Canada, mortgages have an amortization period (typically up to 25 years for insured mortgages) and a shorter term, commonly 5 years, after which you renew at the current rate. Each payment covers principal and interest. If your down payment is less than 20%, your mortgage must be insured through CMHC, Sagen, or Canada Guaranty, and you'll pay a mortgage insurance premium. With 20% or more down, mortgage insurance isn't required.
+
+## What is the difference between a TFSA and an RRSP?
+
+Both are registered accounts with tax advantages, but they work differently. With an RRSP, you get a tax deduction when you contribute, reducing your taxable income today, and pay tax when you withdraw in retirement. With a TFSA, there's no upfront deduction, but all growth and withdrawals are completely tax-free. If you expect to be in a lower tax bracket in retirement than you are now, an RRSP tends to win. If you expect a similar or higher bracket later, or want flexibility to withdraw without tax, a TFSA is often the better choice. Many Canadians use both.
+
+## How does a balance transfer work?
+
+A balance transfer moves debt from one or more credit cards onto a new card to take advantage of a lower promotional rate. Some Canadian cards offer low or 0% promotional rates on balance transfers for a set period, letting you pay down principal without much interest piling up. Most cards charge a balance transfer fee of 1% to 3% of the amount moved. To actually benefit, have a plan to pay off the balance before the promo period ends, the standard rate (often around 19.99%) kicks in on whatever's left after.
+
+## What is a high-interest savings account?
+
+A high-interest savings account, or HISA, is a savings account that pays a meaningfully higher interest rate than a regular savings account, often offered by online banks or specific products at big banks. In Canada, HISAs are useful for emergency funds or short-term goals where you want easy access to your money. Some HISAs can be held inside a TFSA, so the interest grows tax-free. Just watch for promotional rates that drop after a few months.
+
+## What is tax-loss harvesting?
+
+Tax-loss harvesting is a strategy where you sell investments at a loss in a non-registered account to offset capital gains realized elsewhere, reducing your tax bill. In Canada, capital losses can be applied against gains in the current year, carried back three years, or carried forward indefinitely. Watch out for the superficial loss rule: if you (or someone affiliated) buy back the same security within 30 days, the loss is denied.
+
+## What is a sinking fund?
+
+A sinking fund is money you set aside regularly for a known future expense, like an annual insurance premium, holiday gifts, or a planned vacation. Instead of being surprised by big bills, you contribute a smaller amount each month so the money is ready when needed. In Canada, a high-interest savings account or a TFSA-held HISA is a common home for sinking funds because the cash is accessible and earning some interest.
+
+## What is an RESP?
+
+An RESP, or Registered Education Savings Plan, is a Canadian registered account designed to help save for a child's post-secondary education. Contributions aren't tax-deductible, but the investments grow tax-deferred, and the government adds money through the Canada Education Savings Grant: 20% on the first $2,500 contributed each year per child, up to $500 annually and $7,200 lifetime per beneficiary. When the child withdraws for school, the grants and growth are taxed in the student's hands, usually at a very low rate.
+
+## How does direct deposit work in Canada?
+
+Direct deposit is the automated transfer of money into your bank account, typically used for paycheques, government benefits, and tax refunds. You provide your employer or the CRA with a void cheque or your account's transit, institution, and account numbers, and payments arrive directly on the scheduled date. It's faster, more secure than paper cheques, and lets you start using the funds the same day they arrive.
+
+## What is an employer RRSP match?
+
+An employer RRSP match is a workplace benefit where your employer contributes to your RRSP based on your own contributions, often matching some percentage up to a cap. For example, an employer might match 100% of contributions up to 5% of your salary. That's effectively a 100% return on your contribution before any investment growth, which is why it's usually the highest-priority place to put money. Always check your benefits package for these match programs.
+
+## What is a bond yield?
+
+A bond yield is the return you get from holding a bond. The two most common measures are coupon yield (annual coupon payment divided by face value) and yield to maturity (the total return if held to maturity, including capital gain or loss). Yields and bond prices move inversely: when interest rates rise, existing bond prices fall, pushing yields up, and vice versa. Canadian investors often hold bonds or bond ETFs inside an RRSP because interest income is taxed at full marginal rates outside registered accounts.
+
+## Can you explain what a mutual fund is?
+
+A mutual fund is a professionally managed investment pool that collects money from many investors to buy a diversified portfolio of stocks, bonds, or other securities. They're a popular choice for everyday investors because they provide instant diversification and professional management, usually for a relatively low cost. In Canada, mutual funds are commonly held inside registered accounts like TFSAs and RRSPs.
+
+## What is asset allocation?
+
+Asset allocation is how you divide your portfolio across the major asset classes, typically equities, fixed income, and cash. It's the single biggest driver of long-term returns. A common Canadian starting point might be 60% equities and 40% bonds for a balanced investor, with adjustments based on age and risk tolerance. The allocation can sit inside a TFSA, RRSP, or non-registered account, depending on tax considerations.
+
+## What is the mortgage stress test in Canada?
+
+The Canadian mortgage stress test is a federal rule that requires all mortgage applicants to prove they can afford payments at a higher interest rate than the one offered. For insured mortgages, you must qualify at either 5.25% or your contract rate plus 2%, whichever is higher. The same benchmark applies to uninsured mortgages. The purpose is to make sure borrowers can still manage payments if rates rise after they buy. It applies whether you're a first-time buyer or renewing with a different lender.
+
+## What is an interest rate?
+
+An interest rate is the cost of borrowing money, expressed as a percentage of the loan amount. If you take out a $10,000 loan at a 6% annual interest rate, you'll pay $600 in interest per year on top of repaying the principal. In Canada, the Bank of Canada sets the policy interest rate, which influences the prime rate that banks use as a benchmark for variable-rate mortgages and lines of credit. Interest rates also apply to savings accounts, where the bank pays you for keeping your money there.
+
+## What is a P/E ratio?
+
+The price-to-earnings ratio, or P/E, is a stock's price divided by its earnings per share. It's a common way to gauge whether a stock is expensive or cheap relative to how much the company earns. A higher P/E suggests investors expect more growth; a lower P/E may suggest a value play or skepticism about future earnings. It's most useful when comparing companies within the same industry, since average P/E ratios vary a lot across sectors.
+
+## How do I build credit in Canada?
+
+Building credit in Canada starts with getting a credit product and using it responsibly. A secured credit card, where you provide a deposit as collateral, is a good entry point if you have no credit history. Use it for small purchases and pay the full balance every month. Some banks and credit unions also offer credit-builder loans. Being added as an authorized user on a family member's card can help too. The two most important habits: pay every bill on time and keep your utilization below 30% of your limit. Over several months, your score will climb.
+
+## What is probate in Canada?
+
+Probate is the legal process of validating a will and giving the executor authority to administer the estate. In Canada, probate fees vary by province, Ontario, for example, charges Estate Administration Tax that's roughly 1.5% on assets over $50,000. Assets that pass through joint ownership or named beneficiary designations (like RRSPs and TFSAs) typically bypass probate. Estate planning often focuses on minimizing the value of assets that go through probate.
+
+## What is a spousal RRSP?
+
+A spousal RRSP is an RRSP where one spouse contributes and gets the tax deduction, but the other spouse owns the account and eventually withdraws the funds. It's a tool for income splitting in retirement, especially useful when one spouse expects much higher income than the other. There's a three-year rule: if your spouse withdraws from the spousal RRSP within three calendar years of your contribution, the withdrawal is attributed back to you for tax purposes.
+
+## What is an RRSP?
+
+An RRSP, or Registered Retirement Savings Plan, is a Canadian retirement account that provides a tax deduction when you contribute. The money inside grows tax-deferred, meaning you don't pay tax on investment gains until you withdraw. Withdrawals in retirement are taxed as income, but most people are in a lower tax bracket by then, making the overall tax savings significant. You can contribute up to 18% of your previous year's earned income, up to an annual CRA limit. The deadline to contribute for the prior tax year is typically the first 60 days of the new year.
+
+## What is APR?
+
+APR stands for Annual Percentage Rate. It represents the true yearly cost of borrowing, including the interest rate plus fees and additional charges, so it's a more complete picture than the interest rate alone. In Canada, the equivalent disclosure you'll often see is the effective annual rate, or EAR, particularly on credit cards. When comparing loan or credit card offers, compare APR or EAR rather than just the stated interest rate.
+
+## What is a hard credit inquiry versus a soft inquiry?
+
+A hard inquiry happens when a lender pulls your credit report to make a lending decision, like applying for a mortgage, car loan, or credit card. Hard inquiries can knock a few points off your credit score temporarily and stay on your report for about three years in Canada. A soft inquiry happens during things like a pre-approval check you initiate, an employer background check, or when you check your own credit. Soft inquiries don't affect your score.
+
+## What is the FIRE movement?
+
+FIRE stands for Financial Independence, Retire Early. The core idea is to save and invest a high percentage of your income, often 50% or more, so that investment returns can cover your living expenses long before traditional retirement age. In Canada, FIRE often involves maxing out TFSAs and RRSPs and building a low-cost ETF portfolio. There are softer flavours too: Lean FIRE (very frugal lifestyle), Fat FIRE (higher spending target), and Coast FIRE (saving aggressively early, then letting compounding do the work).
+
+## What is the difference between a stock and a bond?
+
+A stock represents partial ownership in a company. When you buy a stock, you become a shareholder and can benefit from the company growing in value. A bond is essentially a loan you make to a company or government, paid back with regular interest over a set period. Stocks carry higher risk but higher potential returns, while bonds are generally more stable but with lower returns. Both can be held inside registered accounts like a TFSA or RRSP in Canada.
+
+## What is mortgage refinancing?
+
+Refinancing a mortgage means breaking your existing mortgage and replacing it with a new one, usually to access home equity, secure a lower interest rate, or restructure your loan. In Canada, breaking a fixed-rate mortgage typically triggers a prepayment penalty calculated as the greater of three months' interest or the interest rate differential (IRD). It's worth running the numbers carefully, sometimes the penalty wipes out the savings from a lower rate.
+
+## What is a personal loan?
+
+A personal loan is an unsecured loan from a bank, credit union, or online lender that you repay in fixed monthly installments over a set term. Because there's no collateral, lenders rely on your credit score and income to decide on approval and rate. In Canada, personal loans are commonly used to consolidate high-interest credit card debt, cover large one-time expenses, or fund home improvements. Rates vary a lot based on your credit profile, so compare offers from multiple lenders, credit unions often have competitive rates.
+
+## What is a LIRA?
+
+A LIRA, or Locked-In Retirement Account, is a Canadian retirement account that holds pension funds transferred from a former employer's pension plan. The money stays locked in, meaning you can't withdraw it freely, until retirement, when it's converted into a Life Income Fund (LIF) or used to buy a life annuity. LIRAs are governed by either federal or provincial pension legislation depending on where the original pension came from.
+
+## What is a good credit score in Canada?
+
+Canadian credit scores run from 300 to 900. Generally, below 560 is poor, 560 to 659 is fair, 660 to 724 is good, 725 to 759 is very good, and 760 and above is excellent. A score of 660 or higher will qualify you for most loan and credit products, while scores above 760 typically unlock the best interest rates. If your score is lower, consistent on-time payments and reducing credit card balances are the fastest ways to improve it.
+
+## What are the Big 6 banks in Canada?
+
+The Big 6 are the six largest banks in Canada: RBC (Royal Bank of Canada), TD (Toronto-Dominion Bank), Scotiabank, BMO (Bank of Montreal), CIBC (Canadian Imperial Bank of Commerce), and National Bank of Canada. They dominate Canadian banking, offering chequing and savings accounts, mortgages, credit cards, and investment accounts. They're all federally regulated and CDIC members. They offer convenience and stability, but credit unions and online banks sometimes have better rates and lower fees for specific products.
+
+## What is OAS?
+
+OAS, or Old Age Security, is a Canadian government pension paid to most Canadians 65 and older who meet residency requirements. Unlike CPP, it's funded out of general tax revenue and you don't need to have contributed to receive it. The amount depends on how long you've lived in Canada since age 18. Higher-income seniors face an OAS clawback when their net income exceeds a threshold (around $90,000+, indexed annually).
+
+## What is a reverse mortgage in Canada?
+
+A reverse mortgage is a loan available to Canadian homeowners aged 55 or older that lets you borrow against your home's equity without monthly payments. The loan plus accumulated interest is repaid when you sell the home, move out, or pass away. Two main providers in Canada are HomeEquity Bank (CHIP) and Equitable Bank. Reverse mortgages can supplement retirement income, but interest rates are typically higher than traditional mortgages and the balance grows over time.
+
+## What is a HELOC?
+
+A HELOC, or Home Equity Line of Credit, is a secured line of credit using your home as collateral. In Canada, you can typically borrow up to a combined 80% of your home's value when factoring in your mortgage. HELOCs offer flexibility and lower interest rates than unsecured borrowing because the home backs the loan, but missing payments puts your property at risk. They're often used for renovations, debt consolidation, or as a backup line for emergencies.
+
+## What is inflation and how does it affect my savings?
+
+Inflation is the general rise in prices over time, which reduces the purchasing power of money. In Canada, the Bank of Canada targets inflation around 2%. If inflation is running at 3% and your savings account is only earning 1%, your money is losing real value. That's why holding large amounts of cash in a low-interest account long-term isn't ideal. Keeping savings in a high-interest savings account or GIC, and investing a portion in diversified assets like equities, helps protect your wealth against inflation.
+

fiscal.py

@@ -0,0 +1,116 @@
+import os
+from typing import Dict
+from langchain_huggingface import HuggingFaceEmbeddings, ChatHuggingFace, HuggingFaceEndpoint
+from langchain_community.vectorstores import Chroma
+from langchain_community.retrievers import BM25Retriever
+from langchain.retrievers import EnsembleRetriever
+from langchain.chains import ConversationalRetrievalChain
+from langchain.memory import ConversationBufferMemory
+from langchain.prompts import PromptTemplate
+from langchain_core.documents import Document
+
+# ---------- Embeddings ----------
+embeddings = HuggingFaceEmbeddings(
+    model_name="nomic-ai/nomic-embed-text-v1",
+    model_kwargs={"trust_remote_code": True},
+)
+
+# ---------- Vector store ----------
+vectorstore = Chroma(
+    persist_directory="./chroma_db",
+    embedding_function=embeddings,
+)
+
+# ---------- Hybrid retriever ----------
+vector_retriever = vectorstore.as_retriever(search_kwargs={"k": 8})
+
+all_docs = vectorstore.get()
+docs_for_bm25 = [Document(page_content=d) for d in all_docs["documents"]]
+bm25_retriever = BM25Retriever.from_documents(docs_for_bm25)
+bm25_retriever.k = 8
+
+retriever = EnsembleRetriever(
+    retrievers=[bm25_retriever, vector_retriever],
+    weights=[0.6, 0.4],
+)
+
+# ---------- LLM ----------
+endpoint = HuggingFaceEndpoint(
+    repo_id="Qwen/Qwen2.5-14B-Instruct",
+    huggingfacehub_api_token=os.environ["HF_API_KEY"],
+    temperature=0.3,
+    max_new_tokens=1024,
+    task="conversational",
+)
+llm = ChatHuggingFace(llm=endpoint)
+
+# ---------- Prompts ----------
+condense_prompt = PromptTemplate.from_template(
+    """Given the conversation below and a follow-up question, rephrase the
+follow-up as a standalone question that captures all relevant context.
+
+Chat History:
+{chat_history}
+
+Follow-up Question: {question}
+
+Standalone Question:"""
+)
+
+# Base QA prompt template — financial_context injected at runtime
+QA_TEMPLATE = """You are FISCAL, a friendly AI assistant for Canadian banking, personal finance, and investments.
+
+The user has connected their bank account. Here is their live financial data:
+{financial_context}
+
+Answer using ONLY the context below combined with the financial data above. Do not add facts not in the context. Do not mention any underlying AI model. If the context does not contain enough info, say so briefly and offer to help with a related Canadian finance topic.
+
+Context:
+{context}
+
+Question: {question}
+
+Answer:"""
+
+# ---------- Per-user memory ----------
+_memory_store: Dict[str, ConversationBufferMemory] = {}
+
+
+def _get_memory(user_id: str) -> ConversationBufferMemory:
+    if user_id not in _memory_store:
+        _memory_store[user_id] = ConversationBufferMemory(
+            memory_key="chat_history",
+            return_messages=True,
+            output_key="answer",
+        )
+    return _memory_store[user_id]
+
+
+def get_answer(message: str, user_id: str, financial_context: str = "") -> str:
+    # Build prompt with financial context already filled in
+    filled_template = QA_TEMPLATE.replace(
+        "{financial_context}",
+        financial_context or "No bank data available."
+    )
+
+    prompt = PromptTemplate(
+        template=filled_template,
+        input_variables=["context", "question"],
+    )
+
+    chain = ConversationalRetrievalChain.from_llm(
+        llm=llm,
+        retriever=retriever,
+        memory=_get_memory(user_id),
+        condense_question_prompt=condense_prompt,
+        combine_docs_chain_kwargs={"prompt": prompt},
+        return_source_documents=False,
+    )
+
+    result = chain.invoke({"question": message})
+    return result["answer"]
+
+
+def clear_memory(user_id: str) -> None:
+    if user_id in _memory_store:
+        _memory_store[user_id].clear()

plaid_client.py

@@ -0,0 +1,118 @@
+import os
+from datetime import date, timedelta
+from plaid.api import plaid_api
+from plaid.configuration import Configuration
+from plaid.api_client import ApiClient
+from plaid.model.products import Products
+from plaid.model.country_code import CountryCode
+from plaid.model.accounts_balance_get_request import AccountsBalanceGetRequest
+from plaid.model.transactions_get_request import TransactionsGetRequest
+from plaid.model.transactions_get_request_options import TransactionsGetRequestOptions
+
+# ---------- Client setup ----------
+
+def _make_client():
+    env = os.environ.get("PLAID_ENV", "sandbox")
+    host = {
+        "sandbox":     "https://sandbox.plaid.com",
+        "development": "https://development.plaid.com",
+        "production":  "https://production.plaid.com",
+    }[env]
+
+    config = Configuration(
+        host=host,
+        api_key={
+        "clientId": os.environ["PLAID_CLIENT_ID"],   # reads from .env
+        "secret":   os.environ["PLAID_SECRET"]
+        }
+    )
+    return plaid_api.PlaidApi(ApiClient(config))
+
+plaid_client = _make_client()
+
+
+# ---------- Balances ----------
+
+def get_balances(access_token: str) -> str:
+    """Returns formatted balance snapshot for the LLM prompt."""
+    request = AccountsBalanceGetRequest(access_token=access_token)
+    response = plaid_client.accounts_balance_get(request)
+
+    lines = ["USER'S CURRENT ACCOUNT BALANCES:"]
+    for account in response['accounts']:
+        name     = account['name']
+        subtype  = account['subtype']       # 'checking', 'credit card', etc.
+        current  = account['balances']['current']
+        
+        if subtype == 'credit card':
+            limit     = account['balances']['limit'] or 0
+            available = account['balances']['available'] or (limit - current)
+            lines.append(
+                f"- {name} (Visa/Credit): "
+                f"${current:.2f} owing, ${available:.2f} available"
+            )
+        else:
+            lines.append(f"- {name} (Chequing): ${current:.2f}")
+
+    return "\n".join(lines)
+
+
+# ---------- Transactions ----------
+
+def get_transactions(access_token: str, days: int = 30) -> str:
+    """Returns formatted transaction summary for the LLM prompt."""
+    end_date   = date.today()
+    start_date = end_date - timedelta(days=days)
+
+    request = TransactionsGetRequest(
+        access_token=access_token,
+        start_date=start_date,
+        end_date=end_date,
+        options=TransactionsGetRequestOptions(
+            count=100,
+            include_personal_finance_category=True
+        )
+    )
+    response = plaid_client.transactions_get(request)
+    transactions = response['transactions']
+
+    if not transactions:
+        return "No transactions found in the last 30 days."
+
+    # Python does the math — never let the LLM calculate
+    category_totals: dict[str, float] = {}
+    for txn in transactions:
+        if txn['amount'] <= 0:
+            continue   # skip deposits/refunds
+        category = txn.get('personal_finance_category', {}).get('primary', 'OTHER')
+        category_totals[category] = category_totals.get(category, 0) + txn['amount']
+
+    # Format for prompt
+    lines = [f"SPENDING SUMMARY (last {days} days):"]
+    for category, total in sorted(category_totals.items(), key=lambda x: -x[1]):
+        readable = category.replace("_", " ").title()
+        lines.append(f"- {readable}: ${total:.2f}")
+
+    lines.append(f"\nTotal spent: ${sum(category_totals.values()):.2f}")
+    lines.append(f"\nRECENT TRANSACTIONS (last 10):")
+    for txn in transactions[:10]:
+        lines.append(
+            f"- {txn['date']}  {txn['name']:<30}  ${txn['amount']:.2f}"
+        )
+
+    return "\n".join(lines)
+
+
+# ---------- Combined snapshot ----------
+
+def get_financial_snapshot(access_token: str) -> str:
+    """
+    Returns full financial context string to inject into the LLM prompt.
+    Combines balances + transaction summary.
+    """
+    try:
+        balances     = get_balances(access_token)
+        transactions = get_transactions(access_token)
+        return f"{balances}\n\n{transactions}"
+    except Exception as e:
+        return f"Unable to fetch account data: {str(e)}"

requirements.txt

@@ -0,0 +1,15 @@
+fastapi==0.111.0
+uvicorn==0.29.0
+pydantic==2.7.1
+PyJWT==2.8.0
+langchain==0.2.6
+langchain-community==0.2.6
+langchain-huggingface==0.1.0
+sentence-transformers==3.0.0
+chromadb==0.5.0
+rank_bm25==0.2.2
+supabase==2.5.0
+plaid-python==16.2.0
+python-dotenv==1.0.1
+einops==0.8.0
+huggingface-hub>=0.24.0