Metadata-Version: 2.4
Name: sysnet-sekm-model
Version: 0.2.0
Summary: SEKM Pydantic 2 domain model and Beanie/MongoDB persistence model
Project-URL: Homepage, https://github.com/SYSNET-CZ/sekm-migrate
Project-URL: Documentation, https://github.com/SYSNET-CZ/sekm-migrate/blob/master/docs/DATA_MODEL.md
Project-URL: Repository, https://github.com/SYSNET-CZ/sekm-migrate
Project-URL: Bug Tracker, https://github.com/SYSNET-CZ/sekm-migrate/issues
License: AGPL-3.0-or-later
Requires-Python: >=3.12
Requires-Dist: beanie>=1.26
Requires-Dist: pydantic-settings>=2.3
Requires-Dist: pydantic>=2.7
Requires-Dist: pymongo>=4.7
Requires-Dist: sysnet-docversion>=0.1.3
Requires-Dist: sysnet-pyutils>=1.7.5
Provides-Extra: dev
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.2; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Description-Content-Type: text/markdown

# sysnet-sekm-model

[![PyPI](https://img.shields.io/pypi/v/sysnet-sekm-model)](https://pypi.org/project/sysnet-sekm-model/)
[![Python](https://img.shields.io/pypi/pyversions/sysnet-sekm-model)](https://pypi.org/project/sysnet-sekm-model/)
[![License: AGPL v3](https://img.shields.io/badge/License-AGPL_v3-blue.svg)](https://www.gnu.org/licenses/agpl-3.0)
[![GitHub](https://img.shields.io/badge/GitHub-SYSNET--CZ%2Fsekm--migrate-blue?logo=github)](https://github.com/SYSNET-CZ/sekm-migrate)

Pydantic 2 domain models and Beanie/MongoDB persistence layer for **SEKM** —
the Czech System of Evidence of Contaminated Sites (*Systém Evidence Kontaminovaných Míst*).

This library is the shared data layer for any service that reads or writes SEKM data
from MongoDB. It has no dependency on Elasticsearch; migration tooling lives in the
companion package [`sysnet-sekm-migrate`](https://pypi.org/project/sysnet-sekm-migrate/).

## Installation

```bash
pip install sysnet-sekm-model
```

## Requirements

- Python ≥ 3.12
- MongoDB instance (no Elasticsearch required)
- `.env` file with `MONGO_HOST`, `MONGO_PORT`, `MONGO_USERNAME`, `MONGO_PASSWORD`, `MONGO_DB`

## Quick start

```python
from sysnet_sekm_model.config import MongoSettings
from sysnet_sekm_model.db import init_mongo, close_mongo
from sysnet_sekm_model.models.persistence import AreaSourceDoc

# Initialise Beanie (reads credentials from .env / environment variables)
settings = MongoSettings()
client = await init_mongo(settings.mongo_uri, settings.mongo_db)

# Query
doc = await AreaSourceDoc.find_one(AreaSourceDoc.sekm_id == "12345678")

# Shutdown
await close_mongo(client)
```

## What's inside

### Domain models (`sysnet_sekm_model.models.domain`)

Pydantic 2 models for all 21 SEKM entities — validation and business logic only,
no MongoDB awareness:

| Model | Entity |
|---|---|
| `AreaSource` | Contaminated site (*lokalita*) — the central SEKM entity |
| `AsObject`, `AsRegion`, `AsDocument` | Site sub-entities |
| `Observation` | Field observation record |
| `Sample`, `SampleAdvanced` | Environmental measurement (up to 28 M records) |
| `User`, `Organisation` | Auth and organisation |
| `Template` | Document template |
| `Dictionary`, `Substance` | Reference data |
| `HistoryEvent`, `LockDocument`, `Approval` | Audit trail |
| `Region`, `District`, `Municipality`, … | Geographic reference data |

### Persistence models (`sysnet_sekm_model.models.persistence`)

Beanie documents backed by `sysnet-docversion`'s `VersionedDocument` for entities
that carry audit history. Each document stores:

- `sekm_id` — SEKM business key (unique index)
- `current_version` — version counter managed by `sysnet-docversion`
- `migration_meta` — provenance metadata (source ES index, migrated_at, batch ID)

### MongoDB connection (`sysnet_sekm_model.db`)

```python
from sysnet_sekm_model.db import init_mongo, close_mongo, ALL_DOCUMENT_MODELS
```

`init_mongo(uri, db)` initialises Beanie with all document models and creates indexes.
Uses `pymongo.AsyncMongoClient` directly — Motor is not used.

### Settings (`sysnet_sekm_model.config`)

```python
from sysnet_sekm_model.config import MongoSettings
```

`MongoSettings` is a Pydantic `BaseSettings` subclass that reads `MONGO_*` variables
from the environment or `.env`.

## Documentation

| Document | Contents |
|---|---|
| [Data Model](https://github.com/SYSNET-CZ/sekm-migrate/blob/master/docs/DATA_MODEL.md) | Full domain and persistence model reference |
| [Trial Migration Report](https://github.com/SYSNET-CZ/sekm-migrate/blob/master/docs/TRIAL_MIGRATION_REPORT.md) | Migration results and entity volumes |
| [Data Quality Report](https://github.com/SYSNET-CZ/sekm-migrate/blob/master/docs/DATA_QUALITY_REPORT.md) | Post-migration data quality findings |

## License

[AGPL-3.0](https://github.com/SYSNET-CZ/sekm-migrate/blob/master/LICENSE)
