Metadata-Version: 2.4
Name: deped-primitives
Version: 0.0.2
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 three layers:

- **Foundation primitives:** PSGC code rules, boundary/legacy code
  normalization, hierarchy metadata, region groups, and shared reference
  vocabularies.
- **Consumer semantics:** normalized PSGC frames, `psgc-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.

The root package exposes a curated facade for common foundation and product
helpers. Specialized consumer-semantics helpers stay in their owner modules so
their artifact contracts remain explicit.

## Quick Start

```python
from deped_primitives import (
    AccessScope,
    FilterSpec,
    GeoType,
    SCHOOL_OBSERVATIONS_ADAPTER,
    ancestor_codes,
    breakdown,
    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 "school_observations" in summary_sql(
    SCHOOL_OBSERVATIONS_ADAPTER,
    FilterSpec(),
)
```

Import specialized semantics from owner modules:

```python
from deped_primitives.boundaries import 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)
children = legislative_child_rollups(coverage, barangay_context)
```

## Owned Surfaces

- `deped_primitives.psgc` and `psgc.frames`: PSGC parsing, validation,
  parentage, 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.
- `deped_primitives.boundaries`: consumer-safe interpretation of `psgc-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.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.

## 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), [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),
  [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
```
