Skip to content

Commit a21d0f6

Browse files
JMR825JMR825
committed
- images
1 parent dc6ef2d commit a21d0f6

17 files changed

Lines changed: 180 additions & 70 deletions

‎README.md‎

Lines changed: 67 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,21 +1,38 @@
11
# FinOptima
22

3+
<div align="center"> ![OSCG 2026](/docs/oscg%202026.jpeg) </div>
4+
35
## AI-Powered Portfolio Optimization System
46

57
FinOptima is an AI-driven financial analytics platform built for **OSC AI Build 1.0**, a global hackathon organized by Open Source Connect (OSC). The project combines live market data, machine learning, clustering, and portfolio optimization to help users analyze stocks and generate smart investment insights in an interactive dashboard.
68

79
---
8-
10+
<div align="center"> ![design](/docs/Finoptima.png) </div>
911
## Dashboard Showcase
1012

1113
### Main Analytics Interface
12-
![FinOptima Main Dashboard UI](docs/Interactive-Interface.png)
14+
<div align="center"> ![FinOptima Main Dashboard UI](docs/Interactive-Interface.png) </div>
1315

1416
### Live Price Board
15-
![Live Prices of Stocks](docs/Live%20Price%20Board.png)
17+
<div align="center"> ![Live Prices of Stocks](docs/Live%20Price%20Board.png) </div>
18+
19+
### Portfolio Summary
20+
<div align="center"> ![Portfolio Summary](/docs/Portfolio%20Summary.png)</div>
1621

1722
### Asset Allocation Charting Panel
18-
![FinOptima Portfolio Weights and Recharts Panel](docs/allocation.png)
23+
<div align="center"> ![FinOptima Asset Allocation](docs/allocation.png) </div>
24+
25+
### Expected Return vs Volatility
26+
<div align="center"> ![FinOptima Returns](/docs/Returns.png) </div>
27+
28+
### Price Trends (Daily)
29+
<div align="center"> ![FinOptima Trends](/docs/Price%20Trends%20(Daily).png) </div>
30+
31+
### Price Trends (Intraday)
32+
<div align="center"> ![FinOptima Trends Intraday](/docs/Price%20Trends%20\(Intraday.png)) </div>
33+
34+
### Stock Clusters && Correlation Matrix & Stock Analysis Table
35+
<div align="center"> ![FinOptima Trends Intraday](/docs/clusters%20corr%20Matrix%20and%20analysis%20table.png) </div>
1936

2037

2138
---
@@ -24,6 +41,8 @@ FinOptima is an AI-driven financial analytics platform built for **OSC AI Build
2441

2542
FinOptima is designed to showcase how open-source AI can be applied to financial decision-making. Users enter stock symbols and investment preferences, and the system fetches market data, engineers financial features, predicts short-term returns using machine learning, groups similar assets through clustering, and computes optimized portfolio allocations. The results are displayed in a clean, responsive dashboard with live prices, prediction signals, risk metrics, and allocation charts.
2643

44+
> **📘 Comprehensive technical documentation including ML model details, training methodology, feature engineering, evaluation metrics, benchmarks, and sample outputs is available at [`docs/TECHNICAL_DETAILS.md`](docs/TECHNICAL_DETAILS.md).**
45+
2746
## Why This Project
2847

2948
This hackathon project focuses on building a practical AI system that is:
@@ -53,10 +72,20 @@ This hackathon project focuses on building a practical AI system that is:
5372

5473
---
5574

56-
## Performance Note: Local vs. Cloud Deployment
75+
## Performance: Local vs. Cloud Deployment
76+
77+
| Metric | Local (8-core, 16 GB) | Render Free Tier (512 MB) |
78+
|--------|----------------------|--------------------------|
79+
| Full pipeline (5 symbols, no LSTM) | ~3–5 s | ~20–30 s |
80+
| Full pipeline (10 symbols, no LSTM) | ~5–8 s | ~40–60 s |
81+
| LSTM training (8 epochs, 5 symbols) | ~8–12 s | Disabled (OOM risk) |
82+
| Memory usage (5 symbols) | ~200 MB | ~350 MB |
83+
| Data freshness | Real-time | Up to 2 min delay (yfinance cache + rate limits) |
5784

