axis-synome 0.1.0.dev29__tar.gz → 0.1.0.dev31__tar.gz

{axis_synome-0.1.0.dev29 → axis_synome-0.1.0.dev31}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: axis-synome
-Version: 0.1.0.dev29
+Version: 0.1.0.dev31
 Summary: Axis specification modules (entities, formulas, validators)
 Author-email: Archon Tech <hello@archontech.ai>
 License: MIT

{axis_synome-0.1.0.dev29 → axis_synome-0.1.0.dev31}/src/axis_synome/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.1.0.dev29'
-__version_tuple__ = version_tuple = (0, 1, 0, 'dev29')
+__version__ = version = '0.1.0.dev31'
+__version_tuple__ = version_tuple = (0, 1, 0, 'dev31')
 
 __commit_id__ = commit_id = None

axis_synome-0.1.0.dev31/src/axis_synome/spec/suraf/README.md

@@ -0,0 +1,281 @@
+# SURAF Specification
+
+This module is the executable specification for Sky Protocol's **SURAF** collateral risk assessment framework. It encodes the scoring pipeline and Capital Requirement Ratio (CRR) derivation rules into typed Python so that assessments can be evaluated, tested, and audited against real scorecard data.
+
+---
+
+## Background
+
+Sky Protocol accepts collateral assets to back USDS issuance. The risk of each asset must be quantified before capital can be committed against it. **SURAF** is the framework that does this: three independent assessors score an asset across five pillars of risk, and the resulting aggregate score determines a **Capital Requirement Ratio (CRR)** — the fraction of exposure that must be held as reserve capital.
+
+A higher CRR means the asset is riskier and demands more capital. A penalty is added to the base CRR when assessors flag structurally weak subsections with the lowest possible score (1 out of 5).
+
+This specification answers: *given three completed scorecards and the governance-approved mapping tables, what is the adjusted CRR for this asset?*
+
+---
+
+## Module Layout
+
+```
+entities/       : data types and constants (inputs to the pipeline)
+formulas/       : pure functions that compute the CRR from entities
+opaque/         : implementation helpers exempt from the spec subset (e.g. interpolation via numpy)
+```
+
+All formulas follow one rule: **they accept raw entity inputs and compute everything internally**. No formula accepts a precomputed intermediate value as an argument.
+
+---
+
+## Entities
+
+### `AssessorScore` (`entities/assessor_score.py`)
+
+One assessor's complete evaluation of an asset. Subsection scores are grouped by pillar and stored together with their absolute weights.
+
+| Field | Type | Description |
+|---|---|---|
+| `scores` | `list[PillarEntry]` | Scored pillars; each entry is `(pillar_weight, [(section_weight, score), ...])` |
+
+Where `PillarEntry = tuple[PillarWeight, list[SectionEntry]]` and `SectionEntry = tuple[SubsectionWeight, SubsectionScore]`.
+
+**Score range:** `SubsectionScore` ∈ [`1.0`, `5.0`].
+
+**Weight semantics:** weights are **absolute integers** defined in the weights file, e.g. `40` for Pillar I and `8` for subsection 1.A. Normalisation (dividing by totals) happens inside the formula functions, not in the inputs.
+
+Only scored subsections are included; callers must filter out blanks before construction.
+
+---
+
+### `EligibleSURAFAsset` (`entities/assets.py`)
+
+A closed-world Enum of assets approved for SURAF assessment. Each member's `.value` is a fully specified `AssetWrapper` (token, network, protocol, on-chain address, Atlas source reference).
+
+| Member | Asset |
+|---|---|
+| `AAVE_AUSDC` | Aave aUSDC on Ethereum Mainnet via Aave Core V3 |
+
+---
+
+### `CRRMapping` (`entities/mappings.py`)
+
+Governance-approved score-to-CRR% interpolation table. Maps an aggregate score (1–5) to an unadjusted Capital Requirement Ratio (%). Linear interpolation between breakpoints; values outside the range are clamped.
+
+| Field | Type | Description |
+|---|---|---|
+| `table` | `tuple[tuple[float, float], ...]` | Ordered `(score, crr_pct)` breakpoints; scores strictly increasing |
+
+Example from the reference table:
+
+| Score | CRR% |
+|---|---|
+| 1.00 | 100 |
+| 2.50 | 28 |
+| 3.00 | 20 |
+| 5.00 | 5 |
+
+---
+
+### `PenaltyMapping` (`entities/mappings.py`)
+
+Governance-approved count-to-penalty interpolation table. Maps the total number of score-1 subsections across all assessors to a penalty in percentage points added to the base CRR.
+
+| Field | Type | Description |
+|---|---|---|
+| `table` | `tuple[tuple[int, float], ...]` | Ordered `(n_score_1, penalty_pp)` breakpoints; counts non-negative and strictly increasing |
+
+Example: 7 subsections scored 1 → `penalty_pp = 10 + (7 − 5) / (10 − 5) × (20 − 10) = 14.0 pp`.
+
+---
+
+## Formulas
+
+### Top-level: `crr` (`formulas/crr.py`)
+
+```python
+crr(asset, assessor_scores, crr_mapping, penalty_mapping) -> float
+```
+
+Computes the adjusted Capital Requirement Ratio for a SURAF asset. Returns a value in `[0, 100]`, capped at 100%.
+
+**Pipeline:**
+
+```
+1. overall_score(assessor)       per-assessor two-level weighted average (section → pillar → overall)
+2. weighted_average(assessors)   arithmetic mean of all assessors' overall scores → avg_score
+3. map_crr(avg_score, ...)       look up base CRR% by linear interpolation
+4. total_n_score_1(assessors)    count of all score-1 subsections across all assessors
+5. calculate_penalty(n, ...)     look up penalty pp by linear interpolation
+6. min(base_crr + penalty, 100)  final adjusted CRR, capped at 100%
+```
+
+---
+
+### Scoring helpers (`formulas/scoring.py`)
+
+These pure functions implement each stage of the pipeline. They are composed by `crr`.
+
+#### `overall_score(assessor)` → `float`
+
+Two-level weighted average for a single assessor.
+
+```
+pillar_score_i = Σ(section_weight_j × score_j) / Σ(section_weight_j)
+overall        = Σ(pillar_score_i × pillar_weight_i) / Σ(pillar_weight_i)
+```
+
+---
+
+#### `weighted_average(assessors)` → `float`
+
+Arithmetic mean of `overall_score` across all assessors.
+
+---
+
+#### `n_score_1(assessor)` → `int`
+
+Count of subsections where an assessor gave the minimum score of `1`. Used to measure how many structurally weak areas the assessor flagged.
+
+---
+
+#### `total_n_score_1(assessors)` → `int`
+
+Sum of `n_score_1` across all assessors. This is the input to the penalty interpolation.
+
+---
+
+
+#### `map_crr(avg_score, crr_mapping)` → `float`
+
+Interpolates the base CRR% from the aggregate score using the `CRRMapping` table.
+
+---
+
+#### `calculate_penalty(n_score1, penalty_mapping)` → `float`
+
+Interpolates the penalty in percentage points from the score-1 count using the `PenaltyMapping` table.
+
+---
+
+## Loading Data from CSVs
+
+The spec operates on fully-constructed dataclasses. To go from raw CSV files (assessor scorecards, weights, mapping tables) to spec inputs, use the loader classes in `tests/axis_synome/suraf/suraf_client/suraf_client.py`.
+
+> **Note:** these loaders are test utilities; they live in `tests/` because CSV I/O is a runtime concern, not a spec concern. They are the reference implementation for how data should be adapted before being passed to spec formulas.
+
+---
+
+### `AssessorScoreInput.from_csv(path, weights_path)`
+
+Parses an assessor scorecard CSV together with the weights CSV and returns an `AssessorScore` with absolute weights.
+
+**Scorecard CSV** (`scorecards/Assessor_N_scores.csv`) — required columns: `pillar`, `subsection_ref`, `score`:
+
+```
+pillar,subsection_ref,title,score
+,,SECTION A: GENERAL INFORMATION,
+1,1.A,Asset Composition & Eligibility,4
+1,1.B,Asset Cashflow Structure,3
+1,1.C,Asset Liquidity Analysis,
+2,2.A,Recoverability & Custody,5
+```
+
+Rows with a blank `score` column are skipped. Rows where `pillar` is not a digit (e.g. section headers) are skipped.
+
+**Weights CSV** (`weights.csv`) — required columns: `pillar`, `subsection_ref`, `title`, `pillar_weight`, `subsection_weight`:
+
+```
+pillar,subsection_ref,title,pillar_weight,subsection_weight
+,,PILLAR I: ASSET & COLLATERAL ASSESSMENT,40,0
+1,1.A,Asset Composition & Eligibility,0,8
+1,1.B,Asset Cashflow Structure,0,7
+```
+
+```python
+from suraf_client import AssessorScoreInput
+
+a1 = AssessorScoreInput.from_csv("scorecards/Assessor_1_scores.csv", "weights.csv")
+a2 = AssessorScoreInput.from_csv("scorecards/Assessor_2_scores.csv", "weights.csv")
+a3 = AssessorScoreInput.from_csv("scorecards/Assessor_3_scores.csv", "weights.csv")
+```
+
+---
+
+### `CRRMappingInput.from_csv(path)`
+
+Parses a CRR interpolation table CSV and returns a `CRRMapping`.
+
+**CSV** (`crr_mapping.csv`) — required columns: `score`, `crr`:
+
+```
+score,crr
+1.00,100
+2.50,28
+5.00,5
+```
+
+Scores must be strictly increasing. At least two breakpoints are required.
+
+```python
+from suraf_client import CRRMappingInput
+
+crr_mapping = CRRMappingInput.from_csv("crr_mapping.csv")
+```
+
+---
+
+### `PenaltyMappingInput.from_csv(path)`
+
+Parses a penalty interpolation table CSV and returns a `PenaltyMapping`.
+
+**CSV** (`penalty.csv`) — required columns: `n_score_1`, `penalty_pp`:
+
+```
+n_score_1,penalty_pp
+0,0
+2,0
+20,30
+```
+
+`n_score_1` values must be non-negative and strictly increasing.
+
+```python
+from suraf_client import PenaltyMappingInput
+
+penalty_mapping = PenaltyMappingInput.from_csv("penalty.csv")
+```
+
+---
+
+### End-to-end example
+
+```python
+from suraf_client import AssessorScoreInput, CRRMappingInput, PenaltyMappingInput
+from axis_synome.spec.suraf.entities.assets import EligibleSURAFAsset
+from axis_synome.spec.suraf.formulas.crr import crr
+
+base = "tests/axis_synome/suraf/static/aave_ausdc/v1"
+
+assessors = [
+    AssessorScoreInput.from_csv(f"{base}/scorecards/Assessor_{i}_scores.csv", f"{base}/weights.csv")
+    for i in range(1, 4)
+]
+crr_mapping = CRRMappingInput.from_csv(f"{base}/crr_mapping.csv")
+penalty_map = PenaltyMappingInput.from_csv(f"{base}/penalty.csv")
+
+result = crr(EligibleSURAFAsset.AAVE_AUSDC_DEMO, assessors, crr_mapping, penalty_map)
+print(f"Adjusted CRR: {result:.2f}%")
+```
+
+---
+
+## Design Principles
+
+1. **No precomputed inputs.** Every formula accepts raw entities and derives all intermediates internally. This makes formulas independently testable and prevents stale-input bugs.
+
+2. **Absolute weights, normalised internally.** Weights (e.g. `40` for Pillar I, `8` for subsection 1.A) are stored as absolute integers on `AssessorScore`. Each formula divides by the sum of weights at its level — pillar normalisation inside `overall_score`, assessor averaging inside `weighted_average`.
+
+3. **Governance tables are entity inputs.** `CRRMapping` and `PenaltyMapping` are dataclass inputs, not hardcoded in formulas. Updating the governance decision means providing a new table, not changing spec code.
+
+4. **Score-1 penalty is additive.** The penalty for flagged subsections (score = 1) is added to the base CRR after interpolation and the total is capped at `100%`. This is a separate governance lever from the score-to-CRR curve.
+
+5. **Opaque functions are isolated.** Numerical primitives that require external libraries (e.g. `numpy.interp` for linear interpolation) live in `opaque/` and are exempt from the spec language subset. The spec formulas call them by name; the parser treats the call as an uninterpreted function.

