{"id":29946030,"url":"https://github.com/adityasreevatsak/smartflow","last_synced_at":"2026-04-13T14:31:25.197Z","repository":{"id":306737110,"uuid":"952994921","full_name":"AdityaSreevatsaK/SmartFlow","owner":"AdityaSreevatsaK","description":"SmartFlow enhances bike-sharing efficiency by combining deep reinforcement learning with agentic AI. The RL model optimizes bike distribution, while agentic AI coordinates real-time actions, like alerting truck drivers. This scalable approach ensures smart decisions and timely execution for urban transport.","archived":false,"fork":false,"pushed_at":"2025-08-24T18:37:46.000Z","size":85590,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-08-24T22:50:35.820Z","etag":null,"topics":["agentic-ai","jupyter-notebook","keras","open-ai-gym","pandas","python","pytorch","reinforcement-learning","scikit-learn","seaborn","stable-baselines3","tensorflow"],"latest_commit_sha":null,"homepage":"","language":"HTML","has_issues":false,"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/AdityaSreevatsaK.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-03-22T10:24:19.000Z","updated_at":"2025-08-24T18:37:50.000Z","dependencies_parsed_at":"2025-08-24T20:35:32.931Z","dependency_job_id":null,"html_url":"https://github.com/AdityaSreevatsaK/SmartFlow","commit_stats":null,"previous_names":["adityasreevatsak/smartflow"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/AdityaSreevatsaK/SmartFlow","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AdityaSreevatsaK%2FSmartFlow","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AdityaSreevatsaK%2FSmartFlow/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AdityaSreevatsaK%2FSmartFlow/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AdityaSreevatsaK%2FSmartFlow/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/AdityaSreevatsaK","download_url":"https://codeload.github.com/AdityaSreevatsaK/SmartFlow/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AdityaSreevatsaK%2FSmartFlow/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31757477,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-13T13:27:56.013Z","status":"ssl_error","status_checked_at":"2026-04-13T13:21:23.512Z","response_time":93,"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":["agentic-ai","jupyter-notebook","keras","open-ai-gym","pandas","python","pytorch","reinforcement-learning","scikit-learn","seaborn","stable-baselines3","tensorflow"],"created_at":"2025-08-03T05:11:15.709Z","updated_at":"2026-04-13T14:31:25.177Z","avatar_url":"https://github.com/AdityaSreevatsaK.png","language":"HTML","funding_links":[],"categories":[],"sub_categories":[],"readme":"# \u003cp align=\"center\"\u003eSmartFlow: Reinforcement Learning and Agentic AI for Bike-Sharing Optimisation\u003c/p\u003e\n\n---\n\n## Objective\n\nSmartFlow introduces a novel solution for enhancing the efficiency of bike-sharing systems through the integration of\ndeep reinforcement learning and agentic AI. The RL model learns optimal policies to balance supply and demand across\nstations, while the agentic components manage real-time communication with ground personnel, such as truck drivers. This\ndual approach ensures that intelligent, data-driven decisions are translated into timely, real-world actions, offering a\nscalable and adaptive strategy for modern urban transport networks.\n\n---\n\n## Overview\n\nSmartFlow is a **hybrid framework** designed to optimise urban bike-sharing operations. It combines a deep reinforcement\nlearning (RL) model with an agentic AI layer to dynamically learn bike movement patterns, anticipate demand, and\nrecommend optimal bike redistribution strategies. The agentic layer autonomously communicates with truck drivers and\noperational staff, enabling seamless, hands-free coordination and significantly reducing the need for manual\nintervention.\n\n#### This project aims to:\n\n* Minimise bike idle time and station imbalances (overcrowding or emptiness).\n* Improve overall bike availability and enhance user satisfaction.\n* Lower operational costs associated with fleet management.\n* Provide a scalable and adaptable solution for complex urban environments.\n\n---\n\n## Architecture\n\nA high-level diagram illustrating the interaction between the RL core, the simulator, and the agentic AI layer.\n\n\u003cimg src='docs/SmartFlow - Architecture.png'\u003e\u003c/img\u003e\n\n---\n\n## Key Features\n\n* **Deep Reinforcement Learning Core:**\n  Learns optimal, state-aware redistribution policies from historical trip data and simulated demand, outperforming\n  static and heuristic-based rebalancing methods.\n\n* **Agentic AI Communication Layer:**\n  Automates operational logistics by issuing clear, actionable tasks (e.g., truck routing, inventory checks) to ground\n  staff via autonomous communication agents.\n\n* **Simulator-in-the-Loop Training:**\n  Utilises a digital twin of the urban environment to train, test, and validate policies safely, allowing for dynamic\n  adaptation to real-time changes in demand and traffic before deployment.\n\n* **Modular and Extensible:**\n  Designed for flexible integration with public data feeds, real-time APIs, and diverse urban infrastructures, ensuring\n  broad applicability.\n\n---\n\n## Motivation\n\nDespite the global success of bike-sharing systems, maintaining an optimal distribution of bikes in real-time remains a\nsignificant operational challenge. Traditional rebalancing methods are often static or manually scheduled, rendering\nthem unable to adapt to the dynamic fluctuations of user demand, traffic congestion, or city-wide events. This\ninefficiency leads to underutilised assets, increased operational costs, and a diminished user experience.\n\nSmartFlow directly addresses these limitations by enabling an adaptive, data-driven, and automated approach to fleet\nmanagement that aligns with modern smart city objectives.\n\n---\n### Technology Stack\n\nThe SmartFlow framework is built on a specific stack of modern libraries for data science, reinforcement learning, and agentic AI.\n\n* **Core ML \u0026 Data Science:** Python, Pandas, NumPy, Scikit-learn\n* **Deep Learning Backend:** PyTorch\n* **Reinforcement Learning:** Stable-Baselines3 (DQN Algorithm), Gymnasium (for the environment API)\n* **Agentic AI \u0026 NLP:** Hugging Face (Transformers, Accelerate, BitsAndBytes) with the `google/gemma-2b-it` model\n* **Geospatial \u0026 Routing:** OSMnx, NetworkX\n* **Visualisation \u0026 Mapping:** Matplotlib, Seaborn, Folium, TensorBoard\n\n---\n\n## Repository Structure\n\n```\n.\n├── data/                 # Raw and processed datasets\n│   ├── processed/\n│   └── raw/\n├── docs/                 # Project documentation, papers, and reports\n├── images/               # Diagrams and visual assets for documentation\n├── references/           # Supporting research papers and code snippets\n│   ├── code-snippets/\n│   └── papers/\n├── results/              # Model outputs, logs, and performance visualisations\n│   ├── models/\n│   ├── other_metrics/\n│   ├── plots/\n│   ├── rewards/\n│   └── simulation/\n├── src/                  # Source code for different implementation approaches\n│   ├── library_based/    # Implementations using existing RL/AI libraries\n│   ├── snippets/         # Reusable code snippets for development\n│   └── vanilla_python/   # Core logic implemented in standard Python\n├── .env                  # Environment variables configuration\n├── .gitignore            # Files and directories to be ignored by Git\n├── environment.yml       # Conda environment dependencies\n├── LICENSE               # Project software license\n├── README.md             # This file\n└── TODO.md               # Development roadmap and tasks\n```\n\n---\n\n## Getting Started\n\n1. **Clone the repository:**\n\n   ```bash\n   git clone https://github.com/AdityaSreevatsaK/SmartFlow.git\n   cd SmartFlow\n   ```\n\n2. **Create and activate the Conda environment:**\n   The `environment.yml` file contains all the necessary dependencies. Create the environment using this file.\n\n   ```bash\n   conda env create -f environment.yml\n   ```\n\n   This will create a new environment with the name specified inside the file (e.g., `smartflow_env`). Activate it:\n\n   ```bash\n   conda activate smartflow_env\n   ```\n\n3. **Prepare the data:**\n   Place your raw trip data in the `data/raw/` directory. Raw data can be processed and cleaned for modelling using the\n   dedicated [**SmartFlow-Prep pipeline**](https://github.com/AdityaSreevatsaK/SmartFlow-Prep).\n\n4. **Run the scripts:**\n   Execute the desired training or simulation scripts located within the `src/` subdirectories.\n\n---\n\n### Citation\n\nIf you use SmartFlow in your research, please cite it as follows. For in-text citations, please use the format (\nSreevatsa K et al., 2025).\n\n**BibTeX Entry:**\n\n```bibtex\n@unpublished{sreevatsa2025smartflow,\n  author    = {Sreevatsa K, Aditya and Raveendran, Arun Kumar and Mani, Jesrael K and Shigli, Prakash G and Rangadore, Rajkumar},\n  title     = {{SmartFlow: Reinforcement Learning and Agentic AI for Bike-Sharing Optimisation}},\n  note      = {Manuscript in preparation},\n  year      = {2025},\n  month     = {aug}\n}\n```\n\n---\n\n## Licensing\n\nThe source code of SmartFlow is licensed under the **MIT License**. You can find the full license text in the `LICENSE`\nfile.\n\nThe accompanying research paper is licensed under a\n**Creative Commons Attribution 4.0 International License (CC BY 4.0)**, as required by the conference publisher.\n\n---\n\n## Project Status\n\nSee `TODO.md` for our development roadmap, planned features, and bug tracking.\n\n---\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fadityasreevatsak%2Fsmartflow","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fadityasreevatsak%2Fsmartflow","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fadityasreevatsak%2Fsmartflow/lists"}