deped-entity 0.1.0

Builds a canonical stakeholder entity SQLite database from the StakeholderProfile workbook.

deped-entity

deped-entity builds the canonical stakeholder entity SQLite database from the StakeholderProfile workbook. It owns entity identity for schools, division offices, and regional offices so downstream packages can join against a shared natural_key contract instead of rebuilding their own entity tables.

What This Package Owns

• Header-driven extraction from StakeholderProfile
• Canonical entities.db artifact creation
• Travel-time, coordinate, and transportation alias normalization
• Reference and junction tables for nearby institutions, road conditions, and transportation modes
• Build provenance through build_runs

This package is the source of truth for the entities.db artifact only.

Inputs And Outputs

Required input:

• A stakeholder workbook under data/ with the expected StakeholderProfile headers

Primary output:

• artifacts/entities.db

CLI

Build the entity database:

uv run entity build \
  --input data/2026-04-02-entities.xlsx \
  --db artifacts/entities.db

Audit a built database:

uv run entity audit \
  --db artifacts/entities.db

Notes

• The loader maps columns by header text, not by Excel column letter.
• Blank business-key rows are skipped.
• All nonblank stakeholder rows are retained, including rows whose Type Of Transaction is not Beginning Inventory.
• natural_key generation intentionally matches the shared helpers from deped-dcp-template.
• Multiple source rows may share the same natural_key; source_row_id remains the unique row-level provenance key.

Documentation

This repository uses Zensical for documentation.

• Overview
• Build Guide
• Data Contract
• Development

Build the docs locally with:

uv run zensical build

Tests

uv run pytest -q