femic.tsr_catalog Module

The femic.tsr_catalog module owns FEMIC’s first BC Timber Supply Review intelligence slice. It crawls the public TSA-oriented TSR document surfaces, normalizes TSA/cycle/document metadata, writes the canonical JSON registry artifacts under metadata/tsr, and fetches/caches TSR PDFs into a configurable corpus root with provenance manifests. The current extraction slice also derives reviewable candidate facts from cached TSR PDFs and writes a canonical metadata/tsr/tsa_candidate_facts.json artifact. The current overlay slice initializes reviewed/adopted per-instance TSR overlays under config/tsr/overlay.yaml without auto-promoting unresolved candidate facts, the current reporting slice renders guided review tables over the canonical fact pool without forcing users to hand-scrub raw JSON, and the current override slice adds reviewed per-instance source-layer escape hatches under config/tsr/source_layer_overrides.yaml for tokens that public BCDC inference cannot resolve safely. The new recipe scaffold slice adds reviewed working YAML surfaces under:

• config/tsr/source_layers.recipe.yaml

• config/tsr/thlb_netdown.recipe.yaml

Use this page when you are debugging the TSR indexing logic itself rather than the higher-level CLI surface.

Default user-local cache paths used by the first fetch/cache slice are:

• ~/.femic/tsr/corpus

• ~/.femic/tsr/tsa_pdf_cache_manifest.json

Start Here If…

Use this page first if you are trying to:

• understand how FEMIC crawls the BC TSR landing surface and TSA publish tree;

• inspect how TSA identity, cycle labels, and document types are normalized; or

• debug the canonical JSON outputs written to metadata/tsr; or

• inspect how TSR PDF cache manifests and corpus-relative paths are shaped for a later DataLad-managed corpus split; or

• inspect how cached TSR PDFs are turned into reviewable source-layer, AU, THLB, and TIPSY candidate facts; or

• inspect how reviewed/adopted instance-local TSR overlays are initialized and summarized.

Typical Usage

The common operator-facing entrypoint is:

femic tsr index
femic tsr fetch
femic tsr extract
femic tsr facts-report --tsa 29 --fact-family source_layer_candidate
femic tsr recipe-init --instance-root external/femic-tsa29-instance --tsa 29
femic tsr source-layers-build --instance-root external/femic-tsa29-instance
femic tsr source-layers-run --instance-root external/femic-tsa29-instance --bbox ...
femic tsr thlb-netdown-build --instance-root external/femic-tsa29-instance
femic tsr thlb-step13-compile-attributes --instance-root external/femic-tsa29-instance
femic tsr thlb-netdown-workbench-build --instance-root external/femic-tsa29-instance
femic tsr thlb-netdown-run --instance-root external/femic-tsa29-instance
femic tsr thlb-netdown-workbench-lock --instance-root external/femic-tsa29-instance
femic tsr overlay-init --instance-root external/femic-tsa29-instance --tsa 29
femic tsr overlay-report --instance-root external/femic-tsa29-instance
femic tsr override-init --instance-root external/femic-tsa29-instance
femic tsr override-report --instance-root external/femic-tsa29-instance

Important instance-local THLB artifacts in this lane include:

• config/tsr/thlb_netdown.recipe.yaml

• workbench/tsr/thlb_netdown.workbench.ipynb

• workbench/tsr/thlb_netdown.locked.py

• data/tsr/lhlb_checkpoint.feather as the raw post-step-12 restart seam

• data/tsr/lhlb_curve_ready_checkpoint.feather as the default strict restart seam for steps 13+

The matching Python entrypoints are:

from pathlib import Path
from femic.tsr_catalog import (
   build_tsr_thlb_netdown_recipe,
   build_tsr_overlay_report,
   build_tsr_source_layers_recipe,
   build_tsr_thlb_workbench,
   compile_tsr_thlb_step13_attributes,
   extract_tsr_candidate_facts,
   fetch_tsr_pdfs,
   init_tsr_overlay,
   init_tsr_recipe_scaffolds,
   init_tsr_source_layer_overrides,
   index_tsr_tsa_surfaces,
   lock_tsr_thlb_workbench,
   report_tsr_candidate_facts,
   build_tsr_source_layer_override_report,
   run_tsr_source_layers_recipe,
   write_tsr_fact_report_csv,
   write_tsr_index,
)

result = index_tsr_tsa_surfaces()
write_tsr_index(result, Path("metadata/tsr"))
fetch_tsr_pdfs(
    documents_path=Path("metadata/tsr/tsa_documents.json"),
    corpus_root=Path.home() / ".femic" / "tsr" / "corpus",
    manifest_path=Path.home() / ".femic" / "tsr" / "tsa_pdf_cache_manifest.json",
)
extract_tsr_candidate_facts(
    documents_path=Path("metadata/tsr/tsa_documents.json"),
    corpus_root=Path.home() / ".femic" / "tsr" / "corpus",
    output_path=Path("metadata/tsr/tsa_candidate_facts.json"),
)
report = report_tsr_candidate_facts(
    candidate_facts_path=Path("metadata/tsr/tsa_candidate_facts.json"),
    tsa="29",
    fact_families=("source_layer_candidate",),
)
write_tsr_fact_report_csv(
    report,
    path=Path("runtime/logs/tsa29_tsr_source_layers_review.csv"),
)
init_tsr_overlay(
    instance_root=Path("external/femic-tsa29-instance"),
    overlay_path=Path("external/femic-tsa29-instance/config/tsr/overlay.yaml"),
    tsa="29",
    registry_path=Path("metadata/tsr/tsa_registry.json"),
    documents_path=Path("metadata/tsr/tsa_documents.json"),
    candidate_facts_path=Path("metadata/tsr/tsa_candidate_facts.json"),
    source_root=Path.cwd(),
)
init_tsr_recipe_scaffolds(
    instance_root=Path("external/femic-tsa29-instance"),
    tsa="29",
    registry_path=Path("metadata/tsr/tsa_registry.json"),
    documents_path=Path("metadata/tsr/tsa_documents.json"),
    candidate_facts_path=Path("metadata/tsr/tsa_candidate_facts.json"),
    source_root=Path.cwd(),
    overlay_path=Path("external/femic-tsa29-instance/config/tsr/overlay.yaml"),
    overrides_path=Path(
        "external/femic-tsa29-instance/config/tsr/source_layer_overrides.yaml"
    ),
    source_layers_recipe_path=Path(
        "external/femic-tsa29-instance/config/tsr/source_layers.recipe.yaml"
    ),
    thlb_netdown_recipe_path=Path(
        "external/femic-tsa29-instance/config/tsr/thlb_netdown.recipe.yaml"
    ),
)
build_tsr_source_layers_recipe(
    recipe_path=Path(
        "external/femic-tsa29-instance/config/tsr/source_layers.recipe.yaml"
    ),
    source_root=Path.cwd(),
)
run_tsr_source_layers_recipe(
    recipe_path=Path(
        "external/femic-tsa29-instance/config/tsr/source_layers.recipe.yaml"
    ),
    bbox_epsg3005=(1170000.0, 450000.0, 1180000.0, 460000.0),
)
build_tsr_thlb_netdown_recipe(
    recipe_path=Path(
        "external/femic-tsa29-instance/config/tsr/thlb_netdown.recipe.yaml"
    ),
    source_root=Path.cwd(),
)
compile_tsr_thlb_step13_attributes(
    instance_root=Path("external/femic-tsa29-instance"),
)
run_tsr_thlb_netdown_recipe(
    recipe_path=Path(
        "external/femic-tsa29-instance/config/tsr/thlb_netdown.recipe.yaml"
    ),
)
build_tsr_overlay_report(
    overlay_path=Path("external/femic-tsa29-instance/config/tsr/overlay.yaml"),
)
init_tsr_source_layer_overrides(
    instance_root=Path("external/femic-tsa29-instance"),
    overlay_path=Path("external/femic-tsa29-instance/config/tsr/overlay.yaml"),
    overrides_path=Path(
        "external/femic-tsa29-instance/config/tsr/source_layer_overrides.yaml"
    ),
)
build_tsr_source_layer_override_report(
    overlay_path=Path("external/femic-tsa29-instance/config/tsr/overlay.yaml"),
    overrides_path=Path(
        "external/femic-tsa29-instance/config/tsr/source_layer_overrides.yaml"
    ),
)

Key Entry Surfaces

• index_tsr_tsa_surfaces() Crawl the public TSR TSA surfaces and build the canonical in-memory index.

• write_tsr_index() Persist the canonical registry and document inventory JSON artifacts.

• fetch_tsr_pdfs() Download/cache indexed TSR PDFs into a configurable corpus root and write a provenance manifest with corpus-relative paths, stable user-local path placeholders, and checksums.

• extract_tsr_candidate_facts() Parse cached TSR PDFs into reviewable candidate facts with page/snippet provenance for later human or agent adoption.

• report_tsr_candidate_facts() Shape canonical candidate facts into review-friendly rows with lightweight quality heuristics for operator review.

• init_tsr_overlay() Initialize the reviewed/adopted instance-local TSR overlay YAML without auto-adopting candidate facts.

• init_tsr_recipe_scaffolds() Initialize the reviewed working recipe YAML files that later source-layer and THLB recipe build/run slices will own.

• build_tsr_source_layers_recipe() Refresh the reviewed source-layer recipe from TSR facts plus current public BCDC resolution metadata.

• run_tsr_source_layers_recipe() Execute safe acquisition steps from the reviewed source-layer recipe while reusing already materialized artifacts when available.

• build_tsr_thlb_netdown_recipe() Refresh the reviewed THLB netdown recipe from TSR THLB facts plus the stable logical-source ids already captured in the source-layer recipe, while also classifying rows into the GLB/AFLB/LHLB/THLB backbone instead of leaving every row in one flat semantic bucket.

• run_tsr_thlb_netdown_recipe() Execute the bounded supported subset of the reviewed THLB recipe into a stand-level checkpoint carrying thlb_fact plus a structured audit JSON.

• build_tsr_overlay_report() Summarize one reviewed overlay against the canonical candidate-fact pool it references.

• init_tsr_source_layer_overrides() Initialize a reviewed instance-local source-layer override YAML from the unresolved rows already captured in the TSR overlay.

• build_tsr_source_layer_override_report() Summarize how many unresolved overlay rows have reviewed escape hatches recorded locally.

The override layer can now also carry review-only replacement_family_candidates for selected stale wildlife/netdown tokens. These are bounded public shortlists meant to help human review move the wall; they are not treated as exact replacements or auto-fetch targets.

Current THLB Execution Boundary

The THLB execution helper shipped in issue #126 is intentionally a reproducible hybrid bridge, not yet the full raw-land-base reconstruction engine:

• it starts from the existing checkpoint THLB signal when building thlb_fact;

• it applies the bounded supported reviewed exclusions on top of that baseline; and

• it keeps unsupported or blocked clauses explicit in the audit output.

The promoted next target, tracked in issue #128, is to rebuild THLB from the raw/resultant land base itself by overlaying the reviewed exclusion layers, fragmenting the geometry, and assigning binary fragment-level THLB membership {0,1}.

The current recipe/review improvement lane under #128 also teaches FEMIC the explicit land-base ladder:

• GLB -> AFLB

• AFLB -> LHLB

• LHLB -> THLB

That staged schema is what lets later execution and fallback slices tell the difference between universe definition, legal exclusions, projected operational deductions, benchmark targets, and pure context.

Cross-References

• CLI Reference

• TSR Intelligence Workflow

• Data Access Inventory

BC TSR document indexing helpers.

class femic.tsr_catalog.TsaRegistryRecord(tsa_id, tsa_code, tsa_name, tsa_directory_name, url, listed_modified_raw, cycles)

Bases: object

Canonical metadata for one TSA folder in the TSR corpus.

Parameters:

• tsa_id (str)

• tsa_code (str)

• tsa_name (str)

• tsa_directory_name (str)

• url (str)

• listed_modified_raw (str)

• cycles (tuple[TsrCycleRecord, ...])

cycles: tuple[TsrCycleRecord, ...]

property document_count: int

listed_modified_raw: str

to_dict()

Return type:

dict[str, object]

tsa_code: str

tsa_directory_name: str

tsa_id: str

tsa_name: str

url: str

exception femic.tsr_catalog.TsrAdjudicationOverlayError

Bases: RuntimeError

Raised when TSR adjudication overlay configuration is invalid.

class femic.tsr_catalog.TsrAdjudicationOverlayProvider(*args, **kwargs)

Bases: Protocol

Provider hook for instance-owned TSR adjudication policy.

classify_land_base_summary_row(*, label)

Return an instance-specific row classification, when known.

Parameters:

label (str)

Return type:

TsrLandBaseSummaryRowClassification | None

is_strict_seam_checkpoint_path(*, instance_root, checkpoint_path)

Return whether a checkpoint is an instance-approved strict seam.

Parameters:

• instance_root (Path)

• checkpoint_path (Path)

Return type:

bool

provider_id: str

reconstruction_gap_interpretation(*, recipe_tsa_id, parent_step)

Return an instance-specific reconstruction-gap interpretation.

Parameters:

• recipe_tsa_id (str)

• parent_step (dict[str, Any])

Return type:

TsrReconstructionGapInterpretation | None

report_notes(*, recipe_tsa_id)

Return instance-specific plain-language report notes.

Parameters:

recipe_tsa_id (str)

Return type:

tuple[str, …]

validate_checkpoint_path(*, instance_root, checkpoint_path)

Reject checkpoint paths that violate instance adjudication policy.

Parameters:

• instance_root (Path)

• checkpoint_path (Path)

Return type:

None

class femic.tsr_catalog.TsrAflbYieldBridgeBuildResult(instance_root, tsa, aflb_checkpoint_path, strata_checkpoint_path, au_checkpoint_path, yield_ready_checkpoint_path, manifest_path, run_config_path, run_config_sha256, au_table_path, top_area_coverage, top_area_coverage_source, selected_strata_count, realized_coverage, aflb_input_row_count, au_assigned_row_count, cache_sufficiency_verdict='insufficient', cache_sufficiency_reasons=(), prior_manifest_found=False, yield_ready_status='not_ready_cache_insufficient', execution_path=None, yield_ready_reason=None)

Bases: object

Summary of one bounded AFLB -> strata/AU yield-bridge build slice.

Parameters:

• instance_root (Path)

• tsa (str)

• aflb_checkpoint_path (Path)

• strata_checkpoint_path (Path)

• au_checkpoint_path (Path)

• yield_ready_checkpoint_path (Path | None)

• manifest_path (Path)

• run_config_path (Path | None)

• run_config_sha256 (str | None)

• au_table_path (Path)

• top_area_coverage (float)

• top_area_coverage_source (str)

• selected_strata_count (int)

• realized_coverage (float)

• aflb_input_row_count (int)

• au_assigned_row_count (int)

• cache_sufficiency_verdict (str)

• cache_sufficiency_reasons (tuple[str, ...])

• prior_manifest_found (bool)

• yield_ready_status (str)

• execution_path (str | None)

• yield_ready_reason (str | None)

aflb_checkpoint_path: Path

aflb_input_row_count: int

au_assigned_row_count: int

au_checkpoint_path: Path

au_table_path: Path

cache_sufficiency_reasons: tuple[str, ...] = ()

cache_sufficiency_verdict: str = 'insufficient'

execution_path: str | None = None

instance_root: Path

manifest_path: Path

prior_manifest_found: bool = False

realized_coverage: float

run_config_path: Path | None

run_config_sha256: str | None

selected_strata_count: int

strata_checkpoint_path: Path

top_area_coverage: float

top_area_coverage_source: str

tsa: str

yield_ready_checkpoint_path: Path | None

yield_ready_reason: str | None = None

yield_ready_status: str = 'not_ready_cache_insufficient'

exception femic.tsr_catalog.TsrCacheError

Bases: RuntimeError

Raised when TSR document inventory or PDF fetch/cache work fails.

class femic.tsr_catalog.TsrCacheFailure(tsa_id, source_url, source_relative_path, error)

Bases: object

One failed TSR PDF fetch attempt.

Parameters:

• tsa_id (str)

• source_url (str)

• source_relative_path (str)

• error (str)

error: str

source_relative_path: str

source_url: str

to_dict()

Return type:

dict[str, str]

tsa_id: str

class femic.tsr_catalog.TsrCandidateFact(tsa_id, tsa_code, tsa_name, cycle_label, cycle_year, title, document_type, file_name, source_url, source_relative_path, corpus_relative_path, fact_family, value, page_number, snippet, provenance_id)

Bases: object

One extracted TSR candidate fact with lightweight provenance.

Parameters:

• tsa_id (str)

• tsa_code (str)

• tsa_name (str)

• cycle_label (str)

• cycle_year (int | None)

• title (str)

• document_type (str)

• file_name (str)

• source_url (str)

• source_relative_path (str)

• corpus_relative_path (str)

• fact_family (str)

• value (str)

• page_number (int | None)

• snippet (str)

• provenance_id (str)

corpus_relative_path: str

cycle_label: str

cycle_year: int | None

document_type: str

fact_family: str

file_name: str

page_number: int | None

provenance_id: str

snippet: str

source_relative_path: str

source_url: str

title: str

to_dict()

Return type:

dict[str, object]

tsa_code: str

tsa_id: str

tsa_name: str

value: str

exception femic.tsr_catalog.TsrCatalogError

Bases: RuntimeError

Raised when TSR pages cannot be crawled or parsed.

class femic.tsr_catalog.TsrCycleRecord(cycle_label, cycle_year, url, listed_modified_raw, document_count)

