industry-slice-core 0.1.2__tar.gz

industry_slice_core-0.1.2/PKG-INFO

@@ -0,0 +1,8 @@
+Metadata-Version: 2.4
+Name: industry-slice-core
+Version: 0.1.2
+Summary: Shared industry, comps, source and KPI contracts
+Requires-Python: >=3.11
+Requires-Dist: pydantic<3,>=2.10
+Requires-Dist: PyYAML<7,>=6.0
+Requires-Dist: value-semantics-core==2.1.0

industry_slice_core-0.1.2/README.md

@@ -0,0 +1,43 @@
+# industry-slice-core
+
+Engine-free industry, comps, source and KPI contracts, plus the static data they
+read. Pure types and loaders: no provider calls, no model engine, no publication
+of accepted artifacts. The add-in gateway and the Risk service install the same
+version so both sides parse the same payloads.
+
+Tests: `python3 -m pytest packages/industry-slice-core/tests -q`
+
+## Public surface
+
+| Module | Owns |
+|---|---|
+| `industry_types` | `CompanyProfile`, `Unit`, `DriverCategory` — plain company and assumption types shared with the compiler |
+| `industry_resolver` | `resolve_industry_key` over `data/industry_taxonomy.yaml` |
+| `kpi_registry`, `kpi_registry_loader` | `KPI`/`KPIRegistry` types and `load_kpi_registry` per industry key |
+| `comps_template`, `comps_template_loader` | Comps manifest types, manifest/fixture loading |
+| `metric_registry` | Canonical provider-neutral `metric_id` vocabulary; `require_registered_metric_id` raises `UnknownMetricIdError` |
+| `source_registry` | Identity/excerpt hashing and `register_source` for cited evidence |
+| `thesis_shared_industry`, `thesis_shared_sources`, `thesis_shared_slice_helpers` | Shared landscape, comparison, snapshot and source-record shapes |
+| `numeric`, `enum_canonicalizers`, `profile_normalization` | Sign/scale parsing, enum canonicalization, FMP record to provider-port values |
+| `strategy_categories` | Strategy-category registry and `validate_strategy_category_id` |
+| `manifest_bindings` | FMP adapter configuration for legacy comps-manifest bindings |
+| `artifact_data` | `artifact_path` — an accepted runtime artifact wins over the bundled default |
+
+Contract models derive from `_contract._ContractModel`: `extra="forbid"` and
+whitespace-stripped strings, so an unknown field is a validation error on both
+sides of the wire rather than a silently dropped value.
+
+## Static data and runtime overrides
+
+`industry_slice_core/data/` holds the bundled taxonomy, per-industry KPI files,
+and comps manifests with their fixture rows. When `INDUSTRY_ARTIFACTS_DIR` is
+set, `artifact_path` prefers `<dir>/industry_kpis/<file>` and
+`<dir>/comps_templates/<file>` when that file exists and falls back to the
+bundled copy otherwise, so a reviewed replacement is picked up on the next
+request without a restart. This package reads that directory; it never writes to
+it and never decides what is accepted.
+
+In the Hank monorepo, `docs/reference/financial-modeling-studio.md` ("Industry
+configuration") documents the consumer contract — which loader reads which file,
+who owns `INDUSTRY_ARTIFACTS_DIR`, and how a new industry is staged for review.
+That reference is outside this package; `packages/README.md` is the tree map.

industry_slice_core-0.1.2/industry_slice_core/__init__.py

@@ -0,0 +1 @@
+"""Engine-free industry, comps, source and KPI contracts."""

industry_slice_core-0.1.2/industry_slice_core/_contract.py

@@ -0,0 +1,7 @@
+from pydantic import BaseModel, ConfigDict
+
+
+class _ContractModel(BaseModel):
+    model_config = ConfigDict(
+        extra="forbid", str_strip_whitespace=True, populate_by_name=True
+    )

industry_slice_core-0.1.2/industry_slice_core/artifact_data.py

@@ -0,0 +1,15 @@
+"""Read accepted runtime industry artifacts ahead of bundled defaults."""
+
+from importlib.resources import files
+from importlib.resources.abc import Traversable
+import os
+from pathlib import Path
+
+
+def artifact_path(directory: str, filename: str) -> Traversable:
+    root = os.environ.get("INDUSTRY_ARTIFACTS_DIR")
+    if root:
+        runtime_path = Path(root).expanduser() / directory / filename
+        if runtime_path.is_file():
+            return runtime_path
+    return files("industry_slice_core").joinpath("data", directory, filename)

industry_slice_core-0.1.2/industry_slice_core/comps_template.py

@@ -0,0 +1,126 @@
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import Field, field_validator, model_validator
+
+from value_semantics_core.numeric_display import NumericDisplaySpec
+from ._contract import _ContractModel
+from industry_slice_core.metric_registry import require_registered_metric_id
+
+
+class CompsManifestSourceBinding(_ContractModel):
+    kind: Literal["concept", "metric", "transcript_kpi", "derived", "kpi"]
+    concept_id: str | None = None
+    metric_id: str | None = None
+    kpi_key: str | None = None
+    derived_formula: str | None = None
+
+    @model_validator(mode="after")
+    def _validate_binding_identity(self) -> "CompsManifestSourceBinding":
+        if self.kind == "concept" and not self.concept_id:
+            raise ValueError("concept bindings require concept_id")
+        if self.kind == "metric" and not self.metric_id:
+            raise ValueError("metric bindings require metric_id")
+        if self.kind == "metric":
+            self.metric_id = require_registered_metric_id(
+                self.metric_id,
+                entry_point="comps-manifest metric",
+            )
+        if self.kind != "concept" and self.concept_id is not None:
+            raise ValueError("concept_id is only valid for concept bindings")
+        if self.kind != "metric" and self.metric_id is not None:
+            raise ValueError("metric_id is only valid for metric bindings")
+        return self
+
+
+class CompsManifestMetric(_ContractModel):
+    key: str = Field(min_length=1)
+    label: str = Field(min_length=1)
+    display: NumericDisplaySpec
+    order: int = Field(ge=1)
+    aggregation: Literal["median", "mean", "weighted"] = "median"
+    null_policy: Literal["skip", "zero", "fail"] = "skip"
+    source: CompsManifestSourceBinding
+
+
+class CompsManifestSection(_ContractModel):
+    name: str = Field(min_length=1)
+    order: int = Field(ge=1)
+    metrics: list[CompsManifestMetric]
+
+    @field_validator("metrics")
+    @classmethod
+    def _reject_duplicate_metric_keys(
+        cls, value: list[CompsManifestMetric]
+    ) -> list[CompsManifestMetric]:
+        keys = [metric.key for metric in value]
+        duplicates = sorted({key for key in keys if keys.count(key) > 1})
+        if duplicates:
+            raise ValueError(f"duplicate metric keys: {duplicates}")
+        orders = [metric.order for metric in value]
+        duplicate_orders = sorted({order for order in orders if orders.count(order) > 1})
+        if duplicate_orders:
+            raise ValueError(f"duplicate metric orders: {duplicate_orders}")
+        return value
+
+
+class CompsTemplateManifest(_ContractModel):
+    template_id: str = Field(min_length=1)
+    template_kind: Literal["industry_comps", "operating_comps"]
+    industry_key: str | None = None
+    source_sheet_key: str | None = Field(
+        default=None,
+        description="Comps sheet registry key for manifests bound to reusable sheets.",
+    )
+    source_gsheet_id: str | None = Field(
+        default=None,
+        description=(
+            "Deprecated legacy direct Google Sheet id; accepted for backcompat."
+        ),
+    )
+    source_gsheet_version: str | None = Field(
+        default=None,
+        description="Deprecated legacy/source version stamp; accepted for backcompat.",
+    )
+    years: list[int] | None = None
+    years_back: int | None = None
+    sections: list[CompsManifestSection]
+    needs_re_emission: bool = Field(default=False, exclude=True)
+
+    @model_validator(mode="after")
+    def _validate_manifest(self) -> "CompsTemplateManifest":
+        if self.source_sheet_key is not None and self.source_gsheet_id is not None:
+            raise ValueError(
+                "source_sheet_key and source_gsheet_id are mutually exclusive when non-null"
+            )
+        if self.template_kind == "operating_comps" and not self.industry_key:
+            raise ValueError("industry_key is required for operating_comps templates")
+        if self.template_kind == "operating_comps":
+            has_years = self.years is not None
+            has_years_back = self.years_back is not None
+            if has_years == has_years_back:
+                raise ValueError(
+                    "operating_comps templates require exactly one of years or years_back"
+                )
+        section_names = [section.name for section in self.sections]
+        duplicate_names = sorted(
+            {name for name in section_names if section_names.count(name) > 1}
+        )
+        if duplicate_names:
+            raise ValueError(f"duplicate section names: {duplicate_names}")
+        section_orders = [section.order for section in self.sections]
+        duplicate_orders = sorted(
+            {order for order in section_orders if section_orders.count(order) > 1}
+        )
+        if duplicate_orders:
+            raise ValueError(f"duplicate section orders: {duplicate_orders}")
+        return self
+
+
+__all__ = [
+    "CompsManifestMetric",
+    "CompsManifestSection",
+    "CompsManifestSourceBinding",
+    "CompsTemplateManifest",
+]

industry_slice_core-0.1.2/industry_slice_core/comps_template_loader.py

@@ -0,0 +1,69 @@
+from __future__ import annotations
+
+from pathlib import Path
+from importlib.resources.abc import Traversable
+from typing import Any
+
+import yaml
+
+from industry_slice_core.comps_template import CompsTemplateManifest
+from industry_slice_core.manifest_bindings import (
+    translate_legacy_manifest_payload,
+)
+
+
+from .artifact_data import artifact_path
+
+
+def load_comps_template_manifest(
+    template_id: str,
+    *,
+    template_root: Path | None = None,
+) -> CompsTemplateManifest:
+    normalized_id = str(template_id or "").strip()
+    if not normalized_id:
+        raise ValueError("template_id is required")
+    path = (
+        template_root / f"{normalized_id}.yaml"
+        if template_root is not None
+        else artifact_path("comps_templates", f"{normalized_id}.yaml")
+    )
+    return load_comps_template_manifest_path(path)
+
+
+def load_comps_template_manifest_path(path: Path | Traversable) -> CompsTemplateManifest:
+    payload = yaml.safe_load(path.read_text(encoding="utf-8")) or {}
+    if not isinstance(payload, dict):
+        raise ValueError(f"comps template manifest must be a mapping: {path}")
+    translated, _changed = translate_legacy_manifest_payload(payload)
+    return CompsTemplateManifest.model_validate(translated)
+
+
+def manifest_fixture_rows(manifest: CompsTemplateManifest) -> list[dict[str, Any]]:
+    rows: list[dict[str, Any]] = []
+    for section in sorted(manifest.sections, key=lambda item: item.order):
+        for metric in sorted(section.metrics, key=lambda item: item.order):
+            rows.append(
+                {
+                    "section_order": section.order,
+                    "section_name": section.name,
+                    "metric_order": metric.order,
+                    "metric_key": metric.key,
+                    "label": metric.label,
+                    "aggregation": metric.aggregation,
+                    "null_policy": metric.null_policy,
+                    "source_kind": metric.source.kind,
+                    "concept_id": metric.source.concept_id or "",
+                    "metric_id": metric.source.metric_id or "",
+                    "kpi_key": metric.source.kpi_key or "",
+                    "derived_formula": metric.source.derived_formula or "",
+                }
+            )
+    return rows
+
+
+__all__ = [
+    "load_comps_template_manifest",
+    "load_comps_template_manifest_path",
+    "manifest_fixture_rows",
+]

industry_slice_core-0.1.2/industry_slice_core/data/comps_templates/industry_comps_generic_v1.fixture.csv

@@ -0,0 +1,20 @@
+section_order,section_name,metric_order,metric_key,label,aggregation,null_policy,source_kind,concept_id,metric_id,kpi_key,derived_formula
+1,Performance (LTM),1,revenue_ltm,Revenues ($M),median,skip,concept,revenue,,,
+1,Performance (LTM),2,ebitda_ltm,EBITDA ($M),median,skip,concept,ebitda,,,
+1,Performance (LTM),3,ebit_ltm,EBIT ($M),median,skip,metric,,ebit,,
+1,Performance (LTM),4,dna_ltm,D&A ($M),median,skip,concept,depreciation_amortization,,,
+1,Performance (LTM),5,revenue_growth_ltm,Revenue Growth,median,skip,metric,,revenue_growth,,
+1,Performance (LTM),6,roe_ltm,ROE,median,skip,metric,,return_on_equity,,
+2,Valuation,1,ev_revenue_ltm,EV / Revenue,median,skip,metric,,ev_revenue,,
+2,Valuation,2,ev_ebitda_ltm,EV / EBITDA,median,skip,metric,,ev_ebitda,,
+2,Valuation,3,net_debt_ltm,Net Debt ($M),median,skip,metric,,net_debt,,
+2,Valuation,4,cash_ltm,Cash ($M),median,skip,concept,cash_and_equivalents,,,
+3,EPS forward,1,eps_fy1,FY1 EPS,median,skip,metric,,eps_avg,,
+3,EPS forward,2,eps_fy2,FY2 EPS,median,skip,metric,,eps_avg,,
+3,EPS forward,3,eps_fy3,FY3 EPS,median,skip,metric,,eps_avg,,
+3,EPS forward,4,eps_2y_cagr,2Y EPS CAGR,median,skip,derived,,,,(eps_fy3 / eps_fy1) ** 0.5 - 1
+4,P/E multiples,1,pe_ltm,P / E,median,skip,metric,,reported_pe_ratio,,
+4,P/E multiples,2,pe_fy1,FY1 P / E,median,skip,derived,,,,price / eps_fy1
+5,Dividend,1,dividend_yield,Dividend Yield,median,skip,metric,,dividend_yield,,
+5,Dividend,2,dividend_per_share,Dividend / Share,median,skip,metric,,dividend_per_share,,
+5,Dividend,3,dividends_paid_ltm,Dividends Paid ($M),median,skip,concept,dividends_paid,,,

industry_slice_core-0.1.2/industry_slice_core/data/comps_templates/industry_comps_generic_v1.yaml

@@ -0,0 +1,264 @@
+template_id: "industry_comps_generic_v1"
+template_kind: "industry_comps"
+industry_key: null
+source_gsheet_id: null
+source_gsheet_version: "track0_fixture_2026_05_07"
+sections:
+  - name: "Performance (LTM)"
+    order: 1
+    metrics:
+      - key: "revenue_ltm"
+        label: "Revenues ($M)"
+        display:
+          numeric_kind: currency
+          scale: millions
+          currency: USD
+          precision: 1
+        order: 1
+        aggregation: "median"
+        null_policy: "skip"
+        source:
+          kind: "concept"
+          concept_id: "revenue"
+      - key: "ebitda_ltm"
+        label: "EBITDA ($M)"
+        display:
+          numeric_kind: currency
+          scale: millions
+          currency: USD
+          precision: 1
+        order: 2
+        aggregation: "median"
+        null_policy: "skip"
+        source:
+          kind: "concept"
+          concept_id: "ebitda"
+      - key: "ebit_ltm"
+        label: "EBIT ($M)"
+        display:
+          numeric_kind: currency
+          scale: millions
+          currency: USD
+          precision: 1
+        order: 3
+        aggregation: "median"
+        null_policy: "skip"
+        source:
+          kind: "metric"
+          metric_id: "ebit"
+      - key: "dna_ltm"
+        label: "D&A ($M)"
+        display:
+          numeric_kind: currency
+          scale: millions
+          currency: USD
+          precision: 1
+        order: 4
+        aggregation: "median"
+        null_policy: "skip"
+        source:
+          kind: "concept"
+          concept_id: "depreciation_amortization"
+      - key: "revenue_growth_ltm"
+        label: "Revenue Growth"
+        # arrives fraction
+        display:
+          numeric_kind: percentage
+          scale: unit
+          precision: 1
+        order: 5
+        aggregation: "median"
+        null_policy: "skip" # revenueGrowthTTM unavailable; data gap
+        source:
+          kind: "metric"
+          metric_id: "revenue_growth"
+      - key: "roe_ltm"
+        label: "ROE"
+        # arrives fraction
+        display:
+          numeric_kind: percentage
+          scale: unit
+          precision: 1
+        order: 6
+        aggregation: "median"
+        null_policy: "skip"
+        source:
+          kind: "metric"
+          metric_id: "return_on_equity"
+  - name: "Valuation"
+    order: 2
+    metrics:
+      - key: "ev_revenue_ltm"
+        label: "EV / Revenue"
+        display:
+          numeric_kind: multiple
+          scale: unit
+          precision: 1
+        order: 1
+        aggregation: "median"
+        null_policy: "skip"
+        source:
+          kind: "metric"
+          metric_id: "ev_revenue"
+      - key: "ev_ebitda_ltm"
+        label: "EV / EBITDA"
+        display:
+          numeric_kind: multiple
+          scale: unit
+          precision: 1
+        order: 2
+        aggregation: "median"
+        null_policy: "skip"
+        source:
+          kind: "metric"
+          metric_id: "ev_ebitda"
+      - key: "net_debt_ltm"
+        label: "Net Debt ($M)"
+        display:
+          numeric_kind: currency
+          scale: millions
+          currency: USD
+          precision: 1
+        order: 3
+        aggregation: "median"
+        null_policy: "skip"
+        source:
+          kind: "metric"
+          metric_id: "net_debt"
+      - key: "cash_ltm"
+        label: "Cash ($M)"
+        display:
+          numeric_kind: currency
+          scale: millions
+          currency: USD
+          precision: 1
+        order: 4
+        aggregation: "median"
+        null_policy: "skip"
+        source:
+          kind: "concept"
+          concept_id: "cash_and_equivalents"
+  - name: "EPS forward"
+    order: 3
+    metrics:
+      - key: "eps_fy1"
+        label: "FY1 EPS"
+        display:
+          numeric_kind: per_share
+          scale: unit
+          currency: USD
+          precision: 1
+        order: 1
+        aggregation: "median"
+        null_policy: "skip"
+        source:
+          kind: "metric"
+          metric_id: "eps_avg"
+      - key: "eps_fy2"
+        label: "FY2 EPS"
+        display:
+          numeric_kind: per_share
+          scale: unit
+          currency: USD
+          precision: 1
+        order: 2
+        aggregation: "median"
+        null_policy: "skip"
+        source:
+          kind: "metric"
+          metric_id: "eps_avg"
+      - key: "eps_fy3"
+        label: "FY3 EPS"
+        display:
+          numeric_kind: per_share
+          scale: unit
+          currency: USD
+          precision: 1
+        order: 3
+        aggregation: "median"
+        null_policy: "skip"
+        source:
+          kind: "metric"
+          metric_id: "eps_avg"
+      - key: "eps_2y_cagr"
+        label: "2Y EPS CAGR"
+        # arrives fraction
+        display:
+          numeric_kind: percentage
+          scale: unit
+          precision: 1
+        order: 4
+        aggregation: "median"
+        null_policy: "skip"
+        source:
+          kind: "derived"
+          derived_formula: "(eps_fy3 / eps_fy1) ** 0.5 - 1"
+  - name: "P/E multiples"
+    order: 4
+    metrics:
+      - key: "pe_ltm"
+        label: "P / E"
+        display:
+          numeric_kind: multiple
+          scale: unit
+          precision: 1
+        order: 1
+        aggregation: "median"
+        null_policy: "skip"
+        source:
+          kind: "metric"
+          metric_id: "reported_pe_ratio"
+      - key: "pe_fy1"
+        label: "FY1 P / E"
+        display:
+          numeric_kind: multiple
+          scale: unit
+          precision: 1
+        order: 2
+        aggregation: "median"
+        null_policy: "skip"
+        source:
+          kind: "derived"
+          derived_formula: "price / eps_fy1"
+  - name: "Dividend"
+    order: 5
+    metrics:
+      - key: "dividend_yield"
+        label: "Dividend Yield"
+        # arrives fraction
+        display:
+          numeric_kind: percentage
+          scale: unit
+          precision: 1
+        order: 1
+        aggregation: "median"
+        null_policy: "skip"
+        source:
+          kind: "metric"
+          metric_id: "dividend_yield"
+      - key: "dividend_per_share"
+        label: "Dividend / Share"
+        display:
+          numeric_kind: per_share
+          scale: unit
+          currency: USD
+          precision: 1
+        order: 2
+        aggregation: "median"
+        null_policy: "skip"
+        source:
+          kind: "metric"
+          metric_id: "dividend_per_share"
+      - key: "dividends_paid_ltm"
+        label: "Dividends Paid ($M)"
+        display:
+          numeric_kind: currency
+          scale: millions
+          currency: USD
+          precision: 1
+        order: 3
+        aggregation: "median"
+        null_policy: "skip"
+        source:
+          kind: "concept"
+          concept_id: "dividends_paid"

industry_slice_core-0.1.2/industry_slice_core/data/comps_templates/operating_comps_grocers_v1.fixture.csv

@@ -0,0 +1,15 @@
+section_order,section_name,metric_order,metric_key,label,aggregation,null_policy,source_kind,concept_id,metric_id,kpi_key,derived_formula
+1,Growth,1,revenue,Revenue,median,skip,concept,revenue,,,
+1,Growth,2,sales_growth,Sales Growth,median,skip,derived,,,,revenue / revenue_prior - 1
+2,Customer Base / Volume,1,total_employees,Total Associates Employed,median,skip,kpi,,,total_employees,
+2,Customer Base / Volume,2,loyalty_program_members,Annual Households Served,median,skip,kpi,,,loyalty_program_members,
+2,Customer Base / Volume,3,total_stores_in_operation,Total Supermarkets Operated,median,skip,kpi,,,total_stores_in_operation,
+2,Customer Base / Volume,4,new_store_openings,Cumulative New Store Openings,median,skip,kpi,,,new_store_openings,
+2,Customer Base / Volume,5,comparable_sales_growth,Identical Sales Growth Ex-fuel Ex-Labor Dispute,median,skip,kpi,,,comparable_sales_growth,
+2,Customer Base / Volume,6,gross_margin_rate,GAAP Gross Margin Rate,median,skip,kpi,,,gross_margin_rate,
+3,Investment,1,sm_expense,S&M Expense,median,skip,concept,sales_and_marketing,,,
+3,Investment,2,rd_expense,R&D Expense,median,skip,concept,research_and_development,,,
+3,Investment,3,capex_ratio,CapEx / Revenue,median,skip,metric,,capex_to_revenue,,
+4,Margins,1,ebitda_margin,EBITDA Margin,median,skip,metric,,ebitda_margin,,
+4,Margins,2,fcf_margin,FCF Margin,median,skip,derived,,,,freeCashFlow / revenue
+4,Margins,3,fcf_conversion,FCF Conversion,median,skip,metric,,fcf_conversion,,