Metadata-Version: 2.3
Name: deped-entity
Version: 0.3.6
Summary: Builds a canonical stakeholder entity SQLite database from the portal source.
Requires-Dist: deped-dcp-template>=0.12.1,<0.13
Requires-Dist: deped-primitives>=0.17.0,<0.18
Requires-Dist: deped-runtime>=0.9.0,<0.10
Requires-Python: >=3.14
Description-Content-Type: text/markdown

# 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](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 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`:

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