# Public API — `mgf-logship`

> **Master-HEAD banner:** tracks the CURRENT main/release surface. Verify your pin via
> `mgf.logship.__version__` (mirrors `pyproject.toml`). Machine-readable companion:
> [`PUBLIC_API.json`](PUBLIC_API.json), generated from `__all__` + pinned in CI.

The public surface is exactly `mgf.logship.__all__`. Modules under a leading underscore
(`_shipper`, `_protocol`) are private. The `collector` submodule is the optional `[collector]` stub.

- **Stability tiers:** every public name is `experimental` (the 0.x window).

## `mgf.logship`

| Name | Tier | Description |
|---|---|---|
| `LogShipper` | experimental | The fail-open `logging.Handler`: batches redacted LogRecord JSON + POSTs to a collector. |
| `encode_ndjson` | experimental | Encode records (+ optional stats) to the versioned NDJSON wire (bytes). |
| `decode_ndjson` | experimental | Decode the NDJSON wire back to a list of record dicts. |
| `SHIP_PROTOCOL_VERSION` | experimental | The wire-protocol version integer (negotiated/embedded). |
| `INGEST_PATH` | experimental | The collector ingest route (`/ingest`). |
| `HEALTH_PATH` | experimental | The collector health route (`/health`). |
| `STATS_PATH` | experimental | The collector stats route (`/stats`). |

## The stub collector

`create_collector_app` lives in `mgf.logship.collector` (optional `[collector]` FastAPI extra) —
a dev/test store-now sink, NOT in the generic `__all__` so `import mgf.logship` stays FastAPI-free.
