value-semantics-core 2.1.0__tar.gz

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.
Files changed (29) hide show
  1. value_semantics_core-2.1.0/PKG-INFO +6 -0
  2. value_semantics_core-2.1.0/README.md +12 -0
  3. value_semantics_core-2.1.0/pyproject.toml +14 -0
  4. value_semantics_core-2.1.0/setup.cfg +4 -0
  5. value_semantics_core-2.1.0/tests/test_comps_manifest_display.py +283 -0
  6. value_semantics_core-2.1.0/tests/test_enterprise_value.py +102 -0
  7. value_semantics_core-2.1.0/tests/test_forward_ev_adjusted_ebitda.py +89 -0
  8. value_semantics_core-2.1.0/tests/test_forward_pe.py +258 -0
  9. value_semantics_core-2.1.0/tests/test_ntm_forward_ev_adjusted_ebitda.py +379 -0
  10. value_semantics_core-2.1.0/tests/test_ntm_forward_pe.py +595 -0
  11. value_semantics_core-2.1.0/tests/test_numeric_display.py +69 -0
  12. value_semantics_core-2.1.0/tests/test_two_stage_reconciliation.py +377 -0
  13. value_semantics_core-2.1.0/value_semantics_core/__init__.py +157 -0
  14. value_semantics_core-2.1.0/value_semantics_core/comps_manifest_display.py +99 -0
  15. value_semantics_core-2.1.0/value_semantics_core/conventions_ir_v1.py +503 -0
  16. value_semantics_core-2.1.0/value_semantics_core/decimal_wire.py +43 -0
  17. value_semantics_core-2.1.0/value_semantics_core/enterprise_value.py +223 -0
  18. value_semantics_core-2.1.0/value_semantics_core/formatting.py +220 -0
  19. value_semantics_core-2.1.0/value_semantics_core/forward_ev_adjusted_ebitda.py +669 -0
  20. value_semantics_core-2.1.0/value_semantics_core/forward_pe.py +751 -0
  21. value_semantics_core-2.1.0/value_semantics_core/numeric_display.py +129 -0
  22. value_semantics_core-2.1.0/value_semantics_core/period_ref.py +120 -0
  23. value_semantics_core-2.1.0/value_semantics_core/quantity.py +18 -0
  24. value_semantics_core-2.1.0/value_semantics_core/reconciliation.py +362 -0
  25. value_semantics_core-2.1.0/value_semantics_core.egg-info/PKG-INFO +6 -0
  26. value_semantics_core-2.1.0/value_semantics_core.egg-info/SOURCES.txt +27 -0
  27. value_semantics_core-2.1.0/value_semantics_core.egg-info/dependency_links.txt +1 -0
  28. value_semantics_core-2.1.0/value_semantics_core.egg-info/requires.txt +1 -0
  29. value_semantics_core-2.1.0/value_semantics_core.egg-info/top_level.txt +1 -0
