From 534816d7995edd395367dbe31d459e35ba6b520c 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/api-reference.md | 44 +++++++++++++++++++++++++++ docs/getting-started.md | 67 +++++++++++++++++++++++++++++++++++++++++ docs/index.md | 28 +++++++++++++++++ docs/model-info.md | 31 +++++++++++++++++++ mkdocs.yml | 12 ++++++++ 6 files changed, 200 insertions(+) create mode 100644 catalog-info.yaml create mode 100644 docs/api-reference.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..2fabb41 --- /dev/null +++ b/catalog-info.yaml @@ -0,0 +1,18 @@ +apiVersion: backstage.io/v1alpha1 +kind: Component +metadata: + name: test-score-predictor + description: A machine learning service for predicting test scores based on study hours + annotations: + github.com/project-slug: test-score-predictor + backstage.io/techdocs-ref: dir:./docs + tags: + - fastapi + - python + - machine-learning + - education +spec: + type: service + lifecycle: experimental + owner: education-team + system: ml-services diff --git a/docs/api-reference.md b/docs/api-reference.md new file mode 100644 index 0000000..e5665fb --- /dev/null +++ b/docs/api-reference.md @@ -0,0 +1,44 @@ +# API Reference + +## Endpoints + +### GET / + +Returns the home page HTML. + +### GET /predict + +Returns the prediction form HTML. + +### POST /predict + +Predicts test scores based on the provided study hours. + +**Request Body** + +```json +{ + "hours_studied": 5.5 +} +``` + +| Parameter | Type | Description | +|-----------|------|-------------| +| hours_studied | float | Number of hours studied | + +**Response** + +```json +{ + "predicted_test_score": 85.6 +} +``` + +## Error Handling + +The API uses standard HTTP status codes to indicate the success or failure of requests. + +- 200: Success +- 400: Bad request (e.g., negative hours studied) +- 500: Server error +- 503: Service unavailable (model not loaded) diff --git a/docs/getting-started.md b/docs/getting-started.md new file mode 100644 index 0000000..bacca53 --- /dev/null +++ b/docs/getting-started.md @@ -0,0 +1,67 @@ +# Getting Started + +## Prerequisites + +- Docker +- Python 3.7+ + +## Installation + +1. Clone the repository +2. Build the Docker image: + +```bash +docker build -t test-score-predictor . +``` + +3. Run the container: + +```bash +docker run -p 8000:8000 test-score-predictor +``` + +## Environment Variables + +The application uses the following environment variables: +- `MODEL_PATH`: Path to the model file (default: `linear_regression_model.pkl`) +- `SCALER_PATH`: Path to the scaler file (default: `scaler.pkl`) +- `PORT`: Port to run the application on (default: `8000`) + +These can be set in the `.env` file or passed as environment variables. + +## Development + +To set up a development environment: + +1. Create a virtual environment: + +```bash +python -m venv venv +source venv/bin/activate # On Windows: venv\Scripts\activate +``` + +2. Install dependencies: + +```bash +pip install -r requirements.txt +``` + +3. Run the application: + +```bash +uvicorn main:app --reload +``` + +The application will be available at http://localhost:8000. + +## Testing + +Run the tests using: + +```bash +pytest test_api.py +``` + +## Deployment + +The application includes a GitHub Actions workflow for CI/CD in the `.github/workflows/deploy.yml` file. diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..421e754 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,28 @@ +# Test Score Predictor + +## Overview + +This is a machine learning service that predicts test scores based on the number of hours studied. The service uses a pre-trained linear regression model and provides both a web interface and API endpoints for predictions. + +## Features + +- Test score prediction based on study hours +- Web interface for easy interaction +- RESTful API for programmatic access +- Containerized with Docker +- CI/CD pipeline with GitHub Actions +- Environment variable configuration + +## Architecture + +The service is built using: +- FastAPI for the web framework +- Scikit-learn for the machine learning model (Linear Regression) +- Docker for containerization +- GitHub Actions for CI/CD + +## Documentation + +- [API Reference](api-reference.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..47efea6 --- /dev/null +++ b/docs/model-info.md @@ -0,0 +1,31 @@ +# Model Information + +## Overview + +The Test 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..0e40f18 --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,12 @@ +site_name: 'Test Score Predictor' +nav: + - Home: index.md + - API Reference: api-reference.md + - Model Information: model-info.md + - Getting Started: getting-started.md +plugins: + - techdocs-core +markdown_extensions: + - admonition + - pymdownx.highlight + - pymdownx.superfences