gitflow-analytics 1.0.3__py3-none-any.whl → 1.3.11__py3-none-any.whl

gitflow_analytics/pm_framework/registry.py

@@ -0,0 +1,333 @@
+"""Platform registry for managing and instantiating PM platform adapters.
+
+This module provides centralized registration and management of platform adapters,
+including instance creation, caching, and capability discovery.
+"""
+
+import logging
+from typing import Any, Optional
+
+from .base import BasePlatformAdapter
+
+# Configure logger for registry
+logger = logging.getLogger(__name__)
+
+
+class PlatformRegistry:
+    """Registry for managing platform adapters.
+
+    WHY: Centralized registry provides a clean way to discover available
+    platforms, manage adapter instances, and ensure consistent initialization
+    patterns across all adapters.
+
+    DESIGN DECISION: Use registry pattern rather than direct imports to enable
+    dynamic adapter discovery and plugin-style architecture. This allows
+    future extensions without modifying core framework code.
+    """
+
+    def __init__(self) -> None:
+        """Initialize the platform registry.
+
+        Creates empty registry for adapter classes and instances.
+        Built-in adapters should be registered during module initialization.
+        """
+        self._adapters: dict[str, type[BasePlatformAdapter]] = {}
+        self._instances: dict[str, BasePlatformAdapter] = {}
+
+        logger.info("Platform registry initialized")
+
+    def register_adapter(
+        self, platform_name: str, adapter_class: type[BasePlatformAdapter]
+    ) -> None:
+        """Register a platform adapter class.
+
+        WHY: Registration allows the framework to discover and use platform
+        adapters without hardcoding imports. This enables a plugin architecture
+        where new adapters can be added by simply registering them.
+
+        Args:
+            platform_name: Unique identifier for the platform (e.g., 'jira').
+            adapter_class: Class that implements BasePlatformAdapter interface.
+
+        Raises:
+            ValueError: If platform_name is already registered or invalid.
+            TypeError: If adapter_class doesn't inherit from BasePlatformAdapter.
+        """
+        if not platform_name or not isinstance(platform_name, str):
+            raise ValueError("Platform name must be a non-empty string")
+
+        if not issubclass(adapter_class, BasePlatformAdapter):
+            raise TypeError(f"Adapter class {adapter_class} must inherit from BasePlatformAdapter")
+
+        if platform_name in self._adapters:
+            logger.warning(f"Overriding existing adapter for platform: {platform_name}")
+
+        self._adapters[platform_name] = adapter_class
+        logger.info(f"Registered adapter for platform: {platform_name}")
+
+    def unregister_adapter(self, platform_name: str) -> None:
+        """Unregister a platform adapter.
+
+        WHY: Allows dynamic removal of adapters, useful for testing or
+        when adapters need to be replaced at runtime.
+
+        Args:
+            platform_name: Platform identifier to unregister.
+        """
+        if platform_name in self._adapters:
+            del self._adapters[platform_name]
+            logger.info(f"Unregistered adapter for platform: {platform_name}")
+
+        # Also remove any existing instance
+        if platform_name in self._instances:
+            del self._instances[platform_name]
+            logger.info(f"Removed cached instance for platform: {platform_name}")
+
+    def get_available_platforms(self) -> list[str]:
+        """Get list of available platform names.
+
+        WHY: Allows discovery of available platforms for configuration
+        validation and user interface generation.
+
+        Returns:
+            List of registered platform identifiers.
+        """
+        return list(self._adapters.keys())
+
+    def is_platform_available(self, platform_name: str) -> bool:
+        """Check if a platform adapter is available.
+
+        Args:
+            platform_name: Platform identifier to check.
+
+        Returns:
+            True if platform adapter is registered, False otherwise.
+        """
+        return platform_name in self._adapters
+
+    def get_platform_capabilities(self, platform_name: str) -> Optional[dict[str, Any]]:
+        """Get capabilities for a platform without instantiating it.
+
+        WHY: Allows capability discovery for configuration validation and
+        feature planning without the overhead of authentication and connection.
+
+        Args:
+            platform_name: Platform identifier to check capabilities for.
+
+        Returns:
+            Dictionary of capabilities, or None if platform not found.
+        """
+        if platform_name not in self._adapters:
+            logger.warning(f"Platform not found: {platform_name}")
+            return None
+
+        try:
+            # Create temporary instance to get capabilities
+            adapter_class = self._adapters[platform_name]
+            temp_adapter = adapter_class({})  # Empty config for capability check only
+            capabilities = temp_adapter._get_capabilities()
+
+            return {
+                "supports_projects": capabilities.supports_projects,
+                "supports_issues": capabilities.supports_issues,
+                "supports_sprints": capabilities.supports_sprints,
+                "supports_time_tracking": capabilities.supports_time_tracking,
+                "supports_story_points": capabilities.supports_story_points,
+                "supports_custom_fields": capabilities.supports_custom_fields,
+                "supports_issue_linking": capabilities.supports_issue_linking,
+                "supports_comments": capabilities.supports_comments,
+                "supports_attachments": capabilities.supports_attachments,
+                "supports_workflows": capabilities.supports_workflows,
+                "supports_bulk_operations": capabilities.supports_bulk_operations,
+                "rate_limit_requests_per_hour": capabilities.rate_limit_requests_per_hour,
+                "rate_limit_burst_size": capabilities.rate_limit_burst_size,
+                "max_results_per_page": capabilities.max_results_per_page,
+                "supports_cursor_pagination": capabilities.supports_cursor_pagination,
+            }
+        except Exception as e:
+            logger.error(f"Failed to get capabilities for {platform_name}: {e}")
+            return None
+
+    def create_adapter(self, platform_name: str, config: dict[str, Any]) -> BasePlatformAdapter:
+        """Create and configure a platform adapter instance.
+
+        WHY: Centralized instance creation ensures consistent initialization
+        patterns and enables caching for performance. Authentication is
+        performed during creation to fail fast on configuration issues.
+
+        Args:
+            platform_name: Platform identifier to create adapter for.
+            config: Platform-specific configuration including credentials.
+
+        Returns:
+            Configured and authenticated adapter instance.
+
+        Raises:
+            ValueError: If platform is not registered.
+            ConnectionError: If authentication fails.
+            Exception: If adapter initialization fails.
+        """
+        if platform_name not in self._adapters:
+            available = ", ".join(self.get_available_platforms())
+            raise ValueError(f"Unknown platform: {platform_name}. Available platforms: {available}")
+
+        logger.info(f"Creating adapter for platform: {platform_name}")
+
+        try:
+            adapter_class = self._adapters[platform_name]
+            adapter = adapter_class(config)
+
+            # Test authentication during creation
+            logger.info(f"Authenticating with {platform_name}...")
+            if not adapter.authenticate():
+                raise ConnectionError(f"Failed to authenticate with {platform_name}")
+
+            # Test connection to validate configuration
+            connection_info = adapter.test_connection()
+            if connection_info.get("status") != "connected":
+                error_msg = connection_info.get("error", "Unknown connection error")
+                raise ConnectionError(f"Connection test failed for {platform_name}: {error_msg}")
+
+            # Cache the instance for reuse
+            self._instances[platform_name] = adapter
+            logger.info(f"Successfully created and cached adapter for {platform_name}")
+
+            return adapter
+
+        except Exception as e:
+            logger.error(f"Failed to create adapter for {platform_name}: {e}")
+            # Remove failed instance from cache
+            if platform_name in self._instances:
+                del self._instances[platform_name]
+            raise
+
+    def get_adapter(self, platform_name: str) -> Optional[BasePlatformAdapter]:
+        """Get existing adapter instance from cache.
+
+        WHY: Reusing adapter instances avoids repeated authentication and
+        connection setup, improving performance for multiple operations.
+
+        Args:
+            platform_name: Platform identifier to retrieve adapter for.
+
+        Returns:
+            Cached adapter instance, or None if not found or not cached.
+        """
+        return self._instances.get(platform_name)
+
+    def remove_adapter_instance(self, platform_name: str) -> None:
+        """Remove adapter instance from cache.
+
+        WHY: Allows forcing recreation of adapter instances, useful when
+        configuration changes or connection issues require fresh authentication.
+
+        Args:
+            platform_name: Platform identifier to remove from cache.
+        """
+        if platform_name in self._instances:
+            del self._instances[platform_name]
+            logger.info(f"Removed cached adapter instance for {platform_name}")
+
+    def clear_all_instances(self) -> None:
+        """Clear all cached adapter instances.
+
+        WHY: Useful for cleanup operations, testing, or when configuration
+        changes require fresh adapter creation.
+        """
+        instance_count = len(self._instances)
+        self._instances.clear()
+        logger.info(f"Cleared {instance_count} cached adapter instances")
+
+    def validate_config(self, platform_name: str, config: dict[str, Any]) -> dict[str, Any]:
+        """Validate configuration for a platform without creating full adapter.
+
+        WHY: Allows configuration validation during setup or testing without
+        the overhead of full adapter creation and authentication.
+
+        Args:
+            platform_name: Platform identifier to validate config for.
+            config: Configuration to validate.
+
+        Returns:
+            Dictionary with validation results including status and any errors.
+        """
+        if platform_name not in self._adapters:
+            return {
+                "valid": False,
+                "error": f"Unknown platform: {platform_name}",
+                "missing_fields": [],
+                "invalid_fields": [],
+            }
+
+        try:
+            # Get adapter class to check required config fields
+            adapter_class = self._adapters[platform_name]
+
+            # Create instance with config for basic validation
+            # Note: This doesn't call authenticate() to avoid side effects
+            temp_adapter = adapter_class(config)
+
+            # Basic validation passed if we got here
+            return {
+                "valid": True,
+                "platform_name": temp_adapter.platform_name,
+                "capabilities": self.get_platform_capabilities(platform_name),
+                "missing_fields": [],
+                "invalid_fields": [],
+            }
+
+        except KeyError as e:
+            return {
+                "valid": False,
+                "error": f"Missing required configuration field: {str(e)}",
+                "missing_fields": [str(e)],
+                "invalid_fields": [],
+            }
+        except ValueError as e:
+            return {
+                "valid": False,
+                "error": f"Invalid configuration value: {str(e)}",
+                "missing_fields": [],
+                "invalid_fields": [str(e)],
+            }
+        except Exception as e:
+            return {
+                "valid": False,
+                "error": f"Configuration validation failed: {str(e)}",
+                "missing_fields": [],
+                "invalid_fields": [],
+            }
+
+    def get_registry_status(self) -> dict[str, Any]:
+        """Get current registry status and statistics.
+
+        WHY: Provides diagnostic information for monitoring and debugging
+        the registry state, useful for administration and troubleshooting.
+
+        Returns:
+            Dictionary containing registry statistics and status information.
+        """
+        active_instances = {}
+        for platform_name, adapter in self._instances.items():
+            try:
+                # Test if cached instance is still valid
+                connection_info = adapter.test_connection()
+                active_instances[platform_name] = {
+                    "status": connection_info.get("status", "unknown"),
+                    "platform": adapter.platform_name,
+                    "capabilities_count": sum(
+                        1
+                        for k, v in vars(adapter.capabilities).items()
+                        if k.startswith("supports_") and v
+                    ),
+                }
+            except Exception as e:
+                active_instances[platform_name] = {"status": "error", "error": str(e)}
+
+        return {
+            "registered_platforms": len(self._adapters),
+            "available_platforms": self.get_available_platforms(),
+            "cached_instances": len(self._instances),
+            "active_instances": active_instances,
+            "registry_initialized": True,
+        }

