Finlens

AI-powered financial document intelligence platform with 11 agent tools, MCP server, and ERP connectivity.

FinLens is a financial operations copilot that lets finance teams upload documents — PDFs, Excel workbooks, CSVs — and ask questions in plain English. An ADK agent routes each question to the right tool: retrieval, calculation, comparison, ratio analysis, charting, dashboards, SEC benchmarking, cross-document analysis, audience-aware summarization, scenario modeling, or QuickBooks data. Every answer is grounded in your documents, cited to a specific file and page, and scored for confidence. In v3, FinLens also exposes all capabilities as an MCP server so Claude Desktop, Cursor, and custom agents can use them directly.

---

Features

Document Intelligence — Upload PDFs, Excel (.xlsx/.xls), and CSV files (up to 10 files, 20MB each). Natural language Q&A with source citations. Cross-document analysis across files, quarters, and companies. Audience-aware summarization for executives, technical teams, or board presentations.

Analysis Tools — Financial calculations (burn rate, runway, margins, growth rates). Financial ratios (current ratio, debt-to-equity, ROE). Cross-document comparisons across time periods or entities. Scenario generation with what-if modeling.

Visualizations — Plotly charts (bar, line, pie, waterfall) with dark theme. Auto dashboards that surface key metrics from uploaded documents.

External Data — SEC EDGAR benchmarking against any US public company via XBRL. QuickBooks Online connector for live P&L, balance sheet, and cash flow (demo + live mode).

Platform — MCP server with 14 tools for Claude Desktop, Cursor, or any MCP-compatible agent. Agentic RAG with 11 specialized tools routed by Google ADK. Cross-encoder reranking, confidence scoring, relevance filtering, and graceful fallback to v1 RAG.

---

Architecture

Documents (PDF, Excel, CSV) --> Parse --> Chunk --> Embed --> ChromaDB <-- Reranker
                                                                |
Question --> ADK Agent (Gemini 2.5 Flash) --> selects from 11 tools:
  |-- Search Documents           |-- Chart Generator
  |-- Calculator                 |-- Dashboard
  |-- Comparator                 |-- SEC Benchmark
  |-- Financial Ratios           |-- Cross-Doc Analysis
  |-- Audience Summarizer        |-- Scenario Generator
  |-- QuickBooks Connector
                    |
            Answer + Sources + Confidence Score + Charts

MCP Server (14 tools) <-- Claude Desktop / Cursor / Custom Agents

---

Tech Stack

Layer	Technology	Purpose
Frontend	Streamlit	Chat UI with sidebar document management
LLM	Google Gemini 2.5 Flash	Answer generation, structured output, tool routing
Agent Framework	Google ADK	Hierarchical agent with 11 specialized tools
MCP	MCP SDK (mcp>=1.0.0)	Expose tools to Claude Desktop, Cursor, custom agents
Orchestration	LangChain	RAG pipeline, document loaders, text splitters
Reranker	cross-encoder/ms-marco-MiniLM-L-6-v2	Reranks retrieved chunks for precision (22MB, local)
Embeddings	HuggingFace all-MiniLM-L6-v2	384-dim vectors, runs locally
Vector Store	ChromaDB	Local persistence, cosine similarity search
Charts	Plotly	Interactive financial visualizations with dark theme
PDF Parsing	PyPDF	Page-level text extraction with metadata
Spreadsheets	openpyxl + pandas	Excel and CSV ingestion with structured extraction
Public Data	SEC EDGAR XBRL API	Free benchmark data for all US public companies
ERP	QuickBooks Online API	Live financial data (demo + production)
Environment	python-dotenv	Secure API key management

---

Quick Start

1. Clone and set up

git clone https://github.com/pranavkarthik/finlens.git
cd finlens
python -m venv venv
source venv/bin/activate   # Windows: venv\Scripts\activate
pip install -r requirements.txt

2. Configure API key

Get a free key at Google AI Studio, then:

cp .env.example .env
# Edit .env and add: GOOGLE_API_KEY=your-gemini-api-key-here

3. Run the app

streamlit run src/app.py

The app opens at http://localhost:8501. Upload a document and start asking questions.

4. (Optional) Start the MCP server

python mcp_server.py

See the MCP Server section for connecting Claude Desktop or Cursor.

---

MCP Server

FinLens exposes 14 tools via the Model Context Protocol so external agents can use them without the Streamlit UI: 11 analysis tools (search, calculate, compare, ratios, chart, dashboard, benchmark, cross-doc, summarize, scenarios, QuickBooks) and 3 document management tools (upload, list, delete).

Claude Desktop — Add to claude_desktop_config.json:

{
  "mcpServers": {
    "finlens": {
      "command": "python",
      "args": ["/path/to/finlens/mcp_server.py"],
      "env": { "GOOGLE_API_KEY": "your-gemini-api-key" }
    }
  }
}

