{"id":34505090,"url":"https://github.com/meridianalgo/araai","last_synced_at":"2026-05-26T19:01:36.909Z","repository":{"id":306484802,"uuid":"1025796827","full_name":"MeridianAlgo/AraAI","owner":"MeridianAlgo","description":"A machine learning platform for market analysis and forecasting, specializing in stock volatility prediction, market trend forecasting, and portfolio optimization.","archived":false,"fork":false,"pushed_at":"2026-05-22T17:28:18.000Z","size":156210,"stargazers_count":13,"open_issues_count":1,"forks_count":3,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-22T21:31:38.267Z","etag":null,"topics":["artificial-intelligence","huggingface","huggingface-models","machine-learning","machine-learning-algorithms","meridianalgo","stock-analysis","stock-price-prediction"],"latest_commit_sha":null,"homepage":"https://huggingface.co/meridianal/ARA.AI","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/MeridianAlgo.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-07-24T20:17:58.000Z","updated_at":"2026-05-22T17:28:24.000Z","dependencies_parsed_at":"2025-11-27T19:03:23.171Z","dependency_job_id":null,"html_url":"https://github.com/MeridianAlgo/AraAI","commit_stats":null,"previous_names":["meridianalgo/in-python","meridianalgo/araai"],"tags_count":19,"template":false,"template_full_name":null,"purl":"pkg:github/MeridianAlgo/AraAI","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MeridianAlgo%2FAraAI","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MeridianAlgo%2FAraAI/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MeridianAlgo%2FAraAI/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MeridianAlgo%2FAraAI/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/MeridianAlgo","download_url":"https://codeload.github.com/MeridianAlgo/AraAI/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MeridianAlgo%2FAraAI/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33534563,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"ssl_error","status_checked_at":"2026-05-26T15:22:15.568Z","response_time":63,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["artificial-intelligence","huggingface","huggingface-models","machine-learning","machine-learning-algorithms","meridianalgo","stock-analysis","stock-price-prediction"],"created_at":"2025-12-24T02:54:36.933Z","updated_at":"2026-05-26T19:01:36.901Z","avatar_url":"https://github.com/MeridianAlgo.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Meridian.AI\n\n### Real Time Financial Prediction Engine\n\n![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)\n![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)\n![Version](https://img.shields.io/badge/version-5.2.2-green.svg)\n[![Forex Training](https://github.com/MeridianAlgo/AraAI/actions/workflows/forex.yml/badge.svg)](https://github.com/MeridianAlgo/AraAI/actions/workflows/forex.yml)\n[![Stock Training](https://github.com/MeridianAlgo/AraAI/actions/workflows/stocks.yml/badge.svg)](https://github.com/MeridianAlgo/AraAI/actions/workflows/stocks.yml)\n[![Lint](https://github.com/MeridianAlgo/AraAI/actions/workflows/lint.yml/badge.svg)](https://github.com/MeridianAlgo/AraAI/actions/workflows/lint.yml)\n\n## Overview\n\nMeridian.AI is a deep learning system that forecasts price movements for any stock or forex pair. It reads recent market history, turns that history into a set of technical features, and produces two things at once: a price forecast and a direction signal that estimates whether the next move is likely to be up or down.\n\nThe system retrains itself every hour through GitHub Actions and publishes each fresh checkpoint to Hugging Face, so the version you download is always the most recent one. You do not need a GPU to use it, and you do not need to run any training yourself.\n\nThe trained models live here: [meridianal/ARA.AI](https://huggingface.co/meridianal/ARA.AI).\n\n## Architecture\n\nThe model is called MeridianModel. It is a compact transformer style network adapted for financial time series, and it carries roughly 33 million parameters in the configuration that ships in the hourly pipeline. The design favors techniques that stay stable on a CPU and train quickly, because every hourly run happens on a standard GitHub Actions runner with no GPU attached.\n\nEach component has a specific job:\n\n| Component | What it is | Why it is there |\n|-----------|------------|-----------------|\n| Attention | Grouped Query Attention with query and key normalization | Lets every timestep look at the others while sharing key and value projections, which keeps memory use low |\n| Position encoding | Rotary Position Embeddings | Gives the model a sense of relative time without a fixed lookup table |\n| Expert routing | Mixture of Experts with SwiGLU experts and top 2 routing | Sends each input to the two experts best suited to it, so different market conditions get different treatment |\n| Activations | SwiGLU gated units | Smoother gradient flow than plain ReLU or GELU |\n| Normalization | RMSNorm with layer scale | Keeps training numerically stable |\n| Regularization | Stochastic depth and dropout | Reduces overfitting |\n| Optional state space block | Mamba SSM with a vectorized scan | Captures long range patterns when it is switched on |\n| Loss | BalancedDirectionLoss, a blend of Huber regression and binary cross entropy | Trains for price accuracy and direction accuracy together |\n\n### Default configuration\n\n| Setting | Value |\n|---------|-------|\n| Parameters | about 33 million |\n| Hidden dimension | 256 |\n| Layers | 6 |\n| Attention heads | 4, with 2 key and value heads |\n| Experts | 4, with top 2 routing |\n| Prediction heads | 4 |\n| Input features | 44 technical indicators |\n| Sequence length | 30 timesteps |\n| Mamba SSM | off by default on CPU |\n\n## How a Prediction Is Made\n\nThe model reads the last 30 timesteps of market data. For each timestep it computes 44 technical indicators from the raw open, high, low, close, and volume values. After normalization, every feature is clamped to a fixed range (`[-10, 10]` in the code) so that extreme values cannot push the gradients toward zero. The cleaned features then flow through the network and out the other side as a single combined prediction.\n\n```\nMarket data for any ticker or pair\n        |\n        v\n44 technical indicators\n(RSI, MACD, Bollinger Bands, ATR, OBV, VWAP, and more)\n        |\n        v\nGrouped Query Attention with rotary positions\n        |\n        v\nMixture of Experts layer (SwiGLU experts, top 2 routing)\n        |\n        v\nFour prediction heads, combined into one output\n        |\n        v\nPrice forecast and direction signal\n```\n\nThe four prediction heads each make their own forecast, and the model blends them with learned weights into a final number. The direction signal comes from the same forward pass, which is why the loss function trains both targets at the same time.\n\n## Quick Start\n\nClone the repository and install the dependencies.\n\n```bash\ngit clone https://github.com/MeridianAlgo/AraAI.git\ncd AraAI\n\npython -m venv venv\nsource venv/bin/activate  # on Windows use: venv\\Scripts\\activate\n\npip install torch --index-url https://download.pytorch.org/whl/cpu\npip install -r requirements.txt\n```\n\n### Predict a stock\n\n```python\nfrom meridianalgo.unified_ml import UnifiedStockML\nfrom huggingface_hub import hf_hub_download\n\nmodel_path = hf_hub_download(\n    repo_id=\"meridianal/ARA.AI\",\n    filename=\"models/Meridian.AI_Stocks.pt\",\n)\n\nml = UnifiedStockML(model_path=model_path)\nresult = ml.predict_ultimate(\"AAPL\", days=5)\nprint(result)\n```\n\n### Predict a forex pair\n\n```python\nfrom meridianalgo.forex_ml import ForexML\nfrom huggingface_hub import hf_hub_download\n\nmodel_path = hf_hub_download(\n    repo_id=\"meridianal/ARA.AI\",\n    filename=\"models/Meridian.AI_Forex.pt\",\n)\n\nml = ForexML(model_path=model_path)\nresult = ml.predict_forex(\"EURUSD=X\", days=5)\nprint(result)\n```\n\nThe first call downloads the checkpoint from Hugging Face and caches it locally, so later runs start instantly.\n\n## How Training Works\n\nTraining runs on its own, without anyone starting it. GitHub Actions launches the stock pipeline at the top of every hour and the forex pipeline at half past every hour. If a run is still going when the next one is due, the new run waits in line rather than canceling the one already in progress, so a checkpoint is never lost to a restart.\n\nEach run moves through four stages:\n\n1. Fetch. The pipeline pulls recent market data for up to 50 stocks or up to 30 forex pairs and stores it in a local SQLite database. It collects several timeframes per symbol so the model sees both short and long horizons.\n2. Train. The pipeline downloads the current checkpoint from Hugging Face and continues training it for 70 optimizer steps. There is no wall clock time limit. The step count is the only stop condition, which keeps every run predictable in length. Training uses gradient accumulation to simulate a batch size of 256, light data augmentation, and an exponential moving average of the weights for a smoother final model.\n3. Track. Every optimizer step reports its loss, learning rate, gradient norm, and elapsed time to Comet ML, so you can watch the training curves live. Per epoch metrics such as validation loss and direction accuracy are recorded as well.\n4. Deploy. Once training finishes, the updated checkpoint is written to disk and uploaded back to Hugging Face, ready for the next run and for anyone who wants to download it.\n\nThe whole pipeline runs as a single GitHub Actions job. The model file never leaves the machine that produced it, which removes a class of failures where a checkpoint could go missing while it was handed between separate jobs.\n\n### Training techniques\n\n| Technique | Detail |\n|-----------|--------|\n| Learning rate warmup | A short linear ramp before cosine annealing begins |\n| Cosine warm restarts | Periodic restarts of the learning rate to escape shallow minima |\n| EMA weight averaging | A decay of 0.999, which produces weights that tend to generalize better |\n| Gradient clipping | A maximum norm of 1.0 to keep gradients from exploding |\n| Gradient accumulation | Builds an effective batch size of 256 from smaller micro batches |\n| Data augmentation | Small Gaussian noise plus occasional masking of timesteps |\n| BalancedDirectionLoss | Roughly 60 percent Huber regression and 40 percent weighted direction loss |\n| Early stopping | Stops when the moving average validation loss stops improving |\n| Feature clamping | Bounds features to a fixed range after normalization |\n| Mixed precision | bfloat16 on CPU and float16 on CUDA |\n\n## Technical Indicators\n\nThe model reads 44 features computed from raw open, high, low, close, and volume data. There is no zero padding, so every feature carries real information.\n\n| Category | Indicators |\n|----------|------------|\n| Price | Returns, Log Returns, Volatility, ATR |\n| Trend | SMA (5, 10, 20, 50, 200), EMA (5, 10, 20, 50, 200) |\n| Momentum | RSI, Fast RSI, Stochastic RSI, Momentum, Rate of Change, Williams %R |\n| Oscillators | MACD, MACD Signal, MACD Histogram, Stochastic K and D, CCI |\n| Volatility | Bollinger Bands (Upper, Lower, Width, %B), Keltner Channels (Upper, Lower, %K) |\n| Volume | Volume SMA, Volume Ratio, OBV (normalized) |\n| Trend strength | ADX, Plus DI, Minus DI, Price versus SMA50 and SMA200, ATR percent |\n| Mean reversion | Z Score over 20 days, Distance from the 52 week high |\n\n## Checkpoint Format\n\nEvery checkpoint is a single `.pt` file that holds both the weights and enough configuration to rebuild the model exactly. The main keys are:\n\n| Key | Type | Description |\n|-----|------|-------------|\n| `model_state_dict` | `dict` | The PyTorch model weights |\n| `model_type` | `str` | Either `stock` or `forex` |\n| `architecture` | `str` | `MeridianModel-2026` |\n| `version` | `str` | The model version, currently `5.2.2` |\n| `input_size` | `int` | `44`, the feature count |\n| `seq_len` | `int` | `30`, the lookback window |\n| `dim` | `int` | Hidden dimension |\n| `num_layers` | `int` | Network depth |\n| `num_heads` | `int` | Attention heads |\n| `num_kv_heads` | `int` | Key and value heads for Grouped Query Attention |\n| `num_experts` | `int` | Number of experts in the Mixture of Experts layer |\n| `num_prediction_heads` | `int` | Number of output heads |\n| `dropout` | `float` | Dropout rate |\n| `use_mamba` | `bool` | Whether the Mamba block is active |\n| `mamba_state_dim` | `int` | Size of the Mamba hidden state |\n| `scaler_mean` | `Tensor` | Mean used to normalize features |\n| `scaler_std` | `Tensor` | Standard deviation used to normalize features |\n| `metadata` | `dict` | Best validation loss, direction accuracy, target bounds, and training history |\n\nThe loader accepts any checkpoint at version 4.1 or newer. Older checkpoints are skipped so that a stale format can never corrupt a fresh run.\n\n## Project Structure\n\n```\nmeridianalgo/\n  meridian_model.py        The MeridianModel architecture (GQA, MoE, optional Mamba SSM)\n  large_torch_model.py     Training loop, data handling, checkpoint save and load, inference\n  direction_loss.py        BalancedDirectionLoss and the direction accuracy metrics\n  unified_ml.py            Stock prediction interface and feature engineering\n  forex_ml.py              Forex prediction interface\n  utils.py                 GPU detection and accuracy tracking helpers\n  __init__.py              Package metadata and entry points\nscripts/\n  train_stocks.py          Stock training entry point\n  train_forex.py           Forex training entry point\n  fetch_and_store_data.py  Market data ingestion into SQLite\n  push_to_hf.py            Uploads checkpoints to Hugging Face\n  migrate_hf_legacy.py     Moves older checkpoints into a legacy folder on Hugging Face\n  clean_workflow_runs.py   Maintenance helper for old GitHub Actions runs\n.github/workflows/\n  stocks.yml               Hourly stock training at minute 00\n  forex.yml                Hourly forex training at minute 30\n  lint.yml                 Formatting and lint checks\ntests/\n  conftest.py                     Shared fixtures, including model checkpoints\n  test_checkpoint_health.py       Checks on checkpoint metadata\n  test_model_inference.py         Forward pass and state dictionary tests\n  test_directional_signal.py      Direction accuracy on real market data\n  test_predict_denormalization.py Verifies predictions are scaled back correctly\n```\n\n## Version History\n\nThe full record of changes lives in [docs/CHANGELOG.md](docs/CHANGELOG.md), kept separate from this document.\n\n## Disclaimer\n\nThis software is for research and educational purposes only. It is not financial advice.\n\nTrading financial instruments carries significant risk. Every prediction is a probabilistic forecast based on historical data, and past performance does not guarantee future results. Markets can behave in ways no model expects during sudden shocks, liquidity crises, or structural shifts.\n\nYou should never trade with money you cannot afford to lose. Any trading decision you make is yours alone. MeridianAlgo and its contributors are not liable for any financial loss that results from using this software.\n\nThe software is provided as is, without warranty of any kind. By using it you agree to hold MeridianAlgo and all contributors harmless from any claim that arises from your use of it. You are responsible for following all financial regulations that apply to you.\n\n## License\n\nReleased under the MIT License. See [LICENSE](LICENSE) for the full text.\n\nMade with care by [MeridianAlgo](https://github.com/MeridianAlgo)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmeridianalgo%2Faraai","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmeridianalgo%2Faraai","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmeridianalgo%2Faraai/lists"}