Python Script Bridge
The LoanPilot platform utilizes a Python Script Bridge to handle complex financial data extraction and spreadsheet processing that exceeds the standard capabilities of a typical Node.js environment. This bridge allows the application to leverage powerful Python libraries (such as Pandas, NumPy, or specialized OCR wrappers) to parse bank statements, GST returns, and financial statements into structured JSON.
Overview
The bridge operates as a background processing layer triggered by Next.js API routes. When a document is uploaded, the system retrieves the file from storage, converts it to a base64 string or temporary file path, and passes it to the Python environment for analysis.
The primary analysis modules include:
- Bank Statement Analyzer: Extracts transaction history, detects fraud, and calculates cash flow metrics.
- Financial Statement Parser: Processes Balance Sheets and P&L statements to calculate financial ratios.
- GST Reconciliation: Cross-references GST returns with bank inflows to verify business turnover.
API Usage
Analysis is triggered via POST requests to the internal analysis endpoints. These routes manage the hand-off between the Supabase storage layer and the processing engine.
Analyze Bank Statements
Triggers the extraction of transaction data and the generation of enhanced metrics (e.g., fraud scores, EMI detection).
Endpoint: POST /api/analyze/bank-statement
Payload:
{
"documentId": "uuid-of-the-document",
"applicationId": "uuid-of-the-loan-application",
"organizationId": "uuid-of-your-org",
"aiProvider": "openai" // Optional: specify provider
}
Output: The bridge returns a structured object containing:
summary: High-level metrics (average balance, net income, etc.).transactions: Normalized list of all detected transactions.enhanced_analysis: Advanced data includingfraud_risk_scoreandrepayment_capacity.
Analyze Financial Statements
Processes statutory filings such as Balance Sheets, Profit & Loss statements, or Income Tax Returns (ITR).
Endpoint: POST /api/analyze/financial-statement
Payload:
{
"documentId": "uuid-of-the-document",
"applicationId": "uuid-of-the-application",
"organizationId": "uuid-of-your-org",
"statementType": "balance_sheet" // Options: 'balance_sheet', 'profit_loss', 'itr'
}
Key Ratios Extracted:
- Asset Turnover
- Debt-to-Equity
- DSCR (Debt Service Coverage Ratio)
- Current & Quick Ratios
GST & Bank Reconciliation
A specialized bridge function that runs a multi-source analysis to ensure consistency between declared GST turnover and actual bank deposits.
Endpoint: POST /api/analyze/reconciliation
Payload:
{
"applicationId": "uuid-of-the-application"
}
Configuration & Environment
To ensure the Python Bridge functions correctly, the environment must be configured with the following prerequisites:
- Python Runtime: Python 3.9+ must be available in the execution environment.
- Dependencies: The bridge requires specific libraries for document processing. These are typically managed via a
requirements.txtin the root of the processing directory. - Storage Access: The bridge uses the
smartDownloadutility. Ensure your environment variables for Supabase (or local storage) are configured so the Python process can retrieve the files:NEXT_PUBLIC_SUPABASE_URLSUPABASE_SERVICE_ROLE_KEY
Error Handling
The bridge communicates errors through standard HTTP status codes:
- 401 Unauthorized: User session is invalid or missing.
- 400 Missing Fields: Required parameters like
documentIdorapplicationIdwere not provided. - 500 Analysis Failed: The Python script encountered an error (e.g., corrupted PDF, unsupported document format). Check the server logs for the
AI extraction failedmessage to see the raw output from the bridge.
Note: For high-volume processing, the
maxDurationfor these API routes is set to 120 seconds to allow the Python engine sufficient time to perform OCR and complex calculations.