nishantnsut27/ledgerlens

Purpose and runtime

LedgerLens is a Python 3.12+ FastAPI investor-intelligence backend: it ingests annual-report PDFs, builds a searchable semantic corpus, extracts financial KPIs, and serves evidence-grounded analysis and dashboard data. The application entry point is app.py; route modules expose the HTTP surface under routes/. A lightweight dashboard is present in templates/dashboard.html and static/js/dashboard.js.

API composition

app.py assembles the FastAPI application and mounts domain route groups. The API boundary is organized by workflow: document ingestion, retrieval/chat, KPI data, database access, vector-store operations, LLM access, evaluation, and optimization.

• app.py

• routes/ingestion.py

• routes/chat_routes.py

• routes/kpi_routes.py

Document ingestion pipeline

PDF processing is a staged pipeline: parse report content, clean it, extract/preserve metadata, create semantic chunks, validate chunks, then hand records to embedding/indexing layers. This is the principal boundary between unstructured filings and normalized retrieval units.

• ingestion/pipeline.py

• ingestion/pdf_parser.py

• ingestion/chunker.py

• ingestion/document_manager.py

Vector retrieval layer

Chunk records are embedded with Jina and stored/searched in Qdrant. The vector-store adapter and index manager isolate Qdrant collection/index operations from RAG consumers. Retrieval can include similarity logic, debugging visibility, and optimization/caching enhancements.

• rag/embeddings.py

• vectorstore/qdrant_store.py

• vectorstore/index_manager.py

• rag/retriever.py

• optimization/retrieval_booster.py

RAG answer generation

For a user question, retrieval obtains relevant report chunks; context construction and prompt assembly constrain the evidence passed to the financial-analyst LLM layer. The Groq client forms the external inference boundary, while the analyst module turns model output into grounded financial responses.

• rag/context_builder.py

• rag/prompt_assembler.py

• llm/financial_analyst.py

• llm/groq_client.py

Structured KPI workflow

KPI extraction is distinct from conversational RAG: the extractor produces schema-bound financial metrics and the store persists/retrieves them for analytics. Sample persisted KPI and vector artifacts under data/ suggest local fixtures or seeded data, not the primary service boundary.

• kpi/extractor.py

• kpi/schema.py

• kpi/store.py

• data/kpi_records/apple_2024.json

Persistence and external infrastructure

PostgreSQL/Supabase is accessed through the database connection, models, and repository layers; it holds structured KPIs and related durable application data. Qdrant is the semantic index. Groq supplies Llama-3/Mixtral inference, Jina AI supplies embeddings, and PyMuPDF4LLM is the declared PDF parsing technology. Credentials and service endpoints are environment-driven.

• database/connection.py

• database/models.py

• database/repository.py

• .env.example

Quality and performance controls

Evaluation modules measure hallucination, prompts, and retrieval quality. Semantic and embedding caches reduce repeated LLM/embedding work; these sit beside, rather than inside, the primary ingestion-to-answer path.

• evaluation/hallucination_test.py

• evaluation/retrieval_metrics.py

• optimization/semantic_cache.py

• optimization/embedding_cache.py