@@ -0,0 +1,6 @@
1
+ Metadata-Version: 2.4
2
+ Name: value-semantics-core
3
+ Version: 2.1.0
4
+ Summary: Shared value-semantics types and canonical numeric conventions
5
+ Requires-Python: >=3.10
6
+ Requires-Dist: pydantic<3,>=2.10
@@ -0,0 +1,12 @@
1
+ # value-semantics-core
2
+
3
+ Python authority for serialized numeric semantics. `value_semantics_core/__init__.py`
4
+ `__all__` is the public surface; `packages/value-semantics-js` is its TypeScript
5
+ mirror (only `src/generated.ts` there is generated from this package).
6
+
7
+ Tests: `python3 -m pytest packages/value-semantics-core/tests -q`
8
+
9
+ The exported models, enums, and normalization helpers in
10
+ `value_semantics_core/__init__.py` are authoritative. In the Hank monorepo,
11
+ `docs/reference/value-semantics-contract.md` documents the wider consumer
12
+ contract; that reference is outside this package.
@@ -0,0 +1,14 @@
1
+ [build-system]
2
+ requires = ["setuptools>=68", "wheel"]
3
+ build-backend = "setuptools.build_meta"
4
+
5
+ [project]
6
+ name = "value-semantics-core"
7
+ version = "2.1.0"
8
+ description = "Shared value-semantics types and canonical numeric conventions"
9
+ requires-python = ">=3.10"
10
+ dependencies = ["pydantic>=2.10,<3"]
11
+
12
+ [tool.setuptools.packages.find]
13
+ where = ["."]
14
+ include = ["value_semantics_core*"]
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
@@ -0,0 +1,283 @@
1
+ from __future__ import annotations
2
+
3
+ from pathlib import Path
4
+ import shutil
5
+ import subprocess
6
+ import sys
7
+ import textwrap
8
+ from types import SimpleNamespace
9
+
10
+ import pytest
11
+
12
+
13
+ PACKAGE_ROOT = Path(__file__).resolve().parents[1]
14
+ REPOSITORY_ROOT = Path(__file__).resolve().parents[3]
15
+ sys.path.insert(0, str(PACKAGE_ROOT))
16
+
17
+ from value_semantics_core.comps_manifest_display import ( # noqa: E402
18
+ ast_referenced_names,
19
+ display_for_metric,
20
+ enforce_withheld_display,
21
+ namespace_names_for,
22
+ require_snapshot_compatible_manifest,
23
+ withheld_display_metric_keys,
24
+ )
25
+
26
+
27
+ DISPLAY = SimpleNamespace(
28
+ numeric_kind="percentage",
29
+ scale="unit",
30
+ precision=1,
31
+ )
32
+ COUNT_DISPLAY = SimpleNamespace(
33
+ numeric_kind="count",
34
+ scale="unit",
35
+ precision=1,
36
+ )
37
+ CURRENCY_DISPLAY = SimpleNamespace(
38
+ numeric_kind="currency",
39
+ scale="unit",
40
+ currency="USD",
41
+ precision=1,
42
+ )
43
+
44
+
45
+ def _metric(
46
+ key: str,
47
+ kind: str,
48
+ formula: str | None = None,
49
+ *,
50
+ display: SimpleNamespace | None = DISPLAY,
51
+ ) -> SimpleNamespace:
52
+ return SimpleNamespace(
53
+ key=key,
54
+ display=display,
55
+ source=SimpleNamespace(kind=kind, derived_formula=formula),
56
+ )
57
+
58
+
59
+ def _manifest(metrics: list[SimpleNamespace]) -> SimpleNamespace:
60
+ return SimpleNamespace(
61
+ sections=[SimpleNamespace(name="Guard", order=1, metrics=metrics)]
62
+ )
63
+
64
+
65
+ def _withheld(manifest: SimpleNamespace) -> frozenset[str]:
66
+ return withheld_display_metric_keys(manifest)
67
+
68
+
69
+ def test_vendored_package_imports_without_hidden_dependencies(tmp_path: Path) -> None:
70
+ vendor_root = tmp_path / "vendor"
71
+ run_dir = tmp_path / "run"
72
+ shutil.copytree(PACKAGE_ROOT / "value_semantics_core", vendor_root / "value_semantics_core")
73
+ run_dir.mkdir()
74
+ script = textwrap.dedent(
75
+ """
76
+ from pathlib import Path
77
+ from types import SimpleNamespace
78
+ import sys
79
+
80
+ vendor_root = Path(sys.argv[1]).resolve()
81
+ repository_root = Path(sys.argv[2]).resolve()
82
+ sys.path.insert(0, str(vendor_root))
83
+ for entry in sys.path:
84
+ if not entry:
85
+ raise SystemExit("empty sys.path entry would expose the subprocess CWD")
86
+ resolved = Path(entry).resolve()
87
+ if resolved == repository_root or repository_root in resolved.parents:
88
+ raise SystemExit(f"AI repository leaked onto sys.path: {resolved}")
89
+
90
+ from value_semantics_core.comps_manifest_display import (
91
+ display_for_metric,
92
+ namespace_names_for,
93
+ require_snapshot_compatible_manifest,
94
+ withheld_display_metric_keys,
95
+ )
96
+
97
+ percentage_display = SimpleNamespace(
98
+ numeric_kind="percentage", scale="unit", precision=1
99
+ )
100
+ count_display = SimpleNamespace(
101
+ numeric_kind="count", scale="unit", precision=1
102
+ )
103
+ def metric(key, kind, formula=None, display=percentage_display):
104
+ return SimpleNamespace(
105
+ key=key,
106
+ display=display,
107
+ source=SimpleNamespace(kind=kind, derived_formula=formula),
108
+ )
109
+ metrics = [
110
+ metric("kpi_seed", "kpi"),
111
+ metric("transcript_seed", "transcript_kpi"),
112
+ metric("count_seed", "transcript_kpi", display=count_display),
113
+ metric("derived_prior", "derived", "count_seed_prior / 2"),
114
+ metric("derived_transitive", "derived", "derived_prior + 1"),
115
+ metric("safe", "concept"),
116
+ ]
117
+ manifest = SimpleNamespace(sections=[SimpleNamespace(metrics=metrics)])
118
+ withheld = withheld_display_metric_keys(manifest)
119
+ assert withheld == {
120
+ "count_seed", "derived_prior", "derived_transitive"
121
+ }
122
+ assert display_for_metric(metrics[0], withheld) == percentage_display
123
+ assert display_for_metric(metrics[2], withheld) is None
124
+ assert display_for_metric(metrics[-1], withheld) == percentage_display
125
+ assert namespace_names_for("clients") == (
126
+ "clients", "clients_prior", "clients_prev"
127
+ )
128
+ try:
129
+ require_snapshot_compatible_manifest(manifest)
130
+ except ValueError as exc:
131
+ assert "kpi_seed, transcript_seed" in str(exc)
132
+ else:
133
+ raise AssertionError("snapshot-incompatible manifest was accepted")
134
+ assert not any(name == "fmp" or name.startswith("fmp.") for name in sys.modules)
135
+ assert not any(name == "config" or name.startswith("config.") for name in sys.modules)
136
+ """
137
+ )
138
+
139
+ result = subprocess.run(
140
+ [
141
+ sys.executable,
142
+ "-I",
143
+ "-c",
144
+ script,
145
+ str(vendor_root),
146
+ str(REPOSITORY_ROOT),
147
+ ],
148
+ cwd=run_dir,
149
+ capture_output=True,
150
+ text=True,
151
+ check=False,
152
+ )
153
+
154
+ assert result.returncode == 0, result.stderr
155
+
156
+
157
+ def test_withheld_closure_releases_percentages_and_covers_every_taint_route() -> None:
158
+ metrics = [
159
+ _metric("kpi_percentage", "kpi"),
160
+ _metric("direct_transcript_percentage", "transcript_kpi"),
161
+ _metric(
162
+ "direct_transcript_count",
163
+ "transcript_kpi",
164
+ display=COUNT_DISPLAY,
165
+ ),
166
+ _metric("kpi_count", "kpi", display=COUNT_DISPLAY),
167
+ _metric(
168
+ "revenue_per_client",
169
+ "kpi",
170
+ display=CURRENCY_DISPLAY,
171
+ ),
172
+ _metric("first_hop", "derived", "kpi_count / 2"),
173
+ _metric("second_hop", "derived", "first_hop + 1"),
174
+ _metric(
175
+ "prior_hop",
176
+ "derived",
177
+ "direct_transcript_count_prior * 2",
178
+ ),
179
+ _metric(
180
+ "prev_hop",
181
+ "derived",
182
+ "direct_transcript_count_prev + 1",
183
+ ),
184
+ _metric("alias_transitive", "derived", "prior_hop / 3"),
185
+ _metric("derived_from_released_kpi", "derived", "kpi_percentage / 2"),
186
+ _metric("concept_safe", "concept"),
187
+ _metric("metric_safe", "metric"),
188
+ _metric("derived_safe", "derived", "freeCashFlow / revenue"),
189
+ ]
190
+
191
+ withheld = _withheld(_manifest(metrics))
192
+
193
+ assert withheld == {
194
+ "direct_transcript_count",
195
+ "kpi_count",
196
+ "revenue_per_client",
197
+ "first_hop",
198
+ "second_hop",
199
+ "prior_hop",
200
+ "prev_hop",
201
+ "alias_transitive",
202
+ }
203
+ for metric in metrics:
204
+ assert display_for_metric(metric, withheld) == (
205
+ None if metric.key in withheld else DISPLAY
206
+ )
207
+
208
+
209
+ def test_enforce_withheld_display_covers_shipped_counts_and_percentages() -> None:
210
+ count_keys = (
211
+ "clients",
212
+ "total_employees",
213
+ "loyalty_program_members",
214
+ "total_stores_in_operation",
215
+ "new_store_openings",
216
+ )
217
+ percentage_keys = (
218
+ "retention",
219
+ "comparable_sales_growth",
220
+ "gross_margin_rate",
221
+ )
222
+ metrics = [
223
+ *(
224
+ _metric(key, "kpi", display=COUNT_DISPLAY)
225
+ for key in count_keys
226
+ ),
227
+ _metric("revenue_per_client", "kpi", display=CURRENCY_DISPLAY),
228
+ *(_metric(key, "kpi") for key in percentage_keys),
229
+ ]
230
+ withheld = _withheld(_manifest(metrics))
231
+
232
+ assert withheld == {*count_keys, "revenue_per_client"}
233
+ for metric in metrics:
234
+ if metric.key in withheld:
235
+ with pytest.raises(
236
+ ValueError,
237
+ match=rf"withheld metric {metric.key!r}",
238
+ ):
239
+ enforce_withheld_display(metric, withheld, metric.display)
240
+ enforce_withheld_display(metric, withheld, None)
241
+ else:
242
+ enforce_withheld_display(metric, withheld, metric.display)
243
+
244
+
245
+ def test_withheld_display_closure_accepts_manifest_directly() -> None:
246
+ manifest = _manifest([_metric("retention", "transcript_kpi")])
247
+
248
+ assert withheld_display_metric_keys(manifest) == frozenset()
249
+
250
+
251
+ def test_namespace_aliases_have_one_definition() -> None:
252
+ assert namespace_names_for("clients") == (
253
+ "clients",
254
+ "clients_prior",
255
+ "clients_prev",
256
+ )
257
+
258
+
259
+ def test_snapshot_manifest_rejects_fiscal_year_only_sources() -> None:
260
+ manifest = _manifest([_metric("direct_seed", "transcript_kpi")])
261
+
262
+ with pytest.raises(
263
+ ValueError,
264
+ match="snapshot comps manifest cannot bind kpi/transcript_kpi sources: direct_seed",
265
+ ):
266
+ require_snapshot_compatible_manifest(manifest)
267
+
268
+
269
+
270
+
271
+ @pytest.mark.parametrize(
272
+ ("formula", "expected"),
273
+ [
274
+ ("revenue / clients", {"revenue", "clients"}),
275
+ ("retention_prior + retention_prev", {"retention_prior", "retention_prev"}),
276
+ ("max(gross_profit, 0)", {"max", "gross_profit"}),
277
+ ("1 + 2", set()),
278
+ ],
279
+ )
280
+ def test_ast_referenced_names_formula_corpus(
281
+ formula: str, expected: set[str]
282
+ ) -> None:
283
+ assert ast_referenced_names(formula) == expected
@@ -0,0 +1,102 @@
1
+ from __future__ import annotations
2
+
3
+ from decimal import Decimal, getcontext
4
+
5
+ import pytest
6
+
7
+ from value_semantics_core import (
8
+ DatedEnterpriseValueAvailable,
9
+ DatedEnterpriseValueUnavailable,
10
+ EnterpriseValueComponent,
11
+ derive_dated_enterprise_value,
12
+ )
13
+
14
+
15
+ def _component(component_id: str, value: str) -> EnterpriseValueComponent:
16
+ return EnterpriseValueComponent(component_id=component_id, value=Decimal(value))
17
+
18
+
19
+ def test_pcty_dated_enterprise_value_is_exact_and_ordered() -> None:
20
+ result = derive_dated_enterprise_value(
21
+ price_per_share=Decimal("147.32"),
22
+ split_adjusted_shares=Decimal("53.056963"),
23
+ components=(
24
+ _component("long_term_debt", "81.250"),
25
+ _component("corporate_cash", "-271.917"),
26
+ ),
27
+ )
28
+
29
+ assert isinstance(result, DatedEnterpriseValueAvailable)
30
+ assert result.equity_value == Decimal("7816.35178916")
31
+ assert result.enterprise_value == Decimal("7625.68478916")
32
+ assert tuple(item.component_id for item in result.components) == (
33
+ "long_term_debt",
34
+ "corporate_cash",
35
+ )
36
+
37
+
38
+ @pytest.mark.parametrize(
39
+ ("price", "shares", "reason"),
40
+ (
41
+ ("0", "1", "non_positive_price"),
42
+ ("-1", "1", "non_positive_price"),
43
+ ("1", "0", "non_positive_shares"),
44
+ ("1", "-1", "non_positive_shares"),
45
+ ),
46
+ )
47
+ def test_non_positive_market_cap_operands_are_unavailable(
48
+ price: str,
49
+ shares: str,
50
+ reason: str,
51
+ ) -> None:
52
+ result = derive_dated_enterprise_value(
53
+ price_per_share=Decimal(price),
54
+ split_adjusted_shares=Decimal(shares),
55
+ components=(),
56
+ )
57
+ assert isinstance(result, DatedEnterpriseValueUnavailable)
58
+ assert result.reason == reason
59
+
60
+
61
+ def test_duplicate_component_identity_is_unavailable() -> None:
62
+ result = derive_dated_enterprise_value(
63
+ price_per_share=Decimal("10"),
64
+ split_adjusted_shares=Decimal("2"),
65
+ components=(_component("cash", "-1"), _component("cash", "-2")),
66
+ )
67
+ assert isinstance(result, DatedEnterpriseValueUnavailable)
68
+ assert result.reason == "duplicate_component_id"
69
+
70
+
71
+ @pytest.mark.parametrize("value", [Decimal("NaN"), Decimal("Infinity")])
72
+ def test_nonfinite_operands_are_rejected(value: Decimal) -> None:
73
+ with pytest.raises(ValueError, match="finite"):
74
+ derive_dated_enterprise_value(
75
+ price_per_share=value,
76
+ split_adjusted_shares=Decimal("1"),
77
+ components=(),
78
+ )
79
+
80
+
81
+ def test_non_decimal_operands_are_rejected() -> None:
82
+ with pytest.raises(TypeError, match="Decimal"):
83
+ derive_dated_enterprise_value(
84
+ price_per_share=1.0, # pyright: ignore[reportArgumentType] # negative: non-Decimal operand rejection
85
+ split_adjusted_shares=Decimal("1"),
86
+ components=(),
87
+ )
88
+
89
+
90
+ def test_ambient_decimal_context_does_not_change_result() -> None:
91
+ original = getcontext().prec
92
+ try:
93
+ getcontext().prec = 4
94
+ result = derive_dated_enterprise_value(
95
+ price_per_share=Decimal("147.32"),
96
+ split_adjusted_shares=Decimal("53.056963"),
97
+ components=(_component("cash", "-271.917"),),
98
+ )
99
+ finally:
100
+ getcontext().prec = original
101
+ assert isinstance(result, DatedEnterpriseValueAvailable)
102
+ assert result.enterprise_value == Decimal("7544.43478916")
@@ -0,0 +1,89 @@
1
+ from __future__ import annotations
2
+
3
+ from decimal import Decimal, getcontext
4
+
5
+ import pytest
6
+
7
+ from value_semantics_core import (
8
+ ForwardEvAdjustedEbitdaAvailable,
9
+ ForwardEvAdjustedEbitdaUnavailable,
10
+ derive_forward_ev_adjusted_ebitda,
11
+ )
12
+
13
+
14
+ def test_pcty_exact_dated_ev_over_forward_adjusted_ebitda() -> None:
15
+ result = derive_forward_ev_adjusted_ebitda(
16
+ enterprise_value=Decimal("7625.68478916"),
17
+ adjusted_ebitda=Decimal("800"),
18
+ quantum=Decimal("0.000001"),
19
+ )
20
+
21
+ assert isinstance(result, ForwardEvAdjustedEbitdaAvailable)
22
+ assert result.multiple == Decimal("9.532106")
23
+ assert result.enterprise_value == Decimal("7625.68478916")
24
+ assert result.adjusted_ebitda == Decimal("800")
25
+
26
+
27
+ @pytest.mark.parametrize(
28
+ ("enterprise_value", "adjusted_ebitda", "reason"),
29
+ (
30
+ ("0", "1", "non_positive_enterprise_value"),
31
+ ("-1", "1", "non_positive_enterprise_value"),
32
+ ("1", "0", "non_positive_adjusted_ebitda"),
33
+ ("1", "-1", "non_positive_adjusted_ebitda"),
34
+ ),
35
+ )
36
+ def test_non_positive_operands_are_explicitly_unavailable(
37
+ enterprise_value: str,
38
+ adjusted_ebitda: str,
39
+ reason: str,
40
+ ) -> None:
41
+ result = derive_forward_ev_adjusted_ebitda(
42
+ enterprise_value=Decimal(enterprise_value),
43
+ adjusted_ebitda=Decimal(adjusted_ebitda),
44
+ quantum=Decimal("0.000001"),
45
+ )
46
+
47
+ assert isinstance(result, ForwardEvAdjustedEbitdaUnavailable)
48
+ assert result.reason == reason
49
+
50
+
51
+ @pytest.mark.parametrize("value", [Decimal("NaN"), Decimal("Infinity")])
52
+ def test_nonfinite_operands_are_rejected(value: Decimal) -> None:
53
+ with pytest.raises(ValueError, match="finite"):
54
+ derive_forward_ev_adjusted_ebitda(
55
+ enterprise_value=value,
56
+ adjusted_ebitda=Decimal("1"),
57
+ quantum=Decimal("0.000001"),
58
+ )
59
+
60
+
61
+ def test_non_decimal_operands_and_invalid_quantum_are_rejected() -> None:
62
+ with pytest.raises(TypeError, match="Decimal"):
63
+ derive_forward_ev_adjusted_ebitda(
64
+ enterprise_value=1.0, # pyright: ignore[reportArgumentType] # negative: non-Decimal operand rejection
65
+ adjusted_ebitda=Decimal("1"),
66
+ quantum=Decimal("0.000001"),
67
+ )
68
+ with pytest.raises(ValueError, match="quantum must be positive"):
69
+ derive_forward_ev_adjusted_ebitda(
70
+ enterprise_value=Decimal("1"),
71
+ adjusted_ebitda=Decimal("1"),
72
+ quantum=Decimal("0"),
73
+ )
74
+
75
+
76
+ def test_half_even_and_ambient_decimal_context_are_deterministic() -> None:
77
+ original = getcontext().prec
78
+ try:
79
+ getcontext().prec = 4
80
+ result = derive_forward_ev_adjusted_ebitda(
81
+ enterprise_value=Decimal("1.0000005"),
82
+ adjusted_ebitda=Decimal("1"),
83
+ quantum=Decimal("0.000001"),
84
+ )
85
+ finally:
86
+ getcontext().prec = original
87
+
88
+ assert isinstance(result, ForwardEvAdjustedEbitdaAvailable)
89
+ assert result.multiple == Decimal("1.000000")