@theihtisham/dev-pulse 1.0.0 → 1.1.0

package/devpulse/api/app.py

@@ -1,371 +1,371 @@
-"""FastAPI application for DevPulse REST API."""
-
-import os
-from datetime import datetime
-from typing import Any, Optional
-
-from fastapi import FastAPI, HTTPException, Query
-from fastapi.responses import HTMLResponse, JSONResponse
-from fastapi.middleware.cors import CORSMiddleware
-from pydantic import BaseModel
-
-from devpulse.core.database import Database
-from devpulse.core.analytics import AnalyticsEngine
-from devpulse.core.report_generator import ReportGenerator
-
-app = FastAPI(
-    title="DevPulse API",
-    description="AI-powered developer productivity dashboard with GitHub integration.",
-    version="1.0.0",
-    docs_url="/docs",
-    redoc_url="/redoc",
-)
-
-app.add_middleware(
-    CORSMiddleware,
-    allow_origins=["*"],
-    allow_credentials=True,
-    allow_methods=["*"],
-    allow_headers=["*"],
-)
-
-
-def _get_db() -> Database:
-    return Database()
-
-
-def _get_engine() -> AnalyticsEngine:
-    return AnalyticsEngine(db=_get_db())
-
-
-def _get_report_gen() -> ReportGenerator:
-    return ReportGenerator(db=_get_db())
-
-
-# ── Request/Response models ──────────────────────────────────────────
-
-class GoalCreate(BaseModel):
-    title: str
-    description: str = ""
-    target_value: float
-    metric: str
-    deadline: Optional[str] = None
-
-
-class SprintSnapshot(BaseModel):
-    sprint_name: str
-    total_points: float
-    completed_points: float
-    added_points: float = 0.0
-
-
-class QualitySnapshot(BaseModel):
-    repo: str
-    test_coverage: float = 0.0
-    open_bugs: int = 0
-    tech_debt_score: float = 0.0
-    lines_added: int = 0
-    lines_removed: int = 0
-    files_changed: int = 0
-
-
-class HealthResponse(BaseModel):
-    overall_score: float
-    workload_balance: float
-    burnout_risk: dict[str, float]
-    collaboration_score: float
-    velocity_trend: str
-    recommendations: list[str]
-
-
-class MessageResponse(BaseModel):
-    message: str
-    detail: Optional[str] = None
-
-
-# ── Health check ─────────────────────────────────────────────────────
-
-@app.get("/", tags=["health"])
-def root() -> dict[str, str]:
-    """API health check."""
-    return {
-        "name": "DevPulse API",
-        "version": "1.0.0",
-        "status": "healthy",
-        "timestamp": datetime.utcnow().isoformat(),
-    }
-
-
-# ── Commits ──────────────────────────────────────────────────────────
-
-@app.get("/api/commits", tags=["commits"])
-def list_commits(
-    repo: Optional[str] = Query(None),
-    author: Optional[str] = Query(None),
-    since: Optional[str] = Query(None),
-    limit: int = Query(100, ge=1, le=1000),
-) -> list[dict[str, Any]]:
-    """List commits with optional filters."""
-    db = _get_db()
-    return db.get_commits(repo=repo, author=author, since=since, limit=limit)
-
-
-@app.get("/api/commits/heatmap", tags=["commits"])
-def commit_heatmap(
-    author: Optional[str] = Query(None),
-    days: int = Query(365, ge=7, le=730),
-) -> list[dict[str, Any]]:
-    """Get daily commit counts for heatmap visualization."""
-    db = _get_db()
-    return db.get_commit_count_by_day(author=author, days=days)
-
-
-# ── Pull Requests ────────────────────────────────────────────────────
-
-@app.get("/api/pull-requests", tags=["pull-requests"])
-def list_pull_requests(
-    repo: Optional[str] = Query(None),
-    author: Optional[str] = Query(None),
-    state: Optional[str] = Query(None),
-    since: Optional[str] = Query(None),
-    limit: int = Query(100, ge=1, le=500),
-) -> list[dict[str, Any]]:
-    """List pull requests with optional filters."""
-    db = _get_db()
-    return db.get_pull_requests(repo=repo, author=author, state=state, since=since, limit=limit)
-
-
-# ── Issues ───────────────────────────────────────────────────────────
-
-@app.get("/api/issues", tags=["issues"])
-def list_issues(
-    repo: Optional[str] = Query(None),
-    state: Optional[str] = Query(None),
-    since: Optional[str] = Query(None),
-    limit: int = Query(100, ge=1, le=500),
-) -> list[dict[str, Any]]:
-    """List issues with optional filters."""
-    db = _get_db()
-    return db.get_issues(repo=repo, state=state, since=since, limit=limit)
-
-
-# ── Reviews ──────────────────────────────────────────────────────────
-
-@app.get("/api/reviews", tags=["reviews"])
-def list_reviews(
-    repo: Optional[str] = Query(None),
-    author: Optional[str] = Query(None),
-    since: Optional[str] = Query(None),
-    limit: int = Query(100, ge=1, le=500),
-) -> list[dict[str, Any]]:
-    """List code reviews with optional filters."""
-    db = _get_db()
-    return db.get_reviews(repo=repo, author=author, since=since, limit=limit)
-
-
-# ── Metrics ──────────────────────────────────────────────────────────
-
-@app.get("/api/metrics/{author}", tags=["metrics"])
-def get_developer_metrics(
-    author: str,
-    days: int = Query(30, ge=1, le=365),
-    repo: Optional[str] = Query(None),
-) -> dict[str, Any]:
-    """Get comprehensive metrics for a developer."""
-    engine = _get_engine()
-    metrics = engine.developer_metrics(author=author, days=days, repo=repo)
-    return metrics.model_dump()
-
-
-@app.get("/api/metrics", tags=["metrics"])
-def get_team_metrics(
-    days: int = Query(30, ge=1, le=365),
-    repo: Optional[str] = Query(None),
-) -> list[dict[str, Any]]:
-    """Get metrics for all team members."""
-    engine = _get_engine()
-    team = engine.team_metrics(days=days, repo=repo)
-    return [m.model_dump() for m in team]
-
-
-# ── Team Health ──────────────────────────────────────────────────────
-
-@app.get("/api/health", tags=["health"], response_model=HealthResponse)
-def team_health(
-    days: int = Query(30, ge=1, le=365),
-    repo: Optional[str] = Query(None),
-) -> HealthResponse:
-    """Analyze team health and burnout risk."""
-    engine = _get_engine()
-    health = engine.team_health(days=days, repo=repo)
-    return HealthResponse(
-        overall_score=health.overall_score,
-        workload_balance=health.workload_balance,
-        burnout_risk=health.burnout_risk,
-        collaboration_score=health.collaboration_score,
-        velocity_trend=health.velocity_trend,
-        recommendations=health.recommendations,
-    )
-
-
-# ── AI Insights ──────────────────────────────────────────────────────
-
-@app.get("/api/insights", tags=["insights"])
-def get_insights(
-    days: int = Query(30, ge=1, le=365),
-    repo: Optional[str] = Query(None),
-) -> list[dict[str, str]]:
-    """Get AI-powered insights and recommendations."""
-    engine = _get_engine()
-    return engine.generate_insights(days=days, repo=repo)
-
-
-# ── Goals ────────────────────────────────────────────────────────────
-
-@app.get("/api/goals", tags=["goals"])
-def list_goals(status: Optional[str] = Query(None)) -> list[dict[str, Any]]:
-    """List goals."""
-    db = _get_db()
-    return db.get_goals(status=status)
-
-
-@app.post("/api/goals", tags=["goals"], status_code=201)
-def create_goal(goal: GoalCreate) -> dict[str, Any]:
-    """Create a new goal."""
-    db = _get_db()
-    gid = db.upsert_goal(goal.model_dump())
-    return {"id": gid, **goal.model_dump()}
-
-
-@app.delete("/api/goals/{goal_id}", tags=["goals"])
-def delete_goal(goal_id: int) -> MessageResponse:
-    """Delete a goal."""
-    db = _get_db()
-    if db.delete_goal(goal_id):
-        return MessageResponse(message=f"Goal {goal_id} deleted.")
-    raise HTTPException(status_code=404, detail=f"Goal {goal_id} not found.")
-
-
-@app.get("/api/goals/coach", tags=["goals"])
-def goal_coaching(goal_id: Optional[int] = Query(None)) -> list[dict[str, Any]]:
-    """Get AI coaching for goals."""
-    engine = _get_engine()
-    return engine.goal_coaching(goal_id=goal_id)
-
-
-# ── Sprints ──────────────────────────────────────────────────────────
-
-@app.post("/api/sprints/snapshot", tags=["sprints"], status_code=201)
-def create_sprint_snapshot(snapshot: SprintSnapshot) -> MessageResponse:
-    """Record a sprint snapshot."""
-    db = _get_db()
-    db.save_sprint_snapshot({
-        "sprint_name": snapshot.sprint_name,
-        "total_points": snapshot.total_points,
-        "completed_points": snapshot.completed_points,
-        "remaining_points": snapshot.total_points - snapshot.completed_points,
-        "added_points": snapshot.added_points,
-    })
-    return MessageResponse(message=f"Sprint snapshot recorded for '{snapshot.sprint_name}'.")
-
-
-@app.get("/api/sprints/{sprint_name}/burndown", tags=["sprints"])
-def sprint_burndown(sprint_name: str) -> list[dict[str, Any]]:
-    """Get burndown data for a sprint."""
-    engine = _get_engine()
-    return engine.sprint_burndown(sprint_name)
-
-
-@app.get("/api/sprints/{sprint_name}/predict", tags=["sprints"])
-def predict_sprint(
-    sprint_name: str,
-    total: float = Query(...),
-    elapsed: int = Query(...),
-    duration: int = Query(...),
-) -> dict[str, Any]:
-    """Predict sprint completion."""
-    engine = _get_engine()
-    return engine.predict_sprint_completion(sprint_name, total, elapsed, duration)
-
-
-# ── Code Quality ─────────────────────────────────────────────────────
-
-@app.post("/api/quality/snapshot", tags=["quality"], status_code=201)
-def create_quality_snapshot(snapshot: QualitySnapshot) -> MessageResponse:
-    """Record a code quality snapshot."""
-    db = _get_db()
-    db.save_quality_snapshot(snapshot.model_dump())
-    return MessageResponse(message=f"Quality snapshot recorded for '{snapshot.repo}'.")
-
-
-@app.get("/api/quality", tags=["quality"])
-def code_quality_trends(
-    repo: Optional[str] = Query(None),
-    days: int = Query(90, ge=1, le=365),
-) -> list[dict[str, Any]]:
-    """Get code quality trends."""
-    engine = _get_engine()
-    trends = engine.code_quality_trend(repo=repo, days=days)
-    return [t.model_dump() for t in trends]
-
-
-@app.get("/api/quality/score", tags=["quality"])
-def quality_score(
-    repo: str = Query(..., description="Repository full name (e.g. owner/repo)"),
-    days: int = Query(30, ge=1, le=365),
-) -> dict[str, Any]:
-    """Compute aggregate quality score for a repo."""
-    engine = _get_engine()
-    return engine.compute_quality_score(repo=repo, days=days)
-
-
-# ── Reports ──────────────────────────────────────────────────────────
-
-@app.get("/api/reports/daily", tags=["reports"])
-def daily_report(
-    date: Optional[str] = Query(None),
-    author: Optional[str] = Query(None),
-    repo: Optional[str] = Query(None),
-    format: str = Query("json", regex="^(json|markdown|html)$"),
-) -> Any:
-    """Generate a daily report."""
-    gen = _get_report_gen()
-    data = gen.daily_report(target_date=date, author=author, repo=repo)
-    if format == "html":
-        return HTMLResponse(content=gen.to_html(data, "daily"))
-    if format == "markdown":
-        return JSONResponse(content={"markdown": gen.to_markdown(data, "daily")})
-    return data
-
-
-@app.get("/api/reports/weekly", tags=["reports"])
-def weekly_report(
-    week_start: Optional[str] = Query(None),
-    repo: Optional[str] = Query(None),
-    format: str = Query("json", regex="^(json|markdown|html)$"),
-) -> Any:
-    """Generate a weekly report."""
-    gen = _get_report_gen()
-    data = gen.weekly_report(week_start=week_start, repo=repo)
-    if format == "html":
-        return HTMLResponse(content=gen.to_html(data, "weekly"))
-    if format == "markdown":
-        return JSONResponse(content={"markdown": gen.to_markdown(data, "weekly")})
-    return data
-
-
-@app.get("/api/reports/monthly", tags=["reports"])
-def monthly_report(
-    year: Optional[int] = Query(None),
-    month: Optional[int] = Query(None),
-    repo: Optional[str] = Query(None),
-    format: str = Query("json", regex="^(json|markdown|html)$"),
-) -> Any:
-    """Generate a monthly report."""
-    gen = _get_report_gen()
-    data = gen.monthly_report(year=year, month=month, repo=repo)
-    if format == "html":
-        return HTMLResponse(content=gen.to_html(data, "monthly"))
-    if format == "markdown":
-        return JSONResponse(content={"markdown": gen.to_markdown(data, "monthly")})
-    return data
+"""FastAPI application for DevPulse REST API."""
+
+import os
+from datetime import datetime
+from typing import Any, Optional
+
+from fastapi import FastAPI, HTTPException, Query
+from fastapi.responses import HTMLResponse, JSONResponse
+from fastapi.middleware.cors import CORSMiddleware
+from pydantic import BaseModel
+
+from devpulse.core.database import Database
+from devpulse.core.analytics import AnalyticsEngine
+from devpulse.core.report_generator import ReportGenerator
+
+app = FastAPI(
+    title="DevPulse API",
+    description="AI-powered developer productivity dashboard with GitHub integration.",
+    version="1.0.0",
+    docs_url="/docs",
+    redoc_url="/redoc",
+)
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+
+def _get_db() -> Database:
+    return Database()
+
+
+def _get_engine() -> AnalyticsEngine:
+    return AnalyticsEngine(db=_get_db())
+
+
+def _get_report_gen() -> ReportGenerator:
+    return ReportGenerator(db=_get_db())
+
+
+# ── Request/Response models ──────────────────────────────────────────
+
+class GoalCreate(BaseModel):
+    title: str
+    description: str = ""
+    target_value: float
+    metric: str
+    deadline: Optional[str] = None
+
+
+class SprintSnapshot(BaseModel):
+    sprint_name: str
+    total_points: float
+    completed_points: float
+    added_points: float = 0.0
+
+
+class QualitySnapshot(BaseModel):
+    repo: str
+    test_coverage: float = 0.0
+    open_bugs: int = 0
+    tech_debt_score: float = 0.0
+    lines_added: int = 0
+    lines_removed: int = 0
+    files_changed: int = 0
+
+
+class HealthResponse(BaseModel):
+    overall_score: float
+    workload_balance: float
+    burnout_risk: dict[str, float]
+    collaboration_score: float
+    velocity_trend: str
+    recommendations: list[str]
+
+
+class MessageResponse(BaseModel):
+    message: str
+    detail: Optional[str] = None
+
+
+# ── Health check ─────────────────────────────────────────────────────
+
+@app.get("/", tags=["health"])
+def root() -> dict[str, str]:
+    """API health check."""
+    return {
+        "name": "DevPulse API",
+        "version": "1.0.0",
+        "status": "healthy",
+        "timestamp": datetime.utcnow().isoformat(),
+    }
+
+
+# ── Commits ──────────────────────────────────────────────────────────
+
+@app.get("/api/commits", tags=["commits"])
+def list_commits(
+    repo: Optional[str] = Query(None),
+    author: Optional[str] = Query(None),
+    since: Optional[str] = Query(None),
+    limit: int = Query(100, ge=1, le=1000),
+) -> list[dict[str, Any]]:
+    """List commits with optional filters."""
+    db = _get_db()
+    return db.get_commits(repo=repo, author=author, since=since, limit=limit)
+
+
+@app.get("/api/commits/heatmap", tags=["commits"])
+def commit_heatmap(
+    author: Optional[str] = Query(None),
+    days: int = Query(365, ge=7, le=730),
+) -> list[dict[str, Any]]:
+    """Get daily commit counts for heatmap visualization."""
+    db = _get_db()
+    return db.get_commit_count_by_day(author=author, days=days)
+
+
+# ── Pull Requests ────────────────────────────────────────────────────
+
+@app.get("/api/pull-requests", tags=["pull-requests"])
+def list_pull_requests(
+    repo: Optional[str] = Query(None),
+    author: Optional[str] = Query(None),
+    state: Optional[str] = Query(None),
+    since: Optional[str] = Query(None),
+    limit: int = Query(100, ge=1, le=500),
+) -> list[dict[str, Any]]:
+    """List pull requests with optional filters."""
+    db = _get_db()
+    return db.get_pull_requests(repo=repo, author=author, state=state, since=since, limit=limit)
+
+
+# ── Issues ───────────────────────────────────────────────────────────
+
+@app.get("/api/issues", tags=["issues"])
+def list_issues(
+    repo: Optional[str] = Query(None),
+    state: Optional[str] = Query(None),
+    since: Optional[str] = Query(None),
+    limit: int = Query(100, ge=1, le=500),
+) -> list[dict[str, Any]]:
+    """List issues with optional filters."""
+    db = _get_db()
+    return db.get_issues(repo=repo, state=state, since=since, limit=limit)
+
+
+# ── Reviews ──────────────────────────────────────────────────────────
+
+@app.get("/api/reviews", tags=["reviews"])
+def list_reviews(
+    repo: Optional[str] = Query(None),
+    author: Optional[str] = Query(None),
+    since: Optional[str] = Query(None),
+    limit: int = Query(100, ge=1, le=500),
+) -> list[dict[str, Any]]:
+    """List code reviews with optional filters."""
+    db = _get_db()
+    return db.get_reviews(repo=repo, author=author, since=since, limit=limit)
+
+
+# ── Metrics ──────────────────────────────────────────────────────────
+
+@app.get("/api/metrics/{author}", tags=["metrics"])
+def get_developer_metrics(
+    author: str,
+    days: int = Query(30, ge=1, le=365),
+    repo: Optional[str] = Query(None),
+) -> dict[str, Any]:
+    """Get comprehensive metrics for a developer."""
+    engine = _get_engine()
+    metrics = engine.developer_metrics(author=author, days=days, repo=repo)
+    return metrics.model_dump()
+
+
+@app.get("/api/metrics", tags=["metrics"])
+def get_team_metrics(
+    days: int = Query(30, ge=1, le=365),
+    repo: Optional[str] = Query(None),
+) -> list[dict[str, Any]]:
+    """Get metrics for all team members."""
+    engine = _get_engine()
+    team = engine.team_metrics(days=days, repo=repo)
+    return [m.model_dump() for m in team]
+
+
+# ── Team Health ──────────────────────────────────────────────────────
+
+@app.get("/api/health", tags=["health"], response_model=HealthResponse)
+def team_health(
+    days: int = Query(30, ge=1, le=365),
+    repo: Optional[str] = Query(None),
+) -> HealthResponse:
+    """Analyze team health and burnout risk."""
+    engine = _get_engine()
+    health = engine.team_health(days=days, repo=repo)
+    return HealthResponse(
+        overall_score=health.overall_score,
+        workload_balance=health.workload_balance,
+        burnout_risk=health.burnout_risk,
+        collaboration_score=health.collaboration_score,
+        velocity_trend=health.velocity_trend,
+        recommendations=health.recommendations,
+    )
+
+
+# ── AI Insights ──────────────────────────────────────────────────────
+
+@app.get("/api/insights", tags=["insights"])
+def get_insights(
+    days: int = Query(30, ge=1, le=365),
+    repo: Optional[str] = Query(None),
+) -> list[dict[str, str]]:
+    """Get AI-powered insights and recommendations."""
+    engine = _get_engine()
+    return engine.generate_insights(days=days, repo=repo)
+
+
+# ── Goals ────────────────────────────────────────────────────────────
+
+@app.get("/api/goals", tags=["goals"])
+def list_goals(status: Optional[str] = Query(None)) -> list[dict[str, Any]]:
+    """List goals."""
+    db = _get_db()
+    return db.get_goals(status=status)
+
+
+@app.post("/api/goals", tags=["goals"], status_code=201)
+def create_goal(goal: GoalCreate) -> dict[str, Any]:
+    """Create a new goal."""
+    db = _get_db()
+    gid = db.upsert_goal(goal.model_dump())
+    return {"id": gid, **goal.model_dump()}
+
+
+@app.delete("/api/goals/{goal_id}", tags=["goals"])
+def delete_goal(goal_id: int) -> MessageResponse:
+    """Delete a goal."""
+    db = _get_db()
+    if db.delete_goal(goal_id):
+        return MessageResponse(message=f"Goal {goal_id} deleted.")
+    raise HTTPException(status_code=404, detail=f"Goal {goal_id} not found.")
+
+
+@app.get("/api/goals/coach", tags=["goals"])
+def goal_coaching(goal_id: Optional[int] = Query(None)) -> list[dict[str, Any]]:
+    """Get AI coaching for goals."""
+    engine = _get_engine()
+    return engine.goal_coaching(goal_id=goal_id)
+
+
+# ── Sprints ──────────────────────────────────────────────────────────
+
+@app.post("/api/sprints/snapshot", tags=["sprints"], status_code=201)
+def create_sprint_snapshot(snapshot: SprintSnapshot) -> MessageResponse:
+    """Record a sprint snapshot."""
+    db = _get_db()
+    db.save_sprint_snapshot({
+        "sprint_name": snapshot.sprint_name,
+        "total_points": snapshot.total_points,
+        "completed_points": snapshot.completed_points,
+        "remaining_points": snapshot.total_points - snapshot.completed_points,
+        "added_points": snapshot.added_points,
+    })
+    return MessageResponse(message=f"Sprint snapshot recorded for '{snapshot.sprint_name}'.")
+
+
+@app.get("/api/sprints/{sprint_name}/burndown", tags=["sprints"])
+def sprint_burndown(sprint_name: str) -> list[dict[str, Any]]:
+    """Get burndown data for a sprint."""
+    engine = _get_engine()
+    return engine.sprint_burndown(sprint_name)
+
+
+@app.get("/api/sprints/{sprint_name}/predict", tags=["sprints"])
+def predict_sprint(
+    sprint_name: str,
+    total: float = Query(...),
+    elapsed: int = Query(...),
+    duration: int = Query(...),
+) -> dict[str, Any]:
+    """Predict sprint completion."""
+    engine = _get_engine()
+    return engine.predict_sprint_completion(sprint_name, total, elapsed, duration)
+
+
+# ── Code Quality ─────────────────────────────────────────────────────
+
+@app.post("/api/quality/snapshot", tags=["quality"], status_code=201)
+def create_quality_snapshot(snapshot: QualitySnapshot) -> MessageResponse:
+    """Record a code quality snapshot."""
+    db = _get_db()
+    db.save_quality_snapshot(snapshot.model_dump())
+    return MessageResponse(message=f"Quality snapshot recorded for '{snapshot.repo}'.")
+
+
+@app.get("/api/quality", tags=["quality"])
+def code_quality_trends(
+    repo: Optional[str] = Query(None),
+    days: int = Query(90, ge=1, le=365),
+) -> list[dict[str, Any]]:
+    """Get code quality trends."""
+    engine = _get_engine()
+    trends = engine.code_quality_trend(repo=repo, days=days)
+    return [t.model_dump() for t in trends]
+
+
+@app.get("/api/quality/score", tags=["quality"])
+def quality_score(
+    repo: str = Query(..., description="Repository full name (e.g. owner/repo)"),
+    days: int = Query(30, ge=1, le=365),
+) -> dict[str, Any]:
+    """Compute aggregate quality score for a repo."""
+    engine = _get_engine()
+    return engine.compute_quality_score(repo=repo, days=days)
+
+
+# ── Reports ──────────────────────────────────────────────────────────
+
+@app.get("/api/reports/daily", tags=["reports"])
+def daily_report(
+    date: Optional[str] = Query(None),
+    author: Optional[str] = Query(None),
+    repo: Optional[str] = Query(None),
+    format: str = Query("json", regex="^(json|markdown|html)$"),
+) -> Any:
+    """Generate a daily report."""
+    gen = _get_report_gen()
+    data = gen.daily_report(target_date=date, author=author, repo=repo)
+    if format == "html":
+        return HTMLResponse(content=gen.to_html(data, "daily"))
+    if format == "markdown":
+        return JSONResponse(content={"markdown": gen.to_markdown(data, "daily")})
+    return data
+
+
+@app.get("/api/reports/weekly", tags=["reports"])
+def weekly_report(
+    week_start: Optional[str] = Query(None),
+    repo: Optional[str] = Query(None),
+    format: str = Query("json", regex="^(json|markdown|html)$"),
+) -> Any:
+    """Generate a weekly report."""
+    gen = _get_report_gen()
+    data = gen.weekly_report(week_start=week_start, repo=repo)
+    if format == "html":
+        return HTMLResponse(content=gen.to_html(data, "weekly"))
+    if format == "markdown":
+        return JSONResponse(content={"markdown": gen.to_markdown(data, "weekly")})
+    return data
+
+
+@app.get("/api/reports/monthly", tags=["reports"])
+def monthly_report(
+    year: Optional[int] = Query(None),
+    month: Optional[int] = Query(None),
+    repo: Optional[str] = Query(None),
+    format: str = Query("json", regex="^(json|markdown|html)$"),
+) -> Any:
+    """Generate a monthly report."""
+    gen = _get_report_gen()
+    data = gen.monthly_report(year=year, month=month, repo=repo)
+    if format == "html":
+        return HTMLResponse(content=gen.to_html(data, "monthly"))
+    if format == "markdown":
+        return JSONResponse(content={"markdown": gen.to_markdown(data, "monthly")})
+    return data