Metadata-Version: 2.4
Name: ai-dev-pulse
Version: 1.0.0
Summary: AI-powered developer productivity dashboard with GitHub integration
Author: theihtisham
License: MIT
Project-URL: Homepage, https://github.com/user/devpulse
Project-URL: Repository, https://github.com/user/devpulse
Project-URL: Issues, https://github.com/user/devpulse/issues
Keywords: developer-tools,productivity,dashboard,github,metrics
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastapi>=0.110.0
Requires-Dist: uvicorn>=0.27.0
Requires-Dist: rich>=13.7.0
Requires-Dist: click>=8.1.0
Requires-Dist: requests>=2.31.0
Requires-Dist: jinja2>=3.1.3
Requires-Dist: schedule>=1.2.0
Requires-Dist: pydantic>=2.6.0
Requires-Dist: pydantic-settings>=2.1.0
Requires-Dist: python-dateutil>=2.8.2
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
Requires-Dist: httpx>=0.27.0; extra == "dev"
Requires-Dist: ruff>=0.2.0; extra == "dev"
Requires-Dist: mypy>=1.8.0; extra == "dev"
Dynamic: license-file

<p align="center">
  <img src="https://img.shields.io/badge/version-1.0.0-blue" alt="version">
  <img src="https://img.shields.io/badge/python-3.10+-3776AB?logo=python&logoColor=white" alt="python">
  <img src="https://img.shields.io/badge/license-MIT-green" alt="license">
  <img src="https://img.shields.io/badge/tests-passing-brightgreen" alt="tests">
  <img src="https://img.shields.io/badge/code%20quality-A+-success" alt="quality">
  <img src="https://img.shields.io/badge/PRs-welcome-blueviolet" alt="prs">
  <img src="https://img.shields.io/pypi/v/ai-dev-pulse?style=for-the-badge&logo=pypi&color=3775A9" alt="pypi">
</p>

