Intial commit for HF deployment

.gitignore

@@ -0,0 +1,36 @@
+.env
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+.pytest_cache/
+.coverage
+.hypothesis/
+*.log
+.venv
+venv/
+ENV/
+env/
+*.db
+*.sqlite
+*.sqlite3
+.DS_Store
+.vscode/
+.idea/

DEPLOYMENT.md

@@ -0,0 +1,148 @@
+# Deploying to Hugging Face Spaces
+
+This guide will help you deploy your FastAPI application to Hugging Face Spaces.
+
+## Prerequisites
+
+1. A Hugging Face account (sign up at https://huggingface.co/)
+2. Git installed on your system
+3. Your Jira API credentials
+
+## Deployment Steps
+
+### Step 1: Create a New Space
+
+1. Go to https://huggingface.co/new-space
+2. Fill in the details:
+   - **Space name**: Choose a name (e.g., `enterprise-intelligence-api`)
+   - **License**: MIT (or your preferred license)
+   - **Select SDK**: Choose **Docker**
+   - **Space hardware**: Select the free tier or upgrade if needed
+3. Click "Create Space"
+
+### Step 2: Push Your Code to Hugging Face
+
+1. **Initialize Git** (if not already done):
+   ```bash
+   git init
+   git add .
+   git commit -m "Initial commit for HF deployment"
+   ```
+
+2. **Add Hugging Face Space as remote**:
+   ```bash
+   git remote add hf https://huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE_NAME
+   ```
+   Replace `YOUR_USERNAME` and `YOUR_SPACE_NAME` with your actual values.
+
+3. **Push to Hugging Face**:
+   ```bash
+   git push hf main
+   ```
+   If you're on a different branch, use:
+   ```bash
+   git push hf master:main
+   ```
+
+### Step 3: Configure Environment Variables (Secrets)
+
+Your API needs environment variables (like Jira credentials). To add them:
+
+1. Go to your Space settings: `https://huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE_NAME/settings`
+2. Scroll down to **Repository secrets**
+3. Add the following secrets one by one:
+   - `JIRA_URL`: Your Jira instance URL (e.g., `https://yourcompany.atlassian.net`)
+   - `JIRA_EMAIL`: Your Jira email
+   - `JIRA_API_TOKEN`: Your Jira API token
+   - `DEBUG`: Set to `false`
+   - `ENVIRONMENT`: Set to `production`
+   - Any other secrets from your `.env.example` file
+
+4. Click "Add secret" for each one
+
+### Step 4: Wait for Build
+
+1. Hugging Face will automatically build your Docker container
+2. Check the **Logs** tab to monitor the build process
+3. Once complete, your API will be available at:
+   ```
+   https://YOUR_USERNAME-YOUR_SPACE_NAME.hf.space
+   ```
+
+### Step 5: Test Your Deployment
+
+1. Visit your Space URL
+2. Add `/docs` to access the FastAPI Swagger documentation:
+   ```
+   https://YOUR_USERNAME-YOUR_SPACE_NAME.hf.space/docs
+   ```
+3. Test the endpoints to ensure everything works
+
+## Important Notes
+
+### Free Tier Limitations
+- The free tier may have limited resources
+- The app might go to sleep after inactivity
+- Consider upgrading to a paid tier for production workloads
+
+### Environment Variables via Dockerfile (Alternative)
+If you don't want to use secrets (not recommended for sensitive data), you can set default values in the Dockerfile:
+```dockerfile
+ENV JIRA_URL=https://example.atlassian.net
+ENV DEBUG=false
+```
+
+### Updating Your Deployment
+To update your deployed app:
+```bash
+git add .
+git commit -m "Update: description of changes"
+git push hf main
+```
+
+Hugging Face will automatically rebuild and redeploy.
+
+## Troubleshooting
+
+### Build Fails
+- Check the **Logs** tab in your Space
+- Ensure all dependencies in `requirements.txt` are compatible
+- Make sure the Dockerfile syntax is correct
+
+### App Crashes on Startup
+- Check if all required environment variables are set in Secrets
+- Review the application logs in the Space's Logs tab
+- Ensure the port is 7860 (required by HF Spaces)
+
+### Can't Access the API
+- Verify the Space is "Running" (not "Sleeping" or "Building")
+- Check the URL is correct: `https://YOUR_USERNAME-YOUR_SPACE_NAME.hf.space`
+- Free tier spaces may take a moment to wake up
+
+## Quick Reference Commands
+
+```bash
+# Clone your existing Space
+git clone https://huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE_NAME
+
+# Add changes
+git add .
+git commit -m "Your message"
+git push
+
+# Force push (use carefully)
+git push --force
+```
+
+## Resources
+
+- [Hugging Face Spaces Documentation](https://huggingface.co/docs/hub/spaces)
+- [Docker Spaces Guide](https://huggingface.co/docs/hub/spaces-sdks-docker)
+- [FastAPI Documentation](https://fastapi.tiangolo.com/)
+
+## Support
+
+If you encounter issues:
+1. Check Hugging Face Spaces documentation
+2. Review the build logs in your Space
+3. Visit Hugging Face forums or Discord for community support

Dockerfile

@@ -0,0 +1,26 @@
+# Use Python 3.11 slim image
+FROM python:3.11-slim
+
+# Set working directory
+WORKDIR /app
+
+# Install system dependencies
+RUN apt-get update && apt-get install -y \
+    gcc \
+    && rm -rf /var/lib/apt/lists/*
+
+# Copy requirements first for better caching
+COPY requirements.txt .
+
+# Install Python dependencies
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Copy the entire application
+COPY . .
+
+# Expose port 7860 (Hugging Face Spaces default)
+EXPOSE 7860
+
+# Command to run the application
+# Hugging Face Spaces expects the app to run on 0.0.0.0:7860
+CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "7860"]

README.md

@@ -0,0 +1,378 @@
+---
+title: Enterprise Delivery & Workforce Intelligence API
+emoji: 🚀
+colorFrom: blue
+colorTo: purple
+sdk: docker
+pinned: false
+license: mit
+---
+
+# Enterprise Delivery & Workforce Intelligence API
+
+## Overview
+AI-powered enterprise intelligence system that converts raw engineering activity from Jira (and GitHub) into meaningful business-level insights. 
+
+## Features
+
+### 📊 Data Integration
+- **Jira Integration**: Fetch issues, sprints, worklogs, team members, and project data
+- **GitHub Integration**: (Coming soon - handled by frontend team)
+
+### 🧠 Intelligence & Analytics
+- **Delivery Health Metrics**: Track velocity, completion rates, cycle time, and sprint health
+- **Productivity Metrics**: Monitor individual and team productivity, utilization, and efficiency
+- **Cost Efficiency Analysis**: Calculate cost per feature, story point, and identify waste
+- **Risk Alerts**: Automated detection of delivery delays, resource issues, and cost overruns
+- **AI Insights**: Generate actionable recommendations based on engineering data
+
+### 🎯 Business Impact
+- Predict delivery delays early
+- Optimize workforce allocation
+- Identify cost inefficiencies
+- Data-driven decision making for engineering leaders
+
+## Project Structure
+
+```
+backend/
+├── api/                      # FastAPI route handlers
+│   ├── jira_routes.py       # Jira data endpoints
+│   ├── intelligence_routes.py # Intelligence & metrics endpoints
+│   └── __init__.py
+├── config/                  # Configuration management
+│   ├── settings.py         # Environment settings
+│   └── __init__.py
+├── integrations/           # External API integrations
+│   ├── jira_service.py    # Jira API client
+│   └── __init__.py
+├── models/                 # Data models (Pydantic)
+│   ├── jira_models.py     # Jira domain models
+│   ├── intelligence_models.py # Intelligence metrics models
+│   └── __init__.py
+├── services/              # Business logic
+│   ├── intelligence_service.py # Analytics & insights generation
+│   └── __init__.py
+├── main.py               # FastAPI application entry point
+├── requirements.txt      # Python dependencies
+├── .env.example         # Environment variables template
+└── README.md           # This file
+```
+
+## Setup Instructions
+
+### Prerequisites
+- Python 3.9+
+- Jira account with API access
+- Jira API token ([Get it here](https://id.atlassian.com/manage-profile/security/api-tokens))
+
+### Installation
+
+1. **Clone the repository** (if not already done)
+   ```bash
+   cd d:\Datathon\backend
+   ```
+
+2. **Create virtual environment**
+   ```bash
+   python -m venv venv
+   venv\Scripts\activate  # On Windows
+   # source venv/bin/activate  # On Linux/Mac
+   ```
+
+3. **Install dependencies**
+   ```bash
+   pip install -r requirements.txt
+   ```
+
+4. **Configure environment variables**
+   ```bash
+   copy .env.example .env
+   ```
+   
+   Edit `.env` with your credentials:
+   ```env
+   JIRA_SERVER_URL=https://your-domain.atlassian.net
+   JIRA_EMAIL=your-email@example.com
+   JIRA_API_TOKEN=your_jira_api_token
+   SECRET_KEY=your-secret-key-here
+   ```
+
+5. **Run the application**
+   ```bash
+   python main.py
+   ```
+   
+   Or using uvicorn directly:
+   ```bash
+   uvicorn main:app --reload --host 0.0.0.0 --port 8000
+   ```
+
+6. **Access the API**
+   - API: http://localhost:8000
+   - Interactive docs: http://localhost:8000/docs
+   - Alternative docs: http://localhost:8000/redoc
+
+## API Endpoints
+
+### Jira Data Endpoints
+
+#### Get All Projects
+```http
+GET /jira/projects
+```
+
+#### Get Project Issues
+```http
+GET /jira/projects/{project_key}/issues?start_date=2026-01-01&end_date=2026-02-07&max_results=100
+```
+
+#### Get Boards
+```http
+GET /jira/boards
+```
+
+#### Get Sprints for Board
+```http
+GET /jira/boards/{board_id}/sprints
+```
+
+#### Get Active Sprint
+```http
+GET /jira/boards/{board_id}/active-sprint
+```
+
+#### Get Sprint Issues
+```http
+GET /jira/sprints/{sprint_id}/issues
+```
+
+#### Get Team Members
+```http
+GET /jira/projects/{project_key}/team-members
+```
+
+#### Get Worklogs
+```http
+GET /jira/projects/{project_key}/worklogs?start_date=2026-01-01&end_date=2026-02-07
+```
+
+### Intelligence Endpoints
+
+#### Get Delivery Health Metrics
+```http
+GET /intelligence/delivery-health/{project_key}?start_date=2026-01-01&end_date=2026-02-07
+GET /intelligence/delivery-health/{project_key}?board_id=1&sprint_id=10
+```
+
+**Response:**
+```json
+{
+  "sprint_name": "Sprint 1",
+  "period_start": "2026-01-01",
+  "period_end": "2026-02-07",
+  "completed_story_points": 45.0,
+  "velocity": 45.0,
+  "completion_rate": 85.5,
+  "avg_cycle_time_hours": 12.5,
+  "health_score": 82.3,
+  "blocked_issues_count": 2
+}
+```
+
+#### Get Productivity Metrics
+```http
+GET /intelligence/productivity/{project_key}?start_date=2026-01-01&end_date=2026-02-07
+```
+
+**Response:**
+```json
+[
+  {
+    "team_member_name": "John Doe",
+    "issues_completed": 8,
+    "story_points_completed": 21.0,
+    "total_hours_logged": 80.0,
+    "productivity_score": 78.5,
+    "utilization_rate": 90.0
+  }
+]
+```
+
+#### Get Cost Efficiency Metrics
+```http
+GET /intelligence/cost-efficiency/{project_key}?start_date=2026-01-01&avg_hourly_rate=75
+```
+
+**Response:**
+```json
+{
+  "total_hours_logged": 320.0,
+  "estimated_cost": 24000.0,
+  "features_delivered": 15,
+  "cost_per_feature": 1600.0,
+  "cost_per_story_point": 533.33,
+  "waste_percentage": 8.5
+}
+```
+
+#### Get Risk Alerts
+```http
+GET /intelligence/risk-alerts/{project_key}?start_date=2026-01-01
+```
+
+**Response:**
+```json
+[
+  {
+    "alert_type": "delivery_delay",
+    "severity": "high",
+    "title": "Low Completion Rate",
+    "description": "Only 45.0% of planned work is completed.",
+    "suggested_action": "Reduce scope or extend timeline to meet commitments."
+  }
+]
+```
+
+#### Get AI Insights
+```http
+GET /intelligence/insights/{project_key}?start_date=2026-01-01
+```
+
+**Response:**
+```json
+[
+  {
+    "category": "delivery",
+    "title": "Velocity Analysis",
+    "description": "Team completed 45.0 story points with 85.5% completion rate.",
+    "confidence_score": 0.85,
+    "impact_level": "medium",
+    "recommendations": [
+      "Maintain current sprint planning strategy",
+      "Consider increasing capacity for higher throughput"
+    ]
+  }
+]
+```
+
+#### Get Complete Dashboard
+```http
+GET /intelligence/dashboard/{project_key}?start_date=2026-01-01&end_date=2026-02-07
+```
+
+**Response includes all metrics:**
+- Delivery health
+- Productivity metrics for all team members
+- Cost efficiency
+- Risk alerts
+- AI insights
+
+## Usage Examples
+
+### Example 1: Monitor Sprint Health
+```python
+import requests
+
+# Get active sprint
+response = requests.get(
+    "http://localhost:8000/jira/boards/1/active-sprint"
+)
+sprint = response.json()
+
+# Get delivery health for that sprint
+response = requests.get(
+    f"http://localhost:8000/intelligence/delivery-health/PROJ",
+    params={
+        "board_id": 1,
+        "sprint_id": sprint["sprint_id"]
+    }
+)
+health = response.json()
+print(f"Sprint Health Score: {health['health_score']}/100")
+```
+
+### Example 2: Team Productivity Report
+```python
+import requests
+
+response = requests.get(
+    "http://localhost:8000/intelligence/productivity/PROJ",
+    params={
+        "start_date": "2026-01-01",
+        "end_date": "2026-02-07"
+    }
+)
+
+for member in response.json():
+    print(f"{member['team_member_name']}: {member['productivity_score']}/100")
+```
+
+### Example 3: Cost Analysis
+```python
+import requests
+
+response = requests.get(
+    "http://localhost:8000/intelligence/cost-efficiency/PROJ",
+    params={
+        "start_date": "2026-01-01",
+        "avg_hourly_rate": 80
+    }
+)
+
+cost = response.json()
+print(f"Cost per Story Point: ${cost['cost_per_story_point']:.2f}")
+print(f"Waste: {cost['waste_percentage']:.1f}%")
+```
+
+## Integration with Frontend
+
+The frontend team working on GitHub integration can consume these endpoints:
+
+1. **Dashboard View**: Use `/intelligence/dashboard/{project_key}` for comprehensive data
+2. **Real-time Alerts**: Poll `/intelligence/risk-alerts/{project_key}` for updates
+3. **Team Performance**: Display `/intelligence/productivity/{project_key}` data
+
+## Future Enhancements
+
+- [ ] GitHub integration for code metrics
+- [ ] Real-time websocket updates
+- [ ] Historical trend analysis
+- [ ] Machine learning predictions
+- [ ] Custom metric definitions
+- [ ] Team capacity planning
+- [ ] Automated reporting
+
+## Troubleshooting
+
+### Common Issues
+
+**401 Unauthorized Error**
+- Check Jira API token is valid
+- Verify email and server URL in `.env`
+
+**No data returned**
+- Ensure project key is correct
+- Check date ranges are valid
+- Verify you have access to the Jira project
+
+**Import errors**
+- Activate virtual environment
+- Run `pip install -r requirements.txt`
+
+## Contributing
+
+This is an MVP for a datathon. Focus areas:
+1. Jira data accuracy
+2. Intelligence algorithm improvements
+3. API performance optimization
+
+## License
+
+MIT License - Datathon 2026
+
+---
+
+**Built for**: AI-Driven Enterprise Delivery & Workforce Intelligence
+**Team**: Backend (Jira) + Frontend (GitHub)
+**Date**: February 2026

api/__init__.py

@@ -0,0 +1,4 @@
+from .jira_routes import router as jira_router
+from .intelligence_routes import router as intelligence_router
+
+__all__ = ["jira_router", "intelligence_router"]

api/intelligence_routes.py

@@ -0,0 +1,660 @@
+from fastapi import APIRouter, HTTPException, Query
+from typing import List, Optional
+from datetime import datetime, timedelta, date
+from integrations.jira_service import jira_service
+from services.intelligence_service import intelligence_service
+from models.intelligence_models import (
+    DeliveryHealthMetrics,
+    ProductivityMetrics,
+    CostEfficiencyMetrics,
+    TeamCapacityMetrics,
+    RiskAlert,
+    InsightRecommendation,
+    KanbanFlowMetrics,
+    KanbanColumnAnalysis,
+    WIPLimitRecommendation
+)
+import logging
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(prefix="/intelligence", tags=["Intelligence"])
+
+
+@router.get("/delivery-health/{project_key}", response_model=DeliveryHealthMetrics)
+async def get_delivery_health(
+    project_key: str,
+    board_id: Optional[int] = None,
+    sprint_id: Optional[int] = None,
+    start_date: Optional[str] = None,
+    end_date: Optional[str] = None
+):
+    """Get delivery health metrics for a project or sprint"""
+    try:
+        # Parse dates
+        start_dt = date.fromisoformat(start_date) if start_date else None
+        end_dt = date.fromisoformat(end_date) if end_date else None
+        
+        # Get sprint if specified
+        sprint = None
+        if sprint_id:
+            issues = jira_service.get_sprint_issues(sprint_id)
+            if board_id:
+                sprints = jira_service.get_sprints(board_id)
+                sprint = next((s for s in sprints if s.sprint_id == sprint_id), None)
+        else:
+            # Get all issues for the project
+            issues = jira_service.get_issues_by_project(
+                project_key=project_key,
+                max_results=1000,
+                start_date=datetime.combine(start_dt, datetime.min.time()) if start_dt else None,
+                end_date=datetime.combine(end_dt, datetime.max.time()) if end_dt else None
+            )
+        
+        return intelligence_service.calculate_delivery_health(
+            issues=issues,
+            sprint=sprint,
+            period_start=start_dt,
+            period_end=end_dt
+        )
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=f"Invalid date format: {str(e)}")
+    except Exception as e:
+        logger.error(f"Error calculating delivery health: {str(e)}")
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@router.get("/productivity/{project_key}", response_model=List[ProductivityMetrics])
+async def get_productivity_metrics(
+    project_key: str,
+    start_date: Optional[str] = None,
+    end_date: Optional[str] = None
+):
+    """Get productivity metrics for all team members in a project"""
+    try:
+        # Parse dates
+        start_dt = date.fromisoformat(start_date) if start_date else (date.today() - timedelta(days=14))
+        end_dt = date.fromisoformat(end_date) if end_date else date.today()
+        
+        # Get data
+        issues = jira_service.get_issues_by_project(
+            project_key=project_key,
+            max_results=1000,
+            start_date=datetime.combine(start_dt, datetime.min.time()),
+            end_date=datetime.combine(end_dt, datetime.max.time())
+        )
+        
+        worklogs = jira_service.get_worklogs(
+            project_key=project_key,
+            start_date=datetime.combine(start_dt, datetime.min.time()),
+            end_date=datetime.combine(end_dt, datetime.max.time())
+        )
+        
+        team_members = jira_service.get_team_members(project_key)
+        
+        # Calculate metrics for each team member
+        metrics = []
+        for member in team_members:
+            metric = intelligence_service.calculate_productivity_metrics(
+                issues=issues,
+                worklogs=worklogs,
+                team_member_id=member.account_id,
+                team_member_name=member.display_name,
+                period_start=start_dt,
+                period_end=end_dt
+            )
+            metrics.append(metric)
+        
+        return metrics
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=f"Invalid date format: {str(e)}")
+    except Exception as e:
+        logger.error(f"Error calculating productivity metrics: {str(e)}")
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@router.get("/cost-efficiency/{project_key}", response_model=CostEfficiencyMetrics)
+async def get_cost_efficiency(
+    project_key: str,
+    start_date: Optional[str] = None,
+    end_date: Optional[str] = None,
+    avg_hourly_rate: float = Query(75.0, gt=0)
+):
+    """Get cost efficiency metrics for a project"""
+    try:
+        # Parse dates
+        start_dt = date.fromisoformat(start_date) if start_date else (date.today() - timedelta(days=14))
+        end_dt = date.fromisoformat(end_date) if end_date else date.today()
+        
+        # Get data
+        issues = jira_service.get_issues_by_project(
+            project_key=project_key,
+            max_results=1000,
+            start_date=datetime.combine(start_dt, datetime.min.time()),
+            end_date=datetime.combine(end_dt, datetime.max.time())
+        )
+        
+        worklogs = jira_service.get_worklogs(
+            project_key=project_key,
+            start_date=datetime.combine(start_dt, datetime.min.time()),
+            end_date=datetime.combine(end_dt, datetime.max.time())
+        )
+        
+        return intelligence_service.calculate_cost_efficiency(
+            issues=issues,
+            worklogs=worklogs,
+            period_start=start_dt,
+            period_end=end_dt,
+            avg_hourly_rate=avg_hourly_rate
+        )
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=f"Invalid date format: {str(e)}")
+    except Exception as e:
+        logger.error(f"Error calculating cost efficiency: {str(e)}")
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@router.get("/risk-alerts/{project_key}", response_model=List[RiskAlert])
+async def get_risk_alerts(
+    project_key: str,
+    board_id: Optional[int] = None,
+    sprint_id: Optional[int] = None,
+    start_date: Optional[str] = None,
+    end_date: Optional[str] = None
+):
+    """Get risk alerts for a project"""
+    try:
+        # Parse dates
+        start_dt = date.fromisoformat(start_date) if start_date else (date.today() - timedelta(days=14))
+        end_dt = date.fromisoformat(end_date) if end_date else date.today()
+        
+        # Get all metrics
+        sprint = None
+        if sprint_id and board_id:
+            issues = jira_service.get_sprint_issues(sprint_id)
+            sprints = jira_service.get_sprints(board_id)
+            sprint = next((s for s in sprints if s.sprint_id == sprint_id), None)
+        else:
+            issues = jira_service.get_issues_by_project(
+                project_key=project_key,
+                max_results=1000,
+                start_date=datetime.combine(start_dt, datetime.min.time()),
+                end_date=datetime.combine(end_dt, datetime.max.time())
+            )
+        
+        worklogs = jira_service.get_worklogs(
+            project_key=project_key,
+            start_date=datetime.combine(start_dt, datetime.min.time()),
+            end_date=datetime.combine(end_dt, datetime.max.time())
+        )
+        
+        team_members = jira_service.get_team_members(project_key)
+        
+        # Calculate metrics
+        delivery_health = intelligence_service.calculate_delivery_health(
+            issues=issues,
+            sprint=sprint,
+            period_start=start_dt,
+            period_end=end_dt
+        )
+        
+        productivity_metrics = [
+            intelligence_service.calculate_productivity_metrics(
+                issues=issues,
+                worklogs=worklogs,
+                team_member_id=member.account_id,
+                team_member_name=member.display_name,
+                period_start=start_dt,
+                period_end=end_dt
+            )
+            for member in team_members
+        ]
+        
+        cost_metrics = intelligence_service.calculate_cost_efficiency(
+            issues=issues,
+            worklogs=worklogs,
+            period_start=start_dt,
+            period_end=end_dt
+        )
+        
+        # Generate alerts
+        return intelligence_service.generate_risk_alerts(
+            delivery_health=delivery_health,
+            productivity_metrics=productivity_metrics,
+            cost_metrics=cost_metrics
+        )
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=f"Invalid date format: {str(e)}")
+    except Exception as e:
+        logger.error(f"Error generating risk alerts: {str(e)}")
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@router.get("/insights/{project_key}", response_model=List[InsightRecommendation])
+async def get_insights(
+    project_key: str,
+    board_id: Optional[int] = None,
+    sprint_id: Optional[int] = None,
+    start_date: Optional[str] = None,
+    end_date: Optional[str] = None
+):
+    """Get AI-generated insights and recommendations"""
+    try:
+        # Parse dates
+        start_dt = date.fromisoformat(start_date) if start_date else (date.today() - timedelta(days=14))
+        end_dt = date.fromisoformat(end_date) if end_date else date.today()
+        
+        # Get all metrics (same as risk alerts)
+        sprint = None
+        if sprint_id and board_id:
+            issues = jira_service.get_sprint_issues(sprint_id)
+            sprints = jira_service.get_sprints(board_id)
+            sprint = next((s for s in sprints if s.sprint_id == sprint_id), None)
+        else:
+            issues = jira_service.get_issues_by_project(
+                project_key=project_key,
+                max_results=1000,
+                start_date=datetime.combine(start_dt, datetime.min.time()),
+                end_date=datetime.combine(end_dt, datetime.max.time())
+            )
+        
+        worklogs = jira_service.get_worklogs(
+            project_key=project_key,
+            start_date=datetime.combine(start_dt, datetime.min.time()),
+            end_date=datetime.combine(end_dt, datetime.max.time())
+        )
+        
+        team_members = jira_service.get_team_members(project_key)
+        
+        # Calculate metrics
+        delivery_health = intelligence_service.calculate_delivery_health(
+            issues=issues,
+            sprint=sprint,
+            period_start=start_dt,
+            period_end=end_dt
+        )
+        
+        productivity_metrics = [
+            intelligence_service.calculate_productivity_metrics(
+                issues=issues,
+                worklogs=worklogs,
+                team_member_id=member.account_id,
+                team_member_name=member.display_name,
+                period_start=start_dt,
+                period_end=end_dt
+            )
+            for member in team_members
+        ]
+        
+        cost_metrics = intelligence_service.calculate_cost_efficiency(
+            issues=issues,
+            worklogs=worklogs,
+            period_start=start_dt,
+            period_end=end_dt
+        )
+        
+        # Generate insights
+        return intelligence_service.generate_insights(
+            delivery_health=delivery_health,
+            productivity_metrics=productivity_metrics,
+            cost_metrics=cost_metrics
+        )
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=f"Invalid date format: {str(e)}")
+    except Exception as e:
+        logger.error(f"Error generating insights: {str(e)}")
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@router.get("/dashboard/{project_key}")
+async def get_dashboard_data(
+    project_key: str,
+    board_id: Optional[int] = None,
+    sprint_id: Optional[int] = None,
+    start_date: Optional[str] = None,
+    end_date: Optional[str] = None
+):
+    """Get comprehensive dashboard data including all metrics"""
+    try:
+        # Parse dates
+        start_dt = date.fromisoformat(start_date) if start_date else (date.today() - timedelta(days=14))
+        end_dt = date.fromisoformat(end_date) if end_date else date.today()
+        
+        # Get all data
+        sprint = None
+        if sprint_id and board_id:
+            issues = jira_service.get_sprint_issues(sprint_id)
+            sprints = jira_service.get_sprints(board_id)
+            sprint = next((s for s in sprints if s.sprint_id == sprint_id), None)
+        else:
+            issues = jira_service.get_issues_by_project(
+                project_key=project_key,
+                max_results=1000,
+                start_date=datetime.combine(start_dt, datetime.min.time()),
+                end_date=datetime.combine(end_dt, datetime.max.time())
+            )
+        
+        worklogs = jira_service.get_worklogs(
+            project_key=project_key,
+            start_date=datetime.combine(start_dt, datetime.min.time()),
+            end_date=datetime.combine(end_dt, datetime.max.time())
+        )
+        
+        team_members = jira_service.get_team_members(project_key)
+        
+        # Calculate all metrics
+        delivery_health = intelligence_service.calculate_delivery_health(
+            issues=issues,
+            sprint=sprint,
+            period_start=start_dt,
+            period_end=end_dt
+        )
+        
+        productivity_metrics = [
+            intelligence_service.calculate_productivity_metrics(
+                issues=issues,
+                worklogs=worklogs,
+                team_member_id=member.account_id,
+                team_member_name=member.display_name,
+                period_start=start_dt,
+                period_end=end_dt
+            )
+            for member in team_members
+        ]
+        
+        cost_metrics = intelligence_service.calculate_cost_efficiency(
+            issues=issues,
+            worklogs=worklogs,
+            period_start=start_dt,
+            period_end=end_dt
+        )
+        
+        risk_alerts = intelligence_service.generate_risk_alerts(
+            delivery_health=delivery_health,
+            productivity_metrics=productivity_metrics,
+            cost_metrics=cost_metrics
+        )
+        
+        insights = intelligence_service.generate_insights(
+            delivery_health=delivery_health,
+            productivity_metrics=productivity_metrics,
+            cost_metrics=cost_metrics
+        )
+        
+        return {
+            "delivery_health": delivery_health,
+            "productivity_metrics": productivity_metrics,
+            "cost_efficiency": cost_metrics,
+            "risk_alerts": risk_alerts,
+            "insights": insights,
+            "period": {
+                "start": start_dt,
+                "end": end_dt
+            }
+        }
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=f"Invalid date format: {str(e)}")
+    except Exception as e:
+        logger.error(f"Error generating dashboard data: {str(e)}")
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+# ===== KANBAN INTELLIGENCE ENDPOINTS =====
+
+@router.get("/kanban/flow-metrics/{board_id}", response_model=KanbanFlowMetrics)
+async def get_kanban_flow_metrics(
+    board_id: int,
+    start_date: Optional[str] = None,
+    end_date: Optional[str] = None
+):
+    """Get Kanban flow efficiency metrics for a board"""
+    try:
+        # Parse dates
+        start_dt = date.fromisoformat(start_date) if start_date else (date.today() - timedelta(days=30))
+        end_dt = date.fromisoformat(end_date) if end_date else date.today()
+        
+        # Get board info
+        board = jira_service.get_kanban_board_by_id(board_id)
+        if not board:
+            raise HTTPException(status_code=404, detail=f"Kanban board {board_id} not found")
+        
+        # Get issues and columns
+        columns = jira_service.get_kanban_issues_by_column(board_id)
+        
+        # Get all issues for the board
+        all_issues = []
+        for col in columns:
+            all_issues.extend(col.issues)
+        
+        return intelligence_service.calculate_kanban_flow_metrics(
+            board_id=board_id,
+            board_name=board.board_name,
+            issues=all_issues,
+            columns=columns,
+            period_start=start_dt,
+            period_end=end_dt
+        )
+    except HTTPException:
+        raise
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=f"Invalid date format: {str(e)}")
+    except Exception as e:
+        logger.error(f"Error calculating Kanban flow metrics: {str(e)}")
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@router.get("/kanban/column-analysis/{board_id}", response_model=List[KanbanColumnAnalysis])
+async def get_kanban_column_analysis(board_id: int):
+    """Get detailed analysis of each Kanban column"""
+    try:
+        # Get board info
+        board = jira_service.get_kanban_board_by_id(board_id)
+        if not board:
+            raise HTTPException(status_code=404, detail=f"Kanban board {board_id} not found")
+        
+        # Get issues by column
+        columns = jira_service.get_kanban_issues_by_column(board_id)
+        
+        # Get all issues
+        all_issues = []
+        for col in columns:
+            all_issues.extend(col.issues)
+        
+        return intelligence_service.analyze_kanban_columns(
+            columns=columns,
+            issues=all_issues
+        )
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Error analyzing Kanban columns: {str(e)}")
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@router.get("/kanban/wip-recommendations/{board_id}", response_model=List[WIPLimitRecommendation])
+async def get_wip_recommendations(
+    board_id: int,
+    start_date: Optional[str] = None,
+    end_date: Optional[str] = None
+):
+    """Get WIP limit recommendations for Kanban board columns"""
+    try:
+        # Parse dates
+        start_dt = date.fromisoformat(start_date) if start_date else (date.today() - timedelta(days=30))
+        end_dt = date.fromisoformat(end_date) if end_date else date.today()
+        
+        # Get board info
+        board = jira_service.get_kanban_board_by_id(board_id)
+        if not board:
+            raise HTTPException(status_code=404, detail=f"Kanban board {board_id} not found")
+        
+        # Get columns and issues
+        columns = jira_service.get_kanban_issues_by_column(board_id)
+        
+        all_issues = []
+        for col in columns:
+            all_issues.extend(col.issues)
+        
+        # Analyze columns
+        column_analyses = intelligence_service.analyze_kanban_columns(
+            columns=columns,
+            issues=all_issues
+        )
+        
+        # Calculate flow metrics
+        flow_metrics = intelligence_service.calculate_kanban_flow_metrics(
+            board_id=board_id,
+            board_name=board.board_name,
+            issues=all_issues,
+            columns=columns,
+            period_start=start_dt,
+            period_end=end_dt
+        )
+        
+        # Generate recommendations
+        return intelligence_service.generate_wip_recommendations(
+            column_analyses=column_analyses,
+            flow_metrics=flow_metrics
+        )
+    except HTTPException:
+        raise
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=f"Invalid date format: {str(e)}")
+    except Exception as e:
+        logger.error(f"Error generating WIP recommendations: {str(e)}")
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@router.get("/kanban/insights/{board_id}", response_model=List[InsightRecommendation])
+async def get_kanban_insights(
+    board_id: int,
+    start_date: Optional[str] = None,
+    end_date: Optional[str] = None
+):
+    """Get AI-generated insights for Kanban board"""
+    try:
+        # Parse dates
+        start_dt = date.fromisoformat(start_date) if start_date else (date.today() - timedelta(days=30))
+        end_dt = date.fromisoformat(end_date) if end_date else date.today()
+        
+        # Get board info
+        board = jira_service.get_kanban_board_by_id(board_id)
+        if not board:
+            raise HTTPException(status_code=404, detail=f"Kanban board {board_id} not found")
+        
+        # Get columns and issues
+        columns = jira_service.get_kanban_issues_by_column(board_id)
+        
+        all_issues = []
+        for col in columns:
+            all_issues.extend(col.issues)
+        
+        # Calculate all metrics
+        flow_metrics = intelligence_service.calculate_kanban_flow_metrics(
+            board_id=board_id,
+            board_name=board.board_name,
+            issues=all_issues,
+            columns=columns,
+            period_start=start_dt,
+            period_end=end_dt
+        )
+        
+        column_analyses = intelligence_service.analyze_kanban_columns(
+            columns=columns,
+            issues=all_issues
+        )
+        
+        wip_recommendations = intelligence_service.generate_wip_recommendations(
+            column_analyses=column_analyses,
+            flow_metrics=flow_metrics
+        )
+        
+        # Generate insights
+        return intelligence_service.generate_kanban_insights(
+            flow_metrics=flow_metrics,
+            column_analyses=column_analyses,
+            wip_recommendations=wip_recommendations
+        )
+    except HTTPException:
+        raise
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=f"Invalid date format: {str(e)}")
+    except Exception as e:
+        logger.error(f"Error generating Kanban insights: {str(e)}")
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@router.get("/kanban/dashboard/{board_id}")
+async def get_kanban_dashboard(
+    board_id: int,
+    start_date: Optional[str] = None,
+    end_date: Optional[str] = None
+):
+    """Get comprehensive Kanban dashboard data"""
+    try:
+        # Parse dates
+        start_dt = date.fromisoformat(start_date) if start_date else (date.today() - timedelta(days=30))
+        end_dt = date.fromisoformat(end_date) if end_date else date.today()
+        
+        # Get board info
+        board = jira_service.get_kanban_board_by_id(board_id)
+        if not board:
+            raise HTTPException(status_code=404, detail=f"Kanban board {board_id} not found")
+        
+        # Get columns and issues
+        columns = jira_service.get_kanban_issues_by_column(board_id)
+        
+        all_issues = []
+        for col in columns:
+            all_issues.extend(col.issues)
+        
+        # Calculate all metrics
+        flow_metrics = intelligence_service.calculate_kanban_flow_metrics(
+            board_id=board_id,
+            board_name=board.board_name,
+            issues=all_issues,
+            columns=columns,
+            period_start=start_dt,
+            period_end=end_dt
+        )
+        
+        column_analyses = intelligence_service.analyze_kanban_columns(
+            columns=columns,
+            issues=all_issues
+        )
+        
+        wip_recommendations = intelligence_service.generate_wip_recommendations(
+            column_analyses=column_analyses,
+            flow_metrics=flow_metrics
+        )
+        
+        insights = intelligence_service.generate_kanban_insights(
+            flow_metrics=flow_metrics,
+            column_analyses=column_analyses,
+            wip_recommendations=wip_recommendations
+        )
+        
+        return {
+            "board": {
+                "id": board.board_id,
+                "name": board.board_name,
+                "type": board.board_type,
+                "project_key": board.project_key
+            },
+            "flow_metrics": flow_metrics,
+            "column_analyses": column_analyses,
+            "wip_recommendations": wip_recommendations,
+            "insights": insights,
+            "columns_with_issues": columns,
+            "period": {
+                "start": start_dt,
+                "end": end_dt
+            }
+        }
+    except HTTPException:
+        raise
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=f"Invalid date format: {str(e)}")
+    except Exception as e:
+        logger.error(f"Error generating Kanban dashboard: {str(e)}")
+        raise HTTPException(status_code=500, detail=str(e))

api/jira_routes.py

@@ -0,0 +1,240 @@
+from fastapi import APIRouter, HTTPException, Query
+from typing import List, Optional
+from datetime import datetime, timedelta, date
+from integrations.jira_service import jira_service
+from models.jira_models import (
+    JiraIssue,
+    Sprint,
+    TeamMember,
+    WorklogEntry,
+    ProjectInfo,
+    KanbanBoard,
+    KanbanIssuesByColumn,
+    BoardConfiguration
+)
+import logging
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(prefix="/jira", tags=["Jira"])
+
+
+@router.get("/projects", response_model=List[ProjectInfo])
+async def get_projects():
+    """Get all Jira projects"""
+    try:
+        return jira_service.get_projects()
+    except Exception as e:
+        logger.error(f"Error fetching projects: {str(e)}")
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@router.get("/projects/{project_key}/issues", response_model=List[JiraIssue])
+async def get_project_issues(
+    project_key: str,
+    max_results: int = Query(100, ge=1, le=1000),
+    start_date: Optional[str] = None,
+    end_date: Optional[str] = None
+):
+    """Get issues for a specific project"""
+    try:
+        start_dt = datetime.fromisoformat(start_date) if start_date else None
+        end_dt = datetime.fromisoformat(end_date) if end_date else None
+        
+        return jira_service.get_issues_by_project(
+            project_key=project_key,
+            max_results=max_results,
+            start_date=start_dt,
+            end_date=end_dt
+        )
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=f"Invalid date format: {str(e)}")
+    except Exception as e:
+        logger.error(f"Error fetching issues: {str(e)}")
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@router.get("/boards", response_model=List[dict])
+async def get_boards():
+    """Get all Jira boards"""
+    try:
+        return jira_service.get_boards()
+    except Exception as e:
+        logger.error(f"Error fetching boards: {str(e)}")
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@router.get("/boards/{board_id}/sprints", response_model=List[Sprint])
+async def get_board_sprints(board_id: int):
+    """Get sprints for a board"""
+    try:
+        return jira_service.get_sprints(board_id)
+    except Exception as e:
+        logger.error(f"Error fetching sprints: {str(e)}")
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@router.get("/boards/{board_id}/active-sprint", response_model=Optional[Sprint])
+async def get_active_sprint(board_id: int):
+    """Get the currently active sprint for a board"""
+    try:
+        return jira_service.get_active_sprint(board_id)
+    except Exception as e:
+        logger.error(f"Error fetching active sprint: {str(e)}")
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@router.get("/sprints/{sprint_id}/issues", response_model=List[JiraIssue])
+async def get_sprint_issues(sprint_id: int):
+    """Get issues for a specific sprint"""
+    try:
+        return jira_service.get_sprint_issues(sprint_id)
+    except Exception as e:
+        logger.error(f"Error fetching sprint issues: {str(e)}")
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@router.get("/projects/{project_key}/team-members", response_model=List[TeamMember])
+async def get_team_members(project_key: str):
+    """Get team members for a project"""
+    try:
+        return jira_service.get_team_members(project_key)
+    except Exception as e:
+        logger.error(f"Error fetching team members: {str(e)}")
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@router.get("/projects/{project_key}/worklogs", response_model=List[WorklogEntry])
+async def get_worklogs(
+    project_key: str,
+    start_date: Optional[str] = None,
+    end_date: Optional[str] = None
+):
+    """Get worklogs for a project"""
+    try:
+        start_dt = datetime.fromisoformat(start_date) if start_date else None
+        end_dt = datetime.fromisoformat(end_date) if end_date else None
+        
+        return jira_service.get_worklogs(
+            project_key=project_key,
+            start_date=start_dt,
+            end_date=end_dt
+        )
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=f"Invalid date format: {str(e)}")
+    except Exception as e:
+        logger.error(f"Error fetching worklogs: {str(e)}")
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@router.get("/issues/{issue_key}", response_model=JiraIssue)
+async def get_issue(issue_key: str):
+    """Get a specific issue by key"""
+    try:
+        issue = jira_service.get_issue_by_key(issue_key)
+        if not issue:
+            raise HTTPException(status_code=404, detail=f"Issue {issue_key} not found")
+        return issue
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Error fetching issue: {str(e)}")
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+# ===== KANBAN BOARD ENDPOINTS =====
+
+@router.get("/kanban/boards", response_model=List[KanbanBoard])
+async def get_kanban_boards():
+    """Get all Kanban boards with their column configurations"""
+    try:
+        return jira_service.get_kanban_boards()
+    except Exception as e:
+        logger.error(f"Error fetching Kanban boards: {str(e)}")
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@router.get("/kanban/boards/{board_id}", response_model=KanbanBoard)
+async def get_kanban_board(board_id: int):
+    """Get a specific Kanban board by ID"""
+    try:
+        board = jira_service.get_kanban_board_by_id(board_id)
+        if not board:
+            raise HTTPException(
+                status_code=404,
+                detail=f"Kanban board {board_id} not found or is not a Kanban board"
+            )
+        return board
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Error fetching Kanban board: {str(e)}")
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@router.get("/boards/{board_id}/configuration", response_model=BoardConfiguration)
+async def get_board_configuration(board_id: int):
+    """Get detailed board configuration including columns, estimation, and ranking"""
+    try:
+        return jira_service.get_board_configuration(board_id)
+    except Exception as e:
+        logger.error(f"Error fetching board configuration: {str(e)}")
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@router.get("/kanban/boards/{board_id}/issues", response_model=List[KanbanIssuesByColumn])
+async def get_kanban_board_issues(board_id: int):
+    """Get issues for a Kanban board grouped by columns"""
+    try:
+        return jira_service.get_kanban_issues_by_column(board_id)
+    except Exception as e:
+        logger.error(f"Error fetching Kanban board issues: {str(e)}")
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@router.get("/boards/{board_id}/backlog", response_model=List[JiraIssue])
+async def get_board_backlog(
+    board_id: int,
+    max_results: int = Query(100, ge=1, le=500)
+):
+    """Get backlog issues for a board"""
+    try:
+        return jira_service.get_board_backlog(board_id, max_results)
+    except Exception as e:
+        logger.error(f"Error fetching board backlog: {str(e)}")
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@router.post("/issues/{issue_key}/transition")
+async def transition_issue(
+    issue_key: str,
+    transition_name: str = Query(..., description="Name of the transition to execute")
+):
+    """Move an issue to a different status/column via transition"""
+    try:
+        success = jira_service.move_issue_to_status(issue_key, transition_name)
+        if not success:
+            raise HTTPException(
+                status_code=400,
+                detail=f"Transition '{transition_name}' not available for issue {issue_key}"
+            )
+        return {
+            "success": True,
+            "message": f"Issue {issue_key} transitioned to {transition_name}"
+        }
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Error transitioning issue: {str(e)}")
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@router.get("/issues/{issue_key}/transitions", response_model=List[dict])
+async def get_issue_transitions(issue_key: str):
+    """Get available transitions for an issue"""
+    try:
+        return jira_service.get_issue_transitions(issue_key)
+    except Exception as e:
+        logger.error(f"Error fetching issue transitions: {str(e)}")
+        raise HTTPException(status_code=500, detail=str(e))
+

config/__init__.py

@@ -0,0 +1,3 @@
+from .settings import settings
+
+__all__ = ["settings"]

config/settings.py

@@ -0,0 +1,39 @@
+from pydantic_settings import BaseSettings
+from typing import Optional
+
+
+class Settings(BaseSettings):
+    # Mock Data Configuration
+    use_mock_data: bool = False  # Set to True to use mock data instead of real Jira
+    
+    # Jira Configuration
+    jira_server_url: str = "https://mock.atlassian.net"  # Default for mock mode
+    jira_email: str = "mock@example.com"  # Default for mock mode
+    jira_api_token: str = "mock_token"  # Default for mock mode
+    
+    # GitHub Configuration
+    github_token: Optional[str] = None
+    github_org: Optional[str] = None
+    
+    # Database
+    database_url: str = "sqlite:///./enterprise_intelligence.db"
+    
+    # Redis
+    redis_url: str = "redis://localhost:6379/0"
+    
+    # API Configuration
+    api_host: str = "0.0.0.0"
+    api_port: int = 8000
+    debug: bool = True
+    
+    # Security
+    secret_key: str = "mock_secret_key_change_in_production"  # Default for mock mode
+    algorithm: str = "HS256"
+    access_token_expire_minutes: int = 30
+    
+    class Config:
+        env_file = ".env"
+        case_sensitive = False
+
+
+settings = Settings()

integrations/__init__.py

@@ -0,0 +1,3 @@
+from .jira_service import jira_service, JiraIntegrationService
+
+__all__ = ["jira_service", "JiraIntegrationService"]

integrations/jira_service.py

@@ -0,0 +1,947 @@
+from jira import JIRA
+from typing import List, Optional, Dict, Any
+from datetime import datetime, timedelta
+from config.settings import settings
+from models.jira_models import (
+    JiraIssue,
+    Sprint,
+    TeamMember,
+    WorklogEntry,
+    ProjectInfo,
+    KanbanBoard,
+    KanbanColumn,
+    KanbanIssuesByColumn,
+    BoardConfiguration
+)
+import logging
+import requests
+
+logger = logging.getLogger(__name__)
+
+
+class JiraIntegrationService:
+    """Service for integrating with Jira API"""
+    
+    def __init__(self):
+        """Initialize Jira client"""
+        try:
+            # Configure for API v3 (v2 is deprecated as of 2026)
+            options = {
+                'server': settings.jira_server_url,
+                'rest_api_version': '3',  # Use API v3 instead of deprecated v2
+                'agile_rest_api_version': 'latest'
+            }
+            self.jira = JIRA(
+                options=options,
+                basic_auth=(settings.jira_email, settings.jira_api_token)
+            )
+            
+            # Direct API access for new endpoints
+            self.base_url = settings.jira_server_url
+            self.auth = (settings.jira_email, settings.jira_api_token)
+            self.headers = {
+                'Accept': 'application/json',
+                'Content-Type': 'application/json'
+            }
+            
+            logger.info("Jira client initialized successfully with API v3")
+        except Exception as e:
+            logger.error(f"Failed to initialize Jira client: {str(e)}")
+            raise
+    
+    def get_projects(self) -> List[ProjectInfo]:
+        """Fetch all projects"""
+        try:
+            projects = self.jira.projects()
+            return [
+                ProjectInfo(
+                    project_key=proj.key,
+                    project_name=proj.name,
+                    project_type=getattr(proj, 'projectTypeKey', 'unknown'),
+                    lead=getattr(proj.lead, 'displayName', None) if hasattr(proj, 'lead') else None,
+                    description=getattr(proj, 'description', None)
+                )
+                for proj in projects
+            ]
+        except Exception as e:
+            logger.error(f"Error fetching projects: {str(e)}")
+            raise
+    
+    def get_issues_by_project(
+        self,
+        project_key: str,
+        max_results: int = 100,
+        start_date: Optional[datetime] = None,
+        end_date: Optional[datetime] = None
+    ) -> List[JiraIssue]:
+        """Fetch issues for a specific project"""
+        try:
+            jql = f"project = {project_key}"
+            
+            if start_date:
+                jql += f" AND created >= '{start_date.strftime('%Y-%m-%d')}'"
+            if end_date:
+                jql += f" AND created <= '{end_date.strftime('%Y-%m-%d')}'"
+            
+            jql += " ORDER BY created DESC"
+            
+            issues = self._search_jql(
+                jql,
+                max_results=max_results,
+                fields=['summary', 'status', 'priority', 'assignee', 'reporter', 'created',
+                       'updated', 'resolutiondate', 'customfield_10016', 'description',
+                       'labels', 'components', 'issuetype', 'timespent', 'timeestimate']
+            )
+            
+            return [self._parse_issue_dict(issue) for issue in issues]
+        except Exception as e:
+            logger.error(f"Error fetching issues for project {project_key}: {str(e)}")
+            raise
+    
+    def get_sprint_issues(self, sprint_id: int) -> List[JiraIssue]:
+        """Fetch issues for a specific sprint"""
+        try:
+            jql = f"sprint = {sprint_id} ORDER BY created DESC"
+            issues = self._search_jql(
+                jql,
+                max_results=500,
+                fields=['summary', 'status', 'priority', 'assignee', 'reporter', 'created',
+                       'updated', 'resolutiondate', 'customfield_10016', 'description',
+                       'labels', 'components', 'issuetype', 'timespent', 'timeestimate']
+            )
+            
+            return [self._parse_issue_dict(issue) for issue in issues]
+        except Exception as e:
+            logger.error(f"Error fetching sprint issues: {str(e)}")
+            raise
+    
+    def get_sprints(self, board_id: int) -> List[Sprint]:
+        """Fetch sprints for a board"""
+        try:
+            # Use REST API directly
+            url = f"{self.base_url}/rest/agile/latest/board/{board_id}/sprint"
+            
+            response = requests.get(url, headers=self.headers, auth=self.auth)
+            response.raise_for_status()
+            
+            data = response.json()
+            sprints = data.get('values', [])
+            
+            return [
+                Sprint(
+                    sprint_id=sprint.get('id'),
+                    sprint_name=sprint.get('name', ''),
+                    state=sprint.get('state', ''),
+                    start_date=self._parse_datetime(sprint.get('startDate')),
+                    end_date=self._parse_datetime(sprint.get('endDate')),
+                    complete_date=self._parse_datetime(sprint.get('completeDate')),
+                    goal=sprint.get('goal')
+                )
+                for sprint in sprints
+            ]
+        except Exception as e:
+            logger.error(f"Error fetching sprints for board {board_id}: {str(e)}")
+            raise
+    
+    def get_active_sprint(self, board_id: int) -> Optional[Sprint]:
+        """Get the currently active sprint"""
+        try:
+            sprints = self.get_sprints(board_id)
+            active_sprints = [s for s in sprints if s.state == 'active']
+            return active_sprints[0] if active_sprints else None
+        except Exception as e:
+            logger.error(f"Error fetching active sprint: {str(e)}")
+            return None
+    
+    def get_team_members(self, project_key: str) -> List[TeamMember]:
+        """Fetch team members for a project"""
+        try:
+            # Get users who have been assigned issues in the project
+            jql = f"project = {project_key} AND assignee is not EMPTY"
+            issues = self._search_jql(jql, max_results=1000, fields=['assignee'])
+            
+            # Extract unique assignees
+            assignees_dict = {}
+            for issue in issues:
+                assignee = issue.get('fields', {}).get('assignee')
+                if assignee:
+                    account_id = assignee.get('accountId')
+                    if account_id and account_id not in assignees_dict:
+                        # Fetch full user details to get email
+                        user_details = self._get_user_details(account_id)
+                        
+                        assignees_dict[account_id] = TeamMember(
+                            account_id=account_id,
+                            display_name=user_details.get('displayName') or assignee.get('displayName', ''),
+                            email=user_details.get('emailAddress'),
+                            active=user_details.get('active', assignee.get('active', True)),
+                            avatar_url=user_details.get('avatarUrls', {}).get('48x48') or assignee.get('avatarUrls', {}).get('48x48')
+                        )
+            
+            return list(assignees_dict.values())
+        except Exception as e:
+            logger.error(f"Error fetching team members: {str(e)}")
+            raise
+    
+    def _get_user_details(self, account_id: str) -> Dict[str, Any]:
+        """Fetch detailed user information including email"""
+        try:
+            url = f"{self.base_url}/rest/api/3/user"
+            params = {
+                'accountId': account_id,
+                'expand': 'groups,applicationRoles'
+            }
+            
+            response = requests.get(url, headers=self.headers, auth=self.auth, params=params)
+            response.raise_for_status()
+            
+            return response.json()
+        except Exception as e:
+            logger.warning(f"Could not fetch details for user {account_id}: {str(e)}")
+            # Return empty dict if user details can't be fetched
+            return {}
+            raise
+    
+    def get_worklogs(
+        self,
+        project_key: str,
+        start_date: Optional[datetime] = None,
+        end_date: Optional[datetime] = None
+    ) -> List[WorklogEntry]:
+        """Fetch worklogs for a project"""
+        try:
+            jql = f"project = {project_key} AND timespent > 0"
+            
+            if start_date:
+                jql += f" AND updated >= '{start_date.strftime('%Y-%m-%d')}'"
+            if end_date:
+                jql += f" AND updated <= '{end_date.strftime('%Y-%m-%d')}'"
+            
+            issues = self._search_jql(jql, max_results=1000, fields=['key'])
+            
+            worklogs = []
+            for issue in issues:
+                try:
+                    issue_key = issue.get('key')
+                    if not issue_key:
+                        continue
+                    
+                    # Fetch worklogs using direct API
+                    url = f"{self.base_url}/rest/api/3/issue/{issue_key}/worklog"
+                    response = requests.get(url, headers=self.headers, auth=self.auth)
+                    response.raise_for_status()
+                    
+                    worklog_data = response.json()
+                    for worklog in worklog_data.get('worklogs', []):
+                        # Parse datetime before passing to model
+                        started = self._parse_datetime(worklog.get('started'))
+                        worklog['started'] = started
+                        
+                        worklogs.append(
+                            WorklogEntry.from_jira_worklog(worklog, issue_key)
+                        )
+                except Exception as e:
+                    logger.warning(f"Error fetching worklogs for issue {issue.get('key')}: {str(e)}")
+                    continue
+            
+            return worklogs
+        except Exception as e:
+            logger.error(f"Error fetching worklogs: {str(e)}")
+            raise
+    
+    def get_issue_by_key(self, issue_key: str) -> Optional[JiraIssue]:
+        """Fetch a specific issue by key"""
+        try:
+            # Use JQL search instead of direct issue fetch
+            issues = self._search_jql(
+                f"key = {issue_key}",
+                max_results=1,
+                fields=['summary', 'status', 'priority', 'assignee', 'reporter', 'created',
+                       'updated', 'resolutiondate', 'customfield_10016', 'description',
+                       'labels', 'components', 'issuetype', 'timespent', 'timeestimate']
+            )
+            
+            if issues:
+                return self._parse_issue_dict(issues[0])
+            return None
+        except Exception as e:
+            logger.error(f"Error fetching issue {issue_key}: {str(e)}")
+            return None
+    
+    def get_boards(self) -> List[Dict[str, Any]]:
+        """Fetch all boards"""
+        try:
+            # Use REST API directly
+            url = f"{self.base_url}/rest/agile/latest/board"
+            
+            response = requests.get(url, headers=self.headers, auth=self.auth)
+            response.raise_for_status()
+            
+            data = response.json()
+            boards = data.get('values', [])
+            
+            return [
+                {
+                    'id': board.get('id'),
+                    'name': board.get('name', ''),
+                    'type': board.get('type', '')
+                }
+                for board in boards
+            ]
+        except Exception as e:
+            logger.error(f"Error fetching boards: {str(e)}")
+            raise
+    
+    def _parse_issue(self, issue) -> JiraIssue:
+        """Parse Jira issue object to JiraIssue model"""
+        fields = issue.fields
+        
+        # Extract story points (customfield_10016 is common for story points)
+        story_points = None
+        if hasattr(fields, 'customfield_10016'):
+            story_points = fields.customfield_10016
+        
+        # Extract sprint information
+        sprint = None
+        if hasattr(fields, 'customfield_10020'):  # Common sprint field
+            sprint_data = fields.customfield_10020
+            if sprint_data and isinstance(sprint_data, list) and len(sprint_data) > 0:
+                sprint = sprint_data[0].name if hasattr(sprint_data[0], 'name') else str(sprint_data[0])
+        
+        return JiraIssue(
+            issue_key=issue.key,
+            summary=fields.summary,
+            description=getattr(fields, 'description', None),
+            status=fields.status.name,
+            priority=fields.priority.name if fields.priority else None,
+            assignee=fields.assignee.displayName if fields.assignee else None,
+            reporter=fields.reporter.displayName if fields.reporter else None,
+            created=self._parse_datetime(fields.created),
+            updated=self._parse_datetime(fields.updated),
+            resolved=self._parse_datetime(getattr(fields, 'resolutiondate', None)),
+            story_points=story_points,
+            sprint=sprint,
+            labels=getattr(fields, 'labels', []),
+            components=[comp.name for comp in getattr(fields, 'components', [])],
+            project_key=fields.project.key,
+            issue_type=fields.issuetype.name,
+            time_spent=getattr(fields, 'timespent', None),
+            time_estimate=getattr(fields, 'timeestimate', None)
+        )
+    
+    def _parse_datetime(self, date_str: Optional[str]) -> Optional[datetime]:
+        """Parse datetime string from Jira"""
+        if not date_str:
+            return None
+        try:
+            # Jira typically returns ISO format
+            return datetime.fromisoformat(date_str.replace('Z', '+00:00'))
+        except Exception:
+            return None
+    
+    def _search_jql(
+        self,
+        jql: str,
+        max_results: int = 100,
+        fields: Optional[List[str]] = None
+    ) -> List[Dict[str, Any]]:
+        """Execute JQL search using the new /rest/api/3/search/jql endpoint"""
+        try:
+            url = f"{self.base_url}/rest/api/3/search/jql"
+            
+            params = {
+                'jql': jql,
+                'maxResults': max_results,
+                'startAt': 0
+            }
+            
+            if fields:
+                params['fields'] = ','.join(fields)
+            
+            response = requests.get(
+                url,
+                params=params,
+                headers=self.headers,
+                auth=self.auth
+            )
+            response.raise_for_status()
+            
+            data = response.json()
+            return data.get('issues', [])
+            
+        except requests.exceptions.RequestException as e:
+            logger.error(f"Error executing JQL search: {str(e)}")
+            raise
+    
+    def _parse_issue_dict(self, issue_dict: Dict[str, Any]) -> JiraIssue:
+        """Parse issue dictionary from API response to JiraIssue model"""
+        fields = issue_dict.get('fields', {})
+        
+        # Extract story points (customfield_10016 is common for story points)
+        story_points = fields.get('customfield_10016')
+        
+        # Extract sprint information
+        sprint = None
+        sprint_data = fields.get('customfield_10020')  # Common sprint field
+        if sprint_data and isinstance(sprint_data, list) and len(sprint_data) > 0:
+            sprint_obj = sprint_data[0]
+            if isinstance(sprint_obj, dict):
+                sprint = sprint_obj.get('name')
+            else:
+                sprint = str(sprint_obj)
+        
+        # Parse assignee
+        assignee = None
+        if fields.get('assignee'):
+            assignee = fields['assignee'].get('displayName')
+        
+        # Parse reporter
+        reporter = None
+        if fields.get('reporter'):
+            reporter = fields['reporter'].get('displayName')
+        
+        # Parse priority
+        priority = None
+        if fields.get('priority'):
+            priority = fields['priority'].get('name')
+        
+        # Parse status
+        status = fields.get('status', {}).get('name', 'Unknown')
+        
+        # Parse issue type
+        issue_type = fields.get('issuetype', {}).get('name', 'Unknown')
+        
+        # Parse project
+        project_key = fields.get('project', {}).get('key', '')
+        
+        # Parse components
+        components = [comp.get('name', '') for comp in fields.get('components', [])]
+        
+        # Parse description (API v3 may return ADF format)
+        description = self._parse_description(fields.get('description'))
+        
+        return JiraIssue(
+            issue_key=issue_dict.get('key', ''),
+            summary=fields.get('summary', ''),
+            description=description,
+            status=status,
+            priority=priority,
+            assignee=assignee,
+            reporter=reporter,
+            created=self._parse_datetime(fields.get('created')),
+            updated=self._parse_datetime(fields.get('updated')),
+            resolved=self._parse_datetime(fields.get('resolutiondate')),
+            story_points=story_points,
+            sprint=sprint,
+            labels=fields.get('labels', []),
+            components=components,
+            project_key=project_key,
+            issue_type=issue_type,
+            time_spent=fields.get('timespent'),
+            time_estimate=fields.get('timeestimate')
+        )
+    
+    def _parse_description(self, description_data: Any) -> Optional[str]:
+        """Parse description field from Jira API v3 (handles rich text format)"""
+        if not description_data:
+            return None
+        
+        # If it's already a string, return it
+        if isinstance(description_data, str):
+            return description_data
+        
+        # If it's a dict (Atlassian Document Format), extract text content
+        if isinstance(description_data, dict):
+            return self._extract_text_from_adf(description_data)
+        
+        return None
+    
+    def _extract_text_from_adf(self, adf_content: Dict[str, Any]) -> str:
+        """Extract plain text from Atlassian Document Format (ADF)"""
+        if not adf_content:
+            return ""
+        
+        text_parts = []
+        
+        def extract_text(node):
+            """Recursively extract text from ADF nodes"""
+            if isinstance(node, dict):
+                # If node has text, add it
+                if 'text' in node:
+                    text_parts.append(node['text'])
+                
+                # Process content array
+                if 'content' in node and isinstance(node['content'], list):
+                    for child in node['content']:
+                        extract_text(child)
+            elif isinstance(node, list):
+                for item in node:
+                    extract_text(item)
+        
+        extract_text(adf_content)
+        return ' '.join(text_parts).strip()
+    
+    # ===== KANBAN BOARD METHODS =====
+    
+    def get_kanban_boards(self) -> List[KanbanBoard]:
+        """Fetch all Kanban boards"""
+        try:
+            # Use REST API directly
+            url = f"{self.base_url}/rest/agile/latest/board"
+            params = {'type': 'kanban'}
+            
+            response = requests.get(url, headers=self.headers, auth=self.auth, params=params)
+            response.raise_for_status()
+            
+            data = response.json()
+            boards_data = data.get('values', [])
+            
+            kanban_boards = []
+            for board in boards_data:
+                # Get board configuration to extract columns
+                board_config = self._get_board_config_details(board.get('id'))
+                
+                # Extract location info
+                location = board.get('location', {})
+                project_key = location.get('projectKey') if location else None
+                
+                kanban_boards.append(KanbanBoard(
+                    board_id=board.get('id'),
+                    board_name=board.get('name', ''),
+                    board_type=board.get('type', 'kanban'),
+                    project_key=project_key,
+                    columns=board_config.get('columns', []),
+                    filter_id=board.get('filter', {}).get('id') if board.get('filter') else None,
+                    location=None  # Simplified to avoid serialization issues
+                ))
+            
+            return kanban_boards
+        except Exception as e:
+            logger.error(f"Error fetching Kanban boards: {str(e)}")
+            raise
+    
+    def get_kanban_board_by_id(self, board_id: int) -> Optional[KanbanBoard]:
+        """Fetch a specific Kanban board by ID with actual issue counts"""
+        try:
+            # Use REST API directly
+            url = f"{self.base_url}/rest/agile/latest/board/{board_id}"
+            
+            response = requests.get(url, headers=self.headers, auth=self.auth)
+            response.raise_for_status()
+            
+            board = response.json()
+            
+            if board.get('type', '').lower() != 'kanban':
+                logger.warning(f"Board {board_id} is not a Kanban board")
+                return None
+            
+            # Get board configuration
+            board_config = self._get_board_config_details(board.get('id'))
+            columns = board_config.get('columns', [])
+            
+            # Fetch all issues for the board to get real counts and statuses
+            issues_url = f"{self.base_url}/rest/agile/latest/board/{board_id}/issue"
+            params = {
+                'maxResults': 500,
+                'fields': 'summary,status,priority,assignee,reporter,created,updated,resolutiondate,customfield_10016,description,labels,components,issuetype,timespent,timeestimate'
+            }
+            
+            issues_response = requests.get(issues_url, headers=self.headers, auth=self.auth, params=params)
+            issues_response.raise_for_status()
+            
+            issues_data = issues_response.json()
+            raw_issues = issues_data.get('issues', [])
+            
+            # Parse issues to JiraIssue objects
+            parsed_issues = [self._parse_issue_dict(issue) for issue in raw_issues]
+            
+            logger.info(f"Board {board_id}: Found {len(parsed_issues)} issues")
+            
+            # If columns have empty statuses, infer them from actual issues
+            if columns and all(not col.statuses for col in columns):
+                logger.info(f"Board {board_id}: Column statuses are empty, inferring from issues")
+                columns = self._infer_columns_from_issues(parsed_issues, columns)
+            
+            # Count issues per column based on their status
+            status_to_column = {}
+            for col in columns:
+                for status in col.statuses:
+                    status_to_column[status.lower()] = col.name
+            
+            # Count issues
+            column_counts = {col.name: 0 for col in columns}
+            for issue in parsed_issues:
+                if issue.status:
+                    column_name = status_to_column.get(issue.status.lower())
+                    if column_name:
+                        column_counts[column_name] += 1
+            
+            # Update issue counts
+            for col in columns:
+                col.issue_count = column_counts.get(col.name, 0)
+            
+            logger.info(f"Board {board_id} column counts: {column_counts}")
+            
+            # Extract location info
+            location = board.get('location', {})
+            project_key = location.get('projectKey') if location else None
+            
+            return KanbanBoard(
+                board_id=board.get('id'),
+                board_name=board.get('name', ''),
+                board_type=board.get('type', 'kanban'),
+                project_key=project_key,
+                columns=columns,
+                filter_id=board.get('filter', {}).get('id') if board.get('filter') else None,
+                location=None  # Simplified to avoid serialization issues
+            )
+        except Exception as e:
+            logger.error(f"Error fetching Kanban board {board_id}: {str(e)}")
+            raise
+    
+    def get_board_configuration(self, board_id: int) -> BoardConfiguration:
+        """Get detailed board configuration"""
+        try:
+            url = f"{self.base_url}/rest/agile/latest/board/{board_id}/configuration"
+            response = requests.get(url, headers=self.headers, auth=self.auth)
+            response.raise_for_status()
+            
+            config_data = response.json()
+            
+            return BoardConfiguration(
+                board_id=board_id,
+                name=config_data.get('name', ''),
+                self_link=config_data.get('self', ''),
+                estimation=config_data.get('estimation'),
+                ranking=config_data.get('ranking'),
+                column_config=config_data.get('columnConfig')
+            )
+        except Exception as e:
+            logger.error(f"Error fetching board configuration: {str(e)}")
+            raise
+    
+    def get_kanban_issues_by_column(self, board_id: int) -> List[KanbanIssuesByColumn]:
+        """Get issues grouped by Kanban board columns"""
+        try:
+            # Get board configuration first
+            board_config = self._get_board_config_details(board_id)
+            columns = board_config.get('columns', [])
+            
+            # Get all issues for the board using the Agile API endpoint
+            url = f"{self.base_url}/rest/agile/latest/board/{board_id}/issue"
+            params = {
+                'maxResults': 500,
+                'fields': 'summary,status,priority,assignee,reporter,created,updated,resolutiondate,customfield_10016,description,labels,components,issuetype,timespent,timeestimate'
+            }
+            
+            response = requests.get(url, headers=self.headers, auth=self.auth, params=params)
+            response.raise_for_status()
+            
+            data = response.json()
+            issues = data.get('issues', [])
+            
+            parsed_issues = [self._parse_issue_dict(issue) for issue in issues]
+            
+            logger.info(f"Found {len(parsed_issues)} total issues for board {board_id}")
+            
+            # Check if columns have any statuses configured
+            has_configured_statuses = any(col.statuses for col in columns)
+            
+            if not has_configured_statuses and parsed_issues:
+                # Fallback: Infer columns from actual issue statuses
+                logger.warning(f"No statuses configured in columns, inferring from {len(parsed_issues)} issues")
+                columns = self._infer_columns_from_issues(parsed_issues, columns)
+            
+            # Group issues by column
+            issues_by_column = []
+            matched_issues = set()
+            
+            for column in columns:
+                # Case-insensitive status matching
+                column_statuses_lower = [s.lower() for s in column.statuses]
+                column_issues = [
+                    issue for issue in parsed_issues
+                    if issue.status.lower() in column_statuses_lower
+                ]
+                
+                # Track which issues were matched
+                for issue in column_issues:
+                    matched_issues.add(issue.issue_key)
+                
+                logger.info(f"Column '{column.name}' has {len(column_issues)} issues (statuses: {column.statuses})")
+                
+                issues_by_column.append(KanbanIssuesByColumn(
+                    column_name=column.name,
+                    statuses=column.statuses,
+                    issues=column_issues,
+                    wip_limit_min=column.min,
+                    wip_limit_max=column.max,
+                    issue_count=len(column_issues)
+                ))
+            
+            # Add unmatched issues to a separate "Other" column if any
+            unmatched_issues = [i for i in parsed_issues if i.issue_key not in matched_issues]
+            if unmatched_issues:
+                logger.warning(f"Found {len(unmatched_issues)} unmatched issues with statuses: {set([i.status for i in unmatched_issues])}")
+                issues_by_column.append(KanbanIssuesByColumn(
+                    column_name="Other",
+                    statuses=list(set([i.status for i in unmatched_issues])),  # Remove duplicates
+                    issues=unmatched_issues,
+                    wip_limit_min=None,
+                    wip_limit_max=None,
+                    issue_count=len(unmatched_issues)
+                ))
+            
+            return issues_by_column
+        except Exception as e:
+            logger.error(f"Error fetching Kanban issues by column: {str(e)}")
+            raise
+    
+    def _infer_columns_from_issues(self, issues: List[JiraIssue], existing_columns: List[KanbanColumn]) -> List[KanbanColumn]:
+        """Infer column configurations from actual issue statuses"""
+        # Get unique statuses from issues
+        unique_statuses = {}
+        for issue in issues:
+            status = issue.status
+            if status not in unique_statuses:
+                unique_statuses[status] = 0
+            unique_statuses[status] += 1
+        
+        logger.info(f"Found unique statuses: {list(unique_statuses.keys())}")
+        
+        # Map statuses to columns by matching column names
+        inferred_columns = []
+        
+        for col in existing_columns:
+            # Try to match statuses by column name (case-insensitive partial match)
+            col_name_lower = col.name.lower()
+            matched_statuses = []
+            
+            for status in unique_statuses.keys():
+                status_lower = status.lower()
+                # Try exact match first
+                if status_lower == col_name_lower:
+                    matched_statuses.append(status)
+                # Try partial match (e.g., "In Progress" matches "Progress")
+                elif status_lower in col_name_lower or col_name_lower in status_lower:
+                    matched_statuses.append(status)
+            
+            # If no match found, check for common patterns
+            if not matched_statuses:
+                if 'backlog' in col_name_lower:
+                    matched_statuses = [s for s in unique_statuses.keys() if 'backlog' in s.lower()]
+                elif 'progress' in col_name_lower or 'doing' in col_name_lower or 'development' in col_name_lower:
+                    matched_statuses = [s for s in unique_statuses.keys() if 'progress' in s.lower() or 'development' in s.lower()]
+                elif 'done' in col_name_lower or 'complete' in col_name_lower:
+                    matched_statuses = [s for s in unique_statuses.keys() if 'done' in s.lower() or 'complete' in s.lower()]
+                elif 'selected' in col_name_lower or 'ready' in col_name_lower or 'todo' in col_name_lower:
+                    matched_statuses = [s for s in unique_statuses.keys() if 'selected' in s.lower() or 'ready' in s.lower() or 'todo' in s.lower() or 'to do' in s.lower()]
+            
+            logger.info(f"Inferred column '{col.name}': {matched_statuses}")
+            
+            inferred_columns.append(KanbanColumn(
+                name=col.name,
+                statuses=matched_statuses,
+                min=col.min,
+                max=col.max,
+                issue_count=0
+            ))
+        
+        # If we still have unmapped statuses, they'll go to "Other"
+        mapped_statuses = set()
+        for col in inferred_columns:
+            mapped_statuses.update(col.statuses)
+        
+        unmapped = set(unique_statuses.keys()) - mapped_statuses
+        if unmapped:
+            logger.warning(f"Unmapped statuses after inference: {unmapped}")
+        
+        return inferred_columns
+    
+    def get_board_backlog(self, board_id: int, max_results: int = 100) -> List[JiraIssue]:
+        """Get backlog issues for a board
+        
+        For Scrum boards: Uses the /backlog endpoint
+        For Kanban boards: Returns issues in 'Backlog' status/column
+        """
+        try:
+            # First, check if this is a Kanban or Scrum board
+            board_url = f"{self.base_url}/rest/agile/latest/board/{board_id}"
+            board_response = requests.get(board_url, headers=self.headers, auth=self.auth)
+            board_response.raise_for_status()
+            board_data = board_response.json()
+            board_type = board_data.get('type', '').lower()
+            
+            if board_type == 'scrum':
+                # Use the backlog endpoint for Scrum boards
+                url = f"{self.base_url}/rest/agile/latest/board/{board_id}/backlog"
+                params = {
+                    'maxResults': max_results,
+                    'fields': 'summary,status,priority,assignee,reporter,created,updated,resolutiondate,customfield_10016,description,labels,components,issuetype,timespent,timeestimate'
+                }
+                
+                response = requests.get(url, headers=self.headers, auth=self.auth, params=params)
+                response.raise_for_status()
+                
+                data = response.json()
+                issues = data.get('issues', [])
+                
+                return [self._parse_issue_dict(issue) for issue in issues]
+            else:
+                # For Kanban boards, get all issues and filter by Backlog status
+                logger.info(f"Board {board_id} is Kanban, filtering for Backlog column issues")
+                
+                url = f"{self.base_url}/rest/agile/latest/board/{board_id}/issue"
+                params = {
+                    'maxResults': max_results,
+                    'fields': 'summary,status,priority,assignee,reporter,created,updated,resolutiondate,customfield_10016,description,labels,components,issuetype,timespent,timeestimate'
+                }
+                
+                response = requests.get(url, headers=self.headers, auth=self.auth, params=params)
+                response.raise_for_status()
+                
+                data = response.json()
+                all_issues = data.get('issues', [])
+                
+                # Filter issues that are in "Backlog" status
+                backlog_issues = [
+                    self._parse_issue_dict(issue) 
+                    for issue in all_issues 
+                    if 'backlog' in issue.get('fields', {}).get('status', {}).get('name', '').lower()
+                ]
+                
+                logger.info(f"Found {len(backlog_issues)} backlog issues out of {len(all_issues)} total")
+                return backlog_issues
+                
+        except Exception as e:
+            logger.error(f"Error fetching board backlog: {str(e)}")
+            raise
+    
+    def move_issue_to_status(self, issue_key: str, transition_name: str) -> bool:
+        """Move an issue to a different status (column) via transition"""
+        try:
+            # Get available transitions for the issue
+            url = f"{self.base_url}/rest/api/3/issue/{issue_key}/transitions"
+            response = requests.get(url, headers=self.headers, auth=self.auth)
+            response.raise_for_status()
+            
+            transitions = response.json().get('transitions', [])
+            
+            # Find the matching transition
+            transition_id = None
+            for transition in transitions:
+                if transition.get('name', '').lower() == transition_name.lower():
+                    transition_id = transition.get('id')
+                    break
+            
+            if not transition_id:
+                logger.error(f"Transition '{transition_name}' not found for issue {issue_key}")
+                return False
+            
+            # Execute the transition
+            transition_data = {
+                'transition': {'id': transition_id}
+            }
+            
+            response = requests.post(
+                url,
+                json=transition_data,
+                headers=self.headers,
+                auth=self.auth
+            )
+            response.raise_for_status()
+            
+            logger.info(f"Successfully moved issue {issue_key} to {transition_name}")
+            return True
+            
+        except Exception as e:
+            logger.error(f"Error moving issue {issue_key}: {str(e)}")
+            raise
+    
+    def get_issue_transitions(self, issue_key: str) -> List[Dict[str, Any]]:
+        """Get available transitions for an issue"""
+        try:
+            url = f"{self.base_url}/rest/api/3/issue/{issue_key}/transitions"
+            response = requests.get(url, headers=self.headers, auth=self.auth)
+            response.raise_for_status()
+            
+            transitions = response.json().get('transitions', [])
+            
+            return [
+                {
+                    'id': t.get('id'),
+                    'name': t.get('name'),
+                    'to_status': t.get('to', {}).get('name'),
+                    'has_screen': t.get('hasScreen', False)
+                }
+                for t in transitions
+            ]
+        except Exception as e:
+            logger.error(f"Error fetching transitions for {issue_key}: {str(e)}")
+            raise
+    
+    def _get_board_config_details(self, board_id: int) -> Dict[str, Any]:
+        """Helper method to get board configuration details"""
+        try:
+            url = f"{self.base_url}/rest/agile/latest/board/{board_id}/configuration"
+            response = requests.get(url, headers=self.headers, auth=self.auth)
+            response.raise_for_status()
+            
+            config_data = response.json()
+            column_config = config_data.get('columnConfig', {})
+            columns_data = column_config.get('columns', [])
+            
+            logger.info(f"Board {board_id} config: {len(columns_data)} columns found")
+            
+            # Parse columns with their statuses and WIP limits
+            columns = []
+            for col in columns_data:
+                # Get statuses - handle both 'statuses' array and 'mappedStatuses'
+                statuses = []
+                
+                # Try 'statuses' first
+                status_list = col.get('statuses', [])
+                if status_list:
+                    statuses = [
+                        s.get('name') if isinstance(s, dict) else str(s)
+                        for s in status_list
+                        if s and (isinstance(s, str) or (isinstance(s, dict) and s.get('name')))
+                    ]
+                
+                # If no statuses found, try 'mappedStatuses'
+                if not statuses:
+                    mapped_statuses = col.get('mappedStatuses', [])
+                    if mapped_statuses:
+                        statuses = [
+                            s.get('name') if isinstance(s, dict) else str(s)
+                            for s in mapped_statuses
+                            if s and (isinstance(s, str) or (isinstance(s, dict) and s.get('name')))
+                        ]
+                
+                column_name = col.get('name', '')
+                logger.info(f"  Column '{column_name}': {len(statuses)} statuses = {statuses}")
+                
+                # Only add columns that have at least a name
+                if column_name:
+                    columns.append(KanbanColumn(
+                        name=column_name,
+                        statuses=statuses,
+                        min=col.get('min'),
+                        max=col.get('max'),
+                        issue_count=0
+                    ))
+            
+            return {'columns': columns, 'raw_config': config_data}
+            
+        except Exception as e:
+            logger.warning(f"Could not fetch board configuration for {board_id}: {str(e)}")
+            # Log the raw response if available for debugging
+            try:
+                logger.warning(f"Raw config data: {config_data if 'config_data' in locals() else 'Not available'}")
+            except:
+                pass
+            return {'columns': [], 'raw_config': {}}
+
+
+# Singleton instance
+jira_service = JiraIntegrationService()

main.py

@@ -0,0 +1,73 @@
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+from api.jira_routes import router as jira_router
+from api.intelligence_routes import router as intelligence_router
+from config.settings import settings
+import logging
+
+# Configure logging
+logging.basicConfig(
+    level=logging.INFO,
+    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
+)
+
+logger = logging.getLogger(__name__)
+
+# Create FastAPI app
+app = FastAPI(
+    title="Enterprise Delivery & Workforce Intelligence API",
+    description="AI-powered enterprise intelligence system for engineering operations",
+    version="1.0.0",
+    debug=settings.debug
+)
+
+# Configure CORS
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],  # In production, specify actual origins
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+# Include routers
+app.include_router(jira_router)
+app.include_router(intelligence_router)
+
+
+@app.get("/")
+async def root():
+    """Root endpoint"""
+    return {
+        "message": "Enterprise Delivery & Workforce Intelligence API",
+        "version": "1.0.0",
+        "status": "operational",
+        "endpoints": {
+            "jira": "/jira",
+            "intelligence": "/intelligence",
+            "docs": "/docs",
+            "redoc": "/redoc"
+        }
+    }
+
+
+@app.get("/health")
+async def health_check():
+    """Health check endpoint"""
+    return {
+        "status": "healthy",
+        "timestamp": "2026-02-07T00:00:00Z"
+    }
+
+
+if __name__ == "__main__":
+    import uvicorn
+    
+    logger.info(f"Starting server on {settings.api_host}:{settings.api_port}")
+    uvicorn.run(
+        "main:app",
+        host=settings.api_host,
+        port=settings.api_port,
+        reload=settings.debug
+    )
+

models/__init__.py

@@ -0,0 +1,33 @@
+from .jira_models import (
+    JiraIssue,
+    Sprint,
+    TeamMember,
+    WorklogEntry,
+    ProjectInfo,
+    PriorityLevel,
+    IssueStatus
+)
+from .intelligence_models import (
+    DeliveryHealthMetrics,
+    ProductivityMetrics,
+    CostEfficiencyMetrics,
+    TeamCapacityMetrics,
+    RiskAlert,
+    InsightRecommendation
+)
+
+__all__ = [
+    "JiraIssue",
+    "Sprint",
+    "TeamMember",
+    "WorklogEntry",
+    "ProjectInfo",
+    "PriorityLevel",
+    "IssueStatus",
+    "DeliveryHealthMetrics",
+    "ProductivityMetrics",
+    "CostEfficiencyMetrics",
+    "TeamCapacityMetrics",
+    "RiskAlert",
+    "InsightRecommendation"
+]

models/intelligence_models.py

@@ -0,0 +1,211 @@
+from pydantic import BaseModel, Field
+from typing import List, Optional, Dict
+from datetime import datetime, date
+
+
+class DeliveryHealthMetrics(BaseModel):
+    """Metrics for delivery health analysis"""
+    sprint_id: Optional[str] = None
+    sprint_name: Optional[str] = None
+    period_start: date
+    period_end: date
+    
+    # Velocity Metrics
+    planned_story_points: float = 0
+    completed_story_points: float = 0
+    velocity: float = 0
+    velocity_trend: float = 0  # percentage change from previous period
+    
+    # Completion Metrics
+    total_issues: int = 0
+    completed_issues: int = 0
+    completion_rate: float = 0
+    
+    # Time Metrics
+    avg_cycle_time_hours: float = 0
+    avg_lead_time_hours: float = 0
+    
+    # Quality Indicators
+    blocked_issues_count: int = 0
+    overdue_issues_count: int = 0
+    reopened_issues_count: int = 0
+    
+    # Risk Indicators
+    at_risk_issues: int = 0
+    health_score: float = 0  # 0-100
+
+
+class ProductivityMetrics(BaseModel):
+    """Workforce productivity metrics"""
+    team_member_id: str
+    team_member_name: str
+    period_start: date
+    period_end: date
+    
+    # Activity Metrics
+    issues_completed: int = 0
+    story_points_completed: float = 0
+    code_commits: int = 0  # from GitHub
+    pull_requests: int = 0  # from GitHub
+    
+    # Time Metrics
+    total_hours_logged: float = 0
+    avg_hours_per_day: float = 0
+    
+    # Efficiency Metrics
+    avg_issue_completion_time_hours: float = 0
+    productivity_score: float = 0  # 0-100
+    
+    # Workload Metrics
+    current_assigned_issues: int = 0
+    current_story_points: float = 0
+    utilization_rate: float = 0  # percentage
+
+
+class CostEfficiencyMetrics(BaseModel):
+    """Cost and efficiency analysis"""
+    period_start: date
+    period_end: date
+    project_key: Optional[str] = None
+    
+    # Resource Metrics
+    total_team_members: int = 0
+    total_hours_logged: float = 0
+    estimated_cost: float = 0  # based on hours
+    
+    # Output Metrics
+    features_delivered: int = 0
+    story_points_delivered: float = 0
+    
+    # Efficiency Ratios
+    cost_per_feature: float = 0
+    cost_per_story_point: float = 0
+    hours_per_story_point: float = 0
+    
+    # Waste Indicators
+    blocked_time_hours: float = 0
+    rework_hours: float = 0
+    waste_percentage: float = 0
+
+
+class TeamCapacityMetrics(BaseModel):
+    """Team capacity and utilization"""
+    team_id: Optional[str] = None
+    team_name: str
+    period_start: date
+    period_end: date
+    
+    # Capacity Metrics
+    total_capacity_hours: float = 0
+    allocated_hours: float = 0
+    available_hours: float = 0
+    utilization_rate: float = 0
+    
+    # Workload Distribution
+    team_members: List[Dict] = Field(default_factory=list)
+    overloaded_members: int = 0
+    underutilized_members: int = 0
+    
+    # Sprint Metrics
+    current_sprint_load: float = 0
+    forecasted_capacity: float = 0
+
+
+class RiskAlert(BaseModel):
+    """Risk and alert model"""
+    alert_id: str
+    alert_type: str  # delivery_delay, cost_overrun, resource_shortage, quality_issue
+    severity: str  # critical, high, medium, low
+    title: str
+    description: str
+    affected_entity: str  # sprint, project, team_member
+    entity_id: str
+    detected_at: datetime
+    suggested_action: Optional[str] = None
+    metrics: Dict = Field(default_factory=dict)
+
+
+class InsightRecommendation(BaseModel):
+    """AI-generated insights and recommendations"""
+    insight_id: str
+    category: str  # delivery, productivity, cost, resource
+    title: str
+    description: str
+    confidence_score: float = 0  # 0-1
+    impact_level: str  # high, medium, low
+    recommendations: List[str] = Field(default_factory=list)
+    supporting_data: Dict = Field(default_factory=dict)
+    generated_at: datetime
+
+
+class KanbanFlowMetrics(BaseModel):
+    """Kanban flow efficiency metrics"""
+    board_id: int
+    board_name: str
+    period_start: date
+    period_end: date
+    
+    # Flow Metrics
+    throughput: int = 0  # Issues completed in period
+    avg_cycle_time_days: float = 0
+    avg_lead_time_days: float = 0
+    flow_efficiency: float = 0  # 0-100
+    
+    # WIP Metrics
+    current_wip: int = 0
+    avg_wip: float = 0
+    wip_violations: int = 0  # Number of times WIP limits were exceeded
+    
+    # Column Metrics
+    bottleneck_column: Optional[str] = None
+    bottleneck_score: float = 0
+    
+    # Predictability
+    throughput_variance: float = 0
+    cycle_time_variance: float = 0
+    
+    # Health Score
+    flow_health_score: float = 0  # 0-100
+
+
+class KanbanColumnAnalysis(BaseModel):
+    """Analysis for a specific Kanban column"""
+    column_name: str
+    statuses: List[str]
+    
+    # Current State
+    current_issue_count: int = 0
+    wip_limit_min: Optional[int] = None
+    wip_limit_max: Optional[int] = None
+    is_over_wip_limit: bool = False
+    
+    # Flow Metrics
+    avg_time_in_column_days: float = 0
+    throughput: int = 0  # Issues exited this column
+    
+    # Efficiency
+    utilization_rate: float = 0  # current / max limit
+    is_bottleneck: bool = False
+    bottleneck_score: float = 0  # Higher = more of a bottleneck
+
+
+class KanbanCumulativeFlow(BaseModel):
+    """Cumulative flow diagram data"""
+    board_id: int
+    period_start: date
+    period_end: date
+    
+    # Daily snapshots
+    data_points: List[Dict] = Field(default_factory=list)
+    # Each data point: {date, column_name, issue_count}
+
+
+class WIPLimitRecommendation(BaseModel):
+    """WIP limit optimization recommendations"""
+    column_name: str
+    current_limit: Optional[int]
+    recommended_min: int
+    recommended_max: int
+    reasoning: str
+    confidence_score: float = 0  # 0-1
+

models/jira_models.py

@@ -0,0 +1,158 @@
+from pydantic import BaseModel, Field
+from typing import List, Optional, Dict, Any
+from datetime import datetime
+from enum import Enum
+
+
+class PriorityLevel(str, Enum):
+    HIGHEST = "Highest"
+    HIGH = "High"
+    MEDIUM = "Medium"
+    LOW = "Low"
+    LOWEST = "Lowest"
+
+
+class IssueStatus(str, Enum):
+    TODO = "To Do"
+    IN_PROGRESS = "In Progress"
+    IN_REVIEW = "In Review"
+    DONE = "Done"
+    BLOCKED = "Blocked"
+
+
+class JiraIssue(BaseModel):
+    issue_key: str
+    summary: str
+    description: Optional[str] = None
+    status: str
+    priority: Optional[str] = None
+    assignee: Optional[str] = None
+    reporter: Optional[str] = None
+    created: datetime
+    updated: datetime
+    resolved: Optional[datetime] = None
+    story_points: Optional[float] = None
+    sprint: Optional[str] = None
+    labels: List[str] = Field(default_factory=list)
+    components: List[str] = Field(default_factory=list)
+    project_key: str
+    issue_type: str
+    time_spent: Optional[int] = None  # in seconds
+    time_estimate: Optional[int] = None  # in seconds
+
+
+class Sprint(BaseModel):
+    sprint_id: int
+    sprint_name: str
+    state: str  # active, closed, future
+    start_date: Optional[datetime] = None
+    end_date: Optional[datetime] = None
+    complete_date: Optional[datetime] = None
+    goal: Optional[str] = None
+
+
+class TeamMember(BaseModel):
+    account_id: str
+    display_name: str
+    email: Optional[str] = None
+    active: bool = True
+    avatar_url: Optional[str] = None
+
+
+class WorklogEntry(BaseModel):
+    id: str
+    issue_key: str
+    author: str
+    time_spent_seconds: int
+    started: datetime
+    comment: Optional[str] = None
+    
+    @classmethod
+    def from_jira_worklog(cls, worklog_data: dict, issue_key: str):
+        """Create WorklogEntry from Jira API response, handling ADF comment format"""
+        comment = worklog_data.get('comment')
+        
+        # Convert ADF (Atlassian Document Format) to plain text
+        if isinstance(comment, dict):
+            comment = cls._extract_text_from_adf(comment)
+        
+        return cls(
+            id=worklog_data.get('id'),
+            issue_key=issue_key,
+            author=worklog_data.get('author', {}).get('displayName', ''),
+            time_spent_seconds=worklog_data.get('timeSpentSeconds', 0),
+            started=worklog_data.get('started'),
+            comment=comment
+        )
+    
+    @staticmethod
+    def _extract_text_from_adf(adf: dict) -> str:
+        """Extract plain text from Atlassian Document Format"""
+        if not adf or not isinstance(adf, dict):
+            return ""
+        
+        text_parts = []
+        
+        def extract_content(node):
+            if isinstance(node, dict):
+                # Extract text from text nodes
+                if node.get('type') == 'text':
+                    text_parts.append(node.get('text', ''))
+                # Recursively process content array
+                if 'content' in node:
+                    for child in node['content']:
+                        extract_content(child)
+            elif isinstance(node, list):
+                for item in node:
+                    extract_content(item)
+        
+        extract_content(adf)
+        return ' '.join(text_parts).strip()
+
+
+class ProjectInfo(BaseModel):
+    project_key: str
+    project_name: str
+    project_type: str
+    lead: Optional[str] = None
+    description: Optional[str] = None
+
+
+class KanbanColumn(BaseModel):
+    """Represents a column in a Kanban board"""
+    name: str
+    statuses: List[str] = Field(default_factory=list)
+    min: Optional[int] = None  # WIP limit min
+    max: Optional[int] = None  # WIP limit max
+    issue_count: int = 0
+
+
+class KanbanBoard(BaseModel):
+    """Represents a Kanban board with its configuration"""
+    board_id: int
+    board_name: str
+    board_type: str
+    project_key: Optional[str] = None
+    columns: List[KanbanColumn] = Field(default_factory=list)
+    filter_id: Optional[int] = None
+    location: Optional[Dict[str, Any]] = None
+
+
+class KanbanIssuesByColumn(BaseModel):
+    """Issues grouped by Kanban columns"""
+    column_name: str
+    statuses: List[str]
+    issues: List[JiraIssue] = Field(default_factory=list)
+    wip_limit_min: Optional[int] = None
+    wip_limit_max: Optional[int] = None
+    issue_count: int = 0
+
+
+class BoardConfiguration(BaseModel):
+    """Board configuration details"""
+    board_id: int
+    name: str
+    self_link: str
+    estimation: Optional[Dict[str, Any]] = None
+    ranking: Optional[Dict[str, Any]] = None
+    column_config: Optional[Dict[str, Any]] = None

requirements.txt

@@ -0,0 +1,16 @@
+fastapi==0.109.0
+uvicorn==0.27.0
+pydantic==2.5.3
+pydantic-settings==2.1.0
+jira==3.8.0
+httpx==0.26.0
+python-dotenv==1.0.0
+pandas==2.1.4
+numpy==1.26.3
+sqlalchemy==2.0.25
+redis==5.0.1
+celery==5.3.6
+python-jose[cryptography]==3.3.0
+passlib[bcrypt]==1.7.4
+python-multipart==0.0.6
+aiohttp==3.9.1

services/__init__.py

@@ -0,0 +1,3 @@
+from .intelligence_service import intelligence_service, IntelligenceService
+
+__all__ = ["intelligence_service", "IntelligenceService"]

services/intelligence_service.py

@@ -0,0 +1,760 @@
+from typing import List, Dict, Optional
+from datetime import datetime, timedelta, date
+from collections import defaultdict
+import numpy as np
+from models.jira_models import JiraIssue, Sprint, WorklogEntry
+from models.intelligence_models import (
+    DeliveryHealthMetrics,
+    ProductivityMetrics,
+    CostEfficiencyMetrics,
+    TeamCapacityMetrics,
+    RiskAlert,
+    InsightRecommendation,
+    KanbanFlowMetrics,
+    KanbanColumnAnalysis,
+    KanbanCumulativeFlow,
+    WIPLimitRecommendation
+)
+import logging
+import uuid
+
+logger = logging.getLogger(__name__)
+
+
+class IntelligenceService:
+    """Service for generating business intelligence from engineering data"""
+    
+    def calculate_delivery_health(
+        self,
+        issues: List[JiraIssue],
+        sprint: Optional[Sprint] = None,
+        period_start: Optional[date] = None,
+        period_end: Optional[date] = None
+    ) -> DeliveryHealthMetrics:
+        """Calculate delivery health metrics"""
+        
+        if not period_start and sprint:
+            period_start = sprint.start_date.date() if sprint.start_date else date.today()
+        if not period_end and sprint:
+            period_end = sprint.end_date.date() if sprint.end_date else date.today()
+        
+        if not period_start:
+            period_start = date.today() - timedelta(days=14)
+        if not period_end:
+            period_end = date.today()
+        
+        # Filter issues within the period
+        period_issues = [
+            issue for issue in issues
+            if period_start <= issue.created.date() <= period_end
+        ]
+        
+        # Calculate metrics
+        total_issues = len(period_issues)
+        completed_issues = len([i for i in period_issues if i.status.lower() in ['done', 'closed']])
+        blocked_issues = len([i for i in period_issues if i.status.lower() == 'blocked'])
+        
+        # Story points
+        planned_points = sum([i.story_points or 0 for i in period_issues])
+        completed_points = sum([
+            i.story_points or 0 for i in period_issues
+            if i.status.lower() in ['done', 'closed']
+        ])
+        
+        # Cycle time calculation
+        cycle_times = []
+        for issue in period_issues:
+            if issue.resolved and issue.created:
+                cycle_time = (issue.resolved - issue.created).total_seconds() / 3600
+                cycle_times.append(cycle_time)
+        
+        avg_cycle_time = np.mean(cycle_times) if cycle_times else 0
+        
+        # Calculate completion rate
+        completion_rate = (completed_issues / total_issues * 100) if total_issues > 0 else 0
+        
+        # Calculate health score (0-100)
+        health_score = self._calculate_health_score(
+            completion_rate=completion_rate,
+            blocked_ratio=blocked_issues / total_issues if total_issues > 0 else 0,
+            velocity_ratio=completed_points / planned_points if planned_points > 0 else 0
+        )
+        
+        return DeliveryHealthMetrics(
+            sprint_id=str(sprint.sprint_id) if sprint else None,
+            sprint_name=sprint.sprint_name if sprint else None,
+            period_start=period_start,
+            period_end=period_end,
+            planned_story_points=planned_points,
+            completed_story_points=completed_points,
+            velocity=completed_points,
+            velocity_trend=0,  # TODO: Calculate from historical data
+            total_issues=total_issues,
+            completed_issues=completed_issues,
+            completion_rate=completion_rate,
+            avg_cycle_time_hours=avg_cycle_time,
+            avg_lead_time_hours=avg_cycle_time,  # Simplified
+            blocked_issues_count=blocked_issues,
+            overdue_issues_count=0,  # TODO: Calculate based on due dates
+            reopened_issues_count=0,  # TODO: Track issue history
+            at_risk_issues=blocked_issues,
+            health_score=health_score
+        )
+    
+    def calculate_productivity_metrics(
+        self,
+        issues: List[JiraIssue],
+        worklogs: List[WorklogEntry],
+        team_member_id: str,
+        team_member_name: str,
+        period_start: date,
+        period_end: date
+    ) -> ProductivityMetrics:
+        """Calculate productivity metrics for a team member"""
+        
+        # Filter issues assigned to this member
+        member_issues = [
+            i for i in issues
+            if i.assignee == team_member_name
+            and period_start <= i.created.date() <= period_end
+        ]
+        
+        # Filter worklogs for this member
+        member_worklogs = [
+            w for w in worklogs
+            if w.author == team_member_name
+            and period_start <= w.started.date() <= period_end
+        ]
+        
+        # Calculate metrics
+        completed_issues = len([i for i in member_issues if i.status.lower() in ['done', 'closed']])
+        story_points_completed = sum([
+            i.story_points or 0 for i in member_issues
+            if i.status.lower() in ['done', 'closed']
+        ])
+        
+        # Time metrics
+        total_hours = sum([w.time_spent_seconds / 3600 for w in member_worklogs])
+        days_in_period = (period_end - period_start).days + 1
+        avg_hours_per_day = total_hours / days_in_period if days_in_period > 0 else 0
+        
+        # Completion time
+        completion_times = []
+        for issue in member_issues:
+            if issue.resolved and issue.created:
+                completion_time = (issue.resolved - issue.created).total_seconds() / 3600
+                completion_times.append(completion_time)
+        
+        avg_completion_time = np.mean(completion_times) if completion_times else 0
+        
+        # Productivity score
+        productivity_score = self._calculate_productivity_score(
+            completed_issues=completed_issues,
+            story_points_completed=story_points_completed,
+            avg_completion_time=avg_completion_time,
+            hours_logged=total_hours
+        )
+        
+        # Current workload
+        current_assigned = len([i for i in issues if i.assignee == team_member_name and i.status.lower() not in ['done', 'closed']])
+        current_points = sum([i.story_points or 0 for i in issues if i.assignee == team_member_name and i.status.lower() not in ['done', 'closed']])
+        
+        return ProductivityMetrics(
+            team_member_id=team_member_id,
+            team_member_name=team_member_name,
+            period_start=period_start,
+            period_end=period_end,
+            issues_completed=completed_issues,
+            story_points_completed=story_points_completed,
+            code_commits=0,  # TODO: Integrate with GitHub
+            pull_requests=0,  # TODO: Integrate with GitHub
+            total_hours_logged=total_hours,
+            avg_hours_per_day=avg_hours_per_day,
+            avg_issue_completion_time_hours=avg_completion_time,
+            productivity_score=productivity_score,
+            current_assigned_issues=current_assigned,
+            current_story_points=current_points,
+            utilization_rate=min(100, (total_hours / (days_in_period * 8)) * 100) if days_in_period > 0 else 0
+        )
+    
+    def calculate_cost_efficiency(
+        self,
+        issues: List[JiraIssue],
+        worklogs: List[WorklogEntry],
+        period_start: date,
+        period_end: date,
+        avg_hourly_rate: float = 75.0  # Default rate
+    ) -> CostEfficiencyMetrics:
+        """Calculate cost efficiency metrics"""
+        
+        # Filter data for period
+        period_issues = [
+            i for i in issues
+            if period_start <= i.created.date() <= period_end
+        ]
+        
+        period_worklogs = [
+            w for w in worklogs
+            if period_start <= w.started.date() <= period_end
+        ]
+        
+        # Get unique team members
+        team_members = set([w.author for w in period_worklogs])
+        total_team_members = len(team_members)
+        
+        # Calculate hours and cost
+        total_hours = sum([w.time_spent_seconds / 3600 for w in period_worklogs])
+        estimated_cost = total_hours * avg_hourly_rate
+        
+        # Output metrics
+        features_delivered = len([i for i in period_issues if i.status.lower() in ['done', 'closed'] and i.issue_type.lower() in ['story', 'feature']])
+        story_points_delivered = sum([
+            i.story_points or 0 for i in period_issues
+            if i.status.lower() in ['done', 'closed']
+        ])
+        
+        # Efficiency ratios
+        cost_per_feature = estimated_cost / features_delivered if features_delivered > 0 else 0
+        cost_per_story_point = estimated_cost / story_points_delivered if story_points_delivered > 0 else 0
+        hours_per_story_point = total_hours / story_points_delivered if story_points_delivered > 0 else 0
+        
+        # Waste calculation (blocked time)
+        blocked_hours = sum([
+            (w.time_spent_seconds / 3600) for w in period_worklogs
+            if any(i.issue_key == w.issue_key and i.status.lower() == 'blocked' for i in period_issues)
+        ])
+        
+        waste_percentage = (blocked_hours / total_hours * 100) if total_hours > 0 else 0
+        
+        return CostEfficiencyMetrics(
+            period_start=period_start,
+            period_end=period_end,
+            total_team_members=total_team_members,
+            total_hours_logged=total_hours,
+            estimated_cost=estimated_cost,
+            features_delivered=features_delivered,
+            story_points_delivered=story_points_delivered,
+            cost_per_feature=cost_per_feature,
+            cost_per_story_point=cost_per_story_point,
+            hours_per_story_point=hours_per_story_point,
+            blocked_time_hours=blocked_hours,
+            rework_hours=0,  # TODO: Track rework
+            waste_percentage=waste_percentage
+        )
+    
+    def generate_risk_alerts(
+        self,
+        delivery_health: DeliveryHealthMetrics,
+        productivity_metrics: List[ProductivityMetrics],
+        cost_metrics: CostEfficiencyMetrics
+    ) -> List[RiskAlert]:
+        """Generate risk alerts based on metrics"""
+        
+        alerts = []
+        
+        # Delivery health alerts
+        if delivery_health.health_score < 50:
+            alerts.append(RiskAlert(
+                alert_id=str(uuid.uuid4()),
+                alert_type="delivery_delay",
+                severity="critical" if delivery_health.health_score < 30 else "high",
+                title="Low Delivery Health Score",
+                description=f"Sprint health score is {delivery_health.health_score:.1f}/100, indicating significant delivery risks.",
+                affected_entity="sprint",
+                entity_id=delivery_health.sprint_id or "unknown",
+                detected_at=datetime.now(),
+                suggested_action="Review blocked issues, reassign workload, and identify bottlenecks.",
+                metrics={"health_score": delivery_health.health_score}
+            ))
+        
+        if delivery_health.completion_rate < 60:
+            alerts.append(RiskAlert(
+                alert_id=str(uuid.uuid4()),
+                alert_type="delivery_delay",
+                severity="high",
+                title="Low Completion Rate",
+                description=f"Only {delivery_health.completion_rate:.1f}% of planned work is completed.",
+                affected_entity="sprint",
+                entity_id=delivery_health.sprint_id or "unknown",
+                detected_at=datetime.now(),
+                suggested_action="Reduce scope or extend timeline to meet commitments.",
+                metrics={"completion_rate": delivery_health.completion_rate}
+            ))
+        
+        # Productivity alerts
+        overworked = [p for p in productivity_metrics if p.avg_hours_per_day > 10]
+        if overworked:
+            for member in overworked:
+                alerts.append(RiskAlert(
+                    alert_id=str(uuid.uuid4()),
+                    alert_type="resource_shortage",
+                    severity="medium",
+                    title="Team Member Overworked",
+                    description=f"{member.team_member_name} is logging {member.avg_hours_per_day:.1f} hours/day.",
+                    affected_entity="team_member",
+                    entity_id=member.team_member_id,
+                    detected_at=datetime.now(),
+                    suggested_action="Redistribute workload to prevent burnout.",
+                    metrics={"avg_hours_per_day": member.avg_hours_per_day}
+                ))
+        
+        # Cost alerts
+        if cost_metrics.waste_percentage > 20:
+            alerts.append(RiskAlert(
+                alert_id=str(uuid.uuid4()),
+                alert_type="cost_overrun",
+                severity="high",
+                title="High Waste Percentage",
+                description=f"{cost_metrics.waste_percentage:.1f}% of time is wasted on blocked work.",
+                affected_entity="project",
+                entity_id="project",
+                detected_at=datetime.now(),
+                suggested_action="Identify and remove blockers urgently.",
+                metrics={"waste_percentage": cost_metrics.waste_percentage}
+            ))
+        
+        return alerts
+    
+    def generate_insights(
+        self,
+        delivery_health: DeliveryHealthMetrics,
+        productivity_metrics: List[ProductivityMetrics],
+        cost_metrics: CostEfficiencyMetrics
+    ) -> List[InsightRecommendation]:
+        """Generate AI-powered insights and recommendations"""
+        
+        insights = []
+        
+        # Velocity trend insight
+        if delivery_health.velocity > 0:
+            insights.append(InsightRecommendation(
+                insight_id=str(uuid.uuid4()),
+                category="delivery",
+                title="Velocity Analysis",
+                description=f"Team completed {delivery_health.completed_story_points:.1f} story points with {delivery_health.completion_rate:.1f}% completion rate.",
+                confidence_score=0.85,
+                impact_level="medium",
+                recommendations=[
+                    "Maintain current sprint planning strategy",
+                    "Consider increasing capacity for higher throughput"
+                ],
+                supporting_data={
+                    "completed_points": delivery_health.completed_story_points,
+                    "completion_rate": delivery_health.completion_rate
+                },
+                generated_at=datetime.now()
+            ))
+        
+        # Team efficiency insight
+        if productivity_metrics:
+            avg_productivity = np.mean([p.productivity_score for p in productivity_metrics])
+            insights.append(InsightRecommendation(
+                insight_id=str(uuid.uuid4()),
+                category="productivity",
+                title="Team Productivity Overview",
+                description=f"Average team productivity score is {avg_productivity:.1f}/100.",
+                confidence_score=0.80,
+                impact_level="high" if avg_productivity < 60 else "low",
+                recommendations=[
+                    "Identify top performers and share best practices",
+                    "Provide additional support to team members scoring below 50",
+                    "Review tool and process efficiency"
+                ] if avg_productivity < 70 else [
+                    "Team is performing well",
+                    "Focus on maintaining current practices"
+                ],
+                supporting_data={"avg_productivity_score": avg_productivity},
+                generated_at=datetime.now()
+            ))
+        
+        # Cost optimization insight
+        if cost_metrics.cost_per_story_point > 0:
+            insights.append(InsightRecommendation(
+                insight_id=str(uuid.uuid4()),
+                category="cost",
+                title="Cost Efficiency Analysis",
+                description=f"Current cost per story point is ${cost_metrics.cost_per_story_point:.2f}.",
+                confidence_score=0.75,
+                impact_level="medium",
+                recommendations=[
+                    "Track this metric over time to identify trends",
+                    "Compare with industry benchmarks",
+                    "Focus on reducing waste to improve efficiency"
+                ],
+                supporting_data={
+                    "cost_per_story_point": cost_metrics.cost_per_story_point,
+                    "waste_percentage": cost_metrics.waste_percentage
+                },
+                generated_at=datetime.now()
+            ))
+        
+        return insights
+    
+    def _calculate_health_score(
+        self,
+        completion_rate: float,
+        blocked_ratio: float,
+        velocity_ratio: float
+    ) -> float:
+        """Calculate overall health score (0-100)"""
+        
+        # Weighted scoring
+        completion_weight = 0.4
+        blocked_weight = 0.3
+        velocity_weight = 0.3
+        
+        completion_score = completion_rate
+        blocked_score = max(0, 100 - (blocked_ratio * 200))  # Penalize blocked items
+        velocity_score = min(100, velocity_ratio * 100)
+        
+        health_score = (
+            completion_score * completion_weight +
+            blocked_score * blocked_weight +
+            velocity_score * velocity_weight
+        )
+        
+        return max(0, min(100, health_score))
+    
+    def _calculate_productivity_score(
+        self,
+        completed_issues: int,
+        story_points_completed: float,
+        avg_completion_time: float,
+        hours_logged: float
+    ) -> float:
+        """Calculate productivity score (0-100)"""
+        
+        # Simple scoring based on output
+        output_score = min(100, (completed_issues * 10) + (story_points_completed * 5))
+        
+        # Efficiency score (inverse of completion time)
+        efficiency_score = min(100, 100 - (avg_completion_time / 10)) if avg_completion_time > 0 else 50
+        
+        # Average the scores
+        productivity_score = (output_score * 0.6) + (efficiency_score * 0.4)
+        
+        return max(0, min(100, productivity_score))
+
+
+    # ===== KANBAN INTELLIGENCE METHODS =====
+    
+    def calculate_kanban_flow_metrics(
+        self,
+        board_id: int,
+        board_name: str,
+        issues: List[JiraIssue],
+        columns: List,  # List of KanbanIssuesByColumn
+        period_start: date,
+        period_end: date
+    ) -> KanbanFlowMetrics:
+        """Calculate Kanban flow efficiency metrics"""
+        
+        # Filter issues within period
+        period_issues = [
+            issue for issue in issues
+            if period_start <= issue.created.date() <= period_end
+        ]
+        
+        # Calculate throughput (completed in period)
+        completed_issues = [
+            i for i in period_issues
+            if i.status.lower() in ['done', 'closed'] and i.resolved
+            and period_start <= i.resolved.date() <= period_end
+        ]
+        throughput = len(completed_issues)
+        
+        # Calculate cycle time for completed issues
+        cycle_times = []
+        for issue in completed_issues:
+            if issue.resolved and issue.created:
+                cycle_time = (issue.resolved.date() - issue.created.date()).days
+                cycle_times.append(cycle_time)
+        
+        avg_cycle_time = np.mean(cycle_times) if cycle_times else 0
+        cycle_time_variance = np.std(cycle_times) if len(cycle_times) > 1 else 0
+        
+        # Calculate WIP
+        current_wip = sum([col.issue_count for col in columns if col.column_name.lower() != 'done'])
+        
+        # Calculate WIP violations
+        wip_violations = sum([
+            1 for col in columns
+            if col.wip_limit_max and col.issue_count > col.wip_limit_max
+        ])
+        
+        # Identify bottleneck
+        bottleneck_column = None
+        bottleneck_score = 0
+        
+        for col in columns:
+            if col.column_name.lower() not in ['backlog', 'done']:
+                # Bottleneck score based on utilization and throughput
+                utilization = col.issue_count / col.wip_limit_max if col.wip_limit_max else 0
+                score = utilization * col.issue_count
+                if score > bottleneck_score:
+                    bottleneck_score = score
+                    bottleneck_column = col.column_name
+        
+        # Calculate flow efficiency (simplified)
+        flow_efficiency = min(100, (throughput / max(1, current_wip)) * 100)
+        
+        # Calculate flow health score
+        flow_health_score = self._calculate_flow_health_score(
+            throughput=throughput,
+            avg_cycle_time=avg_cycle_time,
+            wip_violations=wip_violations,
+            current_wip=current_wip
+        )
+        
+        return KanbanFlowMetrics(
+            board_id=board_id,
+            board_name=board_name,
+            period_start=period_start,
+            period_end=period_end,
+            throughput=throughput,
+            avg_cycle_time_days=avg_cycle_time,
+            avg_lead_time_days=avg_cycle_time,  # Simplified
+            flow_efficiency=flow_efficiency,
+            current_wip=current_wip,
+            avg_wip=current_wip,  # TODO: Calculate historical average
+            wip_violations=wip_violations,
+            bottleneck_column=bottleneck_column,
+            bottleneck_score=bottleneck_score,
+            throughput_variance=0,  # TODO: Calculate from historical data
+            cycle_time_variance=cycle_time_variance,
+            flow_health_score=flow_health_score
+        )
+    
+    def analyze_kanban_columns(
+        self,
+        columns: List,  # List of KanbanIssuesByColumn
+        issues: List[JiraIssue]
+    ) -> List[KanbanColumnAnalysis]:
+        """Analyze each Kanban column for bottlenecks and efficiency"""
+        
+        analyses = []
+        max_issue_count = max([col.issue_count for col in columns]) if columns else 1
+        
+        for col in columns:
+            # Calculate average time in column (simplified)
+            column_issues = col.issues
+            times_in_column = []
+            
+            for issue in column_issues:
+                if issue.resolved and issue.created:
+                    time_in_col = (issue.resolved - issue.created).total_seconds() / (3600 * 24)
+                    times_in_column.append(time_in_col)
+            
+            avg_time = np.mean(times_in_column) if times_in_column else 0
+            
+            # Calculate utilization
+            utilization = 0
+            if col.wip_limit_max and col.wip_limit_max > 0:
+                utilization = (col.issue_count / col.wip_limit_max) * 100
+            
+            # Determine if bottleneck (high issue count relative to others)
+            is_bottleneck = col.issue_count >= (max_issue_count * 0.7) and col.column_name.lower() not in ['backlog', 'done']
+            bottleneck_score = (col.issue_count / max_issue_count) * 100
+            
+            analyses.append(KanbanColumnAnalysis(
+                column_name=col.column_name,
+                statuses=col.statuses,
+                current_issue_count=col.issue_count,
+                wip_limit_min=col.wip_limit_min,
+                wip_limit_max=col.wip_limit_max,
+                is_over_wip_limit=bool(col.wip_limit_max and col.issue_count > col.wip_limit_max),
+                avg_time_in_column_days=avg_time,
+                throughput=len(column_issues),
+                utilization_rate=utilization,
+                is_bottleneck=is_bottleneck,
+                bottleneck_score=bottleneck_score
+            ))
+        
+        return analyses
+    
+    def generate_wip_recommendations(
+        self,
+        column_analyses: List[KanbanColumnAnalysis],
+        flow_metrics: KanbanFlowMetrics
+    ) -> List[WIPLimitRecommendation]:
+        """Generate WIP limit recommendations for columns"""
+        
+        recommendations = []
+        
+        for analysis in column_analyses:
+            if analysis.column_name.lower() in ['backlog', 'done']:
+                continue  # Skip backlog and done columns
+            
+            current_limit = analysis.wip_limit_max
+            current_count = analysis.current_issue_count
+            
+            # Calculate recommended limits
+            if analysis.is_bottleneck:
+                # Bottleneck: recommend lower WIP to force upstream to slow down
+                recommended_max = max(2, int(current_count * 0.7))
+                recommended_min = max(1, int(recommended_max * 0.5))
+                reasoning = f"Column is a bottleneck. Reducing WIP limit will help identify and resolve issues faster."
+                confidence = 0.8
+            elif analysis.is_over_wip_limit:
+                # Over limit: recommend current count or slightly higher
+                recommended_max = max(current_limit or 5, current_count)
+                recommended_min = max(1, int(recommended_max * 0.5))
+                reasoning = f"Currently over WIP limit. Recommend increasing limit to {recommended_max} or focusing on moving work out of this column."
+                confidence = 0.7
+            elif current_limit and analysis.utilization_rate < 50:
+                # Underutilized: recommend lower limit
+                recommended_max = max(2, int(current_limit * 0.7))
+                recommended_min = max(1, int(recommended_max * 0.5))
+                reasoning = f"Column is underutilized ({analysis.utilization_rate:.1f}%). Consider reducing WIP limit to improve focus."
+                confidence = 0.6
+            else:
+                # Optimal: keep current or suggest based on team size
+                recommended_max = current_limit or max(3, int(current_count * 1.2))
+                recommended_min = max(1, int(recommended_max * 0.5))
+                reasoning = f"Current WIP appears optimal. Maintain current limits and monitor flow."
+                confidence = 0.5
+            
+            recommendations.append(WIPLimitRecommendation(
+                column_name=analysis.column_name,
+                current_limit=current_limit,
+                recommended_min=recommended_min,
+                recommended_max=recommended_max,
+                reasoning=reasoning,
+                confidence_score=confidence
+            ))
+        
+        return recommendations
+    
+    def generate_kanban_insights(
+        self,
+        flow_metrics: KanbanFlowMetrics,
+        column_analyses: List[KanbanColumnAnalysis],
+        wip_recommendations: List[WIPLimitRecommendation]
+    ) -> List[InsightRecommendation]:
+        """Generate Kanban-specific insights and recommendations"""
+        
+        insights = []
+        
+        # Flow efficiency insight
+        insights.append(InsightRecommendation(
+            insight_id=str(uuid.uuid4()),
+            category="kanban_flow",
+            title="Kanban Flow Efficiency",
+            description=f"Board throughput is {flow_metrics.throughput} items with average cycle time of {flow_metrics.avg_cycle_time_days:.1f} days.",
+            confidence_score=0.85,
+            impact_level="high" if flow_metrics.flow_health_score < 60 else "medium",
+            recommendations=[
+                f"Current flow health score: {flow_metrics.flow_health_score:.1f}/100",
+                "Focus on reducing WIP to improve flow" if flow_metrics.current_wip > 10 else "WIP levels are healthy",
+                f"Address bottleneck in '{flow_metrics.bottleneck_column}' column" if flow_metrics.bottleneck_column else "No major bottlenecks detected"
+            ],
+            supporting_data={
+                "throughput": flow_metrics.throughput,
+                "cycle_time": flow_metrics.avg_cycle_time_days,
+                "wip": flow_metrics.current_wip,
+                "health_score": flow_metrics.flow_health_score
+            },
+            generated_at=datetime.now()
+        ))
+        
+        # WIP violations insight
+        if flow_metrics.wip_violations > 0:
+            insights.append(InsightRecommendation(
+                insight_id=str(uuid.uuid4()),
+                category="kanban_wip",
+                title="WIP Limit Violations Detected",
+                description=f"{flow_metrics.wip_violations} column(s) are exceeding their WIP limits.",
+                confidence_score=0.95,
+                impact_level="high",
+                recommendations=[
+                    "Review and enforce WIP limits to maintain flow",
+                    "Investigate why work is accumulating in these columns",
+                    "Consider if WIP limits need adjustment or if there are blockers"
+                ],
+                supporting_data={"wip_violations": flow_metrics.wip_violations},
+                generated_at=datetime.now()
+            ))
+        
+        # Bottleneck insight
+        if flow_metrics.bottleneck_column:
+            bottleneck_analysis = next(
+                (a for a in column_analyses if a.column_name == flow_metrics.bottleneck_column),
+                None
+            )
+            
+            if bottleneck_analysis:
+                insights.append(InsightRecommendation(
+                    insight_id=str(uuid.uuid4()),
+                    category="kanban_bottleneck",
+                    title=f"Bottleneck Identified: {flow_metrics.bottleneck_column}",
+                    description=f"The '{flow_metrics.bottleneck_column}' column has {bottleneck_analysis.current_issue_count} items with {bottleneck_analysis.avg_time_in_column_days:.1f} days average dwell time.",
+                    confidence_score=0.80,
+                    impact_level="high",
+                    recommendations=[
+                        "Add more resources to this stage of the workflow",
+                        "Review and optimize processes in this column",
+                        "Consider splitting this column into smaller steps",
+                        "Implement swarming: have team members help clear this column"
+                    ],
+                    supporting_data={
+                        "column": flow_metrics.bottleneck_column,
+                        "issue_count": bottleneck_analysis.current_issue_count,
+                        "avg_time_days": bottleneck_analysis.avg_time_in_column_days
+                    },
+                    generated_at=datetime.now()
+                ))
+        
+        # Cycle time insight
+        if flow_metrics.cycle_time_variance > flow_metrics.avg_cycle_time_days * 0.5:
+            insights.append(InsightRecommendation(
+                insight_id=str(uuid.uuid4()),
+                category="kanban_predictability",
+                title="High Cycle Time Variability",
+                description=f"Cycle times are inconsistent (variance: {flow_metrics.cycle_time_variance:.1f} days), making delivery predictions difficult.",
+                confidence_score=0.75,
+                impact_level="medium",
+                recommendations=[
+                    "Standardize work item sizes for better predictability",
+                    "Identify and address sources of variation",
+                    "Consider using work item types or classes of service",
+                    "Break down larger items into smaller, more predictable pieces"
+                ],
+                supporting_data={
+                    "avg_cycle_time": flow_metrics.avg_cycle_time_days,
+                    "variance": flow_metrics.cycle_time_variance
+                },
+                generated_at=datetime.now()
+            ))
+        
+        return insights
+    
+    def _calculate_flow_health_score(
+        self,
+        throughput: int,
+        avg_cycle_time: float,
+        wip_violations: int,
+        current_wip: int
+    ) -> float:
+        """Calculate Kanban flow health score (0-100)"""
+        
+        # Throughput score (higher is better)
+        throughput_score = min(100, throughput * 10)
+        
+        # Cycle time score (lower is better, assuming < 7 days is good)
+        cycle_time_score = max(0, 100 - (avg_cycle_time * 10))
+        
+        # WIP score (penalize violations and high WIP)
+        wip_score = max(0, 100 - (wip_violations * 30) - (current_wip * 2))
+        
+        # Weighted average
+        health_score = (
+            throughput_score * 0.4 +
+            cycle_time_score * 0.4 +
+            wip_score * 0.2
+        )
+        
+        return max(0, min(100, health_score))
+
+
+# Singleton instance
+intelligence_service = IntelligenceService()

utils/__init__.py

@@ -0,0 +1,29 @@
+from .helpers import (
+    parse_date_string,
+    parse_datetime_string,
+    get_date_range,
+    calculate_percentage,
+    safe_divide,
+    format_hours,
+    format_days,
+    extract_unique_values,
+    group_by_key,
+    serialize_datetime,
+    to_json,
+    PerformanceTimer
+)
+
+__all__ = [
+    "parse_date_string",
+    "parse_datetime_string",
+    "get_date_range",
+    "calculate_percentage",
+    "safe_divide",
+    "format_hours",
+    "format_days",
+    "extract_unique_values",
+    "group_by_key",
+    "serialize_datetime",
+    "to_json",
+    "PerformanceTimer"
+]

utils/helpers.py

@@ -0,0 +1,112 @@
+from typing import Optional, List, Dict, Any
+from datetime import datetime, date, timedelta
+import json
+
+
+def parse_date_string(date_str: Optional[str], default: Optional[date] = None) -> Optional[date]:
+    """Parse date string to date object"""
+    if not date_str:
+        return default
+    try:
+        return date.fromisoformat(date_str)
+    except ValueError:
+        return default
+
+
+def parse_datetime_string(datetime_str: Optional[str], default: Optional[datetime] = None) -> Optional[datetime]:
+    """Parse datetime string to datetime object"""
+    if not datetime_str:
+        return default
+    try:
+        return datetime.fromisoformat(datetime_str.replace('Z', '+00:00'))
+    except ValueError:
+        return default
+
+
+def get_date_range(days: int = 14) -> tuple[date, date]:
+    """Get date range for last N days"""
+    end_date = date.today()
+    start_date = end_date - timedelta(days=days)
+    return start_date, end_date
+
+
+def calculate_percentage(part: float, whole: float, decimals: int = 2) -> float:
+    """Calculate percentage safely"""
+    if whole == 0:
+        return 0.0
+    return round((part / whole) * 100, decimals)
+
+
+def safe_divide(numerator: float, denominator: float, default: float = 0.0) -> float:
+    """Divide safely, returning default if denominator is 0"""
+    if denominator == 0:
+        return default
+    return numerator / denominator
+
+
+def format_hours(seconds: int) -> float:
+    """Convert seconds to hours"""
+    if not seconds:
+        return 0.0
+    return round(seconds / 3600, 2)
+
+
+def format_days(hours: float) -> float:
+    """Convert hours to days (8-hour workday)"""
+    if not hours:
+        return 0.0
+    return round(hours / 8, 2)
+
+
+def extract_unique_values(items: List[Dict[str, Any]], key: str) -> List[Any]:
+    """Extract unique values from list of dictionaries"""
+    return list(set([item.get(key) for item in items if item.get(key)]))
+
+
+def group_by_key(items: List[Dict[str, Any]], key: str) -> Dict[Any, List[Dict[str, Any]]]:
+    """Group list of dictionaries by a specific key"""
+    groups = {}
+    for item in items:
+        key_value = item.get(key)
+        if key_value:
+            if key_value not in groups:
+                groups[key_value] = []
+            groups[key_value].append(item)
+    return groups
+
+
+def serialize_datetime(obj):
+    """JSON serializer for datetime objects"""
+    if isinstance(obj, (datetime, date)):
+        return obj.isoformat()
+    raise TypeError(f"Type {type(obj)} not serializable")
+
+
+def to_json(data: Any) -> str:
+    """Convert data to JSON string with datetime support"""
+    return json.dumps(data, default=serialize_datetime, indent=2)
+
+
+class PerformanceTimer:
+    """Simple performance timer context manager"""
+    
+    def __init__(self, name: str = "Operation"):
+        self.name = name
+        self.start_time = None
+        self.end_time = None
+    
+    def __enter__(self):
+        self.start_time = datetime.now()
+        return self
+    
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        self.end_time = datetime.now()
+        duration = (self.end_time - self.start_time).total_seconds()
+        print(f"{self.name} took {duration:.2f} seconds")
+    
+    @property
+    def duration(self) -> float:
+        """Get duration in seconds"""
+        if self.start_time and self.end_time:
+            return (self.end_time - self.start_time).total_seconds()
+        return 0.0