Metadata-Version: 2.3
Name: deped-entity
Version: 0.3.1
Summary: Builds a canonical stakeholder entity SQLite database from the portal source.
Requires-Dist: deped-dcp-template>=0.11,<0.12
Requires-Dist: deped-primitives>=0.11.0
Requires-Dist: deped-runtime>=0.6.7,<0.7
Requires-Python: >=3.14
Description-Content-Type: text/markdown

# deped-entity

`deped-entity` builds the canonical stakeholder entity artifact for DepEd data
repositories. Package version `0.3.1` produces schema `entities_v10` at
`artifacts/entities.db` from the portal `stakeholder_profile` table.

The artifact preserves each admitted source row, derives shared entity identity,
normalizes repeatable detail records, publishes current stakeholder and
remoteness views, and records build provenance. Reporting marts,
consumer-specific filters, authoritative geography, and ITO access policy stay
with their owning repositories.

## Start by task

- Build or inspect the artifact: see [operations](docs/operations.md).
- Choose the correct table, view, and join key: see the
  [artifact contract](docs/artifact-contract.md).
- Understand package and repository ownership: see
  [architecture and ownership](docs/architecture.md).
- Review field cleaning and source admission: see
  [normalization](docs/normalization.md).
- Change the producer safely: see [development](docs/development.md).

The complete documentation starts at [docs/index.md](docs/index.md).

## Standard workflow

```sh
just preflight
just build
just status --json
just audit
```

`just download` and `just fetch` explain that the raw source is owned by
`azure-db-extractor`; they do not contact the network. Use `just package` only
to build the Python distribution.

The default paths are:

| Purpose | Path |
| --- | --- |
| Portal source | `../azure-db-extractor/data/portal.db` |
| Generated artifact | `artifacts/entities.db` |

Set `PORTAL_DB` to use another portal database. To pass both paths explicitly:

```sh
uv run entity build \
  --portal-db ../azure-db-extractor/data/portal.db \
  --db artifacts/entities.db

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

The build validates the source relation and its required snake_case columns,
creates schema `entities_v10` in a same-directory staging database, loads and
checks the artifact, then atomically replaces the output. A failed build leaves
the previous artifact intact. The audit opens an existing artifact read-only.

## Public surfaces

| Surface | Use |
| --- | --- |
| `entities` | Source-row identity, provenance, submitted geography, and transaction fields |
| `entity_stakeholder_current` | Latest raw stakeholder row per `natural_key` |
| `entity_remoteness_current` | Latest raw stakeholder row with explicit known/unknown remoteness evidence |
| `school_remoteness_current` | One canonical school after reviewed school-ID aliases and evidence consolidation |
| detail and relation tables | Normalized location, remoteness, community, contact, personnel, institution, road, and transport evidence |
| `build_runs` | Source hash, row counts, schema version, and completion metadata |

## Consumer rules

- Use `entity_id` only for joins inside `entities.db`; use `natural_key` across
  artifacts.
- Use `school_remoteness_current.school_id` for school-grain remoteness joins.
  The view keeps contributing raw IDs in `source_school_ids`.
- Treat missing detail rows and false `_known` fields as absent evidence, not a
  negative answer.
- Treat `psgc_code`, `longitude`, and `latitude` as cleaned portal submissions.
  Canonical geography and coordinate review belong to `deped-dataset` and
  `deped-maps`.
- Read ITO personnel and office-access surfaces from `deped-hr`.

## Development

```sh
just test
just check
```

`just check` runs lint, formatting and Pyright checks, tests, and the Zensical
docs build.
