feat: add IQBCache component

This commit implements the IQBCache component for fetching IQB
measurement data from local cache files.

Key features:

1. Git-like .iqb/ directory convention (customizable)

2. Support for US, DE, BR data (October 2024)

3. Percentile extraction (1-99) with helpful error messages

4. Good test coverage (13 tests)

We adopt a convention where .iqb/ is the default cache directory
in the current working directory (like .git/), but this can be
overridden by passing a custom path.

While there, we address these additional quality improvements:

1. Add .editorconfig for cross-editor consistency

2. Add explicit ruff formatting rules (spaces, double quotes, LF)

3. Add ruff format/lint/pyright checks to CI pipeline

Author: bassosimone

.editorconfig

@@ -0,0 +1,41 @@
+# EditorConfig for m-lab/iqb
+# https://editorconfig.org
+
+root = true
+
+# Defaults for all files
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+# Python source files
+[*.py]
+indent_style = space
+indent_size = 4
+max_line_length = 100
+
+# YAML files
+[*.{yml,yaml}]
+indent_style = space
+indent_size = 2
+
+# JSON files
+[*.json]
+indent_style = space
+indent_size = 2
+
+# Markdown files
+[*.md]
+indent_style = space
+indent_size = 2
+
+# Makefiles require tabs
+[Makefile]
+indent_style = tab
+
+# Shell scripts
+[*.sh]
+indent_style = space
+indent_size = 2

.github/workflows/ci.yml

@@ -25,6 +25,33 @@ jobs:
       - name: Sync workspace dependencies
         run: uv sync --dev
 
+      - name: Check code formatting with ruff
+        working-directory: library
+        run: |
+          uv run ruff format --check || {
+            echo "❌ Code formatting check failed!"
+            echo "To fix locally, run: cd library && uv run ruff format"
+            exit 1
+          }
+
+      - name: Lint code with ruff
+        working-directory: library
+        run: |
+          uv run ruff check || {
+            echo "❌ Linting check failed!"
+            echo "To fix locally, run: cd library && uv run ruff check --fix"
+            exit 1
+          }
+
+      - name: Type check with pyright
+        working-directory: library
+        run: |
+          uv run pyright || {
+            echo "❌ Type checking failed!"
+            echo "To see errors locally, run: cd library && uv run pyright"
+            exit 1
+          }
+
       - name: Run pytest
         working-directory: library
         run: uv run pytest

library/pyproject.toml