Bases: object

One TSA TSR cycle directory.

Parameters:

• cycle_label (str)

• cycle_year (int | None)

• url (str)

• listed_modified_raw (str)

• document_count (int)

cycle_label: str

cycle_year: int | None

document_count: int

listed_modified_raw: str

to_dict()

Return type:

dict[str, object]

url: str

class femic.tsr_catalog.TsrDocumentRecord(tsa_id, tsa_code, tsa_name, cycle_label, cycle_year, title, document_type, file_name, file_extension, relative_path, url, listed_modified_raw, size_bytes)

Bases: object

One discovered TSR document file under a TSA cycle.

Parameters:

• tsa_id (str)

• tsa_code (str)

• tsa_name (str)

• cycle_label (str)

• cycle_year (int | None)

• title (str)

• document_type (str)

• file_name (str)

• file_extension (str)

• relative_path (str)

• url (str)

• listed_modified_raw (str)

• size_bytes (int | None)

cycle_label: str

cycle_year: int | None

document_type: str

file_extension: str

file_name: str

listed_modified_raw: str

relative_path: str

size_bytes: int | None

title: str

to_dict()

Return type:

dict[str, object]

tsa_code: str

tsa_id: str

tsa_name: str

url: str

class femic.tsr_catalog.TsrDownloadedPdf(tsa_id, tsa_code, tsa_name, cycle_label, cycle_year, title, document_type, file_name, source_url, source_relative_path, corpus_relative_path, fetch_status, fetched_utc, sha256, size_bytes, content_type)

Bases: object

One fetched or cache-hit TSR PDF with provenance details.

Parameters:

• tsa_id (str)

• tsa_code (str)

• tsa_name (str)

• cycle_label (str)

• cycle_year (int | None)

• title (str)

• document_type (str)

• file_name (str)

• source_url (str)

• source_relative_path (str)

• corpus_relative_path (str)

• fetch_status (str)

• fetched_utc (str)

• sha256 (str)

• size_bytes (int)

• content_type (str | None)

content_type: str | None

corpus_relative_path: str

cycle_label: str

cycle_year: int | None

document_type: str

fetch_status: str

fetched_utc: str

file_name: str

sha256: str

size_bytes: int

source_relative_path: str

source_url: str

title: str

to_dict()

Return type:

dict[str, object]

tsa_code: str

tsa_id: str

tsa_name: str

exception femic.tsr_catalog.TsrExtractError

Bases: RuntimeError

Raised when cached TSR PDFs cannot be parsed into candidate facts.

class femic.tsr_catalog.TsrExtractResult(generated_utc, documents_path, corpus_root, output_path, selected_tsa_filters, selected_document_count, extracted_documents_count, facts, failures)

Bases: object

Result payload for one TSR candidate-fact extraction run.

Parameters:

• generated_utc (str)

• documents_path (Path)

• corpus_root (Path)

• output_path (Path)

• selected_tsa_filters (tuple[str, ...])

• selected_document_count (int)

• extracted_documents_count (int)

• facts (tuple[TsrCandidateFact, ...])

• failures (tuple[TsrExtractionFailure, ...])

corpus_root: Path

documents_path: Path

extracted_documents_count: int

fact_family_counts()

Return type:

dict[str, int]

facts: tuple[TsrCandidateFact, ...]

failures: tuple[TsrExtractionFailure, ...]

generated_utc: str

output_path: Path

payload(*, source_root=None)

Parameters:

source_root (Path | None)

Return type:

dict[str, object]

selected_document_count: int

selected_tsa_filters: tuple[str, ...]

class femic.tsr_catalog.TsrExtractionFailure(tsa_id, source_relative_path, corpus_relative_path, error)

Bases: object

One failed candidate-fact extraction attempt.

Parameters:

• tsa_id (str)

• source_relative_path (str)

• corpus_relative_path (str)

• error (str)

corpus_relative_path: str

error: str

source_relative_path: str

to_dict()

Return type:

dict[str, str]

tsa_id: str

exception femic.tsr_catalog.TsrFactReportError

Bases: RuntimeError

Raised when TSR candidate facts cannot be rendered into review reports.

class femic.tsr_catalog.TsrFactReportResult(candidate_facts_path, tsa_id, tsa_code, tsa_name, selected_fact_families, rows)

Bases: object

Structured result for one guided TSR fact review query.

Parameters:

• candidate_facts_path (Path)

• tsa_id (str)

• tsa_code (str)

• tsa_name (str)

• selected_fact_families (tuple[str, ...])

• rows (tuple[TsrFactReviewRow, ...])

candidate_facts_path: Path

fact_family_counts()

Return type:

dict[str, int]

quality_counts()

Return type:

dict[str, int]

rows: tuple[TsrFactReviewRow, ...]

selected_fact_families: tuple[str, ...]

tsa_code: str

tsa_id: str

tsa_name: str

class femic.tsr_catalog.TsrFactReviewRow(tsa_id, tsa_code, tsa_name, fact_family, extracted_value, recommended_query, quality, quality_reason, snippet, page_number, title, cycle_label, cycle_year, provenance_id, source_url)

Bases: object

One reviewable row rendered from the canonical TSR candidate-fact pool.

Parameters:

• tsa_id (str)

• tsa_code (str)

• tsa_name (str)

• fact_family (str)

• extracted_value (str)

• recommended_query (str)

• quality (str)

• quality_reason (str)

• snippet (str)

• page_number (int | None)

• title (str)

• cycle_label (str)

• cycle_year (int | None)

• provenance_id (str)

• source_url (str)

cycle_label: str

cycle_year: int | None

extracted_value: str

fact_family: str

page_number: int | None

provenance_id: str

quality: str

quality_reason: str

recommended_query: str

snippet: str

source_url: str

title: str

to_dict()

Return type:

dict[str, object]

tsa_code: str

tsa_id: str

tsa_name: str

class femic.tsr_catalog.TsrFetchResult(generated_utc, documents_path, corpus_root, manifest_path, selected_tsa_filters, selected_document_count, cached_documents, failures)

Bases: object

Result payload for a TSR PDF fetch/cache run.

Parameters:

• generated_utc (str)

• documents_path (Path)

• corpus_root (Path)

• manifest_path (Path)

• selected_tsa_filters (tuple[str, ...])

• selected_document_count (int)

• cached_documents (tuple[TsrDownloadedPdf, ...])

• failures (tuple[TsrCacheFailure, ...])

cached_documents: tuple[TsrDownloadedPdf, ...]

corpus_root: Path

documents_path: Path

failures: tuple[TsrCacheFailure, ...]

generated_utc: str

manifest_path: Path

manifest_payload(*, source_root=None)

Parameters:

source_root (Path | None)

Return type:

dict[str, object]

selected_document_count: int

selected_tsa_filters: tuple[str, ...]

class femic.tsr_catalog.TsrIndexResult(generated_utc, landing_url, publish_root_url, tsa_root_url, landing_resources, registry, documents)

Bases: object

Canonical TSR crawl result for TSA surfaces.

Parameters:

• generated_utc (str)

• landing_url (str)

• publish_root_url (str)

• tsa_root_url (str)

• landing_resources (tuple[TsrLandingResource, ...])

• registry (tuple[TsaRegistryRecord, ...])

• documents (tuple[TsrDocumentRecord, ...])

documents: tuple[TsrDocumentRecord, ...]

documents_payload()

Return type:

dict[str, object]

generated_utc: str

landing_resources: tuple[TsrLandingResource, ...]

landing_url: str

publish_root_url: str

registry: tuple[TsaRegistryRecord, ...]

registry_payload()

Return type:

dict[str, object]

tsa_root_url: str

class femic.tsr_catalog.TsrInventoryDocument(tsa_id, tsa_code, tsa_name, cycle_label, cycle_year, title, document_type, file_name, file_extension, relative_path, url, listed_modified_raw, size_bytes)

Bases: object

One document record loaded from the canonical TSA documents inventory.

Parameters:

• tsa_id (str)

• tsa_code (str)

• tsa_name (str)

• cycle_label (str)

• cycle_year (int | None)

• title (str)

• document_type (str)

• file_name (str)

• file_extension (str)

• relative_path (str)

• url (str)

• listed_modified_raw (str)

• size_bytes (int | None)

cycle_label: str

cycle_year: int | None

document_type: str

file_extension: str

file_name: str

listed_modified_raw: str

relative_path: str

size_bytes: int | None

title: str

tsa_code: str

tsa_id: str

tsa_name: str

url: str

class femic.tsr_catalog.TsrLandBaseSummaryRowClassification(land_base_stage, execution_class, benchmark_role)

Bases: object

Classification for one TSR land-base summary row.

Parameters:

• land_base_stage (str)

• execution_class (str)

• benchmark_role (str)

benchmark_role: str

execution_class: str

land_base_stage: str

class femic.tsr_catalog.TsrLandingResource(title, url, document_type)

