README.md

---
title: FinRyver
sdk: gradio
emoji: 📈
colorFrom: yellow
colorTo: yellow
pinned: true
---
title: FinRyver
emoji: 🌖
colorFrom: yellow
colorTo: yellow
sdk: docker
sdk_version: latest
app_file: app.py
pinned: false

# FinRyver 🏦

## 📋 Overview

FinRyver is an AI-powered financial statement generation platform that automatically converts trial balance data into comprehensive financial reports including balance sheets, cash flow statements, and profit & loss statements. Built with FastAPI and leveraging Large Language Models (LLMs) through LangGraph workflows, it streamlines the financial reporting process for accountants, auditors, and financial professionals.

**LangGraph Architecture**: FinRyver now features an intelligent **agentic system** powered by LangGraph that provides AI-driven workflow orchestration, state management, and intelligent task coordination for financial statement generation.

## 🎯 Key Features

- **Automated Trial Balance Processing**: Upload Excel files containing trial balance data and automatically extract structured financial information
- **AI-Powered Financial Notes Generation**: Utilize LLMs to generate comprehensive financial notes with detailed explanations and context
- **LangGraph Workflow Orchestration**: State-driven workflows that manage complex financial processing tasks with proper error handling and monitoring
- **Multi-Statement Support**: Generate Balance Sheets, Cash Flow Statements, and Profit & Loss statements from the same data source
- **Excel Output Generation**: Export all generated reports and notes to professional Excel formats
- **RESTful API Architecture**: Easy integration with existing financial systems through well-documented REST endpoints
- **Specialized Endpoints**: Dedicated routes for each financial statement type (`/notes`, `/pnl`, `/bs`, `/cf`)
- **Performance Monitoring**: Built-in timing and status tracking for all agentic workflows

## 🏗️ Project Architecture

```
FinRyver/
├── app.py                 # Main FastAPI application with 4 specialized routes
├── requirements.txt       # Python dependencies 
├── Dockerfile            # Container configuration
├── docker-compose.yml    # Multi-container orchestration
├── 
├── agents/               # LangGraph-based agentic system
│   ├── langgraph.py   # LangGraph workflow definitions
│   ├── simple_tools.py       # LangChain tools for financial processing
│   ├── base_config.py        # Agent configuration and utilities
│   └── simple_agent.py       # Financial statement agent (legacy)
├── 
├── bs/                   # Balance Sheet processing modules
│   ├── bl_llm.py         # Balance sheet LLM integration
│   ├── csv_json_bs.py    # Balance sheet data conversion
│   └── sircodebs.py      # Balance sheet generation logic
├── 
├── cf/                   # Cash Flow processing modules
│   ├── cf_generation.py  # Cash flow statement generation
│   ├── cf_middlestep.py  # Intermediate processing steps
│   └── csv_json_cf.py    # Cash flow data conversion
├── 
├── pnl/                  # Profit & Loss processing modules
│   ├── pnl_note.py       # P&L notes generation
│   └── sircodepnl.py     # P&L statement logic
├── 
├── notes/                # Core notes generation engine
│   ├── data_extraction.py     # Trial balance data extraction
│   ├── llm_notes_generator.py # LLM-powered note generation
│   ├── notes_generator.py     # Notes processing pipeline
│   ├── json_to_excel.py       # Excel export functionality
│   └── notes_template.py      # Note templates and formatting
├── 
├── utils/                # Shared utilities
│   ├── utils.py          # General utility functions
│   └── utils_normalize.py # Data normalization functions
├── 
├── config/               # Configuration files
│   ├── mapping1.json     # Account mapping configurations
│   └── rules1.json       # Business rules and validation
├── 
└── data/                 # Data storage and processing
    ├── input/            # Uploaded trial balance files
    ├── output/           # Generated financial statements
    ├── csv_notes_*/      # Processed CSV data by statement type
    └── generated_notes/  # AI-generated financial notes
```

### Data Flow Architecture

```
Trial Balance Upload → Data Extraction → AI Processing → Financial Statements
        ↓                    ↓               ↓              ↓
    Excel File          JSON Structure   LLM Analysis    Excel Export
```

## 🛠️ Technologies Used

### Backend Framework
- **FastAPI**: Modern, fast web framework for building APIs with Python
- **Uvicorn**: ASGI server implementation for FastAPI applications
- **Pydantic**: Data validation and settings management using Python type annotations