@@ -46,6 +46,11 @@ addopts = [
 line-length = 100
 target-version = "py313"
 
+[tool.ruff.format]
+indent-style = "space"
+quote-style = "double"
+line-ending = "lf"
+
 [tool.ruff.lint]
 select = [
     "E",   # pycodestyle errors

library/src/iqb/__init__.py

@@ -4,11 +4,12 @@
 network measurement data, weight matrices, and quality thresholds.
 """
 
+from .cache import IQBCache
 from .calculator import IQBCalculator
 from .config import IQB_CONFIG
 
 # Backward compatibility alias
 IQB = IQBCalculator
 
-__all__ = ["IQB", "IQBCalculator", "IQB_CONFIG"]
+__all__ = ["IQB", "IQBCalculator", "IQBCache", "IQB_CONFIG"]
 __version__ = "0.1.0"

library/src/iqb/cache.py

@@ -0,0 +1,139 @@
+"""Module for fetching IQB measurement data from cache.
+
+The IQBCache component manages local caching of IQB measurement data, following
+a Git-like convention for storing local state.
+
+Cache Directory Convention
+---------------------------
+By default, IQBCache looks for a `.iqb/` directory in the current working
+directory, similar to how Git uses `.git/` for repository state. This provides:
+
+- Clear ownership (`.iqb/` contains IQB-specific data)
+- Per-project isolation (each project has its own cache)
+- Conventional pattern (like `.cache/`, `.config/`, etc.)
+
+Example usage:
+
+    # Uses ./.iqb/ in current directory
+    cache = IQBCache()
+
+    # Or specify custom location
+    cache = IQBCache(cache_dir="/shared/iqb-cache")
+"""
+
+import json
+from datetime import datetime
+from pathlib import Path
+
+
+class IQBCache:
+    """Component for fetching IQB measurement data from cache."""
+
+    def __init__(self, cache_dir: str | Path | None = None):
+        """
+        Initialize cache with data directory path.
+
+        Parameters:
+            cache_dir: Path to directory containing cached data files.
+                If None, defaults to ./.iqb/ in current working directory.
+        """
+        if cache_dir is None:
+            # Git-like convention: local state in .iqb/ directory
+            self.cache_dir = Path.cwd() / ".iqb"
+        else:
+            self.cache_dir = Path(cache_dir)
+
+    def get_data(
+        self,
+        country: str,
+        start_date: datetime,
+        end_date: datetime | None = None,
+        percentile: int = 95,
+    ) -> dict:
+        """
+        Fetch measurement data for IQB calculation.
+
+        Args:
+            country: ISO 2-letter country code ("US", "DE", "BR").
+            start_date: Start of date range (inclusive).
+            end_date: End of date range (exclusive). If None, defaults to start_date + 1 month.
+            percentile: Which percentile to extract (1-99).
+
+        Returns:
+            dict with keys for IQBCalculator:
+            {
+                "download_throughput_mbps": float,
+                "upload_throughput_mbps": float,
+                "latency_ms": float,
+                "packet_loss": float,
+            }
+
+        Raises:
+            FileNotFoundError: If requested data is not available in cache.
+            ValueError: If requested percentile is not available in cached data.
+        """
+        # Hard-coded data we have: October 2024 for US, DE, BR
+        country_lower = country.lower()
+
+        # Check if we have this exact data
+        if country_lower == "us" and start_date == datetime(2024, 10, 1) and end_date is None:
+            filename = "us_2024_10.json"
+        elif country_lower == "de" and start_date == datetime(2024, 10, 1) and end_date is None:
+            filename = "de_2024_10.json"
+        elif country_lower == "br" and start_date == datetime(2024, 10, 1) and end_date is None:
+            filename = "br_2024_10.json"
+        else:
+            raise FileNotFoundError(
+                f"No cached data for country={country}, "
+                f"start_date={start_date}, end_date={end_date}. "
+                f"Currently only have: US/DE/BR for October 2024."
+            )
+
+        # Load from file
+        filepath = self.cache_dir / filename
+        if not filepath.exists():
+            raise FileNotFoundError(f"Cache file missing: {filepath}")
+
+        with open(filepath) as f:
+            data = json.load(f)
+
+        # Extract the requested percentile
+        return self._extract_percentile(data, percentile)
+
+    def _extract_percentile(self, data: dict, percentile: int) -> dict:
+        """
+        Extract specific percentile from JSON data.
+
+        Converts from JSON format to IQBCalculator format:
+        - Input: {"metrics": {"download_throughput_mbps": {"p95": 123, ...}, ...}}
+        - Output: {"download_throughput_mbps": 123, ...}
+
+        Args:
+            data: Full JSON data structure from cache file.
+            percentile: Which percentile to extract.
+
+        Returns:
+            dict with metric values for the specified percentile.
+
+        Raises:
+            ValueError: If requested percentile is not available in the cached data.
+        """
+        metrics = data["metrics"]
+        p_key = f"p{percentile}"
+
+        try:
+            return {
+                "download_throughput_mbps": metrics["download_throughput_mbps"][p_key],
+                "upload_throughput_mbps": metrics["upload_throughput_mbps"][p_key],
+                "latency_ms": metrics["latency_ms"][p_key],
+                "packet_loss": metrics["packet_loss"][p_key],
+            }
+        except KeyError as err:
+            # Determine which percentiles ARE available
+            available = sorted(
+                [int(k[1:]) for k in metrics["download_throughput_mbps"] if k.startswith("p")]
+            )
+            raise ValueError(
+                f"Percentile {percentile} not available in cached data. "
+                f"Available percentiles: {available}"
+            ) from err

library/src/iqb/calculator.py

@@ -56,9 +56,7 @@ def print_config(self):
         for uc in IQB_CONFIG["use cases"]:
             for nr in IQB_CONFIG["use cases"][uc]["network requirements"]:
                 nr_w = IQB_CONFIG["use cases"][uc]["network requirements"][nr]["w"]
-                nr_th = IQB_CONFIG["use cases"][uc]["network requirements"][nr][
-                    "threshold min"
-                ]
+                nr_th = IQB_CONFIG["use cases"][uc]["network requirements"][nr]["threshold min"]
                 print(f"\t{uc:20} \t{nr:20} \t{nr_w} \t{nr_th}")
         print()
 
@@ -113,19 +111,15 @@ def calculate_iqb_score(self, data=None, print_details=False):
             nr_weights = []
             for nr in self.config["use cases"][uc]["network requirements"]:
                 nr_w = self.config["use cases"][uc]["network requirements"][nr]["w"]
-                nr_th = self.config["use cases"][uc]["network requirements"][nr][
-                    "threshold min"
-                ]
+                nr_th = self.config["use cases"][uc]["network requirements"][nr]["threshold min"]
 
                 # TODO: TEMP method for calculating binary requirement scores. To be
                 # updated with weighted average of scores per dataset.
                 ds_s = []
-                for ds in self.config["use cases"][uc]["network requirements"][nr][
-                    "datasets"
-                ]:
-                    ds_w = self.config["use cases"][uc]["network requirements"][nr][
-                        "datasets"
-                    ][ds]["w"]
+                for ds in self.config["use cases"][uc]["network requirements"][nr]["datasets"]:
+                    ds_w = self.config["use cases"][uc]["network requirements"][nr]["datasets"][ds][
+                        "w"
+                    ]
                     if ds_w > 0:
                         # binary requirement score (dataset, network requirement)
                         brs = self.calculate_binary_requirement_score(