Bases: object

One general TSR landing-page resource.

Parameters:

• title (str)

• url (str)

• document_type (str)

document_type: str

title: str

to_dict()

Return type:

dict[str, str]

url: str

class femic.tsr_catalog.TsrOverlayCanonicalSummary(candidate_fact_count, document_count, fact_family_counts, candidate_facts_path, documents_path, registry_path)

Bases: object

Canonical candidate-fact summary surfaced into the reviewed overlay.

Parameters:

• candidate_fact_count (int)

• document_count (int)

• fact_family_counts (dict[str, int])

• candidate_facts_path (str)

• documents_path (str)

• registry_path (str)

candidate_fact_count: int

candidate_facts_path: str

document_count: int

documents_path: str

fact_family_counts: dict[str, int]

registry_path: str

to_dict()

Return type:

dict[str, object]

exception femic.tsr_catalog.TsrOverlayError

Bases: RuntimeError

Raised when TSR overlay initialization or reporting fails.

class femic.tsr_catalog.TsrOverlayInitResult(overlay_path, tsa, canonical_summary, created)

Bases: object

Result payload for TSR overlay initialization.

Parameters:

• overlay_path (Path)

• tsa (TsrOverlayTsaRecord)

• canonical_summary (TsrOverlayCanonicalSummary)

• created (bool)

canonical_summary: TsrOverlayCanonicalSummary

created: bool

overlay_path: Path

tsa: TsrOverlayTsaRecord

class femic.tsr_catalog.TsrOverlayRecord(schema_version, tsa, canonical_summary, adopted)

Bases: object

Reviewed/adopted per-instance TSR overlay payload.

Parameters:

• schema_version (int)

• tsa (TsrOverlayTsaRecord)

• canonical_summary (TsrOverlayCanonicalSummary)

• adopted (dict[str, list[dict[str, Any]]])

adopted: dict[str, list[dict[str, Any]]]

canonical_summary: TsrOverlayCanonicalSummary

schema_version: int

to_dict()

Return type:

dict[str, object]

tsa: TsrOverlayTsaRecord

class femic.tsr_catalog.TsrOverlayReport(overlay_path, tsa, canonical_summary, adopted_counts)

Bases: object

Comparison of canonical candidate facts vs adopted instance overlay state.

Parameters:

• overlay_path (Path)

• tsa (TsrOverlayTsaRecord)

• canonical_summary (TsrOverlayCanonicalSummary)

• adopted_counts (dict[str, int])

adopted_counts: dict[str, int]

canonical_summary: TsrOverlayCanonicalSummary

overlay_path: Path

tsa: TsrOverlayTsaRecord

class femic.tsr_catalog.TsrOverlayTsaRecord(tsa_id, tsa_code, tsa_name)

Bases: object

Canonical TSA identity used by instance-local TSR overlays.

Parameters:

• tsa_id (str)

• tsa_code (str)

• tsa_name (str)

to_dict()

Return type:

dict[str, str]

tsa_code: str

tsa_id: str

tsa_name: str

class femic.tsr_catalog.TsrRecipeCanonicalInputs(registry_path, documents_path, candidate_facts_path)

Bases: object

Canonical shared inputs referenced by TSR recipes.

Parameters:

• registry_path (str)

• documents_path (str)

• candidate_facts_path (str)

candidate_facts_path: str

documents_path: str

registry_path: str

to_dict()

Return type:

dict[str, str]

exception femic.tsr_catalog.TsrRecipeError

Bases: RuntimeError

Raised when TSR recipe initialization or loading fails.

class femic.tsr_catalog.TsrRecipeInitResult(tsa, source_layers_recipe_path, thlb_netdown_recipe_path, created_source_layers_recipe, created_thlb_netdown_recipe)

Bases: object

Result payload for recipe scaffold initialization.

Parameters:

• tsa (TsrOverlayTsaRecord)

• source_layers_recipe_path (Path)

• thlb_netdown_recipe_path (Path)

• created_source_layers_recipe (bool)

• created_thlb_netdown_recipe (bool)

created_source_layers_recipe: bool

created_thlb_netdown_recipe: bool

source_layers_recipe_path: Path

thlb_netdown_recipe_path: Path

tsa: TsrOverlayTsaRecord

class femic.tsr_catalog.TsrReconstructionGapInterpretation(problem_ownership, difference_nature, engineering_interpretation, recommended_next_move)

Bases: object

Instance-specific interpretation for one reconstruction comparison row.

Parameters:

• problem_ownership (str)

• difference_nature (str)

• engineering_interpretation (str)

• recommended_next_move (str)

difference_nature: str

engineering_interpretation: str

problem_ownership: str

recommended_next_move: str

class femic.tsr_catalog.TsrSourceLayerOverrideEntry(query, current_public_status, matched_by, top_match_title, dataset_page_url, suggested_fetch_strategy, current_public_notes, replacement_family_candidates=(), override_kind=None, override_value=None, notes=None)

Bases: object

One unresolved TSR source-layer row plus any reviewed user override.

Parameters:

• query (str)

• current_public_status (str)

• matched_by (str)

• top_match_title (str)

• dataset_page_url (str)

• suggested_fetch_strategy (str)

• current_public_notes (tuple[str, ...])

• replacement_family_candidates (tuple[BcdcReplacementFamilyCandidate, ...])

• override_kind (str | None)

• override_value (str | None)

• notes (str | None)

current_public_notes: tuple[str, ...]

current_public_status: str

dataset_page_url: str

property is_resolved: bool

matched_by: str

notes: str | None = None

override_kind: str | None = None

override_value: str | None = None

query: str

replacement_family_candidates: tuple[BcdcReplacementFamilyCandidate, ...] = ()

suggested_fetch_strategy: str

to_dict()

Return type:

dict[str, object]

top_match_title: str

exception femic.tsr_catalog.TsrSourceLayerOverridesError

Bases: RuntimeError

Raised when TSR source-layer override initialization or reporting fails.

class femic.tsr_catalog.TsrSourceLayerOverridesInitResult(overrides_path, overlay_path, tsa, entry_count, created)

Bases: object

Result payload for source-layer override initialization.

Parameters:

• overrides_path (Path)

• overlay_path (Path)

• tsa (TsrOverlayTsaRecord)

• entry_count (int)

• created (bool)

created: bool

entry_count: int

overlay_path: Path

overrides_path: Path

tsa: TsrOverlayTsaRecord

class femic.tsr_catalog.TsrSourceLayerOverridesRecord(schema_version, tsa, source_overlay_path, entries)

Bases: object

User-maintained instance-local source-layer overrides.

Parameters:

• schema_version (int)

• tsa (TsrOverlayTsaRecord)

• source_overlay_path (str)

• entries (tuple[TsrSourceLayerOverrideEntry, ...])

entries: tuple[TsrSourceLayerOverrideEntry, ...]

schema_version: int

source_overlay_path: str

to_dict()

Return type:

dict[str, object]

tsa: TsrOverlayTsaRecord

class femic.tsr_catalog.TsrSourceLayerOverridesReport(overrides_path, overlay_path, tsa, total_entries, resolved_entries, pending_entries, entries_with_suggestions, total_suggestion_candidates, unresolved_overlay_queries, override_kind_counts)

Bases: object

Summary of user-supplied source-layer override coverage.

Parameters:

• overrides_path (Path)

• overlay_path (Path)

• tsa (TsrOverlayTsaRecord)

• total_entries (int)

• resolved_entries (int)

• pending_entries (int)

• entries_with_suggestions (int)

• total_suggestion_candidates (int)

• unresolved_overlay_queries (tuple[str, ...])

• override_kind_counts (dict[str, int])

entries_with_suggestions: int

overlay_path: Path

override_kind_counts: dict[str, int]

overrides_path: Path

pending_entries: int

resolved_entries: int

total_entries: int

total_suggestion_candidates: int

tsa: TsrOverlayTsaRecord

unresolved_overlay_queries: tuple[str, ...]

class femic.tsr_catalog.TsrSourceLayersRecipeBuildResult(recipe_path, tsa, entry_count, status_counts)

Bases: object

Summary of one source-layer recipe build pass.

Parameters:

• recipe_path (Path)

• tsa (TsrOverlayTsaRecord)

• entry_count (int)

• status_counts (dict[str, int])

entry_count: int

recipe_path: Path

status_counts: dict[str, int]

tsa: TsrOverlayTsaRecord

class femic.tsr_catalog.TsrSourceLayersRecipeInstanceInputs(overlay_path, source_layer_overrides_path, download_root)

Bases: object

Instance-local inputs referenced by the source-layer recipe.

Parameters:

• overlay_path (str)

• source_layer_overrides_path (str)

• download_root (str)

download_root: str

overlay_path: str

source_layer_overrides_path: str

to_dict()

Return type:

dict[str, str]

