🪙 QUANT_ENGINE_V1: Bitcoin Predictive AnalyticsInstitutional Sentiment & Machine Learning FrameworkQUANT_ENGINE_V1 is a sophisticated quantitative framework designed to forecast Bitcoin (BTC-GBP) market returns by synthesizing high-frequency news sentiment with historical price action. By converting raw linguistic data into mathematical vectors, the system bypasses the "extrapolation trap" of standard ML models to provide actionable financial targets.

🏛 System ArchitectureThe engine operates on a synchronized three-tier architecture optimized for low-latency data processing and predictive accuracy:Data Ingestion Layer: Automates the extraction of global financial headlines via SerpAPI and real-time market OHLCV data via Yahoo Finance.Intelligence Layer:NLP Engine: Utilizes a dual-model approach (VADER + TextBlob) to calculate composite sentiment scores.ML Engine: Features a Multi-Output Random Forest Regressor.

The model is trained on stationary data (logarithmic returns and volatility ratios) rather than absolute price, ensuring statistical reliability across different market regimes. Verification Layer: A "Machine-to-Machine" (M2M) protocol that transmits internal model states to the Gemini-2.5-Flash Oracle for qualitative verification and macro-economic cross-referencing.

🛠 Installation & Configuration1. Environment SetupRecommended: Python 3.10+ in a dedicated virtual environment.Bash# Clone and enter directory git clone https://github.com/Eljyoussef/Bitcoin-Predictive-Sentiment-Analytics.git cd Bitcoin-Predictive-Sentiment-Analytics

Initialize environment

python -m venv btc_env source btc_env/bin/activate # Windows: btc_env\Scripts\activate

Install dependencies

pip install -r requirements.txt

API Configuration

Create or edit config/settings.py with your credentials: SERPAPI_KEY: News extraction. GEMINI_API_KEY: Oracle research briefings.

⚡ Operational WorkflowThe system utilizes an orchestrator pattern to manage concurrent threads for the web server and the background AI agent.

Phase 1: BootstrapInitialize the project structure and SQLite schema:Bashpython run.py Wait for [SUCCESS] Database schema verified, then interrupt with Ctrl+C. Phase 2: Historical ImputationPopulate the engine with historical data to calibrate the ML model:Bashpython migrate_db.py Phase 3: Live DeploymentLaunch the production stack:Bashpython run.py

Dashboard URL: http://127.0.0.1:8000/dashboard

📊 Core Quant FeaturesFeatureTechnical ImplementationReturns PredictionForecasts next-day $Target_Return$ and $Volatility_Ratios$.Divergence OverlayDual-axis Plotly charts mapping Price vs. Sentiment Momentum.Oracle BriefingGenerates an institutional-grade PDF via LLM verification.

Stationarity FixReconstructs absolute price targets from predicted percentage variance.

📁 Project Skeleton

├── config/ # Centralized settings & API keys ├── data/ # SQLite binaries (news.db) ├── src/
│ ├── api.py # FastAPI endpoints & UI logic │ ├── fetch_data.py # Asynchronous ETL pipeline │ ├── ml_predict.py # Random Forest Quant Model │ ├── models.py # SQLAlchemy ORM schemas │ └── scheduler.py # Background thread management ├── templates/ # High-fidelity "Terminal" UI ├── run.py # System Orchestrator └── migrate_db.py # Data migration & backfill tool

🛡 DisclaimerThis software is provided for quantitative research purposes only. Trading digital assets involves significant financial risk. The predictions generated by QUANT_ENGINE_V1 are mathematical estimates based on historical sentiment correlations and should not be construed as financial advice.