feat: expose review alert endpoints and team-aware analytics

Author: haasonsaas

README.md

@@ -84,6 +84,7 @@ Copy `.env.example` to `.env` and adjust values locally if you prefer dotenv-sty
 | `PROVENANCE_GITHUB_AGENT_LABEL_PREFIX` | PR label prefix used to infer agent IDs | `agent:` |
 | `PROVENANCE_GITHUB_CACHE_TTL_SECONDS` | Cache TTL (seconds) for GitHub metadata lookups | `300` |
 | `PROVENANCE_GITHUB_AGENT_MAP` | JSON map of GitHub logins/keywords to agent IDs | `{}` |
+| `PROVENANCE_GITHUB_REVIEWER_TEAM_MAP` | JSON map of reviewer logins to team names for cohort reporting | `{}` |
 
 ## Detection with Semgrep
 
@@ -150,6 +151,8 @@ Example ingestion payload:
 - `/v1/analytics/summary` now surfaces GitHub-aware metrics alongside the existing risk/volume suite: `code_volume`, `code_churn_rate`, `avg_line_complexity`, `agent_response_rate`, `agent_response_p50_hours`, `agent_response_p90_hours`, `reopened_threads`, `force_push_events`, `rewrite_loops`, `human_followup_commits`, `human_followup_fast`, `ci_time_to_green_hours`, `ci_failed_checks`, `agent_commit_ratio`, `commit_lead_time_hours`, `force_push_after_approval`, `human_reviewer_count`, `avg_human_reviewers`, `avg_unique_reviewers`, `bot_review_events`, `bot_block_events`, `bot_block_overrides`, `bot_block_resolved`, `bot_reviewer_count`, `bot_informational_only_reviewer_count`, `bot_comment_count`, and `classification_<label>_count` (e.g., `classification_security_count`).
 - `/v1/analytics/agents/behavior` returns composite snapshots that now blend code/finding metrics with review conversation health (thread counts, response latency, classification breakdowns), CI friction (failures, time-to-green), commit dynamics (force pushes, rewrite loops, human follow-ups), and attention heatmaps (top paths + hot files) per agent.
 - Snapshots also include reviewer cohort context (`human_reviewer_count`, association breakdowns), bot review behavior (`bot_block_events`, `bot_block_overrides`), provenance anomalies (`force_push_after_approval_count`), and CI failure taxonomy (failing check names and contexts) to highlight operational hotspots.
+- `/v1/analytics/review-alerts` highlights agents/analyses where bot change-requests were overridden or force-pushes occurred post-approval.
+- `/v1/analytics/review-load` reports human vs. bot review load per agent, while `/v1/analytics/review-load/teams` aggregates human reviewer effort by the configured team map.
 - Review-focused metrics (`review_comments`, `unique_reviewers`, `review_events`, `agent_comment_mentions`) continue to leverage GitHub PR data when credentials are supplied; classification metrics reflect the resolver's heuristic labeling of each conversation snippet.
 - Use `PROVENANCE_ANALYTICS_DEFAULT_WINDOW` or query parameters such as `?time_window=14d` to track longer horizons and compare agents.
 

app/core/config.py

@@ -41,6 +41,7 @@ class Settings(BaseSettings):
     github_agent_label_prefix: str = "agent:"
     github_cache_ttl_seconds: int = 300
     github_agent_map: dict[str, str] = Field(default_factory=dict)
+    github_reviewer_team_map: dict[str, str] = Field(default_factory=dict)
 
     model_config = SettingsConfigDict(env_prefix="provenance_", env_file=".env", extra="ignore")
 

app/dependencies.py

@@ -56,6 +56,7 @@ def get_github_resolver() -> GitHubProvenanceResolver | None:
         agent_label_prefix=settings.github_agent_label_prefix,
         cache_ttl_seconds=settings.github_cache_ttl_seconds,
         agent_map=settings.github_agent_map,
+        reviewer_team_map=settings.github_reviewer_team_map,
     )
 
 

app/models/analytics.py

@@ -70,6 +70,8 @@ class AgentBehaviorSnapshot(BaseModel):
     reviewer_association_breakdown: dict[str, int] = Field(
         default_factory=dict, description="Reviewer participation by GitHub association (member, contributor, etc.)."
     )
+    human_reviewer_teams: dict[str, int] = Field(
+        default_factory=dict, description="Human reviewer counts grouped by mapped team.")
     bot_review_events: int = Field(0, description="Total bot-authored review submissions.")
     bot_block_events: int = Field(0, description="Bot reviews that requested changes.")
     bot_informational_events: int = Field(0, description="Bot reviews that left non-blocking feedback.")

