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 including fraud_risk_score and repayment_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:

1. Python Runtime: Python 3.9+ must be available in the execution environment.
2. Dependencies: The bridge requires specific libraries for document processing. These are typically managed via a requirements.txt in the root of the processing directory.
3. Storage Access: The bridge uses the smartDownload utility. Ensure your environment variables for Supabase (or local storage) are configured so the Python process can retrieve the files:
   • NEXT_PUBLIC_SUPABASE_URL
   • SUPABASE_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 documentId or applicationId were 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 failed message to see the raw output from the bridge.

Note: For high-volume processing, the maxDuration for these API routes is set to 120 seconds to allow the Python engine sufficient time to perform OCR and complex calculations.