convez.ai
AgenteFinanceiroAvançado
pranavpanchal1326

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 GitHub
InicialPluginScore · de 0 a 100

Sistema 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-credit

1 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

Estrelas
8
Forks
0
Acompanhando
0
Saúde
28%
Último commit
há 7 meses
Versão
—
Issues abertas
0
Contribuidores
1

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

Python Next.js FastAPI License

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

AgentFunction
Agent 00Google Maps verification — validates business existence, ratings, reviews
Agent 01OCR extraction — processes bills, UPI screenshots with Hindi support
Agent 02WhatsApp parser — classifies financial transactions from Hinglish chats
Agent 03Khata Book — parses handwritten ledger entries
Agent 04Credit Warmth Score — ML-based scoring using 7 financial signals
Agent 05Forensic Reconciliation — detects gaps, generates RBI-compliant hypotheses
Agent 06Compliance — RBI MSME checklist verification
Agent 07Credit 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

MethodEndpointDescription
POST/api/v1/sessionsCreate new session (requires consent)
GET/api/v1/sessions/{id}Fetch session status
POST/api/v1/sessions/{id}/analyzeTrigger analysis pipeline
POST/api/v1/sessions/{id}/clarifyAnswer clarification question
POST/api/v1/sessions/{id}/exportDownload PDF report
DELETE/api/v1/sessions/{id}Right-to-erasure (DPDP)

Document Ingestion

MethodEndpointDescription
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

ProtocolEndpointDescription
WebSocket/ws/{session_id}Live agent progress stream

🎭 Demo Mode

Three pre-configured personas for testing:

PersonaScenarioDuration
SureshClean approval — straightforward case~45 sec
MeenaDiscrepancy detected — triggers clarification modal~60 sec
RajuSeasonal 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:

SignalWeightDescription
Income Regularity26.6%Consistency of monthly inflows
Inflow-Claim Consistency20.9%WhatsApp claims vs. UPI verification
Business Continuity19.0%Google Maps presence, reviews, tenure
Seasonal Patterns14.25%Revenue fluctuation analysis
Network Reliability9.5%Repeat customer transactions
Data Source Diversity4.75%Multiple verification sources
Behavioral Consistency5.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

ServiceCost
Groq APIFree (500+ calls/day)
EasyOCRFree (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

Ver o original no GitHub

Bom para

Relacionados