# 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)
└─────────────────┘