Metadata-Version: 2.3
Name: deped-hr
Version: 0.3.3
Summary: Cleans personnel source exports into a standalone SQLite database.
Requires-Dist: deped-dcp-template>=0.11.1
Requires-Dist: deped-primitives>=0.12
Requires-Dist: deped-runtime[excel,polars,r2]>=0.7
Requires-Dist: polars>=1.42
Requires-Dist: pydantic>=2.13
Requires-Dist: rapidfuzz>=3.14.5
Requires-Python: >=3.14
Description-Content-Type: text/markdown

# deped-hr

`deped-hr` combines personnel, InsightED ESF7, information-technology officer,
Entity, and Dataset inputs into read-only SQLite products for staffing analysis
and audit. It normalizes qualifications and assignments while keeping
person-level evidence and review limits explicit.

`deped-hr` builds and documents the DepEd personnel SQLite artifact:
`artifacts/personnel.db`. The artifact is the read-only boundary for downstream
systems that need HR metrics, staffing coverage, contact fields, or audit
evidence without re-parsing the portal personnel DB or ESF7 source files. An
optional later stage produces `artifacts/esf7_details.db` for row-linked
workload and training audit detail.

Installed consumers use `deped_hr.reader.load_reader()` for version-bound,
receipt-verified, read-only access to the personnel provider output.

The complete staged artifact can combine these source families:

- the portal personnel SQLite database
- the current InsightED ESF7 SQLite extract
- optionally, the three SY 2024-2025 ESF7 CSVs as historical category and COC
  evidence
- the ITO access workbook
- lookup data from `deped-dcp-template`
- school, division-office, and regional-office entities from `deped-entity`
- the history-aware Public DepEd school spine from `deped-dataset`

## What This Repo Owns

- Personnel row cleaning and normalization
- Lookup-driven position title resolution
- Entity loading for the personnel domain only
- snapshot-aware ESF7 loading, category authority, workload/training detail,
  and conservative current-ESF7-to-personnel matching
- ITO access-source loading, office matching, and access-safe publication
- A staged, auditable rebuild pipeline for `artifacts/personnel.db`
- Public SQL surfaces for analytics, registry import, KPI review, and audit
- Build metadata, row rejects, compatibility files, and quality-review reports

It does not own the canonical entity registry, the DCP lookup generator, or
downstream school-universe, geography, learner-denominator, or analytics policy.

## Build

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

`just build` is the normal local workflow. It reads the personnel source from
`PORTAL_DB` or `../azure-db-extractor/data/portal.db`, refreshes
`artifacts/lookups.db`, incrementally rebuilds `artifacts/personnel.db` from
the narrow current InsightED core and
`../deped-dataset/artifacts/db.sqlite3`. Run `just audit` separately for the
read-only receipt and domain-quality gate.

Add the expensive optional layers independently after the core is usable:

```sh
just build-esf7-history
just build-esf7-details
```

Export the current ESF7 school-governance evidence without personnel fields:

```sh
just export-esf7-governance
```

This writes `artifacts/esf7-governance.db`, a privacy-minimal audit artifact
containing raw school/governance submissions, primitives-derived source IDs,
variant counts, and unanimity or strict-majority consensus. It refuses to read
an in-progress HR build and does not declare whether ESF7 or BEIS is correct.

The history stage adds exact category evidence and COC fallback. The details
stage performs a separate wide InsightED scan to build workload/training
summaries and `artifacts/esf7_details.db`. Either can be run later or omitted.

## Docs

Start from [Docs Home](./docs/index.md). The main reading paths are:

- Build and operate: [Build Workflow](./docs/operations/build.md)
- Query and consume: [Data Contract](./docs/reference/data-contract.md) and
  [Downstream Queries](./docs/reference/downstream-queries.md)
- Understand source rules:
  [Source Normalization](./docs/source-contracts/normalization.md)
- Review evidence and current data issues:
  [Evidence Diagnostics](./docs/analysis/evidence-diagnostics/index.md)

Serve the docs locally:

```sh
just docs
```

## Key Semantics

- The selected InsightED SY 2025-2026 snapshot is authoritative for current
  school-level staffing counts. Before optional history is loaded, current
  positions remain `UNCLASSIFIED`; exact SY 2024-2025 raw-position evidence
  classifies matching positions when the history stage is added.
- The personnel survey is the contact/email source after audited matching; it
  is not the staffing-count authority.
- `school_personnel_public_current` is the analytics provider surface. It is
  keyed by `school_id` and intentionally excludes HR-owned geography text,
  resubmission guidance, and other registry-only fields.
- `office_ito_access_current` is the office access provider surface. It keeps
  matched ITO regional and division office rows with personal DepEd email
  addresses and leaves contact/audit details in internal tables and views.
- `school_personnel_registry_current` is the materialized school-level import
  table for registry-style consumers. Historical modified COC evidence is
  mapped to the shared `levels_mask` vocabulary with source-year provenance.
- ESF7 region, division, and district text remains raw evidence alongside
  primitives-derived normalized labels and source-area IDs. Canonical school
  governance IDs remain owned by the downstream school spine.
- Personnel `detailed_from` and `detailed_to` evidence resolves to canonical
  dataset `school_key` values when an embedded ID, exact normalized name, or
  strict same-division fuzzy match is safe. Ambiguous candidates remain audit
  evidence rather than silently becoming school IDs.
- `esf7-governance.db` is the narrow cross-repo comparison handoff. It excludes
  employee, contact, position, qualification, and submission-time fields.
- School and office KPI consumers should start from `v_school_personnel_kpis`
  and `v_office_personnel_kpis`.
- Office rollups should use `v_office_personnel_summary` and
  `v_office_personnel_kpis`, not inferred school rows.
- `TIN`, `phylsys_num`, religion, ethnic group, civil status, and raw change
  payloads from ESF7 are never stored in either artifact.

School-level public surfaces resolve reviewed provider operational aliases
before deduplication and aggregation. Raw personnel and ESF7 tables retain
source IDs; public rows expose their sorted JSON provenance in
`source_school_ids`.

## Verification

Run the complete quality gate:

```bash
uv run ruff check src tests notebooks
uv run ruff format --check src tests notebooks
uv run pyright
uv run pytest -q
uv run zensical build
just package
```
