{"slug": "gsoc-2026-final-report-ai-powered-loan-contract-analysis-for-the-mifos-ecosystem", "title": "GSoC 2026 Final Report - AI-Powered Loan Contract Analysis for the Mifos Ecosystem", "summary": "A GSoC 2026 developer built an AI-powered loan contract analysis and summarization tool for the Mifos Initiative, part of the Apache Fineract ecosystem. The system extracts financial terms from loan contracts using large language models, validates data through a five-layer verification process, and generates plain-language summaries in English and Hindi. It supports five LLM providers, document upload with OCR, and direct integration with Mifos X, achieving 88–100% extraction accuracy.", "body_md": "This document is the final report for my **GSoC 2026** project with the [Mifos Initiative](https://github.com/openMF) (part of the Apache Fineract ecosystem). My project focused on building an **AI-Powered Loan Contract Analysis & Summarization Tool** an intelligent system that uses Large Language Models to extract financial terms from loan contracts, validate data accuracy through multi-layer verification, and generate plain-language summaries that empower borrowers to make informed decisions.\n\nThe project was built from scratch over **15 weeks** (95 working days): a **FastAPI + Python** backend powering an AI analysis pipeline, a **React 19 + Vite** frontend, full **Apache Fineract integration**, support for **5 LLM providers** (including local inference via Ollama), and **document upload with OCR** all production-ready with Docker, CI/CD, and comprehensive testing.\n\nNote\n\n**Accepted GSoC Proposal (Reference)**\nIf you'd like a concrete example of a strong proposal — structure, milestones, and approach:\n[View my accepted GSoC 2026 proposal (PDF) »](https://summerofcode.withgoogle.com/media/user/b45ca60ade54/proposal/gAAAAABqiY-IHyS3wb8po_t6ek9Jv4JpYJtctTtaRIjgq6ZAmGIN_uqACKRehGQPbO_EnoJnn-elATeHtios2CansItUcaWO2bJf1sHUdmwnru-fHOPWi3Y=.pdf)\n\nTip\n\n**All my contributions:**\n[Browse all commits by me »](https://github.com/hopessugar/mifos-loan-summarizer/commits/main) · [View the full repository »](https://github.com/hopessugar/mifos-loan-summarizer)\n\n[Project Overview](#-project-overview)[Project Timeline](#-project-timeline)[Architecture](#-architecture)[Phase 1 — AI Extraction & Analysis Pipeline](#-phase-1--ai-extraction--analysis-pipeline-weeks-15)[Phase 2 — Apache Fineract Integration](#-phase-2--apache-fineract-integration-weeks-611)[Phase 3 — Document Upload & OCR](#-phase-3--document-upload--ocr-weeks-1215)[Demos](#-demos)[Technical Highlights](#-technical-highlights)[Key Metrics](#-key-metrics)[Challenges & Learnings](#-challenges--learnings)[Documentation](#-documentation)[Future Work](#-future-work)[Conclusion](#-conclusion)\n\nMillions of borrowers worldwide especially in developing economies — sign loan agreements they don't fully understand. Complex legal language, hidden fees, predatory clauses, and language barriers prevent informed decision-making, driving financial exclusion and debt traps.\n\nAn AI-powered system that takes a loan contract (pasted text, uploaded PDF/DOCX, or pulled directly from Mifos X / Apache Fineract) and delivers:\n\n| Capability | What it does |\n|---|---|\n🔍 Smart Extraction |\nExtracts 20+ financial entities (rates, fees, penalties, terms) with 88–100% accuracy |\n✅ 5-Layer Validation |\nLevenshtein matching, TF-IDF cosine similarity, numerical cross-check, EMI math verification, hallucination detection |\n⚠️ Risk Scoring |\n0–10 risk scale with predatory lending detection, borrower protection scoring, and negotiation tips |\n📝 Plain-Language Summary |\nClear, borrower-friendly summaries in English & Hindi |\n💬 WhatsApp Export |\nCompact <300-char summary for easy mobile sharing |\n🔌 Fineract Integration |\nDirect data pull from Mifos X — bypasses LLM extraction for 100% accurate structured data |\n📄 Document Upload |\nPDF, DOCX, TXT, and image uploads with OCR (Tesseract) |\n🤖 5 LLM Providers |\nGemini, Groq, Ollama (local), Cerebras, HuggingFace — with timeout-based automatic fallback |\n\n15 Weeks · 95 Days · From Zero to Production-Ready AI System\n\nCore AI pipeline: extraction, validation, risk scoring, summarization, React frontend, CI/CD\n\nBuilt the entire AI analysis engine from scratch a multi-stage async pipeline that takes raw loan contract text and produces structured, validated financial data with confidence scores, risk analysis, and borrower-friendly summaries.\n\n| Area | What was built |\n|---|---|\nFastAPI Backend |\nREST API skeleton, routers, middleware (CORS, logging, rate limiting), async request handling |\nPydantic Schemas |\n`LoanAgreementSchema` with 20+ typed financial entity fields, request/response models |\nLLM Provider Registry |\nPluggable provider system supporting Gemini, Groq, Ollama, Cerebras, HuggingFace with retry logic |\nExtraction Pipeline |\nPrompt engineering for structured JSON extraction, 3-tier extraction path (Instructor / Native JSON / Raw), provider-aware routing |\nContract Segmentation |\n3 strategies header-based regex, NLTK sentence-based, TF-IDF semantic chunking — with adaptive selection |\n5-Layer Validation |\nLevenshtein fuzzy matching (80% threshold), TF-IDF cosine similarity, numerical cross-check, EMI math verification (`Decimal` -based), hallucination detection |\nRisk Analysis |\n0–10 risk scoring, RBI-guideline-based thresholds, predatory lending detection, default clause classification (standard vs. predatory) |\nFinancial Calculator |\nReducing balance & flat rate EMI formulas, total cost calculation — all using Python `Decimal` for financial precision |\nSummarizer |\nLLM-powered plain-language summaries (EN/HI), WhatsApp-ready <300-char export, language-aware provider routing |\nInput Sanitization |\nPrompt injection detection & prevention, delimiter-based prompt hardening |\nReact Frontend |\n`ContractInput` , `AnalysisView` , `EntityCard` , `RiskBadge` , `ExportButton` , loading states, error boundaries |\nTesting |\n95+ unit & integration tests, 85% coverage, security tests for prompt injection |\nCI/CD |\nGitHub Actions (CI, CD, Security scanning — Bandit, Safety, npm audit, Trivy) |\nDocker |\nMulti-stage Dockerfiles, docker-compose with health checks, production-ready config |\n\n**📋 Key Commits (Phase 1) - click to expand**\n\n| Commit | Description |\n|---|---|\n`1cd4940` |\n\n`6d51b63`\n\n`78f5d5b`\n\n`c8ade26`\n\n`72cd7e8`\n\n`3a93b6a`\n\n`7b796ad`\n\n`697b4aa`\n\n`39ab329`\n\n`b68076e`\n\n`bdd1a65`\n\nDirect Mifos X integration, Ollama local LLM support, production hardening, comprehensive documentation\n\nIntegrated the app directly with Apache Fineract / Mifos X. The key architectural insight: **bypass LLM extraction entirely** for Fineract products — build the `LoanAgreementSchema`\n\ndirectly from Fineract's structured JSON (100% accurate, no hallucination risk), and use the LLM only for human-readable summary generation.\n\nAlso built a complete **Ollama integration** (325-line native provider) using Ollama's HTTP API directly — enabling fully local, offline, privacy-preserving loan analysis.\n\n| Area | What was built |\n|---|---|\nFineract Service |\n`fineract_service.py` (711 lines) — async HTTP client with connection pooling, caching (5-min TTL), retry logic (tenacity), SSL config (3 modes), Basic Auth + tenant headers |\nDirect Schema Builder |\n`build_schema_from_fineract()` — maps every Fineract field to `LoanAgreementSchema` directly from JSON. Interest rate normalization (per-period → annual), charge classification (7 fee categories), down payment handling, grace periods, multi-disbursement support |\nCharge Classification |\nMaps Fineract charge arrays to specific fee fields using `chargeTimeType` + name-based classification: processing, late, prepayment, insurance, admin, other — with percentage vs. flat distinction |\nAPI Endpoints |\n`GET /loanproducts` (cached list), `GET /loanproducts/{id}` (product detail), `POST /loanproducts/refresh` (cache invalidation), enhanced `/health` with Fineract connectivity status |\nCurrency Utilities |\n50+ ISO 4217 currency codes → display symbols, `format_currency()` and `format_currency_precise()` — multi-currency support (INR, USD, KES, etc.) |\nOllama Provider |\n325-line native provider `generate_native()` (streaming text), `generate_json()` (Ollama JSON mode), auto-model-pull, health check, 120s timeout for local inference |\nLoan Simulator |\n`/simulator` endpoint full amortization schedule with month-by-month EMI breakdown, flat/reducing rate support, `Decimal` precision |\nFrontend |\n`MifosProductPicker` component auto-fetch products, loading/error/retry states, refresh button, product count, graceful Fineract-down fallback |\nTesting |\n`test_fineract_service.py` (444 lines) + `test_integration_fineract.py` (416 lines) — 19 test classes covering SSL, auth, API, caching, health check |\nDocumentation |\n`CONTRIBUTING.md` (550 lines), `DOCKER_SETUP.md` (693 lines), `LLM_PROVIDER_COMPARISON.md` (531 lines), `LOCAL_MODEL_SETUP_GUIDE.md` (1,029 lines) |\n\n**📋 Key Commits (Phase 2) — click to expand**\n\n| Commit | Description |\n|---|---|\n`c17e72a` |\n\n`bdcc3f6`\n\n`d0d0236`\n\n`999b01e`\n\n`e20c2cd`\n\n`2274ba0`\n\n`c1bb952`\n\n`75de5a5`\n\n`2237504`\n\nPDF/DOCX/image upload, Tesseract OCR, frontend polish\n\nBuilt a complete document processing pipeline — users can upload loan agreements as files (PDF, DOCX, TXT, or images) and the system automatically extracts the text (with OCR for scanned documents) before feeding it through the existing AI analysis pipeline. Also wrote 4 comprehensive documentation guides totaling 2,800+ lines.\n\n| Area | What was built |\n|---|---|\nPDF Service |\n`pdf_service.py` (473 lines) — PyMuPDF text extraction, Tesseract OCR fallback (per-page, 300 DPI), DOCX (paragraphs + tables), TXT (multi-encoding fallback chain), image OCR (PNG/JPG) |\nText Cleanup |\n`_clean_extracted_text()` — null byte stripping, form feed → newline, hyphenated line-break repair (`agree-\\nment` → `agreement` ), whitespace normalization |\nFile Validation |\nExtension check, 10MB size limit, empty file detection, encrypted PDF detection, `.doc` vs `.docx` format guidance |\nAPI Endpoint |\n`POST /analyze/pdf` — `multipart/form-data` , `UploadFile` , rate-limited (10/min), specific error messages per failure mode |\nReact Component |\n`PdfUpload` (318 lines) — drag-and-drop zone with visual feedback, file type badges (color-coded by format), size display, upload progress bar, loading/error states |\nFrontend Integration |\nTab-based input switching (paste / upload / Fineract), `analyzeFile()` hook, proper state cleanup on tab switch |\nClipboard Paste |\nImage paste from clipboard via Clipboard API → OCR → analysis |\nDocker OCR |\n`tesseract-ocr` + `tesseract-ocr-hin` installed in backend container for out-of-box OCR support |\n\n**📋 Key Commits (Phase 3) — click to expand**\n\n| Commit | Description |\n|---|---|\n`b68076e` |\n\nPaste a loan contract → AI extracts 20+ entities → 5-layer validation → risk score → plain-language summary\n\nSelect a loan product from Mifos X → schema built directly from Fineract JSON (no LLM extraction) → validated → summarized\n\nUpload a PDF/DOCX/image → text extracted (with OCR for scanned docs) → full AI analysis pipeline\n\nThe most impactful architectural decision was creating **two separate analysis paths**:\n\n```\nPath A: Text/PDF  →  LLM Extraction  →  Validation  →  Summary   (user-uploaded contracts)\nPath B: Fineract  →  Direct JSON Map →  Validation  →  Summary   (Mifos X products)\n```\n\nPath B **bypasses LLM extraction entirely** every value comes from Fineract's authoritative API. The LLM is used only for summary generation (the one thing it excels at). This gives **100% data accuracy** with **2–3× faster** response times.\n\nAfter a brutal debugging session (Day 34) where floating-point arithmetic turned `Rs. 8,885`\n\ninto `8884.999999999998`\n\n, the entire financial calculation layer was rewritten to use Python's `Decimal`\n\nmodule.\n\n**Rule: never use float for money.** This is non-negotiable for financial applications.\n\nInstead of fighting `instructor`\n\ncompatibility, I built a native Ollama provider using Ollama's HTTP API directly:\n\n**Streaming generation** via`httpx.stream`\n\n(no timeouts on slow hardware)**JSON mode**(`format: \"json\"`\n\n) for**95%+ parse success rate** vs. ~70% with prompt-based JSON**Auto-model-pull** on first run set`OLLAMA_MODEL=llama3.2:latest`\n\nand the app handles the rest**Detailed health check** reports running status, model availability, installed models\n\nThe risk analysis system distinguishes between **standard** default triggers (\"miss 3 payments\") and **predatory** ones (\"at lender's sole discretion\"). Only predatory clauses increase the risk score.\n\nFineract's flat charge array is automatically classified into **7 fee categories** using a combination of `chargeTimeType`\n\ncodes and name-based pattern matching with percentage vs. flat distinction for each:\n\n```\ndisbursement time → processing_fee\noverdue time      → late_fee (flat) / late_payment_interest (%)\nname: prepayment  → prepayment_penalty\nname: insurance   → insurance_fee\nname: admin       → administrative_fee\neverything else   → other_fee\n```\n\n|\n|\n\n| Layer | Technologies |\n|---|---|\nBackend |\nPython 3.11, FastAPI, Pydantic v2, httpx (async), Tenacity (retry) |\nAI/ML |\nLangChain, Instructor, NLTK, scikit-learn (TF-IDF), tiktoken |\nLLM Providers |\nGoogle Gemini, Groq, Ollama (local), Cerebras, HuggingFace Inference |\nDocument Processing |\nPyMuPDF, python-docx, Tesseract OCR, Pillow |\nFrontend |\nReact 19, Vite, Tailwind CSS, Axios, i18n |\nInfrastructure |\nDocker (multi-stage), docker-compose, Nginx, GitHub Actions |\nSecurity |\nBandit, Safety, Trivy, npm audit, API key auth, input sanitization |\nTesting |\npytest, pytest-asyncio, pytest-cov, unittest.mock |\n\n| # | Challenge | What went wrong | What I learned |\n|---|---|---|---|\n| 1 | Floating-point precision |\n`float` math turned `8885` into `8884.999999999998` . EMI validation flagged correct values as wrong. |\nNever use Python's `float` for money.`Decimal` module exists for a reason. Rewrote the entire financial calculator. |\n| 2 | Async event loop blocking |\nSync LLM API calls froze FastAPI — the whole app hung on concurrent requests. | `asyncio.to_thread()` wraps sync calls to play nice with async. Now handles 10+ concurrent requests. |\n| 3 | Prompt engineering |\nFirst prompts returned paragraphs of explanation instead of JSON. LLMs confused \"late fee\" with \"late payment interest.\" | Be painfully explicit: \"Return ONLY valid JSON.\" Include the schema in the prompt. Add disambiguation instructions. Took ~10 iterations to get 85%+ accuracy. |\n| 4 | Ollama + Instructor |\nThe `instructor` library works with OpenAI-compatible APIs but breaks with Ollama's quirks. 5–10 seconds wasted per request on failed attempts. |\nBuilt a native Ollama provider using the HTTP API directly. Ollama's `format: \"json\"` mode is far more reliable than prompt-based JSON. |\n| 5 | Docker networking |\nContainers couldn't communicate. Ollama on host unreachable from Docker backend (`localhost` resolves to the container, not the host). |\n`host.docker.internal` resolves to the host machine. Set up Docker early — not in Week 5 when the project is complex. |\n\n**Daily stand-ups** with mentor learned to communicate blockers early instead of debugging alone for hours**PR discipline** conventional commits, clear descriptions, linking to issues**Documentation as a first-class deliverable** 4 comprehensive guides totaling 2,800+ lines\n\n| Document | Lines | Description |\n|---|---|---|\n`README.md` |\n\n`CONTRIBUTING.md`\n\n`DOCKER_SETUP.md`\n\n`LLM_PROVIDER_COMPARISON.md`\n\n`LOCAL_MODEL_SETUP_GUIDE.md`\n\n`GSoC_Daily_Work_Log.md`\n\nThese are areas I'd love to see the project grow into:\n\n| Area | Description |\n|---|---|\nBatch Processing |\nAnalyze multiple contracts at once for MFIs processing loan portfolios |\nMore Languages |\nExpand to other language for global MFI coverage |\nFine-Tuned Models |\nTrain a domain-specific model for higher extraction accuracy |\nMobile App |\nReact Native or KMP client for field officers to scan contracts on-the-go |\nRegulatory Compliance |\nAuto-check against country-specific lending regulations (RBI, CFPB, etc.) |\nBorrower Dashboard |\nTrack multiple loans, compare offers, monitor risk over time |\nWebhook Notifications |\nAlert MFI admins when a high-risk loan product is detected |\n\nThis summer, I built a production-ready AI system **from scratch** from the first `git init`\n\nto a deployed Docker application with 120+ tests, 5 LLM providers, Apache Fineract integration, OCR-powered document processing, and comprehensive documentation.\n\n**On the technical side**, I learned to ship real software: async Python at scale, LLM reliability engineering (prompt iteration, structured output, fallback chains), financial precision (`Decimal`\n\n, not `float`\n\n), multi-provider architecture, and the discipline of CI/CD and security scanning from Day 1.\n\n**On the human side**, I learned to work in the open: daily stand-ups, clear commit messages, scope negotiation, and writing documentation that helps the next contributor. I kept a [95-day engineering diary](https://github.com/hopessugar/mifos-loan-summarizer/blob/main/GSoC_Daily_Work_Log.md) that documents every decision, failure, and lesson including the ones I'm not proud of.\n\nThe project matters because **financial literacy shouldn't require a law degree**. If this tool helps even one borrower spot a predatory clause or understand the true cost of their loan, it was worth building.\n\nHuge thanks to:\n\n**Akshat Sharma** and**Rahul Goel** for fast feedback loops, honest design reviews, and the patience to say \"start simple\" when I was overengineeringfor building the infrastructure that makes financial inclusion possible[Mifos Initiative](https://mifos.org/)for the opportunity, structure, and funding that made this work possible[Google Summer of Code](https://summerofcode.withgoogle.com/)the core banking platform this tool integrates with[Apache Fineract](https://fineract.apache.org/)- The open-source LLM ecosystem Gemini, Groq, Ollama, and the communities behind them\n\n**Built with ❤️ during GSoC 2026**\n\n[🔗 Repository](https://github.com/hopessugar/mifos-loan-summarizer) · [📋 Daily Work Log](https://github.com/hopessugar/mifos-loan-summarizer/blob/main/GSoC_Daily_Work_Log.md) · [📚 API Docs](https://github.com/hopessugar/mifos-loan-summarizer/blob/main/README.md#-documentation) · [📄 GSoC Proposal](https://summerofcode.withgoogle.com/media/user/b45ca60ade54/proposal/gAAAAABqiY-IHyS3wb8po_t6ek9Jv4JpYJtctTtaRIjgq6ZAmGIN_uqACKRehGQPbO_EnoJnn-elATeHtios2CansItUcaWO2bJf1sHUdmwnru-fHOPWi3Y=.pdf)", "url": "https://wpnews.pro/news/gsoc-2026-final-report-ai-powered-loan-contract-analysis-for-the-mifos-ecosystem", "canonical_source": "https://gist.github.com/hopessugar/6000051c4b8f669bf2098f1ace88736b", "published_at": "2026-08-22 13:34:35+00:00", "updated_at": "2026-08-25 08:44:20.786845+00:00", "lang": "en", "topics": ["artificial-intelligence", "large-language-models", "ai-products", "ai-tools", "developer-tools"], "entities": ["Mifos Initiative", "Apache Fineract", "FastAPI", "React", "Gemini", "Groq", "Ollama", "Cerebras"], "alternates": {"html": "https://wpnews.pro/news/gsoc-2026-final-report-ai-powered-loan-contract-analysis-for-the-mifos-ecosystem", "markdown": "https://wpnews.pro/news/gsoc-2026-final-report-ai-powered-loan-contract-analysis-for-the-mifos-ecosystem.md", "text": "https://wpnews.pro/news/gsoc-2026-final-report-ai-powered-loan-contract-analysis-for-the-mifos-ecosystem.txt", "jsonld": "https://wpnews.pro/news/gsoc-2026-final-report-ai-powered-loan-contract-analysis-for-the-mifos-ecosystem.jsonld"}}