Metadata-Version: 2.4
Name: deped-entity
Version: 0.1.2
Summary: Builds a canonical stakeholder entity SQLite database from the StakeholderProfile workbook.
Requires-Python: >=3.14
Requires-Dist: click>=8.1
Requires-Dist: deped-dcp-template>=0.2.1
Requires-Dist: rich>=14.0
Description-Content-Type: text/markdown

# 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
- Canonical relation 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:

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

Audit a built database:

```sh
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.