axis_synome-0.1.0.dev31/src/axis_synome/spec/suraf/entities/assessor_score.py

@@ -0,0 +1,43 @@
+from typing import Annotated
+
+from pydantic import Field
+
+from axis_synome.spec_support.validated_dataclass import validated_dataclass
+
+SCORE_MIN: int = 1
+SCORE_MAX: int = 5
+
+SubsectionScore = Annotated[int, Field(ge=SCORE_MIN, le=SCORE_MAX)]
+SubsectionWeight = Annotated[int, Field(gt=0)]
+PillarWeight = Annotated[int, Field(gt=0)]
+
+SectionEntry = tuple[SubsectionWeight, SubsectionScore]
+PillarEntry = tuple[PillarWeight, list[SectionEntry]]
+
+
+@validated_dataclass
+class AssessorScore:
+    """One assessor's subsection-level evaluation of a SURAF asset.
+
+    ``scores`` groups subsection evaluations by pillar.  Each entry is a
+    ``(pillar_weight, sections)`` pair where:
+
+    * ``pillar_weight`` – absolute weight of the pillar (e.g. 40 for Pillar I).
+    * ``sections``      – list of ``(section_weight, score)`` pairs for every
+                          scored subsection within that pillar, where
+                          ``section_weight`` is the absolute subsection weight
+                          (e.g. 8) and ``score`` ∈ [``SCORE_MIN``, ``SCORE_MAX``].
+
+    Only scored (non-null) subsections are included; callers must filter out
+    unscored subsections before constructing this object.
+
+    The two-level weighted average for this assessor is::
+
+        pillar_score_i = Σ(score_j × section_w_j) / Σ(section_w_j)
+        overall        = Σ(pillar_score_i × pillar_w_i) / Σ(pillar_w_i)
+
+    Attributes:
+        scores: Absolute-weight-annotated subsection evaluations grouped by pillar.
+    """
+
+    scores: list[PillarEntry]

