From f19e81964fd4fdfc457ea2af2b7113410102df11 Mon Sep 17 00:00:00 2001 From: spham Date: Sun, 8 Jun 2025 00:14:36 +0200 Subject: [PATCH] Ajout de la documentation et de la configuration Backstage.io --- catalog-info.yaml | 18 ++++++++++++++++ docs/application-guide.md | 30 ++++++++++++++++++++++++++ docs/getting-started.md | 44 +++++++++++++++++++++++++++++++++++++++ docs/index.md | 25 ++++++++++++++++++++++ docs/model-info.md | 31 +++++++++++++++++++++++++++ mkdocs.yml | 12 +++++++++++ 6 files changed, 160 insertions(+) create mode 100644 catalog-info.yaml create mode 100644 docs/application-guide.md create mode 100644 docs/getting-started.md create mode 100644 docs/index.md create mode 100644 docs/model-info.md create mode 100644 mkdocs.yml diff --git a/catalog-info.yaml b/catalog-info.yaml new file mode 100644 index 0000000..bb0c597 --- /dev/null +++ b/catalog-info.yaml @@ -0,0 +1,18 @@ +apiVersion: backstage.io/v1alpha1 +kind: Component +metadata: + name: streamlit-score-predictor + description: A Streamlit application for predicting test scores based on study hours + annotations: + github.com/project-slug: streamlit-score-predictor + backstage.io/techdocs-ref: dir:./docs + tags: + - streamlit + - python + - machine-learning + - education +spec: + type: website + lifecycle: experimental + owner: education-team + system: ml-services diff --git a/docs/application-guide.md b/docs/application-guide.md new file mode 100644 index 0000000..0aeabf2 --- /dev/null +++ b/docs/application-guide.md @@ -0,0 +1,30 @@ +# Application Guide + +## Using the Streamlit Application + +The Streamlit Score Predictor is a simple web application that allows users to predict test scores based on the number of hours studied. + +### Interface Overview + +The application consists of: +1. A title and description +2. A number input field for entering hours studied +3. A "Predict" button +4. A results section that displays the predicted test score + +### Making Predictions + +1. Enter the number of hours studied in the input field + - Use the up/down arrows or type directly in the field + - The minimum value is 0 + - You can increment by 1.0 hour using the arrows + +2. Click the "Predict" button + +3. View the predicted test score + - The prediction will appear below the button + - The score is displayed with two decimal places + +### Error Handling + +If there is an issue with the prediction (e.g., invalid input or model error), an error message will be displayed. diff --git a/docs/getting-started.md b/docs/getting-started.md new file mode 100644 index 0000000..1810595 --- /dev/null +++ b/docs/getting-started.md @@ -0,0 +1,44 @@ +# Getting Started + +## Prerequisites + +- Python 3.7+ +- Streamlit +- Scikit-learn +- Joblib + +## Installation + +1. Clone the repository +2. Install dependencies: + +```bash +pip install -r requirements.txt +``` + +## Running the Application + +Run the Streamlit application with: + +```bash +streamlit run streamlit.py +``` + +The application will open in your default web browser, typically at http://localhost:8501. + +## Development + +To modify the application: + +1. Edit the `streamlit.py` file to change the UI or functionality +2. The application will automatically reload when you save changes + +## Deployment + +Streamlit applications can be deployed in several ways: + +1. **Streamlit Sharing**: A free hosting service for Streamlit apps +2. **Heroku**: Deploy using a Procfile and requirements.txt +3. **Docker**: Containerize the application for deployment anywhere + +For deployment, ensure that the model and scaler files are included with the application code. diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..897d966 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,25 @@ +# Streamlit Score Predictor + +## Overview + +This is a Streamlit application that predicts test scores based on the number of hours studied. The application uses a pre-trained linear regression model to make predictions. + +## Features + +- Simple, user-friendly web interface built with Streamlit +- Test score prediction based on study hours +- Interactive input controls +- Immediate prediction results + +## Architecture + +The application is built using: +- Streamlit for the web interface +- Scikit-learn for the machine learning model (Linear Regression) +- Joblib for model loading + +## Documentation + +- [Application Guide](application-guide.md) +- [Model Information](model-info.md) +- [Getting Started](getting-started.md) diff --git a/docs/model-info.md b/docs/model-info.md new file mode 100644 index 0000000..7583b4a --- /dev/null +++ b/docs/model-info.md @@ -0,0 +1,31 @@ +# Model Information + +## Overview + +The Streamlit Score Predictor uses a Linear Regression machine learning model trained to predict test scores based on the number of hours studied. + +## Model Details + +- **Model Type**: Linear Regression +- **Features Used**: + - Hours Studied: Number of hours a student studied +- **Output**: Predicted test score +- **Model File**: `linear_regression_model.pkl` +- **Scaler File**: `scaler.pkl` + +## Dataset + +The model was trained on a dataset containing information about students' study hours and their corresponding test scores. + +## Model Performance + +The model demonstrates a strong correlation between hours studied and test scores, with typical metrics showing: +- R² score: ~0.95 +- Mean Absolute Error: ~2-3 points + +## Limitations + +- The model assumes a linear relationship between study hours and test scores +- The model may not account for other factors that influence test performance (quality of study, prior knowledge, etc.) +- Predictions for very low or very high study hours may be less reliable +- The model is intended for educational purposes and should not be used for critical decision-making diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 0000000..b654c7f --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,12 @@ +site_name: 'Streamlit Score Predictor' +nav: + - Home: index.md + - Application Guide: application-guide.md + - Model Information: model-info.md + - Getting Started: getting-started.md +plugins: + - techdocs-core +markdown_extensions: + - admonition + - pymdownx.highlight + - pymdownx.superfences