babylon.engine.headless_runner.scopes

Predefined scope resolver for the headless simulation runner.

Resolves a scope name like "michigan-canada" into a concrete (scope_fips, external_node_ids) pair. The four canonical scopes match contracts/cli_contract.yaml.

The Michigan FIPS list is enumerated from data/sqlite/marxist-data-3NF.sqlite (dim_county filtered to state 26, excluding the synthetic 26999 rest-of-state code). The national list is resolved lazily by querying SQLite at scope-resolution time — hard-coding ~3,200 codes here would create unnecessary maintenance churn when TIGER vintages bump.

Functions

resolve_scope(name, *[, sqlite_path])

Resolve a predefined scope name to its concrete FIPS + externals.

Classes

Scope(scope_fips, external_node_ids)

Concrete scope resolution: county FIPS + external boundary nodes.

Exceptions

UnknownScopeError

Raised when an unrecognized scope name is requested.
class babylon.engine.headless_runner.scopes.Scope(scope_fips, external_node_ids)[source]

Bases: NamedTuple

Concrete scope resolution: county FIPS + external boundary nodes.

Parameters:
scope_fips: frozenset[str]

Alias for field number 0

external_node_ids: frozenset[str]

Alias for field number 1

exception babylon.engine.headless_runner.scopes.UnknownScopeError[source]

Bases: ValueError

Raised when an unrecognized scope name is requested.

babylon.engine.headless_runner.scopes.resolve_scope(name, *, sqlite_path=DEFAULT_SQLITE_PATH)[source]

Resolve a predefined scope name to its concrete FIPS + externals.

Parameters:

  • name (str) – One of michigan-canada, michigan-statewide-no-canada, detroit-tri-county, national.

  • sqlite_path (Path) – Override for the SQLite reference DB. Only consulted when name == "national" — other scopes are fully resolvable from the hard-coded literals above.

Return type:

Scope

Returns:

Scope tuple with scope_fips and external_node_ids.

Raises: