Metadata-Version: 2.4
Name: deped-primitives
Version: 0.0.6
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.23.9; 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

Read the package top-down:

- places get one canonical identity across PSGC IDs, legacy codes, boundary
  PCODEs, and source names;
- regions can be read through geography, congressional, and school-admin lenses;
- areas carry boundary geometry, PSGC classifications, shapefile metrics, and
  school-observation properties;
- users drill down a lens tree to an area, access scopes gate the visible
  subtree, and metrics/outliers measure the selected population.

The root package exposes a curated facade for common helpers; specialized
artifact semantics and complete module surfaces stay in their owner modules so
their contracts remain explicit. See the
[documentation overview](docs/index.md) for the domain flow and
[ecosystem guide](docs/ecosystem.md) for the sibling-repo ownership map.

## Ecosystem

`deped-primitives` interprets across the ecosystem data flow:

- [deped-psgc](https://github.com/justmars/deped-psgc),
  [deped-legdist](https://github.com/justmars/deped-legdist),
  [deped-enroll](https://github.com/justmars/deped-enroll), and
  [deped-entity](https://github.com/justmars/deped-entity) produce source
  contracts.
- [deped-dataset](https://github.com/justmars/deped-dataset) builds canonical
  identity and school-observation tables.
- [deped-maps](https://github.com/justmars/deped-maps) combines identity with
  shapefiles so areas have shared IDs, shapes, population, and `area_sqkm`.
- [deped-geos](https://github.com/justmars/deped-geos) aggregates area and
  school properties into read-only geography artifacts.
- [deped-analytics](https://github.com/justmars/deped-analytics) serves the
  office-scoped user-facing app.

Provider repositories such as [deped-web](https://github.com/justmars/deped-web),
[deped-hr](https://github.com/justmars/deped-hr),
[deped-equipment](https://github.com/justmars/deped-equipment), and
[deped-exams](https://github.com/justmars/deped-exams) keep their own domain
artifacts and public tables. The [ecosystem guide](docs/ecosystem.md) explains
why those sibling repos remain separate and which shared rules belong here.

## 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.areas.boundaries import (
    area_component_rollups,
    usable_area_boundary_components,
)
from deped_primitives.authority.legislative import legislative_child_rollups
from deped_primitives.areas.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

The [status page](docs/status.md) is the capability map. The generated
[package reference](docs/reference/package.md) shows the root facade, and the
module reference pages show complete owner-module surfaces.

## Documentation

- [Overview](docs/index.md) explains where this package sits between producers
  and consumers and how identity, regions, boundaries, filters, access, and
  metrics connect.
- [Ecosystem](docs/ecosystem.md) explains the sibling-repo ownership boundaries
  and the rule for moving shared semantics into this package.
- [Core references](docs/reference/identity/psgc.md),
  [codes](docs/reference/identity/codes.md),
  [coordinates](docs/reference/schools/coordinates.md),
  [boundaries](docs/reference/areas/boundaries.md), and
  [legislative](docs/reference/authority/legislative.md) cover the central semantic
  contracts.
- [Hierarchy](docs/reference/authority/hierarchies.md),
  [region group](docs/reference/authority/region-groups.md),
  [filter](docs/reference/selection/filters.md),
  [access](docs/reference/selection/access.md),
  [SQL](docs/reference/selection/sql.md),
  [DataFrames](docs/reference/selection/dataframes.md), and
  [Marimo](docs/reference/selection/marimo.md) references cover reusable
  construction helpers.
- [Planning metrics](docs/reference/insights/metrics.md),
  [outliers](docs/reference/insights/outliers.md), and
  [CLI](docs/reference/operations/cli.md)
  cover shared scoring and terminal build helpers.
- [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
```
