Metadata-Version: 2.3
Name: deped-hr
Version: 0.5.1
Summary: Cleans personnel source exports into a standalone SQLite database.
Requires-Dist: deped-dcp-template>=0.12.1,<0.13
Requires-Dist: deped-primitives>=0.17.0,<0.18
Requires-Dist: deped-runtime[excel,polars,r2]>=0.9.2,<0.10
Requires-Dist: polars>=1.44
Requires-Dist: pydantic>=2.13
Requires-Dist: rapidfuzz>=3.14.5
Requires-Python: >=3.14
Description-Content-Type: text/markdown

# deped-hr

DepEd HR prepares personnel records for contact lookup, survey follow-up, and
source review. It combines the Portal survey with an InsightED ESF7 snapshot
and writes a standalone SQLite database, `artifacts/personnel.db`.

Start with [the guides](docs/index.md), [query examples](docs/reference/downstream-queries.md),
or [the schema and table rationale](docs/reference/schema.md).

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

The build needs the source files and sibling packages described in the
[build guide](docs/operations/build.md). Add historical category evidence with
`just build-esf7-history`; add workload and training details with
`just build-esf7-details`. Neither optional layer runs during the normal build.

ESF7 records, survey responses, and BEIS position counts measure different
things. An unmatched ESF7 record is a record to follow up, not a vacancy.
[Understand the sources](docs/source-contracts/index.md) before comparing counts.

The phase11 database uses contract `personnel_v6`, with Entity selection owned by
Entity’s published current view. A rebuild is required to obtain this corrected
selection; the reader can still inspect historical `personnel_v5` artifacts. The three school/office reporting names remain available as saved
queries (SQL views). Equipment uses the restricted `personnel_matching` view.
“Public” in a view name means a supported interface; it does not grant permission
to share personnel data.

For development, run `just check` and `just package`. See
[development](docs/operations/development.md) for setup and checks.

## Command environment

R2 transfer recipes use `op run --env-file=env.r2` to resolve the checked-in
1Password references only for the transfer process. Install the 1Password CLI
and authorize access to the referenced vault before running them.
`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

Have your secret manager or CI secret store supply `R2_ACCOUNT_ID`,
`R2_ACCESS_KEY_ID`, `R2_SECRET_ACCESS_KEY`, and `R2_BUCKET` to the command's
environment, with `R2_REGION=auto`. Supply resolved values, not `op://`
references. Run the underlying CLI directly; the Just transfer recipes still
invoke `op`, even when credentials are already exported:

```sh
uv run deped-runtime r2 download --target "data/portal" --prefix "deped-hr/portal"
uv run deped-runtime r2 download --target "data/esf7" --prefix "deped-hr/esf7"
uv run deped-runtime r2 download --target "data/ito" --prefix "deped-hr/ito"
uv run deped-runtime r2 upload --source "data/portal" --prefix "deped-hr/portal" --overwrite
uv run deped-runtime r2 upload --source "data/esf7" --prefix "deped-hr/esf7" --overwrite
uv run deped-runtime r2 upload --source "data/ito" --prefix "deped-hr/ito" --overwrite
```

These examples use the repository's default paths and prefixes. Adjust the
explicit flags for another location, retaining any include/overwrite options.
The upload command writes to the remote bucket. If you lack bucket access,
obtain the required inputs from maintainers and place them at the documented
local paths; installing 1Password does not itself grant data access.

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.
