deped-entity

deped-entity turns validated Portal stakeholder rows into a versioned SQLite database of schools and governance entities. It applies shared value cleanup, records a build receipt, and provides a supported read-only reader.

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 ty checks through pre-commit, tests, and the Zensical docs build.

Shared-library development

The [tool.uv.sources] entries select sibling checkouts for this coordinated release; published packages retain versioned requirements. Keep the declared sibling repositories next to this checkout. Run uv sync --locked --all-extras, then pre-commit run --all-files and just check. Candidate distributions are also validated without editable sources before external publication.

Command environment

just publish uses op run --env-file=env.publish; only the upload process receives UV_PUBLISH_TOKEN. Package builds do not require vault access. Just does not load or generate .env. Export ordinary configuration overrides in your shell. Existing local .env files are not deleted automatically; move any needed overrides before removing old plaintext copies.

Without 1Password

For package publication, build with just package, then supply UV_PUBLISH_TOKEN from your secret manager or CI secret store to uv publish:

just package
uv publish

This requires publishing permission for the package. just publish still invokes op; use the direct command above when 1Password is unavailable.

Keep actual secrets out of reference files, committed files, and shell command history. Ordinary offline builds and checks do not require 1Password.