class femic.tsr_catalog.TsrSourceLayersRecipeRecord(schema_version, recipe_kind, tsa, canonical_inputs, instance_inputs, recipe_contract, entries)

Bases: object

One instance-local source-layer recipe scaffold.

Parameters:

• schema_version (int)

• recipe_kind (str)

• tsa (TsrOverlayTsaRecord)

• canonical_inputs (TsrRecipeCanonicalInputs)

• instance_inputs (TsrSourceLayersRecipeInstanceInputs)

• recipe_contract (dict[str, Any])

• entries (tuple[dict[str, Any], ...])

canonical_inputs: TsrRecipeCanonicalInputs

entries: tuple[dict[str, Any], ...]

instance_inputs: TsrSourceLayersRecipeInstanceInputs

recipe_contract: dict[str, Any]

recipe_kind: str

schema_version: int

to_dict()

Return type:

dict[str, object]

tsa: TsrOverlayTsaRecord

class femic.tsr_catalog.TsrSourceLayersRecipeRunResult(recipe_path, tsa, entry_count, outcome_counts)

Bases: object

Summary of one source-layer recipe execution pass.

Parameters:

• recipe_path (Path)

• tsa (TsrOverlayTsaRecord)

• entry_count (int)

• outcome_counts (dict[str, int])

entry_count: int

outcome_counts: dict[str, int]

recipe_path: Path

tsa: TsrOverlayTsaRecord

class femic.tsr_catalog.TsrThlbNetdownRecipeBuildResult(recipe_path, tsa, step_count, step_kind_counts, status_counts, selected_document_paths)

Bases: object

Summary of one THLB netdown recipe build pass.

Parameters:

• recipe_path (Path)

• tsa (TsrOverlayTsaRecord)

• step_count (int)

• step_kind_counts (dict[str, int])

• status_counts (dict[str, int])

• selected_document_paths (tuple[str, ...])

recipe_path: Path

selected_document_paths: tuple[str, ...]

status_counts: dict[str, int]

step_count: int

step_kind_counts: dict[str, int]

tsa: TsrOverlayTsaRecord

class femic.tsr_catalog.TsrThlbNetdownRecipeInstanceInputs(overlay_path, source_layer_recipe_path, source_layer_overrides_path)

Bases: object

Instance-local inputs referenced by the THLB netdown recipe.

Parameters:

• overlay_path (str)

• source_layer_recipe_path (str)

• source_layer_overrides_path (str)

overlay_path: str

source_layer_overrides_path: str

source_layer_recipe_path: str

to_dict()

Return type:

dict[str, str]

class femic.tsr_catalog.TsrThlbNetdownRecipeRecord(schema_version, recipe_kind, tsa, canonical_inputs, instance_inputs, recipe_contract, parent_steps, steps)

Bases: object

One instance-local THLB netdown recipe scaffold.

Parameters:

• schema_version (int)

• recipe_kind (str)

• tsa (TsrOverlayTsaRecord)

• canonical_inputs (TsrRecipeCanonicalInputs)

• instance_inputs (TsrThlbNetdownRecipeInstanceInputs)

• recipe_contract (dict[str, Any])

• parent_steps (tuple[dict[str, Any], ...])

• steps (tuple[dict[str, Any], ...])

canonical_inputs: TsrRecipeCanonicalInputs

instance_inputs: TsrThlbNetdownRecipeInstanceInputs

parent_steps: tuple[dict[str, Any], ...]

recipe_contract: dict[str, Any]

recipe_kind: str

schema_version: int

steps: tuple[dict[str, Any], ...]

to_dict()

Return type:

dict[str, object]

tsa: TsrOverlayTsaRecord

class femic.tsr_catalog.TsrThlbNetdownRecipeRunResult(recipe_path, tsa, checkpoint_path, output_path, audit_path, status_report_path, runtime_status_report_path, aflb_checkpoint_path, aflb_gpkg_path, aflb_lu_cache_warmed, lhlb_checkpoint_path, lhlb_gpkg_path, lhlb_lu_cache_warmed, lhlb_curve_ready_checkpoint_path, lhlb_curve_ready_gpkg_path, lhlb_curve_ready_lu_cache_warmed, execution_mode, baseline_signal, selected_map_ids, step_count, outcome_counts, input_area_ha, baseline_managed_area_ha, final_managed_area_ha, legacy_reference_managed_area_ha, tsr_reported_aflb_area_ha, tsr_reported_thlb_area_ha, aflb_checkpoint_area_ha, lhlb_checkpoint_area_ha, lhlb_curve_ready_checkpoint_area_ha)

Bases: object

Summary of one THLB netdown recipe execution pass.

Parameters:

• recipe_path (Path)

• tsa (TsrOverlayTsaRecord)

• checkpoint_path (Path)

• output_path (Path)

• audit_path (Path)

• status_report_path (Path)

• runtime_status_report_path (Path)

• aflb_checkpoint_path (Path | None)

• aflb_gpkg_path (Path | None)

• aflb_lu_cache_warmed (bool)

• lhlb_checkpoint_path (Path | None)

• lhlb_gpkg_path (Path | None)

• lhlb_lu_cache_warmed (bool)

• lhlb_curve_ready_checkpoint_path (Path | None)

• lhlb_curve_ready_gpkg_path (Path | None)

• lhlb_curve_ready_lu_cache_warmed (bool)

• execution_mode (str)

• baseline_signal (str)

• selected_map_ids (tuple[str, ...])

• step_count (int)

• outcome_counts (dict[str, int])

• input_area_ha (float)

• baseline_managed_area_ha (float)

• final_managed_area_ha (float)

• legacy_reference_managed_area_ha (float | None)

• tsr_reported_aflb_area_ha (float | None)

• tsr_reported_thlb_area_ha (float | None)

• aflb_checkpoint_area_ha (float | None)

• lhlb_checkpoint_area_ha (float | None)

• lhlb_curve_ready_checkpoint_area_ha (float | None)

aflb_checkpoint_area_ha: float | None

aflb_checkpoint_path: Path | None

aflb_gpkg_path: Path | None

aflb_lu_cache_warmed: bool

audit_path: Path

baseline_managed_area_ha: float

baseline_signal: str

checkpoint_path: Path

execution_mode: str

final_managed_area_ha: float

input_area_ha: float

legacy_reference_managed_area_ha: float | None

lhlb_checkpoint_area_ha: float | None

lhlb_checkpoint_path: Path | None

lhlb_curve_ready_checkpoint_area_ha: float | None

lhlb_curve_ready_checkpoint_path: Path | None

lhlb_curve_ready_gpkg_path: Path | None

lhlb_curve_ready_lu_cache_warmed: bool

lhlb_gpkg_path: Path | None

lhlb_lu_cache_warmed: bool

outcome_counts: dict[str, int]

output_path: Path

recipe_path: Path

runtime_status_report_path: Path

selected_map_ids: tuple[str, ...]

status_report_path: Path

step_count: int

tsa: TsrOverlayTsaRecord

tsr_reported_aflb_area_ha: float | None

tsr_reported_thlb_area_ha: float | None

class femic.tsr_catalog.TsrThlbParallelBenchmarkResult(summary_path, run_results, parent_step_ids, landscape_units)

Bases: object

Aggregate benchmark summary for one or more THLB parent steps.

Parameters:

• summary_path (Path)

• run_results (tuple[TsrThlbParallelBenchmarkRunResult, ...])

• parent_step_ids (tuple[str, ...])

• landscape_units (tuple[str, ...])

landscape_units: tuple[str, ...]

parent_step_ids: tuple[str, ...]

run_results: tuple[TsrThlbParallelBenchmarkRunResult, ...]

summary_path: Path

to_dict()

Return type:

dict[str, object]

class femic.tsr_catalog.TsrThlbParallelBenchmarkRunResult(parent_step_id, parent_label, execution_mode, worker_count, lu_count, wall_time_seconds, peak_memory_mb, status, input_area_ha, removed_area_ha, remaining_area_ha, output_row_count, result_json_path, output_path, parity_with_serial, parity_removed_area_delta_ha, parity_remaining_area_delta_ha, notes)

Bases: object

One serial or LU-parallel benchmark record for a THLB parent step.

Parameters:

• parent_step_id (str)

• parent_label (str)

• execution_mode (str)

• worker_count (int)

• lu_count (int)

• wall_time_seconds (float)

• peak_memory_mb (float | None)

• status (str)

• input_area_ha (float)

• removed_area_ha (float)

• remaining_area_ha (float)

• output_row_count (int)

• result_json_path (Path)

• output_path (Path)

• parity_with_serial (bool | None)

• parity_removed_area_delta_ha (float | None)

• parity_remaining_area_delta_ha (float | None)

• notes (tuple[str, ...])

execution_mode: str

input_area_ha: float

lu_count: int

notes: tuple[str, ...]

output_path: Path

output_row_count: int

parent_label: str

parent_step_id: str

parity_remaining_area_delta_ha: float | None