axis_synome-0.1.0.dev31/src/axis_synome/spec/suraf/entities/assets.py

@@ -0,0 +1,48 @@
+from dataclasses import KW_ONLY
+from enum import Enum
+
+from axis_synome.spec.asc.entities.assets import Asset
+from axis_synome.spec.asc.entities.networks import Network
+from axis_synome.spec.asc.entities.protocol_sets import Protocol
+from axis_synome.spec.asc.entities.tokens import Token
+from axis_synome.spec_support.evm_address import EvmAddress
+from axis_synome.spec_support.validated_dataclass import validated_dataclass
+
+
+@validated_dataclass
+class AssetWrapper(Asset):
+    """Wrapper around Asset to include SURAF-specific fields (i.e halo identifiers, prime's link to the asset, etc).
+    Placeholder until we have a more complete SURAF asset spec.
+
+    TODO: Investigate if there are shareable entities between different specs (e.g. Asset) and move to a common module
+    to avoid duplication. For now, we can keep SURAF-specific fields in a wrapper class that inherit from asc/assets
+    until we have a more complete SURAF asset spec.
+
+    """
+
+    _: KW_ONLY
+    halo_id: str | None = None
+
+
+class SURAFAsset(Enum):
+    """All SURAF assets."""
+
+    AAVE_AUSDC_DEMO = AssetWrapper(
+        token=Token.A_ETH_USDC,
+        network=Network.ETHEREUM_MAINNET,
+        protocol=Protocol.AAVE_CORE_V3,
+        address=EvmAddress("0x98C23E9d8f34FEFb1B7BD6a91B7FF122F4e16F5c"),
+        # TODO: include url/ uuid
+        source="A.6.1.1.2.2.6.1.3.1.5.1.2.2.1",
+        underlying_asset=Token.A_ETH_USDC,
+        underlying_asset_address=EvmAddress("0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"),
+        underlying_asset_source="A.6.1.1.2.2.6.1.3.1.5.1.2.2.2",
+    )
+
+
+class EligibleSURAFAsset(Enum):
+    """SURAF assets eligible for CRR calculation.
+    We are only supporting a demo asset for now.
+    """
+
+    AAVE_AUSDC_DEMO = SURAFAsset.AAVE_AUSDC_DEMO.value