### Data Processing
- **Pandas**: Data manipulation and analysis library for structured financial data
- **OpenPyXL**: Excel file reading and writing capabilities
- **JSON**: Data interchange format for internal processing

### AI/ML Integration
- **Large Language Models (LLMs)**: For intelligent financial note generation and analysis
- **LangChain Framework**: Tool integration and AI agent development
- **LangGraph**: Workflow orchestration and state management for complex financial processing
- **OpenRouter API**: Flexible LLM provider integration for AI-powered analysis
- **Custom AI Pipelines**: Specialized processing for financial data interpretation

### Infrastructure
- **Docker**: Containerization for consistent deployment across environments
- **Docker Compose**: Multi-container application orchestration

### Development Tools
- **Python 3.11+**: Core programming language
- **Git**: Version control and collaboration

## 💻 Implementation Details

### Core Components

1. **Trial Balance Processor** (`notes/data_extraction.py`)
   - Extracts and validates trial balance data from Excel uploads
   - Converts unstructured financial data into standardized JSON format
   - Implements data cleaning and normalization algorithms

2. **LLM Notes Generator** (`notes/llm_notes_generator.py`)
   - Integrates with language models for intelligent note generation
   - Contextualizes financial data with industry-standard explanations
   - Supports flexible note numbering and categorization

3. **Financial Statement Generators**
   - **Balance Sheet Module** (`bs/`): Generates comprehensive balance sheets with supporting notes
   - **Cash Flow Module** (`cf/`): Creates cash flow statements with categorized activities
   - **P&L Module** (`pnl/`): Produces profit & loss statements with detailed breakdowns

4. **Excel Export Engine** (`notes/json_to_excel.py`)
   - Converts processed JSON data into professional Excel formats
   - Maintains financial statement formatting standards
   - Supports multiple output templates

### Design Patterns
- **Modular Architecture**: Separation of concerns across financial statement types
- **Factory Pattern**: Dynamic generation of financial reports based on input data
- **Pipeline Pattern**: Sequential data processing from upload to final output

### API Endpoints

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/notes` | POST | Generate financial notes from trial balance using LangGraph workflow |
| `/pnl` | POST | Generate P&L statement from trial balance using LangGraph workflow |
| `/bs` | POST | Generate balance sheet from trial balance using LangGraph workflow |
| `/cf` | POST | Generate cash flow statement from trial balance using LangGraph workflow |

#### LangGraph-Powered Endpoints

All endpoints follow the same pattern and use LangGraph workflows for intelligent task orchestration:

**Parameters:**
- `file`: Trial balance Excel file (multipart/form-data)

**Response:**
- Excel file download with the generated financial statement

**Example Usage:**
```bash
# Generate financial notes
curl -X POST "http://localhost:8000/notes" \
  -H "Content-Type: multipart/form-data" \
  --output notes.xlsx

# Generate P&L statement
curl -X POST "http://localhost:8000/pnl" \
  -H "Content-Type: multipart/form-data" \
  --output pnl_statement.xlsx

# Generate balance sheet
curl -X POST "http://localhost:8000/bs" \
  -H "Content-Type: multipart/form-data" \
  --output balance_sheet.xlsx

# Generate cash flow statement
curl -X POST "http://localhost:8000/cf" \
  -H "Content-Type: multipart/form-data" \
  -F "file=@trial_balance.xlsx" \
  --output cash_flow.xlsx
```

**LangGraph Workflow Features:**
- **State Management**: Each workflow tracks execution state, timing, and errors
- **Error Handling**: Comprehensive error capture and reporting
- **Performance Monitoring**: Built-in timing for workflow execution
- **Tool Integration**: Seamless integration with LangChain tools

## 📊 Results & Examples

### Input Format
Upload trial balance Excel files containing:
- Account codes and descriptions
- Debit/Credit amounts
- Account categories and classifications

### Output Examples
- **Financial Notes**: AI-generated explanations for each financial statement line item
- **Balance Sheet**: Comprehensive balance sheet with assets, liabilities, and equity
- **Cash Flow Statement**: Operating, investing, and financing activities breakdown
- **P&L Statement**: Revenue, expenses, and profit analysis

### Performance Metrics
- **Processing Time**: < 30 seconds for standard trial balance files
- **Accuracy**: 95%+ accuracy in financial data extraction and categorization
- **Note Quality**: Professional-grade financial notes suitable for audit and compliance

## 🚀 Setup & Usage

### Prerequisites
- Python 3.11 or higher
- Docker and Docker Compose (for containerized deployment)
- 4GB+ RAM for LLM processing

### Installation

#### Local Development
```bash
# Clone the repository
git clone https://github.com/santhoshmallojwala/finryver.git
cd finryver

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Run the application
uvicorn app:app --host 0.0.0.0 --port 8000 --reload
```

#### Docker Deployment
```bash
# Build and run with Docker
docker-compose up -d

