Metadata-Version: 2.4
Name: zen-anomaly-client
Version: 0.1.0
Summary: Anomaly event contract and client for the zen-space anomaly stream
Author-email: Hank Haines <hankhaines@wellchecked.com>
License-Expression: MIT
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE.md
Requires-Dist: pydantic<3,>=2.5
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Dynamic: license-file

# zen-anomaly-client

The anomaly event contract for the zen-space platform, and (from Phase 3) the
client, wiring helpers and pytest harness an edge or service process uses to
report failures to the anomaly stream.

Plan and phases: `docs/ANOMALY_EVENT_STREAM_PLAN.md` in zen-space-network-api.
Edge contract (endpoints, codes, examples): `docs/contracts/ANOMALY_EDGE_CONTRACT.md`
in the same repository.

## Install

```
pip install zen-anomaly-client
```

Depends on `pydantic` only.

## The contract

```python
from zen_anomaly_client import AnomalyEvent, AnomalySource, Category, Severity, codes

event = AnomalyEvent(
    source=AnomalySource(system="edge", instance="org1.box7", version="1.4.0"),
    site_slug="gil",
    category=Category.UPLOAD,
    code=codes.EDGE_UPLOAD_FAILED,
    severity=Severity.WARNING,
    message="upload failed after 3 attempts",
    details={"file": "w_Gil_camera0_20261112120001.mp4", "size": 12345, "error": "ReadTimeoutError"},
)
event.to_json()      # the wire format
event.topic          # "edge/edge.upload.failed"
event.dedupe_key     # "edge:edge.upload.failed:gil" unless you set one
```

Rules the model enforces: `code` is `system.subject.what` in lower snake case
(2–4 segments); `message` is stripped and cut at 500 characters; `details` is
one level deep, at most 32 keys, string values cut at 1024 characters; slugs
are lower-case; timestamps are normalised to UTC. Unknown fields are rejected.

`codes.CATALOGUE` lists every known code with its category, default severity
and meaning. Codes not in the catalogue are accepted but shown as "Unlisted".

## Development

```
python -m venv .venv && .venv/bin/pip install -e '.[dev]'
.venv/bin/python -m pytest
```

Release: `bin/pypi-build.sh` then `bin/pypi-upload.sh` (twine, PyPI credentials required).
