Overview
FAIN (Financial AI iNtelligence) is an institutional-grade trading terminal engineered for the Bourse des Valeurs Mobilières de Tunis (BVMT), built during the IHEC CodeLab 2.0 hackathon in February 2026. The platform co-orchestrates 12 microservices to deliver real-time tracking of all 82 listed BVMT equities, on-the-fly XGBoost price forecasting powered by 30+ technical indicators (RSI, MACD, Bollinger Bands, candlestick patterns), PPO Reinforcement Learning portfolio optimization grounded in live macro data from the World Bank, IMF, and Tunisian Central Bank with SHAP explainability, multi-source NLP sentiment analysis, and a Llama 3.3 70B RAG chatbot running on OpenRouter with ChromaDB over official BVMT/CMF regulatory documentation.
The Problem
Tunisia's BVMT market is severely underserved by modern analytical tooling. Retail and institutional investors alike rely on fragmented, manual processes with no quantitative framework. No existing system combines real-time data ingestion for all 82 listed equities, ML-driven price forecasting, AI-based portfolio recommendation with trust-building explainability, and local sentiment monitoring that correlates Tunisian news and social media with market movements.
Solution
Co-architected a distributed platform with a central FastAPI API Gateway (port 8000) routing to 6 specialized microservices: XGBoost Forecasting (port 8008), Isolation Forest Anomaly Detection (port 8004), Gemini/Perplexity Sentiment (port 8005), PPO Portfolio Management (port 8007), NestJS Core (auth + market + stock data, port 8006), and SMTP Notification (port 8003) — plus Stock, Market, and Jobs services sharing the PostgreSQL layer.
Built an on-the-fly XGBoost forecasting engine that trains one model per forecast request using 30+ engineered features (RSI-14, MACD, EMA-12/26, Bollinger Bands, volume ratio, candlestick body/shadow sizes, day-of-week) plus a parallel RandomForest classifier for liquidity probability — returning 5-day price forecasts with horizon-scaled confidence intervals.
Implemented a Reinforcement Learning portfolio optimizer using Stable-Baselines3 (PPO) in a custom Gymnasium environment with reward = Sharpe ratio − drawdown penalty. The agent ingests live macro data from World Bank API (7 indicators), IMF DataMapper (5 indicators), and Tunisian Central Bank (BCT) XLS scraping, then SHAP KernelExplainer surfaces which features drove each allocation. An LLM (OpenRouter) generates plain-French explanations of every recommendation.
Engineered a two-layer NLP sentiment pipeline: BeautifulSoup scrapes Webdo.tn, Kapitalis.com, and African Manager for financial articles which Google Gemini Flash Lite classifies per ticker; a parallel Perplexity Sonar integration performs real-time social media searches for dynamic, live sentiment updates.
Integrated a RAG chatbot running Llama 3.3 70B Instruct via OpenRouter with ChromaDB (all-MiniLM-L6-v2 embeddings) over a curated BVMT/CMF regulatory knowledge base — maintaining a 10-turn sliding conversation window for contextual multi-turn queries.
Architecture
A Next.js frontend (Recharts visualizations) talks exclusively to a FastAPI API Gateway (port 8000). The gateway handles direct SQLAlchemy/PostgreSQL reads for stocks and price history, then HTTP-proxies to 6 downstream services: NestJS Core on :8006 (JWT auth + market data + stock management via its own PostgreSQL), XGBoost Forecasting on :8008, Isolation Forest Anomaly Detection on :8004, Gemini+Perplexity Sentiment on :8005, PPO Portfolio Management on :8007 (Streamlit demo UI also available on :8501), and SMTP Notification on :8003. A Jobs Service orchestrates 4 scheduled tasks: market pulse every 15 min, anomaly scan hourly, daily PDF market report at 18h, and weekly portfolio rebalancing Monday 9h. PostgreSQL (Neon) is the shared persistence layer; Docker Compose orchestrates the entire stack.
Tech Stack
FastAPI (API Gateway)
Central gateway on :8000 — direct DB reads for stocks/history + HTTP proxy to 6 downstream services
NestJS (Core Backend)
JWT auth, market data, and stock management on :8006 with its own PostgreSQL schema
XGBoost + RandomForest
On-the-fly 5-day price forecasting (30+ features: RSI, MACD, Bollinger, candlestick) + liquidity classifier
Stable-Baselines3 PPO
RL portfolio optimization in Gymnasium env; reward = Sharpe − drawdown penalty
SHAP + OpenRouter LLM
KernelExplainer surfaces macro/price feature importance; LLM writes plain-French investment rationale
Gemini Flash Lite
Classifies article sentiment per ticker from BeautifulSoup-scraped Tunisian financial news
Perplexity Sonar
Real-time social media search for live ticker sentiment from online discussions
Llama 3.3 70B + ChromaDB
RAG chatbot via OpenRouter; ChromaDB stores BVMT/CMF docs with all-MiniLM-L6-v2 embeddings
PostgreSQL + Docker Compose
Shared Neon PostgreSQL persistence layer; single docker compose up launches all 12 services
Results
IHEC CodeLab 2.0 Hackathon — February 2026
FastAPI Gateway + 6 proxied services + stock/market/jobs services on shared DB
All BVMT-listed equities tracked with 15-min market pulse refresh
RSI, MACD, EMA, Bollinger Bands, volume ratios powering XGBoost on-the-fly training
Sharpe-optimized portfolio across 8 BVMT bank stocks using real World Bank/IMF/BCT macro data
Gemini Flash Lite (sentiment), Perplexity Sonar (social), Llama 3.3 70B (RAG chatbot)
Achievement Gallery
Moments that made it all worth it
Achievement 01
🏆 Official award ceremony — IHEC CodeLab 2.0, February 2026
Achievement 02
Team Makarouna Kadheba celebrating 3rd Place with the 1000 DT prize
Key Takeaways
Choosing XGBoost over LSTM for forecasting was the right hackathon call — on-the-fly training per request with early stopping converges in seconds, while LSTM fine-tuning per stock would take hours. Directional accuracy on thin BVMT data was comparable.
Using PPO Reinforcement Learning for portfolio allocation instead of classical Markowitz lets the agent learn non-linear risk/return tradeoffs and directly incorporate macro signals (BCT policy rate, IMF debt/GDP) into the reward function — something mean-variance optimization cannot do.
The two-layer sentiment approach (Gemini Flash Lite for scraped archives + Perplexity Sonar for real-time social) proved essential: static scrapers lag by hours on breaking news, while Sonar returns live discussion threads within seconds.
SHAP on top of the PPO agent's feature set was the single biggest trust-builder in the demo — once judges could see that 'BCT policy rate' and 'BIAT volatility' were the top drivers of a recommendation, skepticism about the RL black box evaporated instantly.
The API Gateway pattern was the most important architectural decision for team velocity — each engineer owned one service on its own port, and the gateway unified everything behind a single URL without ever touching the frontend routing code.