parity_removed_area_delta_ha: float | None

parity_with_serial: bool | None

peak_memory_mb: float | None

remaining_area_ha: float

removed_area_ha: float

result_json_path: Path

status: str

to_dict()

Return type:

dict[str, object]

wall_time_seconds: float

worker_count: int

class femic.tsr_catalog.TsrThlbParentStepRunResult(recipe_path, parent_step_id, parent_label, tsa, checkpoint_path, selected_map_ids, selected_landscape_units, output_path, result_json_path, status, executed_parent_step_ids, input_area_ha, removed_area_ha, remaining_area_ha, benchmark_marginal_area_ha, benchmark_cumulative_area_ha, benchmark_marginal_delta_ha, benchmark_cumulative_delta_ha, smoke_benchmark_scale_factor, scaled_benchmark_marginal_area_ha, scaled_benchmark_cumulative_area_ha, scaled_benchmark_marginal_delta_ha, scaled_benchmark_cumulative_delta_ha, notes, execution_mode='serial', worker_count=None, lu_chunk_count=None, lu_bundle_count=None, progress_root=None, profiling=None)

Bases: object

Summary of one notebook-safe THLB parent-step execution pass.

Parameters:

• recipe_path (Path)

• parent_step_id (str)

• parent_label (str)

• tsa (TsrOverlayTsaRecord)

• checkpoint_path (Path)

• selected_map_ids (tuple[str, ...])

• selected_landscape_units (tuple[str, ...])

• output_path (Path)

• result_json_path (Path)

• status (str)

• executed_parent_step_ids (tuple[str, ...])

• input_area_ha (float)

• removed_area_ha (float)

• remaining_area_ha (float)

• benchmark_marginal_area_ha (float | None)

• benchmark_cumulative_area_ha (float | None)

• benchmark_marginal_delta_ha (float | None)

• benchmark_cumulative_delta_ha (float | None)

• smoke_benchmark_scale_factor (float | None)

• scaled_benchmark_marginal_area_ha (float | None)

• scaled_benchmark_cumulative_area_ha (float | None)

• scaled_benchmark_marginal_delta_ha (float | None)

• scaled_benchmark_cumulative_delta_ha (float | None)

• notes (tuple[str, ...])

• execution_mode (str)

• worker_count (int | None)

• lu_chunk_count (int | None)

• lu_bundle_count (int | None)

• progress_root (Path | None)

• profiling (dict[str, Any] | None)

benchmark_cumulative_area_ha: float | None

benchmark_cumulative_delta_ha: float | None

benchmark_marginal_area_ha: float | None

benchmark_marginal_delta_ha: float | None

checkpoint_path: Path

executed_parent_step_ids: tuple[str, ...]

execution_mode: str = 'serial'

input_area_ha: float

lu_bundle_count: int | None = None

lu_chunk_count: int | None = None

notes: tuple[str, ...]

output_path: Path

parent_label: str

parent_step_id: str

profiling: dict[str, Any] | None = None

progress_root: Path | None = None

recipe_path: Path

remaining_area_ha: float

removed_area_ha: float

result_json_path: Path

scaled_benchmark_cumulative_area_ha: float | None

scaled_benchmark_cumulative_delta_ha: float | None

scaled_benchmark_marginal_area_ha: float | None

scaled_benchmark_marginal_delta_ha: float | None

selected_landscape_units: tuple[str, ...]

selected_map_ids: tuple[str, ...]

smoke_benchmark_scale_factor: float | None

status: str

to_dict()

Return type:

dict[str, object]

tsa: TsrOverlayTsaRecord

worker_count: int | None = None

class femic.tsr_catalog.TsrThlbReconstructionComparisonBuildResult(recipe_path, markdown_path, json_path, tsa, parent_step_count, comparison_bucket_counts)

Bases: object

Summary of one strict-vs-reviewed THLB comparison build pass.

Parameters:

• recipe_path (Path)

• markdown_path (Path)

• json_path (Path)

• tsa (TsrOverlayTsaRecord)

• parent_step_count (int)

• comparison_bucket_counts (dict[str, int])

comparison_bucket_counts: dict[str, int]

json_path: Path

markdown_path: Path

parent_step_count: int

recipe_path: Path

tsa: TsrOverlayTsaRecord

class femic.tsr_catalog.TsrThlbStep13AttributeCompileResult(instance_root, checkpoint_path, output_path, audit_path, dem_dataset_page_url, dem_resource_root_url, dem_tile_ids, dem_tile_paths, highway_artifact_path, highway_filter_field, highway_filter_value, stand_count, slope_value_count, highway_side_counts, steep_slope_flag_count, curve_ready_row_count, missing_curve1_count)

Bases: object

Summary of one step-13 checkpoint-attribute compilation run.

Parameters:

• instance_root (Path)

• checkpoint_path (Path)

• output_path (Path)

• audit_path (Path)

• dem_dataset_page_url (str)

• dem_resource_root_url (str)

• dem_tile_ids (tuple[str, ...])

• dem_tile_paths (tuple[Path, ...])

• highway_artifact_path (Path)

• highway_filter_field (str)

• highway_filter_value (str)

• stand_count (int)

• slope_value_count (int)

• highway_side_counts (dict[str, int])

• steep_slope_flag_count (int)

• curve_ready_row_count (int)

• missing_curve1_count (int)

audit_path: Path

checkpoint_path: Path

curve_ready_row_count: int

dem_dataset_page_url: str

dem_resource_root_url: str

dem_tile_ids: tuple[str, ...]

dem_tile_paths: tuple[Path, ...]

highway_artifact_path: Path

highway_filter_field: str

highway_filter_value: str

highway_side_counts: dict[str, int]

instance_root: Path

missing_curve1_count: int

output_path: Path

slope_value_count: int

stand_count: int

steep_slope_flag_count: int

class femic.tsr_catalog.TsrThlbWarmstartBuildResult(recipe_path, markdown_path, yaml_path, tsa, milestone_count, parent_step_count, warmstart_status_counts)

Bases: object

Summary of one THLB warm-start artifact build pass.

Parameters:

• recipe_path (Path)

• markdown_path (Path)

• yaml_path (Path)

• tsa (TsrOverlayTsaRecord)

• milestone_count (int)

• parent_step_count (int)

• warmstart_status_counts (dict[str, int])

markdown_path: Path

milestone_count: int

parent_step_count: int

recipe_path: Path

tsa: TsrOverlayTsaRecord

warmstart_status_counts: dict[str, int]

yaml_path: Path

class femic.tsr_catalog.TsrThlbWorkbenchBuildResult(recipe_path, notebook_path, tsa, parent_step_count, compiled_logic_count, stage_counts)

Bases: object

Summary of one THLB workbench notebook build pass.

Parameters:

• recipe_path (Path)

• notebook_path (Path)

• tsa (TsrOverlayTsaRecord)

• parent_step_count (int)

• compiled_logic_count (int)

• stage_counts (dict[str, int])

compiled_logic_count: int

notebook_path: Path

parent_step_count: int

recipe_path: Path

stage_counts: dict[str, int]

tsa: TsrOverlayTsaRecord

class femic.tsr_catalog.TsrThlbWorkbenchLockResult(recipe_path, notebook_path, locked_script_path, locked_recipe_path, frozen_status_report_path, frozen_audit_path, tsa, lock_scope)

Bases: object

Summary of one THLB workbench lock/export pass.

Parameters:

• recipe_path (Path)

• notebook_path (Path)

• locked_script_path (Path)

• locked_recipe_path (Path)

• frozen_status_report_path (Path)

• frozen_audit_path (Path | None)

• tsa (TsrOverlayTsaRecord)

• lock_scope (str)

frozen_audit_path: Path | None

frozen_status_report_path: Path

lock_scope: str

locked_recipe_path: Path

locked_script_path: Path

notebook_path: Path

recipe_path: Path

tsa: TsrOverlayTsaRecord

class femic.tsr_catalog.TsrWrittenIndex(output_root, registry_path, documents_path, tsa_count, document_count)

Bases: object

Paths written by the canonical TSR index exporter.

Parameters:

• output_root (Path)

• registry_path (Path)

• documents_path (Path)

• tsa_count (int)

• document_count (int)

document_count: int

documents_path: Path

output_root: Path

registry_path: Path

tsa_count: int

femic.tsr_catalog.build_tsr_aflb_yield_bridge(*, instance_root, tsa=None, run_config_path=None)

Build the first bounded AFLB -> strata/AU yield-bridge artifacts.

Parameters:

• instance_root (Path)

• tsa (str | None)

• run_config_path (Path | None)

Return type:

TsrAflbYieldBridgeBuildResult

femic.tsr_catalog.build_tsr_overlay_report(*, overlay_path)

Summarize one reviewed overlay against its canonical candidate summary.

Parameters:

overlay_path (Path)

Return type:

TsrOverlayReport

