diff --git a/README.md b/README.md index 0bbf313..0d31e1a 100644 --- a/README.md +++ b/README.md @@ -8,3 +8,8 @@ A minimal MVP scaffold for PulseMesh Open Telemetry Visualization A. This repository is structured to be Python-package friendly. The packaging config in pyproject.toml targets a standard PEP 517 build flow using setuptools. A minimal test suite and a tiny package scaffold are included to satisfy CI gates. + +Phase 0 MVP: Protocol Skeleton +- Introduced a lightweight protocol module (protocol.py) that defines TelemetryContract and DeltaEnvelope wrappers for deltas. +- Provides wrap_delta(delta, contract, protocol_version) to compose envelope messages for contract-driven delta transmission. +- Exposes TelemetryContract, DeltaEnvelope, and wrap_delta via the package root for experimentation and future adapters. diff --git a/src/pulsemesh_open_telemetry_visualization_a/__init__.py b/src/pulsemesh_open_telemetry_visualization_a/__init__.py index 15882b2..b0174e7 100644 --- a/src/pulsemesh_open_telemetry_visualization_a/__init__.py +++ b/src/pulsemesh_open_telemetry_visualization_a/__init__.py @@ -3,5 +3,7 @@ PulseMesh Open Telemetry Visualization A - minimal package scaffold. This file exists to satisfy packaging/build in the MVP. """ -__all__ = ["__version__"] +from .protocol import TelemetryContract, DeltaEnvelope, wrap_delta + +__all__ = ["__version__", "TelemetryContract", "DeltaEnvelope", "wrap_delta"] __version__ = "0.1.0" diff --git a/src/pulsemesh_open_telemetry_visualization_a/protocol.py b/src/pulsemesh_open_telemetry_visualization_a/protocol.py new file mode 100644 index 0000000..14194bf --- /dev/null +++ b/src/pulsemesh_open_telemetry_visualization_a/protocol.py @@ -0,0 +1,50 @@ +from __future__ import annotations + +from dataclasses import dataclass, asdict +from typing import List, Dict, Any +import json + +from .delta import Delta +from .telemetry import TelemetrySample + + +@dataclass +class TelemetryContract: + contract_id: str + device_type: str + metrics: List[str] + units: Dict[str, str] # metric -> unit + quality_flags: List[str] + version: int + + def to_dict(self) -> Dict[str, Any]: + return asdict(self) + + def to_json(self) -> str: + return json.dumps(self.to_dict()) + + +@dataclass +class DeltaEnvelope: + protocol_version: str + contract: TelemetryContract + delta: Delta + + def to_dict(self) -> Dict[str, Any]: + return { + "protocol_version": self.protocol_version, + "contract": self.contract.to_dict(), + "delta": self.delta.to_dict(), + } + + def to_json(self) -> str: + return json.dumps(self.to_dict()) + + +def wrap_delta(delta: Delta, contract: TelemetryContract, protocol_version: str = "PulseMesh/0.1.0") -> DeltaEnvelope: + """Wrap a Delta into a DeltaEnvelope with contract metadata. + + This is a light-weight protocol scaffold for Phase 0 MVP to enable + contract-driven delta transmission without coupling to a full runtime. + """ + return DeltaEnvelope(protocol_version=protocol_version, contract=contract, delta=delta)