Composite Stability Index (CSI) Calculator

A tool for calculating and visualising repository stability metrics based on the theoretical framework introduced in "Introducing Repository Stability" (FSE 2025).

Overview

This application implements the Composite Stability Index (CSI) framework to measure repository health through four key indicators:

• Commit Pattern Stability
• Issue Management Stability
• Pull Request Processing Stability
• Community Engagement Stability

Architecture

• Backend: FastAPI REST API for CSI calculations
• Frontend: Streamlit dashboard for visualisation and threshold management
• Database: PostgreSQL for data storage
• Deployment: Docker containers

Quick Start

Prerequisites

• Python 3.12
• PostgreSQL (or use Docker)
• Git

Setup

1. Clone the repository

   git clone <your-repo-url>
   cd composite-stability-index

2. Create virtual environment

   python3.12 -m venv venv
   source venv/bin/activate  # On macOS/Linux

3. Install dependencies

   pip install -r requirements.txt

4. Configure environment

   cp .env.example .env
   # Edit .env with your database credentials

5. Run with Docker

   docker-compose up

Project Structure

composite-stability-index/
├── src/
│   ├── api/                # FastAPI backend
│   ├── dashboard/          # Streamlit frontend
│   ├── core/               # CSI calculation logic
│   ├── data/               # CSV cleaning & database operations
│   └── models/             # Database models
├── tests/                  # Test suite
├── docker/                 # Docker configuration
├── data/                   # Data storage
└── docs/                   # Documentation