A domain-agnostic tool for generating professional KPI reports from git repository metrics. Analyze release history, commit counts, and line changes across multiple microservice repositories with console output, HTML reports, and embedded data visualizations.
- 📊 Git Metrics Analysis - Extract semantic version tags, count commits, and track line changes between releases
- 📈 Data Visualization - Generate professional charts with matplotlib (activity, volume, comparisons, timelines)
- 📄 HTML Reports - Professional, print-ready HTML reports with embedded CSS and charts
- ⚙️ Flexible Configuration - YAML-based configuration with support for private organization data
- 🎯 File Exclusions - Smart filtering to exclude lock files, minified assets, and dependencies
- ⚡ Fast Testing - Comprehensive test suite with mocked unit tests (~1s) and integration tests
- 🔧 CLI Interface - Command-line arguments for output format and period selection
All git repositories to be analyzed must be located in the same parent directory specified by projects_directory in your configuration file.
The tool looks for repositories using this structure:
projects_directory/
├── service-1/ # Git repository 1
│ └── .git/
├── service-2/ # Git repository 2
│ └── .git/
└── service-3/ # Git repository 3
└── .git/
Example Configuration:
# config.yaml
projects_directory: /Users/username/projects
included_projects:
- service-1 # Must exist at: /Users/username/projects/service-1
- service-2 # Must exist at: /Users/username/projects/service-2
- service-3 # Must exist at: /Users/username/projects/service-3If a repository is not found in the projects_directory, it will be skipped with a warning:
⚠️ SKIP: service-name (not found at /Users/username/projects/service-name)
- Python 3.10+
- Git repositories with semantic versioning tags
- Virtual environment (recommended)
# Clone the repository
git clone https://github.com/edwardselby/kpi.git
cd kpi
# Create and activate virtual environment
python -m venv .venv
source .venv/bin/activate # On Windows: .venv\Scripts\activate
# Install package in development mode
pip install -e .This installs all dependencies and creates a kpi console command.
The tool uses a hierarchical configuration system:
- config.local.yaml (if exists) - Your private organization configuration
- config.yaml (fallback) - Public template with generic examples
# Copy the template
cp config.yaml config.local.yaml
# Edit with your organization's services
nano config.local.yamlThe config.local.yaml file is gitignored and safe for private data.
# config.yaml
projects_directory: ./projects
included_projects:
- api-gateway-service
- user-service
- payment-service
file_exclusions:
- "*.lock"
- "*.min.js"
- "node_modules/*"
- "dist/*"# Console output (default)
kpi
# Generate HTML report
kpi --html
# Generate report for specific period
kpi --html --period 2025-11
# Get help
kpi --helpGenerate a text-based report to your terminal:
kpiSample Output:
======================================================================
KPI Report Generator
======================================================================
Configuration: config.yaml
Projects directory: /Users/username/projects
Analyzing 3 projects...
📦 api-gateway-service
----------------------------------------------------------------------
2.1.0 2025-12-02 (latest)
2.0.5 2025-10-23 → 45 commits (+8,234 / -342 lines)
2.0.4 2025-10-23 → 3 commits (+512 / -28 lines)
2.0.0 2025-10-15 → 12 commits (+2,145 / -623 lines)
Generate professional HTML reports with embedded visualizations:
# All-time report
kpi --html
# Specific month
kpi --html --period 2025-11
# Specific quarter
kpi --html --period 2025-Q4
# Custom output directory
kpi --html -o ./reportsOutput:
✅ HTML report generated: reports/kpi-report-all.html
Open in browser: file:///path/to/kpi-report-generator/reports/kpi-report-all.html
HTML Report Features:
- 📊 Summary cards (total releases, commits, lines added/removed)
- 📈 Visual charts (6 embedded matplotlib visualizations)
- 📋 Per-service breakdown tables
- 📜 Complete release history
- 🎨 Professional styling with gradient headers
- 🖨️ Print-ready with optimized page breaks
- 🔗 No external dependencies (all CSS and charts embedded)
# macOS
open reports/kpi-report-all.html
# Linux
xdg-open reports/kpi-report-all.html
# Windows
start reports/kpi-report-all.html- Open HTML report in browser
- File → Print (or Cmd/Ctrl+P)
- Select "Save as PDF"
- Layout automatically optimized for print
# Path to directory containing repositories
projects_directory: /path/to/repos
# Projects to analyze (whitelist)
included_projects:
- project-1
- project-2
# Files to exclude from line counts
file_exclusions:
- "*.lock"
- "*.min.js"
- "*.min.css"
- "node_modules/*"
- "dist/*"
- "build/*"
- "migrations/*"
- "package-lock.json"
# Valid git branches for analysis
valid_branches:
- main
- master
- dev
# Optional: Service metadata for enhanced reporting
service_metadata:
api-gateway-service:
category: "Core Infrastructure"
tags: ["API", "routing", "orchestration"]
description: "Central API gateway for request routing"The tool supports flexible exclusion patterns:
- Wildcards:
*.lock,*.min.js - Directories:
node_modules/*,dist/* - Specific files:
package-lock.json
The configuration loader checks files in this order:
config.local.yaml(if exists) - Private organization configconfig.yaml(fallback) - Public template
This allows you to keep private organization data in config.local.yaml (gitignored) while maintaining a generic public template.
Service metadata enables rich executive summaries and intelligent narrative generation by categorizing your microservices and defining their technical characteristics.
Each service can have:
- category: High-level grouping (Core Infrastructure, Domain Services, User Features, Supporting Services)
- tags: Technical characteristics for detailed analysis
- description: Human-readable purpose of the service
service_metadata:
# Core Infrastructure - Critical business systems
product-catalog-service:
category: "Core Infrastructure"
tags: ["API", "database", "search", "caching"]
description: "Product catalog with search and recommendations"
inventory-management-service:
category: "Core Infrastructure"
tags: ["inventory", "database", "real_time", "API"]
description: "Real-time inventory tracking and allocation"
# Domain Services - Business logic
pricing-engine-service:
category: "Domain Services"
tags: ["domain_logic", "calculation", "API"]
description: "Dynamic pricing and promotion calculation engine"
order-orchestrator-service:
category: "Domain Services"
tags: ["orchestration", "domain_logic", "transaction_processing"]
description: "Order workflow orchestration and fulfillment coordination"
# User Features - Customer-facing
shopping-cart-service:
category: "User Features"
tags: ["user_interface", "real_time", "API"]
description: "Shopping cart and checkout experience"
payment-gateway-service:
category: "User Features"
tags: ["transaction_processing", "security", "API", "integration"]
description: "Payment processing and fraud detection"
# Supporting Services - Infrastructure
notification-service:
category: "Supporting Services"
tags: ["messaging", "email", "infrastructure"]
description: "Multi-channel customer notifications"
analytics-service:
category: "Supporting Services"
tags: ["analytics", "data_processing", "monitoring"]
description: "Customer behavior analytics and reporting"
# Tag descriptions for narrative generation
tag_descriptions:
API: "API development"
database: "database operations"
search: "search functionality"
caching: "caching layer"
inventory: "inventory management"
real_time: "real-time processing"
domain_logic: "business logic"
calculation: "calculation engine"
orchestration: "service coordination"
transaction_processing: "transaction handling"
user_interface: "user-facing features"
security: "security features"
integration: "external integrations"
messaging: "messaging systems"
email: "email delivery"
infrastructure: "infrastructure support"
analytics: "analytics capabilities"
data_processing: "data pipeline"
monitoring: "monitoring systems"
# Tag grouping for service layer analysis
tag_groups:
service_layers:
data_layer: ["database", "caching", "data_processing"]
presentation_layer: ["API", "user_interface"]
business_layer: ["domain_logic", "transaction_processing", "calculation"]
infrastructure_layer: ["orchestration", "integration", "messaging"]
technical_characteristics:
real_time_services: ["real_time", "inventory"]
batch_services: ["data_processing", "analytics"]
user_facing: ["user_interface", "API"]
backend_services: ["database", "messaging", "monitoring"]
# Category priority for narrative (most important first)
category_priority:
- "Core Infrastructure"
- "Domain Services"
- "User Features"
- "Supporting Services"service_metadata:
user-auth-service:
category: "Core Infrastructure"
tags: ["authentication", "security", "API"]
description: "User authentication and session management"
subscription-service:
category: "Domain Services"
tags: ["domain_logic", "billing", "transaction_processing"]
description: "Subscription lifecycle and tier management"
billing-service:
category: "Domain Services"
tags: ["transaction_processing", "integration", "API"]
description: "Payment processing and invoice generation"
workspace-service:
category: "User Features"
tags: ["user_interface", "collaboration", "real_time"]
description: "Collaborative workspace management"
reporting-dashboard-service:
category: "User Features"
tags: ["analytics", "data_presentation", "user_interface"]
description: "Customer-facing analytics and reporting"
email-service:
category: "Supporting Services"
tags: ["messaging", "infrastructure", "integration"]
description: "Transactional email delivery"
tag_descriptions:
authentication: "authentication services"
security: "security features"
billing: "billing operations"
collaboration: "collaboration features"
data_presentation: "data visualization"The tool uses this metadata to generate executive summaries like:
Example Output:
Executive Summary:
- Core Infrastructure saw the most activity with 45 releases across
authentication services and API development
- Domain Services focused on billing operations and business logic (28 releases)
- User-facing features received 15 releases improving collaboration features
and data visualization
- Top contributor: user-auth-service (authentication services, security features)
- Consistent Categories: Use the same 4 categories across your organization
- Meaningful Tags: Choose tags that reflect technical characteristics, not service names
- Tag Descriptions: Keep descriptions concise and action-oriented
- Layer Grouping: Organize tags into logical layers for architectural insights
- Priority Order: List categories by business importance for better narratives
| Category | Purpose | Examples |
|---|---|---|
| Core Infrastructure | Mission-critical business systems | Auth, catalog, inventory |
| Domain Services | Business logic and workflows | Pricing, orders, billing |
| User Features | Customer-facing functionality | Cart, dashboard, search |
| Supporting Services | Infrastructure and utilities | Logging, email, monitoring |
E-commerce:
inventory,pricing,cart,checkout,fulfillment,shipping
SaaS:
authentication,subscription,billing,workspace,collaboration,reporting
Fintech:
transaction,compliance,risk_assessment,fraud_detection,ledger,reconciliation
General:
API,database,caching,real_time,analytics,security,integration
The test suite includes fast unit tests with mocks and slower integration tests with real operations.
# Run unit tests only (~1 second)
pytest tests/
# With verbose output
pytest tests/ -v
# With coverage report
pytest tests/ --cov=src --cov-report=termUnit tests use mocks to avoid slow operations like git commands and matplotlib rendering.
# Run integration tests with real git/matplotlib operations (~3 minutes)
pytest tests/ -m integration -v# Run both unit and integration tests
pytest tests/ -m "" -v
# With HTML coverage report
pytest tests/ --cov=src --cov-report=html -m ""
open htmlcov/index.html- ✅ 33 tests passing
- ✅ 74% overall coverage
- ✅ 100% coverage on chart_generator.py
- ✅ 89% coverage on git_analyzer.py
- ✅ 88% coverage on config_manager.py
kpi-report-generator/
├── config.yaml # Configuration template
├── config.local.yaml # Private config (gitignored)
├── src/
│ ├── __init__.py
│ ├── main.py # CLI entry point and orchestration
│ ├── git_analyzer.py # Git operations and metrics
│ ├── config_manager.py # Configuration loading
│ ├── chart_generator.py # Matplotlib chart generation
│ ├── report_generator.py # HTML report generation
│ └── narrative_generator.py # Text narrative generation
├── templates/
│ └── report.html # Jinja2 HTML template
├── reports/ # Generated reports (gitignored)
│ ├── kpi-report-*.html # HTML output files
│ └── .charts/ # Generated chart images
│ ├── release-activity-*.png
│ ├── code-volume-*.png
│ ├── project-total_commits-*.png
│ ├── project-total_lines_added-*.png
│ ├── project-net_change-*.png
│ └── timeline-*.png
├── tests/
│ ├── test_git_analyzer.py
│ ├── test_git_analyzer_unit.py
│ ├── test_chart_generator.py
│ ├── test_chart_generator_unit.py
│ ├── test_config_manager.py
│ ├── test_report_generator.py
│ ├── test_narrative_generator.py
│ ├── test_integration.py
│ └── fixtures/
│ └── sample_repo/ # Test git repository
├── docs/ # Development documentation
├── requirements.txt # Python dependencies
├── setup.py # Package configuration
├── pytest.ini # Test configuration
└── README.md
def get_tags(repo_path: Path) -> List[Tuple[str, datetime]]:
"""Extract semantic version tags from repository."""
def count_commits_between(repo_path: Path, from_tag: str, to_tag: str) -> int:
"""Count commits between two git tags."""
def calculate_line_changes(
repo_path: Path,
from_tag: str,
to_tag: str,
exclusions: List[str]
) -> Tuple[int, int]:
"""Calculate lines added and removed between tags."""
def should_exclude_file(filepath: str, patterns: List[str]) -> bool:
"""Check if file matches exclusion patterns."""def generate_project_breakdown_chart(
projects: List[Dict],
metric: str,
period: str,
output_path: Path
) -> Path:
"""Create horizontal bar chart comparing services."""
def generate_timeline_chart(
timeline_data: List[Tuple],
period: str,
output_path: Path
) -> Path:
"""Create timeline showing releases over time."""
def generate_summary_comparison_chart(
summary_data: Dict,
period: str,
output_path: Path
) -> Path:
"""Create bar chart with summary metrics."""def generate_html_report(
projects_data: List[Dict],
output_dir: Path,
period: str = "all"
) -> Path:
"""Generate HTML report with embedded charts."""def load_config(path: str = "config.yaml") -> Config:
"""Load configuration with local override support."""GitPython==3.1.40 # Git repository operations
pytest==7.4.3 # Testing framework
pytest-cov==4.1.0 # Coverage reporting
PyYAML==6.0.3 # YAML configuration
python-dateutil==2.9 # Date parsing utilities
Jinja2==3.1.6 # HTML template rendering
matplotlib==3.10.7 # Chart generation and visualizationBenchmarks:
- 3 repositories with 334 tags: ~4 seconds
- Chart generation adds ~1-2 seconds
- HTML rendering: < 1 second
- Total end-to-end: < 10 seconds
included_projects:
- product-catalog-service
- shopping-cart-service
- payment-gateway-service
- order-fulfillment-serviceincluded_projects:
- user-auth-service
- subscription-management-service
- billing-service
- analytics-dashboard-serviceincluded_projects:
- account-service
- transaction-processor-service
- risk-assessment-service
- compliance-reporting-service❌ Error: config.yaml not found
Solution: Create config.yaml in project root with required fields.
⚠️ SKIP: project-name (not found at /path/to/repo)
Solution: Verify projects_directory path in config.yaml points to the correct location.
ModuleNotFoundError: No module named 'yaml'
Solution: Install dependencies: pip install -r requirements.txt
PermissionError: [Errno 13] Permission denied
Solution: Ensure you have read access to git repositories and write access to the output directory.
Contributions are welcome! Please follow these guidelines:
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Make your changes with tests
- Ensure all tests pass (
pytest tests/ -m "") - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
# Clone your fork
git clone https://github.com/yourusername/kpi.git
cd kpi
# Install in development mode with test dependencies
pip install -e .
pip install -r requirements.txt
# Run tests
pytest tests/ -v
# Run with coverage
pytest tests/ --cov=src --cov-report=htmlMIT License - see LICENSE file for details.
- Issues: https://github.com/edwardselby/kpi/issues
- Documentation: See
docs/directory for detailed specifications
Built with Claude Code
Co-Authored-By: Claude Sonnet 4.5 noreply@anthropic.com