gitflow_analytics/qualitative/__init__.py

@@ -6,25 +6,24 @@ file changes.
 
 Key Components:
 - QualitativeProcessor: Main orchestrator for qualitative analysis
-- NLPEngine: spaCy-based fast processing for most commits  
+- EnhancedQualitativeAnalyzer: Advanced multi-dimensional analysis for executives, projects, developers, and workflows
+- NLPEngine: spaCy-based fast processing for most commits
 - LLMFallback: Strategic use of LLMs for uncertain cases
 - Various classifiers for change type, domain, risk, and intent analysis
 """
 
 from .core.processor import QualitativeProcessor
-from .models.schemas import (
-    QualitativeCommitData,
-    QualitativeConfig,
-    NLPConfig,
-    LLMConfig,
-    CacheConfig as QualitativeCacheConfig,
-)
+
+# from .enhanced_analyzer import EnhancedQualitativeAnalyzer  # Commented out - missing dependencies
+from .models.schemas import CacheConfig as QualitativeCacheConfig
+from .models.schemas import LLMConfig, NLPConfig, QualitativeCommitData, QualitativeConfig
 
 __all__ = [
     "QualitativeProcessor",
-    "QualitativeCommitData", 
+    # "EnhancedQualitativeAnalyzer",  # Commented out - missing dependencies
+    "QualitativeCommitData",
     "QualitativeConfig",
     "NLPConfig",
     "LLMConfig",
     "QualitativeCacheConfig",
-]
+]

gitflow_analytics/qualitative/chatgpt_analyzer.py

@@ -0,0 +1,259 @@
+"""ChatGPT-based qualitative analysis for GitFlow Analytics.
+
+This module uses OpenAI's ChatGPT-4.1 to generate insightful executive summaries
+based on comprehensive GitFlow Analytics data.
+"""
+
+import json
+import logging
+import os
+from pathlib import Path
+from typing import Any, Optional
+
+import requests
+
+logger = logging.getLogger(__name__)
+
+
+class ChatGPTQualitativeAnalyzer:
+    """Generate qualitative insights using ChatGPT-4.1."""
+
+    def __init__(self, api_key: Optional[str] = None):
+        """Initialize the ChatGPT analyzer.
+
+        Args:
+            api_key: API key. If not provided, uses OPENROUTER_API_KEY or OPENAI_API_KEY env var.
+        """
+        self.api_key = api_key or os.getenv("OPENROUTER_API_KEY") or os.getenv("OPENAI_API_KEY")
+        if not self.api_key:
+            raise ValueError(
+                "API key not provided. Set OPENROUTER_API_KEY or OPENAI_API_KEY environment variable."
+            )
+
+        # Check if this is an OpenRouter key
+        self.use_openrouter = self.api_key.startswith("sk-or-")
+        if self.use_openrouter:
+            self.api_url = "https://openrouter.ai/api/v1/chat/completions"
+            self.model = "openai/gpt-4-turbo-preview"  # OpenRouter model name
+        else:
+            # Fallback to OpenAI direct
+            from openai import OpenAI
+
+            self.client = OpenAI(api_key=self.api_key)
+            self.model = "gpt-4-turbo-preview"
+
+    def generate_executive_summary(self, comprehensive_data: dict[str, Any]) -> str:
+        """Generate a qualitative executive summary from comprehensive export data.
+
+        Args:
+            comprehensive_data: The comprehensive JSON export data
+
+        Returns:
+            A markdown-formatted executive summary with qualitative insights
+        """
+        # Extract key metrics for the prompt
+        summary_data = self._extract_summary_data(comprehensive_data)
+
+        # Create the prompt
+        prompt = self._create_executive_summary_prompt(summary_data)
+
+        try:
+            # Call ChatGPT
+            messages = [
+                {
+                    "role": "system",
+                    "content": "You are a data-driven software development analyst providing objective insights on team productivity and project health. Use factual, analytical language. Strictly avoid: promotional language, subjective assessments, marketing terms, superlatives (best, worst, great, poor), praise words (impressive, commendable, excellent, strong, effective), emotional qualifiers (positive, negative, concerning), interpretive language (suggests, indicates potential, appears to show). Report only measurable patterns, quantifiable trends, and evidence-based observations. Use neutral technical terminology. Present findings as statistical facts without subjective interpretation.",
+                },
+                {"role": "user", "content": prompt},
+            ]
+
+            if self.use_openrouter:
+                # Use OpenRouter API
+                headers = {
+                    "Authorization": f"Bearer {self.api_key}",
+                    "Content-Type": "application/json",
+                    "HTTP-Referer": "https://github.com/EWTN-Global/gitflow-analytics",
+                    "X-Title": "GitFlow Analytics",
+                }
+
+                data = {
+                    "model": self.model,
+                    "messages": messages,
+                    "max_tokens": 1500,
+                    "temperature": 0.7,
+                }
+
+                response = requests.post(self.api_url, headers=headers, json=data)
+                response.raise_for_status()
+                result = response.json()
+                content = result["choices"][0]["message"]["content"]
+            else:
+                # Use OpenAI directly
+                response = self.client.chat.completions.create(
+                    model=self.model, messages=messages, temperature=0.7, max_tokens=1500
+                )
+                content = response.choices[0].message.content
+
+            return content
+
+        except Exception as e:
+            logger.error(f"Error generating ChatGPT summary: {e}")
+            return self._generate_fallback_summary(summary_data)
+
+    def _extract_summary_data(self, data: dict[str, Any]) -> dict[str, Any]:
+        """Extract key data points for the executive summary."""
+
+        exec_summary = data.get("executive_summary", {})
+        metadata = data.get("metadata", {})
+        projects = data.get("projects", {})
+        developers = data.get("developers", {})
+
+        # Get top contributors
+        top_developers = []
+        for _dev_id, dev_data in developers.items():
+            identity = dev_data.get("identity", {})
+            summary = dev_data.get("summary", {})
+            top_developers.append(
+                {
+                    "name": identity.get("name", "Unknown"),
+                    "commits": summary.get("total_commits", 0),
+                    "story_points": summary.get("total_story_points", 0),
+                    "projects": len(dev_data.get("projects", {})),
+                }
+            )
+        top_developers.sort(key=lambda x: x["commits"], reverse=True)
+
+        # Get project health
+        project_health = []
+        for proj_key, proj_data in projects.items():
+            health = proj_data.get("health_score", {})
+            summary = proj_data.get("summary", {})
+            project_health.append(
+                {
+                    "name": proj_key,
+                    "health_score": health.get("overall", 0),
+                    "health_rating": health.get("rating", "unknown"),
+                    "commits": summary.get("total_commits", 0),
+                    "contributors": summary.get("total_contributors", 0),
+                }
+            )
+        project_health.sort(key=lambda x: x["commits"], reverse=True)
+
+        return {
+            "period_weeks": metadata.get("analysis_weeks", 0),
+            "total_commits": exec_summary.get("key_metrics", {}).get("commits", {}).get("total", 0),
+            "total_developers": exec_summary.get("key_metrics", {})
+            .get("developers", {})
+            .get("total", 0),
+            "lines_changed": exec_summary.get("key_metrics", {})
+            .get("lines_changed", {})
+            .get("total", 0),
+            "story_points": exec_summary.get("key_metrics", {})
+            .get("story_points", {})
+            .get("total", 0),
+            "ticket_coverage": exec_summary.get("key_metrics", {})
+            .get("ticket_coverage", {})
+            .get("percentage", 0),
+            "team_health_score": exec_summary.get("health_score", {}).get("overall", 0),
+            "team_health_rating": exec_summary.get("health_score", {}).get("rating", "unknown"),
+            "top_developers": top_developers[:5],
+            "project_health": project_health[:5],
+            "velocity_trend": exec_summary.get("trends", {})
+            .get("velocity", {})
+            .get("direction", "stable"),
+            "wins": exec_summary.get("wins", [])[:3],
+            "concerns": exec_summary.get("concerns", [])[:3],
+            "anomalies": data.get("anomaly_detection", {}).get("anomalies", [])[:3],
+        }
+
+    def _create_executive_summary_prompt(self, summary_data: dict[str, Any]) -> str:
+        """Create the prompt for ChatGPT."""
+
+        prompt = f"""Based on the following GitFlow Analytics data from the past {summary_data['period_weeks']} weeks, provide a comprehensive executive summary with qualitative insights:
+
+## Key Metrics:
+- Total Commits: {summary_data['total_commits']:,}
+- Active Developers: {summary_data['total_developers']}
+- Lines Changed: {summary_data['lines_changed']:,}
+- Story Points Delivered: {summary_data['story_points']}
+- Ticket Coverage: {summary_data['ticket_coverage']:.1f}%
+- Team Health Score: {summary_data['team_health_score']:.1f}/100 ({summary_data['team_health_rating']})
+- Velocity Trend: {summary_data['velocity_trend']}
+
+## Top Contributors:
+"""
+
+        for dev in summary_data["top_developers"]:
+            prompt += f"- {dev['name']}: {dev['commits']} commits, {dev['story_points']} story points across {dev['projects']} projects\n"
+
+        prompt += "\n## Project Health:\n"
+        for proj in summary_data["project_health"]:
+            prompt += f"- {proj['name']}: Health {proj['health_score']:.1f}/100 ({proj['health_rating']}), {proj['commits']} commits, {proj['contributors']} contributors\n"
+
+        if summary_data["wins"]:
+            prompt += "\n## Recent Wins:\n"
+            for win in summary_data["wins"]:
+                prompt += f"- {win.get('title', 'Achievement')}: {win.get('description', '')}\n"
+
+        if summary_data["concerns"]:
+            prompt += "\n## Areas of Concern:\n"
+            for concern in summary_data["concerns"]:
+                prompt += f"- {concern.get('title', 'Issue')}: {concern.get('description', '')}\n"
+
+        if summary_data["anomalies"]:
+            prompt += "\n## Detected Anomalies:\n"
+            for anomaly in summary_data["anomalies"]:
+                prompt += f"- {anomaly.get('type', 'anomaly')} in {anomaly.get('metric', 'unknown')}: {anomaly.get('description', '')}\n"
+
+        prompt += """
+Provide a technical analysis with:
+1. A 2-3 paragraph data summary reporting team output patterns, work distribution, and process metrics
+2. Quantitative observations about team dynamics derived from the metrics (commit frequency, ticket coverage ratios, health score calculations)
+3. 3-5 specific, data-driven recommendations with measurable targets based on metric thresholds
+4. Observable patterns in the data that deviate from baseline measurements (if applicable)
+
+Report only statistical patterns, measurable trends, and process gaps. Use factual technical language. Base all statements on quantifiable metrics and their mathematical relationships. Avoid subjective interpretations or assessments.
+"""
+
+        return prompt
+
+    def _generate_fallback_summary(self, summary_data: dict[str, Any]) -> str:
+        """Generate a basic summary if ChatGPT fails."""
+
+        return f"""## Executive Summary
+
+Over the past {summary_data['period_weeks']} weeks, the development team generated {summary_data['total_commits']:,} commits across {summary_data['total_developers']} active developers.
+
+The team health score measured {summary_data['team_health_score']:.1f}/100 ({summary_data['team_health_rating']}). Ticket coverage reached {summary_data['ticket_coverage']:.1f}% of total commits with trackable references.
+
+### Measured Outputs:
+- Code changes: {summary_data['lines_changed']:,} lines modified
+- Story points completed: {summary_data['story_points']}
+- Velocity trend: {summary_data['velocity_trend']}
+
+### Process Recommendations:
+1. {'Maintain current output rate' if summary_data['velocity_trend'] == 'increasing' else 'Analyze velocity decline factors'}
+2. {'Sustain current tracking rate' if summary_data['ticket_coverage'] > 60 else 'Increase commit-ticket linking to reach 70% coverage target'}
+3. Review projects with health scores below 60/100 for process gaps
+
+*Note: This is a fallback summary. For detailed analysis, configure ChatGPT integration.*
+"""
+
+
+def generate_chatgpt_summary(json_file_path: Path, api_key: Optional[str] = None) -> str:
+    """Convenience function to generate a ChatGPT summary from a JSON export file.
+
+    Args:
+        json_file_path: Path to the comprehensive JSON export
+        api_key: Optional OpenAI API key
+
+    Returns:
+        Markdown-formatted executive summary
+    """
+    # Load the JSON data
+    with open(json_file_path) as f:
+        comprehensive_data = json.load(f)
+
+    # Generate summary
+    analyzer = ChatGPTQualitativeAnalyzer(api_key)
+    return analyzer.generate_executive_summary(comprehensive_data)

gitflow_analytics/qualitative/classifiers/__init__.py

@@ -1,13 +1,13 @@
 """Classification components for qualitative analysis."""
 
 from .change_type import ChangeTypeClassifier
-from .domain_classifier import DomainClassifier  
+from .domain_classifier import DomainClassifier
 from .intent_analyzer import IntentAnalyzer
 from .risk_analyzer import RiskAnalyzer
 
 __all__ = [
     "ChangeTypeClassifier",
     "DomainClassifier",
-    "IntentAnalyzer", 
+    "IntentAnalyzer",
     "RiskAnalyzer",
-]
+]