Shadow Credit - Avaliação de Crédito por IA para PMEs Indianas
pranavpanchal1326/shadow-credit
Crédito bancário para pequenos negócios sem documentação formal
Ver no GitHubSistema completo de análise de crédito para microempresas informais indianas que transforma documentos informais (WhatsApp, fotos de recibos, cadernetas manuscritas) em relatórios de crédito em 90 segundos. Coordena 7 agentes especializados (OCR multilíngue, análise de WhatsApp, scoring ML, verificação RBI) com orquestração inteligente e decisão automatizada.
Instalação
npx convez-ai pranavpanchal1326/shadow-credit1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Avaliação de crédito para lojas de conveniência (kirana) sem histórico formal
- Processamento de transações UPI/WhatsApp como sinais de saúde financeira
- Análise de ledgers manuscritos (khata books) de pequenos varejistas
- Geração de relatórios compatíveis com RBI para aprovação de crédito
Veredito

Solução impressionante e contextualizada para inclusão financeira na Índia, combinando OCR multinidicativo, processamento de linguagem natural em Hinglish e machine learning de scoring com conformidade regulatória DPDP/RBI. Excelente para instituições de microfinanças ou bancos que buscam expandir para mercados informais com automação responsável.
README
A tradução para o português deste README ainda está na fila.
🏦 Shadow Credit
AI-Powered Credit Assessment for Indian MSMEs
Automating credit decisions for unbanked small businesses in 90 seconds
Features • Quick Start • Architecture • API • Demo
🎯 Problem Statement
380 million Indians lack access to formal credit. Traditional banks require:
- 📄 3+ years of ITR filings
- 🏛️ GST registration
- 💳 Credit history (CIBIL score)
Kirana stores and small retailers operate informally with:
- WhatsApp payment confirmations
- UPI transaction screenshots
- Handwritten ledgers (Khata books)
- No formal documentation
Shadow Credit bridges this gap by extracting financial signals from informal documents and generating bank-grade credit assessments.
✨ Features
🤖 7 Specialized AI Agents
| Agent | Function |
|---|---|
| Agent 00 | Google Maps verification — validates business existence, ratings, reviews |
| Agent 01 | OCR extraction — processes bills, UPI screenshots with Hindi support |
| Agent 02 | WhatsApp parser — classifies financial transactions from Hinglish chats |
| Agent 03 | Khata Book — parses handwritten ledger entries |
| Agent 04 | Credit Warmth Score — ML-based scoring using 7 financial signals |
| Agent 05 | Forensic Reconciliation — detects gaps, generates RBI-compliant hypotheses |
| Agent 06 | Compliance — RBI MSME checklist verification |
| Agent 07 | Credit Report — generates professional PDF memos |
🎛️ Intelligent Orchestration
- Supervisor Agent coordinates all agents with dynamic execution
- Human-in-the-loop — pipeline pauses for clarification, resumes automatically
- Real-time WebSocket streaming shows live agent progress
- Auto-decision engine: AUTO_ACCEPT / CLARIFY / FALLBACK based on confidence
🔒 Privacy & Compliance
- AES-256-GCM encryption for all sensitive data
- DPDP Act 2023 compliant — consent tracking, right-to-erasure
- Immutable audit log — database triggers prevent tampering
- No unencrypted PII stored
🚀 Quick Start
Prerequisites
- Python 3.11+
- Node.js 18+
- Docker (optional)
1. Clone & Setup Environment
git clone https://github.com/pranavpanchal1326/shadow-credit.git
cd shadow-credit
# Backend
cp backend/.env.example backend/.env
# Edit backend/.env with your API keys
2. Configure Environment Variables
# Required
MASTER_ENCRYPTION_KEY=<generate: python -c "import secrets; print(secrets.token_hex(32))">
GROQ_API_KEY=<get free key from console.groq.com>
# Optional
GOOGLE_MAPS_API_KEY=<for business verification>
3. Start Backend
cd backend
pip install -r requirements.txt
uvicorn main:app --reload --port 8000
4. Start Frontend
cd frontend
npm install
npm run dev
5. Open Application
http://localhost:3000/apply
Docker Alternative
docker-compose up
🏗️ Architecture
┌─────────────────────────────────────────────────────────────────┐
│ FRONTEND (Next.js 15) │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────────────┐ │
│ │ Apply │ │Processing│ │ Result │ │ Dashboard │ │
│ │ Form │ │ Stream │ │ Display │ │ (RM View) │ │
│ └──────────┘ └──────────┘ └──────────┘ └──────────────────┘ │
└─────────────────────────────┬───────────────────────────────────┘
│ WebSocket + REST
┌─────────────────────────────▼───────────────────────────────────┐
│ BACKEND (FastAPI) │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ SUPERVISOR AGENT │ │
│ │ Orchestrates pipeline • Decision engine • Clarification │ │
│ └──────────────────────────────────────────────────────────┘ │
│ │ │
│ ┌────────┬────────┬────────┼────────┬────────┬────────┬─────┐ │
│ │Agent 00│Agent 01│Agent 02│Agent 03│Agent 04│Agent 05│ 06 │ │
│ │ Maps │ OCR │WhatsApp│ Khata │Warmth │Forensic│Compl│ │
│ └────────┴────────┴────────┴────────┴────────┴────────┴─────┘ │
│ │ │
│ ┌──────────────────────────▼──────────────────────────────┐ │
│ │ Agent 07 — Credit Report Generator │ │
│ │ (ReportLab PDF + QR Code) │ │
│ └──────────────────────────────────────────────────────────┘ │
└─────────────────────────────┬───────────────────────────────────┘
│
┌─────────────────────────────▼───────────────────────────────────┐
│ EXTERNAL SERVICES │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────────────┐ │
│ │ Groq │ │ Google │ │ EasyOCR │ │ SQLite │ │
│ │ LLM │ │ Maps │ │ (Local) │ │ (Encrypted) │ │
│ └──────────┘ └──────────┘ └──────────┘ └──────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
📡 API Endpoints
Session Management
| Method | Endpoint | Description |
|---|---|---|
POST | /api/v1/sessions | Create new session (requires consent) |
GET | /api/v1/sessions/{id} | Fetch session status |
POST | /api/v1/sessions/{id}/analyze | Trigger analysis pipeline |
POST | /api/v1/sessions/{id}/clarify | Answer clarification question |
POST | /api/v1/sessions/{id}/export | Download PDF report |
DELETE | /api/v1/sessions/{id} | Right-to-erasure (DPDP) |
Document Ingestion
| Method | Endpoint | Description |
|---|---|---|
POST | /api/v1/ingest/whatsapp/{id} | Upload WhatsApp chat |
POST | /api/v1/ingest/upi/{id} | Upload UPI screenshot |
POST | /api/v1/ingest/bill/{id} | Upload utility bill |
POST | /api/v1/ingest/khata/{id} | Upload ledger photo |
Real-time Events
| Protocol | Endpoint | Description |
|---|---|---|
WebSocket | /ws/{session_id} | Live agent progress stream |
🎭 Demo Mode
Three pre-configured personas for testing:
| Persona | Scenario | Duration |
|---|---|---|
| Suresh | Clean approval — straightforward case | ~45 sec |
| Meena | Discrepancy detected — triggers clarification modal | ~60 sec |
| Raju | Seasonal pattern — requires analysis | ~48 sec |
# Create demo session
curl -X POST http://localhost:8000/api/v1/sessions \
-H "Content-Type: application/json" \
-d '{"demo_mode": true, "consent_given": true}'
# Trigger analysis with persona
curl -X POST "http://localhost:8000/api/v1/sessions/{session_id}/analyze?persona_id=persona02_discrepancy"
🧠 Credit Scoring Model
XGBoost-based ML model with 7 weighted signals:
| Signal | Weight | Description |
|---|---|---|
| Income Regularity | 26.6% | Consistency of monthly inflows |
| Inflow-Claim Consistency | 20.9% | WhatsApp claims vs. UPI verification |
| Business Continuity | 19.0% | Google Maps presence, reviews, tenure |
| Seasonal Patterns | 14.25% | Revenue fluctuation analysis |
| Network Reliability | 9.5% | Repeat customer transactions |
| Data Source Diversity | 4.75% | Multiple verification sources |
| Behavioral Consistency | 5.0% | Transaction timing patterns |
Credit Grade Scale:
- A+: ≥0.85 — Auto-approve
- A: ≥0.75 — High confidence
- B+: ≥0.65 — Moderate confidence
- B: ≥0.55 — Clarification needed
- C: <0.55 — Manual review
🛠️ Tech Stack
Backend
- FastAPI — async Python web framework
- Groq — LLaMA 3.3 70B for reasoning
- XGBoost + SHAP — ML scoring with explainability
- EasyOCR — offline OCR with Hindi support
- SQLite — encrypted database with WAL mode
- ReportLab — PDF generation
Frontend
- Next.js 15 — React framework
- Tailwind CSS — styling
- Radix UI — accessible components
- Zustand — state management
- React Query — data fetching
- Recharts — visualizations
📁 Project Structure
shadow-credit/
├── backend/
│ ├── agents/ # 7 AI agents + supervisor
│ ├── api/ # REST endpoints
│ ├── core/ # Security, events, AI client
│ ├── db/ # Database schema & queries
│ └── main.py # FastAPI application
├── frontend/
│ ├── app/ # Next.js pages
│ ├── components/ # React components
│ └── hooks/ # Custom hooks
└── docker-compose.yml # Container orchestration
💰 Cost
| Service | Cost |
|---|---|
| Groq API | Free (500+ calls/day) |
| EasyOCR | Free (local) |
| Google Maps | ~$0.50 (on $200 free credit) |
| Total | $0.00 |
📄 License
MIT License — see LICENSE for details.
Built for Indian MSMEs 🇮🇳
Democratizing credit access through AI