Hugging Face's logo

Spaces:
point9
/
finryver-dev
Runtime error

App Files Community
19
finryver-dev / SYSTEM_ARCHITECTURE_BOXES.md
Sahil Garg
level-1 of generator and validator for notes
2ac8811
preview code
|
Raw History Blame Contribute Delete
164 kB
# FinRyver - Visual System Architecture
## 🏗️ **SYSTEM ARCHITECTURE OVERVIEW**
```
┌─────────────────────────────────────────────────────────────────────────────────┐
│ FINRYVER SYSTEM │
│ FINANCIAL STATEMENT GENERATION │
└─────────────────────┬─────────────────────┬─────────────────────┬─────────────┘
│ │ │
▼ ▼ ▼
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ CLIENT/UI │ │ FASTAPI │ │ LANGGRAPH │
│ (Streamlit) │ │ ENDPOINTS │ │ WORKFLOWS │
└─────────────────┘ └─────────────────┘ └─────────────────┘
│ │ │
▼ ▼ ▼
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ EXCEL INPUT │ │ DATA PROCESSING│ │ AI TOOLS │
│ FILES │ │ SCRIPTS │ │ (SUBPROCESS) │
└─────────────────┘ └─────────────────┘ └─────────────────┘
│ │ │
▼ ▼ ▼
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ JSON DATA │ │ EXCEL GENERATION│ │ OUTPUT │
│ STRUCTURES │ │ SCRIPTS │ │ FILES │
└─────────────────┘ └─────────────────┘ └─────────────────┘
```
---
## 📁 **FILE STRUCTURE MAP**
```
FinRyver/
├── app.py # 🚀 MAIN API SERVER
├── agents/
│ ├── simple_tools.py # 🛠️ LANGCHAIN TOOLS
│ ├── langgraph.py # 🔄 WORKFLOW ENGINE
│ └── rlhf_workflows.py # 🎯 RLHF ENHANCED
├── notes/ # 📝 NOTES PROCESSING
│ ├── data_extraction.py # 📊 EXCEL → JSON
│ ├── notes_generator.py # 🤖 RULE-BASED NOTES
│ ├── json_to_excel.py # 📋 JSON → EXCEL
│ ├── llm_notes_generator.py # 🧠 AI NOTES (MISTRAL)
│ └── notes_template.py # 📄 TEMPLATES
├── bs/ # 🏦 BALANCE SHEET
│ ├── bl_llm.py # 🤖 AI PROCESSING
│ ├── csv_json_bs.py # 🔄 CSV → JSON
│ └── sircodebs.py # 📈 BS GENERATION
├── pnl/ # 💰 P&L STATEMENT
│ ├── csv_json_pnl.py # 🔄 DATA PROCESSING
│ └── pnl_note.py # 🧮 CALCULATIONS
├── cf/ # 💧 CASH FLOW
│ ├── cash_flow_data_extractor.py # 📊 DATA EXTRACTION
│ ├── cash_flow_csv_to_json_converter.py # 🔄 CSV → JSON
│ ├── cash_flow_data_processor.py # 🧮 PROCESSING
│ └── cash_flow_statement_generator.py # 📋 EXCEL OUTPUT
├── config/ # ⚙️ CONFIGURATION
│ ├── mapping1.json # 🗺️ ACCOUNT MAPPINGS
│ └── rules1.json # 📋 BUSINESS RULES
└── data/ # 💾 DATA STORAGE
├── input/ # 📥 UPLOADS
├── output/ # 📤 GENERATED FILES
├── generated_notes/ # 📝 AI NOTES
└── clean_financial_data_*.json # 🔄 PROCESSED DATA
```
---
## 🔄 **API ENDPOINTS FLOW**
```
┌─────────────────────────────────────────────────────────────────────────────────┐
│ FASTAPI ENDPOINTS │
└─────────────────────┬─────────────────────┬─────────────────────┬─────────────┘
│ │ │
▼ ▼ ▼
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ POST /notes │ │ POST /notes-llm │ │ POST /bs │
│ │ │ │ │ │
│ 🤖 RULE-BASED │ │ 🤖 AI-POWERED │ │ 🏦 BALANCE SHEET│
│ 📝 NOTES │ │ 📝 NOTES │ │ 📊 GENERATION │
└─────────────────┘ └─────────────────┘ └─────────────────┘
│ │ │
▼ ▼ ▼
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ POST /pnl │ │ POST /cf │ │ RLHF ENHANCED │
│ │ │ │ │ │
│ 💰 P&L STATEMENT│ │ 💧 CASH FLOW │ │ 🎯 QUALITY │
│ 📈 GENERATION │ │ 📊 STATEMENT │ │ 🚀 IMPROVEMENT │
└─────────────────┘ └─────────────────┘ └─────────────────┘
```
---
## 📊 **BALANCE SHEET GENERATION FLOW**
```
📥 EXCEL UPLOAD
↓
🏦 POST /bs
↓
💾 data/input/filename.xlsx
↓
🔄 LANGGRAPH WORKFLOW
↓
🛠️ generate_balance_sheet()
↓
┌─────────────────────────────────────┐
│ STEP 1: DATA EXTRACTION │
│ balance_sheet_data_extractor.py │
│ → Extract from Excel sheets │
│ → Create CSV files │
│ → data/csv_notes_bs/ │
└─────────────────────────────────────┘
↓
┌─────────────────────────────────────┐
│ STEP 2: CSV → JSON │
│ csv_json_bs.py │
│ → Process CSV data │
│ → Apply business rules │
│ → clean_financial_data_bs.json │
└─────────────────────────────────────┘
↓
┌─────────────────────────────────────┐
│ STEP 3: AI PROCESSING │
│ bl_llm.py + sircodebs.py │
│ → Claude 3.5 Sonnet AI │
│ → Account classification │
│ → Balance calculations │
└─────────────────────────────────────┘
↓
┌─────────────────────────────────────┐
│ STEP 4: EXCEL GENERATION │
│ → Professional formatting │
│ → Balance sheet layout │
│ → data/output/balance_sheet_*.xlsx │
└─────────────────────────────────────┘
↓
📤 FILE DOWNLOAD
```
---
## 💰 **P&L STATEMENT GENERATION FLOW**
```
📥 EXCEL UPLOAD
↓
💰 POST /pnl
↓
💾 data/input/filename.xlsx
↓
🔄 LANGGRAPH WORKFLOW
↓
🛠️ generate_pnl_statement()
↓
┌─────────────────────────────────────┐
│ STEP 1: DATA EXTRACTION │
│ pnl_data_extractor.py │
│ → Extract P&L accounts │
│ → Identify revenue/expenses │
│ → Create structured data │
└─────────────────────────────────────┘
↓
┌─────────────────────────────────────┐
│ STEP 2: DATA PROCESSING │
│ csv_json_pnl.py │
│ → Convert to JSON format │
│ → Apply account mappings │
│ → clean_financial_data_pnl.json │
└─────────────────────────────────────┘
↓
┌─────────────────────────────────────┐
│ STEP 3: CALCULATIONS │
│ pnl_note.py │
│ → Revenue calculations │
│ → Expense calculations │
│ → Profit calculations │
│ → EBITDA, EBIT, PBT, PAT │
└─────────────────────────────────────┘
↓
┌─────────────────────────────────────┐
│ STEP 4: EXCEL GENERATION │
│ → Professional P&L format │
│ → Comparative columns │
│ → data/pnl_statement.xlsx │
└─────────────────────────────────────┘
↓
📤 FILE DOWNLOAD
```
---
## 💧 **CASH FLOW STATEMENT GENERATION FLOW**
```
📥 EXCEL UPLOAD
↓
💧 POST /cf
↓
💾 data/input/filename.xlsx
↓
🔄 LANGGRAPH WORKFLOW
↓
🛠️ generate_cash_flow_statement()
↓
┌─────────────────────────────────────┐
│ STEP 1: DATA EXTRACTION │
│ cash_flow_data_extractor.py │
│ → Extract from Excel sheets │
│ → Note 16-23, 2-8, 9, 10-15, 24-30 │
│ → Create CSV files │
└─────────────────────────────────────┘
↓
┌─────────────────────────────────────┐
│ STEP 2: CSV → JSON │
│ cash_flow_csv_to_json_converter.py │
│ → Process all CSV files │
│ → Create structured JSON │
│ → clean_financial_data_cfs.json │
└─────────────────────────────────────┘
↓
┌─────────────────────────────────────┐
│ STEP 3: DATA PROCESSING │
│ cash_flow_data_processor.py │
│ → Extract P&L data │
│ → Process working capital changes │
│ → Calculate cash flow components │
│ → data/extracted_cfs_data.json │
└─────────────────────────────────────┘
↓
┌─────────────────────────────────────┐
│ STEP 4: EXCEL GENERATION │
│ cash_flow_statement_generator.py │
│ → Operating activities │
│ → Investing activities │
│ → Financing activities │
│ → data/cash_flow_statements.xlsx │
└─────────────────────────────────────┘
↓
📤 FILE DOWNLOAD
```
---
## 📝 **NOTES GENERATION FLOW (RULE-BASED)**
```
📥 EXCEL UPLOAD
↓
📝 POST /notes
↓
💾 data/input/filename.xlsx
↓
🔄 LANGGRAPH WORKFLOW
↓
🛠️ generate_notes_full_pipeline_from_path()
↓
┌─────────────────────────────────────┐
│ STEP 1: DATA EXTRACTION │
│ data_extraction.py │
│ → extract_trial_balance_data() │
│ → Process Excel trial balance │
│ → Create structured data │
└─────────────────────────────────────┘
↓
┌─────────────────────────────────────┐
│ STEP 2: ANALYSIS & SAVE │
│ analyze_and_save_results() │
│ → Validate data completeness │
│ → data/output1/parsed_trial_balance.json
└─────────────────────────────────────┘
↓
┌─────────────────────────────────────┐
│ STEP 3: NOTES GENERATION │
│ notes_generator.py │
│ → process_json() │
│ → Apply config/rules1.json │
│ → Use config/mapping1.json │
│ → Generate financial notes │
└─────────────────────────────────────┘
↓
┌─────────────────────────────────────┐
│ STEP 4: JSON NORMALIZATION │
│ → Wrap in {"notes": [...]} format │
│ → data/output2/notes_output_wrapped.json
└─────────────────────────────────────┘
↓
┌─────────────────────────────────────┐
│ STEP 5: EXCEL GENERATION │
│ json_to_excel.py │
│ → json_to_xlsx() │
│ → Professional formatting │
│ → data/output3/final_output.xlsx │
└─────────────────────────────────────┘
↓
📤 FILE DOWNLOAD
```
---
## 🤖 **NOTES GENERATION FLOW (AI-POWERED)**
```
📥 EXCEL UPLOAD
↓
📝 POST /notes-llm
↓
💾 data/input/filename.xlsx
↓
🔄 LANGGRAPH WORKFLOW
↓
🛠️ generate_llm_notes()
↓
┌─────────────────────────────────────┐
│ STEP 1: DATA EXTRACTION │
│ llm_notes_data_processor.py │
│ → extract_trial_balance_data() │
│ → Process Excel data │
│ → data/output1/parsed_trial_balance.json
└─────────────────────────────────────┘
↓
┌─────────────────────────────────────┐
│ STEP 2: AI NOTES GENERATION │
│ llm_notes_generator.py │
│ → FlexibleFinancialNoteGenerator │
│ → Mistral AI (mixtral-8x7b) │
│ → OpenRouter API │
│ → data/generated_notes/notes.json │
└─────────────────────────────────────┘
↓
┌─────────────────────────────────────┐
│ STEP 3: VALIDATION │
│ → JSON structure validation │
│ → Content completeness check │
│ → Account classification │
└─────────────────────────────────────┘
↓
┌─────────────────────────────────────┐
│ STEP 4: EXCEL GENERATION │
│ llm_notes_excel_converter.py │
│ → normalize_llm_notes_json() │
│ → Professional Excel format │
│ → data/generated_notes_excel/notes.xlsx
└─────────────────────────────────────┘
↓
📤 FILE DOWNLOAD
```
---
## 🎯 **RLHF ENHANCEMENT FLOW**
```
📥 EXCEL UPLOAD + RLHF=TRUE
↓
🎯 POST /notes?use_rlhf=true
↓
🔄 RLHF WORKFLOW MANAGER
↓
┌─────────────────────────────────────┐
│ STEP 1: STATE CREATION │
│ RLHFFinancialAgentState │
│ → statement_id: uuid │
│ → file_path: input file │
│ → candidates_generated: [] │
│ → best_candidate_index: None │
└─────────────────────────────────────┘
↓
┌─────────────────────────────────────┐
│ STEP 2: CANDIDATE GENERATION │
│ → Generate 3 note variations │
│ → Different processing approaches │
│ → Store in candidates array │
└─────────────────────────────────────┘
↓
┌─────────────────────────────────────┐
│ STEP 3: QUALITY PREDICTION │
│ → ML reward model evaluation │
│ → Score each candidate │
│ → Select best candidate │
└─────────────────────────────────────┘
↓
┌─────────────────────────────────────┐
│ STEP 4: OUTPUT SELECTION │
│ → Return highest quality output │
│ → Update model with feedback │
│ → Continuous improvement │
└─────────────────────────────────────┘
↓
📤 FILE DOWNLOAD
```
---
## 🔧 **ENVIRONMENT VARIABLES MAP**
```
┌─────────────────────────────────────────────────────────────────────────────────┐
│ ENVIRONMENT VARIABLES │
├─────────────────────┬─────────────────────┬─────────────────────┬─────────────┤
│ OPENROUTER_API_KEY │ CFS_EXCEL_FILE_PATH │ CFS_OUTPUT_FOLDER │ CFS_JSON_INPUT │
│ 🤖 AI API Access │ 📁 Input Excel Path │ 📁 CSV Output Dir │ 📄 Input JSON │
├─────────────────────┼─────────────────────┼─────────────────────┼─────────────┤
│ CFS_JSON_OUTPUT │ CFS_EXTRACTED_FILE │ CFS_OUTPUT_FILE │ CFS_TAX_PAID │
│ 📄 Output JSON │ 📄 Extracted Data │ 📄 Final Excel │ 💰 Tax Amount │
├─────────────────────┼─────────────────────┼─────────────────────┼─────────────┤
│ CFS_SKIPROWS │ CFS_NOTE_SHEETS │ INPUT_FILE │ OUTPUT_FOLDER │
│ ⏭️ Excel Skip Rows │ 📋 Sheet Names │ 📄 Input File │ 📁 Output Dir │
└─────────────────────┴─────────────────────┴─────────────────────┴─────────────┘
```
---
## ⚡ **COMPONENT INTERACTION MATRIX**
```
┌─────────────────────────────────────────────────────────────────────────────────┐
│ COMPONENT INTERACTION MATRIX │
├─────────────────────┬─────────────────────┬─────────────────────┬─────────────┤
│ COMPONENT │ INPUT │ PROCESS │ OUTPUT │
├─────────────────────┼─────────────────────┼─────────────────────┼─────────────┤
│ app.py │ HTTP Requests │ FastAPI Routing │ FileResponse │
├─────────────────────┼─────────────────────┼─────────────────────┼─────────────┤
│ langgraph.py │ File Path + Type │ Workflow Orchestration│ Success/Error │
├─────────────────────┼─────────────────────┼─────────────────────┼─────────────┤
│ simple_tools.py │ File Path │ Subprocess Calls │ Excel Path │
├─────────────────────┼─────────────────────┼─────────────────────┼─────────────┤
│ *_extractor.py │ Excel File │ Data Extraction │ CSV Files │
├─────────────────────┼─────────────────────┼─────────────────────┼─────────────┤
│ *_converter.py │ CSV Files │ JSON Processing │ JSON Data │
├─────────────────────┼─────────────────────┼─────────────────────┼─────────────┤
│ *_generator.py │ JSON Data │ Calculations │ Excel File │
├─────────────────────┼─────────────────────┼─────────────────────┼─────────────┤
│ llm_*.py │ JSON Data │ AI Processing │ Enhanced Data│
├─────────────────────┼─────────────────────┼─────────────────────┼─────────────┤
│ rlhf_*.py │ File Path │ Quality Enhancement │ Best Output │
└─────────────────────┴─────────────────────┴─────────────────────┴─────────────┘
```
---
## 🚨 **ERROR HANDLING FLOW**
```
┌─────────────────────────────────────┐ ┌─────────────────────────────────────┐
│ ERROR DETECTED │ │ SUCCESS PATH │
│ • File not found │ │ • All steps complete │
│ • Invalid Excel format │ │ • Output file created │
│ • API connection failed │ │ • Validation passed │
│ • Calculation errors │ │ • FileResponse ready │
└─────────────────────┬─────────────┘ └─────────────────────┬─────────────┘
│ │
▼ ▼
┌─────────────────┐ ┌─────────────────┐
│ ERROR HANDLING │ │ SUCCESS │
│ LOGIC │ │ RESPONSE │
└─────────────────┘ └─────────────────┘
│ │
▼ ▼
┌─────────────────┐ ┌─────────────────┐
│ • Log Error │ │ • Return Excel │
│ • Return Error │ │ • Status: Success│
│ • Status: Error │ │ • File Download │
└─────────────────┘ └─────────────────┘
```
---
## 🔄 **DATA TRANSFORMATION PIPELINE**
```
EXCEL FILE
↓
┌─────────────────────────────────────┐
│ DATA EXTRACTION │
│ • Read Excel sheets │
│ • Extract account data │
│ • Create structured records │
│ • Output: CSV files │
└─────────────────────────────────────┘
↓
┌─────────────────────────────────────┐
│ DATA PROCESSING │
│ • Parse CSV files │
│ • Apply business rules │
│ • Account classification │
│ • Output: JSON structures │
└─────────────────────────────────────┘
↓
┌─────────────────────────────────────┐
│ CALCULATIONS │
│ • Financial calculations │
│ • Balance validations │
│ • AI enhancement (optional) │
│ • Output: Processed data │
└─────────────────────────────────────┘
↓
┌─────────────────────────────────────┐
│ EXCEL GENERATION │
│ • Professional formatting │
│ • Headers and styling │
│ • Multiple worksheets │
│ • Output: Excel file │
└─────────────────────────────────────┘
↓
FILE DOWNLOAD
```
---
## 🤖 **AI INTEGRATION WORKFLOW**
```
┌─────────────────────────────────────┐
│ AI REQUEST │
│ • Trial balance data │
│ • Processing instructions │
│ • Account mappings │
└─────────────────────┬─────────────┘
│
▼
┌─────────────────┐
│ OPENROUTER API │
│ • Claude 3.5 │
│ • Mistral AI │
│ • API Key Auth │
└─────────────────┘
│
▼
┌─────────────────┐
│ AI PROCESSING │
│ • Account analysis│
│ • Note generation│
│ • Classification │
└─────────────────┘
│
▼
┌─────────────────────────────────────┐
│ RESPONSE VALIDATION │
│ • JSON structure check │
│ • Content completeness │
│ • Financial logic validation │
│ • Fallback model if needed │
└─────────────────────────────────────┘
│
▼
┌─────────────────────────────────────┐
│ ENHANCED OUTPUT │
│ • AI-improved data │
│ • Better classifications │
│ • Intelligent notes │
└─────────────────────────────────────┘
```
---
## 📊 **PERFORMANCE MONITORING FLOW**
```
┌─────────────────────────────────────┐
│ REQUEST START │
│ • Timestamp recording │
│ • Execution ID generation │
│ • Resource monitoring │
└─────────────────────┬─────────────┘
│
▼
┌─────────────────┐
│ PROCESSING │
│ • Step timing │
│ • Memory usage │
│ • API calls │
└─────────────────┘
│
▼
┌─────────────────────────────────────┐
│ METRICS COLLECTION │
│ • Total execution time │
│ • Step-by-step timing │
│ • Success/error rates │
│ • Resource utilization │
└─────────────────────────────────────┘
│
▼
┌─────────────────────────────────────┐
│ LOGGING & REPORTING │
│ • Comprehensive logs │
│ • Performance dashboards │
│ • Error tracking │
│ • Optimization insights │
└─────────────────────────────────────┘
```
## 🤖 **Part 1.5: LLM Notes Generation (Simple Flow)**
```
📥 INPUT PHASE
┌─────────────────────────────────────────────────────────────┐
│ Client uploads Excel Trial Balance file via Streamlit/API │
└─────────────────────┬───────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ POST /notes-llm request to FastAPI with file upload │
└─────────────────────┬───────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ FastAPI saves file to data/input/{filename} │
└─────────────────────┬───────────────────────────────────────┘
│
▼
🔄 WORKFLOW ORCHESTRATION
┌─────────────────────────────────────────────────────────────┐
│ run_workflow(file_path, "notes-llm") called from app.py │
└─────────────────────┬───────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ LangGraph creates FinancialAgentState with file_path │
└─────────────────────┬───────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ LangGraph invokes generate_llm_notes tool │
└─────────────────────┬───────────────────────────────────────┘
│
▼
🔍 DATA EXTRACTION PHASE
┌─────────────────────────────────────────────────────────────┐
│ Step 1: Run llm_notes_data_processor.py via subprocess │
│ - Calls extract_trial_balance_data(file_path) │
│ - Processes Excel trial balance data │
│ - Creates structured trial balance records │
│ - Saves to data/output1/parsed_trial_balance.json │
└─────────────────────┬───────────────────────────────────────┘
│
▼
🤖 LLM PROCESSING PHASE
┌─────────────────────────────────────────────────────────────┐
│ Step 2: Run llm_notes_generator.py via subprocess │
│ - Loads parsed_trial_balance.json │
│ - Uses FlexibleFinancialNoteGenerator class │
│ - Calls OpenRouter API with Mistral AI models: │
│ * Primary: mistralai/mixtral-8x7b-instruct │
│ * Fallback: mistralai/mistral-7b-instruct-v0.2 │
│ - Generates intelligent financial notes using LLM │
│ - Supports specific note numbers or all notes │
│ - Saves to data/generated_notes/notes.json │
└─────────────────────┬───────────────────────────────────────┘
│
▼
📊 EXCEL GENERATION PHASE
┌─────────────────────────────────────────────────────────────┐
│ Step 3: Run llm_notes_excel_converter.py via subprocess │
│ - Loads data/generated_notes/notes.json │
│ - Applies normalize_llm_notes_json() transformation │
│ - Creates professional Excel format with formatting │
│ - Adds headers and styling for financial notes │
│ - Saves to data/generated_notes_excel/notes.xlsx │
└─────────────────────┬───────────────────────────────────────┘
│
▼
✅ VALIDATION PHASE
┌─────────────────────────────────────────────────────────────┐
│ LLM Response Validation │
│ - Validates JSON structure from LLM response │
│ - Checks for required note fields and data completeness │
│ - Verifies account classifications and amounts │
│ - Logs validation results and any parsing issues │
└─────────────────────┬───────────────────────────────────────┘
│
▼
📤 OUTPUT PHASE
┌─────────────────────────────────────────────────────────────┐
│ LangGraph returns success with output_xlsx_path │
└─────────────────────┬───────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ FastAPI creates FileResponse with notes Excel file │
└─────────────────────┬───────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ Client downloads LLM-generated financial notes Excel │
└─────────────────────────────────────────────────────────────┘
```
## 🏦 **Part 2: Balance Sheet Generation (Simple Flow)**
```
📥 INPUT PHASE
┌─────────────────────────────────────────────────────────────┐
│ Client uploads Excel Trial Balance file │
└─────────────────────┬───────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ POST /bs request to FastAPI │
└─────────────────────┬───────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ File saved to data/input/{filename} │
└─────────────────────┬───────────────────────────────────────┘
│
▼
🔄 WORKFLOW ORCHESTRATION
┌─────────────────────────────────────────────────────────────┐
│ run_workflow(file_path, "bs") from LangGraph │
└─────────────────────┬───────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ LangGraph invokes generate_balance_sheet tool │
└─────────────────────┬───────────────────────────────────────┘
│
▼
🔍 DATA EXTRACTION PHASE
┌─────────────────────────────────────────────────────────────┐
│ Step 1: Run balance_sheet_data_extractor.py via subprocess │
│ - Extracts trial balance data │
│ - Processes account classifications │
│ - Creates clean_financial_data_bs.json │
└─────────────────────┬───────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ Step 2: Run csv_json_bs.py via subprocess │
│ - Converts extracted data to structured format │
│ - Applies business logic and validations │
│ - Prepares data for balance sheet generation │
└─────────────────────┬───────────────────────────────────────┘
│
▼
🏗️ BALANCE SHEET GENERATION PHASE
┌─────────────────────────────────────────────────────────────┐
│ Step 3: Run sircodebs.py via subprocess │
│ - Loads clean_financial_data_bs.json │
│ - Uses EnhancedBalanceSheetGenerator class │
│ - Extracts data using template structure │
│ - Applies AI-assisted extraction if needed │
│ - Calculates totals and balances │
│ - Validates balance sheet equation │
└─────────────────────┬───────────────────────────────────────┘
│
▼
📊 EXCEL FORMATTING PHASE
┌─────────────────────────────────────────────────────────────┐
│ Balance Sheet Excel Generation │
│ - Creates professional Excel format │
│ - Applies corporate styling and formatting │
│ - Adds headers: "BALANCE SHEET As at March 31, 2024" │
│ - Structures: Equity & Liabilities vs Assets │
│ - Saves to data/output/balance_sheet_{timestamp}.xlsx │
└─────────────────────┬───────────────────────────────────────┘
│
▼
✅ VALIDATION PHASE
┌─────────────────────────────────────────────────────────────┐
│ Balance Sheet Validation │
│ - Verifies Assets = Equity + Liabilities │
│ - Checks for balance differences │
│ - Logs validation results │
│ - Reports any discrepancies │
└─────────────────────┬───────────────────────────────────────┘
│
▼
📤 OUTPUT PHASE
┌─────────────────────────────────────────────────────────────┐
│ FastAPI locates first .xlsx file in data/output/ │
└─────────────────────┬───────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ FileResponse created with balance sheet Excel file │
└─────────────────────┬───────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ Client downloads professional balance sheet │
└─────────────────────────────────────────────────────────────┘
```
## 💰 **Part 3: P&L Generation (Simple Flow)**
```
📥 INPUT PHASE
┌─────────────────────────────────────────────────────────────┐
│ Client uploads Excel Trial Balance file │
└─────────────────────┬───────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ POST /pnl request to FastAPI │
└─────────────────────┬───────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ File saved to data/input/{filename} │
└─────────────────────┬───────────────────────────────────────┘
│
▼
🔄 WORKFLOW ORCHESTRATION
┌─────────────────────────────────────────────────────────────┐
│ run_workflow(file_path, "pnl") from LangGraph │
└─────────────────────┬───────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ LangGraph invokes generate_pnl_statement tool │
└─────────────────────┬───────────────────────────────────────┘
│
▼
🔍 DATA EXTRACTION PHASE
┌─────────────────────────────────────────────────────────────┐
│ Step 1: Run PnL data extraction subprocess │
│ - Processes trial balance Excel file │
│ - Identifies revenue and expense accounts │
│ - Extracts income statement line items │
│ - Creates structured PnL data │
└─────────────────────┬───────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ Step 2: Account Classification │
│ - Maps accounts using config/mapping1.json │
│ - Applies rules from config/rules1.json │
│ - Categorizes into: Revenue, COGS, Operating Expenses │
│ - Separates Other Income and Finance Costs │
└─────────────────────┬───────────────────────────────────────┘
│
▼
🧮 PNL CALCULATION PHASE
┌─────────────────────────────────────────────────────────────┐
│ Revenue Calculations │
│ - Revenue from Operations (Sales, Service Income) │
│ - Other Income (Interest, Gains) │
│ - Total Income calculation │
└─────────────────────┬───────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ Expense Calculations │
│ - Cost of Materials Consumed │
│ - Employee Benefits Expense │
│ - Finance Costs │
│ - Depreciation and Amortization │
│ - Other Expenses │
│ - Total Expenses calculation │
└─────────────────────┬───────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ Profit Calculations │
│ - EBITDA = Total Income - Operating Expenses │
│ - EBIT = EBITDA - Depreciation & Amortization │
│ - PBT = EBIT - Finance Costs │
│ - PAT = PBT - Tax Expense │
└─────────────────────┬───────────────────────────────────────┘
│
▼
📊 EXCEL GENERATION PHASE
┌─────────────────────────────────────────────────────────────┐
│ P&L Statement Excel Creation │
│ - Creates professional P&L format │
│ - Headers: "PROFIT AND LOSS STATEMENT" │
│ - Period: "For the year ended March 31, 2024" │
│ - Comparative columns: Current Year vs Previous Year │
│ - Applies accounting formatting and styling │
│ - Saves to data/pnl_statement.xlsx │
└─────────────────────┬───────────────────────────────────────┘
│
▼
📤 OUTPUT PHASE
┌─────────────────────────────────────────────────────────────┐
│ FastAPI creates FileResponse with pnl_statement.xlsx │
└─────────────────────┬───────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ Client downloads P&L statement Excel file │
└─────────────────────────────────────────────────────────────┘
```
## 💧 **Part 4: Cash Flow Generation (Simple Flow)**
```
📥 INPUT PHASE
┌─────────────────────────────────────────────────────────────┐
│ Client uploads Excel Trial Balance file │
└─────────────────────┬───────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ POST /cf request to FastAPI │
└─────────────────────┬───────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ File saved to data/input/{filename} │
└─────────────────────┬───────────────────────────────────────┘
│
▼
🔄 WORKFLOW ORCHESTRATION
┌─────────────────────────────────────────────────────────────┐
│ run_workflow(file_path, "cf") from LangGraph │
└─────────────────────┬───────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ LangGraph invokes generate_cash_flow_statement tool │
└─────────────────────┬───────────────────────────────────────┘
│
▼
🔍 DATA EXTRACTION PHASE
┌─────────────────────────────────────────────────────────────┐
│ Step 1: Run cf_middlestep.py via subprocess │
│ - Executes FinancialDataExtractor class │
│ - Loads trial balance data │
│ - Extracts P&L data (Profit, Depreciation, Interest) │
│ - Extracts Working Capital changes │
│ - Extracts Investing Activities data │
│ - Extracts Financing Activities data │
│ - Creates data/extracted_cfs_data.json │
└─────────────────────┬───────────────────────────────────────┘
│
▼
🧮 CASH FLOW CALCULATION PHASE
┌─────────────────────────────────────────────────────────────┐
│ Operating Activities Calculations │
│ - Start with Profit Before Tax (PBT) │
│ - Add: Depreciation and Amortization │
│ - Less: Interest Income │
│ - Operating Profit Before Working Capital Changes │
└─────────────────────┬───────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ Working Capital Movements │
│ - (Increase)/Decrease in Trade Receivables │
│ - (Increase)/Decrease in Inventories │
│ - (Increase)/Decrease in Other Current Assets │
│ - Increase/(Decrease) in Trade Payables │
│ - Increase/(Decrease) in Other Current Liabilities │
│ - Cash Generated from Operations │
│ - Less: Direct Taxes Paid │
│ - Net Cash Flow from Operating Activities │
└─────────────────────┬───────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ Investing Activities Calculations │
│ - Purchase of Fixed Assets (Outflow) │
│ - Sale of Fixed Assets (Inflow) │
│ - Interest Income (Inflow) │
│ - Net Cash Flow from Investing Activities │
└─────────────────────┬───────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ Financing Activities Calculations │
│ - Proceeds from Long Term Borrowings │
│ - Repayment of Long Term Borrowings │
│ - Dividend Paid (Outflow) │
│ - Net Cash Flow from Financing Activities │
└─────────────────────┬───────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ Net Cash Flow Calculation │
│ - Net Increase/Decrease in Cash = Operating + Investing + │
│ Financing │
│ - Cash at Beginning of Year │
│ - Cash at End of Year │
│ - Verification of Cash Reconciliation │
└─────────────────────┬───────────────────────────────────────┘
│
▼
📊 EXCEL GENERATION PHASE
┌─────────────────────────────────────────────────────────────┐
│ Step 2: Run cf_generation.py via subprocess │
│ - Loads extracted_cfs_data.json │
│ - Uses CashFlowStatementGenerator class │
│ - Creates professional Excel format │
│ - Headers: "CASH FLOW STATEMENT" │
│ - Period: "For the year ended March 31, 2024" │
│ - Three main sections: Operating, Investing, Financing │
│ - Components of Cash and Cash Equivalents │
│ - Applies professional styling and formatting │
│ - Saves to data/cash_flow_statements.xlsx │
└─────────────────────┬───────────────────────────────────────┘
│
▼
✅ VALIDATION PHASE
┌─────────────────────────────────────────────────────────────┐
│ Cash Flow Validation │
│ - Verifies Net Change = Ending Cash - Beginning Cash │
│ - Checks mathematical accuracy of all sections │
│ - Validates working capital calculations │
│ - Reports any discrepancies or balancing issues │
└─────────────────────┬───────────────────────────────────────┘
│
▼
📤 OUTPUT PHASE
┌─────────────────────────────────────────────────────────────┐
│ FastAPI creates FileResponse with cash_flow_statements.xlsx │
└─────────────────────┬───────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ Client downloads professional cash flow statement │
└─────────────────────────────────────────────────────────────┘
```
## 🤖 **Part 5: Notes Generation (RLHF-Enhanced Flow)**
```
📥 INPUT PHASE
┌─────────────────────────────────────────────────────────────┐
│ Client uploads Excel Trial Balance file │
│ Streamlit checkbox: "Use RLHF" = TRUE │
└─────────────────────┬───────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ POST /notes?use_rlhf=true request to FastAPI │
└─────────────────────┬───────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ FastAPI saves file to data/input/{filename} │
└─────────────────────┬───────────────────────────────────────┘
│
▼
🤖 RLHF WORKFLOW ORCHESTRATION
┌─────────────────────────────────────────────────────────────┐
│ run_rlhf_workflow(file_path, "notes") called from app.py │
└─────────────────────┬───────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ RLHFWorkflowManager creates RLHFFinancialAgentState │
│ - statement_id: uuid.uuid4() │
│ - file_path: input file path │
│ - candidates_generated: [] │
│ - best_candidate_index: None │
│ - predicted_quality: None │
│ - confidence_score: None │
└─────────────────────┬───────────────────────────────────────┘
│
▼
🔄 CANDIDATE GENERATION PHASE
┌─────────────────────────────────────────────────────────────┐
│ Check if Reward Model is Trained │
│ if self.reward_model.is_trained: Generate 3 Candidates │
│ else: Generate Single Statement │
└─────────────────────┬───────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ CANDIDATE 1 GENERATION │
│ _generate_candidates() calls generate_notes_full_pipeline_ │
│ from_path(file_path) with slight variations: │
│ - Same data extraction process │
│ - extract_trial_balance_data(file_location) │
│ - analyze_and_save_results() → parsed_trial_balance.json │
│ - process_json() with LLM variation 1 │
│ - json_to_xlsx() → candidate_1_notes.xlsx │
└─────────────────────┬───────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ CANDIDATE 2 GENERATION │
│ Second call to generate_notes_full_pipeline_from_path(): │
│ - Same extraction and analysis │
│ - Different LLM prompt variations or temperature │
│ - Slightly different note generation approach │
│ - json_to_xlsx() → candidate_2_notes.xlsx │
└─────────────────────┬───────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ CANDIDATE 3 GENERATION │
│ Third call to generate_notes_full_pipeline_from_path(): │
│ - Same extraction process │
│ - Third variation in LLM processing │
│ - Alternative formatting or structure │
│ - json_to_xlsx() → candidate_3_notes.xlsx │
└─────────────────────┬───────────────────────────────────────┘
│
▼
🎯 QUALITY PREDICTION PHASE
┌─────────────────────────────────────────────────────────────┐
│ Feature Extraction for Candidate 1 │
│ reward_model.extract_features(): │
│ - File size and processing time metrics │
│ - Content analysis (word count, structure complexity) │
│ - Domain-specific metrics (account categories count) │
│ - Balance verification accuracy │
│ - Metadata features (statement type, complexity) │
│ → Feature Vector 1 (16 dimensions) │
└─────────────────────┬───────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ Quality Prediction for Candidate 1 │
│ RandomForestRegressor.predict(features_1): │
│ - Model trained on human feedback data │
│ - Predicts quality score (1.0-5.0 scale) │
│ - Calculates confidence score │
│ → Predicted Quality: 3.2, Confidence: 0.85 │
└─────────────────────┬───────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ Feature Extraction & Prediction for Candidate 2 │
│ → Predicted Quality: 4.1, Confidence: 0.92 │
└─────────────────────┬───────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ Feature Extraction & Prediction for Candidate 3 │
│ → Predicted Quality: 3.8, Confidence: 0.88 │
└─────────────────────┬───────────────────────────────────────┘
│
▼
🏆 BEST CANDIDATE SELECTION PHASE
┌─────────────────────────────────────────────────────────────┐
│ _select_best_candidate() Analysis: │
│ - Compare quality scores: [3.2, 4.1, 3.8] │
│ - Compare confidence scores: [0.85, 0.92, 0.88] │
│ - Select highest quality with sufficient confidence │
│ → Best Candidate: #2 (Quality: 4.1, Confidence: 0.92) │
│ - best_candidate_index = 1 │
│ - predicted_quality = 4.1 │
│ - confidence_score = 0.92 │
└─────────────────────┬───────────────────────────────────────┘
│
▼
💾 STATEMENT STORAGE PHASE
┌─────────────────────────────────────────────────────────────┐
│ feedback_manager.store_generated_statement(): │
│ - statement_id: uuid.uuid4() │
│ - statement_type: "notes" │
│ - file_path: original input file │
│ - output_path: selected candidate Excel path │
│ - generation_time: end_time - start_time │
│ - predicted_quality: 4.1 │
│ - confidence_score: 0.92 │
│ - metadata: {candidates_count: 3, best_index: 1} │
│ → Stored in data/feedback/generated_statements.json │
└─────────────────────┬───────────────────────────────────────┘
│
▼
📤 ENHANCED OUTPUT PHASE
┌─────────────────────────────────────────────────────────────┐
│ FastAPI creates FileResponse with best candidate Excel │
│ + Enhanced Headers: │
│ - X-RLHF-Statement-ID: uuid-123 │
│ - X-RLHF-Quality-Score: 4.1 │
│ - X-RLHF-Confidence: 0.92 │
│ - Content-Disposition: attachment; filename=notes.xlsx │
└─────────────────────┬───────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ Client receives highest-quality notes with RLHF metadata │
│ Streamlit displays RLHF information to user │
└─────────────────────────────────────────────────────────────┘
🔄 FEEDBACK COLLECTION PHASE (Asynchronous)
┌─────────────────────────────────────────────────────────────┐
│ Human reviewer accesses /rlhf/pending-reviews │
│ Reviews generated notes statement │
│ Submits feedback via /rlhf/feedback: │
│ - statement_id: uuid-123 │
│ - calculation_accuracy: 4 (1-5 scale) │
│ - account_classification: 5 │
│ - statement_balance: 4 │
│ - accounting_standards: 4 │
│ - regulatory_compliance: 5 │
│ - completeness: 4 │
│ - professional_presentation: 4 │
│ - would_accept_for_audit: true │
│ - specific_errors: "Minor formatting in note headers" │
│ → overall_score: (4+5+4+4+5+4+4)/7 = 4.29 │
└─────────────────────┬───────────────────────────────────────┘
│
▼
🎓 MODEL IMPROVEMENT PHASE
┌─────────────────────────────────────────────────────────────┐
│ feedback_manager.store_feedback() saves human evaluation │
│ RLHFTrainer.periodic_training_check(): │
│ - Check if enough samples for retraining (min 2-5) │
│ - If yes: Extract features + feedback for all statements │
│ - Retrain RandomForestRegressor with new feedback data │
│ - Update model weights and save to data/models/ │
│ - Log training metrics (R², MSE, feature importance) │
│ → Next statements will have improved quality predictions │
└─────────────────────────────────────────────────────────────┘
```
## 🤖 **Part 5.5: LLM Notes Generation (RLHF-Enhanced Flow)**
```
📥 INPUT PHASE
┌─────────────────────────────────────────────────────────────┐
│ Client uploads Excel Trial Balance file │
│ Streamlit checkbox: "Use RLHF" = TRUE │
└─────────────────────┬───────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ POST /notes-llm?use_rlhf=true request to FastAPI │
└─────────────────────┬───────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ FastAPI saves file to data/input/{filename} │
└─────────────────────┬───────────────────────────────────────┘
│
▼
🤖 RLHF WORKFLOW ORCHESTRATION
┌─────────────────────────────────────────────────────────────┐
│ run_rlhf_workflow(file_path, "notes-llm") called from app.py│
└─────────────────────┬───────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ RLHFWorkflowManager creates RLHFFinancialAgentState │
│ - statement_id: uuid.uuid4() │
│ - statement_type: "notes-llm" │
│ - candidates_generated: [] │
│ - best_candidate_index: None │
│ - predicted_quality: None │
│ - confidence_score: None │
└─────────────────────┬───────────────────────────────────────┘
│
▼
🔄 CANDIDATE GENERATION PHASE
┌─────────────────────────────────────────────────────────────┐
│ Check if Reward Model is Trained │
│ if self.reward_model.is_trained: Generate 3 Candidates │
│ else: Generate Single Statement │
└─────────────────────┬───────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ CANDIDATE 1 GENERATION │
│ _generate_candidates() calls generate_llm_notes(): │
│ - Run llm_notes_data_processor.py (variant 1) │
│ - Apply different extraction parameters │
│ - llm_notes_generator.py with prompt variation 1: │
│ * Different LLM temperature or instructions │
│ * Alternative note structure approach │
│ - llm_notes_excel_converter.py with formatting style 1 │
│ → candidate_1_notes_llm.xlsx │
└─────────────────────┬───────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ CANDIDATE 2 GENERATION │
│ Second call to generate_llm_notes(): │
│ - Same data extraction process │
│ - Different LLM model selection strategy: │
│ * Prefer Mixtral 8x7B over Mistral 7B │
│ * Alternative prompt engineering │
│ - Different Excel formatting and styling options │
│ → candidate_2_notes_llm.xlsx │
└─────────────────────┬───────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ CANDIDATE 3 GENERATION │
│ Third call to generate_llm_notes(): │
│ - Same extraction foundation │
│ - Third LLM approach with different parameters: │
│ * Varied max_tokens and temperature settings │
│ * Alternative account classification prompts │
│ - Enhanced Excel formatting with different styling │
│ → candidate_3_notes_llm.xlsx │
└─────────────────────┬───────────────────────────────────────┘
│
▼
🎯 QUALITY PREDICTION PHASE
┌─────────────────────────────────────────────────────────────┐
│ LLM Notes Specific Feature Extraction: │
│ reward_model.extract_features() for each candidate: │
│ - LLM response quality and coherence metrics │
│ - Account classification accuracy in generated notes │
│ - Note completeness and structure validation │
│ - Professional formatting quality assessment │
│ - Content relevance to financial statement requirements │
│ - Processing time and API call efficiency │
│ - JSON structure validity and parsing success │
│ → LLM-specific feature vectors for quality prediction │
└─────────────────────┬───────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ Quality Scoring for LLM Notes Candidates: │
│ RandomForestRegressor predictions with LLM focus: │
│ - Candidate 1: Quality 3.7, Confidence 0.88 │
│ - Candidate 2: Quality 4.5, Confidence 0.94 │
│ - Candidate 3: Quality 4.1, Confidence 0.91 │
│ LLM-specific quality criteria applied │
└─────────────────────┬───────────────────────────────────────┘
│
▼
🏆 BEST CANDIDATE SELECTION PHASE
┌─────────────────────────────────────────────────────────────┐
│ _select_best_candidate() for LLM Notes: │
│ - Prioritize LLM response quality and coherence │
│ - Evaluate account classification accuracy │
│ - Consider note completeness and professional presentation │
│ - Assess content relevance and structure │
│ → Best Candidate: #2 (Quality: 4.5, Confidence: 0.94) │
│ - Highest combined score for LLM-generated content │
└─────────────────────┬───────────────────────────────────────┘
│
▼
💾 STATEMENT STORAGE PHASE
┌─────────────────────────────────────────────────────────────┐
│ Store LLM Notes for Human Review: │
│ feedback_manager.store_generated_statement(): │
│ - statement_type: "notes-llm" │
│ - LLM-specific metadata: │
│ * llm_model_used: "mistralai/mixtral-8x7b-instruct" │
│ * api_calls_made: number of OpenRouter API calls │
│ * notes_generated_count: number of financial notes │
│ * average_response_time: API response time │
│ - predicted_quality: 4.5 │
│ - confidence_score: 0.94 │
└─────────────────────┬───────────────────────────────────────┘
│
▼
📤 ENHANCED OUTPUT PHASE
┌─────────────────────────────────────────────────────────────┐
│ FastAPI creates FileResponse with best LLM notes candidate │
│ Enhanced Headers for LLM Notes: │
│ - X-RLHF-Statement-ID: uuid-456 │
│ - X-RLHF-Quality-Score: 4.5 │
│ - X-RLHF-Confidence: 0.94 │
│ - X-RLHF-LLM-Model: mistralai/mixtral-8x7b-instruct │
│ - X-RLHF-API-Calls: [count] │
└─────────────────────┬───────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ Client receives highest-quality LLM notes with RLHF │
│ metadata including LLM model and API usage information │
└─────────────────────────────────────────────────────────────┘
🔄 LLM NOTES FEEDBACK COLLECTION
┌─────────────────────────────────────────────────────────────┐
│ Human reviewer evaluates LLM-generated notes quality: │
│ LLM Notes specific feedback metrics: │
│ - calculation_accuracy: Financial calculations (1-5) │
│ - account_classification: Account grouping accuracy (1-5) │
│ - statement_balance: Mathematical consistency (1-5) │
│ - accounting_standards: GAAP/IFRS compliance (1-5) │
│ - regulatory_compliance: Disclosure requirements (1-5) │
│ - completeness: All required notes present (1-5) │
│ - professional_presentation: Note formatting quality (1-5) │
│ - llm_coherence: Response clarity and logic (1-5) │
│ - content_relevance: Appropriateness for financials (1-5) │
│ - would_accept_for_audit: Audit trail approval │
│ - specific_errors: "LLM hallucinated account classification"│
│ → overall_score: LLM-weighted scoring algorithm │
└─────────────────────┬───────────────────────────────────────┘
│
▼
🎓 LLM NOTES MODEL IMPROVEMENT
┌─────────────────────────────────────────────────────────────┐
│ LLM Notes specific model enhancement: │
│ - Improve LLM response quality predictions │
│ - Enhance account classification accuracy assessment │
│ - Refine content relevance and coherence metrics │
│ - Update LLM model performance tracking │
│ - Optimize prompt engineering based on feedback │
│ → Better LLM notes quality predictions for future │
└─────────────────────────────────────────────────────────────┘
```
## 🏦 **Part 6: Balance Sheet Generation (RLHF-Enhanced Flow)**
```
📥 INPUT PHASE
┌─────────────────────────────────────────────────────────────┐
│ Client uploads Excel Trial Balance file │
│ Streamlit checkbox: "Use RLHF" = TRUE │
└─────────────────────┬───────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ POST /bs?use_rlhf=true request to FastAPI │
└─────────────────────┬───────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ FastAPI saves file to data/input/{filename} │
└─────────────────────┬───────────────────────────────────────┘
│
▼
🤖 RLHF WORKFLOW ORCHESTRATION
┌─────────────────────────────────────────────────────────────┐
│ run_rlhf_workflow(file_path, "bs") called from app.py │
└─────────────────────┬───────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ RLHFWorkflowManager creates RLHFFinancialAgentState │
│ - statement_id: uuid.uuid4() │
│ - statement_type: "balance_sheet" │
│ - Initialize candidate tracking │
└─────────────────────┬───────────────────────────────────────┘
│
▼
🔄 CANDIDATE GENERATION PHASE
┌─────────────────────────────────────────────────────────────┐
│ CANDIDATE 1 GENERATION │
│ _generate_candidates() calls generate_balance_sheet(): │
│ - Run balance_sheet_data_extractor.py (variant 1) │
│ - Apply different extraction parameters or thresholds │
│ - csv_json_bs.py with variation 1 │
│ - sircodebs.py with EnhancedBalanceSheetGenerator │
│ - Different template structure priority │
│ - AI-assisted extraction with prompt variation 1 │
│ → candidate_1_balance_sheet.xlsx │
└─────────────────────┬───────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ CANDIDATE 2 GENERATION │
│ Second call to generate_balance_sheet(): │
│ - Same data extraction process │
│ - Different AI prompt strategy for item extraction │
│ - Alternative account categorization approach │
│ - Different balance validation thresholds │
│ - Varied Excel formatting and styling options │
│ → candidate_2_balance_sheet.xlsx │
└─────────────────────┬───────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ CANDIDATE 3 GENERATION │
│ Third call to generate_balance_sheet(): │
│ - Same extraction pipeline │
│ - Third AI variation for complex account handling │
│ - Alternative totaling and validation logic │
│ - Different professional formatting approach │
│ → candidate_3_balance_sheet.xlsx │
└─────────────────────┬───────────────────────────────────────┘
│
▼
🎯 QUALITY PREDICTION PHASE
┌─────────────────────────────────────────────────────────────┐
│ Feature Extraction for Balance Sheet Candidates │
│ reward_model.extract_features() for each: │
│ - Balance sheet equation accuracy (Assets = Equity + Liab) │
│ - Number of line items extracted vs expected │
│ - Completeness of major sections (Current/Non-current) │
│ - Professional formatting quality metrics │
│ - Data consistency checks (zero balances, missing items) │
│ - Processing time and file size metrics │
│ → Feature vectors for quality prediction │
└─────────────────────┬───────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ Quality Scoring for Balance Sheet Candidates │
│ RandomForestRegressor predictions: │
│ - Candidate 1: Quality 3.4, Confidence 0.89 │
│ - Candidate 2: Quality 4.3, Confidence 0.94 │
│ - Candidate 3: Quality 3.9, Confidence 0.87 │
│ Model considers BS-specific quality factors │
└─────────────────────┬───────────────────────────────────────┘
│
▼
🏆 BEST CANDIDATE SELECTION PHASE
┌─────────────────────────────────────────────────────────────┐
│ _select_best_candidate() for Balance Sheet: │
│ - Prioritize mathematical accuracy (balance equation) │
│ - Consider completeness of financial statement sections │
│ - Evaluate professional presentation quality │
│ → Best Candidate: #2 (Quality: 4.3, Confidence: 0.94) │
│ - Highest combined score for BS-specific metrics │
└─────────────────────┬───────────────────────────────────────┘
│
▼
💾 STATEMENT STORAGE PHASE
┌─────────────────────────────────────────────────────────────┐
│ Store Balance Sheet for Human Review: │
│ feedback_manager.store_generated_statement(): │
│ - statement_type: "balance_sheet" │
│ - Balance sheet specific metadata: │
│ * balance_difference: calculated difference │
│ * total_assets: sum of all assets │
│ * total_equity_liabilities: sum of equity + liabilities │
│ * line_items_count: number of extracted items │
│ - predicted_quality: 4.3 │
│ - confidence_score: 0.94 │
└─────────────────────┬───────────────────────────────────────┘
│
▼
📤 ENHANCED OUTPUT PHASE
┌─────────────────────────────────────────────────────────────┐
│ FastAPI locates best candidate balance sheet Excel file │
│ Enhanced Response Headers: │
│ - X-RLHF-Statement-ID: uuid-456 │
│ - X-RLHF-Quality-Score: 4.3 │
│ - X-RLHF-Confidence: 0.94 │
│ - X-RLHF-Balance-Accuracy: calculated accuracy % │
└─────────────────────┬───────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ Client receives highest-quality balance sheet with RLHF │
│ metadata indicating prediction confidence │
└─────────────────────────────────────────────────────────────┘
🔄 BALANCE SHEET FEEDBACK COLLECTION
┌─────────────────────────────────────────────────────────────┐
│ Human reviewer evaluates balance sheet quality: │
│ BS-specific feedback metrics: │
│ - calculation_accuracy: Mathematical correctness (1-5) │
│ - account_classification: Proper Current/Non-current (1-5) │
│ - statement_balance: Assets = Equity + Liabilities (1-5) │
│ - accounting_standards: GAAP/IFRS compliance (1-5) │
│ - regulatory_compliance: Legal requirements (1-5) │
│ - completeness: All required line items present (1-5) │
│ - professional_presentation: Format quality (1-5) │
│ - would_accept_for_audit: Boolean approval │
│ - specific_errors: "Fixed assets classification issue" │
│ → overall_score: Weighted average of all metrics │
└─────────────────────┬───────────────────────────────────────┘
│
▼
🎓 BALANCE SHEET MODEL IMPROVEMENT
┌─────────────────────────────────────────────────────────────┐
│ Balance Sheet specific model enhancement: │
│ - Update feature importance for BS quality factors │
│ - Improve balance equation accuracy predictions │
│ - Enhance account classification confidence │
│ - Refine professional formatting assessment │
│ → Better balance sheet quality predictions for future │
└─────────────────────────────────────────────────────────────┘
```
## 💰 **Part 7: P&L Generation (RLHF-Enhanced Flow)**
```
📥 INPUT PHASE
┌─────────────────────────────────────────────────────────────┐
│ Client uploads Excel Trial Balance file │
│ Streamlit checkbox: "Use RLHF" = TRUE │
└─────────────────────┬───────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ POST /pnl?use_rlhf=true request to FastAPI │
└─────────────────────┬───────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ FastAPI saves file to data/input/{filename} │
└─────────────────────┬───────────────────────────────────────┘
│
▼
🤖 RLHF WORKFLOW ORCHESTRATION
┌─────────────────────────────────────────────────────────────┐
│ run_rlhf_workflow(file_path, "pnl") called from app.py │
└─────────────────────┬───────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ RLHFWorkflowManager creates RLHFFinancialAgentState │
│ - statement_type: "profit_and_loss" │
│ - Initialize P&L specific tracking │
└─────────────────────┬───────────────────────────────────────┘
│
▼
🔄 CANDIDATE GENERATION PHASE
┌─────────────────────────────────────────────────────────────┐
│ CANDIDATE 1 GENERATION │
│ _generate_candidates() calls generate_pnl_statement(): │
│ - Extract trial balance with revenue/expense focus │
│ - Apply mapping1.json with emphasis on income categories │
│ - Use rules1.json with P&L specific pattern matching │
│ - Revenue categorization approach 1: │
│ * Conservative revenue recognition │
│ * Detailed expense breakdown │
│ - Calculate EBITDA, EBIT, PBT, PAT with method 1 │
│ → candidate_1_pnl.xlsx │
└─────────────────────┬───────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ CANDIDATE 2 GENERATION │
│ Second call to generate_pnl_statement(): │
│ - Same data extraction │
│ - Alternative expense categorization: │
│ * Different Cost of Materials grouping │
│ * Alternative Employee Benefits categorization │
│ * Varied Other Expenses classification │
│ - Different depreciation calculation approach │
│ - Alternative profit calculation sequence │
│ → candidate_2_pnl.xlsx │
└─────────────────────┬───────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ CANDIDATE 3 GENERATION │
│ Third call to generate_pnl_statement(): │
│ - Same extraction foundation │
│ - Third approach to revenue/expense classification │
│ - Different handling of extraordinary items │
│ - Alternative tax calculation methodology │
│ - Varied comparative analysis with previous year │
│ → candidate_3_pnl.xlsx │
└─────────────────────┬───────────────────────────────────────┘
│
▼
🎯 QUALITY PREDICTION PHASE
┌─────────────────────────────────────────────────────────────┐
│ P&L Specific Feature Extraction: │
│ reward_model.extract_features() for each candidate: │
│ - Revenue recognition accuracy and completeness │
│ - Expense categorization correctness │
│ - Profit calculation accuracy (EBITDA → EBIT → PBT → PAT) │
│ - Comparative analysis quality (current vs previous year) │
│ - Compliance with accounting standards │
│ - Professional formatting and presentation │
│ - Mathematical consistency checks │
│ → P&L specific feature vectors │
└─────────────────────┬───────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ Quality Scoring for P&L Candidates: │
│ RandomForestRegressor predictions with P&L focus: │
│ - Candidate 1: Quality 3.6, Confidence 0.87 │
│ - Candidate 2: Quality 4.2, Confidence 0.93 │
│ - Candidate 3: Quality 3.8, Confidence 0.89 │
│ P&L specific quality assessment criteria applied │
└─────────────────────┬───────────────────────────────────────┘
│
▼
🏆 BEST CANDIDATE SELECTION PHASE
┌─────────────────────────────────────────────────────────────┐
│ _select_best_candidate() for P&L Statement: │
│ - Prioritize revenue/expense accuracy │
│ - Evaluate profit calculation correctness │
│ - Consider accounting standards compliance │
│ - Assess comparative analysis quality │
│ → Best Candidate: #2 (Quality: 4.2, Confidence: 0.93) │
│ - Optimal balance of accuracy and presentation │
└─────────────────────┬───────────────────────────────────────┘
│
▼
💾 STATEMENT STORAGE PHASE
┌─────────────────────────────────────────────────────────────┐
│ Store P&L Statement for Human Review: │
│ feedback_manager.store_generated_statement(): │
│ - statement_type: "profit_and_loss" │
│ - P&L specific metadata: │
│ * total_revenue: calculated total income │
│ * total_expenses: calculated total costs │
│ * net_profit: final PAT calculation │
│ * expense_categories_count: number of expense types │
│ - predicted_quality: 4.2 │
│ - confidence_score: 0.93 │
└─────────────────────┬───────────────────────────────────────┘
│
▼
📤 ENHANCED OUTPUT PHASE
┌─────────────────────────────────────────────────────────────┐
│ FastAPI creates FileResponse with best P&L candidate │
│ Enhanced Headers for P&L: │
│ - X-RLHF-Statement-ID: uuid-789 │
│ - X-RLHF-Quality-Score: 4.2 │
│ - X-RLHF-Confidence: 0.93 │
│ - X-RLHF-Profit-Accuracy: calculated accuracy metric │
└─────────────────────┬───────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ Client receives highest-quality P&L with RLHF metadata │
└─────────────────────────────────────────────────────────────┘
🔄 P&L FEEDBACK COLLECTION
┌─────────────────────────────────────────────────────────────┐
│ Human reviewer evaluates P&L statement quality: │
│ P&L specific feedback metrics: │
│ - calculation_accuracy: Revenue/expense calculations (1-5) │
│ - account_classification: Proper income/expense grouping │
│ - statement_balance: Mathematical consistency (1-5) │
│ - accounting_standards: Revenue recognition standards (1-5)│
│ - regulatory_compliance: P&L reporting requirements (1-5) │
│ - completeness: All income/expense items present (1-5) │
│ - professional_presentation: P&L format quality (1-5) │
│ - would_accept_for_audit: Audit trail approval │
│ - specific_errors: "Depreciation calculation method" │
│ → overall_score: P&L weighted scoring algorithm │
└─────────────────────┬───────────────────────────────────────┘
│
▼
🎓 P&L MODEL IMPROVEMENT
┌─────────────────────────────────────────────────────────────┐
│ P&L specific model enhancement: │
│ - Improve revenue recognition accuracy predictions │
│ - Enhance expense categorization algorithms │
│ - Refine profit calculation sequence assessment │
│ - Update comparative analysis quality metrics │
│ → Better P&L quality predictions for future statements │
└─────────────────────────────────────────────────────────────┘
```
## 💧 **Part 8: Cash Flow Generation (RLHF-Enhanced Flow)**
```
📥 INPUT PHASE
┌─────────────────────────────────────────────────────────────┐
│ Client uploads Excel Trial Balance file │
│ Streamlit checkbox: "Use RLHF" = TRUE │
└─────────────────────┬───────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ POST /cf?use_rlhf=true request to FastAPI │
└─────────────────────┬───────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ FastAPI saves file to data/input/{filename} │
└─────────────────────┬───────────────────────────────────────┘
│
▼
🤖 RLHF WORKFLOW ORCHESTRATION
┌─────────────────────────────────────────────────────────────┐
│ run_rlhf_workflow(file_path, "cf") called from app.py │
└─────────────────────┬───────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ RLHFWorkflowManager creates RLHFFinancialAgentState │
│ - statement_type: "cash_flow" │
│ - Initialize Cash Flow specific tracking │
└─────────────────────┬───────────────────────────────────────┘
│
▼
🔄 CANDIDATE GENERATION PHASE
┌─────────────────────────────────────────────────────────────┐
│ CANDIDATE 1 GENERATION │
│ _generate_candidates() calls generate_cash_flow_statement():│
│ - cf_middlestep.py execution with approach 1: │
│ * FinancialDataExtractor with default parameters │
│ * Standard working capital calculation method │
│ * Conservative approach to cash flow classifications │
│ - cf_generation.py with formatting style 1: │
│ * Standard CashFlowStatementGenerator │
│ * Traditional indirect method presentation │
│ → candidate_1_cash_flow.xlsx │
└─────────────────────┬───────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ CANDIDATE 2 GENERATION │
│ Second call to generate_cash_flow_statement(): │
│ - cf_middlestep.py with alternative approach: │
│ * Different working capital change calculations │
│ * Alternative depreciation and amortization handling │
│ * Varied investing activities categorization │
│ - cf_generation.py with enhanced formatting: │
│ * More detailed cash flow line items │
│ * Enhanced reconciliation and validation │
│ → candidate_2_cash_flow.xlsx │
└─────────────────────┬───────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ CANDIDATE 3 GENERATION │
│ Third call to generate_cash_flow_statement(): │
│ - cf_middlestep.py with comprehensive approach: │
│ * Detailed operating activities breakdown │
│ * Alternative financing activities treatment │
│ * Enhanced cash equivalents definition │
│ - cf_generation.py with advanced formatting: │
│ * Comprehensive components of cash section │
│ * Advanced validation and cross-checks │
│ → candidate_3_cash_flow.xlsx │
└─────────────────────┬───────────────────────────────────────┘
│
▼
🎯 QUALITY PREDICTION PHASE
┌─────────────────────────────────────────────────────────────┐
│ Cash Flow Specific Feature Extraction: │
│ reward_model.extract_features() for each candidate: │
│ - Cash flow reconciliation accuracy │
│ - Operating activities calculation correctness │
│ - Working capital changes validation │
│ - Investing activities completeness │
│ - Financing activities accuracy │
│ - Net cash flow mathematical consistency │
│ - Beginning/ending cash reconciliation │
│ - Components of cash and equivalents detail │
│ → Cash flow specific feature vectors │
└─────────────────────┬───────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ Quality Scoring for Cash Flow Candidates: │
│ RandomForestRegressor predictions with CF focus: │
│ - Candidate 1: Quality 3.5, Confidence 0.86 │
│ - Candidate 2: Quality 4.4, Confidence 0.95 │
│ - Candidate 3: Quality 4.0, Confidence 0.91 │
│ Cash flow specific quality criteria emphasized │
└─────────────────────┬───────────────────────────────────────┘
│
▼
🏆 BEST CANDIDATE SELECTION PHASE
┌─────────────────────────────────────────────────────────────┐
│ _select_best_candidate() for Cash Flow Statement: │
│ - Prioritize cash reconciliation accuracy │
│ - Evaluate mathematical consistency across sections │
│ - Consider working capital calculation precision │
│ - Assess comprehensive activity coverage │
│ → Best Candidate: #2 (Quality: 4.4, Confidence: 0.95) │
│ - Highest accuracy in cash flow methodology │
└─────────────────────┬───────────────────────────────────────┘
│
▼
💾 STATEMENT STORAGE PHASE
┌─────────────────────────────────────────────────────────────┐
│ Store Cash Flow Statement for Human Review: │
│ feedback_manager.store_generated_statement(): │
│ - statement_type: "cash_flow" │
│ - Cash Flow specific metadata: │
│ * operating_cash_flow: net cash from operations │
│ * investing_cash_flow: net cash from investing │
│ * financing_cash_flow: net cash from financing │
│ * net_cash_change: total change in cash │
│ * cash_reconciliation_accuracy: percentage match │
│ - predicted_quality: 4.4 │
│ - confidence_score: 0.95 │
└─────────────────────┬───────────────────────────────────────┘
│
▼
📤 ENHANCED OUTPUT PHASE
┌─────────────────────────────────────────────────────────────┐
│ FastAPI creates FileResponse with best CF candidate │
│ Enhanced Headers for Cash Flow: │
│ - X-RLHF-Statement-ID: uuid-012 │
│ - X-RLHF-Quality-Score: 4.4 │
│ - X-RLHF-Confidence: 0.95 │
│ - X-RLHF-Cash-Reconciliation: reconciliation percentage │
└─────────────────────┬───────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ Client receives highest-quality Cash Flow with RLHF data │
└─────────────────────────────────────────────────────────────┘
🔄 CASH FLOW FEEDBACK COLLECTION
┌─────────────────────────────────────────────────────────────┐
│ Human reviewer evaluates Cash Flow statement quality: │
│ Cash Flow specific feedback metrics: │
│ - calculation_accuracy: Cash flow calculations (1-5) │
│ - account_classification: Activity categorization (1-5) │
│ - statement_balance: Cash reconciliation accuracy (1-5) │
│ - accounting_standards: Cash flow standards compliance(1-5)│
│ - regulatory_compliance: CF reporting requirements (1-5) │
│ - completeness: All activities and components covered (1-5)│
│ - professional_presentation: CF format quality (1-5) │
│ - would_accept_for_audit: Cash flow audit acceptance │
│ - specific_errors: "Working capital calculation method" │
│ → overall_score: Cash flow weighted scoring algorithm │
└─────────────────────┬───────────────────────────────────────┘
│
▼
🎓 CASH FLOW MODEL IMPROVEMENT
┌─────────────────────────────────────────────────────────────┐
│ Cash Flow specific model enhancement: │
│ - Improve cash reconciliation accuracy predictions │
│ - Enhance working capital change calculations │
│ - Refine activity classification algorithms │
│ - Update cash flow methodology assessment │
│ → Better Cash Flow quality predictions for future │
└─────────────────────────────────────────────────────────────┘
🔄 CONTINUOUS IMPROVEMENT CYCLE
┌─────────────────────────────────────────────────────────────┐
│ All 4 RLHF Statement Types Feed into Model Improvement: │
│ - Notes feedback → Note generation quality enhancement │
│ - Balance Sheet feedback → BS accuracy improvement │
│ - P&L feedback → Revenue/expense classification refinement │
│ - Cash Flow feedback → Cash reconciliation enhancement │
│ │
│ Cross-Statement Learning: │
│ - Common quality patterns across all statement types │
│ - Professional presentation standards │
│ - Accounting compliance improvements │
│ - Mathematical accuracy enhancements │
│ │
│ → Unified Financial Statement Quality Prediction Model │
└─────────────────────────────────────────────────────────────┘
```
## 🔄 **RLHF Enhanced Processing Flow**
```
📤 CLIENT REQUEST
┌─────────────────────┐
│ POST /pnl? │
│ use_rlhf=true │
└─────────┬───────────┘
│
▼
┌─────────────────────┐
│ FastAPI Endpoint │
└─────────┬───────────┘
│
▼
┌─────────────────────┐
│ RLHF Workflow │
│ Manager │
└─────────┬───────────┘
│
▼
🎯 CANDIDATE GENERATION
┌─────────────────────┐
│ Generate P&L │
│ Statement │
│ [Candidate 1] │
└─────────┬───────────┘
│
▼
┌─────────────────────┐
│ Generate P&L │
│ Statement │
│ [Candidate 2] │
└─────────┬───────────┘
│
▼
┌─────────────────────┐
│ Generate P&L │
│ Statement │
│ [Candidate 3] │
└─────────┬───────────┘
│
▼
🤖 QUALITY PREDICTION
┌─────────────────────┐
│ Reward Model │
│ predict_quality() │
│ │
│ Candidate 1: 3.2 │
│ Confidence: 0.85 │
└─────────┬───────────┘
│
▼
┌─────────────────────┐
│ Reward Model │
│ predict_quality() │
│ │
│ Candidate 2: 4.1 │
│ Confidence: 0.92 │
└─────────┬───────────┘
│
▼
┌─────────────────────┐
│ Reward Model │
│ predict_quality() │
│ │
│ Candidate 3: 3.8 │
│ Confidence: 0.88 │
└─────────┬───────────┘
│
▼
🎖️ BEST SELECTION
┌─────────────────────┐
│ select_best_ │
│ candidate() │
│ │
│ → Candidate 2 │
│ (Highest Score) │
└─────────┬───────────┘
│
▼
┌─────────────────────┐
│ Feedback Manager │
│ store_generated_ │
│ statement() │
│ │
│ → Statement ID: │
│ uuid-123 │
└─────────┬───────────┘
│
▼
📤 RESPONSE TO CLIENT
┌─────────────────────┐
│ Excel File + │
│ RLHF Headers: │
│ │
│ X-Statement-ID │
│ X-Quality-Score │
│ X-Confidence │
└─────────┬───────────┘
│
▼
👥 HUMAN REVIEW CYCLE
┌─────────────────────┐
│ Human Reviews │
│ Statement │
└─────────┬───────────┘
│
▼
┌─────────────────────┐
│ POST /rlhf/feedback │
│ │
│ Statement-ID: 123 │
│ Ratings: 1-5 scale │
└─────────┬───────────┘
│
▼
┌─────────────────────┐
│ Feedback Manager │
│ store_feedback() │
└─────────┬───────────┘
│
▼
┌─────────────────────┐
│ Reward Model │
│ trigger_retraining_ │
│ if_needed() │
└─────────────────────┘
```
## 🛠️ **Component Interaction Flow**
```
📡 API LAYER
┌─────────────┐ ┌─────────────┐
│ FastAPI │ │ RLHF │
│ App │ │ Routes │
└──────┬──────┘ └──────┬──────┘
│ │
▼ ▼
🔄 WORKFLOW LAYER
┌─────────────┐ ┌─────────────┐
│ LangGraph │ │ RLHF │
│ Workflows │ │ Workflows │
└──────┬──────┘ └──────┬──────┘
│ │
└─────┬────────────┘
▼
🛠️ TOOLS LAYER
┌─────────────┐
│ Simple │
│ Tools │
└──────┬──────┘
│
┌──┴────────────────┬────────────────┬──────────────┐
▼ ▼ ▼ ▼
┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐
│ BS │ │ PnL │ │ CF │ │ Notes │
│ Tool │ │ Tool │ │ Tool │ │ Tool │
└────┬────┘ └────┬────┘ └────┬────┘ └────┬────┘
│ │ │ │
└──────┬───────┴──────┬───────┴──────┬───────┘
▼ ▼ ▼
⚙️ PROCESSING LAYER
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ Data │ │ Data │ │ Excel │
│ Extraction │ │ Processing │ │ Formatting │
└──────┬──────┘ └──────┬──────┘ └──────┬──────┘
│ │ │
└─────┬────────────┴─────┬────────────┘
▼ ▼
🤖 RLHF LAYER
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ Feedback │ │ Reward │ │ RLHF │
│ Manager │ │ Model │ │ Trainer │
└──────┬──────┘ └──────┬──────┘ └──────┬──────┘
│ │ │
└─────┬────────────┴─────┬────────────┘
▼ ▼
💾 STORAGE LAYER
┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ JSON │ │ Excel │ │ Feedback │ │ Model │
│ Storage │ │ Output │ │ Database │ │ Storage │
└─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘
```
## 📈 **RLHF Training & Improvement Cycle**
```
🎯 START
┌─────────────────────┐
│ Statement Generation│
│ Request │
└─────────┬───────────┘
│
▼
┌─────────────────────┐
│ RLHF Enabled │
│ (?) │
└─────┬─────────┬─────┘
│ │
NO│ │YES
▼ ▼
┌──────────┐ ┌──────────┐
│ Standard │ │ RLHF │
│ Workflow │ │ Workflow │
└─────┬────┘ └─────┬────┘
│ │
▼ ▼
┌──────────┐ ┌──────────┐
│ Generate │ │Generate 3│
│ Single │ │Candidates│
│Statement │ │ │
└─────┬────┘ └─────┬────┘
│ │
└─────┬──────┘
▼
┌─────────────────────┐
│ Extract Features │
│ for Each Candidate │
└─────────┬───────────┘
│
▼
┌─────────────────────┐
│ Predict Quality │
│ Scores │
└─────────┬───────────┘
│
▼
┌─────────────────────┐
│ Select Best │
│ Candidate │
└─────────┬───────────┘
│
▼
┌─────────────────────┐
│ Store for Feedback │
└─────────┬───────────┘
│
▼
┌─────────────────────┐
│ Excel Output │
└─────────┬───────────┘
│
▼
👥 HUMAN FEEDBACK
┌─────────────────────┐
│ Human Review │
└─────────┬───────────┘
│
▼
┌─────────────────────┐
│ Feedback Form │
└─────────┬───────────┘
│
▼
┌─────────────────────┐
│ Collect Ratings │
│ (1-5 scale) │
└─────────┬───────────┘
│
▼
💾 FEEDBACK STORAGE
┌─────────────────────┐
│ Feedback Database │
└─────────┬───────────┘
│
▼
┌─────────────────────┐
│ Enough Samples │
│ (?) │
└─────┬─────────┬─────┘
│ │
NO│ │YES
▼ ▼
┌──────────┐ ┌──────────┐
│ Wait │ │ Retrain │
│ for │ │ Reward │
│ More │ │ Model │
│Feedback │ │ │
└─────┬────┘ └─────┬────┘
│ │
└─────┐ ▼
│ ┌──────────┐
│ │ Update │
│ │ Model │
│ │ Weights │
│ └─────┬────┘
│ │
│ ▼
│ ┌──────────┐
│ │ Improved │
│ │Predictions│
│ └─────┬────┘
│ │
└───────┼─────────┐
│ │
┌─────────┘ │
▼ │
(Back to Human) │
│
┌───────────────┘
▼
(Back to RLHF Start)
```
## 🎯 **Statement Type Processing Flows**
```
📝 NOTES GENERATION
┌─────────────────────┐
│ Trial Balance Excel │
└─────────┬───────────┘
│
▼
┌─────────────────────┐
│extract_trial_ │
│balance_data │
└─────────┬───────────┘
│
▼
┌─────────────────────┐
│analyze_and_save_ │
│results │
└─────────┬───────────┘
│
▼
┌─────────────────────┐
│ process_json │
└─────────┬───────────┘
│
▼
┌─────────────────────┐
│ LLM Notes Generation│
└─────────┬───────────┘
│
▼
┌─────────────────────┐
│ JSON Normalization │
└─────────┬───────────┘
│
▼
┌─────────────────────┐
│ json_to_xlsx │
└─────────┬───────────┘
│
▼
┌─────────────────────┐
│ final_output.xlsx │
└─────────────────────┘
📊 BALANCE SHEET
┌─────────────────────┐
│ Trial Balance Excel │
└─────────┬───────────┘
│
▼
┌─────────────────────┐
│ BS Data Extractor │
└─────────┬───────────┘
│
▼
┌─────────────────────┐
│clean_financial_ │
│data_bs.json │
└─────────┬───────────┘
│
▼
┌─────────────────────┐
│ BS Generator │
└─────────┬───────────┘
│
▼
┌─────────────────────┐
│ Excel Formatting │
└─────────┬───────────┘
│
▼
┌─────────────────────┐
│ balance_sheet.xlsx │
└─────────────────────┘
💰 P&L STATEMENT
┌─────────────────────┐
│ Trial Balance Excel │
└─────────┬───────────┘
│
▼
┌─────────────────────┐
│ PnL Data Processing │
└─────────┬───────────┘
│
▼
┌─────────────────────┐
│ PnL Calculations │
└─────────┬───────────┘
│
▼
┌─────────────────────┐
│ Excel Export │
└─────────┬───────────┘
│
▼
┌─────────────────────┐
│ pnl_statement.xlsx │
└─────────────────────┘
💧 CASH FLOW
┌─────────────────────┐
│ Trial Balance Excel │
└─────────┬───────────┘
│
▼
┌─────────────────────┐
│ CF Data Processor │
└─────────┬───────────┘
│
▼
┌─────────────────────┐
│extracted_cfs_ │
│data.json │
└─────────┬───────────┘
│
▼
┌─────────────────────┐
│CF Statement │
│Generator │
└─────────┬───────────┘
│
▼
┌─────────────────────┐
│ Excel Formatting │
└─────────┬───────────┘
│
▼
┌─────────────────────┐
│cash_flow_statements.│
│xlsx │
└─────────────────────┘
```
**generator-validator**
┌─────────────────┐
│ API Request │
│ POST /notes-llm│
│ with file │
└─────────┬───────┘
│
▼
┌─────────────────┐
│ create_notes_ │
│ pipeline() │
│ │
│ → LLMNotesGen │
│ → NotesValidator│
└─────────┬───────┘
│
▼
┌─────────────────┐ ┌─────────────────┐
│Generator-Validator│◄───│ Max 3 Attempts │
│ Pipeline │ │ │
│ │ │ │
│ ┌─────────────┐ │ └─────────────────┘
│ │ Attempt │ │ │ No
│ │ Counter=0 │ │ ▼
│ └─────────────┘ │ ┌─────────────────┐
└─────────┬───────┘ │ Return Best │
│ │ Result │
▼ └─────────────────┘
┌─────────────────┐
│ Generate │
│ (LLM) │
│ │
│ - Call langgraph│
│ - Use RLHF if │
│ requested │
│ - Track attempt │
└─────────┬───────┘
│
▼
┌─────────────────┐
│ Validate │
│ Quality │
│ │
│ - File exists │
│ - Size >1KB │
│ - Metadata OK │
│ - RLHF quality │
│ - Score 0.0-1.0 │
└─────────┬───────┘
│
┌─────┴─────┐
│ │
▼ ▼
┌─────────┐ ┌─────────┐
│ Valid? │ │ Invalid │
│ Score │ │ Score │
│ ≥0.6 │ │ <0.6 │
└─────┬───┘ └─────┬───┘
│ │
▼ ▼
┌─────────┐ ┌─────────┐
│ Return │ │ Refine │
│ Success │ │ & Retry │
│ with │ │ │
│ Metadata │ │ - Use │
│ Headers │ │ feedback│
└─────────┘ └─────┬───┘
│
▼
┌─────────┐
│Increment │
│ Attempt │
│ Counter │
└─────┬───┘
│
└─────────────┐
▼
┌─────────────────┐
│ Continue to │
│ Next Attempt │
└─────────────────┘
**refine and retry**
┌─────────────────┐
│ Attempt 1 │
│ Generate │
│ → Validate │
│ Score: 0.4 │ ❌ FAIL (< 0.6)
└─────────┬───────┘
│
▼
┌─────────────────┐
│ Refinement │
│ Analysis │
│ │
│ Feedback: │
│ - "Low quality" │
│ - "Small file" │
└─────────┬───────┘
│
┌─────┴─────┐
│ │
▼ ▼
┌─────────┐ ┌─────────┐
│Quality │ │Other │
│Issue? │ │Issue? │
│ │ │ │
│"quality" │ │File size │
│in feedback│ │Metadata │
└─────┬───┘ └─────┬───┘
│ │
▼ ▼
┌─────────┐ ┌─────────┐
│Switch to │ │Simple │
│RLHF │ │Retry │
│Mode │ │ │
│ │ │Use same │
│use_rlhf= │ │config │
│true │ │ │
└─────┬───┘ └─────┬───┘
│ │
└─────┬─────┘
│
▼
┌─────────────────┐
│ Attempt 2 │
│ Generate │
│ (Improved) │
│ → Validate │
│ Score: 0.8 │ ✅ SUCCESS (≥ 0.6)
└─────────────────┘