🇧🇷 Português

KWANDO: Monte Carlo Simulation Dashboard

A dashboard to forecast work item completion using Monte Carlo simulations. Built with Python and Panel.

Why Monte Carlo Simulation?

Monte Carlo simulations use your team’s actual historical data to generate thousands of possible futures, providing a range of likely outcomes and their probabilities. Unlike simple averages or burn rate calculations, Monte Carlo methods account for the natural variability and unpredictability in real work. This means you get forecasts with confidence levels (percentiles), not just a single number, helping you make better decisions under uncertainty.

For a deeper dive, see Actionable Agile Metrics for Predictability: An Introduction by Daniel Vacanti.

Watch: Your Project Behaves Like a Hurricane. Forecast It Like One (YouTube)

Getting Started

Quick Start with Docker Hub (Recommended)

The easiest way to run Kwando is using the pre-built Docker image from Docker Hub:

docker run -p 5006:5006 -v $(pwd)/data:/app/data rodbv/kwando:latest

Then open http://localhost:5006 in your browser. No installation or setup required!

If you want a CSV file as an example, you can download some here.

Don't have Docker? Install Docker here

Running from source

Prerequisites

• Python 3.12 or higher
• uv package manager

Installation

1. Install uv:

   curl -LsSf https://astral.sh/uv/install.sh | sh

2. Clone the repository:

   git clone https://github.com/rodbv/kwando.git
   cd kwando

3. Install dependencies:

   uv sync

4. Run the dashboard:

   uv run panel serve src/dashboard.py

5. Open your browser at the URL shown in the terminal (typically http://localhost:5006)

Data Format

Enter throughput values directly in the dashboard using comma-separated format:

• Enter values separated by commas: 2,3,5,2,4,6
• Whitespace around commas is automatically trimmed: 2, 3, 5, 2 works the same as 2,3,5,2
• All values must be numeric and non-negative (>= 0)
• Decimal values are supported: 2.5,3.7,5.2
• Maximum 1000 values
• Values are automatically saved and restored on next visit

Example: 2,3,5,2,4,6 represents 6 weeks of throughput data.

How to Use

1. Load Data: Use the "Data Source" section to enter throughput values directly using comma-separated format (e.g., 2,3,5,2,4,6). Values are automatically saved and restored on next visit.
2. Choose Analysis:
   • "When will it be done?": Calculate completion date for a specific number of items
   • "How many items?": Calculate how many items can be completed in a period
3. Adjust Parameters: Set the number of items or date range
4. View Results: See percentiles and confidence levels for your forecast

---

Contributing

Contributions are welcome! See the Contributing Guide for details on how to submit issues, feature requests, and pull requests.

Code of Conduct

This project follows a Code of Conduct. By participating, you are expected to uphold this code.

License

MIT License - see the LICENSE file for details.

Credits

• Monte Carlo simulation adapted from rueedlinger/monte-carlo-simulation
• Inspired by the book Actionable Agile Metrics for Predictability: An Introduction by Daniel Vacanti