Cursor — Add the same server configuration in Cursor's MCP settings. The server communicates over stdio and works with any MCP-compatible client. A sample config is included at mcp_config.json.

---

Example Queries

Retrieval — "What was total revenue in Q3 2025?" / "List all line items under operating expenses."

Calculations — "What is the gross margin percentage from this P&L?" / "Calculate the burn rate from this balance sheet and P&L."

Comparisons — "Compare Q2 vs Q3 revenue across both uploaded reports." / "How did COGS change between the two quarters?"

Ratios — "What is the current ratio from this balance sheet?" / "Calculate debt-to-equity and return on equity."

Charts — "Show me a bar chart of revenue vs expenses." / "Plot the trend of operating income across quarters."

Dashboards — "Give me a dashboard of key metrics from this P&L."

SEC Benchmarking — "How does our gross margin compare to Apple's?" / "Benchmark our revenue growth against Microsoft."

Cross-Document Analysis — "What trends do you see across all three quarterly reports?" / "Identify the largest variance across all uploaded documents."

Audience Summarization — "Summarize this P&L for a board presentation." / "Give me a technical breakdown suitable for the FP&A team."

Scenario Generation — "What happens to net income if revenue drops 15%?" / "Model a scenario where COGS increases by 10% next quarter."

QuickBooks — "Pull the P&L from QuickBooks for last quarter." / "Compare our QuickBooks balance sheet to the uploaded PDF."

---

Configuration

All parameters are centralized in src/config.py:

Parameter	Default	Description
GOOGLE_API_KEY	(env)	Gemini API key, loaded from .env
LLM_MODEL	gemini-2.5-flash	Gemini model for answer generation
LLM_TEMPERATURE	0.1	Low = deterministic and factual
LLM_MAX_TOKENS	1024	Maximum response length
AGENT_MODEL	gemini-2.5-flash	ADK root agent model
AGENT_ENABLED	True	Set False to fall back to v1 RAG-only mode
RERANKER_MODEL	cross-encoder/ms-marco-MiniLM-L-6-v2	Cross-encoder reranker model
RERANKER_ENABLED	True	Toggle reranking on/off
RERANK_TOP_N	3	Chunks kept after reranking
EMBEDDING_MODEL	all-MiniLM-L6-v2	Sentence transformer for embeddings
EMBEDDING_DIMENSION	384	Embedding vector dimensionality
CHUNK_SIZE	1000	Characters per text chunk
CHUNK_OVERLAP	200	Overlap between consecutive chunks
TOP_K	5	Chunks retrieved per query
SIMILARITY_THRESHOLD	0.3	Minimum cosine similarity to include a chunk
MAX_FILE_SIZE_MB	20	Per-file upload limit
MAX_FILES	10	Maximum documents per session
ALLOWED_EXTENSIONS	.pdf, .xlsx, .xls, .csv	Accepted file types
PERSIST_DIR	chroma_db/	ChromaDB storage directory
COLLECTION_NAME	finlens_docs	ChromaDB collection name
QBO_ACCESS_TOKEN	(env)	QuickBooks OAuth access token
QBO_REALM_ID	(env)	QuickBooks company ID
QBO_REFRESH_TOKEN	(env)	QuickBooks OAuth refresh token
QBO_CLIENT_ID	(env)	QuickBooks app client ID
QBO_CLIENT_SECRET	(env)	QuickBooks app client secret
QBO_ENVIRONMENT	sandbox	sandbox for demo, production for live
APP_NAME	FinLens	Application display name
APP_TAGLINE	AI Financial Ops Copilot	Subtitle shown in UI
APP_VERSION	3.0.0	Current release version

---

Project Structure

finlens/
├── src/
│   ├── app.py                    # Streamlit entry point
│   ├── agent.py                  # ADK agent and tool routing
│   ├── ingest.py                 # Document ingestion (PDF + spreadsheets)
│   ├── query.py                  # RAG query engine (v1 fallback)
│   ├── reranker.py               # Cross-encoder reranking
│   ├── prompts.py                # System prompt templates
│   ├── config.py                 # All tunable parameters
│   ├── spreadsheet_parser.py     # Excel/CSV parsing
│   └── tools/
│       ├── _retrieval_helpers.py  # Shared retrieval utilities
│       ├── schemas.py            # Pydantic output schemas
│       ├── search_documents.py   # RAG retrieval tool
│       ├── calculator.py         # Financial calculations
│       ├── comparator.py         # Cross-document comparisons
│       ├── ratios.py             # Financial ratio computation
│       ├── chart.py              # Plotly chart generation
│       ├── dashboard.py          # Auto key-metrics dashboard
│       ├── benchmark.py          # SEC EDGAR benchmarking (wrapper)
│       ├── sec_edgar.py          # SEC EDGAR API client
│       ├── confidence.py         # Confidence scoring
│       ├── cross_doc.py          # Cross-document analysis
│       ├── summarize.py          # Audience-aware summarization
│       ├── scenarios.py          # Scenario generation
│       ├── quickbooks.py         # QuickBooks Online connector
│       └── qbo_tool.py           # QuickBooks agent tool wrapper
├── mcp_server.py                 # MCP server (14 tools)
├── mcp_config.json               # Sample MCP client config
├── docs/                         # Product documentation (phases 1-6, research, decisions)
├── sample_docs/                  # Sample PDFs, Excel, CSV for demo
├── scripts/                      # Utility scripts
├── tests/                        # Test suites (core, v2, v3, edge cases)
├── prototype/                    # Interactive design prototype
├── Dockerfile
├── requirements.txt
├── .env.example
└── README.md

