sable-sphynx 0.7.0.dev0__py3-none-any.whl

sphynx/analytical_views.py

@@ -0,0 +1,515 @@
+"""Typed permitted analytical snapshots. The service owns access and policy."""
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from datetime import datetime
+import html
+import json
+import re
+from types import MappingProxyType
+from typing import Any
+
+from ._analytical_values import (
+    MetricProjectionSummary, ProjectionSummary, ReportProjectionSummary, _Values,
+    count, digest, frame, identifier, identity, keys, parse_json, require, sha, summary, text,
+)
+from .audit_contracts import BankRelease
+from .evaluation_protocols import VersionedIdentity
+
+
+def _display(value: object) -> str:
+    result = ''.join(char if char.isprintable() else ' ' for char in str(value))
+    return result if len(result) <= 256 else result[:256] + '… (full value in to_dict())'
+
+
+def _cell(value: object) -> str:
+    return re.sub(r'([\\`*_{}\[\]()#+.!|>~\-])', r'\\\1', html.escape(_display(value)))
+
+
+def _details(value: Mapping[str, Any]) -> str:
+    raw = json.dumps(value, ensure_ascii=False, indent=2, allow_nan=False)
+    return '\n\n<details><summary>Permitted record details</summary>\n\n<pre>' + html.escape(raw) + '</pre>\n</details>'
+
+
+@dataclass(frozen=True)
+class ProjectionRow(_Values):
+    """One permitted summary, checked against its exact stored hash frames."""
+    team_id: str
+    event_id: str
+    row_id: str
+    row_hash: str
+    row_kind: str
+    record_id: str
+    bank_id: str
+    release_id: str
+    cohort_id: str
+    source_version: int
+    summary_json: str = field(repr=False)
+    source_digest: str
+    plan_digest: str
+    manifest_digest: str
+    row_count: int
+    commit_hash: str
+
+    def __post_init__(self) -> None:
+        for name in ('team_id', 'event_id', 'record_id', 'bank_id', 'release_id'):
+            identifier(getattr(self, name))
+        identifier(self.cohort_id, empty=True)
+        require(count(self.source_version, nullable=False) != 0)
+        require(count(self.row_count, nullable=False, maximum=4096) != 0)
+        for name in ('row_id', 'row_hash', 'source_digest', 'plan_digest', 'manifest_digest', 'commit_hash'):
+            digest(getattr(self, name))
+        value = self.summary
+        body = json.dumps({'schema_version': 'sphynx.evaluation.' + self.row_kind + '-summary.v2',
+                           'summary': value.to_dict()}, sort_keys=True, ensure_ascii=False,
+                          allow_nan=False, separators=(',', ':'))
+        # Only integer counts and exact score bits occur in this schema. Never
+        # canonicalize native floating point payloads with this JSON profile.
+        canonical_summary = json.dumps(value.to_dict(), sort_keys=True, ensure_ascii=False,
+                                       allow_nan=False, separators=(',', ':'))
+        require(canonical_summary == self.summary_json, 'analytical summary bytes differ')
+        expected_id = sha(frame('sphynx.evaluation.row-id.v2', self.row_kind, self.record_id,
+                                self.bank_id, self.release_id, self.cohort_id, self.source_version))
+        require(self.row_id == expected_id, 'analytical row identity differs')
+        expected_hash = sha(frame('sphynx.evaluation.row.v2', self.team_id, self.event_id,
+                                  self.row_id, self.row_kind, self.record_id, self.bank_id,
+                                  self.release_id, self.cohort_id, self.source_version, body))
+        require(self.row_hash == expected_hash, 'analytical row hash differs')
+        plan = sha(frame('sphynx.evaluation.plan.v2', self.team_id, self.event_id,
+                         self.source_digest, self.manifest_digest, self.row_count))
+        commit = sha(frame('sphynx.evaluation.commit.v2', plan, self.source_digest,
+                           self.manifest_digest, self.row_count))
+        require(self.plan_digest == plan and self.commit_hash == commit,
+                'analytical commit hash differs')
+
+    @property
+    def summary(self) -> ProjectionSummary:
+        require(type(self.row_kind) is str and self.row_kind in ('report', 'metric', 'comparison', 'audit'))
+        return summary(self.row_kind, parse_json(self.summary_json))
+
+    @classmethod
+    def from_dict(cls, value: Mapping[str, Any]) -> ProjectionRow:
+        return cls(**keys(value, {'team_id', 'event_id', 'row_id', 'row_hash', 'row_kind',
+            'record_id', 'bank_id', 'release_id', 'cohort_id', 'source_version', 'summary_json',
+            'source_digest', 'plan_digest', 'manifest_digest', 'row_count', 'commit_hash'}))
+
+
+@dataclass(frozen=True)
+class ProjectionEventRef(_Values):
+    """A known source reference; it does not grant read access."""
+    event_id: str
+    source_digest: str
+
+    def __post_init__(self) -> None:
+        identifier(self.event_id)
+        digest(self.source_digest)
+
+    @classmethod
+    def from_dict(cls, value: Mapping[str, Any]) -> ProjectionEventRef:
+        return cls(**keys(value, {'event_id', 'source_digest'}))
+
+
+@dataclass(frozen=True)
+class ProjectionResult(_Values):
+    """A complete committed inventory, or an explicit unavailable result."""
+    event_id: str
+    source_digest: str
+    availability: str
+    reason: str | None
+    rows: tuple[ProjectionRow, ...] = field(repr=False)
+
+    def __post_init__(self) -> None:
+        ProjectionEventRef(self.event_id, self.source_digest)
+        require(isinstance(self.rows, (tuple, list)) and len(self.rows) <= 4096)
+        require(all(isinstance(row, ProjectionRow) for row in self.rows))
+        rows = tuple(sorted(self.rows, key=lambda row: row.row_id))
+        object.__setattr__(self, 'rows', rows)
+        require(self.availability in ('available', 'unavailable'))
+        if self.availability == 'unavailable':
+            require(not rows and self.reason == 'projection_not_committed')
+            return
+        require(bool(rows) and self.reason is None)
+        first = rows[0]
+        require(len(rows) == first.row_count and len({row.row_id for row in rows}) == len(rows),
+                'analytical inventory is incomplete')
+        for row in rows:
+            require(row.event_id == self.event_id and row.source_digest == self.source_digest)
+            require(all(getattr(row, name) == getattr(first, name) for name in (
+                'team_id', 'bank_id', 'release_id', 'cohort_id', 'row_count',
+                'plan_digest', 'manifest_digest', 'commit_hash')))
+        manifest = sha(frame('sphynx.evaluation.manifest.v2',
+                             '\n'.join(row.row_id + '\t' + row.row_hash for row in rows)))
+        require(manifest == first.manifest_digest, 'analytical inventory hash differs')
+
+    @classmethod
+    def from_dict(cls, value: Mapping[str, Any]) -> ProjectionResult:
+        values = keys(value, {'event_id', 'source_digest', 'availability', 'reason', 'rows'})
+        require(isinstance(values['rows'], (tuple, list)))
+        values['rows'] = tuple(ProjectionRow.from_dict(row) for row in values['rows'])
+        return cls(**values)
+
+
+@dataclass(frozen=True)
+class ProjectionSelection(_Values):
+    board_id: str
+    board_version: str
+    entry_id: str
+    definition_digest: str
+
+    def __post_init__(self) -> None:
+        for name in ('board_id', 'entry_id'):
+            identifier(getattr(self, name))
+        text(self.board_version)
+        digest(self.definition_digest)
+
+    @classmethod
+    def from_dict(cls, value: Mapping[str, Any]) -> ProjectionSelection:
+        return cls(**keys(value, {'board_id', 'board_version', 'entry_id', 'definition_digest'}))
+
+
+@dataclass(frozen=True)
+class ProjectionPage(_Values):
+    """Historical committed data; current policy requires a service check."""
+    team_id: str
+    bank_id: str
+    release_id: str
+    cohort_id: str
+    authority: str
+    items: tuple[ProjectionResult, ...] = field(repr=False)
+    selection: ProjectionSelection | None = None
+
+    def __post_init__(self) -> None:
+        for name in ('team_id', 'bank_id', 'release_id', 'cohort_id'):
+            identifier(getattr(self, name))
+        require(self.authority == 'committed_snapshot_requires_current_service_check')
+        require(isinstance(self.items, (tuple, list)) and 1 <= len(self.items) <= 25)
+        require(all(isinstance(item, ProjectionResult) for item in self.items))
+        require(len({item.event_id for item in self.items}) == len(self.items))
+        require(sum(len(item.rows) for item in self.items) <= 4096)
+        require(self.selection is None or isinstance(self.selection, ProjectionSelection))
+        object.__setattr__(self, 'items', tuple(self.items))
+        for row in self.rows:
+            require(row.team_id == self.team_id and row.bank_id == self.bank_id
+                    and row.release_id == self.release_id
+                    and (row.cohort_id == self.cohort_id or row.row_kind == 'audit' and row.cohort_id == ''),
+                    'analytical page scope differs')
+
+    @property
+    def rows(self) -> tuple[ProjectionRow, ...]:
+        return tuple(row for item in self.items for row in item.rows)
+
+    @property
+    def source_refs(self) -> tuple[ProjectionEventRef, ...]:
+        return tuple(ProjectionEventRef(item.event_id, item.source_digest) for item in self.items)
+
+    def to_text(self) -> str:
+        available = sum(item.availability == 'available' for item in self.items)
+        return (f'Projection snapshot: {available}/{len(self.items)} committed events; {len(self.rows)} rows. '
+                'Current ranking and acceptance require a service check.')
+
+    def to_markdown(self, *, include_details: bool = False) -> str:
+        require(type(include_details) is bool)
+        lines = [self.to_text(), '', '| Event | Availability | Rows | Reason |', '| --- | --- | --- | --- |']
+        for item in self.items:
+            lines.append('| ' + ' | '.join(_cell(value) for value in (
+                item.event_id, item.availability, len(item.rows), item.reason or '—')) + ' |')
+        result = '\n'.join(lines)
+        return result + _details(self.to_dict()) if include_details else result
+
+    def to_dict(self) -> dict[str, Any]:
+        result = {'schema_version': 'sphynx.evaluation.projection-page.v2',
+                  **super().to_dict()}
+        if self.selection is None:
+            del result['selection']
+        return result
+
+    @classmethod
+    def from_dict(cls, value: Mapping[str, Any]) -> ProjectionPage:
+        names = {'schema_version', 'team_id', 'bank_id', 'release_id', 'cohort_id', 'authority', 'items'}
+        require(isinstance(value, Mapping))
+        if 'selection' in value:
+            names.add('selection')
+        values = keys(value, names)
+        require(values.pop('schema_version') == 'sphynx.evaluation.projection-page.v2')
+        require(isinstance(values['items'], (tuple, list)))
+        values['items'] = tuple(ProjectionResult.from_dict(item) for item in values['items'])
+        if 'selection' in values:
+            values['selection'] = ProjectionSelection.from_dict(values['selection'])
+        return cls(**values)
+
+
+@dataclass(frozen=True)
+class ProjectionProof(_Values):
+    """Source evidence retained on a service board entry, without raw rows."""
+    event_id: str
+    source_digest: str
+    plan_digest: str
+    manifest_digest: str
+    row_count: int
+    commit_hash: str
+
+    def __post_init__(self) -> None:
+        identifier(self.event_id)
+        for name in ('source_digest', 'plan_digest', 'manifest_digest', 'commit_hash'):
+            digest(getattr(self, name))
+        require(count(self.row_count, nullable=False, maximum=4096) != 0)
+        require(self.commit_hash == sha(frame('sphynx.evaluation.commit.v2', self.plan_digest,
+            self.source_digest, self.manifest_digest, self.row_count)))
+
+    @classmethod
+    def from_dict(cls, value: Mapping[str, Any]) -> ProjectionProof:
+        return cls(**keys(value, {'event_id', 'source_digest', 'plan_digest',
+                                  'manifest_digest', 'row_count', 'commit_hash'}))
+
+
+@dataclass(frozen=True)
+class BoardRanking(_Values):
+    """Declared metric meaning. This value contains no private rank policy."""
+    metric_id: str
+    unit: str
+    direction: str
+    ties: str
+    population_id: str
+    method_id: str
+    uncertainty_id: str | None
+
+    def __post_init__(self) -> None:
+        for name in ('metric_id', 'unit', 'population_id', 'method_id'):
+            text(getattr(self, name))
+        require(self.direction in ('higher', 'lower') and self.ties == 'competition')
+        if self.uncertainty_id is not None:
+            text(self.uncertainty_id)
+
+    @classmethod
+    def from_dict(cls, value: Mapping[str, Any]) -> BoardRanking:
+        return cls(**keys(value, {'metric_id', 'unit', 'direction', 'ties', 'population_id',
+                                  'method_id', 'uncertainty_id'}))
+
+
+@dataclass(frozen=True)
+class BoardCoverage(_Values):
+    selected: int
+    projected: int
+    pending: int
+    rank_eligible: int
+
+    def __post_init__(self) -> None:
+        for name in ('selected', 'projected', 'pending', 'rank_eligible'):
+            count(getattr(self, name), nullable=False, maximum=1000)
+        # These are board source states, not native metric population counts.
+        require(self.projected + self.pending == self.selected and self.rank_eligible <= self.projected)
+
+    @classmethod
+    def from_dict(cls, value: Mapping[str, Any]) -> BoardCoverage:
+        return cls(**keys(value, {'selected', 'projected', 'pending', 'rank_eligible'}))
+
+
+@dataclass(frozen=True)
+class BoardEntry(_Values):
+    entry_id: str
+    candidate: VersionedIdentity = field(repr=False)
+    run_id: str = field(repr=False)
+    grading_id: str = field(repr=False)
+    state: str
+    rank_eligible: bool
+    provisional: bool
+    rank: int | None
+    reasons: tuple[str, ...]
+    report: ReportProjectionSummary | None = field(repr=False)
+    metric: MetricProjectionSummary | None = field(repr=False)
+    projection: ProjectionProof | None
+
+    def __post_init__(self) -> None:
+        identifier(self.entry_id)
+        text(self.run_id); text(self.grading_id)
+        require(isinstance(self.candidate, VersionedIdentity) and self.candidate.digest is not None)
+        require(type(self.rank_eligible) is bool and type(self.provisional) is bool)
+        require(self.state in ('pending', 'unranked', 'provisional', 'ranked'))
+        require(isinstance(self.reasons, (tuple, list)) and len(self.reasons) <= 32)
+        for reason in self.reasons:
+            text(reason)
+        object.__setattr__(self, 'reasons', tuple(self.reasons))
+        count(self.rank, maximum=1000)
+        require(self.rank != 0 and (self.rank is not None) == self.rank_eligible)
+        require(self.report is None or isinstance(self.report, ReportProjectionSummary))
+        require(self.metric is None or isinstance(self.metric, MetricProjectionSummary))
+        require(self.projection is None or isinstance(self.projection, ProjectionProof))
+        if self.state == 'pending':
+            require(not self.rank_eligible and self.projection is None and self.report is None
+                    and self.metric is None and bool(self.reasons))
+        else:
+            require(self.projection is not None)
+        if self.rank_eligible:
+            require(not self.reasons and self.state == ('provisional' if self.provisional else 'ranked'))
+            require(self.report is not None and self.metric is not None)
+            assert self.metric is not None
+            require(self.metric.availability == 'available' and self.metric.value_kind == 'score')
+        else:
+            require(bool(self.reasons) and self.state != 'ranked')
+        if self.report is not None:
+            require(self.report.grading_id == self.grading_id)
+        if self.metric is not None:
+            require(self.metric.grading_id == self.grading_id)
+
+    @classmethod
+    def from_dict(cls, value: Mapping[str, Any]) -> BoardEntry:
+        values = keys(value, {'entry_id', 'candidate', 'run_id', 'grading_id', 'state',
+            'rank_eligible', 'provisional', 'rank', 'reasons', 'report', 'metric', 'projection'})
+        values['candidate'] = identity(values['candidate'])
+        for name, reader in (('report', ReportProjectionSummary), ('metric', MetricProjectionSummary),
+                             ('projection', ProjectionProof)):
+            if values[name] is not None:
+                values[name] = reader.from_dict(values[name])
+        return cls(**values)
+
+
+def board_cursor(value: Any, *, snapshot: str | None = None, after: str | None = None) -> str:
+    require(type(value) is str and value.startswith('v2:') and len(value) <= 2048,
+            'invalid board cursor; retain the original request')
+    try:
+        raw = bytes.fromhex(value[3:]).decode('utf-8')
+    except (ValueError, UnicodeError):
+        require(False, 'invalid board cursor; retain the original request')
+        raise AssertionError('unreachable')
+    parsed = keys(parse_json(raw), {'schema_version', 'snapshot_digest', 'after_entry_id'})
+    require(parsed['schema_version'] == 'sphynx.evaluation-board-cursor.v2')
+    digest(parsed['snapshot_digest']); identifier(parsed['after_entry_id'])
+    require(snapshot is None or snapshot == parsed['snapshot_digest'], 'board cursor snapshot differs')
+    require(after is None or after == parsed['after_entry_id'], 'board cursor entry differs')
+    return value
+
+
+@dataclass(frozen=True)
+class EvaluationBoardPage(_Values):
+    """A bounded page from a current authorized service check, not PR acceptance."""
+    authority: str
+    team_id: str
+    bank_id: str
+    board_id: str
+    board_version: str
+    definition_digest: str
+    cohort: VersionedIdentity = field(repr=False)
+    conditions: Mapping[str, VersionedIdentity] = field(repr=False)
+    scope: str
+    mode: str
+    ranking: BoardRanking
+    ranking_scope: str
+    bank_release: BankRelease = field(repr=False)
+    coverage: BoardCoverage
+    projection_coverage_complete: bool
+    snapshot_digest: str
+    checked_at: str
+    total_entries: int
+    limit: int
+    entries: tuple[BoardEntry, ...] = field(repr=False)
+    next_cursor: str | None = field(repr=False)
+
+    def __post_init__(self) -> None:
+        require(self.authority == 'current_service_check')
+        for name in ('team_id', 'bank_id', 'board_id'):
+            identifier(getattr(self, name))
+        text(self.board_version); digest(self.definition_digest); digest(self.snapshot_digest)
+        require(isinstance(self.cohort, VersionedIdentity) and self.cohort.digest is not None)
+        identifier(self.cohort.identity_id)
+        require(isinstance(self.conditions, Mapping) and {'protocol', 'bank', 'evaluator', 'runtime'} <= set(self.conditions)
+                and set(self.conditions) <= {'protocol', 'bank', 'evaluator', 'runtime', 'labels', 'references', 'hardware'})
+        require(all(isinstance(value, VersionedIdentity) and value.digest is not None for value in self.conditions.values()))
+        object.__setattr__(self, 'conditions', MappingProxyType(dict(self.conditions)))
+        require(self.scope in ('component', 'subsystem', 'system') and self.mode in ('local', 'hosted'))
+        require(isinstance(self.ranking, BoardRanking) and self.ranking_scope == 'verified_available_entries')
+        require(isinstance(self.bank_release, BankRelease) and self.bank_release.bank_id == self.bank_id
+                and self.bank_release.team_id == self.team_id)
+        require(all(self.conditions[key] == self.bank_release.bindings.get(key)
+                    for key in ('bank', 'labels', 'references') if key in self.conditions))
+        require(isinstance(self.coverage, BoardCoverage))
+        require(type(self.projection_coverage_complete) is bool
+                and self.projection_coverage_complete == (self.coverage.pending == 0))
+        count(self.total_entries, nullable=False, maximum=1000)
+        require(self.total_entries == self.coverage.selected)
+        require(count(self.limit, nullable=False, maximum=100) != 0)
+        require(isinstance(self.entries, (tuple, list)) and len(self.entries) <= min(self.limit, self.total_entries)
+                and all(isinstance(entry, BoardEntry) for entry in self.entries))
+        object.__setattr__(self, 'entries', tuple(self.entries))
+        require(len({entry.entry_id for entry in self.entries}) == len(self.entries))
+        require(len({(entry.candidate.identity_id, entry.candidate.version, entry.candidate.digest)
+                     for entry in self.entries}) == len(self.entries))
+        try:
+            checked = datetime.fromisoformat(self.checked_at)
+            require(checked.tzinfo is not None)
+        except (ValueError, TypeError, OverflowError):
+            require(False, 'invalid board check timestamp')
+        for entry in self.entries:
+            if entry.projection is not None:
+                proof = entry.projection
+                expected = sha(frame('sphynx.evaluation.plan.v2', self.team_id, proof.event_id,
+                                     proof.source_digest, proof.manifest_digest, proof.row_count))
+                require(proof.plan_digest == expected)
+            if entry.rank_eligible:
+                require(bool(self.bank_release.eligibility['ranking']['eligible']))
+                require(entry.report is not None and entry.metric is not None)
+                assert entry.report is not None and entry.metric is not None
+                require(entry.report.bindings == {**self.conditions, 'candidate': entry.candidate}
+                        and entry.report.run_id == entry.run_id and entry.metric.run_id == entry.run_id
+                        and entry.report.scope == self.scope and entry.report.mode == self.mode)
+                require(all(getattr(entry.metric, name) == getattr(self.ranking, name) for name in (
+                    'metric_id', 'unit', 'direction', 'population_id', 'method_id', 'uncertainty_id')))
+                require(entry.rank is not None and entry.rank <= self.coverage.rank_eligible)
+        if self.next_cursor is not None:
+            require(bool(self.entries) and len(self.entries) == self.limit)
+            board_cursor(self.next_cursor, snapshot=self.snapshot_digest, after=self.entries[-1].entry_id)
+
+    def to_dict(self) -> dict[str, Any]:
+        result = {'schema_version': 'sphynx.evaluation-board.v2', **super().to_dict()}
+        result['bank_release'] = self.bank_release.to_dict()
+        return result
+
+    def to_text(self) -> str:
+        heading = (f'Board {self.board_id}: {len(self.entries)}/{self.total_entries} entries shown; '
+                f'{self.coverage.pending} pending projections; {self.coverage.rank_eligible} rank eligible. '
+                f'Checked {self.checked_at}. Rank is separate from PR acceptance.')
+        return '\n'.join([heading, *(f'{entry.rank if entry.rank is not None else "—"}. '
+            + _display(entry.candidate.identity_id) + ': ' + _display(_entry_value(entry))
+            + ' [' + entry.state + ']' + (': ' + ', '.join(_display(reason) for reason in entry.reasons) if entry.reasons else '')
+            for entry in self.entries)])
+
+    def to_markdown(self, *, include_details: bool = False) -> str:
+        require(type(include_details) is bool)
+        lines = [f'Board **{_cell(self.board_id)}**: {len(self.entries)}/{self.total_entries} entries shown; '
+                 f'{self.coverage.pending} pending projections; {self.coverage.rank_eligible} rank eligible.',
+                 '', 'Rank is separate from PR acceptance. The service checked this snapshot at ' + _cell(self.checked_at) + '.',
+                 '', '| Rank | Candidate | Value | State | Reasons |', '| --- | --- | --- | --- | --- |']
+        for entry in self.entries:
+            lines.append('| ' + ' | '.join(_cell(value) for value in (
+                entry.rank if entry.rank is not None else '—', entry.candidate.identity_id,
+                _entry_value(entry), entry.state, ', '.join(entry.reasons) or '—')) + ' |')
+        result = '\n'.join(lines)
+        return result + _details(self.to_dict()) if include_details else result
+
+    @classmethod
+    def from_dict(cls, value: Mapping[str, Any]) -> EvaluationBoardPage:
+        values = keys(value, {'schema_version', 'authority', 'team_id', 'bank_id', 'board_id',
+            'board_version', 'definition_digest', 'cohort', 'conditions', 'scope', 'mode', 'ranking',
+            'ranking_scope', 'bank_release', 'coverage', 'projection_coverage_complete', 'snapshot_digest',
+            'checked_at', 'total_entries', 'limit', 'entries', 'next_cursor'})
+        require(values.pop('schema_version') == 'sphynx.evaluation-board.v2')
+        values['cohort'] = identity(values['cohort'])
+        require(isinstance(values['conditions'], Mapping))
+        values['conditions'] = {name: identity(item) for name, item in values['conditions'].items()}
+        values['ranking'] = BoardRanking.from_dict(values['ranking'])
+        values['bank_release'] = BankRelease.from_dict(values['bank_release'])
+        values['coverage'] = BoardCoverage.from_dict(values['coverage'])
+        require(isinstance(values['entries'], (tuple, list)))
+        values['entries'] = tuple(BoardEntry.from_dict(entry) for entry in values['entries'])
+        return cls(**values)
+
+
+def _entry_value(entry: BoardEntry) -> str:
+    metric = entry.metric
+    if metric is None:
+        return 'pending projection' if entry.state == 'pending' else 'metric unavailable'
+    if metric.availability != 'available':
+        return metric.availability
+    if metric.value_kind == 'custom':
+        return 'custom value in native report'
+    return f'{metric.value} {metric.unit}'