axis_synome-0.1.0.dev31/src/axis_synome/spec/suraf/entities/mappings.py

@@ -0,0 +1,60 @@
+from axis_synome.spec_support.validated_dataclass import validated_dataclass
+
+
+@validated_dataclass
+class CRRMapping:
+    """Score → CRR% interpolation table.
+
+    Maps an aggregate assessor score (1–5) to an unadjusted Capital
+    Requirement Ratio (%).  Interpolation is linear between breakpoints;
+    values outside the range are clamped to the first/last CRR value.
+
+    Attributes:
+        table: Ordered breakpoints as ``((score, crr_pct), ...)``.
+               Scores must be strictly increasing; CRR values are in percent.
+
+    Example::
+
+        CRRMapping(
+            table=(
+                (1.0, 100.0),
+                (2.5,  60.0),
+                (4.0,  20.0),
+                (5.0,   5.0),
+            )
+        )
+        # avg_score=3.25 interpolates between (2.5, 60) and (4.0, 20):
+        # crr = 60 + (3.25 - 2.5) / (4.0 - 2.5) * (20 - 60) = 40.0 %
+    """
+
+    table: tuple[tuple[float, float], ...]
+
+
+@validated_dataclass
+class PenaltyMapping:
+    """Score-1 count → penalty percentage-point interpolation table.
+
+    Maps the total number of score-1 subsections across all assessors to a
+    penalty in percentage points added to the unadjusted CRR.  More score-1
+    subsections → higher penalty → higher capital charge.
+
+    Attributes:
+        table: Ordered breakpoints as ``((n_score_1, penalty_pp), ...)``.
+               ``n_score_1`` values must be non-negative and strictly
+               increasing.
+
+    Example::
+
+        PenaltyMapping(
+            table=(
+                ( 0,  0.0),
+                ( 5, 10.0),
+                (10, 20.0),
+                (20, 30.0),
+            )
+        )
+        # 7 total score-1 subsections interpolates between (5, 10) and (10, 20):
+        # penalty_pp = 10 + (7 - 5) / (10 - 5) * (20 - 10) = 14.0 pp
+    """
+
+    table: tuple[tuple[int, float], ...]