58-
* **Local Workspace (Recommended for Evaluators)**: Executes instantly (~5 to 10 seconds). It leverages your local computer's unthrottled CPU cores and high-speed memory to train model weight matrices in eager memory space rapidly.
59-
* **Live Web Instance (https://finoptima-gts9.onrender.com)**: Processes requests within ~20- 30 seconds. Powered by an optimized, non-persistent, 100% in-memory RAM vector data pool to comply with cloud free-tier memory resource limits.
85+
**Key differences:**
86+
- **Local execution** uses unthrottled CPU and full RAM for fast model training.
87+
- **Render free tier** runs on shared CPU with 512 MB RAM ceiling. All operations are optimized for in-memory execution — no disk I/O, no SQLite, no CSV writes.
88+
- LSTM is disabled on Render (`ENABLE_LSTM=false`) because TensorFlow allocates 300–400 MB at load time, exceeding the free tier limit during concurrent requests.
6089

6190
---
6291

@@ -147,6 +176,37 @@ ai-portfolio-optimizer/
147176
| POST | `/api/full-analysis` | Complete pipeline (dashboard) |
148177

149178

179+
## Demo Video
180+
181+
[![FinOptima Demo](docs/Interactive-Interface.png)](https://youtu.be/your-demo-video-link)
182+
183+
To be Added
184+
185+
## Sample Output
186+
187+
A complete sample request and response is documented in [`docs/TECHNICAL_DETAILS.md`](docs/TECHNICAL_DETAILS.md#sample-expected-outputs).
188+
189+
Quick example (5-stock daily analysis with `optimization_goal="max_sharpe"`, `risk_preference="medium"`):
190+
191+
| Asset | Weight | Predicted Return | Trend | Confidence |
192+
|-------|--------|-----------------|-------|------------|
193+
| AAPL | 25% | +0.85% | Upward | 72.3 |
194+
| MSFT | 20% | +0.62% | Upward | 68.1 |
195+
| GOOGL | 15% | +0.38% | Upward | 55.4 |
196+
| NVDA | 30% | +1.10% | Upward | 81.5 |
197+
| TSLA | 10% | -0.22% | Downward | 45.2 |
198+
199+
| Metric | Value |
200+
|--------|-------|
201+
| Expected annual return | 12.45% |
202+
| Expected annual volatility | 18.20% |
203+
| Sharpe ratio | 0.574 |
204+
| Max drawdown | -28.30% |
205+
| VaR (95%) | -2.45% |
206+
| CVaR (95%) | -3.08% |
207+
208+
> Full JSON response structure is shown in the technical documentation.
209+
150210
## Output format
151211

152212
FinOptima produces:

‎docs/FinOptima.png‎

201 KB
Loading

‎docs/Interactive-Interface.png‎

-88 Bytes
Loading

‎docs/Live Price Board.png‎

-37.9 KB
Loading

‎docs/Portfolio Summary.png‎

53.8 KB
Loading

‎docs/Price Trends (Daily).png‎

60 KB
Loading

‎docs/Price Trends (Intraday).png‎

41 KB
Loading

‎docs/Returns.png‎

30 KB
Loading

‎docs/System Architecture.png‎

182 KB
Loading

‎docs/TECHNICAL_DETAILS.md‎

Lines changed: 20 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,8 @@
22

33
## System Architecture
44

5+
![System Architecture](/docs/System%20Architecture.png)
6+
57
```
68
┌──────────┐ ┌──────────────────────────────────────┐ ┌──────────────┐
79
│ React │ ◄──► │ FastAPI Backend │ ◄──► │ yfinance │
@@ -19,6 +21,18 @@
1921

2022
All data processing is 100% in-memory. No disk I/O occurs during request handling (CSV generation is a separate dev-only utility).
2123

24+
### Sample Data
25+
26+
Pre-fetched daily and intraday CSV files for 28 major US equities and ETFs are available in the [`live_data/`](../live_data) directory at the project root:
27+
28+
The datasets were fetched on 12 June.
29+
| Folder | Contents |
30+
|---|---|
31+
| `live_data/daily/` | 28 CSV files, each with 1 year of daily OHLCV data (AAPL, MSFT, GOOGL, AMZN, TSLA, META, NVDA, JPM, NFLX, AMD, AVGO, COST, KO, PEP, WMT, PG, V, BAC, JNJ, UNH, XOM, CAT, GE, LIN, SPY, QQQ, IWM, GLD) |
32+
| `live_data/intraday/` | Intraday 5m bars for AAPL, MSFT, GOOGL, NVDA (under `5m/` subfolder) |
33+
34+
These can be used with the `sample` data provider for testing without yfinance calls. The generator script is at `backend/app/utils/sample_data_generator.py`.
35+
2236
---
2337

2438
## Data Pipeline
@@ -37,8 +51,8 @@ All data processing is 100% in-memory. No disk I/O occurs during request handlin
3751

3852
| Mode | Period | Interval | Min rows |
3953
|---|---|---|---|
40-
| `"daily"` | `"1y"` | `"1d"` | 5 |
41-
| `"intraday"` | `"5d"` | `"5m"` | 20 |
54+
| `"daily"` | `"6mo"` | `"1d"` | 5 |
55+
| `"intraday"` | `"2d"` | `"5m"` | 20 |
4256

4357
### 2. Feature Engineering (`preprocessing.py`)
4458

@@ -80,7 +94,7 @@ Applied per-symbol chronologically:
8094

8195
- **Target:** Next-period return (`daily_return.shift(-1)`)
8296
- **Train/test split:** 80/20 chronological (`shuffle=False`)
83-
- **Minimum training rows:** 30
97+
- **Minimum training rows:** 20
8498
- **Scaling:** `StandardScaler` applied only to LinearRegression (Random Forest uses raw values)
8599
- **Selection:** Model with lower MAE on the 20% test set is used for predictions
86100

@@ -221,8 +235,8 @@ Computes implied equilibrium returns via reverse optimization, then blends with
221235

222236
| Goal | Objective |
223237
|---|---|
224-
| `"sharpe"` | Maximize `(return - RFR) / (vol × risk_multiplier)` |
225-
| `"volatility"` | Minimize `sqrt(wᵀΣw)` |
238+
| `"max_sharpe"` | Maximize `(return - RFR) / (vol × risk_multiplier)` |
239+
| `"min_volatility"` | Minimize `sqrt(wᵀΣw)` |
226240

227241
### Risk Preference Multipliers
228242

@@ -300,7 +314,7 @@ POST /api/full-analysis
300314
"mode": "daily",
301315
"budget": 10000,
302316
"risk_preference": "medium",
303-
"optimization_goal": "sharpe"
317+
"optimization_goal": "max_sharpe"
304318
}
305319
```
306320

0 commit comments

Comments
 (0)
⚡