zen-anomaly-client 0.1.0__tar.gz

zen_anomaly_client-0.1.0/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Well Checked Systems International
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

zen_anomaly_client-0.1.0/PKG-INFO

@@ -0,0 +1,69 @@
+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).

zen_anomaly_client-0.1.0/README.md

@@ -0,0 +1,53 @@
+# 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).

zen_anomaly_client-0.1.0/pyproject.toml

@@ -0,0 +1,30 @@
+[build-system]
+requires = ["setuptools>=77.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "zen-anomaly-client"
+version = "0.1.0"
+description = "Anomaly event contract and client for the zen-space anomaly stream"
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+license-files = ["LICENSE.md"]
+authors = [{ name = "Hank Haines", email = "hankhaines@wellchecked.com" }]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+]
+dependencies = [
+    "pydantic>=2.5,<3",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=7"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+testpaths = ["tests"]

zen_anomaly_client-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

zen_anomaly_client-0.1.0/src/zen_anomaly_client/__init__.py

@@ -0,0 +1,28 @@
+"""zen-anomaly-client: the anomaly event contract shared by every zen-space process.
+
+Phase 1 ships the contract only (`AnomalyEvent` and the code catalogue). The
+HTTP client, the wiring helpers and the pytest harness follow in Phase 3
+(docs/ANOMALY_EVENT_STREAM_PLAN.md in zen-space-network-api).
+"""
+from zen_anomaly_client.contract import (
+    ANOMALY_SCHEMA_VERSION,
+    AnomalyEvent,
+    AnomalySource,
+    Category,
+    Severity,
+    SEVERITY_ORDER,
+    severity_at_least,
+)
+from zen_anomaly_client import codes
+
+__all__ = [
+    "ANOMALY_SCHEMA_VERSION",
+    "AnomalyEvent",
+    "AnomalySource",
+    "Category",
+    "Severity",
+    "SEVERITY_ORDER",
+    "severity_at_least",
+    "codes",
+]
+__version__ = "0.1.0"

zen_anomaly_client-0.1.0/src/zen_anomaly_client/codes.py

@@ -0,0 +1,109 @@
+"""The anomaly code catalogue.
+
+A code is a stable dotted string `<system>.<subject>.<what>`; the first
+segment is the reporting system. Producers may emit codes that are not listed
+here (the contract only checks the shape), but every code that notifies
+someone or appears in a runbook should be added with its category, default
+severity and one-line meaning, so the manager page and the documentation
+describe it the same way.
+"""
+from typing import Dict, NamedTuple
+
+from zen_anomaly_client.contract import Category, Severity
+
+
+class CodeInfo(NamedTuple):
+    category: Category
+    severity: Severity
+    description: str
+
+
+# --- edge -----------------------------------------------------------------
+EDGE_UPLOAD_FAILED = "edge.upload.failed"
+EDGE_UPLOAD_RECOVERED = "edge.upload.recovered"
+EDGE_UPLOAD_GAVE_UP = "edge.upload.gave_up"
+EDGE_SERVICE_CRASHED = "edge.service.crashed"
+EDGE_SERVICE_RESTARTED = "edge.service.restarted"
+EDGE_ANOMALY_SPOOL_DROPPED = "edge.anomaly.spool_dropped"
+EDGE_PROBE = "edge.anomaly.probe"
+
+# --- api ------------------------------------------------------------------
+API_JOB_FAILED = "api.job.failed"
+API_AUDIT_WRITE_FAILED = "api.audit.write_failed"
+API_REQUEST_FAILED = "api.request.failed"
+API_CACHE_FAILED = "api.cache.failed"
+
+# --- lambda ---------------------------------------------------------------
+LAMBDA_REDIS_PUSH_FAILED = "lambda.redis.push_failed"
+LAMBDA_COPY_FAILED = "lambda.copy.failed"
+
+# --- subscribers (router, indexer, notifier, tally, describer) ----------------
+CONSUMER_STOPPED = "{system}.consumer.stopped"
+MESSAGE_FAILED = "{system}.message_failed"
+ROUTER_API_UNREACHABLE = "router.api.unreachable"
+ROUTER_SITE_CAP_REFUSED = "router.site_cap_refused"
+NOTIFIER_DELIVERY_EMAIL_FAILED = "notifier.delivery.email_failed"
+NOTIFIER_DELIVERY_SMS_FAILED = "notifier.delivery.sms_failed"
+NOTIFIER_SILENCE_CHECK_FAILED = "notifier.silence_check.failed"
+NOTIFIER_ANOMALY_RECORD_FAILED = "notifier.anomaly_record_failed"
+
+
+def consumer_stopped(system: str) -> str:
+    return CONSUMER_STOPPED.format(system=system)
+
+
+def message_failed(system: str) -> str:
+    return MESSAGE_FAILED.format(system=system)
+
+
+CATALOGUE: Dict[str, CodeInfo] = {
+    EDGE_UPLOAD_FAILED: CodeInfo(Category.UPLOAD, Severity.WARNING,
+                                 "An upload to S3 failed after its retries; the file waits in errored/."),
+    EDGE_UPLOAD_RECOVERED: CodeInfo(Category.UPLOAD, Severity.INFO,
+                                    "A file from errored/ uploaded on a later rescan."),
+    EDGE_UPLOAD_GAVE_UP: CodeInfo(Category.UPLOAD, Severity.ERROR,
+                                  "A file exhausted its rescan budget and will not be uploaded."),
+    EDGE_SERVICE_CRASHED: CodeInfo(Category.EDGE_SERVICE, Severity.ERROR,
+                                   "An edge container's main loop raised and exited."),
+    EDGE_SERVICE_RESTARTED: CodeInfo(Category.EDGE_SERVICE, Severity.INFO,
+                                     "An edge container started again after a crash."),
+    EDGE_ANOMALY_SPOOL_DROPPED: CodeInfo(Category.EDGE_SERVICE, Severity.WARNING,
+                                         "The anomaly spool hit its cap and dropped its oldest entries."),
+    EDGE_PROBE: CodeInfo(Category.OTHER, Severity.INFO,
+                         "A round-trip probe sent by `anomaly check`; never notifies."),
+    API_JOB_FAILED: CodeInfo(Category.JOB, Severity.ERROR,
+                             "A scheduled API job raised."),
+    API_AUDIT_WRITE_FAILED: CodeInfo(Category.DATABASE, Severity.WARNING,
+                                     "An audit log entry could not be written; the action itself succeeded."),
+    API_REQUEST_FAILED: CodeInfo(Category.API, Severity.ERROR,
+                                 "A request ended in a 5xx."),
+    API_CACHE_FAILED: CodeInfo(Category.INTEGRATION, Severity.INFO,
+                               "A best-effort cache write failed."),
+    LAMBDA_REDIS_PUSH_FAILED: CodeInfo(Category.STREAM, Severity.CRITICAL,
+                                       "The S3 lambda could not publish an object to Redis; the event is not in the pipeline."),
+    LAMBDA_COPY_FAILED: CodeInfo(Category.INTEGRATION, Severity.ERROR,
+                                 "The S3 lambda could not copy an object to its destination bucket."),
+    ROUTER_API_UNREACHABLE: CodeInfo(Category.API, Severity.ERROR,
+                                     "The router exhausted its retries against the API."),
+    ROUTER_SITE_CAP_REFUSED: CodeInfo(Category.API, Severity.INFO,
+                                      "The API refused a new pending site because the org is at its cap."),
+    NOTIFIER_DELIVERY_EMAIL_FAILED: CodeInfo(Category.DELIVERY, Severity.WARNING,
+                                             "An e-mail notification could not be sent."),
+    NOTIFIER_DELIVERY_SMS_FAILED: CodeInfo(Category.DELIVERY, Severity.WARNING,
+                                           "An SMS notification could not be sent."),
+    NOTIFIER_SILENCE_CHECK_FAILED: CodeInfo(Category.JOB, Severity.ERROR,
+                                            "The site-silence check could not run."),
+    NOTIFIER_ANOMALY_RECORD_FAILED: CodeInfo(Category.STREAM, Severity.WARNING,
+                                             "The anomaly consumer could not record a message with the API."),
+}
+
+for _system in ("router", "indexer", "notifier", "tally", "describer"):
+    CATALOGUE[consumer_stopped(_system)] = CodeInfo(
+        Category.STREAM, Severity.CRITICAL, f"The {_system}'s consumer thread stopped; messages are not being read.")
+    CATALOGUE[message_failed(_system)] = CodeInfo(
+        Category.STREAM, Severity.ERROR, f"The {_system} failed to process one stream message.")
+
+
+def info(code: str) -> CodeInfo:
+    """Catalogue entry for a code, or a generic one for an unlisted code."""
+    return CATALOGUE.get(code, CodeInfo(Category.OTHER, Severity.WARNING, "Unlisted code."))

zen_anomaly_client-0.1.0/src/zen_anomaly_client/contract.py

@@ -0,0 +1,163 @@
+"""The anomaly event contract.
+
+One definition, imported by the API that records anomalies, the subscribers
+that publish and consume them, and the edge processes that report them. A
+change here bumps ANOMALY_SCHEMA_VERSION; the API accepts the current and the
+previous version so a box on an older kit keeps reporting.
+
+Bounds are enforced here so no producer can flood the stream or the table:
+`details` is one level deep, at most DETAILS_MAX_KEYS keys, and string values
+longer than DETAILS_MAX_VALUE_CHARS are truncated (a traceback tail is useful,
+a whole log file is not).
+"""
+import re
+import uuid
+from datetime import datetime, timezone
+from enum import Enum
+from typing import Dict, Optional, Union
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
+
+ANOMALY_SCHEMA_VERSION = 1
+
+CODE_PATTERN = r"^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*){1,3}$"
+SLUG_PATTERN = r"^[a-z0-9][a-z0-9_-]*$"
+SYSTEM_PATTERN = r"^[a-z][a-z0-9_-]*$"
+
+MESSAGE_MAX_CHARS = 500
+DETAILS_MAX_KEYS = 32
+DETAILS_MAX_VALUE_CHARS = 1024
+DEDUPE_KEY_MAX_CHARS = 256
+TRUNCATION_MARK = "…"
+
+DetailValue = Union[str, int, float, bool, None]
+
+
+class Severity(str, Enum):
+    INFO = "info"
+    WARNING = "warning"
+    ERROR = "error"
+    CRITICAL = "critical"
+
+
+SEVERITY_ORDER = {Severity.INFO: 0, Severity.WARNING: 1, Severity.ERROR: 2, Severity.CRITICAL: 3}
+
+
+def severity_at_least(severity: Severity, floor: Severity) -> bool:
+    """True when `severity` is as serious as `floor` or more."""
+    return SEVERITY_ORDER[Severity(severity)] >= SEVERITY_ORDER[Severity(floor)]
+
+
+class Category(str, Enum):
+    UPLOAD = "upload"
+    STREAM = "stream"
+    API = "api"
+    DATABASE = "database"
+    DELIVERY = "delivery"
+    JOB = "job"
+    EDGE_SERVICE = "edge-service"
+    INTEGRATION = "integration"
+    OTHER = "other"
+
+
+class AnomalySource(BaseModel):
+    """Who is reporting: the system (edge, api, router, ...), which instance of
+    it (a device id, an ECS task, a lambda request id) and its version."""
+    model_config = ConfigDict(extra="forbid")
+
+    system: str = Field(pattern=SYSTEM_PATTERN, max_length=32)
+    instance: Optional[str] = Field(default=None, max_length=128)
+    version: Optional[str] = Field(default=None, max_length=64)
+
+
+class AnomalyEvent(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    schema_version: int = ANOMALY_SCHEMA_VERSION
+    id: uuid.UUID = Field(default_factory=uuid.uuid4)
+    occurred_at: datetime = Field(default_factory=lambda: datetime.now(tz=timezone.utc))
+    source: AnomalySource
+    org_slug: Optional[str] = Field(default=None, pattern=SLUG_PATTERN, max_length=64)
+    site_slug: Optional[str] = Field(default=None, pattern=SLUG_PATTERN, max_length=64)
+    category: Category
+    code: str = Field(pattern=CODE_PATTERN, max_length=96)
+    severity: Severity
+    message: str = Field(min_length=1, max_length=MESSAGE_MAX_CHARS)
+    details: Dict[str, DetailValue] = Field(default_factory=dict)
+    dedupe_key: Optional[str] = Field(default=None, max_length=DEDUPE_KEY_MAX_CHARS)
+
+    @field_validator("occurred_at")
+    @classmethod
+    def _occurred_at_utc(cls, value: datetime) -> datetime:
+        """A naive timestamp is taken as UTC; an aware one is converted to it."""
+        if value.tzinfo is None:
+            return value.replace(tzinfo=timezone.utc)
+        return value.astimezone(timezone.utc)
+
+    @field_validator("message", mode="before")
+    @classmethod
+    def _message_stripped(cls, value):
+        if isinstance(value, str):
+            value = value.strip()
+            if len(value) > MESSAGE_MAX_CHARS:
+                return value[: MESSAGE_MAX_CHARS - len(TRUNCATION_MARK)] + TRUNCATION_MARK
+        return value
+
+    @field_validator("details", mode="before")
+    @classmethod
+    def _details_bounded(cls, value):
+        if value is None:
+            return {}
+        if not isinstance(value, dict):
+            raise ValueError("details must be an object")
+        if len(value) > DETAILS_MAX_KEYS:
+            raise ValueError(f"details has {len(value)} keys; at most {DETAILS_MAX_KEYS} allowed")
+        bounded = {}
+        for key, item in value.items():
+            if not isinstance(key, str) or not key:
+                raise ValueError("details keys must be non-empty strings")
+            if isinstance(item, (dict, list, tuple, set)):
+                raise ValueError(f"details.{key} must be a scalar; nested values are not allowed")
+            if isinstance(item, str) and len(item) > DETAILS_MAX_VALUE_CHARS:
+                item = item[: DETAILS_MAX_VALUE_CHARS - len(TRUNCATION_MARK)] + TRUNCATION_MARK
+            bounded[key] = item
+        return bounded
+
+    @model_validator(mode="after")
+    def _default_dedupe_key(self):
+        if not self.dedupe_key:
+            self.dedupe_key = self.default_dedupe_key(self.source.system, self.code, self.site_slug)
+        return self
+
+    @staticmethod
+    def default_dedupe_key(system: str, code: str, site_slug: Optional[str]) -> str:
+        return f"{system}:{code}:{site_slug or '-'}"
+
+    def with_site(self, site_slug: str, org_slug: Optional[str] = None) -> "AnomalyEvent":
+        """A copy pinned to a site. A default dedupe key follows the site; an
+        explicit one is kept. The API uses this to pin a device's report to
+        the site its key authenticated."""
+        default_before = self.default_dedupe_key(self.source.system, self.code, self.site_slug)
+        dedupe_key = self.default_dedupe_key(self.source.system, self.code, site_slug) \
+            if self.dedupe_key == default_before else self.dedupe_key
+        return self.model_copy(update={
+            "site_slug": site_slug, "org_slug": org_slug or self.org_slug, "dedupe_key": dedupe_key,
+        })
+
+    @property
+    def topic(self) -> str:
+        """The stream topic: `{system}/{code}`, so a consumer can subscribe by either."""
+        return f"{self.source.system}/{self.code}"
+
+    def to_json(self) -> str:
+        return self.model_dump_json()
+
+    @classmethod
+    def from_json(cls, payload: Union[str, bytes, dict]) -> "AnomalyEvent":
+        if isinstance(payload, dict):
+            return cls.model_validate(payload)
+        return cls.model_validate_json(payload)
+
+
+def is_valid_code(code: str) -> bool:
+    return re.match(CODE_PATTERN, code or "") is not None

zen_anomaly_client-0.1.0/src/zen_anomaly_client.egg-info/PKG-INFO

@@ -0,0 +1,69 @@
+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).

zen_anomaly_client-0.1.0/src/zen_anomaly_client.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+LICENSE.md
+README.md
+pyproject.toml
+src/zen_anomaly_client/__init__.py
+src/zen_anomaly_client/codes.py
+src/zen_anomaly_client/contract.py
+src/zen_anomaly_client.egg-info/PKG-INFO
+src/zen_anomaly_client.egg-info/SOURCES.txt
+src/zen_anomaly_client.egg-info/dependency_links.txt
+src/zen_anomaly_client.egg-info/requires.txt
+src/zen_anomaly_client.egg-info/top_level.txt
+tests/test_contract.py

zen_anomaly_client-0.1.0/src/zen_anomaly_client.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

zen_anomaly_client-0.1.0/src/zen_anomaly_client.egg-info/requires.txt

@@ -0,0 +1,4 @@
+pydantic<3,>=2.5
+
+[dev]
+pytest>=7

zen_anomaly_client-0.1.0/src/zen_anomaly_client.egg-info/top_level.txt

@@ -0,0 +1 @@
+zen_anomaly_client

zen_anomaly_client-0.1.0/tests/test_contract.py

@@ -0,0 +1,205 @@
+import json
+import uuid
+from datetime import datetime, timedelta, timezone
+
+import pytest
+from pydantic import ValidationError
+
+from zen_anomaly_client import (
+    ANOMALY_SCHEMA_VERSION, AnomalyEvent, AnomalySource, Category, Severity, codes, severity_at_least,
+)
+from zen_anomaly_client.contract import (
+    DEDUPE_KEY_MAX_CHARS, DETAILS_MAX_KEYS, DETAILS_MAX_VALUE_CHARS, MESSAGE_MAX_CHARS, TRUNCATION_MARK, is_valid_code,
+)
+
+
+def _event(**overrides):
+    base = dict(
+        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",
+        details={"file": "w_Gil_camera0_20261112120001.mp4", "size": 12345, "attempt": 3},
+    )
+    base.update(overrides)
+    return AnomalyEvent(**base)
+
+
+class TestRequiredAndDefaults:
+
+    def test_minimal_event_gets_id_timestamp_version_and_dedupe_key(self):
+        event = AnomalyEvent(source=AnomalySource(system="api"), category=Category.JOB,
+                             code=codes.API_JOB_FAILED, severity=Severity.ERROR, message="job raised")
+        assert isinstance(event.id, uuid.UUID)
+        assert event.occurred_at.tzinfo is timezone.utc
+        assert event.schema_version == ANOMALY_SCHEMA_VERSION
+        assert event.dedupe_key == "api:api.job.failed:-"
+        assert event.details == {}
+        assert event.site_slug is None and event.org_slug is None
+
+    @pytest.mark.parametrize("missing", ["source", "category", "code", "severity", "message"])
+    def test_each_required_field_is_required(self, missing):
+        fields = dict(source=AnomalySource(system="api"), category=Category.JOB, code=codes.API_JOB_FAILED,
+                      severity=Severity.ERROR, message="x")
+        del fields[missing]
+        with pytest.raises(ValidationError):
+            AnomalyEvent(**fields)
+
+    def test_unknown_fields_are_rejected(self):
+        with pytest.raises(ValidationError):
+            AnomalyEvent(source=AnomalySource(system="api"), category=Category.JOB, code=codes.API_JOB_FAILED,
+                         severity=Severity.ERROR, message="x", extra_field=1)
+
+    def test_dedupe_key_includes_the_site_and_an_explicit_key_wins(self):
+        assert _event().dedupe_key == "edge:edge.upload.failed:gil"
+        assert _event(dedupe_key="custom").dedupe_key == "custom"
+        with pytest.raises(ValidationError):
+            _event(dedupe_key="k" * (DEDUPE_KEY_MAX_CHARS + 1))
+
+    def test_with_site_pins_slug_and_follows_default_dedupe_key(self):
+        unpinned = AnomalyEvent(source=AnomalySource(system="edge"), category=Category.UPLOAD,
+                                code=codes.EDGE_UPLOAD_FAILED, severity=Severity.WARNING, message="x")
+        pinned = unpinned.with_site("gil", org_slug="acme")
+        assert (pinned.site_slug, pinned.org_slug) == ("gil", "acme")
+        assert pinned.dedupe_key == "edge:edge.upload.failed:gil"
+        assert pinned.id == unpinned.id and unpinned.site_slug is None
+        explicit = _event(dedupe_key="mine").with_site("other")
+        assert explicit.dedupe_key == "mine" and explicit.site_slug == "other"
+        repinned = _event().with_site("other")
+        assert repinned.dedupe_key == "edge:edge.upload.failed:other" and repinned.org_slug is None
+
+    def test_topic_is_system_slash_code(self):
+        assert _event().topic == "edge/edge.upload.failed"
+
+
+class TestCodes:
+
+    @pytest.mark.parametrize("code", [
+        "edge.upload.failed", "api.job.failed", "router.consumer.stopped", "a.b", "lambda.redis.push_failed",
+        "x.y.z.w",
+    ])
+    def test_valid_codes(self, code):
+        assert is_valid_code(code)
+        assert _event(code=code).code == code
+
+    @pytest.mark.parametrize("code", [
+        "edge", "Edge.upload", "edge..upload", ".edge.upload", "edge.upload.", "edge upload", "edge.Upload.failed",
+        "1edge.upload", "a.b.c.d.e", "",
+    ])
+    def test_invalid_codes_are_rejected(self, code):
+        assert not is_valid_code(code)
+        with pytest.raises(ValidationError):
+            _event(code=code)
+
+    def test_every_catalogue_code_is_valid_and_has_info(self):
+        for code, entry in codes.CATALOGUE.items():
+            assert is_valid_code(code), code
+            assert isinstance(entry.category, Category)
+            assert isinstance(entry.severity, Severity)
+            assert entry.description
+        assert codes.consumer_stopped("router") in codes.CATALOGUE
+        assert codes.info("not.listed").description == "Unlisted code."
+
+
+class TestEnumsAndSeverity:
+
+    def test_severity_and_category_accept_their_string_values(self):
+        event = _event(severity="critical", category="edge-service")
+        assert event.severity is Severity.CRITICAL
+        assert event.category is Category.EDGE_SERVICE
+
+    @pytest.mark.parametrize("value", ["fatal", "WARNING", "", None])
+    def test_bad_severity_rejected(self, value):
+        with pytest.raises(ValidationError):
+            _event(severity=value)
+
+    def test_bad_category_rejected(self):
+        with pytest.raises(ValidationError):
+            _event(category="video")
+
+    def test_severity_ordering(self):
+        assert severity_at_least(Severity.ERROR, Severity.ERROR)
+        assert severity_at_least(Severity.CRITICAL, Severity.ERROR)
+        assert not severity_at_least(Severity.WARNING, Severity.ERROR)
+        assert severity_at_least("warning", "info")
+
+
+class TestBounds:
+
+    def test_message_is_stripped_and_truncated_not_rejected(self):
+        assert _event(message="  spaced  ").message == "spaced"
+        long = "m" * (MESSAGE_MAX_CHARS + 50)
+        truncated = _event(message=long).message
+        assert len(truncated) == MESSAGE_MAX_CHARS and truncated.endswith(TRUNCATION_MARK)
+
+    def test_empty_message_rejected(self):
+        with pytest.raises(ValidationError):
+            _event(message="   ")
+
+    def test_details_too_many_keys_rejected(self):
+        with pytest.raises(ValidationError):
+            _event(details={f"k{i}": i for i in range(DETAILS_MAX_KEYS + 1)})
+        assert len(_event(details={f"k{i}": i for i in range(DETAILS_MAX_KEYS)}).details) == DETAILS_MAX_KEYS
+
+    def test_details_nested_values_rejected(self):
+        with pytest.raises(ValidationError):
+            _event(details={"nested": {"a": 1}})
+        with pytest.raises(ValidationError):
+            _event(details={"list": [1, 2]})
+
+    def test_details_long_strings_truncated(self):
+        tail = "t" * (DETAILS_MAX_VALUE_CHARS * 3)
+        value = _event(details={"traceback": tail}).details["traceback"]
+        assert len(value) == DETAILS_MAX_VALUE_CHARS and value.endswith(TRUNCATION_MARK)
+
+    def test_details_scalars_kept_as_is(self):
+        details = _event(details={"n": 1, "f": 1.5, "b": True, "none": None, "s": "x"}).details
+        assert details == {"n": 1, "f": 1.5, "b": True, "none": None, "s": "x"}
+
+    def test_details_none_becomes_empty(self):
+        assert _event(details=None).details == {}
+
+    @pytest.mark.parametrize("slug", ["Gil", "gil pad", "-gil", ""])
+    def test_bad_slugs_rejected(self, slug):
+        with pytest.raises(ValidationError):
+            _event(site_slug=slug)
+
+    def test_bad_system_rejected(self):
+        with pytest.raises(ValidationError):
+            AnomalySource(system="Edge Box")
+
+
+class TestTimestamps:
+
+    def test_naive_timestamp_is_taken_as_utc(self):
+        naive = datetime(2026, 11, 12, 12, 0, 1)
+        assert _event(occurred_at=naive).occurred_at == datetime(2026, 11, 12, 12, 0, 1, tzinfo=timezone.utc)
+
+    def test_aware_timestamp_is_converted_to_utc(self):
+        cst = timezone(timedelta(hours=-6))
+        event = _event(occurred_at=datetime(2026, 11, 12, 6, 0, 1, tzinfo=cst))
+        assert event.occurred_at == datetime(2026, 11, 12, 12, 0, 1, tzinfo=timezone.utc)
+
+
+class TestRoundTrip:
+
+    def test_json_round_trip_is_lossless(self):
+        event = _event()
+        copy = AnomalyEvent.from_json(event.to_json())
+        assert copy == event
+        assert copy.id == event.id
+
+    def test_from_json_accepts_dict_and_bytes(self):
+        event = _event()
+        as_dict = json.loads(event.to_json())
+        assert AnomalyEvent.from_json(as_dict) == event
+        assert AnomalyEvent.from_json(event.to_json().encode()) == event
+
+    def test_json_has_the_wire_shape(self):
+        payload = json.loads(_event().to_json())
+        assert set(payload) == {"schema_version", "id", "occurred_at", "source", "org_slug", "site_slug", "category",
+                                "code", "severity", "message", "details", "dedupe_key"}
+        assert payload["severity"] == "warning" and payload["category"] == "upload"
+        assert payload["occurred_at"].endswith("Z") or "+00:00" in payload["occurred_at"]