---

How It Works

1. Ingest — Documents are parsed by type: PDFs page-by-page with PyPDF; Excel and CSV files with openpyxl and pandas. All content is split into overlapping 1000-char chunks, embedded with all-MiniLM-L6-v2, and stored in ChromaDB with source metadata.

2. Route — The ADK agent analyzes your question and selects the right tool from 11 options. Retrieval queries go to Search Documents; math goes to Calculator; "compare X vs Y" to Comparator; "what if revenue drops 15%" to Scenario Generator; and so on.

3. Retrieve and Rerank — For retrieval-based tools, the question is embedded, matched against stored chunks via cosine similarity, and the top-k results are reranked by the cross-encoder. Only the top N reranked chunks become context.

4. Analyze — The selected tool processes context. Calculations extract values and compute metrics. Ratios apply standard formulas. Cross-doc analysis correlates data across files. Scenarios model hypothetical changes.

5. Confidence — A heuristic score is computed from source quality, answer type, hedging language, and retrieval relevance. Low-confidence answers are flagged transparently.

6. Respond — Gemini 2.5 Flash generates a grounded response with document and page citations. Structured output via Pydantic ensures typed results. Charts and dashboards render inline when applicable.

---

QuickBooks Integration

FinLens connects to QuickBooks Online to pull live financial data into your analysis.

Demo mode — Set QBO_ENVIRONMENT=sandbox in .env. Uses QuickBooks sandbox data so you can test without connecting a real company.

Live mode — Set QBO_ENVIRONMENT=production and provide OAuth credentials (QBO_CLIENT_ID, QBO_CLIENT_SECRET, QBO_ACCESS_TOKEN, QBO_REFRESH_TOKEN, QBO_REALM_ID). Pulls your actual P&L, balance sheet, and cash flow on demand.

The agent routes QuickBooks queries automatically — ask "Pull the P&L from QuickBooks" or "Compare QuickBooks data to the uploaded PDF."

---

Version History

Version	What Changed
v1.0	RAG-powered document Q&A with source citations. LangChain, ChromaDB, Gemini 2.0 Flash. PDF upload, relevance filtering, confidence scoring.
v2.0	Agent layer with 7 specialized tools. Google ADK, cross-encoder reranking, SEC EDGAR benchmarking, Plotly charts, dashboards, financial ratios. Gemini 2.5 Flash. Graceful fallback to v1.
v3.0	Platform layer. 11 agent tools (+cross-doc, summarizer, scenarios, QuickBooks). MCP server with 14 tools for Claude Desktop / Cursor. Excel/CSV ingestion. QuickBooks Online integration. 15-competitor market research drove feature selection.

---

Documentation

Detailed product documentation lives in /docs/:

• Phase 1: Discovery & Strategy Brief — Market research, competitive landscape, positioning
• Phase 2: Product Requirements Document — User stories, technical architecture, edge cases
• Phase 3: Design Specification — Wireframes, visual design, UX flows
• Phase 4: Build Documentation (v1) — v1 implementation details and build log
• Phase 5: Launch Strategy — Go-to-market plan, launch checklist
• Phase 6: v2 Build Documentation — Agent layer implementation and tool design
• v3 Market Research — 15-competitor analysis, feature prioritization matrix
• Decision Log — All architectural decisions with rationale

---

Known Limitations

• English only — Supports English-language documents
• Text-based PDFs only — Scanned/image-based PDFs not supported (no OCR)
• Single-user session — No authentication or multi-user support
• Table parsing — Complex table layouts in PDFs may lose structure during extraction
• Gemini free tier — Rate limited to 15 requests per minute
• SEC EDGAR US only — Benchmark data limited to US public companies
• QuickBooks OAuth — Access tokens expire and require manual refresh in live mode

---

License

MIT

---

Built by Pranav Karthikeyan