⛏️

ASX Mining Financial Chatbot

ASX Mining Financial Chatbot · LangGraph Multi-Agent · FastAPI + Next.js · AWS EC2 + Vercel

Live — mines.melailab.com

About the Project

Mines Financial is a production-style, multi-agent RAG chatbot that answers financial questions about the annual reports of five major ASX-listed mining companies — BHP, Rio Tinto (RIO), Fortescue (FMG), Mineral Resources (MIN), and Northern Star (NST) — covering fiscal years FY2023 through FY2025.

The system is built on LangGraph with a supervisor graph that orchestrates three specialised agents in parallel: a hybrid-retrieval sub-graph that fans out across companies, a Tavily news agent for real-time market context, and a ReAct calculator agent for financial arithmetic. All answers are validated through a guardrails node before reaching the user.

A vision-aware ingest pipeline uses PyMuPDF to identify table-dense pages and Google Gemini to extract structured financial data from them — capturing numbers that plain text extraction misses. The backend is containerised with Docker, deployed on AWS EC2 with CI/CD, while the Next.js 15 frontend is on Vercel with its own CI/CD pipeline.

LangGraph

FastAPI

Next.js 15

PostgreSQL

ChromaDB

BM25

Jina AI

AWS EC2

Vercel

5 × 3

Companies × Years

BHP, RIO, FMG, MIN, NST — FY2023 to FY2025 annual reports

Hybrid

Dense + BM25 Retrieval

Jina vector search + keyword index fused per query for maximum recall

2-Tier

Semantic Cache

L1 direct hit at ≥0.95 · L2 context seed at ≥0.80 — skips redundant LLM calls

Graph Execution Flow

supervisorretrieval sub-graph● cache / guardrails⏸ interrupt

supervisor

compress_context

Trim conversation history when context grows long

supervisor

memory

Semantic cache lookup — L1 direct hit (≥0.95) or L2 context seed (≥0.80)

checkpoint

supervisor

retrieve_decision

Classify query: needs retrieval, clarification, or cached answer?

supervisor

clarify

Interrupt — ask user for clarification before expensive work

interrupt

supervisor

dynamic_tool_selector

LLM router: decide retrieval / news / calculator flags

retrieval

retrieval_agent [sub-graph]

query_rewrite → fan-out per company → merge → grade_docs → synthesize → grade_answer (auto-retry ×2)

supervisor

news_agent

Tavily web search for recent company news

supervisor

aggregate

Merge retrieval + news results into one context block

supervisor

calculator_agent

ReAct agent — growth rate, ratio, average tools operating on retrieved numbers only

supervisor

guardrails

Validate answer length and quality — failures route to fallback

checkpoint

supervisor

answer

Format final answer + chart data + source citations → stream to frontend

Backend Deployment

AWS EC2

Dockerised FastAPI + PostgreSQL on EC2, custom domain via Route 53

CI/CD

GitHub Actions — build, push to ECR, SSH deploy on every push to main

PostgreSQL 16

LangGraph checkpointer persists full thread state; survives restarts

LangGraph Supervisor

Multi-agent graph with sub-graph for retrieval, real-time SSE streaming

Frontend Deployment

Vercel

Next.js 15 + React 19, deployed to mines.melailab.com

CI/CD

Automatic Vercel deploys on every push — preview + production environments

Chart.js

Renders financial visualisations from structured chart data in LLM answers

SSE Streaming

Node-level progress streamed from backend; users see graph execution live

Key Features

Multi-Agent Supervisor Graph

A LangGraph state machine orchestrates three independent agents — retrieval, calculator, and news — deciding at runtime via an LLM router which combination to invoke for each query.

Hybrid Dense + BM25 Retrieval

Jina dense vector search (ChromaDB) and BM25 keyword search run in parallel per query, then their results are deduped and re-ranked — maximising recall across structured financial tables and free-form narrative text.

Vision-Aware PDF Ingest

PyMuPDF filters pages likely to contain tables, then Google Gemini vision extracts structured row/column data from those pages — capturing numbers that plain text extraction would miss entirely.

Two-Tier Semantic Cache

Past answers are embedded and stored. At L1 (≥0.95 similarity) the cached answer is returned directly; at L2 (≥0.80) it seeds the context to speed up synthesis — reducing redundant LLM calls significantly.

Adaptive Clarification & Retry

When a query is ambiguous the graph interrupts and asks the user before doing any expensive work. The retrieval sub-graph also retries automatically (up to 2×) when graded docs or graded answers fall below quality thresholds.

Calculator Agent + Chart Data

A ReAct agent equipped with financial math tools (growth rate, ratio, average) operates strictly on retrieved numbers. The answer node also extracts structured chart data so the frontend can render Chart.js visualisations.

Guardrails Validation

Every answer path passes through a validation node that checks length and quality before delivery. Failed checks route to a graceful fallback — no hallucination slips through to the user unchecked.

SSE Streaming + Persistent Threads

Server-Sent Events stream node-level graph progress to the frontend in real time. PostgreSQL checkpointing persists full conversation state per thread — sessions are resumable across server restarts.

Evaluation Framework

Four eval suites (routing, retrieval, calculation, boundary) with mock and real modes. Mock mode validates evaluator logic with no API cost; real mode invokes live LLM and retrieval nodes with a configurable cost cap.

Full Tech Stack

LangGraph 0.6+

Multi-agent graph orchestration

LangChain 0.3+

LLM integration & tooling

FastAPI

Python REST + SSE backend

Next.js 15

React 19 frontend

PostgreSQL 16

Conversation checkpointing

ChromaDB

Dense vector store

BM25 (rank-bm25)

Keyword retrieval index

Jina AI

jina-embeddings-v3

Gemini Vision

PDF table extraction (ingest)

OpenAI GPT-4o

Primary LLM

Tavily

Real-time news search

PyMuPDF

PDF page filtering & rendering

Docker

Containerised backend

AWS EC2

Backend deployment

Vercel

Frontend deployment

LangSmith

Tracing & observability

Chart.js

Financial data visualisation

Python package manager

Try it Live

Ask about BHP's revenue, compare FMG vs RIO margins, or query Northern Star's gold production across three fiscal years

Open Live Demo View on GitHub