{"id":20458303,"url":"https://github.com/asifdotexe/stodir","last_synced_at":"2026-05-08T06:07:11.809Z","repository":{"id":244500638,"uuid":"815424037","full_name":"Asifdotexe/StoDir","owner":"Asifdotexe","description":"Stock direction forecasting model to forecast trends based on the closing price for each day","archived":false,"fork":false,"pushed_at":"2024-08-23T16:50:21.000Z","size":1928,"stargazers_count":1,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-01-16T00:15:57.615Z","etag":null,"topics":["command-line","feature-engineering","random-forest-regression","stock-price-prediction","streamlit","time-series-analysis","yahoo-finance"],"latest_commit_sha":null,"homepage":"https://stodirforecast.streamlit.app/","language":"Jupyter Notebook","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Asifdotexe.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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}},"created_at":"2024-06-15T05:56:14.000Z","updated_at":"2024-07-21T10:22:11.000Z","dependencies_parsed_at":"2024-06-15T07:27:50.228Z","dependency_job_id":"aecd0a7b-a26d-4569-8581-05628d0029bb","html_url":"https://github.com/Asifdotexe/StoDir","commit_stats":null,"previous_names":["asifdotexe/stock-prediction-model","asifdotexe/stodir"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Asifdotexe%2FStoDir","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Asifdotexe%2FStoDir/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Asifdotexe%2FStoDir/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Asifdotexe%2FStoDir/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Asifdotexe","download_url":"https://codeload.github.com/Asifdotexe/StoDir/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":242014361,"owners_count":20057873,"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","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":["command-line","feature-engineering","random-forest-regression","stock-price-prediction","streamlit","time-series-analysis","yahoo-finance"],"created_at":"2024-11-15T12:11:50.981Z","updated_at":"2026-05-08T06:07:11.803Z","avatar_url":"https://github.com/Asifdotexe.png","language":"Jupyter Notebook","funding_links":[],"categories":[],"sub_categories":[],"readme":"# StoDir - Stock Direction Forecasting Application\n\nAn end-to-end system for training, evaluating, and deploying a stock-direction forecasting model.\n\n![Last Commit](https://img.shields.io/github/last-commit/Asifdotexe/StoDir)\n![Top Language](https://img.shields.io/github/languages/top/Asifdotexe/StoDir)\n![Languages Count](https://img.shields.io/github/languages/count/Asifdotexe/StoDir)\n[![Deployed App](https://img.shields.io/badge/Deployed%20App-Live-green)](https://stodirforecast.streamlit.app/)\n\n---\n\n## Table of Contents\n\n- [Overview](#overview)\n  - [What is StoDir?](#what-is-stodir)\n  - [Key technical features](#key-technical-features)\n  - [How it works](#how-it-works)\n  - [Tech stack](#tech-stack)\n- [Getting Started](#getting-started)\n  - [Prerequisites](#prerequisites)\n  - [Installation](#installation)\n  - [Usage](#usage)\n- [Documentation](#documentations)\n- [License](#license)\n\n---\n\n## Overview\n\n### What is StoDir?\nStoDir is a machine learning system that forecasts the likely direction (Up or Down) of a stock's price for the next trading day. This project is a complete, well-architected system that demonstrates professional techniques for building and deploying AI models.\n\n\u003e Disclaimer: This is a portfolio project designed to showcase technical skills and is not financial advice.\n\n### Key Technical Features\n1. A clear separation between the model training pipeline and the live inference application. The model is a versioned artifact, loaded by the app for fast, on-demand predictions.\n2. Employed a sliding-window backtesting methodology to provide a realistic performance assessment, mitigating lookahead bias common in financial forecasting.\n3. Utilized Hugging Face Hub as a model registry to store and version the trained model artifacts, enabling reproducible deployments.\n4. Provides both a Streamlit web interface for interactive use and a command-line interface (CLI) for programmatic access.\n\n### How it works\nThe system is split into two parts: an offline Training Pipeline that builds the model and a live Application that uses the model to make predictions.\n\n```text\n\n                            +--------------------------+\n                            |   Hugging Face Hub       |\n(1) TRAINING (Offline)      |  (Cloud Model Storage)   |     (3) PREDICTION (Live)\n+----------------------+    | +--------------------+   |    +----------------------+\n| train.py             |    | | stodir_model.joblib|   |    | app.py (Web App)     |\n| (Uses historical     |---\u003e| +--------------------+   |---\u003e| (Downloads model     |\n| data to build model) |    +--------------------------+    | \u0026 makes predictions) |\n+----------------------+                                    +----------------------+\n\n\n```\n\nFor a more detailed explanation, see the [Architecture Document](docs/SYSTEM_ARCHITECTURE.md).\n\n### Tech Stack\n- ML \u0026 Data: Scikit-learn, Pandas, yfinance\n- Deployment \u0026 MLOps: Hugging Face Hub, Streamlit, Joblib\n- Tooling: PyYAML, Pytest, Pylint\n\n---\n\n## Getting Started\n\n### Prerequisites\n\n1. **Using the Deployed Web App** \u003cbr\u003e\nThe easiest way to use the application is to visit the live version hosted on Streamlit Cloud:\n\n    \u003e Visit: [StoDir on Streamlit](https://stodirforecast.streamlit.app/)\n\n2. **Running Locally** \u003cbr\u003e\nTo run the project on your local machine, you will need to have Poetry installed. It is a modern dependency and environment manager for Python. The official installer is the recommended method.\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eInstall Poetry (Click to expand)\u003c/strong\u003e\u003c/summary\u003e\n\n\u003cbr/\u003e\n\n**Official Method (Recommended):**\n- macOS / Linux / WSL:\n    ```bash\n    curl -sSL [https://install.python-poetry.org](https://install.python-poetry.org) | python3 -\n    ```\n- Windows (PowerShell):\n    ```bash\n    (Invoke-WebRequest -Uri [https://install.python-poetry.org](https://install.python-poetry.org) -UseBasicParsing).Content | py -\n    ```\n\n**Alternative Methods:**\n\n- Using Homebrew (macOS/Linux):\n\n    ```bash\n    brew install poetry\n    ```\n\n- Using pipx (Windows/macOS/Linux):\nFirst, ensure pipx is installed (pip install pipx), then:\n\n    ```bash\n    pipx install poetry\n    ```\n\nAfter installing, you may need to restart your terminal for the poetry command to be available.\n\n\u003c/details\u003e\n\n### Installation\n\n1. Clone the repository:\n   ```bash\n   git clone https://github.com/Asifdotexe/StoDir.git\n   cd StoDir\n   ```\n\n2. Install Dependencies\nOnce you have the code, use Poetry to create a virtual environment and install all the necessary packages from the poetry.lock file. This guarantees a reproducible setup.\nEnsure `poetry.lock` is committed to the repository for consistency across machines.\n\n    ```bash\n    poetry install\n    ```\n\n### Usage\nAll commands should be prefixed with poetry run to ensure they execute within the project's managed virtual environment.\n\n1. **Run the Web App**\n\n    Starting a local web server. The app uses the pre-trained model from Hugging Face.\n\n    ```bash\n    poetry run streamlit run app.py\n    ```\n    If your Hub repo is private, set `HF_TOKEN` in the environment before starting.\n\n2. **Use the Command-Line Tool**\n\n    The CLI uses a local `artifacts/stodir_model.joblib` by default. Create it by running the training pipeline (or point the CLI to a Hub-hosted model).\n\n    ```bash\n    poetry run python train.py\n    ```\n    Then, get a forecast directly in your terminal:\n\n    ```bash\n    # Example: Get a forecast for Google\n    poetry run python cli.py GOOGL\n    ```\n\n## Documentation\n- [Project Methodology Document](docs/PROJECT_METHODOLOGY.md)\n- [System Architecture Document](docs/SYSTEM_ARCHITECTURE.md)\n- [Backtesting Document](docs/BACKTESTING.md)\n\n## License\nThis project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fasifdotexe%2Fstodir","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fasifdotexe%2Fstodir","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fasifdotexe%2Fstodir/lists"}