axis_synome-0.1.0.dev31/src/axis_synome/spec/suraf/formulas/crr.py

@@ -0,0 +1,54 @@
+from axis_synome.spec.suraf.entities.assessor_score import AssessorScore
+from axis_synome.spec.suraf.entities.assets import EligibleSURAFAsset
+from axis_synome.spec.suraf.entities.mappings import CRRMapping, PenaltyMapping
+from axis_synome.spec.suraf.formulas.scoring import (
+    calculate_penalty,
+    map_crr,
+    total_n_score_1,
+    weighted_average,
+)
+
+
+def crr(
+    _asset: EligibleSURAFAsset,
+    assessor_scores: list[AssessorScore],
+    crr_mapping: CRRMapping,
+    penalty_mapping: PenaltyMapping,
+) -> float:
+    """Compute the adjusted Capital Requirement Ratio (CRR) for a SURAF asset
+    :source_uuid: 3828778e-0197-4ce9-a836-6770d04f2ea9
+
+    The CRR reflects the credit and operational risk of the collateral asset and
+    determines the required reserve capital fraction for a given USD exposure.
+
+    Pipeline
+    --------
+    1. Each assessor's overall score is a two-level weighted average: subsection
+       scores are weighted by their absolute section weights within each pillar,
+       then pillar scores are weighted by their absolute pillar weights.
+       Weights are absolute integers (e.g. 40 for Pillar I, 8 for subsection 1.A);
+       normalisation is done internally by ``overall_score``.
+    2. The assessors' overall scores are averaged to produce ``avg_score``.
+    3. ``avg_score`` is mapped to an unadjusted CRR via ``crr_mapping``
+       (linear interpolation).
+    4. A penalty in percentage points is derived from the total number of
+       score-1 subsections across all assessors via ``penalty_mapping``
+       (linear interpolation).
+    5. ``adjusted_crr = min(unadjusted_crr + penalty_pp, 100.0)``.
+
+    Args:
+        _asset:          The eligible SURAF asset being assessed. Placeholder to allow for future asset-specific logic (i.e specific mappings defined in axis-synome not in client side); currently unused.
+        assessor_scores: One :class:`AssessorScore` per independent assessor
+                         (typically three).  Blank subsections must already be
+                         filtered out before constructing each instance.
+        crr_mapping:     Score → CRR% interpolation table.
+        penalty_mapping: n_score_1 → penalty pp interpolation table.
+
+    Returns:
+        Adjusted CRR as a percentage in ``[0, 100]``.
+    """
+    return min(
+        map_crr(weighted_average(assessor_scores), crr_mapping)
+        + calculate_penalty(total_n_score_1(assessor_scores), penalty_mapping),
+        100.0,
+    )

