deped-hr 0.3.2

o# deped-hr

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

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:

just build-esf7-history
just build-esf7-details

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

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. The main reading paths are:

• Build and operate: Build Workflow
• Query and consume: Data Contract and Downstream Queries
• Understand source rules: Source Normalization
• Review evidence and current data issues: Evidence Diagnostics

Serve the docs locally:

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:

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