Metadata-Version: 2.4
Name: deped-equipment
Version: 0.1.0
Summary: Equipment cleaner extracted from the DepEd asset pipeline.
Requires-Python: >=3.14
Requires-Dist: deped-hr>=0.2.0
Description-Content-Type: text/markdown

# deped-equipment

`deped-equipment` cleans equipment CSV exports into a standalone SQLite database. It consumes three upstream artifacts: `lookups.db` from `deped-template`, `entities.db` from `deped-entity`, and `personnel.db` from `deped-hr`.

## What This Package Owns

- Equipment row cleaning and normalization
- Canonicalization of equipment dimensions such as brand, model, unit, category, acquisition mode, and DCP year
- Review-driven DCP attribution normalization layered on top of `lookups.db`
- Review-driven equipment location normalization for classroom, lab, office, and other storage/use contexts
- Review-driven supplier and disposition-status normalization for common vendor and asset-state variants
- Entity import from the upstream entity artifact
- Linking accountable personnel using a personnel snapshot artifact
- Equipment views and dimension issue audits

This package owns the equipment database contract only.

## Inputs And Outputs

Required inputs:

- an equipment CSV export
- a lookup database produced by `deped-template`
- an entity database produced by `deped-entity`
- a personnel database produced by `deped-hr`

Primary outputs:

- `equipment.db`
- `equipment_dimension_issues.txt`

The database stores normalized equipment rows plus canonical dimension tables seeded from the lookup artifact and reviewed dictionaries under `src/deped_equipment/dictionaries/`.

## CLI

Build the equipment database:

```bash
uv run equipment build \
  --equipment data/equipment.csv \
  --lookups artifacts/lookups.db \
  --entities-db artifacts/entities.db \
  --personnel-db artifacts/personnel.db \
  --db artifacts/equipment.db
```

Run the lightweight audit command:

```bash
uv run --package deped-equipment deped-equipment audit \
  --db artifacts/equipment.db
```

## Nuances

- Entity loading is artifact-driven. This package imports entities from `entities.db` using the same upstream contract as `deped-hr`.
- Personnel matching is artifact-driven. This package reads a snapshot from `personnel.db` and reuses shared helpers from `deped-hr` and `deped-dcp-template` where appropriate.
- Link resolution uses multiple signals, including scoped employee counts and name matching. Ambiguous matches are preserved as ambiguous rather than guessed.
- Equipment rows whose natural key is missing from the upstream entity artifact are flagged in `equipment_dimension_issues.txt` and skipped rather than aborting the build.
- Dimension issues are treated as first-class audit output. Raw values that cannot be canonicalized cleanly are emitted to `equipment_dimension_issues.txt`.
- DCP attribution is review-driven. Raw `DCP Package` values stay in `dcp_package_raw`, while approved canonical values resolve through `equipment_dcp_attributions`.
- Equipment location is review-driven. Raw `equipment_location` values remain intact, while approved canonical groupings resolve through `equipment_locations`.
- Only equipment-owned SQL assets live here now. Retired monolith views and unrelated tables were intentionally removed.

## Tests

Run the package tests from this directory:

```bash
uv run pytest -q
```