axis_synome-0.1.0.dev31/src/axis_synome/spec/suraf/formulas/scoring.py

@@ -0,0 +1,86 @@
+"""SURAF scoring pipeline as pure functions.
+
+Scoring hierarchy
+-----------------
+1. Subsection level  – AssessorScore.scores is a list of (pillar_weight, sections)
+                       pairs where sections = [(section_weight, score), ...].
+                       All weights are absolute (e.g. 40 for Pillar I, 8 for 1.A).
+2. Overall score     – two-level weighted average:
+                         pillar_score_i = Σ(section_weight_j * score_j) / Σ(section_weight_j)
+                         overall        = Σ(pillar_score_i * pillar_weight_i) / Σ(pillar_weight_i)
+3. Aggregate         – simple arithmetic mean of the three assessors' overall
+                       scores.
+4. CRR               – interpolated from CRRMapping.
+5. Penalty           – interpolated from PenaltyMapping; Added to CRR.
+"""
+
+from axis_synome.spec.suraf.entities.assessor_score import AssessorScore, SectionEntry
+from axis_synome.spec.suraf.entities.mappings import CRRMapping, PenaltyMapping
+from axis_synome.spec_support.runtime import math
+
+
+def section_total_weight(sections: list[SectionEntry]) -> float:
+    """Sum of section weights; the denominator of the pillar-level weighted average."""
+    return sum(section_weight for section_weight, _ in sections)
+
+
+def section_weighted_score(sections: list[SectionEntry]) -> float:
+    """Sum of (section_weight × score) for all sections; the numerator of the pillar-level weighted average."""
+    return sum(section_weight * score for section_weight, score in sections)
+
+
+def overall_score(assessor: AssessorScore) -> float:
+    """Two-level weighted average score for a single assessor.
+
+    First computes a weighted average score within each pillar
+    (``section_weighted_score / section_total_weight``), then weights those
+    pillar scores by their pillar weights.  Pillars with no sections or a zero
+    total section weight are skipped.
+
+    Will raise ZeroDivisionError if the assessor has no scored subsections or all pillar
+    weights sum to zero. Should not happen in practice due to validation of the client's AssessorScore instance.
+    """
+
+    total_pillar_weight = sum(pillar_weight for pillar_weight, _ in assessor.scores)
+
+    pillar_total = sum(
+        pillar_weight * section_weighted_score(sections) / section_total_weight(sections)
+        for pillar_weight, sections in assessor.scores
+        if sections and section_total_weight(sections)
+    )
+    return pillar_total / total_pillar_weight
+
+
+def n_score_1(assessor: AssessorScore) -> int:
+    """Count of subsections where this assessor gave the minimum score of 1.0."""
+    return sum(1 for _, sections in assessor.scores for _, score in sections if score == 1.0)
+
+
+def total_n_score_1(assessors: list[AssessorScore]) -> int:
+    """Sum of score-1 subsection counts across all assessors; the input to penalty interpolation."""
+    return sum(n_score_1(a) for a in assessors)
+
+
+def weighted_average(assessors: list[AssessorScore]) -> float:
+    """Arithmetic mean of overall scores across all assessors that produced a valid score."""
+    valid_count = sum(1 for a in assessors if overall_score(a))
+    valid_sum = sum(overall_score(a) for a in assessors if overall_score(a))
+    return valid_sum / valid_count
+
+
+def map_crr(avg_score: float, crr_mapping: CRRMapping) -> float:
+    """Interpolate the base CRR% from the aggregate assessor score using the CRR mapping table."""
+    return math.linear_interp(
+        [avg_score],
+        [score for score, _ in crr_mapping.table],
+        [crr for _, crr in crr_mapping.table],
+    )[0]
+
+
+def calculate_penalty(n_score1: int, penalty_mapping: PenaltyMapping) -> float:
+    """Interpolate the penalty in percentage points from the count of score-1 subsections."""
+    return math.linear_interp(
+        [float(n_score1)],
+        [n for n, _ in penalty_mapping.table],
+        [penalty for _, penalty in penalty_mapping.table],
+    )[0]

