# STARTHERE — mgf-tele-core

> **Sibling library in the Magogi Foundation federation.**
> See [README.md](README.md) for what this library does; see
> [mgf-common/FEDERATION.md](https://codeberg.org/magogi-admin/mgf-standard/src/branch/main/FEDERATION.md)
> for the federation contract.

`mgf-tele-core` is the **vendor-neutral telematics seam** for
`mgf-common` consumers: the `TelematicsProvider` device-session ABC,
the codec-agnostic AVL frame types
(`GeoPoint` / `DecodedAvlRecord` / `ReceivedPacket` / `ParseStatus`),
a typed `TelematicsError` hierarchy (all subclassing
`mgf.common.exceptions.AppError`), and a scripted
`mgf.tele.core.mock.MockTelematicsProvider`. Per-vendor codecs
(`mgf-tele-teltonika`, …) build on it and never the other way.

---

## For consumers (using this library)

1. **Pin** in your `pyproject.toml`:
   ```toml
   dependencies = ["mgf-tele-core>=X.Y,<X.$((Y+1))"]
   ```
   See [CHANGELOG.md](CHANGELOG.md) for the current minor.
2. **Install:** `uv add mgf-tele-core` (or `pip install mgf-tele-core`).
3. **Read** [README.md](README.md) for the stable surface — the
   `TelematicsProvider` ABC, the frame types, and the error hierarchy.
4. **Bootstrap your app** with mgf-common first — see
   [mgf-common/STARTHERE.md](https://codeberg.org/magogi-admin/mgf-common/src/branch/main/STARTHERE.md).
5. **Wire a concrete provider** into your ingest loop (a per-vendor
   codec like `mgf-tele-teltonika`, or `MockTelematicsProvider` in
   tests); the core itself ships only the ABC + frame types + errors.
6. **Adopt the federation contract** — file your
   `MGF_STANDARDS_CONFORMANCE.md` per
   [DOC-15](https://codeberg.org/magogi-admin/mgf-standard/src/branch/main/docs/standards/DOCUMENTATION.md).
7. **Run** `mgf-common catch-up` periodically to verify federation
   drift; see [FEDERATION.md](FEDERATION.md).

---

## For contributors

See [CONTRIBUTING.md](CONTRIBUTING.md). Standards are inherited
from [mgf-common](https://codeberg.org/magogi-admin/mgf-standard/src/branch/main/docs/standards/).

---

## Quick links

| Resource | Where |
|---|---|
| Library purpose | [README.md](README.md) |
| Release notes | [CHANGELOG.md](CHANGELOG.md) |
| What we depend on / who depends on us | [DEPS.md](DEPS.md) |
| Feedback (PAPER-NN) | [FEEDBACK.md](FEEDBACK.md) |
| Federation contract | [FEDERATION.md](FEDERATION.md) |
| Cross-project standards | [mgf-standard/docs/standards/](https://codeberg.org/magogi-admin/mgf-standard/src/branch/main/docs/standards/) |
