Metadata-Version: 2.4
Name: deped-primitives
Version: 0.0.5
Summary: Shared DepEd PSGC, hierarchy, territory, SQL, and Marimo primitives.
Author-email: Marcelino Veloso III <marsveloso@gmail.com>
Requires-Python: >=3.14
Requires-Dist: polars>=1.41
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=15.0
Provides-Extra: marimo
Requires-Dist: marimo>=0.16; extra == 'marimo'
Description-Content-Type: text/markdown

# deped-primitives

![Github CI](https://github.com/justmars/deped-primitives/actions/workflows/ci.yml/badge.svg)

`deped-primitives` is the shared semantic contract layer for the DepEd data
ecosystem. Producer repositories publish artifacts and source-specific
contracts; consumer repositories build maps, datasets, notebooks, and
dashboards. This package owns the reusable value rules and interpretation
semantics between those layers.

It is intentionally not an application framework. It does not load source
workbooks, dissolve geometry, persist databases, run downstream build CLIs,
write artifacts, or host dashboards. It gives every DepEd repo one small,
tested place to import the rules that should not be reimplemented locally.

## Mental Model

The package has four API families:

- **Foundation primitives:** PSGC code rules, boundary/legacy code
  normalization, hierarchy metadata, region groups, and shared reference
  vocabularies.
- **Artifact semantics:** normalized PSGC frames, `deped-maps` boundary artifact
  interpretation, legislative coverage semantics, and legislative child rollup
  classification.
- **Product construction helpers:** territory filters, access scopes,
  schema-adapter SQL builders, CLI build-progress helpers, and optional Marimo
  notebook controls.
- **Source-reference helpers:** governance label normalization, DepEd division
  and school-district IDs, UACS organization reference keys, school-name
  normalization, and small reusable Polars frame helpers.

The root package exposes a curated facade for common foundation, construction,
and source-reference helpers. Specialized artifact semantics and complete
module surfaces stay in their owner modules so their contracts remain explicit.

## Quick Start

```python
from deped_primitives import (
    AccessScope,
    FilterSpec,
    GeoType,
    SCHOOL_OBSERVATIONS_ADAPTER,
    add_governance_ids,
    ancestor_codes,
    breakdown,
    clean_school_name,
    normalize_boundary_pcode_to_psgc_id,
    normalize_code,
    scope_locks_from_access,
    summary_sql,
)

assert normalize_code(" 13-3900-0000 ") == "1339000000"
assert ancestor_codes("1380610001", GeoType.BGY) == [
    "1300000000",
    "1380600000",
    "1380610000",
]
assert breakdown("0908301001").barangay.code == "0908301001"
assert normalize_boundary_pcode_to_psgc_id("PH0102801") == "0102801000"
assert scope_locks_from_access(
    AccessScope(level="regional", psgc_region_id="1300000000")
).locked_levels == ("region",)
assert clean_school_name("baliwag nhs") == "Baliwag National High School"
assert "school_observations" in summary_sql(
    SCHOOL_OBSERVATIONS_ADAPTER,
    FilterSpec(),
)
```

Import specialized semantics from owner modules:

```python
from deped_primitives.boundaries import (
    area_component_rollups,
    usable_area_boundary_components,
)
from deped_primitives.legislative import legislative_child_rollups
from deped_primitives.psgc.frames import normalized_psgc_group_rows

groups = normalized_psgc_group_rows(canonical_psgc_units)
usable_components = usable_area_boundary_components(area_boundary_components)
display_components = area_component_rollups(area_boundary_components, canonical_psgc_units)
children = legislative_child_rollups(coverage, barangay_context)
```

## Owned Surfaces

- `deped_primitives.psgc` and `psgc.frames`: PSGC parsing, validation,
  parentage, Manila sub-municipality normalization, typed breakdowns, lineage,
  and normalized group-row construction from `canonical_psgc_units.csv`.
- `deped_primitives.codes`: PSGC ID, PSA/NAMRIA PCODE, legacy-code, and
  comparable-name normalization plus caller-provided canonical-name mapping.
- `deped_primitives.coordinates`: shared school coordinate parsing, Philippine
  review extent validation, Pag-asa/Kalayaan handling, and presence status
  classification.
- `deped_primitives.boundaries`: consumer-safe interpretation of `deped-maps`
  boundary mapping and area-boundary component artifacts.
- `deped_primitives.hierarchies` and `region_groups`: shared hierarchy
  metadata, aliases, graph topology, renderability, derived IDs, and regional
  reporting groups.
- `deped_primitives.regions`, `education`, and `school_sizes`: typed reference
  vocabularies.
- `deped_primitives.urbanicity`, `school_ids`, and `school_years`: shared
  urban/rural bands, EBEIS school-ID first-digit rules, and school-year source
  specs.
- `deped_primitives.filters` and `access`: territory cascades, area scopes,
  membership traversal, office permission scopes, and UI lock derivation.
- `deped_primitives.sql`, `cli`, and `marimo`: schema-adapter SQL builders,
  shared CLI build-progress helpers, and optional notebook controls.
- `deped_primitives.legislative`: legislative anchors, coverage policy,
  coverage completion, area linkage, special cases, and child rollup
  classification.
- `deped_primitives.outliers` and `planning_metrics`: reusable statistical
  scoring helpers and Polars planning metric formulas for downstream review and
  geography products.
- `deped_primitives.frames`, `enrollment`, `school_names`, and `uacs`: small
  Polars frame utilities, DepEd governance ID construction, school-name
  normalization, and UACS organization reference matching.

## Documentation

- [Ecosystem role](docs/guide/ecosystem-role.md) explains where this package sits
  between producers and consumers.
- [PSGC and codes](docs/guide/psgc-and-codes.md),
  [coordinates](docs/guide/coordinates.md), [boundaries](docs/guide/boundaries.md),
  and [legislative](docs/guide/legislative.md) cover the core semantic
  contracts.
- [Hierarchies](docs/guide/hierarchies-and-region-groups.md),
  [reference vocabularies](docs/guide/reference-vocabularies.md),
  [governance references](docs/guide/governance-references.md),
  [planning metrics](docs/guide/planning-metrics.md),
  [filters](docs/guide/filters.md), and [querying](docs/guide/querying.md)
  cover reusable construction helpers.
- [CLI progress](docs/guide/cli-progress.md) covers shared terminal build
  status and progress helpers for consumer CLIs.
- [Status](docs/status.md) is the current capability map.
- [Reference](docs/reference/package.md) contains generated API pages.

## Development

```sh
pre-commit run --all-files
just check
```

Useful narrower commands:

```sh
just test
uv run zensical build
uv run --extra marimo marimo check notebooks/*.py
```