{axis_synome-0.1.0.dev29 → axis_synome-0.1.0.dev31}/src/axis_synome.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: axis-synome
-Version: 0.1.0.dev29
+Version: 0.1.0.dev31
 Summary: Axis specification modules (entities, formulas, validators)
 Author-email: Archon Tech <hello@archontech.ai>
 License: MIT

{axis_synome-0.1.0.dev29 → axis_synome-0.1.0.dev31}/src/axis_synome.egg-info/SOURCES.txt

@@ -35,6 +35,12 @@ src/axis_synome/spec/crypto_lending/formulas/lif.py
 src/axis_synome/spec/risk_capital/__init__.py
 src/axis_synome/spec/risk_capital/formulas/__init__.py
 src/axis_synome/spec/risk_capital/formulas/required_risk_capital.py
+src/axis_synome/spec/suraf/README.md
+src/axis_synome/spec/suraf/entities/assessor_score.py
+src/axis_synome/spec/suraf/entities/assets.py
+src/axis_synome/spec/suraf/entities/mappings.py
+src/axis_synome/spec/suraf/formulas/crr.py
+src/axis_synome/spec/suraf/formulas/scoring.py
 src/axis_synome/spec_support/__init__.py
 src/axis_synome/spec_support/evm_address.py
 src/axis_synome/spec_support/validated_dataclass.py
@@ -67,4 +73,19 @@ tests/axis_synome/spec_support/runtime/__init__.py
 tests/axis_synome/spec_support/runtime/test_base.py
 tests/axis_synome/spec_support/runtime/test_math.py
 tests/axis_synome/spec_validator/test_checker.py
-tests/axis_synome/spec_validator/test_flake8_plugin.py
+tests/axis_synome/spec_validator/test_flake8_plugin.py
+tests/axis_synome/suraf/__init__.py
+tests/axis_synome/suraf/entities/__init__.py
+tests/axis_synome/suraf/entities/test_assessor_score.py
+tests/axis_synome/suraf/formulas/__init__.py
+tests/axis_synome/suraf/formulas/test_crr.py
+tests/axis_synome/suraf/formulas/test_scoring.py
+tests/axis_synome/suraf/static/aave_ausdc/v1/crr_mapping.csv
+tests/axis_synome/suraf/static/aave_ausdc/v1/penalty.csv
+tests/axis_synome/suraf/static/aave_ausdc/v1/weights.csv
+tests/axis_synome/suraf/static/aave_ausdc/v1/scorecards/Assessor_1_scores.csv
+tests/axis_synome/suraf/static/aave_ausdc/v1/scorecards/Assessor_2_scores.csv
+tests/axis_synome/suraf/static/aave_ausdc/v1/scorecards/Assessor_3_scores.csv
+tests/axis_synome/suraf/suraf_client/__init__.py
+tests/axis_synome/suraf/suraf_client/suraf_client.py
+tests/axis_synome/suraf/suraf_client/test_suraf_client.py

axis_synome-0.1.0.dev31/tests/axis_synome/suraf/entities/test_assessor_score.py

@@ -0,0 +1,33 @@
+"""Tests for AssessorScore entity validation."""
+
+import pytest
+from pydantic import ValidationError
+
+from axis_synome.spec.suraf.entities.assessor_score import AssessorScore
+
+
+class TestAssessorScoreValidation:
+    def test_boundary_scores_accepted(self):
+        a = AssessorScore(scores=[(10, [(5, 1), (5, 5)])])
+        assert len(a.scores) == 1
+        assert len(a.scores[0][1]) == 2
+
+    def test_score_below_min_rejected(self):
+        with pytest.raises(ValidationError):
+            AssessorScore(scores=[(10, [(5, 0)])])
+
+    def test_score_above_max_rejected(self):
+        with pytest.raises(ValidationError):
+            AssessorScore(scores=[(10, [(5, 6)])])
+
+    def test_empty_scores_list_accepted(self):
+        a = AssessorScore(scores=[])
+        assert a.scores == []
+
+    def test_empty_sections_in_pillar_accepted(self):
+        a = AssessorScore(scores=[(10, [])])
+        assert a.scores[0][1] == []
+
+    def test_large_absolute_weights_accepted(self):
+        a = AssessorScore(scores=[(40, [(8, 3), (12, 4)])])
+        assert len(a.scores) == 1