femic.tsr_catalog.build_tsr_source_layer_override_report(*, overlay_path, overrides_path)

Summarize one source-layer override file against unresolved overlay rows.

Parameters:

• overlay_path (Path)

• overrides_path (Path)

Return type:

TsrSourceLayerOverridesReport

femic.tsr_catalog.build_tsr_source_layers_recipe(*, recipe_path, source_root, limit=5)

Populate the source-layer recipe from TSR facts and current BCDC knowledge.

Parameters:

• recipe_path (Path)

• source_root (Path)

• limit (int)

Return type:

TsrSourceLayersRecipeBuildResult

femic.tsr_catalog.build_tsr_thlb_netdown_recipe(*, recipe_path, source_root)

Populate the THLB netdown recipe from TSR facts and source-layer recipe state.

Parameters:

• recipe_path (Path)

• source_root (Path)

Return type:

TsrThlbNetdownRecipeBuildResult

femic.tsr_catalog.build_tsr_thlb_reconstruction_comparison(*, recipe_path, reconstructed_audit_path=None, reviewed_status_path=None, output_markdown_path=None, output_json_path=None)

Emit a strict THLB comparison report with strict-vs-TSR as primary.

Parameters:

• recipe_path (Path)

• reconstructed_audit_path (Path | None)

• reviewed_status_path (Path | None)

• output_markdown_path (Path | None)

• output_json_path (Path | None)

Return type:

TsrThlbReconstructionComparisonBuildResult

femic.tsr_catalog.build_tsr_thlb_warmstart(*, recipe_path, markdown_path=None, yaml_path=None)

Generate non-canonical THLB warm-start checklist artifacts.

Parameters:

• recipe_path (Path)

• markdown_path (Path | None)

• yaml_path (Path | None)

Return type:

TsrThlbWarmstartBuildResult

femic.tsr_catalog.build_tsr_thlb_workbench(*, recipe_path, notebook_path=None)

Generate an instance-local THLB workbench notebook from the recipe.

Parameters:

• recipe_path (Path)

• notebook_path (Path | None)

Return type:

TsrThlbWorkbenchBuildResult

femic.tsr_catalog.compile_tsr_thlb_step13_attributes(*, instance_root, checkpoint_path=None, output_path=None)

Compile the TSR step-13 stand attributes onto the curve-ready checkpoint.

Parameters:

• instance_root (Path)

• checkpoint_path (Path | None)

• output_path (Path | None)

Return type:

TsrThlbStep13AttributeCompileResult

femic.tsr_catalog.default_tsr_aflb_au_checkpoint_path(*, instance_root)

Return the default AFLB-derived AU checkpoint feather path.

Parameters:

instance_root (Path)

Return type:

Path

femic.tsr_catalog.default_tsr_aflb_strata_checkpoint_path(*, instance_root)

Return the default AFLB-derived strata checkpoint feather path.

Parameters:

instance_root (Path)

Return type:

Path

femic.tsr_catalog.default_tsr_aflb_yield_bridge_manifest_path(*, instance_root)

Return the default AFLB-derived yield-bridge manifest JSON path.

Parameters:

instance_root (Path)

Return type:

Path

femic.tsr_catalog.default_tsr_aflb_yield_ready_checkpoint_path(*, instance_root)

Return the default AFLB-derived yield-ready checkpoint feather path.

Parameters:

instance_root (Path)

Return type:

Path

femic.tsr_catalog.default_tsr_source_layer_overrides_path(*, instance_root)

Return the default per-instance source-layer override file path.

Parameters:

instance_root (Path)

Return type:

Path

femic.tsr_catalog.default_tsr_source_layers_recipe_path(*, instance_root)

Return the default per-instance source-layer recipe path.

Parameters:

instance_root (Path)

Return type:

Path

femic.tsr_catalog.default_tsr_thlb_netdown_audit_path(*, instance_root)

Return the default THLB netdown audit JSON path.

Parameters:

instance_root (Path)

Return type:

Path

femic.tsr_catalog.default_tsr_thlb_netdown_output_path(*, instance_root)

Return the default stand-level THLB checkpoint output path.

Parameters:

instance_root (Path)

Return type:

Path

femic.tsr_catalog.default_tsr_thlb_netdown_recipe_path(*, instance_root)

Return the default per-instance THLB netdown recipe path.

Parameters:

instance_root (Path)

Return type:

Path

femic.tsr_catalog.default_tsr_thlb_netdown_status_report_path(*, instance_root)

Return the default human-readable hybrid THLB status report path.

Parameters:

instance_root (Path)

Return type:

Path

femic.tsr_catalog.default_tsr_thlb_notebook_runs_root(*, instance_root)

Return the default runtime root for notebook-driven THLB step runs.

Parameters:

instance_root (Path)

Return type:

Path

femic.tsr_catalog.default_tsr_thlb_reconstructed_audit_path(*, instance_root)

Return the default reconstructed THLB audit JSON path.

Parameters:

instance_root (Path)

Return type:

Path

femic.tsr_catalog.default_tsr_thlb_reconstructed_output_path(*, instance_root)

Return the default reconstructed fragment/resultant THLB checkpoint path.

Parameters:

instance_root (Path)

Return type:

Path

femic.tsr_catalog.default_tsr_thlb_reconstructed_status_report_path(*, instance_root)

Return the default human-readable reconstructed THLB status report path.

Parameters:

instance_root (Path)

Return type:

Path

femic.tsr_catalog.default_tsr_thlb_reconstruction_comparison_json_path(*, instance_root)

Return the default strict-vs-reviewed THLB comparison JSON path.

Parameters:

instance_root (Path)

Return type:

Path

femic.tsr_catalog.default_tsr_thlb_reconstruction_comparison_markdown_path(*, instance_root)

Return the default strict-vs-reviewed THLB comparison Markdown path.

Parameters:

instance_root (Path)

Return type:

Path

femic.tsr_catalog.default_tsr_thlb_step13_attribute_output_path(*, instance_root)

Return the default enriched checkpoint output path for TSR step 13.

Parameters:

instance_root (Path)

Return type:

Path

femic.tsr_catalog.default_tsr_thlb_strict_chain_checkpoint_path(*, instance_root, parent_step_id, row_order)

Parameters:

• instance_root (Path)

• parent_step_id (str)

• row_order (int)

Return type:

Path

femic.tsr_catalog.default_tsr_thlb_warmstart_markdown_path(*, instance_root)

Return the default generated THLB warm-start checklist path.

Parameters:

instance_root (Path)

Return type:

Path

femic.tsr_catalog.default_tsr_thlb_warmstart_yaml_path(*, instance_root)

Return the default editable THLB warm-start YAML path.

Parameters:

instance_root (Path)

Return type:

Path

femic.tsr_catalog.default_tsr_thlb_workbench_locked_recipe_path(*, instance_root)

Return the default frozen THLB recipe copy path.

Parameters:

instance_root (Path)

Return type:

Path

femic.tsr_catalog.default_tsr_thlb_workbench_locked_script_path(*, instance_root)

Return the default locked THLB workbench script path.

Parameters:

instance_root (Path)

Return type:

Path

femic.tsr_catalog.default_tsr_thlb_workbench_notebook_path(*, instance_root)

Return the default generated THLB workbench notebook path.

Parameters:

instance_root (Path)

Return type:

Path

femic.tsr_catalog.discover_tsr_adjudication_overlay_providers()

Discover installed TSR adjudication overlay providers from entry points.

Return type:

tuple[str, …]

femic.tsr_catalog.extract_tsr_candidate_facts(*, documents_path, corpus_root, output_path, tsa_filters=(), max_documents=None, source_root=None, extract_pdf_pages_fn=<function _default_extract_pdf_pages>)

Extract reviewable TSR candidate facts from cached PDFs.

Parameters:

• documents_path (Path)

• corpus_root (Path)

• output_path (Path)

• tsa_filters (tuple[str, ...])

• max_documents (int | None)

• source_root (Path | None)

• extract_pdf_pages_fn (Callable[[Path], tuple[str, ...]])

Return type:

TsrExtractResult

femic.tsr_catalog.fetch_tsr_pdfs(*, documents_path, corpus_root, manifest_path, tsa_filters=(), max_documents=None, source_root=None, download_pdf_fn=<function _default_download_pdf>)

Fetch/cache TSR PDFs referenced by the canonical TSA documents inventory.

Parameters:

• documents_path (Path)

• corpus_root (Path)

• manifest_path (Path)

• tsa_filters (tuple[str, ...])

• max_documents (int | None)

• source_root (Path | None)

• download_pdf_fn (Callable[[str, Path], _DownloadedFileMetadata])

Return type:

TsrFetchResult

femic.tsr_catalog.get_tsr_adjudication_overlay_provider(provider_id)

Return one registered TSR adjudication overlay provider.

Parameters:

provider_id (str)

Return type:

TsrAdjudicationOverlayProvider

