ado-git-repo-insights 3.2.0__tar.gz → 3.3.0__tar.gz

{ado_git_repo_insights-3.2.0 → ado_git_repo_insights-3.3.0}/CHANGELOG.md

@@ -1,3 +1,17 @@
+# [3.3.0](https://github.com/oddessentials/ado-git-repo-insights/compare/v3.2.0...v3.3.0) (2026-01-18)
+
+
+### Bug Fixes
+
+* revert manual version bump, remove obsolete planning doc ([df019c0](https://github.com/oddessentials/ado-git-repo-insights/commit/df019c0738ddc0b3b684e940ed8fcd272e879dec))
+* **tests:** resolve ruff linting errors in Phase 5 ML tests ([d816e36](https://github.com/oddessentials/ado-git-repo-insights/commit/d816e3697d1993369f4be82df563faad7d8b435e))
+
+
+### Features
+
+* **dashboard:** enable Phase 5 features (Predictions & AI Insights tabs) ([649f39e](https://github.com/oddessentials/ado-git-repo-insights/commit/649f39e17ca7c778133aed2dba8df0bf360d4b03))
+* **task:** add Phase 5 ML inputs to pipeline task (v2.3.0) ([314c560](https://github.com/oddessentials/ado-git-repo-insights/commit/314c56045ecc531cec7cf60d94b180dc9655b2ea))
+
 # [3.2.0](https://github.com/oddessentials/ado-git-repo-insights/compare/v3.1.0...v3.2.0) (2026-01-18)
 
 

{ado_git_repo_insights-3.2.0 → ado_git_repo_insights-3.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ado-git-repo-insights
-Version: 3.2.0
+Version: 3.3.0
 Summary: Extract Azure DevOps Pull Request metrics to SQLite and generate PowerBI-compatible CSVs.
 Author-email: "Odd Essentials, LLC" <admin@oddessentials.com>
 License: MIT

ado_git_repo_insights-3.3.0/VERSION

@@ -0,0 +1 @@
+3.3.0

ado_git_repo_insights-3.3.0/docs/ENABLE-ML-FEATURES.md

@@ -0,0 +1,241 @@
+# Enabling ML Features (Phase 5)
+
+This guide explains how to enable and configure the Phase 5 ML features: **Predictions** (Prophet time-series forecasting) and **AI Insights** (OpenAI-powered analysis).
+
+## Overview
+
+Phase 5 adds two new dashboard tabs:
+
+- **Predictions**: Forecasts for PR throughput, cycle time, and review time over the next 4 weeks
+- **AI Insights**: AI-generated observations about bottlenecks, trends, and anomalies
+
+Both features are opt-in via pipeline task inputs and require additional dependencies.
+
+## Prerequisites
+
+### For Predictions (Prophet)
+
+Prophet requires a working C++ compiler and CMake. On hosted agents, this is typically available. For self-hosted agents:
+
+**Ubuntu/Debian:**
+```bash
+sudo apt-get install -y build-essential cmake python3-dev
+pip install prophet>=1.1.0
+```
+
+**Windows:**
+- Install Visual Studio Build Tools with C++ workload
+- Or use a hosted agent where Prophet is pre-installed
+
+**macOS:**
+```bash
+xcode-select --install
+pip install prophet>=1.1.0
+```
+
+### For AI Insights (OpenAI)
+
+1. Create an OpenAI account at https://platform.openai.com
+2. Generate an API key
+3. Store the key as a secret in Azure DevOps:
+   - Go to Pipelines > Library > Variable Groups
+   - Create a new variable group (e.g., "OpenAI Secrets")
+   - Add variable: `OPENAI_API_KEY` = `sk-...` (mark as secret)
+   - Link the variable group to your pipeline
+
+## Pipeline Configuration
+
+### Basic Configuration
+
+Add the new inputs to your pipeline YAML:
+
+```yaml
+- task: ExtractPullRequests@2
+  inputs:
+    organization: $(System.CollectionUri)
+    projects: |
+      ProjectA
+      ProjectB
+    pat: $(PAT)
+    generateAggregates: true
+    # Enable ML features
+    enablePredictions: true
+    enableInsights: true
+    openaiApiKey: $(OPENAI_API_KEY)
+```
+
+### Full Example
+
+```yaml
+trigger:
+  - main
+
+schedules:
+  - cron: "0 6 * * *"  # Run daily at 6 AM
+    displayName: Daily PR Insights
+    branches:
+      include: [main]
+    always: true
+
+variables:
+  - group: OpenAI Secrets  # Contains OPENAI_API_KEY
+
+stages:
+  - stage: Extract
+    jobs:
+      - job: ExtractPRs
+        pool:
+          vmImage: 'ubuntu-latest'
+        steps:
+          - task: UsePythonVersion@0
+            inputs:
+              versionSpec: '3.10'
+              addToPath: true
+
+          - task: ExtractPullRequests@2
+            inputs:
+              organization: $(System.CollectionUri)
+              projects: |
+                MyProject
+              pat: $(PAT)
+              generateAggregates: true
+              enablePredictions: true
+              enableInsights: true
+              openaiApiKey: $(OPENAI_API_KEY)
+
+          - task: PublishPipelineArtifact@1
+            inputs:
+              targetPath: '$(Pipeline.Workspace)/aggregates'
+              artifact: 'aggregates'
+```
+
+## Task Input Reference
+
+| Input | Type | Default | Description |
+|-------|------|---------|-------------|
+| `enablePredictions` | boolean | `false` | Generate ML predictions using Prophet |
+| `enableInsights` | boolean | `false` | Generate AI insights using OpenAI |
+| `openaiApiKey` | string | - | OpenAI API key (required if `enableInsights` is true) |
+
+## Output Files
+
+When ML features are enabled, additional files are generated:
+
+```
+aggregates/
+├── dataset-manifest.json    # features.predictions / features.ai_insights = true
+├── aggregates/
+│   └── ...
+├── predictions/
+│   └── trends.json          # When enablePredictions=true
+└── insights/
+    └── summary.json         # When enableInsights=true
+```
+
+### predictions/trends.json
+
+Contains 4-week forecasts for key metrics:
+
+```json
+{
+  "schema_version": 1,
+  "generated_at": "2026-01-18T12:00:00Z",
+  "is_stub": false,
+  "generated_by": "prophet-v1.0",
+  "forecasts": [
+    {
+      "metric": "pr_throughput",
+      "unit": "count",
+      "horizon_weeks": 4,
+      "values": [
+        {
+          "period_start": "2026-01-20",
+          "predicted": 28,
+          "lower_bound": 22,
+          "upper_bound": 34
+        }
+      ]
+    }
+  ]
+}
+```
+
+### insights/summary.json
+
+Contains AI-generated insights:
+
+```json
+{
+  "schema_version": 1,
+  "generated_at": "2026-01-18T12:00:00Z",
+  "is_stub": false,
+  "generated_by": "openai-v1.0",
+  "insights": [
+    {
+      "id": "bottleneck-abc123",
+      "category": "bottleneck",
+      "severity": "warning",
+      "title": "Review latency increasing",
+      "description": "Average time to first review has increased by 15%.",
+      "affected_entities": ["team:Backend Team"]
+    }
+  ]
+}
+```
+
+## Dashboard Display
+
+Once ML features are enabled and data is generated:
+
+1. **Predictions tab**: Shows forecast charts with confidence intervals
+2. **AI Insights tab**: Shows categorized insight cards grouped by severity
+
+If no data is available, the tabs show "Coming Soon" state with instructions to enable the features in the pipeline.
+
+## Troubleshooting
+
+### "Predictions skipped: Prophet not installed"
+
+Install Prophet with ML extras:
+```bash
+pip install "ado-git-repo-insights[ml]"
+```
+
+Or install Prophet directly:
+```bash
+pip install prophet>=1.1.0
+```
+
+### "AI Insights enabled but OpenAI API Key not provided"
+
+Ensure `openaiApiKey` input is set and the variable group is linked to your pipeline.
+
+### Prophet installation fails
+
+Prophet requires additional build tools. See [Prophet Installation](https://facebook.github.io/prophet/docs/installation.html) for platform-specific instructions.
+
+### OpenAI rate limits
+
+The insights generator caches results for 24 hours to minimize API calls. If you hit rate limits:
+1. Wait for the rate limit window to reset
+2. Consider using a higher-tier OpenAI plan
+
+## Cost Considerations
+
+### Prophet (Predictions)
+- **Cost**: Free (runs locally)
+- **Runtime**: +10-30 seconds per pipeline run
+- **Resource**: CPU-intensive during model fitting
+
+### OpenAI (AI Insights)
+- **Cost**: ~$0.001-0.01 per run (depends on PR count)
+- **Runtime**: +5-15 seconds per pipeline run
+- **Caching**: Results cached for 24 hours (same data = no API call)
+
+## Security
+
+- **PAT**: Never logged, passed securely to Python process
+- **OpenAI API Key**: Passed via environment variable, never logged
+- **Data**: PR metadata is sent to OpenAI for analysis (titles, cycle times, counts)
+
+If your organization has data residency requirements, consider using Azure OpenAI Service instead.

{ado_git_repo_insights-3.2.0 → ado_git_repo_insights-3.3.0}/extension/tasks/extract-prs/index.js

@@ -77,10 +77,13 @@ async function validatePythonEnvironment() {
 
 /**
  * Install the Python package if not already installed.
+ * @param {string} pythonCmd - Python executable command
+ * @param {boolean} withML - Install ML extras (prophet, openai)
  */
-function installPackage(pythonCmd) {
+function installPackage(pythonCmd, withML = false) {
     try {
-        tl.debug(`Checking if ${PACKAGE_NAME} is installed...`);
+        const packageSpec = withML ? `${PACKAGE_NAME}[ml]` : PACKAGE_NAME;
+        tl.debug(`Checking if ${packageSpec} is installed...`);
 
         // Check if package is already installed
         try {
@@ -88,12 +91,32 @@ function installPackage(pythonCmd) {
                 encoding: 'utf-8',
                 stdio: 'pipe'
             });
+
+            // If ML is needed, verify ML dependencies are available
+            if (withML) {
+                try {
+                    execSync(`${pythonCmd} -c "import prophet; import openai"`, {
+                        encoding: 'utf-8',
+                        stdio: 'pipe'
+                    });
+                    tl.debug(`${packageSpec} already installed with ML extras`);
+                    return true;
+                } catch (e) {
+                    // ML dependencies missing, need to install them
+                    tl.debug(`ML dependencies missing, installing ${packageSpec}...`);
+                    execSync(`${pythonCmd} -m pip install "${packageSpec}" --quiet`, {
+                        stdio: 'inherit'
+                    });
+                    return true;
+                }
+            }
+
             tl.debug(`${PACKAGE_NAME} already installed`);
             return true;
         } catch (e) {
             // Package not installed, install it
-            tl.debug(`Installing ${PACKAGE_NAME}...`);
-            execSync(`${pythonCmd} -m pip install ${PACKAGE_NAME} --quiet`, {
+            tl.debug(`Installing ${packageSpec}...`);
+            execSync(`${pythonCmd} -m pip install "${packageSpec}" --quiet`, {
                 stdio: 'inherit'
             });
             return true;
@@ -117,8 +140,13 @@ async function run() {
     const pythonCmd = await validatePythonEnvironment();
     if (!pythonCmd) return;
 
-    // Install package
-    if (!installPackage(pythonCmd)) return;
+    // Phase 5: Check if ML features are requested (need ML extras)
+    const enablePredictions = tl.getBoolInput('enablePredictions', false);
+    const enableInsights = tl.getBoolInput('enableInsights', false);
+    const needsML = enablePredictions || enableInsights;
+
+    // Install package (with ML extras if needed)
+    if (!installPackage(pythonCmd, needsML)) return;
 
     try {
         // Get task inputs
@@ -131,6 +159,8 @@ async function run() {
         // Phase 3: Aggregates generation
         const generateAggregates = tl.getBoolInput('generateAggregates', false);
         const aggregatesDirInput = tl.getInput('aggregatesDir', false) || 'aggregates';
+        // Phase 5: ML features (enablePredictions/enableInsights already read above for install)
+        const openaiApiKey = tl.getInput('openaiApiKey', false);
         // CRITICAL: Input name must match task.json contract ('database', not 'databasePath')
         const databaseInput = tl.getInput('database', false) || 'ado-insights.sqlite';
         const outputDirInput = tl.getInput('outputDir', false) || 'csv_output';
@@ -196,9 +226,23 @@ async function run() {
         if (generateAggregates) {
             console.log(`Generate Aggregates: true`);
             console.log(`Aggregates Dir: ${aggregatesDir}`);
+            if (enablePredictions) console.log(`ML Predictions: enabled`);
+            if (enableInsights) console.log(`AI Insights: enabled`);
+            if (enableInsights && openaiApiKey) console.log(`OpenAI API Key: ********`);
         }
         console.log('='.repeat(50));
 
+        // Phase 5: Validate insights configuration
+        if (enableInsights && !openaiApiKey) {
+            tl.setResult(tl.TaskResult.Failed,
+                `AI Insights enabled but OpenAI API Key not provided.\n\n` +
+                `Resolution:\n` +
+                `1. Create a variable group with OPENAI_API_KEY secret\n` +
+                `2. Set openaiApiKey input to $(OPENAI_API_KEY)`
+            );
+            return;
+        }
+
         // Validate date formats if provided (fail fast on invalid input)
         const datePattern = /^\d{4}-\d{2}-\d{2}$/;
         if (startDate && !datePattern.test(startDate)) {
@@ -278,8 +322,22 @@ async function run() {
                 '--output', aggregatesDir,
             ];
 
+            // Phase 5: Add ML flags
+            if (enablePredictions) {
+                aggArgs.push('--enable-predictions');
+            }
+            if (enableInsights) {
+                aggArgs.push('--enable-insights');
+            }
+
             console.log(`\n[3/${totalSteps}] Generating aggregates...`);
-            const aggResult = await runPython(pythonCmd, aggArgs);
+
+            // Phase 5: Set OPENAI_API_KEY environment variable for insights
+            const aggEnv = enableInsights && openaiApiKey
+                ? { OPENAI_API_KEY: openaiApiKey }
+                : {};
+
+            const aggResult = await runPython(pythonCmd, aggArgs, aggEnv);
             if (!aggResult) return;
         }
 
@@ -302,12 +360,16 @@ async function run() {
 
 /**
  * Run Python command and return success status.
+ * @param {string} pythonCmd - Python executable command
+ * @param {string[]} args - Command arguments
+ * @param {Object} extraEnv - Additional environment variables to pass
  */
-function runPython(pythonCmd, args) {
+function runPython(pythonCmd, args, extraEnv = {}) {
     return new Promise((resolve) => {
         const proc = spawn(pythonCmd, args, {
             stdio: 'inherit',
-            shell: process.platform === 'win32'
+            shell: process.platform === 'win32',
+            env: { ...process.env, ...extraEnv }
         });
 
         proc.on('close', (code) => {

{ado_git_repo_insights-3.2.0 → ado_git_repo_insights-3.3.0}/extension/tasks/extract-prs/task.json

@@ -8,7 +8,7 @@
     "author": "Odd Essentials, LLC",
     "version": {
         "Major": 2,
-        "Minor": 2,
+        "Minor": 3,
         "Patch": 0
     },
     "instanceNameFormat": "Extract PR Metrics",
@@ -86,6 +86,32 @@
             "required": false,
             "defaultValue": "$(Pipeline.Workspace)/aggregates",
             "helpMarkDown": "Directory for aggregate JSON files (used with generateAggregates)"
+        },
+        {
+            "name": "enablePredictions",
+            "type": "boolean",
+            "label": "Generate ML Predictions",
+            "required": false,
+            "defaultValue": "false",
+            "helpMarkDown": "Generate trend predictions using Prophet time-series forecasting. Requires generateAggregates to be enabled. Adds ~10-30s to pipeline runtime.",
+            "visibleRule": "generateAggregates = true"
+        },
+        {
+            "name": "enableInsights",
+            "type": "boolean",
+            "label": "Generate AI Insights",
+            "required": false,
+            "defaultValue": "false",
+            "helpMarkDown": "Generate AI-powered insights using OpenAI. Requires generateAggregates and openaiApiKey. Adds ~5-15s to pipeline runtime.",
+            "visibleRule": "generateAggregates = true"
+        },
+        {
+            "name": "openaiApiKey",
+            "type": "string",
+            "label": "OpenAI API Key",
+            "required": false,
+            "helpMarkDown": "OpenAI API key for AI Insights generation. Use $(OPENAI_API_KEY) from a variable group. Required when enableInsights is true.",
+            "visibleRule": "enableInsights = true"
         }
     ],
     "execution": {

{ado_git_repo_insights-3.2.0 → ado_git_repo_insights-3.3.0}/extension/tests/production-issues.test.js

@@ -804,21 +804,22 @@ describe('Regression Prevention', () => {
 
 describe('Phase 5 Feature Flag (Predictions & AI Insights)', () => {
     /**
-     * Phase 5 features (Predictions, AI Insights) are not yet production-ready.
-     * They require additional setup:
+     * Phase 5 features (Predictions, AI Insights) are now enabled.
+     * The tabs are visible by default and show "Coming Soon" state
+     * until the backend generates predictions/insights data.
+     *
+     * Full functionality requires additional setup:
      * - Prophet library for forecasting
      * - OpenAI API key for AI insights
-     * - Pipeline task inputs not yet exposed
-     *
-     * Until ready, the tabs should show "Coming Soon" state.
+     * - Pipeline task inputs (enablePredictions, enableInsights)
      */
 
     describe('Feature flag behavior', () => {
-        it('ENABLE_PHASE5_FEATURES should be false by default', () => {
-            // This documents the expected default state
-            // When Phase 5 is ready, this test should be updated
-            const ENABLE_PHASE5_FEATURES = false;
-            expect(ENABLE_PHASE5_FEATURES).toBe(false);
+        it('ENABLE_PHASE5_FEATURES should be true (Phase 5 enabled)', () => {
+            // Phase 5 features are now enabled by default
+            // Tabs are visible and show "Coming Soon" until data is available
+            const ENABLE_PHASE5_FEATURES = true;
+            expect(ENABLE_PHASE5_FEATURES).toBe(true);
         });
 
         it('Phase 5 tabs should be hidden when feature flag is false', () => {

{ado_git_repo_insights-3.2.0 → ado_git_repo_insights-3.3.0}/extension/ui/dashboard.js

@@ -31,7 +31,7 @@ const SETTINGS_KEY_PIPELINE = 'pr-insights-pipeline-id';
 // - OpenAI API key for AI insights
 // - Pipeline task inputs (enablePredictions, enableInsights) not yet exposed
 // Set to true when Phase 5 is production-ready
-const ENABLE_PHASE5_FEATURES = false;
+const ENABLE_PHASE5_FEATURES = true;
 
 // DOM element cache
 const elements = {};

{ado_git_repo_insights-3.2.0 → ado_git_repo_insights-3.3.0}/extension/vss-extension.json

@@ -2,7 +2,7 @@
     "manifestVersion": 1,
     "id": "ado-git-repo-insights",
     "name": "Git Repo Insights",
-    "version": "3.2.0",
+    "version": "3.3.0",
     "publisher": "OddEssentials",
     "targets": [
         {

{ado_git_repo_insights-3.2.0 → ado_git_repo_insights-3.3.0}/package-lock.json

@@ -1,12 +1,12 @@
 {
     "name": "ado-git-repo-insights-release",
-    "version": "3.2.0",
+    "version": "3.3.0",
     "lockfileVersion": 3,
     "requires": true,
     "packages": {
         "": {
             "name": "ado-git-repo-insights-release",
-            "version": "3.2.0",
+            "version": "3.3.0",
             "devDependencies": {
                 "@semantic-release/changelog": "^6.0.3",
                 "@semantic-release/commit-analyzer": "^13.0.0",

{ado_git_repo_insights-3.2.0 → ado_git_repo_insights-3.3.0}/package.json

@@ -11,7 +11,7 @@
     "husky": "^9.1.7",
     "semantic-release": "^24.0.0"
   },
-  "version": "3.2.0",
+  "version": "3.3.0",
   "scripts": {
     "prepare": "husky"
   }

{ado_git_repo_insights-3.2.0 → ado_git_repo_insights-3.3.0}/src/ado_git_repo_insights.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ado-git-repo-insights
-Version: 3.2.0
+Version: 3.3.0
 Summary: Extract Azure DevOps Pull Request metrics to SQLite and generate PowerBI-compatible CSVs.
 Author-email: "Odd Essentials, LLC" <admin@oddessentials.com>
 License: MIT

{ado_git_repo_insights-3.2.0 → ado_git_repo_insights-3.3.0}/src/ado_git_repo_insights.egg-info/SOURCES.txt

@@ -5,7 +5,6 @@
 .pre-commit-config.yaml
 .releaserc.json
 CHANGELOG.md
-DEFERRED-PHASE5.md
 LICENSE
 MERMAID.md
 README.md
@@ -28,6 +27,7 @@ agents/INVARIANTS.md
 agents/definition-of-done.md
 agents/victory-gates.md
 docs/DEFAULT-DASHBOARD-ENHANCEMENT-PLAN.md
+docs/ENABLE-ML-FEATURES.md
 docs/EXTENSION.md
 docs/INSTALLATION.md
 docs/MANUAL_WALKTHROUGH.md
@@ -135,6 +135,7 @@ tests/integration/test_db_open_failure.py
 tests/integration/test_golden_outputs.py
 tests/integration/test_incremental_run.py
 tests/integration/test_multi_project_scoping.py
+tests/integration/test_phase5_ml_integration.py
 tests/unit/__init__.py
 tests/unit/test_ado_client_pagination.py
 tests/unit/test_aggregators.py