deped-entity

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

Installed consumers use deped_entity.reader.load_reader() to validate the current or previous supported contract, database surfaces, and common build receipt before opening the artifact read-only.

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.
• Choose the correct table, view, and join key: see the artifact contract.
• Understand package and repository ownership: see architecture and ownership.
• Review field cleaning and source admission: see normalization.
• Change the producer safely: see development.

The complete documentation starts at docs/index.md.

Standard workflow

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:

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

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

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

just test
just check

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