benchmark-reliability 0.2.0__tar.gz → 0.3.0__tar.gz

{benchmark_reliability-0.2.0 → benchmark_reliability-0.3.0}/PKG-INFO

@@ -1,11 +1,11 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.4
 Name: benchmark-reliability
-Version: 0.2.0
+Version: 0.3.0
 Summary: Benchmark Reliability Framework (BRF) - dataset-level reliability auditing with built-in benchmark registry
 Author-email: zhanglizhuo <zhanglizhuo@gmail.com>
 License: MIT
-Project-URL: Homepage, https://github.com/zhanglizhuo/BenchmarkReliability
-Project-URL: Repository, https://github.com/zhanglizhuo/BenchmarkReliability
+Project-URL: Homepage, https://github.com/zhanglizhuo/BRFPackage
+Project-URL: Repository, https://github.com/zhanglizhuo/BRFPackage
 Keywords: benchmark reliability,dataset auditing,educational AI,machine learning,registry
 Classifier: Development Status :: 3 - Alpha
 Classifier: License :: OSI Approved :: MIT License
@@ -65,9 +65,9 @@ print(analyzer.diagnose()["summary"])
 for dim, issue in analyzer.diagnose()["details"].items():
     print(f"  {dim}: {issue}")
 
-# Percentile rank against 25 audited benchmarks
+# Percentile rank against the 51 benchmarks in the BRF Registry (v2.1 reference)
 print(analyzer.rank())
-# {'S_percentile': 16.0, 'E_percentile': 36.0, ...}
+# {'S_percentile': 17.6, 'E_percentile': 27.5, 'reference': 'BRF Registry v2.1 (51 benchmarks)'}
 
 # One-paragraph recommendation
 print(analyzer.recommend())
@@ -77,7 +77,7 @@ print(analyzer.recommend())
 
 ```bash
 $ brf registry list
-BRF Registry -- 16 datasets
+BRF Registry
 
   assistments          ASSISTments 2009-2010           N= 3729  G= 124
   college_scorecard    US College Scorecard            N= 7804  G=  59
@@ -95,7 +95,7 @@ BRF Audit: Teaching Assistant Evaluation (tae)
 ### Download and verify all datasets
 
 ```bash
-$ brf registry sync     # download + SHA-256 verify all 16 datasets
+$ brf registry sync     # download + SHA-256 verify all
 $ brf registry info oulad
   name: oulad
   display_name: Open University Learning Analytics Dataset
@@ -122,7 +122,7 @@ communication shorthand only --- **the signal is in the continuous values**.
 
 Use `analyzer.diagnose()` for per-dimension explanations and actionable
 recommendations, or `analyzer.rank()` to see percentile scores against
-the 25 benchmarks in the BRF Registry.
+the 51 benchmarks in the BRF Registry (v2.1 reference).
 
 ## CLI Reference
 
