PriorityPilot — an ML-first CLI that learns how you ship

CLI copilot for backlogs & projects • Learns from user behavior • Reorders tasks intelligently • Estimates with confidence bands • Detects data drift

Highlights

• Adaptive prioritization that starts neutral and learns from your actions
• Time estimates with ± confidence bands
• Health and analytics reports for projects, milestones, and tasks
• Drift and data sufficiency checks before trusting predictions
• Two-speed UI: Basic for speed, Advanced for full analytics/ML/export controls

---

Quickstart (Windows/macOS/Linux)

1. Prerequisites: Python 3.9+.
2. (Recommended) Create a virtual environment:
   • Windows: python -m venv .venv then .venv\Scripts\activate
   • macOS/Linux: python3 -m venv .venv then source .venv/bin/activate
3. Install deps: pip install -r requirements.txt
4. Run the app: python app.py
5. In the menu: create a project (1), add a few tasks (6), then explore ML: insights (26), train (27), predict time (28). Models become useful after ~10–50 samples.

---

What the CLI can do

• Projects: create, list, select, summarize, archive
• Tasks: create, list, inspect, update status/progress, assign, dependencies, overdue, by assignee
• Milestones: create, list, complete
• Analytics/ML: smart priorities (17), health (18), bottlenecks (19), report (20), ML insights (26), train (27), predict time with intervals (28)
• Data: export/import JSON (21/22), Markdown report (23), switch UI mode (99)

---

How the ML layer works

• Signals: starting a task (higher priority), completing it (true duration), postponing it (lower priority); pairwise samples are generated to improve ranking.
• Models: Gradient Boosting (priority), Random Forest on log-hours (time), Logistic Regression (pairwise ranking), Ridge baseline.
• Auto-training: kicks in after ~10 samples and then every ~15–20; manual training via option 27.
• Transparency: ML insights show metrics, drift, and feature importance when available.

---

Data, models, and outputs

• Database: SQLite at data/projects.db (auto-created)
• Models: ml_models/ → priority_model.pkl, time_estimator.pkl, training_history.pkl
• Training data: ml_training_data/ → training_samples.json, decisions_log.json, pairwise_samples.json
• Exports: exports/ → JSON backups and Markdown report

---

Project layout

project/
├── app.py              # Entry point
├── cli/menu.py         # Text interface (Basic/Advanced)
├── services/           # Business logic & analytics
├── ml/                 # Feature extraction, training, inference
├── database/           # SQLite management
├── utils/              # Validation, formatting, import/export helpers
├── ml_models/          # Persisted models
├── ml_training_data/   # Samples and decisions
└── exports/            # Reports and data dumps

---

Practical flow

1. Create or select a project; add tasks with estimates and due dates.
2. Work normally—start, complete, or postpone tasks to generate signals.
3. Train (27) once you have ~10 samples; quality improves past ~50.
4. Check insights (26) and time predictions (28); heed drift or low-sample warnings before relying on them.

---

Metrics and guardrails

• Priority: R², MAE, Ridge baseline comparison
• Time: R² (log-scale), RMSE, MAPE (hours/percent)
• Ranking: accuracy on train/test pairs
• Drift: feature-shift score with warnings when thresholds break
• Confidence: explicit interval on every time estimate; warns on low sample counts

---

Tips

• Update status and progress often; better signals → better models.
• Log actual durations when completing tasks to tighten future estimates.
• Retrain after noticeable drift or when work type changes.
• Stay in Basic for speed; switch to Advanced for analytics and exports.

PriorityPilot: opinionated automation for teams that want ML clarity, not ML mystery.