Financial Risk Analysis AI Assistant

An AI-powered credit risk assessment and regulatory compliance platform built with Python, FastAPI, RAG (LangChain + FAISS), and Claude API.

The system allows credit risk officers to submit custom queries or upload JSON financial statements. It automatically extracts financial ratios, fetches relevant compliance directives from Basel III, IFRS 9, and SEC regulations, and uses Claude (Anthropic API) to formulate structured risk profiles complete with vector similarity citations, confidence ratings, and LLM-as-a-Judge audits.

---

Key Features

1. AI Credit Risk Reports: Side-by-side prompt tuning comparison of three prompt variations (Zero-Shot, Few-Shot, and Chain-of-Thought reasoning).
2. LLM-as-a-Judge Auditing: Quality assurance module scoring response output dimensions (Accuracy, Completeness, and Regulatory Alignment) and providing constructive feedback logs.
3. Regulatory RAG Corpus: Standard regulatory references indexed into a FAISS vector store using LangChain. It performs real-time similarity matching against financial queries.
4. Automated Risk Solvency Engines: Automatically computes core leverage and liquidity ratios (Current Ratio, Debt-to-Equity, Interest Coverage) and the Altman Z-Score from corporate balance sheets.
5. Role-Based Access Control (RBAC): Secure routes using JWT signatures with distinct authorization scopes (ANALYST or ADMIN).
6. Premium Glassmorphic Dashboard: A fully interactive single-page dashboard styled with modern CSS variables, containing cards, gauges, charts, vector search consoles, and testing controls.

---

Tech Stack

• Backend: FastAPI, SQLAlchemy (PostgreSQL / SQLite fallback), JWT, Passlib (bcrypt).
• AI & Search: LangChain, FAISS Vector Indexing, Anthropic SDK (Claude 3.5 Sonnet).
• Frontend: React (Vite), Vanilla CSS variables.
• Testing Suite: Pytest, Pytest-asyncio, HTTPX client mock interfaces.

---

Directory Structure

financial-risk-analysis-ai/
├── backend/
│   ├── app/
│   │   ├── routes/
│   │   │   ├── auth.py
│   │   │   ├── companies.py
│   │   │   ├── assessments.py
│   │   │   └── regulatory.py
│   │   ├── __init__.py
│   │   ├── main.py
│   │   ├── config.py
│   │   ├── database.py
│   │   ├── models.py
│   │   ├── schemas.py
│   │   ├── auth.py
│   │   ├── rag.py
│   │   └── risk_analyst.py
│   ├── tests/
│   │   ├── conftest.py
│   │   ├── test_auth.py
│   │   ├── test_companies.py
│   │   ├── test_assessments.py
│   │   └── test_rag.py
│   └── seed_data.py
├── frontend/                 # React source files scaffolded with Vite
│   ├── src/
│   │   ├── App.jsx
│   │   ├── App.css
│   │   ├── index.css
│   │   └── main.jsx
│   ├── index.html
│   ├── vite.config.js
│   └── package.json
├── static/                   # Compiled static production assets from React (Vite output)
│   ├── assets/
│   └── index.html
├── requirements.txt
├── .env.example
├── .gitignore
└── README.md

---

Getting Started

1. Prerequisite Installations

Ensure Python 3.10+, Node.js (v18+), and Git are installed on your system.

2. Set Up Virtual Environment

Initialize a clean Python virtual environment:

# Navigate to the workspace directory
cd financial-risk-analysis-ai

# Create virtual environment
python -m venv venv

# Activate virtual environment
# On Windows (PowerShell):
.\venv\Scripts\Activate.ps1
# On macOS / Linux:
source venv/bin/activate

3. Install Package Dependencies

Install backend and frontend dependencies:

# Install Python packages
pip install -r requirements.txt

# Install Node modules
cd frontend
npm install
cd ..

4. Configure Environment Variables

Create your local .env configuration file from the template:

cp .env.example .env

By default, the database will attempt to connect to PostgreSQL. If your PostgreSQL database is offline or not configured, the system automatically falls back to an in-memory/local SQLite database file financial_risk.db in the workspace directory.

Provide your ANTHROPIC_API_KEY in the .env file to activate production Claude API integrations. If empty, the system runs in a Simulated Intelligence Mode, displaying fully mock financial reports and prompt tuning logs to support immediate, out-of-the-box local developer testing!

5. Seed the Database and RAG Index

Populate the database with default Analyst and Admin user accounts, companies (Global Energy, Nova Tech, Apex Builders), standard guidelines (Basel III leverage rules, IFRS 9 ECL criteria, SEC risk reports), and initialize the FAISS vector index:

python backend/seed_data.py

6. Run the Server

You can run the development servers for both the backend and frontend:

Backend FastAPI Server:

uvicorn backend.app.main:app --reload

Frontend Vite Server (proxied to port 8000 for local requests):

cd frontend
npm run dev

Open your browser and navigate to:

• Vite Development Frontend: http://localhost:5173 (supporting Hot Module Replacement)
• UI Production Build: http://localhost:8000 (serving compiled assets from /static)
• OpenAPI Documentation: http://localhost:8000/docs

Credentials for Seeding Demo Logins:

• Analyst: analyst@riskai.com / analystpassword (View dashboards, trigger queries, upload files, compare prompts)
• Admin: admin@riskai.com / adminpassword (All Analyst permissions + ingest new regulatory clauses, manual vector reindexing)

---

Testing Suite

Run the full pytest suite covering authentication scopes, company profile registrations, ratio computations, vector indexers, and LLM evaluations:

python -m pytest backend/tests/ -v

---

Prompt Tuning & Engineering Benchmarks

During developmental evaluations, we tested 3 prompt variations using an LLM-as-a-Judge grading rubric (accuracy, completeness, and regulatory alignment) on a test suite of 50 financial risk scenarios:

Prompt Variant	Key Mechanism	Avg Judge Accuracy	Avg Judge Completeness	Regulatory Alignment	Output Characteristics
Zero-Shot	Raw query + context, direct instruction	67%	68%	66%	Short, lacks source integration, ratio values are unweighted.
Few-Shot	In-context example of structured risk profile	84%	83%	85%	Clean JSON response, references citations, but lacks logic steps.
Chain-of-Thought (CoT)	Multi-step reasoning instruction before final conclusion	95%	96%	97%	Explains liquidity, solvency margins, matches ratios to Basel rules.