app/provenance/github_resolver.py

@@ -65,6 +65,7 @@ def __init__(
         agent_label_prefix: str = "agent:",
         cache_ttl_seconds: int = 300,
         agent_map: dict[str, str] | None = None,
+        reviewer_team_map: dict[str, str] | None = None,
     ) -> None:
         self._agent_label_prefix = agent_label_prefix.lower()
         auth = Token(token)
@@ -74,6 +75,7 @@ def __init__(
             self._client = Github(auth=auth)
         self._cache_ttl = max(cache_ttl_seconds, 30)
         self._agent_map = {k.lower(): v for k, v in (agent_map or {}).items()}
+        self._reviewer_team_map = {k.lower(): v for k, v in (reviewer_team_map or {}).items()}
         self._commit_cache: dict[tuple[str, str], tuple[float, Optional[Commit.Commit]]] = {}
         self._label_cache: dict[tuple[str, int], tuple[float, list[str]]] = {}
         self._comment_cache: dict[tuple[str, int], tuple[float, list[str]]] = {}
@@ -176,6 +178,7 @@ def collect_pr_metadata(
         bot_blocking_reviewers: set[str] = set()
         bot_block_overrides = 0
         bot_block_resolved = 0
+        override_details: list[dict] = []
         for review_entry in reviews_list:
             if not review_entry.get("is_bot"):
                 continue
@@ -198,16 +201,28 @@ def collect_pr_metadata(
                     if later_entry.get("state") in {"APPROVED", "DISMISSED"}:
                         resolved = True
                         break
+            detail = {
+                "bot": login,
+                "submitted_at": review_entry.get("submitted_at"),
+                "state": review_entry.get("state"),
+                "merge_actor": timeline_summary.get("last_merge_actor"),
+                "merged_at": timeline_summary.get("last_merge_at"),
+            }
             if resolved:
                 bot_block_resolved += 1
+                detail["resolved"] = True
             elif merged_at:
                 bot_block_overrides += 1
+                detail["resolved"] = False
+            override_details.append(detail)
 
         conversation_summary["bot_reviewer_count"] = len(bot_reviewers)
         conversation_summary["bot_blocking_reviewer_count"] = len(bot_blocking_reviewers)
         conversation_summary["bot_informational_only_reviewer_count"] = len(bot_reviewers - bot_blocking_reviewers)
         conversation_summary["bot_block_overrides"] = bot_block_overrides
         conversation_summary["bot_block_resolved"] = bot_block_resolved
+        if override_details:
+            conversation_summary["bot_block_override_details"] = override_details
 
         commit_summary = self._summarize_commits(
             pr,
@@ -468,6 +483,17 @@ def _build_conversation_snapshot(self, pr, agent_logins: set[str]) -> dict:
         reviewer_identities = self._merge_identities(
             comments_info.reviewer_identities, reviews_info.reviewer_identities
         )
+        human_team_counts = defaultdict(int)
+        for profile in reviewer_identities.values():
+            if profile.get("is_bot"):
+                continue
+            login = profile.get("login")
+            team = profile.get("team")
+            if not team and login:
+                team = self._reviewer_team_map.get(login.lower())
+            if team:
+                human_team_counts[team] += 1
+                profile["team"] = team
 
         created_at = getattr(pr, "created_at", None)
         merged_at = getattr(pr, "merged_at", None)
@@ -489,6 +515,7 @@ def _build_conversation_snapshot(self, pr, agent_logins: set[str]) -> dict:
             "bot_block_events": reviews_info.bot_block_events,
             "bot_informational_events": reviews_info.bot_informational_events,
             "bot_approval_events": reviews_info.bot_approval_events,
+            "human_reviewer_teams": dict(human_team_counts),
         }
 
         if thread_metrics["response_latencies"]:
@@ -768,6 +795,13 @@ def _extract_user_profile(self, source_obj, login: str) -> dict:
         association = getattr(source_obj, "author_association", None)
         profile["association"] = association
         profile["is_bot"] = self._is_bot_login(login) or (profile.get("type") or "").lower() == "bot"
+        team = None
+        if login:
+            team = self._reviewer_team_map.get(login.lower())
+        if not team and profile.get("company"):
+            team = profile.get("company")
+        if team:
+            profile["team"] = team
         return profile
 
     @staticmethod
@@ -859,6 +893,7 @@ def _collect_timeline(self, repo_full_name: str, pr_number: int, pr=None) -> dic
                 data["summary"]["last_reopen_at"] = created_iso
             elif event_type == "merged":
                 data["summary"]["last_merge_at"] = created_iso
+                data["summary"]["last_merge_actor"] = getattr(getattr(item, "actor", None), "login", None)
             elif event_type == "review_requested":
                 data["summary"]["last_review_request_at"] = created_iso
             elif event_type == "ready_for_review" and data["summary"]["ready_for_review_at"] is None:
@@ -876,6 +911,7 @@ def _collect_timeline(self, repo_full_name: str, pr_number: int, pr=None) -> dic
             "last_force_push_at": data["summary"]["last_force_push_at"],
             "last_reopen_at": data["summary"]["last_reopen_at"],
             "last_merge_at": data["summary"]["last_merge_at"],
+            "last_merge_actor": data["summary"].get("last_merge_actor"),
             "last_review_request_at": data["summary"]["last_review_request_at"],
             "ready_for_review_at": data["summary"]["ready_for_review_at"],
             "converted_to_draft_at": data["summary"]["converted_to_draft_at"],

app/routers/analytics.py

@@ -8,7 +8,13 @@
 
 from app.core.config import settings
 from app.dependencies import get_analytics_service
-from app.schemas.analytics import AnalyticsSummaryResponse, AgentBehaviorResponse
+from app.schemas.analytics import (
+    AnalyticsSummaryResponse,
+    AgentBehaviorResponse,
+    ReviewAlertResponse,
+    ReviewLoadResponse,
+    TeamReviewLoadResponse,
+)
 from app.services.analytics import AnalyticsService
 
 
@@ -59,3 +65,31 @@ def get_agent_behavior_summary(
     except ValueError as exc:
         raise HTTPException(status_code=status.HTTP_422_UNPROCESSABLE_ENTITY, detail=str(exc)) from exc
     return AgentBehaviorResponse(report=report, request_id=f"rq_{uuid.uuid4().hex}")
+
+
+@router.get("/review-alerts", response_model=ReviewAlertResponse)
+def get_review_alerts(
+    time_window: str = Query(..., description="Duration string such as 7d or 24h."),
+    threshold: int = Query(1, ge=1, description="Minimum override/force-push count to surface."),
+    analytics_service: AnalyticsService = Depends(get_analytics_service),
+) -> ReviewAlertResponse:
+    alerts = analytics_service.detect_review_alerts(time_window=time_window, threshold=threshold)
+    return ReviewAlertResponse(alerts=alerts, request_id=f"rq_{uuid.uuid4().hex}")
+
+
+@router.get("/review-load", response_model=ReviewLoadResponse)
+def get_review_load(
+    time_window: str = Query(..., description="Duration string such as 7d or 24h."),
+    analytics_service: AnalyticsService = Depends(get_analytics_service),
+) -> ReviewLoadResponse:
+    load = analytics_service.human_vs_bot_load(time_window=time_window)
+    return ReviewLoadResponse(load=load, request_id=f"rq_{uuid.uuid4().hex}")
+
+
+@router.get("/review-load/teams", response_model=TeamReviewLoadResponse)
+def get_team_review_load(
+    time_window: str = Query(..., description="Duration string such as 7d or 24h."),
+    analytics_service: AnalyticsService = Depends(get_analytics_service),
+) -> TeamReviewLoadResponse:
+    load = analytics_service.team_review_load(time_window=time_window)
+    return TeamReviewLoadResponse(load=load, request_id=f"rq_{uuid.uuid4().hex}")

app/schemas/analytics.py

@@ -29,3 +29,42 @@ class AnalyticsQueryParams(BaseModel):
     group_by: str = Field(..., description="Grouping dimension, e.g. agent_id.")
     category: str | None = Field(None, description="Optional filter for rule category.")
     agent_id: str | None = Field(None, description="Optional filter for specific agent.")
+
+
+class ReviewAlert(BaseModel):
+    agent_id: str
+    bot_block_overrides: int
+    force_push_after_approval: int
+    human_reviewer_count: int
+    bot_block_events: int
+    merge_actor: str | None = None
+    merged_at: str | None = None
+    override_details: list[dict] = Field(default_factory=list)
+
+
+class ReviewAlertResponse(BaseModel):
+    alerts: list[ReviewAlert]
+    request_id: str
+
+
+class ReviewLoadEntry(BaseModel):
+    agent_id: str
+    human_reviewers: int
+    bot_reviews: int
+    bot_block_events: int
+    human_reviewer_teams: dict[str, int] = Field(default_factory=dict)
+
+
+class ReviewLoadResponse(BaseModel):
+    load: list[ReviewLoadEntry]
+    request_id: str
+
+
+class TeamReviewLoadEntry(BaseModel):
+    team: str
+    human_reviewers: int
+
+
+class TeamReviewLoadResponse(BaseModel):
+    load: list[TeamReviewLoadEntry]
+    request_id: str