{"id":27464821,"url":"https://github.com/pratycodes/fintrix","last_synced_at":"2026-04-12T09:02:58.675Z","repository":{"id":287830415,"uuid":"965926892","full_name":"pratycodes/Fintrix","owner":"pratycodes","description":"Fintrix is a quant-driven portfolio optimization framework that combines market-aware synthetic data generation using Diffusion Models (DDPMs) with reinforcement learning via PPO, seamlessly integrated into a comprehensive benchmark evaluation pipeline.","archived":false,"fork":false,"pushed_at":"2025-08-22T09:26:29.000Z","size":75539,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-08-22T11:39:40.059Z","etag":null,"topics":["diffusion-models","portfolio-optimisation","quantitative-research","reinforcement-learning"],"latest_commit_sha":null,"homepage":"","language":"Jupyter Notebook","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pratycodes.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}},"created_at":"2025-04-14T06:12:56.000Z","updated_at":"2025-08-22T09:26:32.000Z","dependencies_parsed_at":"2025-08-11T19:28:38.374Z","dependency_job_id":null,"html_url":"https://github.com/pratycodes/Fintrix","commit_stats":null,"previous_names":["pratycodes/distributed-portfolio-optimization","pratycodes/fintrix"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/pratycodes/Fintrix","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pratycodes%2FFintrix","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pratycodes%2FFintrix/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pratycodes%2FFintrix/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pratycodes%2FFintrix/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pratycodes","download_url":"https://codeload.github.com/pratycodes/Fintrix/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pratycodes%2FFintrix/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278486267,"owners_count":25994941,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-05T02:00:06.059Z","response_time":54,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["diffusion-models","portfolio-optimisation","quantitative-research","reinforcement-learning"],"created_at":"2025-04-15T23:16:03.827Z","updated_at":"2025-10-05T16:45:29.222Z","avatar_url":"https://github.com/pratycodes.png","language":"Jupyter Notebook","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Fintrix: Reinforcement Learning Portfolio Optimization System\n\n**Fintrix** is a modular, research-grade framework for training and evaluating reinforcement learning-based portfolio allocation strategies. It is powered by Proximal Policy Optimization (PPO) and integrates synthetic financial data generation using Denoising Diffusion Probabilistic Models (DDPM). Designed to be interpretable, extensible, and robust, Fintrix is an ideal tool for researchers, quants, and AI engineers looking to build smarter financial agents.\n\n---\n\n## 🚀 Core Objectives\n\n* Generate realistic financial data via regime-aware DDPM models\n* Learn dynamic portfolio strategies that adapt to changing market regimes\n* Optimize allocations using advanced reinforcement learning methods (PPO)\n* Incorporate real-world constraints: transaction costs, position limits, diversification\n* Provide an explainable pipeline with regime attribution, allocation diagnostics, and benchmarking\n\n---\n\n## 🔍 Key Features\n\n### Reinforcement Learning (PPO)\n\n* Actor-critic architecture with clipped objective\n* Supports stochastic policies and continuous action spaces (portfolio weights)\n\n### Synthetic Data via DDPM\n\n* Trains on regime-conditioned time series sequences\n* Simulates different risk scenarios with volatility control\n* Generates training environments that reflect real-world non-stationarity\n\n### Market Regime Detection\n\n* Real-time regime classification (bull, bear, volatile, sideways)\n* Driven by rolling returns, volatility, and trend strength metrics\n* Used to modulate both reward shaping and asset exposure\n\n### Position Sizing \u0026 Timing\n\n* Implements Kelly Criterion (multi-timeframe version)\n* Dynamically adjusts exposure using market timing layer\n* Enforces risk-aware soft and hard constraints (min/max allocation)\n\n### Feature Engineering\n\n* Momentum, volatility, SMA, RSI, trend score (per asset \u0026 market)\n* Correlation matrix descriptors\n* Regime indicators embedded in observations\n\n### Rebalancing Engine\n\n* Rebalances only when drift exceeds threshold or max holding time reached\n* Transaction cost-aware allocation logic\n* Penalizes overtrading and unnecessary weight shifts\n\n### Benchmark-Aware Reward Function\n\n* Encourages outperformance relative to index\n* Penalizes volatility, drawdowns, and costs\n* Promotes steady compounding rather than explosive bets\n\n---\n\n## 🧱 Repository Structure\n\n```\nFintrix/\n├── assets/            # Charts, diagrams, performance outputs\n├── config/            # Training configs and constants\n├── data/              # Data loader, feature calculator, DDPM pipeline\n├── ddpm/              # DDPM model, trainer, denoiser\n├── env/               # Portfolio environment (Gymnasium-style)\n├── market/            # Kelly sizing, market regimes, timing layer\n├── models/            # PPO agent: policy \u0026 value nets\n├── scripts/           # Faster execution script\n├── utils/             # Plotting, logging, metrics\n├── tests/             # Unit \u0026 integration tests\n├── main.py            # Main entry point\n├── requirements.txt   # Required libraries\n└── README.md          # This file\n```\n\n---\n\n## ✅ Installation\n\n### Prerequisites:\n\n* Python 3.10+\n\n### Create Environment:\n\n```bash\ngit clone https://github.com/yourusername/fintrix.git\ncd fintrix\nconda create -n fintrix python=3.10\nconda activate fintrix\npip install -r requirements.txt\n```\n\n---\n\n## 🧪 Running an Experiment\n\n```bash\npython main.py\n```\n\nThis will:\n\n* Detect your market region\n* Download historical price data\n* Train a DDPM to simulate financial time series\n* Generate enhanced training sets\n* Train a PPO agent using synthetic + real data\n* Evaluate final policy on real data only\n* Output performance metrics and plots\n\n---\n\n##  Sample Output\n\n### Cumulative Returns\n\n![Returns](assets/performance_plot_us.jpeg)\n\n### Allocation Pie Chart\n\n![Allocation](assets/final_allocation_us.jpeg)\n\n---\n\n## 🔧 Configuration Overview\n\nEdit `config/config.py`:\n\n```python\nSELECTED_TICKERS = [\"AAPL\", \"MSFT\", \"AMZN\", \"GOOGL\", \"JPM\", \"XOM\"]\nBENCHMARK_INDEX = \"^GSPC\"\nSTART_DATE = \"2010-01-01\"\nEND_DATE = \"2024-01-01\"\nDDPM_EPOCHS = 50\nRL_EPISODES = 200\nMAX_POSITION_SIZE = 0.25\nREBALANCE_THRESHOLD = 0.025\n```\n\n---\n\n## 🧪 Unit Testing\n\n```bash\npytest tests/\n```\n\nIncludes:\n\n* `test_env.py` — environment reset/step validation\n* `test_ddpm.py` — DDPM forward shape check\n* `test_ppo.py` — action, log-prob, value shape integrity\n\n---\n\n##  Future Extensions\n\n* Incorporate **financial news and sentiment data** for context-aware allocation\n* Add **multi-agent framework** (long-short strategies)\n* Integrate **live broker APIs** (e.g. Alpaca, Zerodha Kite)\n* Support **multi-objective RL** (risk-adjusted vs. absolute return)\n* Add **experiment tracking tools** (W\\\u0026B, MLflow)\n\n---\n\n## ⚠️ Disclaimer\n\n\u003e Fintrix is developed strictly for **educational and research purposes**.\n\u003e\n\u003e **Do NOT use Fintrix for live or real-money trading.**\n\u003e\n\u003e There are no guarantees of future performance, reliability, or correctness. Use entirely at your own risk.\n\n---\n\n## 📄 License\n\nMIT License. See [LICENSE](LICENSE) for full details.\n\n---\n\n##  Connect\n\n* GitHub: [github.com/pratycodes](https://github.com/pratycodes)\n* LinkedIn: [linkedin.com/in/pratyush-baliarsingh/](https://www.linkedin.com/in/pratyush-baliarsingh/)\n* Email: [pratyush.baliarsingh2004@gmail.com](mailto:pratyush.baliarsingh2004@gmail.com)\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpratycodes%2Ffintrix","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpratycodes%2Ffintrix","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpratycodes%2Ffintrix/lists"}