value-semantics-core 2.1.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- value_semantics_core/__init__.py +157 -0
- value_semantics_core/comps_manifest_display.py +99 -0
- value_semantics_core/conventions_ir_v1.py +503 -0
- value_semantics_core/decimal_wire.py +43 -0
- value_semantics_core/enterprise_value.py +223 -0
- value_semantics_core/formatting.py +220 -0
- value_semantics_core/forward_ev_adjusted_ebitda.py +669 -0
- value_semantics_core/forward_pe.py +751 -0
- value_semantics_core/numeric_display.py +129 -0
- value_semantics_core/period_ref.py +120 -0
- value_semantics_core/quantity.py +18 -0
- value_semantics_core/reconciliation.py +362 -0
- value_semantics_core-2.1.0.dist-info/METADATA +6 -0
- value_semantics_core-2.1.0.dist-info/RECORD +16 -0
- value_semantics_core-2.1.0.dist-info/WHEEL +5 -0
- value_semantics_core-2.1.0.dist-info/top_level.txt +1 -0
|
@@ -0,0 +1,129 @@
|
|
|
1
|
+
"""Canonical presentation semantics for typed numeric values."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
from typing import Literal
|
|
6
|
+
|
|
7
|
+
from pydantic import (
|
|
8
|
+
BaseModel,
|
|
9
|
+
ConfigDict,
|
|
10
|
+
Field,
|
|
11
|
+
field_validator,
|
|
12
|
+
model_validator,
|
|
13
|
+
)
|
|
14
|
+
|
|
15
|
+
from .conventions_ir_v1 import CONVENTIONS_IR_V1
|
|
16
|
+
|
|
17
|
+
|
|
18
|
+
ISO_4217_ALPHA_CODES = frozenset(CONVENTIONS_IR_V1.iso_4217_alpha_codes)
|
|
19
|
+
|
|
20
|
+
_UNIT_LABEL_CONTROL_CHARACTER_RANGES = r"\u0000-\u001F\u007F-\u009F"
|
|
21
|
+
UNIT_LABEL_CONTROL_CHARACTER_PATTERN = rf"[{_UNIT_LABEL_CONTROL_CHARACTER_RANGES}]"
|
|
22
|
+
UNIT_LABEL_PATTERN = rf"^[^{_UNIT_LABEL_CONTROL_CHARACTER_RANGES}]+$"
|
|
23
|
+
|
|
24
|
+
NumericKind = Literal[
|
|
25
|
+
"currency",
|
|
26
|
+
"percentage",
|
|
27
|
+
"basis_points",
|
|
28
|
+
"multiple",
|
|
29
|
+
"count",
|
|
30
|
+
"per_share",
|
|
31
|
+
"ratio",
|
|
32
|
+
"index",
|
|
33
|
+
"duration",
|
|
34
|
+
"date",
|
|
35
|
+
"weight",
|
|
36
|
+
]
|
|
37
|
+
NumericScale = Literal["unit", "thousands", "millions", "billions"]
|
|
38
|
+
DenominatorBasis = Literal[
|
|
39
|
+
"nav",
|
|
40
|
+
"gross_exposure",
|
|
41
|
+
"net_exposure",
|
|
42
|
+
"portfolio_value",
|
|
43
|
+
"total_market_value",
|
|
44
|
+
"benchmark_total",
|
|
45
|
+
"fund_total",
|
|
46
|
+
]
|
|
47
|
+
|
|
48
|
+
|
|
49
|
+
# ``frozen=True`` is passed as a class keyword (PEP 681) rather than only in
|
|
50
|
+
# ``model_config`` so type checkers see the fields as read-only, which is what
|
|
51
|
+
# lets subclasses narrow them to literals (schema/earnings_preview.py).
|
|
52
|
+
class NumericDisplaySpec(BaseModel, frozen=True):
|
|
53
|
+
"""Complete display semantics for one canonical numeric value or series."""
|
|
54
|
+
|
|
55
|
+
model_config = ConfigDict(
|
|
56
|
+
extra="forbid",
|
|
57
|
+
populate_by_name=True,
|
|
58
|
+
str_strip_whitespace=True,
|
|
59
|
+
strict=True,
|
|
60
|
+
)
|
|
61
|
+
|
|
62
|
+
numeric_kind: NumericKind
|
|
63
|
+
scale: NumericScale = "unit"
|
|
64
|
+
currency: str | None = Field(default=None, min_length=3, max_length=3)
|
|
65
|
+
denominator_basis: DenominatorBasis | None = None
|
|
66
|
+
precision: int = Field(default=1, ge=0, le=8)
|
|
67
|
+
unit_label: str | None = Field(
|
|
68
|
+
default=None,
|
|
69
|
+
min_length=1,
|
|
70
|
+
pattern=UNIT_LABEL_PATTERN,
|
|
71
|
+
)
|
|
72
|
+
|
|
73
|
+
@field_validator("currency")
|
|
74
|
+
@classmethod
|
|
75
|
+
def _validate_currency(cls, value: str | None) -> str | None:
|
|
76
|
+
if value is None:
|
|
77
|
+
return None
|
|
78
|
+
code = value.upper()
|
|
79
|
+
if code not in ISO_4217_ALPHA_CODES:
|
|
80
|
+
raise ValueError("currency must be a pinned ISO 4217 alphabetic code")
|
|
81
|
+
return code
|
|
82
|
+
|
|
83
|
+
@field_validator("unit_label", mode="before")
|
|
84
|
+
@classmethod
|
|
85
|
+
def _reject_unit_label_control_characters(cls, value: object) -> object:
|
|
86
|
+
if isinstance(value, str) and any(
|
|
87
|
+
ord(character) <= 0x1F or 0x7F <= ord(character) <= 0x9F
|
|
88
|
+
for character in value
|
|
89
|
+
):
|
|
90
|
+
raise ValueError("unit_label must not contain control characters")
|
|
91
|
+
return value
|
|
92
|
+
|
|
93
|
+
@model_validator(mode="after")
|
|
94
|
+
def _validate_semantics(self) -> "NumericDisplaySpec":
|
|
95
|
+
monetary = self.numeric_kind in {"currency", "per_share"}
|
|
96
|
+
if monetary != (self.currency is not None):
|
|
97
|
+
raise ValueError(
|
|
98
|
+
"currency/per_share display requires currency; other kinds prohibit it"
|
|
99
|
+
)
|
|
100
|
+
if self.numeric_kind == "per_share" and self.scale != "unit":
|
|
101
|
+
raise ValueError("per_share display requires unit scale")
|
|
102
|
+
if (self.numeric_kind == "weight") != (self.denominator_basis is not None):
|
|
103
|
+
raise ValueError(
|
|
104
|
+
"weight display requires denominator_basis; other kinds prohibit it"
|
|
105
|
+
)
|
|
106
|
+
if self.numeric_kind in {"basis_points", "weight"} and self.scale != "unit":
|
|
107
|
+
raise ValueError("basis_points/weight display requires unit scale")
|
|
108
|
+
if self.scale != "unit" and self.numeric_kind not in {"currency", "count"}:
|
|
109
|
+
raise ValueError("scaled display is only valid for currency or count")
|
|
110
|
+
if (
|
|
111
|
+
self.numeric_kind in {"percentage", "basis_points"}
|
|
112
|
+
and self.unit_label is not None
|
|
113
|
+
):
|
|
114
|
+
raise ValueError(
|
|
115
|
+
"percentage/basis_points display has canonical labeling and "
|
|
116
|
+
"prohibits unit_label"
|
|
117
|
+
)
|
|
118
|
+
return self
|
|
119
|
+
|
|
120
|
+
|
|
121
|
+
__all__ = [
|
|
122
|
+
"DenominatorBasis",
|
|
123
|
+
"ISO_4217_ALPHA_CODES",
|
|
124
|
+
"NumericDisplaySpec",
|
|
125
|
+
"NumericKind",
|
|
126
|
+
"NumericScale",
|
|
127
|
+
"UNIT_LABEL_CONTROL_CHARACTER_PATTERN",
|
|
128
|
+
"UNIT_LABEL_PATTERN",
|
|
129
|
+
]
|
|
@@ -0,0 +1,120 @@
|
|
|
1
|
+
"""Closed typed PeriodRef v1 contract and derived canonical labels."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
from datetime import date as calendar_date
|
|
6
|
+
from typing import Annotated, Literal, TypeAlias
|
|
7
|
+
|
|
8
|
+
from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
|
|
9
|
+
|
|
10
|
+
|
|
11
|
+
_YEAR_MIN = 1900
|
|
12
|
+
_YEAR_MAX = 2200
|
|
13
|
+
_ISO_DATE_PATTERN = r"^[0-9]{4}-[0-9]{2}-[0-9]{2}$"
|
|
14
|
+
|
|
15
|
+
BoundedYear: TypeAlias = Annotated[int, Field(ge=_YEAR_MIN, le=_YEAR_MAX)]
|
|
16
|
+
|
|
17
|
+
|
|
18
|
+
class _PeriodRefVariant(BaseModel):
|
|
19
|
+
model_config = ConfigDict(extra="forbid", frozen=True, strict=True)
|
|
20
|
+
|
|
21
|
+
def canonical_label(self) -> str:
|
|
22
|
+
raise NotImplementedError
|
|
23
|
+
|
|
24
|
+
def _ordering_key(self) -> tuple[int | str, ...]:
|
|
25
|
+
raise NotImplementedError
|
|
26
|
+
|
|
27
|
+
|
|
28
|
+
class FiscalYearPeriod(_PeriodRefVariant):
|
|
29
|
+
kind: Literal["fiscal_year"]
|
|
30
|
+
fiscal_year: BoundedYear
|
|
31
|
+
|
|
32
|
+
def canonical_label(self) -> str:
|
|
33
|
+
return f"FY{self.fiscal_year}"
|
|
34
|
+
|
|
35
|
+
def _ordering_key(self) -> tuple[int | str, ...]:
|
|
36
|
+
return (self.fiscal_year,)
|
|
37
|
+
|
|
38
|
+
|
|
39
|
+
class FiscalQuarterPeriod(_PeriodRefVariant):
|
|
40
|
+
kind: Literal["fiscal_quarter"]
|
|
41
|
+
fiscal_year: BoundedYear
|
|
42
|
+
quarter: Annotated[int, Field(ge=1, le=4)]
|
|
43
|
+
|
|
44
|
+
def canonical_label(self) -> str:
|
|
45
|
+
return f"FY{self.fiscal_year}-Q{self.quarter}"
|
|
46
|
+
|
|
47
|
+
def _ordering_key(self) -> tuple[int | str, ...]:
|
|
48
|
+
return (self.fiscal_year, self.quarter)
|
|
49
|
+
|
|
50
|
+
|
|
51
|
+
class DatePeriod(_PeriodRefVariant):
|
|
52
|
+
kind: Literal["date"]
|
|
53
|
+
date: Annotated[str, Field(pattern=_ISO_DATE_PATTERN)]
|
|
54
|
+
|
|
55
|
+
@field_validator("date")
|
|
56
|
+
@classmethod
|
|
57
|
+
def _require_real_iso_date(cls, value: str) -> str:
|
|
58
|
+
try:
|
|
59
|
+
calendar_date.fromisoformat(value)
|
|
60
|
+
except ValueError as exc:
|
|
61
|
+
raise ValueError("date must be a real ISO calendar date") from exc
|
|
62
|
+
return value
|
|
63
|
+
|
|
64
|
+
def canonical_label(self) -> str:
|
|
65
|
+
return self.date
|
|
66
|
+
|
|
67
|
+
def _ordering_key(self) -> tuple[int | str, ...]:
|
|
68
|
+
return (self.date,)
|
|
69
|
+
|
|
70
|
+
|
|
71
|
+
class CalendarYearPeriod(_PeriodRefVariant):
|
|
72
|
+
kind: Literal["calendar_year"]
|
|
73
|
+
calendar_year: BoundedYear
|
|
74
|
+
|
|
75
|
+
def canonical_label(self) -> str:
|
|
76
|
+
return f"CY{self.calendar_year}"
|
|
77
|
+
|
|
78
|
+
def _ordering_key(self) -> tuple[int | str, ...]:
|
|
79
|
+
return (self.calendar_year,)
|
|
80
|
+
|
|
81
|
+
|
|
82
|
+
class PeriodRange(_PeriodRefVariant):
|
|
83
|
+
kind: Literal["period_range"]
|
|
84
|
+
start: PeriodRef
|
|
85
|
+
end: PeriodRef
|
|
86
|
+
|
|
87
|
+
@model_validator(mode="after")
|
|
88
|
+
def _validate_range(self) -> "PeriodRange":
|
|
89
|
+
if isinstance(self.start, PeriodRange) or isinstance(self.end, PeriodRange):
|
|
90
|
+
raise ValueError("period_range may not nest inside period_range")
|
|
91
|
+
if self.start.kind != self.end.kind:
|
|
92
|
+
raise ValueError("period_range endpoints must have the same kind")
|
|
93
|
+
if self.start._ordering_key() >= self.end._ordering_key():
|
|
94
|
+
raise ValueError("period_range requires start < end")
|
|
95
|
+
return self
|
|
96
|
+
|
|
97
|
+
def canonical_label(self) -> str:
|
|
98
|
+
return f"{self.start.canonical_label()}..{self.end.canonical_label()}"
|
|
99
|
+
|
|
100
|
+
|
|
101
|
+
PeriodRef: TypeAlias = Annotated[
|
|
102
|
+
FiscalYearPeriod
|
|
103
|
+
| FiscalQuarterPeriod
|
|
104
|
+
| DatePeriod
|
|
105
|
+
| CalendarYearPeriod
|
|
106
|
+
| PeriodRange,
|
|
107
|
+
Field(discriminator="kind"),
|
|
108
|
+
]
|
|
109
|
+
|
|
110
|
+
PeriodRange.model_rebuild()
|
|
111
|
+
|
|
112
|
+
|
|
113
|
+
__all__ = [
|
|
114
|
+
"CalendarYearPeriod",
|
|
115
|
+
"DatePeriod",
|
|
116
|
+
"FiscalQuarterPeriod",
|
|
117
|
+
"FiscalYearPeriod",
|
|
118
|
+
"PeriodRange",
|
|
119
|
+
"PeriodRef",
|
|
120
|
+
]
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
"""Value plus the semantics required to render it without guessing."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
from pydantic import BaseModel, ConfigDict
|
|
6
|
+
|
|
7
|
+
from .decimal_wire import CanonicalDecimalWire
|
|
8
|
+
from .numeric_display import NumericDisplaySpec
|
|
9
|
+
|
|
10
|
+
|
|
11
|
+
class Quantity(BaseModel):
|
|
12
|
+
model_config = ConfigDict(extra="forbid", frozen=True, strict=True)
|
|
13
|
+
|
|
14
|
+
value: CanonicalDecimalWire
|
|
15
|
+
display: NumericDisplaySpec
|
|
16
|
+
|
|
17
|
+
|
|
18
|
+
__all__ = ["Quantity"]
|
|
@@ -0,0 +1,362 @@
|
|
|
1
|
+
"""Exact two-stage reconciliation for issuer-disclosed numeric bridges.
|
|
2
|
+
|
|
3
|
+
The primitive deliberately knows nothing about providers, calendars, units, or
|
|
4
|
+
accounting labels. Callers supply already-normalized signed ``Decimal`` facts
|
|
5
|
+
in issuer-disclosed order. No expression language or tolerance is accepted.
|
|
6
|
+
"""
|
|
7
|
+
|
|
8
|
+
from __future__ import annotations
|
|
9
|
+
|
|
10
|
+
from collections import Counter
|
|
11
|
+
from collections.abc import Sequence
|
|
12
|
+
from dataclasses import dataclass, field
|
|
13
|
+
from decimal import Decimal, localcontext
|
|
14
|
+
from typing import Literal, TypeAlias
|
|
15
|
+
|
|
16
|
+
|
|
17
|
+
TwoStageReconciliationUnavailableReason: TypeAlias = Literal[
|
|
18
|
+
"duplicate_component_id",
|
|
19
|
+
"subtotal_mismatch",
|
|
20
|
+
"output_mismatch",
|
|
21
|
+
"subtotal_and_output_mismatch",
|
|
22
|
+
]
|
|
23
|
+
|
|
24
|
+
_UNAVAILABLE_REASONS = frozenset(
|
|
25
|
+
{
|
|
26
|
+
"duplicate_component_id",
|
|
27
|
+
"subtotal_mismatch",
|
|
28
|
+
"output_mismatch",
|
|
29
|
+
"subtotal_and_output_mismatch",
|
|
30
|
+
}
|
|
31
|
+
)
|
|
32
|
+
|
|
33
|
+
|
|
34
|
+
def _require_finite_decimal(value: Decimal, *, field_name: str) -> None:
|
|
35
|
+
if not isinstance(value, Decimal):
|
|
36
|
+
raise TypeError(f"{field_name} must be Decimal")
|
|
37
|
+
if not value.is_finite():
|
|
38
|
+
raise ValueError(f"{field_name} must be finite")
|
|
39
|
+
|
|
40
|
+
|
|
41
|
+
@dataclass(frozen=True, slots=True)
|
|
42
|
+
class ReconciliationComponent:
|
|
43
|
+
"""One already-signed issuer bridge component.
|
|
44
|
+
|
|
45
|
+
``value`` carries the complete additive operation: additions are positive
|
|
46
|
+
and deductions are negative. ``component_id`` is identity, not an
|
|
47
|
+
expression or an accounting-definition authority.
|
|
48
|
+
"""
|
|
49
|
+
|
|
50
|
+
component_id: str
|
|
51
|
+
value: Decimal
|
|
52
|
+
|
|
53
|
+
def __post_init__(self) -> None:
|
|
54
|
+
if not isinstance(self.component_id, str) or not self.component_id.strip():
|
|
55
|
+
raise ValueError("component_id must be a non-empty str")
|
|
56
|
+
if self.component_id != self.component_id.strip():
|
|
57
|
+
raise ValueError("component_id must not have surrounding whitespace")
|
|
58
|
+
_require_finite_decimal(self.value, field_name="component value")
|
|
59
|
+
|
|
60
|
+
|
|
61
|
+
def _component_tuple(
|
|
62
|
+
values: Sequence[ReconciliationComponent],
|
|
63
|
+
*,
|
|
64
|
+
field_name: str,
|
|
65
|
+
) -> tuple[ReconciliationComponent, ...]:
|
|
66
|
+
if isinstance(values, (str, bytes)) or not isinstance(values, Sequence):
|
|
67
|
+
raise TypeError(f"{field_name} must be a sequence")
|
|
68
|
+
result = tuple(values)
|
|
69
|
+
if any(not isinstance(value, ReconciliationComponent) for value in result):
|
|
70
|
+
raise TypeError(f"{field_name} must contain ReconciliationComponent values")
|
|
71
|
+
return result
|
|
72
|
+
|
|
73
|
+
|
|
74
|
+
def _exact_sum(values: Sequence[Decimal]) -> Decimal:
|
|
75
|
+
"""Add finite Decimals exactly without mutating ambient context."""
|
|
76
|
+
|
|
77
|
+
if not values:
|
|
78
|
+
return Decimal(0)
|
|
79
|
+
minimum_exponent = min(int(value.as_tuple().exponent) for value in values)
|
|
80
|
+
maximum_adjusted = max(value.adjusted() for value in values)
|
|
81
|
+
carry_digits = len(str(len(values)))
|
|
82
|
+
with localcontext() as context:
|
|
83
|
+
context.prec = max(
|
|
84
|
+
28,
|
|
85
|
+
maximum_adjusted - minimum_exponent + carry_digits + 2,
|
|
86
|
+
)
|
|
87
|
+
return sum(values, start=Decimal(0))
|
|
88
|
+
|
|
89
|
+
|
|
90
|
+
def _recomputed_subtotal(
|
|
91
|
+
starting_value: Decimal,
|
|
92
|
+
components: Sequence[ReconciliationComponent],
|
|
93
|
+
) -> Decimal:
|
|
94
|
+
return _exact_sum((starting_value, *(item.value for item in components)))
|
|
95
|
+
|
|
96
|
+
|
|
97
|
+
def _recomputed_output(
|
|
98
|
+
reported_subtotal: Decimal,
|
|
99
|
+
components: Sequence[ReconciliationComponent],
|
|
100
|
+
) -> Decimal:
|
|
101
|
+
# Stage two starts from the issuer's disclosed subtotal. This localizes a
|
|
102
|
+
# stage-one mismatch instead of silently replacing the disclosed operand.
|
|
103
|
+
return _exact_sum((reported_subtotal, *(item.value for item in components)))
|
|
104
|
+
|
|
105
|
+
|
|
106
|
+
def _residual(reported: Decimal, recomputed: Decimal) -> Decimal:
|
|
107
|
+
"""Return ``reported - recomputed`` exactly."""
|
|
108
|
+
|
|
109
|
+
return _exact_sum((reported, recomputed.copy_negate()))
|
|
110
|
+
|
|
111
|
+
|
|
112
|
+
def _duplicate_component_ids(
|
|
113
|
+
first_stage_components: Sequence[ReconciliationComponent],
|
|
114
|
+
second_stage_components: Sequence[ReconciliationComponent],
|
|
115
|
+
) -> tuple[str, ...]:
|
|
116
|
+
ids = tuple(
|
|
117
|
+
component.component_id
|
|
118
|
+
for component in (*first_stage_components, *second_stage_components)
|
|
119
|
+
)
|
|
120
|
+
counts = Counter(ids)
|
|
121
|
+
return tuple(dict.fromkeys(value for value in ids if counts[value] > 1))
|
|
122
|
+
|
|
123
|
+
|
|
124
|
+
def _validate_common_result(
|
|
125
|
+
*,
|
|
126
|
+
starting_value: Decimal,
|
|
127
|
+
first_stage_components: tuple[ReconciliationComponent, ...],
|
|
128
|
+
reported_subtotal: Decimal,
|
|
129
|
+
recomputed_subtotal: Decimal,
|
|
130
|
+
subtotal_residual: Decimal,
|
|
131
|
+
second_stage_components: tuple[ReconciliationComponent, ...],
|
|
132
|
+
reported_output: Decimal,
|
|
133
|
+
recomputed_output: Decimal,
|
|
134
|
+
output_residual: Decimal,
|
|
135
|
+
) -> tuple[str, ...]:
|
|
136
|
+
for field_name, value in (
|
|
137
|
+
("starting_value", starting_value),
|
|
138
|
+
("reported_subtotal", reported_subtotal),
|
|
139
|
+
("recomputed_subtotal", recomputed_subtotal),
|
|
140
|
+
("subtotal_residual", subtotal_residual),
|
|
141
|
+
("reported_output", reported_output),
|
|
142
|
+
("recomputed_output", recomputed_output),
|
|
143
|
+
("output_residual", output_residual),
|
|
144
|
+
):
|
|
145
|
+
_require_finite_decimal(value, field_name=field_name)
|
|
146
|
+
for field_name, components in (
|
|
147
|
+
("first_stage_components", first_stage_components),
|
|
148
|
+
("second_stage_components", second_stage_components),
|
|
149
|
+
):
|
|
150
|
+
if type(components) is not tuple or any(
|
|
151
|
+
not isinstance(component, ReconciliationComponent)
|
|
152
|
+
for component in components
|
|
153
|
+
):
|
|
154
|
+
raise TypeError(
|
|
155
|
+
f"{field_name} must be a tuple of ReconciliationComponent values"
|
|
156
|
+
)
|
|
157
|
+
|
|
158
|
+
expected_subtotal = _recomputed_subtotal(
|
|
159
|
+
starting_value,
|
|
160
|
+
first_stage_components,
|
|
161
|
+
)
|
|
162
|
+
expected_output = _recomputed_output(
|
|
163
|
+
reported_subtotal,
|
|
164
|
+
second_stage_components,
|
|
165
|
+
)
|
|
166
|
+
if recomputed_subtotal != expected_subtotal:
|
|
167
|
+
raise ValueError("recomputed_subtotal must equal the exact first-stage sum")
|
|
168
|
+
if subtotal_residual != _residual(reported_subtotal, recomputed_subtotal):
|
|
169
|
+
raise ValueError("subtotal_residual must equal reported minus recomputed")
|
|
170
|
+
if recomputed_output != expected_output:
|
|
171
|
+
raise ValueError("recomputed_output must equal the exact second-stage sum")
|
|
172
|
+
if output_residual != _residual(reported_output, recomputed_output):
|
|
173
|
+
raise ValueError("output_residual must equal reported minus recomputed")
|
|
174
|
+
return _duplicate_component_ids(
|
|
175
|
+
first_stage_components,
|
|
176
|
+
second_stage_components,
|
|
177
|
+
)
|
|
178
|
+
|
|
179
|
+
|
|
180
|
+
class _ResultProjection:
|
|
181
|
+
"""Read-only convenience projections shared by both result variants."""
|
|
182
|
+
|
|
183
|
+
__slots__ = ()
|
|
184
|
+
|
|
185
|
+
first_stage_components: tuple[ReconciliationComponent, ...]
|
|
186
|
+
second_stage_components: tuple[ReconciliationComponent, ...]
|
|
187
|
+
|
|
188
|
+
@property
|
|
189
|
+
def components(self) -> tuple[ReconciliationComponent, ...]:
|
|
190
|
+
return (*self.first_stage_components, *self.second_stage_components)
|
|
191
|
+
|
|
192
|
+
@property
|
|
193
|
+
def component_ids(self) -> tuple[str, ...]:
|
|
194
|
+
return tuple(component.component_id for component in self.components)
|
|
195
|
+
|
|
196
|
+
|
|
197
|
+
@dataclass(frozen=True, slots=True)
|
|
198
|
+
class TwoStageReconciliationAvailable(_ResultProjection):
|
|
199
|
+
"""An exact, identity-unique two-stage reconciliation."""
|
|
200
|
+
|
|
201
|
+
starting_value: Decimal
|
|
202
|
+
first_stage_components: tuple[ReconciliationComponent, ...]
|
|
203
|
+
reported_subtotal: Decimal
|
|
204
|
+
recomputed_subtotal: Decimal
|
|
205
|
+
subtotal_residual: Decimal
|
|
206
|
+
second_stage_components: tuple[ReconciliationComponent, ...]
|
|
207
|
+
reported_output: Decimal
|
|
208
|
+
recomputed_output: Decimal
|
|
209
|
+
output_residual: Decimal
|
|
210
|
+
status: Literal["available"] = field(default="available", init=False)
|
|
211
|
+
|
|
212
|
+
def __post_init__(self) -> None:
|
|
213
|
+
duplicates = _validate_common_result(
|
|
214
|
+
starting_value=self.starting_value,
|
|
215
|
+
first_stage_components=self.first_stage_components,
|
|
216
|
+
reported_subtotal=self.reported_subtotal,
|
|
217
|
+
recomputed_subtotal=self.recomputed_subtotal,
|
|
218
|
+
subtotal_residual=self.subtotal_residual,
|
|
219
|
+
second_stage_components=self.second_stage_components,
|
|
220
|
+
reported_output=self.reported_output,
|
|
221
|
+
recomputed_output=self.recomputed_output,
|
|
222
|
+
output_residual=self.output_residual,
|
|
223
|
+
)
|
|
224
|
+
if duplicates:
|
|
225
|
+
raise ValueError("available reconciliation component IDs must be unique")
|
|
226
|
+
if self.subtotal_residual != 0 or self.output_residual != 0:
|
|
227
|
+
raise ValueError("available reconciliation must close exactly")
|
|
228
|
+
|
|
229
|
+
|
|
230
|
+
@dataclass(frozen=True, slots=True)
|
|
231
|
+
class TwoStageReconciliationUnavailable(_ResultProjection):
|
|
232
|
+
"""A retained bridge that failed one closed reconciliation invariant."""
|
|
233
|
+
|
|
234
|
+
reason: TwoStageReconciliationUnavailableReason
|
|
235
|
+
starting_value: Decimal
|
|
236
|
+
first_stage_components: tuple[ReconciliationComponent, ...]
|
|
237
|
+
reported_subtotal: Decimal
|
|
238
|
+
recomputed_subtotal: Decimal
|
|
239
|
+
subtotal_residual: Decimal
|
|
240
|
+
second_stage_components: tuple[ReconciliationComponent, ...]
|
|
241
|
+
reported_output: Decimal
|
|
242
|
+
recomputed_output: Decimal
|
|
243
|
+
output_residual: Decimal
|
|
244
|
+
status: Literal["unavailable"] = field(default="unavailable", init=False)
|
|
245
|
+
|
|
246
|
+
def __post_init__(self) -> None:
|
|
247
|
+
if self.reason not in _UNAVAILABLE_REASONS:
|
|
248
|
+
raise ValueError(
|
|
249
|
+
"unsupported two-stage reconciliation unavailable reason: "
|
|
250
|
+
f"{self.reason!r}"
|
|
251
|
+
)
|
|
252
|
+
duplicates = _validate_common_result(
|
|
253
|
+
starting_value=self.starting_value,
|
|
254
|
+
first_stage_components=self.first_stage_components,
|
|
255
|
+
reported_subtotal=self.reported_subtotal,
|
|
256
|
+
recomputed_subtotal=self.recomputed_subtotal,
|
|
257
|
+
subtotal_residual=self.subtotal_residual,
|
|
258
|
+
second_stage_components=self.second_stage_components,
|
|
259
|
+
reported_output=self.reported_output,
|
|
260
|
+
recomputed_output=self.recomputed_output,
|
|
261
|
+
output_residual=self.output_residual,
|
|
262
|
+
)
|
|
263
|
+
subtotal_mismatch = self.subtotal_residual != 0
|
|
264
|
+
output_mismatch = self.output_residual != 0
|
|
265
|
+
expected_reason: TwoStageReconciliationUnavailableReason
|
|
266
|
+
if duplicates:
|
|
267
|
+
expected_reason = "duplicate_component_id"
|
|
268
|
+
elif subtotal_mismatch and output_mismatch:
|
|
269
|
+
expected_reason = "subtotal_and_output_mismatch"
|
|
270
|
+
elif subtotal_mismatch:
|
|
271
|
+
expected_reason = "subtotal_mismatch"
|
|
272
|
+
elif output_mismatch:
|
|
273
|
+
expected_reason = "output_mismatch"
|
|
274
|
+
else:
|
|
275
|
+
raise ValueError("unavailable reconciliation must fail an invariant")
|
|
276
|
+
if self.reason != expected_reason:
|
|
277
|
+
raise ValueError("unavailable reason must match reconciliation evidence")
|
|
278
|
+
|
|
279
|
+
@property
|
|
280
|
+
def duplicate_component_ids(self) -> tuple[str, ...]:
|
|
281
|
+
return _duplicate_component_ids(
|
|
282
|
+
self.first_stage_components,
|
|
283
|
+
self.second_stage_components,
|
|
284
|
+
)
|
|
285
|
+
|
|
286
|
+
|
|
287
|
+
TwoStageReconciliationResult: TypeAlias = (
|
|
288
|
+
TwoStageReconciliationAvailable | TwoStageReconciliationUnavailable
|
|
289
|
+
)
|
|
290
|
+
|
|
291
|
+
|
|
292
|
+
def reconcile_two_stage_bridge(
|
|
293
|
+
*,
|
|
294
|
+
starting_value: Decimal,
|
|
295
|
+
first_stage_components: Sequence[ReconciliationComponent],
|
|
296
|
+
reported_subtotal: Decimal,
|
|
297
|
+
second_stage_components: Sequence[ReconciliationComponent],
|
|
298
|
+
reported_output: Decimal,
|
|
299
|
+
) -> TwoStageReconciliationResult:
|
|
300
|
+
"""Validate one exact two-stage additive bridge.
|
|
301
|
+
|
|
302
|
+
Residuals are signed as ``reported - recomputed``. Component order is
|
|
303
|
+
retained exactly, while identity uniqueness is enforced across both stages.
|
|
304
|
+
"""
|
|
305
|
+
|
|
306
|
+
_require_finite_decimal(starting_value, field_name="starting_value")
|
|
307
|
+
_require_finite_decimal(reported_subtotal, field_name="reported_subtotal")
|
|
308
|
+
_require_finite_decimal(reported_output, field_name="reported_output")
|
|
309
|
+
first_stage = _component_tuple(
|
|
310
|
+
first_stage_components,
|
|
311
|
+
field_name="first_stage_components",
|
|
312
|
+
)
|
|
313
|
+
second_stage = _component_tuple(
|
|
314
|
+
second_stage_components,
|
|
315
|
+
field_name="second_stage_components",
|
|
316
|
+
)
|
|
317
|
+
|
|
318
|
+
recomputed_subtotal = _recomputed_subtotal(starting_value, first_stage)
|
|
319
|
+
subtotal_residual = _residual(reported_subtotal, recomputed_subtotal)
|
|
320
|
+
recomputed_output = _recomputed_output(reported_subtotal, second_stage)
|
|
321
|
+
output_residual = _residual(reported_output, recomputed_output)
|
|
322
|
+
common = {
|
|
323
|
+
"starting_value": starting_value,
|
|
324
|
+
"first_stage_components": first_stage,
|
|
325
|
+
"reported_subtotal": reported_subtotal,
|
|
326
|
+
"recomputed_subtotal": recomputed_subtotal,
|
|
327
|
+
"subtotal_residual": subtotal_residual,
|
|
328
|
+
"second_stage_components": second_stage,
|
|
329
|
+
"reported_output": reported_output,
|
|
330
|
+
"recomputed_output": recomputed_output,
|
|
331
|
+
"output_residual": output_residual,
|
|
332
|
+
}
|
|
333
|
+
|
|
334
|
+
duplicates = _duplicate_component_ids(first_stage, second_stage)
|
|
335
|
+
if duplicates:
|
|
336
|
+
return TwoStageReconciliationUnavailable(
|
|
337
|
+
reason="duplicate_component_id",
|
|
338
|
+
**common,
|
|
339
|
+
)
|
|
340
|
+
subtotal_mismatch = subtotal_residual != 0
|
|
341
|
+
output_mismatch = output_residual != 0
|
|
342
|
+
if subtotal_mismatch or output_mismatch:
|
|
343
|
+
if subtotal_mismatch and output_mismatch:
|
|
344
|
+
reason: TwoStageReconciliationUnavailableReason = (
|
|
345
|
+
"subtotal_and_output_mismatch"
|
|
346
|
+
)
|
|
347
|
+
elif subtotal_mismatch:
|
|
348
|
+
reason = "subtotal_mismatch"
|
|
349
|
+
else:
|
|
350
|
+
reason = "output_mismatch"
|
|
351
|
+
return TwoStageReconciliationUnavailable(reason=reason, **common)
|
|
352
|
+
return TwoStageReconciliationAvailable(**common)
|
|
353
|
+
|
|
354
|
+
|
|
355
|
+
__all__ = [
|
|
356
|
+
"ReconciliationComponent",
|
|
357
|
+
"TwoStageReconciliationAvailable",
|
|
358
|
+
"TwoStageReconciliationResult",
|
|
359
|
+
"TwoStageReconciliationUnavailable",
|
|
360
|
+
"TwoStageReconciliationUnavailableReason",
|
|
361
|
+
"reconcile_two_stage_bridge",
|
|
362
|
+
]
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
value_semantics_core/__init__.py,sha256=BIsOBp2K607RmUPhS5LfLCtyLAhWJW9YbMAhkBKJ_Bk,4600
|
|
2
|
+
value_semantics_core/comps_manifest_display.py,sha256=90aGTfePFchzBvM3CcnIbcZek8s1mrEkQ3wDlXRnXXw,3135
|
|
3
|
+
value_semantics_core/conventions_ir_v1.py,sha256=DZ9qXAvnxqGt_HyxKz7Tt34T_EnBoutjWhnDl-oZxOI,12952
|
|
4
|
+
value_semantics_core/decimal_wire.py,sha256=1JO-hnMEIoHmaREPyHG9zvv7mm7-90s3VBBS8yWvutg,1410
|
|
5
|
+
value_semantics_core/enterprise_value.py,sha256=NmPM84cVy9vJvkJGzCO75n-lmSaye33zTBXROZ1sBBU,8144
|
|
6
|
+
value_semantics_core/formatting.py,sha256=g8qhPknuuHwdPGtOvjD358Lp_BCrX-bvaw6wAWUkixc,7648
|
|
7
|
+
value_semantics_core/forward_ev_adjusted_ebitda.py,sha256=NuhrcePuZR9C_NU3nTMNZELFq-_TQHLoc4LGKmoBWSA,24978
|
|
8
|
+
value_semantics_core/forward_pe.py,sha256=E7zcur2xB5bB98FwQXIP68VzpKbmmnxjuIuX8USxG3s,26690
|
|
9
|
+
value_semantics_core/numeric_display.py,sha256=xQ1nn66s1JgY6A9dHU7yy59J_9dRHKXsuf5irdfUXfs,4190
|
|
10
|
+
value_semantics_core/period_ref.py,sha256=0NdQwnprpukIaNHh_uJ8QlGzbL-X4t4xw-7S2cW-BhI,3317
|
|
11
|
+
value_semantics_core/quantity.py,sha256=Hbj7mPYx9VtP_fo8QTK4CO9mgqN4ec-Ce9iNw83CQVE,438
|
|
12
|
+
value_semantics_core/reconciliation.py,sha256=h7lXk2QJIcdHuZg-f6ex3i82PeRt8EqD2ouhsfng_Is,13584
|
|
13
|
+
value_semantics_core-2.1.0.dist-info/METADATA,sha256=-l3enHLH0L405HMmpgfzjQjfA_6DtM2nf88rRBZOJLM,193
|
|
14
|
+
value_semantics_core-2.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
|
|
15
|
+
value_semantics_core-2.1.0.dist-info/top_level.txt,sha256=zCiaT-tOpBQzuVZonxPz9_FkPzBHm-YywHQLZnzsS98,21
|
|
16
|
+
value_semantics_core-2.1.0.dist-info/RECORD,,
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
value_semantics_core
|