# Or build manually
docker build -t finryver .
docker run -p 8000:8000 finryver
```

### Configuration
1. **Environment Variables**: Configure API keys and LLM settings in `.env`
2. **Business Rules**: Modify `config/rules1.json` for custom validation rules
3. **Account Mapping**: Update `config/mapping1.json` for account categorization

#### Agentic System Configuration

For the intelligent agent features, ensure you have your LLM API key configured:

```env
# Required for agentic system
OPENROUTER_API_KEY=your_openrouter_api_key_here

# Optional agent configuration
AGENT_MODEL=gpt-3.5-turbo
AGENT_TEMPERATURE=0.1
AGENT_MAX_TOKENS=2000
```

**Agent Benefits:**
- Natural language understanding for financial tasks
- Intelligent workflow orchestration
- Unified interface for all financial statements
- Error recovery and retry logic
- Contextual financial analysis

### Usage Examples

#### Generate Complete Financial Report
```bash
curl -X POST "http://localhost:8000/new" \
  -H "Content-Type: multipart/form-data" \
  -F "file=@trial_balance.xlsx" \
  -F "note_number=1,2,3,4,5"
```

#### Generate Specific Financial Statement
```bash
# Balance Sheet from existing notes
curl -X POST "http://localhost:8000/bs_from_notes" \
  -H "Content-Type: multipart/form-data" \
  -F "file=@notes.json"
```

### API Documentation
Access interactive API documentation at `http://localhost:8000/docs` when the application is running.

## 🧪 Testing

### Testing Framework
- **Manual Testing**: Comprehensive testing with sample trial balance files
- **Integration Testing**: End-to-end API endpoint validation
- **Data Validation**: Financial calculation accuracy verification

### Running Tests
```bash
# Test API endpoints
curl -X GET "http://localhost:8000/docs"

# Validate with sample data
python -m pytest tests/ --verbose
```

## 📚 Documentation

- **API Documentation**: Available at `/docs` endpoint when running
- **Financial Standards**: Adheres to GAAP/IFRS reporting standards
- **Code Documentation**: Inline comments and docstrings throughout codebase

## 🔮 Future Roadmap

### Completed Features ✅
- **Intelligent Agentic System**: LangChain-powered agents with natural language processing
- **Unified Agent Interface**: Single endpoint for all financial statement generation
- **Optional Note Numbers**: Flexible note generation (specific or all notes)

### Planned Features
- **Multi-Currency Support**: Handle international financial statements
- **Advanced AI Models**: Integration with latest financial AI models
- **Real-time Processing**: WebSocket support for live data updates
- **Audit Trail**: Comprehensive logging and change tracking
- **Custom Templates**: User-defined financial statement templates
- **Agent Conversation History**: Multi-turn conversations with financial agents

### Known Limitations
- Currently supports Excel input formats only
- Limited to standard chart of accounts structures
- Requires internet connectivity for LLM operations

### Development Timeline
- **Q1 2025**: Multi-currency support and enhanced validation
- **Q2 2025**: Advanced AI model integration
- **Q3 2025**: Real-time processing capabilities
- **Q4 2025**: Enterprise audit and compliance features

## 👥 Contributors

### Core Team
- **Santosh Mallojwala** - Project Lead & Backend Development
- **Point9 AI Team** - AI/ML Integration and Architecture

### Contribution Guidelines
1. Fork the repository
2. Create feature branches (`feature/your-feature-name`)
3. Follow PEP 8 coding standards
4. Add comprehensive tests for new features
5. Submit pull requests with detailed descriptions

### Acknowledgments
- OpenAI and LLM providers for AI capabilities
- FastAPI community for framework support
- Financial industry experts for domain guidance

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

### Usage Restrictions
- Commercial use permitted with attribution
- Ensure compliance with local financial regulations
- AI-generated content should be reviewed by qualified professionals

---

**FinRyver** - Transforming Financial Reporting with AI 🚀