rig-ores 0.1.0__tar.gz

rig_ores-0.1.0/.gitignore

@@ -0,0 +1,26 @@
+# Binaries
+bin/
+dist/
+*.wasm
+
+# Generated
+gen/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Test
+coverage.txt
+coverage.html
+
+# Documentation build output
+site/
+
+# Superpowers specs and plans (auto-generated, not for version control)
+docs/superpowers/

rig_ores-0.1.0/PKG-INFO

@@ -0,0 +1,173 @@
+Metadata-Version: 2.5
+Name: rig-ores
+Version: 0.1.0
+Summary: Python client for ORES: local V0 severity-count risk scoring
+Author-email: liad@rig.security, hila@rig.security
+Maintainer-email: liad@rig.security, hila@rig.security
+License-Expression: Apache-2.0
+Requires-Python: >=3.10
+Provides-Extra: test
+Requires-Dist: pytest; extra == 'test'
+Description-Content-Type: text/markdown
+
+# rig-ores
+
+Python client for [ORES](https://github.com/rigsecurity/ores)'s **V0** risk score:
+a severity-count model for identities/assets, ported from rig-security/ml-services'
+`rice/risk_score/risk_score.py`. It runs entirely locally — no `oresd` daemon or
+network call required — so it's suited to notebooks and batch analysis as well as
+services.
+
+Given an identity's finding counts by severity (critical / high / medium / low),
+it returns a 0–10 score capped by the identity's most severe tier, plus the named
+contributions ("factors") that produced it.
+
+## Install
+
+Not yet published to PyPI (see below). Until then, install directly from the repo:
+
+```bash
+# editable install from a local clone
+pip install -e /path/to/ores/clients/python
+
+# or straight from GitHub, no clone needed
+pip install "git+https://github.com/rigsecurity/ores.git#subdirectory=clients/python"
+```
+
+## Usage
+
+### Single identity
+
+```python
+from rig_ores import score_identity
+
+result = score_identity("cluster-123", critical=1, high=2)
+
+result.score     # 9.42
+result.capped    # False
+result.factors   # [Factor(feature="primary", tier="critical", contribution=9.0, reasoning="..."), ...]
+
+print(result.explain())
+# Score: 9.42 (critical)
+#   +9.00  1 critical finding (highest-severity present)
+#   +0.35  1 high finding (next tier down)
+#   +0.07  1 further high finding(s), diminishing weight
+```
+
+`explain()` only lists non-zero contributions, ranked highest first — see
+[Examples](#examples) below for the full range of shapes it can take.
+
+### Batch
+
+`score_batch` takes any iterable of mappings with `id`, `critical`, `high`,
+`medium`, `low` keys (case-insensitive; missing severities default to 0) — a list
+of dicts, or a pandas DataFrame via `df.to_dict("records")`:
+
+```python
+from rig_ores import score_batch
+
+rows = [
+    {"id": "cluster-123", "critical": 1, "high": 2, "medium": 0, "low": 0},
+    {"id": "cluster-456", "critical": 0, "high": 0, "medium": 3, "low": 1},
+]
+
+for result in score_batch(rows):
+    print(result.id, result.score, result.explain())
+
+# from a DataFrame
+# score_batch(findings_df.to_dict("records"))
+```
+
+## Examples
+
+24 finding-count combinations chosen to exercise every named contribution
+(`primary`, `same_secondary`, `lower_secondary`, `same_tier_rest`,
+`cross_tier_rest`) and both non-capped and capped scores, computed with the
+default weights:
+
+| Scenario | critical | high | medium | low | Score | Capped | Features exercised |
+|---|---:|---:|---:|---:|---:|:---:|---|
+| No findings | 0 | 0 | 0 | 0 | 0.00 | no | — |
+| Single critical | 1 | 0 | 0 | 0 | 9.00 | no | primary |
+| Single high | 0 | 1 | 0 | 0 | 7.00 | no | primary |
+| Single medium | 0 | 0 | 1 | 0 | 4.00 | no | primary |
+| Single low | 0 | 0 | 0 | 1 | 2.00 | no | primary |
+| Same secondary: 2 criticals | 2 | 0 | 0 | 0 | 9.70 | no | primary, same_secondary |
+| Same secondary: 2 highs | 0 | 2 | 0 | 0 | 8.05 | no | primary, same_secondary |
+| Same secondary: 2 mediums | 0 | 0 | 2 | 0 | 5.75 | no | primary, same_secondary |
+| Same secondary: 2 lows | 0 | 0 | 0 | 2 | 2.96 | no | primary, same_secondary |
+| Lower secondary: critical + high | 1 | 1 | 0 | 0 | 9.35 | no | primary, lower_secondary |
+| Lower secondary: critical + medium | 1 | 0 | 1 | 0 | 9.25 | no | primary, lower_secondary |
+| Lower secondary: critical + low | 1 | 0 | 0 | 1 | 9.15 | no | primary, lower_secondary |
+| Lower secondary: high + medium | 0 | 1 | 1 | 0 | 7.25 | no | primary, lower_secondary |
+| Lower secondary: high + low | 0 | 1 | 0 | 1 | 7.15 | no | primary, lower_secondary |
+| Lower secondary: medium + low | 0 | 0 | 1 | 1 | 4.15 | no | primary, lower_secondary |
+| Same-tier decay: 4 criticals | 4 | 0 | 0 | 0 | 9.99 | no | primary, same_secondary, same_tier_rest |
+| Same-tier decay: 5 mediums | 0 | 0 | 5 | 0 | 6.50 | yes | primary, same_secondary, same_tier_rest |
+| Cross-tier decay: critical + 3 highs | 1 | 3 | 0 | 0 | 9.46 | no | primary, lower_secondary, cross_tier_rest |
+| Cross-tier decay: critical, 2 medium, 1 low | 1 | 0 | 2 | 1 | 9.33 | no | primary, lower_secondary, cross_tier_rest |
+| Full mix, primary = critical ×2 | 2 | 1 | 1 | 1 | 9.81 | no | primary, same_secondary, cross_tier_rest |
+| Capped: 50 criticals | 50 | 0 | 0 | 0 | 10.00 | yes | primary, same_secondary, same_tier_rest |
+| Capped: 20 mediums | 0 | 0 | 20 | 0 | 6.50 | yes | primary, same_secondary, same_tier_rest |
+| Just under the cap: 20 lows | 0 | 0 | 0 | 20 | 3.50 | no | primary, same_secondary, same_tier_rest |
+| Realistic mixed cluster | 3 | 5 | 10 | 2 | 9.97 | no | primary, same_secondary, same_tier_rest, cross_tier_rest |
+
+A couple of these in full, via `.explain()`:
+
+```
+score_identity("x", critical=1, high=3)
+# Score: 9.46 (critical)
+#   +9.00  1 critical finding (highest-severity present)
+#   +0.35  1 high finding (next tier down)
+#   +0.11  2 further high finding(s), diminishing weight
+```
+
+```
+score_identity("x", critical=0, high=0, medium=20, low=0)
+# Score: 6.50 (medium)
+#   +4.00  1 medium finding (highest-severity present)
+#   +1.75  a second medium finding
+#   +0.99  18 further medium finding(s), diminishing weight
+```
+
+Note the "just under the cap" row: with enough low-tier findings the decaying
+`same_tier_rest` bonus asymptotically approaches — but by design of the decay
+formula never quite reaches — the tier's ceiling.
+
+## Configuring the weights
+
+The weights, per-tier ceilings, and decay rate live in
+[`src/rig_ores/data/v0_weights.json`](src/rig_ores/data/v0_weights.json) and are
+loaded once as `DEFAULT_SPEC`. To score against a different set of weights
+(e.g. while tuning), load your own spec file and pass it explicitly — nothing
+in the package needs to change:
+
+```python
+from rig_ores import load_spec, score_identity
+
+spec = load_spec("my_weights.json")
+result = score_identity("cluster-123", critical=1, spec=spec)
+```
+
+A weights file must have the same shape as `v0_weights.json`: `tiers` (4 names),
+`weights` (5x4 matrix, rows ordered `primary`, `same_secondary`,
+`lower_secondary`, `same_tier_rest`, `cross_tier_rest`), `ceilings` (4 values),
+and `decay_rate`.
+
+## Publishing to PyPI
+
+Publishing is automated via [`.github/workflows/publish-python.yml`](../../.github/workflows/publish-python.yml):
+pushing a tag matching `rig-ores-v*` builds the package and publishes it to
+PyPI using [Trusted Publishing](https://docs.pypi.org/trusted-publishers/)
+(OIDC — no stored API token).
+
+One manual, one-time step is required before the first publish: a PyPI account
+holder (maintainer: liad@rig.security) must create the `rig-ores` project on
+PyPI and register this repo/workflow as a trusted publisher under
+*Publishing* settings, pointing at:
+
+- Repository: `rigsecurity/ores`
+- Workflow: `publish-python.yml`
+- Environment: (none)
+
+Maintainers: liad@rig.security, hila@rig.security.

rig_ores-0.1.0/README.md

@@ -0,0 +1,161 @@
+# rig-ores
+
+Python client for [ORES](https://github.com/rigsecurity/ores)'s **V0** risk score:
+a severity-count model for identities/assets, ported from rig-security/ml-services'
+`rice/risk_score/risk_score.py`. It runs entirely locally — no `oresd` daemon or
+network call required — so it's suited to notebooks and batch analysis as well as
+services.
+
+Given an identity's finding counts by severity (critical / high / medium / low),
+it returns a 0–10 score capped by the identity's most severe tier, plus the named
+contributions ("factors") that produced it.
+
+## Install
+
+Not yet published to PyPI (see below). Until then, install directly from the repo:
+
+```bash
+# editable install from a local clone
+pip install -e /path/to/ores/clients/python
+
+# or straight from GitHub, no clone needed
+pip install "git+https://github.com/rigsecurity/ores.git#subdirectory=clients/python"
+```
+
+## Usage
+
+### Single identity
+
+```python
+from rig_ores import score_identity
+
+result = score_identity("cluster-123", critical=1, high=2)
+
+result.score     # 9.42
+result.capped    # False
+result.factors   # [Factor(feature="primary", tier="critical", contribution=9.0, reasoning="..."), ...]
+
+print(result.explain())
+# Score: 9.42 (critical)
+#   +9.00  1 critical finding (highest-severity present)
+#   +0.35  1 high finding (next tier down)
+#   +0.07  1 further high finding(s), diminishing weight
+```
+
+`explain()` only lists non-zero contributions, ranked highest first — see
+[Examples](#examples) below for the full range of shapes it can take.
+
+### Batch
+
+`score_batch` takes any iterable of mappings with `id`, `critical`, `high`,
+`medium`, `low` keys (case-insensitive; missing severities default to 0) — a list
+of dicts, or a pandas DataFrame via `df.to_dict("records")`:
+
+```python
+from rig_ores import score_batch
+
+rows = [
+    {"id": "cluster-123", "critical": 1, "high": 2, "medium": 0, "low": 0},
+    {"id": "cluster-456", "critical": 0, "high": 0, "medium": 3, "low": 1},
+]
+
+for result in score_batch(rows):
+    print(result.id, result.score, result.explain())
+
+# from a DataFrame
+# score_batch(findings_df.to_dict("records"))
+```
+
+## Examples
+
+24 finding-count combinations chosen to exercise every named contribution
+(`primary`, `same_secondary`, `lower_secondary`, `same_tier_rest`,
+`cross_tier_rest`) and both non-capped and capped scores, computed with the
+default weights:
+
+| Scenario | critical | high | medium | low | Score | Capped | Features exercised |
+|---|---:|---:|---:|---:|---:|:---:|---|
+| No findings | 0 | 0 | 0 | 0 | 0.00 | no | — |
+| Single critical | 1 | 0 | 0 | 0 | 9.00 | no | primary |
+| Single high | 0 | 1 | 0 | 0 | 7.00 | no | primary |
+| Single medium | 0 | 0 | 1 | 0 | 4.00 | no | primary |
+| Single low | 0 | 0 | 0 | 1 | 2.00 | no | primary |
+| Same secondary: 2 criticals | 2 | 0 | 0 | 0 | 9.70 | no | primary, same_secondary |
+| Same secondary: 2 highs | 0 | 2 | 0 | 0 | 8.05 | no | primary, same_secondary |
+| Same secondary: 2 mediums | 0 | 0 | 2 | 0 | 5.75 | no | primary, same_secondary |
+| Same secondary: 2 lows | 0 | 0 | 0 | 2 | 2.96 | no | primary, same_secondary |
+| Lower secondary: critical + high | 1 | 1 | 0 | 0 | 9.35 | no | primary, lower_secondary |
+| Lower secondary: critical + medium | 1 | 0 | 1 | 0 | 9.25 | no | primary, lower_secondary |
+| Lower secondary: critical + low | 1 | 0 | 0 | 1 | 9.15 | no | primary, lower_secondary |
+| Lower secondary: high + medium | 0 | 1 | 1 | 0 | 7.25 | no | primary, lower_secondary |
+| Lower secondary: high + low | 0 | 1 | 0 | 1 | 7.15 | no | primary, lower_secondary |
+| Lower secondary: medium + low | 0 | 0 | 1 | 1 | 4.15 | no | primary, lower_secondary |
+| Same-tier decay: 4 criticals | 4 | 0 | 0 | 0 | 9.99 | no | primary, same_secondary, same_tier_rest |
+| Same-tier decay: 5 mediums | 0 | 0 | 5 | 0 | 6.50 | yes | primary, same_secondary, same_tier_rest |
+| Cross-tier decay: critical + 3 highs | 1 | 3 | 0 | 0 | 9.46 | no | primary, lower_secondary, cross_tier_rest |
+| Cross-tier decay: critical, 2 medium, 1 low | 1 | 0 | 2 | 1 | 9.33 | no | primary, lower_secondary, cross_tier_rest |
+| Full mix, primary = critical ×2 | 2 | 1 | 1 | 1 | 9.81 | no | primary, same_secondary, cross_tier_rest |
+| Capped: 50 criticals | 50 | 0 | 0 | 0 | 10.00 | yes | primary, same_secondary, same_tier_rest |
+| Capped: 20 mediums | 0 | 0 | 20 | 0 | 6.50 | yes | primary, same_secondary, same_tier_rest |
+| Just under the cap: 20 lows | 0 | 0 | 0 | 20 | 3.50 | no | primary, same_secondary, same_tier_rest |
+| Realistic mixed cluster | 3 | 5 | 10 | 2 | 9.97 | no | primary, same_secondary, same_tier_rest, cross_tier_rest |
+
+A couple of these in full, via `.explain()`:
+
+```
+score_identity("x", critical=1, high=3)
+# Score: 9.46 (critical)
+#   +9.00  1 critical finding (highest-severity present)
+#   +0.35  1 high finding (next tier down)
+#   +0.11  2 further high finding(s), diminishing weight
+```
+
+```
+score_identity("x", critical=0, high=0, medium=20, low=0)
+# Score: 6.50 (medium)
+#   +4.00  1 medium finding (highest-severity present)
+#   +1.75  a second medium finding
+#   +0.99  18 further medium finding(s), diminishing weight
+```
+
+Note the "just under the cap" row: with enough low-tier findings the decaying
+`same_tier_rest` bonus asymptotically approaches — but by design of the decay
+formula never quite reaches — the tier's ceiling.
+
+## Configuring the weights
+
+The weights, per-tier ceilings, and decay rate live in
+[`src/rig_ores/data/v0_weights.json`](src/rig_ores/data/v0_weights.json) and are
+loaded once as `DEFAULT_SPEC`. To score against a different set of weights
+(e.g. while tuning), load your own spec file and pass it explicitly — nothing
+in the package needs to change:
+
+```python
+from rig_ores import load_spec, score_identity
+
+spec = load_spec("my_weights.json")
+result = score_identity("cluster-123", critical=1, spec=spec)
+```
+
+A weights file must have the same shape as `v0_weights.json`: `tiers` (4 names),
+`weights` (5x4 matrix, rows ordered `primary`, `same_secondary`,
+`lower_secondary`, `same_tier_rest`, `cross_tier_rest`), `ceilings` (4 values),
+and `decay_rate`.
+
+## Publishing to PyPI
+
+Publishing is automated via [`.github/workflows/publish-python.yml`](../../.github/workflows/publish-python.yml):
+pushing a tag matching `rig-ores-v*` builds the package and publishes it to
+PyPI using [Trusted Publishing](https://docs.pypi.org/trusted-publishers/)
+(OIDC — no stored API token).
+
+One manual, one-time step is required before the first publish: a PyPI account
+holder (maintainer: liad@rig.security) must create the `rig-ores` project on
+PyPI and register this repo/workflow as a trusted publisher under
+*Publishing* settings, pointing at:
+
+- Repository: `rigsecurity/ores`
+- Workflow: `publish-python.yml`
+- Environment: (none)
+
+Maintainers: liad@rig.security, hila@rig.security.

rig_ores-0.1.0/pyproject.toml

@@ -0,0 +1,26 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "rig-ores"
+version = "0.1.0"
+description = "Python client for ORES: local V0 severity-count risk scoring"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "Apache-2.0"
+authors = [
+    { email = "liad@rig.security" },
+    { email = "hila@rig.security" },
+]
+maintainers = [
+    { email = "liad@rig.security" },
+    { email = "hila@rig.security" },
+]
+dependencies = []
+
+[project.optional-dependencies]
+test = ["pytest"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/rig_ores"]

rig_ores-0.1.0/src/rig_ores/__init__.py

@@ -0,0 +1,21 @@
+from rig_ores.scoring import (
+    DEFAULT_SPEC,
+    Factor,
+    ScoreResult,
+    TIERS,
+    WeightsSpec,
+    load_spec,
+    score_batch,
+    score_identity,
+)
+
+__all__ = [
+    "DEFAULT_SPEC",
+    "Factor",
+    "ScoreResult",
+    "TIERS",
+    "WeightsSpec",
+    "load_spec",
+    "score_batch",
+    "score_identity",
+]

rig_ores-0.1.0/src/rig_ores/data/v0_weights.json

@@ -0,0 +1,13 @@
+{
+  "tiers": ["critical", "high", "medium", "low"],
+  "feature_rows": ["primary", "same_secondary", "lower_secondary", "same_tier_rest", "cross_tier_rest"],
+  "weights": [
+    [9, 7, 4, 2],
+    [0.7, 1.05, 1.75, 0.96],
+    [0, 0.35, 0.25, 0.15],
+    [0.39, 0.59, 0.99, 0.54],
+    [0.18, 0.15, 0.12, 0.08]
+  ],
+  "ceilings": [10.0, 8.5, 6.5, 3.5],
+  "decay_rate": 0.5
+}

rig_ores-0.1.0/src/rig_ores/scoring.py

@@ -0,0 +1,173 @@
+"""V0 severity-count risk scoring.
+
+Ports the ORES weights matrix from rig-security/ml-services'
+rice/risk_score/risk_score.py: one identity's Critical/High/Medium/Low finding
+counts go in, a 0-10 score capped by the identity's most severe tier comes out,
+along with the named contributions that produced it.
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Iterable, Mapping
+from dataclasses import dataclass
+from importlib import resources
+from pathlib import Path
+
+
+@dataclass(frozen=True)
+class WeightsSpec:
+    tiers: tuple[str, ...]
+    weights: list[list[float]]
+    ceilings: list[float]
+    decay_rate: float
+
+
+def load_spec(path: str | Path) -> WeightsSpec:
+    text = Path(path).read_text()
+    spec = _spec_from_text(text)
+    return spec
+
+
+def _spec_from_text(text: str) -> WeightsSpec:
+    raw = json.loads(text)
+    spec = WeightsSpec(
+        tiers=tuple(raw["tiers"]),
+        weights=raw["weights"],
+        ceilings=raw["ceilings"],
+        decay_rate=raw["decay_rate"],
+    )
+    return spec
+
+
+DEFAULT_SPEC = _spec_from_text(resources.files("rig_ores").joinpath("data/v0_weights.json").read_text())
+TIERS = DEFAULT_SPEC.tiers
+
+
+@dataclass(frozen=True)
+class Factor:
+    feature: str
+    tier: str
+    contribution: float
+    reasoning: str
+
+
+@dataclass(frozen=True)
+class ScoreResult:
+    id: str
+    score: float
+    capped: bool
+    factors: list[Factor]
+
+    def explain(self) -> str:
+        score_display = f"{self.score:.2f}"
+        if not self.factors:
+            no_findings_explanation = f"Score: {score_display} (no findings)"
+            return no_findings_explanation
+
+        primary_tier = next(factor.tier for factor in self.factors if factor.feature == "primary")
+        ranked_factors = sorted(self.factors, key=lambda factor: factor.contribution, reverse=True)
+        lines = [f"Score: {score_display} ({primary_tier})"]
+        lines += [f"  +{factor.contribution:.2f}  {factor.reasoning}" for factor in ranked_factors]
+        explanation = "\n".join(lines)
+        return explanation
+
+
+def score_identity(
+    id: str,
+    critical: int = 0,
+    high: int = 0,
+    medium: int = 0,
+    low: int = 0,
+    spec: WeightsSpec = DEFAULT_SPEC,
+) -> ScoreResult:
+    result = _score(id, [critical, high, medium, low], spec)
+    return result
+
+
+def score_batch(rows: Iterable[Mapping[str, object]], spec: WeightsSpec = DEFAULT_SPEC) -> list[ScoreResult]:
+    results = [_score_row(row, spec) for row in rows]
+    return results
+
+
+def _score_row(row: Mapping[str, object], spec: WeightsSpec) -> ScoreResult:
+    normalized = {str(key).lower(): value for key, value in row.items()}
+    result = score_identity(
+        id=normalized["id"],
+        critical=int(normalized.get("critical", 0)),
+        high=int(normalized.get("high", 0)),
+        medium=int(normalized.get("medium", 0)),
+        low=int(normalized.get("low", 0)),
+        spec=spec,
+    )
+    return result
+
+
+def _score(id: str, counts: list[int], spec: WeightsSpec) -> ScoreResult:
+    if sum(counts) == 0:
+        empty_result = ScoreResult(id=id, score=0.0, capped=False, factors=[])
+        return empty_result
+
+    primary_col = next(index for index, count in enumerate(counts) if count > 0)
+    primary_count = counts[primary_col]
+    same_secondary = primary_count >= 2
+    secondary_col = next((index for index in range(primary_col + 1, len(counts)) if counts[index] > 0), None)
+    lower_secondary = primary_count == 1 and secondary_col is not None
+
+    rest_counts = list(counts)
+    rest_counts[primary_col] -= 1
+    if same_secondary:
+        rest_counts[primary_col] -= 1
+    if lower_secondary:
+        rest_counts[secondary_col] -= 1
+    rest_counts = [max(count, 0) for count in rest_counts]
+
+    contributions = _contributions(primary_col, same_secondary, secondary_col, lower_secondary, rest_counts, spec)
+    raw_score = sum(value for _, _, value, _ in contributions)
+    ceiling = spec.ceilings[primary_col]
+    capped = raw_score > ceiling
+    score = round(min(raw_score, ceiling), 2)
+    factors = [
+        Factor(feature=feature, tier=spec.tiers[tier], contribution=round(value, 4), reasoning=reasoning)
+        for feature, tier, value, reasoning in contributions
+        if value != 0
+    ]
+
+    result = ScoreResult(id=id, score=score, capped=capped, factors=factors)
+    return result
+
+
+def _contributions(
+    primary_col: int,
+    same_secondary: bool,
+    secondary_col: int | None,
+    lower_secondary: bool,
+    rest_counts: list[int],
+    spec: WeightsSpec,
+) -> list[tuple[str, int, float, str]]:
+    contributions: list[tuple[str, int, float, str]] = []
+
+    primary_reasoning = f"1 {spec.tiers[primary_col]} finding (highest-severity present)"
+    contributions.append(("primary", primary_col, spec.weights[0][primary_col], primary_reasoning))
+
+    if same_secondary:
+        same_secondary_reasoning = f"a second {spec.tiers[primary_col]} finding"
+        contributions.append(("same_secondary", primary_col, spec.weights[1][primary_col], same_secondary_reasoning))
+
+    if lower_secondary:
+        lower_secondary_reasoning = f"1 {spec.tiers[secondary_col]} finding (next tier down)"
+        contributions.append(
+            ("lower_secondary", secondary_col, spec.weights[2][secondary_col], lower_secondary_reasoning)
+        )
+
+    start = 0
+    for tier, rest in enumerate(rest_counts):
+        if rest > 0:
+            decay = (spec.decay_rate**start) * (1 - spec.decay_rate**rest)
+            row = "same_tier_rest" if tier == primary_col else "cross_tier_rest"
+            weight_row = 3 if row == "same_tier_rest" else 4
+            reasoning = f"{rest} further {spec.tiers[tier]} finding(s), diminishing weight"
+            contributions.append((row, tier, decay * spec.weights[weight_row][tier], reasoning))
+        start += rest
+
+    return contributions

rig_ores-0.1.0/tests/test_scoring.py

@@ -0,0 +1,55 @@
+from rig_ores import WeightsSpec, score_batch, score_identity
+
+
+def test_no_findings_scores_zero() -> None:
+    result = score_identity("id-1")
+    assert result.score == 0.0
+    assert result.factors == []
+
+
+def test_single_critical_finding() -> None:
+    result = score_identity("id-1", critical=1)
+    assert result.score == 9.0
+    assert result.factors[0].feature == "primary"
+    assert result.factors[0].tier == "critical"
+
+
+def test_score_caps_at_primary_tier_ceiling() -> None:
+    result = score_identity("id-1", critical=50)
+    assert result.score == 10.0
+    assert result.capped is True
+
+
+def test_custom_spec_overrides_default_weights() -> None:
+    custom_spec = WeightsSpec(
+        tiers=("critical", "high", "medium", "low"),
+        weights=[[5, 5, 5, 5], [0, 0, 0, 0], [0, 0, 0, 0], [0, 0, 0, 0], [0, 0, 0, 0]],
+        ceilings=[10.0, 10.0, 10.0, 10.0],
+        decay_rate=0.5,
+    )
+    result = score_identity("id-1", critical=1, spec=custom_spec)
+    assert result.score == 5.0
+
+
+def test_explain_lists_only_nonzero_contributions_highest_first() -> None:
+    result = score_identity("id-1", critical=1, high=2)
+    lines = result.explain().splitlines()
+    assert lines[0] == "Score: 9.42 (critical)"
+    assert len(lines) == 1 + len(result.factors)
+    assert lines[1].startswith("  +9.00")
+
+
+def test_explain_with_no_findings() -> None:
+    result = score_identity("id-1")
+    assert result.explain() == "Score: 0.00 (no findings)"
+
+
+def test_batch_preserves_id_and_order() -> None:
+    results = score_batch(
+        [
+            {"id": "id-1", "critical": 1, "high": 0, "medium": 0, "low": 0},
+            {"id": "id-2", "critical": 0, "high": 0, "medium": 3, "low": 0},
+        ]
+    )
+    assert [r.id for r in results] == ["id-1", "id-2"]
+    assert results[0].score == 9.0