omaradly commited on
Commit
b10ec10
·
verified ·
1 Parent(s): 018abf3

Update README.md

Browse files
Files changed (1) hide show
  1. README.md +276 -1
README.md CHANGED
@@ -1,3 +1,278 @@
1
  ---
2
- license: apache-2.0
 
 
 
 
 
 
 
 
3
  ---
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
  ---
2
+ license: mit
3
+ tags:
4
+ - text-classification
5
+ - task-duration-estimation
6
+ - logistic-regression
7
+ - scikit-learn
8
+ - fastapi
9
+ - jira
10
+ pipeline_tag: text-classification
11
  ---
12
+
13
+ # Jira Task Duration Classifier
14
+
15
+ This repository packages a machine learning API that predicts whether a Jira-style software issue is likely to be **Short**, **Standard**, or **Long-running** based on the issue text and metadata.
16
+
17
+ It is designed as a recruiter-friendly ML project: the repository includes the trained model, a reproducible training script, cleaned sample data, evaluation artifacts, notebooks, and a FastAPI inference service.
18
+
19
+ ## What It Predicts
20
+
21
+ The model predicts an ordinal duration class, not an exact completion date.
22
+
23
+ | Class | Duration rule used during labeling |
24
+ | --- | --- |
25
+ | `Short` | 3 days or less |
26
+ | `Standard` | More than 3 days and up to 15 days |
27
+ | `Long-running` | More than 15 days |
28
+
29
+ The prediction is useful for early planning, triage, backlog sizing, and identifying tasks that may need more discovery before assignment.
30
+
31
+ ## Project Highlights
32
+
33
+ - **Model:** scikit-learn `Pipeline` with TF-IDF text features, one-hot categorical features, scaled numeric features, and Logistic Regression.
34
+ - **API:** FastAPI service with `/health`, `/predict`, `/docs`, and `/openapi.json`.
35
+ - **Inputs:** issue summary, description, priority, issue type, project metadata, date metadata, labels, assignee flag, votes, and watches.
36
+ - **Output:** predicted class plus class probabilities.
37
+ - **Evaluation:** held-out stratified test set with 20,315 examples and 0.80 accuracy.
38
+ - **Data source:** Apache Jira issues dataset from Kaggle.
39
+
40
+ ## Repository Contents
41
+
42
+ ```text
43
+ task-duration-classifier-hf/
44
+ |-- api/
45
+ | `-- main.py
46
+ |-- data/
47
+ | `-- processed/
48
+ | |-- final_cleaned_sample.csv
49
+ | `-- jira_issues_cleaned_sample.csv
50
+ |-- models/
51
+ | `-- duration_logistic_regression_classifier.joblib
52
+ |-- model_tests/
53
+ | |-- classification_report.txt
54
+ | |-- confusion_matrix.png
55
+ | `-- metric_charts/
56
+ |-- notebooks/
57
+ | |-- 01-exploratory-data-analysis.ipynb
58
+ | |-- 02-data-cleaning.ipynb
59
+ | |-- 03-feature-engineering.ipynb
60
+ | `-- rebuild_data_notebooks.py
61
+ `-- training/
62
+ |-- evaluate_data_filters.py
63
+ `-- model_training.py
64
+ ```
65
+
66
+ ## How It Works
67
+
68
+ The model is trained from completed Jira issues. For each issue, the pipeline combines:
69
+
70
+ - `total_text`: summary plus description, vectorized with TF-IDF unigrams and bigrams.
71
+ - Categorical fields: priority, issue type, project key, project category, created year, and created month.
72
+ - Numeric fields: text lengths, word counts, description presence, label count, assignee presence, votes, and watches.
73
+
74
+ The training script builds a single scikit-learn pipeline:
75
+
76
+ 1. `TfidfVectorizer(max_features=10000, stop_words="english", ngram_range=(1, 2), min_df=5, max_df=0.9, sublinear_tf=True)`
77
+ 2. `OneHotEncoder(handle_unknown="ignore")` for categorical metadata
78
+ 3. `SimpleImputer(strategy="median")` and `StandardScaler()` for numeric metadata
79
+ 4. `LogisticRegression(solver="saga", penalty="l2", max_iter=1200, random_state=42)`
80
+
81
+ The saved artifact is:
82
+
83
+ ```text
84
+ models/duration_logistic_regression_classifier.joblib
85
+ ```
86
+
87
+ ## Data Source And Preparation
88
+
89
+ The original data source is the Kaggle **Apache Jira Issues** dataset:
90
+
91
+ ```text
92
+ https://www.kaggle.com/datasets/tedlozzo/apaches-jira-issues
93
+ ```
94
+
95
+ The notebooks document the data workflow:
96
+
97
+ | Notebook | Purpose |
98
+ | --- | --- |
99
+ | `01-exploratory-data-analysis.ipynb` | Inspects raw fields, missingness, timestamps, text lengths, category distributions, and duration spread. |
100
+ | `02-data-cleaning.ipynb` | Keeps completed issues, validates created/resolution timestamps, normalizes text and category fields, and creates count/flag features. |
101
+ | `03-feature-engineering.ipynb` | Creates `duration_days`, assigns duration labels, filters noisy class boundaries, controls project dominance, and balances classes. |
102
+
103
+ Dataset flow from the source project:
104
+
105
+ | Stage | Rows |
106
+ | --- | ---: |
107
+ | Raw rows loaded in cleaning notebook | 1,149,323 |
108
+ | Completed issues after timestamp filtering | 945,103 |
109
+ | After duplicate removal | 937,203 |
110
+ | After consistency filtering | 258,722 |
111
+ | After project/class cap | 218,629 |
112
+ | Final balanced modeling rows | 101,571 |
113
+ | Rows per final duration class | 33,857 |
114
+ | Held-out test rows | 20,315 |
115
+
116
+ This Hugging Face repository includes sample processed CSVs for inspection. The full raw dataset is not included because it is large and should be downloaded from Kaggle.
117
+
118
+ Sample class distribution in `data/processed/final_cleaned_sample.csv`:
119
+
120
+ | Class | Sample rows |
121
+ | --- | ---: |
122
+ | `Short` | 27 |
123
+ | `Standard` | 37 |
124
+ | `Long-running` | 36 |
125
+
126
+ Example processed row:
127
+
128
+ | Field | Value |
129
+ | --- | --- |
130
+ | `summary` | `MailConsumer: Move mail after processing` |
131
+ | `issuetype_name` | `New Feature` |
132
+ | `priority_name` | `Major` |
133
+ | `project_key` | `CAMEL` |
134
+ | `has_description` | `1` |
135
+ | `duration_category` | `Short` |
136
+
137
+ ## Evaluation Metrics
138
+
139
+ The model was evaluated on a stratified held-out test split of 20,315 examples.
140
+
141
+ | Class | Precision | Recall | F1-score | Support |
142
+ | --- | ---: | ---: | ---: | ---: |
143
+ | `Long-running` | 0.79 | 0.71 | 0.74 | 6,771 |
144
+ | `Short` | 0.85 | 0.87 | 0.86 | 6,772 |
145
+ | `Standard` | 0.76 | 0.81 | 0.79 | 6,772 |
146
+ | **Accuracy** | | | **0.80** | **20,315** |
147
+ | **Macro avg** | **0.80** | **0.80** | **0.80** | **20,315** |
148
+ | **Weighted avg** | **0.80** | **0.80** | **0.80** | **20,315** |
149
+
150
+ ### Confusion Matrix
151
+
152
+ ![Confusion matrix](model_tests/confusion_matrix.png)
153
+
154
+ ### Per-Class Metrics
155
+
156
+ ![Classification metrics by class](model_tests/metric_charts/classification_metrics_by_class.png)
157
+
158
+ ![F1 score by class](model_tests/metric_charts/f1_score_by_class.png)
159
+
160
+ The strongest class is `Short` with an F1-score of 0.86. `Long-running` is the hardest class, mainly because it has lower recall: some long tasks are predicted as shorter categories.
161
+
162
+ ## API Usage
163
+
164
+ Run the API locally from the repository root:
165
+
166
+ ```bash
167
+ python -m pip install fastapi uvicorn pandas scikit-learn joblib pydantic
168
+ python -m uvicorn api.main:app --host 0.0.0.0 --port 8000
169
+ ```
170
+
171
+ Open the interactive API docs:
172
+
173
+ ```text
174
+ http://localhost:8000/docs
175
+ ```
176
+
177
+ ### Endpoints
178
+
179
+ | Method | Endpoint | Description |
180
+ | --- | --- | --- |
181
+ | `GET` | `/` | API metadata |
182
+ | `GET` | `/health` | Service status and model metadata |
183
+ | `POST` | `/predict` | Predicts duration class and probabilities |
184
+ | `GET` | `/docs` | Swagger UI |
185
+ | `GET` | `/openapi.json` | OpenAPI schema |
186
+
187
+ ### Example Request
188
+
189
+ ```bash
190
+ curl -X POST "http://localhost:8000/predict" \
191
+ -H "Content-Type: application/json" \
192
+ -H "Origin: http://localhost:8000" \
193
+ -d '{
194
+ "summary": "Fix CORS error on user endpoint",
195
+ "description": "Frontend requests are failing in production because the API response is missing an Access-Control-Allow-Origin header.",
196
+ "issuetype_name": "Bug",
197
+ "priority_name": "High",
198
+ "project_key": "WEB",
199
+ "project_category_name": "Application",
200
+ "created_year": 2026,
201
+ "created_month": 7,
202
+ "labels_count": 2,
203
+ "has_assignee": 1,
204
+ "votes_votes": 1,
205
+ "watches_watch_count": 4
206
+ }'
207
+ ```
208
+
209
+ Example response shape:
210
+
211
+ ```json
212
+ {
213
+ "duration_category": "Standard",
214
+ "probabilities": {
215
+ "Long-running": 0.18,
216
+ "Short": 0.27,
217
+ "Standard": 0.55
218
+ }
219
+ }
220
+ ```
221
+
222
+ ## Reproducing Training
223
+
224
+ The training script expects the full processed dataset at:
225
+
226
+ ```text
227
+ data/processed/final_cleaned.csv
228
+ ```
229
+
230
+ Then run:
231
+
232
+ ```bash
233
+ python -m pip install pandas scikit-learn joblib matplotlib
234
+ python training/model_training.py
235
+ ```
236
+
237
+ Training writes:
238
+
239
+ ```text
240
+ models/duration_logistic_regression_classifier.joblib
241
+ model_tests/classification_report.txt
242
+ model_tests/confusion_matrix.png
243
+ ```
244
+
245
+ The included `final_cleaned_sample.csv` is intended for inspection and API/schema understanding, not for full model reproduction.
246
+
247
+ ## API Safety Notes
248
+
249
+ The public prediction endpoint includes lightweight safeguards suitable for a demo API:
250
+
251
+ - bounded Pydantic input lengths and numeric ranges
252
+ - CORS configured from environment variables and local development origins
253
+ - origin/referer checks for browser requests
254
+ - request body size limit
255
+ - simple in-memory per-client rate limiting
256
+ - model inference run in a threadpool to avoid blocking the event loop
257
+
258
+ These controls are helpful for a portfolio demo, but they are not a substitute for production authentication, persistent rate limiting, abuse protection, or observability.
259
+
260
+ ## Limitations
261
+
262
+ - The model learns from historical Apache Jira patterns, so predictions may not transfer cleanly to private teams, different workflows, or non-software project management data.
263
+ - Duration is affected by team capacity, priority changes, dependencies, release schedules, and human process factors that are not fully represented in the input features.
264
+ - The labels are coarse buckets. The model does not estimate exact completion time.
265
+ - The target classes are ordinal, but Logistic Regression treats them as nominal classes.
266
+ - Some boundary cases are inherently ambiguous, especially tasks near the 3-day and 15-day thresholds.
267
+ - The included sample CSVs are for transparency and demonstration; full training requires rebuilding or downloading the larger processed dataset.
268
+
269
+ ## Why This Project Matters
270
+
271
+ For recruiters and ML reviewers, this project demonstrates an end-to-end applied ML workflow:
272
+
273
+ - data cleaning and feature engineering from messy real-world issue tracking data
274
+ - responsible simplification of a regression-like problem into useful planning categories
275
+ - scikit-learn pipeline design with text, categorical, and numeric features
276
+ - reproducible model artifact generation
277
+ - quantitative evaluation with both text and image artifacts
278
+ - deployable FastAPI inference with validation, probabilities, and basic API safeguards