Metadata-Version: 2.3
Name: deped-primitives
Version: 0.17.1
Summary: Shared DepEd PSGC, hierarchy, territory, SQL, and Marimo primitives.
Author: Marcelino Veloso III
Author-email: Marcelino Veloso III <marsveloso@gmail.com>
Requires-Dist: deped-runtime>=0.9.0,<0.10
Requires-Dist: polars>=1.44
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=15.0
Requires-Dist: pluggy>=1.6,<2 ; extra == 'insights'
Requires-Dist: deped-runtime[marimo]>=0.9.0,<0.10 ; extra == 'marimo'
Requires-Python: >=3.14
Provides-Extra: insights
Provides-Extra: marimo
Description-Content-Type: text/markdown

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

# deped-primitives

`deped-primitives` gives DepEd repositories one tested interpretation of shared
codes, names, hierarchies, school attributes, filters, metrics, and review
rules. Projects import the focused module they need instead of copying those
rules locally.

Provider contracts can be consumed through `ProviderOutputReader`, which binds
the producer identity and supported contract/schema window, resolves declared
SQLite paths inside the provider repository, validates public relations and
columns, delegates complete-receipt and selected output path/contract/hash
verification to `deped-runtime`, and opens the output read-only.

The package covers Philippine Standard Geographic Code (PSGC) identity,
administrative hierarchies, boundaries, school vocabulary, access scopes,
Structured Query Language (SQL) construction, provider context, metrics, and
review helpers.

It is intentionally small. Producer repos own source ingestion and artifacts;
consumer repos own products, notebooks, dashboards, and runtime state. This
package owns the deterministic interpretation rules that those repos should
not copy locally.

## Quick Start

```python
from deped_primitives.identity import GeoType, ancestor_codes, normalize_code
from deped_primitives.identity.codes import normalize_boundary_pcode_to_psgc_id
from deped_primitives.schools.names import clean_school_name
from deped_primitives.selection.access import AccessScope, scope_locks_from_access

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

Import specialized semantics from their owner modules rather than from the root
package:

```python
from deped_primitives.areas.boundaries import usable_area_boundary_components
from deped_primitives.authority.legislative import legislative_child_rollups
from deped_primitives.selection.providers import provider_context_sql
from deped_primitives.selection.navigation import build_territory_path
from deped_primitives.selection.search import SEARCH_TARGET_BY_KEY
```

Current shared semantics to check before copying local code:

- `deped_primitives.connectivity` for canonical ISP and connection-type
  catalogs, family codes, and ambiguity-safe text normalization.
- `deped_primitives.schools.funding_sources` and
  `deped_primitives.schools.education_levels` for school funding, education
  level, and grade-to-level normalization.
- `deped_primitives.authority.governance` for DepEd source governance area IDs,
  canonical division authority ID grammar, division/school match keys,
  historical division-label aliases, and resolution/status vocabularies.
- `deped_primitives.authority.policy` for shared immutable-policy freezing,
  required text, and canonical PSGC-ID validation.
- `deped_primitives.selection.providers` and
  `deped_primitives.selection.provider_contracts` for school-keyed provider
  context and provider contract metadata.
- `deped_primitives.selection.marimo` for notebook region-group, territory, and
  area-scope controls. Use `deped-runtime` for CLI, SQLite, file, workbook, and
  other non-semantic runtime plumbing.
- `deped_primitives.selection.navigation` and
  `deped_primitives.selection.search` for application-neutral territory paths,
  sibling semantics, Directory targets, and literal matching policy.

## Documentation

- [DepEd Orchestrator](https://mv3.dev/deped-orchestrator/) shows where this
  shared library fits in the full workspace pipeline.
- [Overview](docs/index.md) explains the domain flow and reading path.
- [Ecosystem](docs/ecosystem.md) explains sibling-repo ownership boundaries and
  what belongs in this package.
- [Status](docs/status.md) is the current capability map.
- [Package reference](docs/reference/package.md) lists the curated package
  surface and owner-module references.
- [Migration to 0.1](docs/migration-0.1.md) covers the current public import
  layout.

## Development

Install pre-commit once with `uv tool install pre-commit --with pre-commit-uv`.
Set up the development environment and run the complete verification sequence:

```sh
uv sync --locked --all-extras
pre-commit run --all-files
just check
```

Pre-commit owns Ruff's pinned version and runs lint fixes and formatting.
`pre-commit run --all-files` runs lint, formatting, and ty type checks.
`just check` runs tests, documentation, and distribution builds.

As a shared semantic library, Primitives has no repository-level data product:
`just build` reports that boundary, while `just package` builds the Python
distribution. `just preflight`, `just status --json`, and `just audit` provide
the same read-only operating surface as the data repositories.

Useful narrower commands:

```sh
pre-commit run ruff-check --all-files
pre-commit run ruff-format --all-files
just test
uv run zensical build
uv run --extra marimo marimo check notebooks/*.py
```

## Shared-library development

The `[tool.uv.sources]` entries select sibling checkouts for this coordinated
release; published packages retain versioned requirements. Keep the declared
sibling repositories next to this checkout. Run `uv sync --locked --all-extras`,
then `pre-commit run --all-files` and `just check`. Candidate distributions are
also validated without editable sources before external publication.

## Command environment

`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


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.
