How youcef3939/oracle works
1. What this repository is
ORACLE is a Python 3.10+ market-regime detection system. Architecturally it is split into two top-level surfaces: a reusable detection pipeline in src/ and a Streamlit dashboard in dashboard/app.py. The system is designed for financial time-series rather than generic web requests.
2. Primary entrypoints
The main programmatic boundary is the MarketRegimeDetector-style workflow described in the README and implemented across src/regime_detector.py plus the supporting modules. The user-facing interactive entrypoint is the Streamlit app, which reads results from the core pipeline and renders charts and summaries.
3. Data acquisition layer
src/data_fetcher.py is the ingestion boundary. Its job is to pull raw market data for multiple assets and produce the input dataset used by the rest of the pipeline. The README indicates external sources such as yfinance, so the architecture likely depends on remote market-data APIs rather than an internal datastore.
4. Preprocessing layer
src/preprocessing.py is where raw time series are cleaned and made model-ready. This is the normalization/alignment/resampling boundary: it turns heterogeneous asset series into a consistent panel that downstream feature extraction and modeling can consume.
5. Feature engineering layer
src/features.py converts preprocessed market data into domain signals such as returns, volatility, momentum, and correlations. This is the main transformation layer between normalized time series and learned representations, and it is where cross-asset relationships become explicit inputs.
6. Model core
src/model_core.py contains the learning backbone. Based on the README, the core supports deep sequence models such as Transformers and VAE-style encoders that compress market behavior into latent embeddings. This is the boundary where the repository moves from engineered indicators to learned market-state representations.
7. Regime detection orchestration
src/regime_detector.py is the central coordinator. It ties together fetching, preprocessing, feature generation, model inference/training, and regime assignment. This is the logical “application service” of the repo: the part that exposes fit/predict-style behavior and turns latent outputs into discrete regimes.
8. Prediction/forecasting layer
src/predictive.py is a separate forward-looking module for regime probabilities or short-horizon forecasts. It sits downstream of the detector and is used when the system needs not just current regime labels, but expected transitions or confidence estimates.
9. Visualization layer
src/visualization.py prepares plots and analytical views for the dashboard. It is the reporting boundary that translates regime timelines, embeddings, correlations, and probabilities into visual artifacts rather than raw data structures.
10. Dashboard boundary
dashboard/app.py is the interactive presentation layer built with Streamlit. It does not appear to own model logic; instead, it orchestrates the core modules and visualization helpers to present regime analysis, predictions, and scenario-style views to the user.
11. End-to-end data flow
The architectural flow is: external market data in → fetcher → preprocessing → feature engineering → model core embedding → regime detection/classification → predictive scoring and visualization. The output is a regime label stream plus probabilities/metrics that the dashboard renders.
12. Important architectural boundaries
The repo cleanly separates: data acquisition, data conditioning, feature construction, model inference, regime interpretation, and presentation. That separation is important for diagramming because each stage can change independently without rewriting the dashboard or the ingestion layer.
13. Persistence and deployment posture
There is no obvious database, message bus, or server-side API in the tree. That suggests a mostly local, in-memory analytical application with optional saved model artifacts rather than a distributed system. The main runtime surfaces are a Python library and a Streamlit app.
Main entry points: regime_detector.py Detector · visualization.py Visuals · data_fetcher.py Fetcher · preprocessing.py Preprocess
Components 9
Core pipeline
Reusable market-regime detection and forecasting workflow.
- Fetcher · Retrieves raw asset data and assembles the input dataset.
src/data_fetcher.py - Preprocess · Cleans, aligns, and normalizes heterogeneous time-series panels.
src/preprocessing.py - Features · Builds returns, volatility, momentum, and correlation signals.
src/features.py - Model core · Learns latent market-state representations with deep encoders.
src/model_core.py - Detector · Coordinates the end-to-end fit and regime assignment workflow.
src/regime_detector.py - Predictive · Produces regime probabilities and short-horizon transition signals.
src/predictive.py - Visuals · Prepares charts and analytical views for regime interpretation.
src/visualization.py
Dashboard
Streamlit presentation layer for interactive analysis.
- Dashboard app · Interactive UI that renders regimes, forecasts, and summaries.
dashboard/app.py
Other components
- Market data · Remote financial time-series inputs used by the pipeline.
Connections 10
- Market data → Fetcher: source · External market feeds are pulled into the pipeline.
- Fetcher → Preprocess: raw data · Fetched assets are cleaned and aligned for modeling.
- Preprocess → Features: prepared series · Normalized panels feed feature construction.
- Features → Model core: signals · Engineered indicators are encoded into latent state.
- Model core → Detector: embeddings · Latent representations drive regime labeling.
- Detector → Predictive: regimes · Detected states are used for probabilities and forecasts.
- Detector → Visuals: outputs · Regime timelines and metrics are prepared for display.
- Predictive → Visuals: forecasts · Prediction outputs are turned into charts and summaries.
- Visuals → Dashboard app: views · Prepared plots are rendered in the Streamlit app.
- Detector → Dashboard app: analysis · The dashboard orchestrates the core detector workflow.