@@ -152,8 +152,8 @@ To cite the BRF framework and package (JOSS paper forthcoming):
 @software{zhang2026brf,
   author = {Lizhuo Zhang},
   title = {benchmark-reliability: Benchmark Reliability Framework},
-  url = {https://github.com/zhanglizhuo/BenchmarkReliability},
-  version = {0.1.5},
+  url = {https://github.com/zhanglizhuo/BRFPackage},
+  version = {0.3.0},
   year = {2026},
 }
 ```
@@ -162,7 +162,7 @@ The behavior audit protocol is described in:
 
 > Zhang, L. *BehaviorAudit: a four-dimension protocol for auditing
 > benchmark reliability under group-aware evaluation.*
-> Scientific Reports (under review).
+> Scientific Reports (2026). https://doi.org/10.1038/s41598-026-69629-6
 
 ## Related Work
 

{benchmark_reliability-0.2.0 → benchmark_reliability-0.3.0}/README.md

@@ -38,9 +38,9 @@ print(analyzer.diagnose()["summary"])
 for dim, issue in analyzer.diagnose()["details"].items():
     print(f"  {dim}: {issue}")
 
-# Percentile rank against 25 audited benchmarks
+# Percentile rank against the 51 benchmarks in the BRF Registry (v2.1 reference)
 print(analyzer.rank())
-# {'S_percentile': 16.0, 'E_percentile': 36.0, ...}
+# {'S_percentile': 17.6, 'E_percentile': 27.5, 'reference': 'BRF Registry v2.1 (51 benchmarks)'}
 
 # One-paragraph recommendation
 print(analyzer.recommend())
@@ -50,7 +50,7 @@ print(analyzer.recommend())
 
 ```bash
 $ brf registry list
-BRF Registry -- 16 datasets
+BRF Registry
 
   assistments          ASSISTments 2009-2010           N= 3729  G= 124
   college_scorecard    US College Scorecard            N= 7804  G=  59
@@ -68,7 +68,7 @@ BRF Audit: Teaching Assistant Evaluation (tae)
 ### Download and verify all datasets
 
 ```bash
-$ brf registry sync     # download + SHA-256 verify all 16 datasets
+$ brf registry sync     # download + SHA-256 verify all
 $ brf registry info oulad
   name: oulad
   display_name: Open University Learning Analytics Dataset
@@ -95,7 +95,7 @@ communication shorthand only --- **the signal is in the continuous values**.
 
 Use `analyzer.diagnose()` for per-dimension explanations and actionable
 recommendations, or `analyzer.rank()` to see percentile scores against
-the 25 benchmarks in the BRF Registry.
+the 51 benchmarks in the BRF Registry (v2.1 reference).
 
 ## CLI Reference
 
@@ -125,8 +125,8 @@ To cite the BRF framework and package (JOSS paper forthcoming):
 @software{zhang2026brf,
   author = {Lizhuo Zhang},
   title = {benchmark-reliability: Benchmark Reliability Framework},
-  url = {https://github.com/zhanglizhuo/BenchmarkReliability},
-  version = {0.1.5},
+  url = {https://github.com/zhanglizhuo/BRFPackage},
+  version = {0.3.0},
   year = {2026},
 }
 ```
@@ -135,7 +135,7 @@ The behavior audit protocol is described in:
 
 > Zhang, L. *BehaviorAudit: a four-dimension protocol for auditing
 > benchmark reliability under group-aware evaluation.*
-> Scientific Reports (under review).
+> Scientific Reports (2026). https://doi.org/10.1038/s41598-026-69629-6
 
 ## Related Work
 

{benchmark_reliability-0.2.0 → benchmark_reliability-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "benchmark-reliability"
-version = "0.2.0"
+version = "0.3.0"
 description = "Benchmark Reliability Framework (BRF) - dataset-level reliability auditing with built-in benchmark registry"
 readme = "README.md"
 license = { text = "MIT" }
@@ -37,14 +37,18 @@ dependencies = [
 brf = "brf.cli:main"
 
 [project.urls]
-Homepage = "https://github.com/zhanglizhuo/BenchmarkReliability"
-Repository = "https://github.com/zhanglizhuo/BenchmarkReliability"
+Homepage = "https://github.com/zhanglizhuo/BRFPackage"
+Repository = "https://github.com/zhanglizhuo/BRFPackage"
 
 [tool.setuptools]
 license-files = []
 
 [tool.setuptools.packages.find]
 where = ["src"]
+include = ["brf", "brf.metrics", "brf.phase", "brf.registry", "brf.registry.sources", "brf.report"]
 
 [tool.setuptools.package-data]
-"brf.registry" = ["manifest.yaml"]
+"brf.registry" = ["manifest.yaml", "registry_v2.1.json"]
+
+[tool.setuptools.exclude-package-data]
+"brf.registry" = ["cache/*", "cache/**/*"]

{benchmark_reliability-0.2.0 → benchmark_reliability-0.3.0}/setup.py

@@ -2,15 +2,16 @@ from setuptools import setup, find_packages
 
 setup(
     name="benchmark-reliability",
-    version="0.2.0",
+    version="0.3.0",
     packages=find_packages(where="src"),
     package_dir={"": "src"},
     package_data={
         "brf.registry": ["manifest.yaml"],
     },
     install_requires=[
-        "numpy>=1.18",
-        "scikit-learn>=0.24",
+        "numpy>=1.21",
+        "scikit-learn>=1.0",
+        "matplotlib>=3.5",
         "pandas>=1.1",
         "scipy>=1.5",
         "openml>=0.12",

{benchmark_reliability-0.2.0 → benchmark_reliability-0.3.0}/src/benchmark_reliability.egg-info/PKG-INFO

@@ -1,11 +1,11 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.4
 Name: benchmark-reliability
-Version: 0.2.0
+Version: 0.3.0
 Summary: Benchmark Reliability Framework (BRF) - dataset-level reliability auditing with built-in benchmark registry
 Author-email: zhanglizhuo <zhanglizhuo@gmail.com>
 License: MIT
-Project-URL: Homepage, https://github.com/zhanglizhuo/BenchmarkReliability
-Project-URL: Repository, https://github.com/zhanglizhuo/BenchmarkReliability
+Project-URL: Homepage, https://github.com/zhanglizhuo/BRFPackage
+Project-URL: Repository, https://github.com/zhanglizhuo/BRFPackage
 Keywords: benchmark reliability,dataset auditing,educational AI,machine learning,registry
 Classifier: Development Status :: 3 - Alpha
 Classifier: License :: OSI Approved :: MIT License
@@ -65,9 +65,9 @@ print(analyzer.diagnose()["summary"])
 for dim, issue in analyzer.diagnose()["details"].items():
     print(f"  {dim}: {issue}")
 
-# Percentile rank against 25 audited benchmarks
+# Percentile rank against the 51 benchmarks in the BRF Registry (v2.1 reference)
 print(analyzer.rank())
-# {'S_percentile': 16.0, 'E_percentile': 36.0, ...}
+# {'S_percentile': 17.6, 'E_percentile': 27.5, 'reference': 'BRF Registry v2.1 (51 benchmarks)'}
 
 # One-paragraph recommendation
 print(analyzer.recommend())
@@ -77,7 +77,7 @@ print(analyzer.recommend())
 
 ```bash
 $ brf registry list
-BRF Registry -- 16 datasets
+BRF Registry
 
   assistments          ASSISTments 2009-2010           N= 3729  G= 124
   college_scorecard    US College Scorecard            N= 7804  G=  59
@@ -95,7 +95,7 @@ BRF Audit: Teaching Assistant Evaluation (tae)
 ### Download and verify all datasets
 
 ```bash
-$ brf registry sync     # download + SHA-256 verify all 16 datasets
+$ brf registry sync     # download + SHA-256 verify all
 $ brf registry info oulad
   name: oulad
   display_name: Open University Learning Analytics Dataset
@@ -122,7 +122,7 @@ communication shorthand only --- **the signal is in the continuous values**.
 
 Use `analyzer.diagnose()` for per-dimension explanations and actionable
 recommendations, or `analyzer.rank()` to see percentile scores against
-the 25 benchmarks in the BRF Registry.
+the 51 benchmarks in the BRF Registry (v2.1 reference).
 
 ## CLI Reference
 
@@ -152,8 +152,8 @@ To cite the BRF framework and package (JOSS paper forthcoming):
 @software{zhang2026brf,
   author = {Lizhuo Zhang},
   title = {benchmark-reliability: Benchmark Reliability Framework},
-  url = {https://github.com/zhanglizhuo/BenchmarkReliability},
-  version = {0.1.5},
+  url = {https://github.com/zhanglizhuo/BRFPackage},
+  version = {0.3.0},
   year = {2026},
 }
 ```
@@ -162,7 +162,7 @@ The behavior audit protocol is described in:
 
 > Zhang, L. *BehaviorAudit: a four-dimension protocol for auditing
 > benchmark reliability under group-aware evaluation.*
-> Scientific Reports (under review).
+> Scientific Reports (2026). https://doi.org/10.1038/s41598-026-69629-6
 
 ## Related Work
 

{benchmark_reliability-0.2.0 → benchmark_reliability-0.3.0}/src/benchmark_reliability.egg-info/SOURCES.txt

@@ -22,24 +22,54 @@ src/brf/phase/visualization.py
 src/brf/registry/__init__.py
 src/brf/registry/cli.py
 src/brf/registry/manifest.yaml
+src/brf/registry/registry_v2.1.json
 src/brf/registry/verify.py
 src/brf/registry/sources/__init__.py
+src/brf/registry/sources/abalone.py
+src/brf/registry/sources/air_quality_uci.py
 src/brf/registry/sources/assistments.py
+src/brf/registry/sources/auto_mpg.py
+src/brf/registry/sources/boston_housing.py
+src/brf/registry/sources/climate_weather.py
 src/brf/registry/sources/college_scorecard.py
 src/brf/registry/sources/colleges_aaup.py
 src/brf/registry/sources/colleges_usnews.py
+src/brf/registry/sources/cpu_act.py
+src/brf/registry/sources/credit_card.py
+src/brf/registry/sources/cross_domain_batch.py
+src/brf/registry/sources/customer_churn.py
+src/brf/registry/sources/electricity.py
+src/brf/registry/sources/energy_building.py
+src/brf/registry/sources/energy_efficiency.py
 src/brf/registry/sources/entrance_exam.py
+src/brf/registry/sources/external_validation.py
+src/brf/registry/sources/german_credit.py
 src/brf/registry/sources/higher_ed.py
+src/brf/registry/sources/kaggle_students_performance.py
+src/brf/registry/sources/kdd_cup_2010.py
+src/brf/registry/sources/law_school.py
 src/brf/registry/sources/mathe.py
 src/brf/registry/sources/mm_tba.py
+src/brf/registry/sources/nursery.py
 src/brf/registry/sources/oli.py
+src/brf/registry/sources/olympics.py
 src/brf/registry/sources/oulad.py
+src/brf/registry/sources/pisa2015.py
+src/brf/registry/sources/pollution.py
+src/brf/registry/sources/real_estate.py
+src/brf/registry/sources/seoul_bike.py
+src/brf/registry/sources/student_absences.py
 src/brf/registry/sources/student_depression.py
 src/brf/registry/sources/student_dropout.py
+src/brf/registry/sources/student_health.py
+src/brf/registry/sources/students_exam_scores.py
 src/brf/registry/sources/tae.py
 src/brf/registry/sources/turkiye.py
 src/brf/registry/sources/uci_student.py
+src/brf/registry/sources/uci_student_math.py
+src/brf/registry/sources/wine_quality.py
 src/brf/registry/sources/xapi_edu.py
+src/brf/registry/sources/yacht.py
 src/brf/report/__init__.py
 src/brf/report/json_export.py
 src/brf/report/latex_export.py

{benchmark_reliability-0.2.0 → benchmark_reliability-0.3.0}/src/brf/__init__.py

@@ -1,6 +1,8 @@
 from .analyzer import BRFAnalyzer
 
-__all__ = ["BRFAnalyzer"]
+__version__ = "0.3.0"
+
+__all__ = ["BRFAnalyzer", "__version__"]
 
 # Registry is lazily imported to avoid circular dependencies
 # Use: from brf.registry import REGISTRY_SOURCES, list_sources

{benchmark_reliability-0.2.0 → benchmark_reliability-0.3.0}/src/brf/analyzer.py

@@ -27,7 +27,7 @@ class BRFAnalyzer:
             raise ValueError("n_splits must be >= 2")
         self.n_splits = n_splits
         self.n_permutations = n_permutations
-        self.model = model or Ridge(alpha=1.0)
+        self.model = model if model is not None else Ridge(alpha=1.0)
         self.seed = seed
         self.scale = scale
 
@@ -137,11 +137,15 @@ class BRFAnalyzer:
 
     # ---- improved reporting (v0.2) ----
 
-    def diagnose(self) -> Dict[str, str]:
+    def diagnose(self, n_samples: Optional[int] = None,
+                 n_features: Optional[int] = None,
+                 n_groups: Optional[int] = None) -> Dict[str, str]:
         """Return structured diagnosis explaining *why* the dataset is in its current state.
 
-        Replaces the opaque 3-class label with interpretable per-dimension
-        explanations, enabling benchmark designers to understand what to fix.
+        Args:
+            n_samples: Total sample count (for context-aware suggestions).
+            n_features: Feature count.
+            n_groups: Group count.
         """
         if not self._fitted:
             raise RuntimeError("call fit() before accessing diagnose()")
@@ -149,71 +153,81 @@ class BRFAnalyzer:
         issues = {}
         suggestions = {}
 
+        n = n_samples or 0
+        p = n_features or 0
+        g = n_groups or 0
+
         # --- Predictive signal (B) ---
         if self.B < 0:
             issues["B"] = (f"Model performs WORSE than the mean baseline "
-                           f"(B={self.B:.3f}). The features carry no useful "
-                           f"predictive signal for this target.")
-            suggestions["B"] = "Reconsider feature engineering or target definition."
+                           f"(B={self.B:.3f}). Features carry no useful signal.")
+            suggestions["B"] = ("Reconsider feature engineering and target definition. "
+                               "The chosen features cannot predict this target.")
         elif self.B < 0.05:
-            issues["B"] = (f"Marginal improvement over mean baseline "
-                           f"(B={self.B:.3f}). Features explain very little variance.")
-            suggestions["B"] = "Add more informative features or reframe the task."
+            issues["B"] = (f"Marginal signal (B={self.B:.3f}). "
+                           f"Features explain very little variance.")
+            suggestions["B"] = "Add more informative features or reframe the prediction task."
         elif self.B < 0.2:
-            issues["B"] = (f"Moderate predictive signal (B={self.B:.3f}).")
+            issues["B"] = (f"Moderate signal (B={self.B:.3f}).")
             suggestions["B"] = None
         else:
-            issues["B"] = (f"Strong predictive signal (B={self.B:.3f}).")
+            issues["B"] = (f"Strong signal (B={self.B:.3f}).")
             suggestions["B"] = None
 
         # --- Instability (I) ---
         if self.I > 1.0:
-            issues["I"] = (f"High cross-split instability (I={self.I:.3f}). "
-                           f"Model R^2 varies dramatically depending on which "
-                           f"samples happen to be in the test set.")
-            suggestions["I"] = ("Increase sample size (N), reduce feature count (p), "
-                               "or use regularization.")
+            per_group = f"~{n//g} per group" if g > 0 and n > 0 else ""
+            n_feat_ratio = f" (N/p={n//p})" if p > 0 and n > 0 else ""
+            issues["I"] = (f"High instability (I={self.I:.3f}). "
+                           f"R^2 varies dramatically across data splits.")
+            if n > 0 and n < 200:
+                suggestions["I"] = (f"Only N={n} samples{per_group}. "
+                                   f"Increase to 300+ for stable estimates.")
+            elif p > 0 and n > 0 and n / p < 10:
+                suggestions["I"] = (f"N/p={n//p} is low{n_feat_ratio}. "
+                                   f"Increase N or reduce features (currently {p}).")
+            else:
+                suggestions["I"] = "Increase N, reduce p, or use stronger regularization."
         elif self.I > 0.3:
             issues["I"] = (f"Moderate instability (I={self.I:.3f}).")
-            suggestions["I"] = "Consider larger N or fewer features for more stable estimates."
+            suggestions["I"] = "Consider larger N for more stable estimates."
         else:
-            issues["I"] = (f"Low instability (I={self.I:.3f}). "
-                           f"Model is robust to data split variation.")
+            issues["I"] = (f"Low instability (I={self.I:.3f}). Stable across splits.")
             suggestions["I"] = None
 
         # --- Null separation (N) ---
         if self.N < 0.5:
-            issues["N"] = (f"Model rarely beats permutation baseline "
-                           f"(N={self.N:.3f}). The signal is indistinguishable "
-                           f"from random noise.")
-            suggestions["N"] = ("The model is effectively fitting noise. "
-                               "Consider whether a predictive relationship exists.")
+            issues["N"] = (f"Signal indistinguishable from noise "
+                           f"(N={self.N:.3f}). Model rarely beats permutation.")
+            if self.B <= 0:
+                suggestions["N"] = "No predictive relationship detected. Reconsider features/target."
+            else:
+                suggestions["N"] = "Weak signal. Increase N or simplify the feature set."
         elif self.N < 0.8:
-            issues["N"] = (f"Model sometimes fails to beat permutation "
-                           f"(N={self.N:.3f}). Signal is present but inconsistent.")
-            suggestions["N"] = "Increase sample size or feature quality for more reliable separation."
+            issues["N"] = (f"Inconsistent signal separation (N={self.N:.3f}).")
+            suggestions["N"] = "Increase N or improve feature quality."
         else:
-            issues["N"] = (f"Model consistently beats permutation "
-                           f"(N={self.N:.3f}). Clear signal above noise.")
+            issues["N"] = (f"Clear signal above noise (N={self.N:.3f}).")
             suggestions["N"] = None
 
         # --- Metadata adequacy (M) ---
         if self.M < 0.1:
-            issues["M"] = (f"Insufficient group metadata (M={self.M:.3f}). "
-                           f"Groups are too few, highly imbalanced, or absent.")
-            suggestions["M"] = ("Add or improve group annotations. "
-                               "Consider whether an alternative grouping variable "
-                               "captures more meaningful structure.")
+            issues["M"] = (f"Insufficient group structure (M={self.M:.3f}). "
+                           f"Groups are too few, absent, or severely imbalanced.")
+            if g < 5:
+                suggestions["M"] = (f"Only {g} group(s). Add group annotations "
+                                   f"with >=5 categories for meaningful cross-group evaluation.")
+            else:
+                suggestions["M"] = (f"{g} groups but highly imbalanced. "
+                                   f"Use a more balanced grouping variable.")
         elif self.M < 0.3:
-            issues["M"] = (f"Weak group metadata (M={self.M:.3f}). "
-                           f"Group structure exists but is sparse or imbalanced.")
+            issues["M"] = (f"Weak group structure (M={self.M:.3f}).")
             suggestions["M"] = "Use a finer-grained grouping variable if available."
         elif self.M < 0.5:
-            issues["M"] = (f"Moderate group metadata (M={self.M:.3f}).")
+            issues["M"] = (f"Moderate group structure (M={self.M:.3f}).")
             suggestions["M"] = None
         else:
-            issues["M"] = (f"Strong group metadata (M={self.M:.3f}). "
-                           f"Group structure is well-defined and balanced.")
+            issues["M"] = (f"Strong group structure (M={self.M:.3f}).")
             suggestions["M"] = None
 
         # --- Synthesis ---
@@ -237,10 +251,10 @@ class BRFAnalyzer:
         }
 
     def rank(self) -> Dict[str, float]:
-        """Percentile rank of S and E against the BRF Registry v1.5 benchmarks.
+        """Percentile rank of S and E against the BRF Registry v2.1 benchmarks.
 
         Returns percentiles (0-100) indicating where this dataset's S and E
-        fall relative to the 25 audited benchmarks. Requires the registry
+        fall relative to the audited benchmarks in the bundled Registry reference (v2.1). Requires
         data to be accessible.
         """
         if not self._fitted:
@@ -259,45 +273,52 @@ class BRFAnalyzer:
         return {
             "S_percentile": round(pctile(s_vals, self.S), 1),
             "E_percentile": round(pctile(e_vals, self.E), 1),
-            "reference": f"BRF Registry v1.5 ({len(s_vals)} benchmarks)",
+            "reference": f"BRF Registry v2.1 ({len(s_vals)} benchmarks)",
         }
 
-    def recommend(self) -> str:
-        """One-paragraph actionable recommendation for benchmark improvement."""
-        d = self.diagnose()
+    def recommend(self, n_samples: Optional[int] = None,
+                  n_features: Optional[int] = None,
+                  n_groups: Optional[int] = None) -> str:
+        """Actionable recommendations for benchmark improvement.
+
+        Args:
+            n_samples, n_features, n_groups: Optional context for concrete suggestions
+                (e.g., "Only N=151 samples. Increase to 300+").
+        """
+        d = self.diagnose(n_samples, n_features, n_groups)
         recs = d["recommendations"]
         if not recs:
-            return ("Benchmark metrics are within normal ranges. "
-                    "No specific action recommended.")
-        # Prioritize: B < 0 is most critical, then N < 0.5, then I > 1, then M < 0.1
-        priority = []
-        if self.B < 0:
-            priority.append("B")
-        if self.N < 0.5:
-            priority.append("N")
-        if self.I > 1.0:
-            priority.append("I")
-        if self.M < 0.1:
-            priority.append("M")
-        if not priority:
-            priority = [k for k in recs]
+            return "No issues found. Your benchmark metrics are within normal ranges."
 
-        lines = [
-            f"This benchmark has {len(recs)} dimension(s) needing attention. "
-            f"Primary concern: {recs[priority[0]]}"
-        ]
-        return " ".join(lines)
+        lines = []
+        for dim in ["B", "N", "I", "M"]:
+            if dim in recs:
+                lines.append(f"[{dim}] {recs[dim]}")
+        return "\n".join(lines)
+
+    def recommend_dict(self) -> Dict:
+        """Structured actionable recommendations as a dict.
+
+        Returns {dimension: {"issue": ..., "action": ..., "value": ...}}.
+        """
+        d = self.diagnose()
+        out = {}
+        for dim in ["B", "N", "I", "M"]:
+            if dim in d["details"] and dim in d["recommendations"]:
+                out[dim] = {
+                    "issue": d["details"][dim],
+                    "action": d["recommendations"][dim],
+                    "value": getattr(self, dim),
+                }
+        return out
 
     def _load_registry_ref(self) -> Optional[List[Dict]]:
         """Load Registry reference data for percentile ranking."""
         if self._registry_ref is not None:
             return self._registry_ref
-        # Search for registry_v1.5.json in known locations
+        # Bundled registry reference (ships with the package at brf/registry/)
         candidates = [
-            Path(__file__).parent.parent.parent.parent
-            / "BRFRegistry" / "results" / "registry_v1.5.json",
-            Path(__file__).parent.parent.parent
-            / "BRFRegistry" / "results" / "registry_v1.5.json",
+            Path(__file__).parent / "registry" / "registry_v2.1.json",
         ]
         for p in candidates:
             if p.exists():