A professional-grade Python pipeline for systematic equity analysis. Scans a multi-sector universe, normalizes global currencies to EUR, and scores individual assets and broad market ETFs using Hidden Markov Models (HMM) and sector-aware fundamentals.
Trade Republic Ready. The engine automatically detects the native currency of an asset (USD, CHF, GBP) and converts it to EUR using live FX rates from Yahoo Finance and the European Central Bank (ECB) via the Frankfurter API.
- Universal ETF & Index Architecture — The engine now automatically detects ETFs (e.g.,
IWDA.AS,URA,PHO). It smartly bypasses corporate fundamental filters (like Debt/ROE) and scores ETFs purely on HMM momentum trends and systemic constants. - Macro-News Routing — If an ETF ticker returns no direct news, the engine dynamically searches for the broader sector (e.g., "Uranium / Nuclear news" instead of "URA news") to feed FinBERT accurate global macro-sentiment.
- DuckDB Analytical Core — Replaces standard SQLite with high-performance DuckDB (
quant_cache.duckdb). Handles 300,000+ rows of market history with zero-latency analytical queries. - Asynchronous Text Pipeline — Utilizes
asyncioandaiohttpto fetch SEC 8-K filings and Global News RSS feeds concurrently, reducing network I/O time by ~70%. - Dynamic Currency Normalization (
currency.py) — Automatically translates global prices into EUR. Ensures PnL and scoring are mathematically consistent for Euro-based portfolios.
- Global Sentiment Fallback — US equities are scored via SEC 8-K filings; international assets and ETFs fallback to News RSS feeds.
- Local FinBERT NLP — Air-gapped sentiment analysis using ProsusAI/FinBERT. Processes text in 512-token chunks to avoid "long-text" memory spikes.
- Stochastic Market State (HMM) — Gaussian Hidden Markov Model + GARCH volatility to identify Bull/Bear regimes.
- Live Console Dashboard — Direct-to-terminal reporting with suppressed library noise, featuring a "Top 3 High-Conviction Buys" summary for rapid decision making.
- Portfolio Audit — Cross-references
portfolio.csvagainst live data to issue BUY MORE (DCA OK), HOLD, or SELL directives with accurate EUR-native PnL tracking.
quant/
├── main.py # Orchestration engine (Async Fetch → Multiprocessing → Audit)
├── data_updater.py # Populates DuckDB with global price history
├── currency.py # Real-time FX normalization (Yahoo + ECB API)
├── async_fetcher.py # Concurrent network I/O for SEC and News
├── scoring.py # HMM, GARCH, and Stewardship logic (with ETF logic)
├── sentiment.py # Local FinBERT inference engine
├── database.py # DuckDB connection and schema management
├── indicators.py # Vectorized technical indicators
├── portfolio.py # Audit decision logic for user holdings
├── universe.py # Global asset definitions & universal ETF detection
├── quant_cache.duckdb # Unified high-speed storage for history and NLP scores
└── outputs/ # Market scans and audit reports (.csv)
git clone [https://github.com/akmal523/quant.git](https://github.com/akmal523/quant.git)
cd quant
pip install -r requirements.txtThe v8.5 engine uses DuckDB for local caching. Run this to fetch the global universe:
python3 data_updater.pyEdit portfolio.csv with your Trade Republic holdings. Use the Euro price you paid and exact European tickers (e.g., IWDA.AS instead of URTH):
Symbol,Buy_Price,Amount_EUR
IWDA.AS,120.50,115.00
HEI.DE,185.20,200.00
LMT,509.88,75.00
ROG.SW,280.10,100.00python3 main.py| Category | Components | Logic |
|---|---|---|
| Structural Grade | PE, PEG, ROE | Fixed for Euro-scaling. Rewards capital efficiency. (Systemic constant of 85.0 for broad ETFs). |
| Tactical Grade | HMM, FinBERT, VaR | Probabilistic entry timing based on regime and sentiment. |
| Stewardship | D/E, P/B, ICR | Sector-aware balance sheet stress test (Quality Floor). (Bypassed for index funds). |
| Horizon | Target Profile | Engine Requirements |
|---|---|---|
| RETIREMENT (20yr+) | "Set and Forget" assets. Exceptional compounders with wide moats or global market indices. | Structural Grade > 85 + Stewardship > 20 (or ETF status). |
| BUSINESS COLLATERAL (10yr) | Stable blue-chips with lower volatility. Assets you could borrow against. | Structural Grade 70–85. Reliable interest coverage and price stability. |
| LIQUIDITY CORE (12-Mo) | Mid-term growth or value plays optimized for capital extraction. | High Tactical Grade (Timing) + Decent Structural Grade. |
| SPECULATIVE (Short-Term) | Momentum plays or turnarounds. High risk, high reward. | Structural Grade < 50 OR fails the Stewardship Floor (High Debt/Low P/B). |
A unique feature of this engine is the Stewardship Override. Even if a stock has incredible price momentum (High Tactical Grade), the engine will force-downgrade the horizon to SPECULATIVE if:
- The Debt-to-Equity ratio exceeds sector-safe limits.
- The Interest Coverage Ratio (ICR) suggests the company is struggling to pay its bills.
- The Price-to-Book ratio (for Financials) indicates the market sees a "black hole" on the balance sheet.
The engine differentiates between market signals and your actual bank account:
- BUY MORE (DCA OK): The asset is high quality, and your current position is either at a loss or only slightly profitable. It's time to build the position.
- HOLD: The asset is a "BUY" in the open market, but you are already up 15%+. The engine prevents you from "averaging up" too aggressively, protecting your realized gains.
- BUY MORE (DCA OK): Asset is high quality (Active Score > 80) and currently trading at or below your entry, or within a high-conviction window.
- HOLD: Fundamentals remain strong, but current profit levels or tactical timing suggest waiting.
- URGENT SELL: Significant fundamental decay or extreme negative sentiment detected.
All output is for informational purposes. Probabilistic models and NLP sentiment analysis involve inherent risk. Past performance does not guarantee future results.