```
  ____             _       ____                  _
 |  _ \ _   _  ___| | __  |  _ \ __ _ _ __   ___| |__
 | | | | | | |/ __| |/ /  | |_) / _` | '_ \ / __| '_ \
 | |_| | |_| | (__|   <   |  __/ (_| | | | | (__| | | |
 |____/ \__,_|\___|_|\_\  |_|   \__,_|_| |_|\___|_| |_|

  Your AI-powered engineering manager -- tracks dev productivity,
  predicts bottlenecks, and coaches your team to peak performance.
```

---

## What is DevPulse?

DevPulse is an **AI-powered developer productivity dashboard** that connects to your GitHub organization and gives you deep insights into how your engineering team is performing. It tracks commits, PRs, issues, and code reviews -- then uses intelligent analysis to detect bottlenecks, predict sprint outcomes, flag burnout risk, and coach your team to peak performance.

All data stays **local** (SQLite). No external services. No sending your code to third-party APIs.

---

## Features

### GitHub Integration
- Tracks **commits, pull requests, issues, and code reviews** across all repos
- Supports **organization** and **personal** accounts
- Rate-limited API client with caching to respect GitHub limits

### Developer Metrics
- Commits per day, active days, PR merge time, review turnaround
- Lines added/removed, issue velocity, review participation
- Per-developer and team-wide views

### AI-Powered Insights
- Identifies **bottlenecks** (slow reviews, large PRs, weekend work patterns)
- Suggests **actionable improvements** for each detected issue
- Predicts **sprint completion** based on velocity trends
- Detects **scope creep** in sprints

### Team Health Score
- **Burnout detection**: flags developers at risk based on commit patterns
- **Workload balance**: measures how evenly work is distributed
- **Collaboration score**: tracks code review participation
- **Velocity trend**: growing, stable, or declining

### Sprint Analytics
- Sprint **burndown charts** rendered in ASCII
- **Velocity tracking** across multiple sprints
- **Sprint completion prediction** with confidence scores
- **Scope creep detection**

### Code Quality Trends
- Track test coverage, bug rate, and tech debt score over time
- Per-repo quality scores computed from commit/PR data

### Activity Heatmap
- **GitHub-style contribution graph** rendered directly in your terminal
- 365-day or custom range views
- Per-developer heatmaps

### Reports
- **Daily, weekly, and monthly** reports
- Multiple output formats: **Terminal (Rich), Markdown, JSON, HTML**
- Auto-generated with AI insights and recommendations
- Save to files or output to stdout

### Goal Tracking
- Set measurable targets (e.g., "10 commits/day", "< 24h PR merge time")
- Track progress with percentage completion
- Get **AI coaching** with specific advice per goal

### REST API
- Full **FastAPI** web server with OpenAPI docs
- Every feature accessible via JSON endpoints
- CORS enabled for web dashboard integration

---

## Screenshots

### Terminal Dashboard
```
  ____             _       ____                  _
 |  _ \ _   _  ___| | __  |  _ \ __ _ _ __   ___| |__
 | | | | | | |/ __| |/ /  | |_) / _` | '_ \ / __| '_ \
 | |_| | |_| | (__|   <   |  __/ (_| | | | | (__| | | |
 |____/ \__,_|\___|_|\_\  |_|   \__,_|_| |_|\___|_| |_|

────────────────────── Overview ───────────────────────

  Date: 2026-04-10
  4 commit(s), 2 PR(s) opened, 1 PR(s) merged

───────────────────── Team Metrics ─────────────────────

┏━━━━━━━━━━━━━━┳━━━━━━━━━┳━━━━━┳━━━━━┳━━━━━━━━━┳━━━━━━━━━━┓
┃ Developer    ┃ Commits ┃ C/D ┃ PRs ┃ Reviews ┃ Merge(h) ┃
┡━━━━━━━━━━━━━━╇━━━━━━━━━╇━━━━━╇━━━━━╇━━━━━━━━━╇━━━━━━━━━━┩
│ Alice        │       3 │ 0.1 │   2 │       1 │     24.0 │
│ Bob          │       1 │ 0.0 │   1 │       1 │     12.0 │
└──────────────┴─────────┴─────┴─────┴─────────┴──────────┘

───────────────────── Team Health ──────────────────────

  Health Score: 72/100
  Workload Balance: 65%
  Collaboration: 80%
  Velocity: stable

  Burnout Risk:
    Alice          ##################-- 90%
    Bob            ####---------------- 20%

──────────────────── AI Insights ───────────────────────

  !! Average PR merge time is 24h. Room for improvement.
     -> Set up PR size guidelines and automated review reminders.

  *  Team health looks good! Keep up the great work.

──────────────────── Activity Heatmap ──────────────────

     Apr May Jun Jul Aug Sep Oct Nov Dec Jan Feb Mar Apr
Mon  .  oo +. .. .o .+ .. o. .. +. .. .o .. .+ .o .. .
Wed  .  .. .+ .. o. .. +. .. .o .. +. .. .o .. .+ .. .
Fri  .  o. .. +. .. .o .. +. .. .o .. +. .. .o .. .+ ..
Sun  .  .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. ..

  Total: 847 commits across 198 active days
```

---

## Quick Start

### Installation

```bash
# Install from PyPI
pip install ai-dev-pulse

# Or clone the repository
git clone https://github.com/theihtisham/dev-pulse.git
cd dev-pulse

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate

# Install dependencies
pip install -e ".[dev]"
```

### Configuration

```bash
# Set your GitHub token (required for GitHub integration)
export DEVPULSE_GITHUB_TOKEN=ghp_your_token_here

# Optional: set your username or organization
export DEVPULSE_GITHUB_USERNAME=your_username
# or
export DEVPULSE_GITHUB_ORG=your_org
```

### Sync Data

```bash
# Sync all accessible repositories
devpulse sync --all

# Sync specific repos
devpulse sync --repos owner/repo1 owner/repo2

# Sync data from the last 90 days
devpulse sync --all --since 2026-01-10
```

### View Dashboard

```bash
# Full interactive dashboard
devpulse dashboard

# Focus on a specific developer
devpulse dashboard --author Alice

# Focus on a specific repo
devpulse dashboard --repo myorg/myrepo
```

---

## CLI Commands

```bash
# Sync GitHub data
devpulse sync --all

# Reports
devpulse daily                          # Today's report
devpulse daily --date 2026-04-01        # Specific date
devpulse daily --format json            # JSON output
devpulse daily --format html --save     # Save as HTML
devpulse weekly                         # This week's report
devpulse monthly                        # This month's report

# Metrics
devpulse metrics --author Alice --days 30   # Developer metrics
devpulse metrics --days 7                   # Team metrics (last week)

# AI Insights
devpulse insights --days 30

# Team Health
devpulse health --days 30

# Activity Heatmap
devpulse heatmap --days 365
devpulse heatmap --author Alice

# Goals
devpulse goals add --title "10 commits/day" --target 10 --metric commits_per_day
devpulse goals list
devpulse goals coach                     # Get AI coaching
devpulse goals delete 1                  # Remove a goal

# Sprint Tracking
devpulse sprint snapshot --name "Sprint 1" --total 30 --completed 10
devpulse sprint burndown --name "Sprint 1"
devpulse sprint predict --name "Sprint 1" --total 30 --elapsed 5 --duration 10

# Code Quality
devpulse quality --repo myorg/myrepo --days 30

# Start API Server
devpulse serve --port 8742

# Interactive Dashboard
devpulse dashboard
```

---

## REST API

Start the API server:

```bash
devpulse serve
```

Then access:

| Endpoint | Method | Description |
|----------|--------|-------------|
| `GET /` | GET | Health check |
| `GET /api/commits` | GET | List commits |
| `GET /api/commits/heatmap` | GET | Commit heatmap data |
| `GET /api/pull-requests` | GET | List pull requests |
| `GET /api/issues` | GET | List issues |
| `GET /api/reviews` | GET | List reviews |
| `GET /api/metrics` | GET | Team metrics |
| `GET /api/metrics/{author}` | GET | Developer metrics |
| `GET /api/health` | GET | Team health analysis |
| `GET /api/insights` | GET | AI-powered insights |
| `GET /api/goals` | GET | List goals |
| `POST /api/goals` | POST | Create a goal |
| `DELETE /api/goals/{id}` | DELETE | Delete a goal |
| `GET /api/goals/coach` | GET | AI goal coaching |
| `POST /api/sprints/snapshot` | POST | Record sprint snapshot |
| `GET /api/sprints/{name}/burndown` | GET | Sprint burndown data |
| `GET /api/sprints/{name}/predict` | GET | Sprint prediction |
| `POST /api/quality/snapshot` | POST | Record quality snapshot |
| `GET /api/quality` | GET | Quality trends |
| `GET /api/quality/{repo}/score` | GET | Quality score |
| `GET /api/reports/daily` | GET | Daily report |
| `GET /api/reports/weekly` | GET | Weekly report |
| `GET /api/reports/monthly` | GET | Monthly report |

Interactive docs available at `http://localhost:8742/docs`

---

## Configuration

All settings are configured via environment variables with the `DEVPULSE_` prefix:

| Variable | Default | Description |
|----------|---------|-------------|
| `DEVPULSE_GITHUB_TOKEN` | (required) | GitHub personal access token |
| `DEVPULSE_GITHUB_USERNAME` | | GitHub username |
| `DEVPULSE_GITHUB_ORG` | | GitHub organization |
| `DEVPULSE_GITHUB_REPOS` | | Comma-separated repo list |
| `DEVPULSE_DATABASE_PATH` | `./devpulse_data/devpulse.db` | SQLite database path |
| `DEVPULSE_API_PORT` | `8742` | API server port |
| `DEVPULSE_GITHUB_RATE_LIMIT_RPM` | `40` | Max GitHub API requests per minute |
| `DEVPULSE_BURNOUT_THRESHOLD` | `0.75` | Burnout risk threshold (0-1) |
| `DEVPULSE_LOG_LEVEL` | `INFO` | Logging level |

---

## Architecture

```
devpulse/
  core/
    config.py           # Settings (env vars, defaults)
    database.py         # SQLite layer (all CRUD)
    models.py           # Pydantic data models
    github_client.py    # GitHub API client (rate-limited, cached)
    analytics.py        # Analytics engine (metrics, insights, predictions)
    report_generator.py # Report generation (Markdown, JSON, HTML)
  cli/
    main.py             # Click CLI commands
    dashboard.py        # Interactive terminal dashboard
    render.py           # Rich rendering helpers (heatmap, charts)
  api/
    app.py              # FastAPI REST API server
  templates/
    report.html         # HTML report template
tests/
  conftest.py           # Shared fixtures
  test_database.py      # Database layer tests
  test_analytics.py     # Analytics engine tests
  test_report_generator.py  # Report generation tests
  test_api.py           # API endpoint tests
  test_config.py        # Configuration tests
  test_models.py        # Model validation tests
  test_cli.py           # CLI command tests
```

---

## Testing

```bash
# Run all tests
pytest

# Run with coverage
pytest --cov=devpulse --cov-report=term-missing

# Run specific test file
pytest tests/test_analytics.py -v

# Run with verbose output
pytest -v --tb=short
```

---

## Security

- **GitHub tokens** are read from environment variables only -- never stored in the database or logs
- All API requests use **HTTPS**
- Rate limiting prevents accidental GitHub API abuse
- **No personal data** is logged when `DEVPULSE_REDACT_SENSITIVE=true`
- SQLite database uses **WAL mode** for safe concurrent access
- Input validation via **Pydantic** on all API endpoints

---

## Tech Stack

| Component | Technology |
|-----------|-----------|
| Language | Python 3.10+ |
| CLI | Click + Rich |
| API | FastAPI + Uvicorn |
| Database | SQLite3 (WAL mode) |
| Data Models | Pydantic v2 |
| Templates | Jinja2 |
| Testing | pytest + httpx |
| HTTP Client | requests |

---

## License

MIT License. See [LICENSE](LICENSE) for details.

---

<p align="center">
  Built with passion for developer productivity.<br>
  <strong>DevPulse</strong> -- Your AI-powered engineering manager.
</p>
