[anth-volk]

Fixes #700

Problem

The Public API stores each .py model version's metadata for the PolicyEngine app. Seven groups of fields the app reads are not in .py's public records, so the only way to read them today is the private _load_system() method. This PR publishes them on the existing Pydantic records, so the Public API can read them from .py's public surface.

Additions only. No existing field, default or behaviour changes for current .py users.

New public fields

Record	Field	Type	Source
policyengine.core.Entity (new model)	key, plural, is_person	str, str, bool	The country package's entities
TaxBenefitModelVersion	entities	list[Entity], in the package's order; empty by default	system.entities
TaxBenefitModelVersion	basic_inputs	list[str]; empty by default or when the package declares none	system.basic_inputs (the household fields shown by default)
Variable	is_input_variable	Optional[bool]	core's is_input_variable(): no formula and no adds or subtracts
Variable	hidden_input	Optional[bool]	The variable's hidden_input
Variable	module_name	Optional[str]	The variable's module_name
policyengine.core.EnumValue (new model)	value, label	str, str | int | float | bool | None	Each enum member's name, and its declared value unchanged (an integer stays an integer, as the Public API's /{country}/metadata sends it)
Variable	enum_values	Optional[list[EnumValue]], in declaration order; None for non-enum variables	The variable's possible_values
Variable	adds_parameter_path, subtracts_parameter_path	Optional[str]	Set when adds or subtracts names a parameter instead of a list (237 US variables add and 2 subtract that way)
Parameter	economy, household	bool; True when the package does not say	The parameter's economy and household metadata, as the Public API's /{country}/metadata reads them
ParameterNode	(existing fields)		Each bracket schedule (for example gov.hmrc.income_tax.rates.uk) is now a node, listed before its brackets

Fields that are None mean the country model does not provide the value (for example older country packages).

Deliberate behaviour

• adds and subtracts are unchanged. They still hold the list resolved as of 2025-01-01. The new path fields sit beside them, so a consumer can read the parameter's list for any year.
• A schedule's label is its stored label, or None when the package stores none (for example gov.hmrc.income_tax.rates.dividends). Consumers generate a label from the name. Bracket nodes (name[0], name[1], …) and their rate, threshold and amount parameters are unchanged.
• Schedules without brackets are left out, as empty organisational nodes already are.
• All schedules are published, not only those under gov. That includes the two US calibration.* schedules.
• UK duplicates are unchanged. The UK package's baseline subtree already makes every UK gov.* parameter and node appear twice in parameters and parameter_nodes, with the same id. That includes the 41 UK schedules. This PR does not change it, because deduplicating would change existing behaviour. Consumers should deduplicate by name; parameter_nodes_by_name and parameters_by_name already hold one entry per name.
• Entity labels, descriptions and roles, parameter periods, and a second copy of each parameter's label are not added. Nothing reads them.

Tests

• Stub-based tests for each field, including:
  • enum labels declared as strings, integers, floats, booleans and None;
  • a parameter path that cannot be resolved;
  • schedules with and without a stored label;
  • a schedule without brackets.
• UK and US tests that compare every variable, parameter and schedule with the installed country package.
• UK and US tests that pin concrete values from the pinned country packages: entity keys and plurals, parameter flags, input, hidden and module values, parameter-named parts, and schedule labels.
• The new country tests use shared fixtures (tests/fixtures/country_model_fixtures.py) that skip when a country package is not installed.
• make lint passes, and the full suite passes locally: 4233 passed, 15 skipped.

Environment variables

None read or added.

Country package pins

Unchanged.

Before merging

This PR waits only for review. After it merges, a .py release is needed before the Public API can depend on these fields. This PR does not publish one.

🤖 Generated with Claude Code