femic.tsr_catalog.index_tsr_tsa_surfaces(*, landing_url='https://www2.gov.bc.ca/gov/content/industry/forestry/managing-our-forest-resources/timber-supply-review-and-allowable-annual-cut', publish_root_url='https://www.for.gov.bc.ca/ftp/HTS/external/!publish/Timber_Supply_Review/', tsa_root_url='https://www.for.gov.bc.ca/ftp/HTS/external/!publish/Timber_Supply_Review/TSA/', fetch_text=None)

Crawl BC TSR TSA surfaces into canonical registry and document metadata.

Parameters:

• landing_url (str)

• publish_root_url (str)

• tsa_root_url (str)

• fetch_text (Callable[[str], str] | None)

Return type:

TsrIndexResult

femic.tsr_catalog.init_tsr_overlay(*, instance_root, overlay_path, tsa, registry_path, documents_path, candidate_facts_path, source_root, overwrite=False)

Create a reviewed/adopted TSR overlay skeleton for one TSA instance.

Parameters:

• instance_root (Path)

• overlay_path (Path)

• tsa (str)

• registry_path (Path)

• documents_path (Path)

• candidate_facts_path (Path)

• source_root (Path)

• overwrite (bool)

Return type:

TsrOverlayInitResult

femic.tsr_catalog.init_tsr_recipe_scaffolds(*, instance_root, tsa, registry_path, documents_path, candidate_facts_path, source_root, overlay_path, overrides_path, source_layers_recipe_path, thlb_netdown_recipe_path, overwrite=False)

Initialize per-instance TSR recipe scaffold YAML files.

Parameters:

• instance_root (Path)

• tsa (str)

• registry_path (Path)

• documents_path (Path)

• candidate_facts_path (Path)

• source_root (Path)

• overlay_path (Path)

• overrides_path (Path)

• source_layers_recipe_path (Path)

• thlb_netdown_recipe_path (Path)

• overwrite (bool)

Return type:

TsrRecipeInitResult

femic.tsr_catalog.init_tsr_source_layer_overrides(*, instance_root, overlay_path, overrides_path, include_outcomes=('no_catalog_match', 'failed'), overwrite=False)

Initialize a per-instance source-layer override template from the TSR overlay.

Parameters:

• instance_root (Path)

• overlay_path (Path)

• overrides_path (Path)

• include_outcomes (tuple[str, ...])

• overwrite (bool)

Return type:

TsrSourceLayerOverridesInitResult

femic.tsr_catalog.load_tsr_document_inventory(path)

Load the canonical TSR TSA documents inventory JSON.

Parameters:

path (Path)

Return type:

tuple[TsrInventoryDocument, …]

femic.tsr_catalog.load_tsr_overlay(path)

Load one reviewed/adopted TSR overlay YAML file.

Parameters:

path (Path)

Return type:

TsrOverlayRecord

femic.tsr_catalog.load_tsr_source_layer_overrides(path)

Load one instance-local TSR source-layer override YAML file.

Parameters:

path (Path)

Return type:

TsrSourceLayerOverridesRecord

femic.tsr_catalog.load_tsr_source_layers_recipe(path)

Load one per-instance source-layer recipe scaffold YAML file.

Parameters:

path (Path)

Return type:

TsrSourceLayersRecipeRecord

femic.tsr_catalog.load_tsr_thlb_netdown_recipe(path)

Load one per-instance THLB netdown recipe scaffold YAML file.

Parameters:

path (Path)

Return type:

TsrThlbNetdownRecipeRecord

femic.tsr_catalog.lock_tsr_thlb_workbench(*, recipe_path, notebook_path=None, lock_scope='all')

Freeze the current THLB workbench state into a deterministic script bundle.

Parameters:

• recipe_path (Path)

• notebook_path (Path | None)

• lock_scope (str)

Return type:

TsrThlbWorkbenchLockResult

femic.tsr_catalog.register_tsr_adjudication_overlay_provider(provider)

Register one TSR adjudication overlay provider in-process.

Parameters:

provider (TsrAdjudicationOverlayProvider)

Return type:

None

femic.tsr_catalog.report_tsr_candidate_facts(*, candidate_facts_path, tsa, fact_families, limit=None)

Render review-friendly rows from the canonical TSR candidate-fact pool.

Parameters:

• candidate_facts_path (Path)

• tsa (str)

• fact_families (tuple[str, ...])

• limit (int | None)

Return type:

TsrFactReportResult

femic.tsr_catalog.resolve_tsr_adjudication_overlay_provider(*, instance_root)

Resolve the instance-selected TSR adjudication overlay provider, if any.

Parameters:

instance_root (Path)

Return type:

TsrAdjudicationOverlayProvider | None

femic.tsr_catalog.resolve_tsr_workbench_instance_root(*, start=None)

Resolve the enclosing instance root for a generated THLB workbench.

Parameters:

start (Path | None)

Return type:

Path

femic.tsr_catalog.run_tsr_source_layers_recipe(*, recipe_path, bbox_epsg3005=None, geomark=None, limit=5, allow_order=False)

Execute safe source-layer acquisition steps from one recipe.

Parameters:

• recipe_path (Path)

• bbox_epsg3005 (tuple[float, float, float, float] | None)

• geomark (GeomarkBBox | None)

• limit (int)

• allow_order (bool)

Return type:

TsrSourceLayersRecipeRunResult

femic.tsr_catalog.run_tsr_thlb_locked_parent_step(*, recipe_path, parent_step_id, checkpoint_path, max_workers=None, lu_bundle_count=None, runtime_event_sink=None)

Execute one approved locked THLB parent step from one explicit checkpoint.

Parameters:

• recipe_path (Path)

• parent_step_id (str)

• checkpoint_path (Path)

• max_workers (int | None)

• lu_bundle_count (int | None)

• runtime_event_sink (Callable[[dict[str, Any]], None] | None)

Return type:

TsrThlbParentStepRunResult

femic.tsr_catalog.run_tsr_thlb_netdown_recipe(*, recipe_path, checkpoint_path=None, output_path=None, audit_path=None, execution_mode='hybrid', map_ids=(), auto_map_id_smoke_subset=False, allow_stand_binary_fallback=False, write_aflb_gpkg=True, write_lhlb_gpkg=True, write_lhlb_curve_ready_gpkg=True, parallel_mode='auto', max_workers=None, lu_bundle_count=None, runtime_event_sink=None)

Execute a THLB netdown recipe into either a hybrid or reconstructed checkpoint.

Parameters:

• recipe_path (Path)

• checkpoint_path (Path | None)

• output_path (Path | None)

• audit_path (Path | None)

• execution_mode (str)

• map_ids (Sequence[str])

• auto_map_id_smoke_subset (bool)

• allow_stand_binary_fallback (bool)

• write_aflb_gpkg (bool)

• write_lhlb_gpkg (bool)

• write_lhlb_curve_ready_gpkg (bool)

• parallel_mode (str)

• max_workers (int | None)

• lu_bundle_count (int | None)

• runtime_event_sink (Callable[[dict[str, Any]], None] | None)

Return type:

TsrThlbNetdownRecipeRunResult

femic.tsr_catalog.run_tsr_thlb_parallel_benchmark(*, recipe_path, parent_step_ids, checkpoint_path=None, landscape_units=(), worker_counts=(1, 2, 4, 8))

Benchmark serial vs LU-parallel THLB parent-step execution.

Parameters:

• recipe_path (Path)

• parent_step_ids (Sequence[str])

• checkpoint_path (Path | None)

• landscape_units (Sequence[str])

• worker_counts (Sequence[int])

Return type:

TsrThlbParallelBenchmarkResult

femic.tsr_catalog.run_tsr_thlb_parent_step(*, recipe_path, parent_step_id, checkpoint_path=None, map_ids=(), landscape_units=(), auto_map_id_smoke_subset=True, execution_mode='serial', max_workers=None, lu_bundle_count=None, progress_root=None, persist_recipe_update=True)

Execute one THLB parent step cumulatively on the notebook smoke subset.

Parameters:

• recipe_path (Path)

• parent_step_id (str)

• checkpoint_path (Path | None)

• map_ids (Sequence[str])

• landscape_units (Sequence[str])

• auto_map_id_smoke_subset (bool)

• execution_mode (str)

• max_workers (int | None)

• lu_bundle_count (int | None)

• progress_root (Path | None)

• persist_recipe_update (bool)

Return type:

TsrThlbParentStepRunResult

femic.tsr_catalog.write_tsr_fact_report_csv(result, *, path)

Write review-friendly TSR fact rows to a CSV file.

Parameters:

• result (TsrFactReportResult)

• path (Path)

Return type:

Path

femic.tsr_catalog.write_tsr_index(result, output_root)

Write canonical TSR registry and document inventory JSON outputs.

Parameters:

• result (TsrIndexResult)

• output_root (Path)

Return type:

TsrWrittenIndex