pulse-data 0.2.2__py3-none-any.whl

inventzia/pulse/data/__init__.py

@@ -0,0 +1,19 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later OR LicenseRef-Inventzia-Commercial
+# Copyright (c) 2013-2026 Magrino Bini, Paola Apruzzese, Inventzia Science and Technology Ltd.
+#
+# This file is part of pulse-data.
+#
+# pulse-data is dual-licensed:
+#   - Under the GNU Affero General Public License v3.0 or later (see LICENSE-AGPL-3.0).
+#   - Under a commercial license (see LICENSE-COMMERCIAL.txt).
+#     Contact operations@inventzia.com.
+"""pulse-data: the Datum routing contract and generated event schemas.
+
+See the :mod:`inventzia.pulse.data.datum` subpackage for the ``Datum`` protocol
+and JSON codecs, and ``inventzia.pulse.data.schemas`` for the generated models.
+
+``inventzia`` and ``inventzia.pulse`` are deliberately PEP 420 namespace packages
+(no ``__init__.py``) so pulse-data and pulse-beacon can share the
+``inventzia.pulse.*`` prefix and install side by side; from here inward the
+hand-written packages are regular packages with deliberate exports.
+"""

inventzia/pulse/data/datum/__init__.py

@@ -0,0 +1,29 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later OR LicenseRef-Inventzia-Commercial
+# Copyright (c) 2013-2026 Magrino Bini, Paola Apruzzese, Inventzia Science and Technology Ltd.
+#
+# This file is part of pulse-data.
+#
+# pulse-data is dual-licensed:
+#   - Under the GNU Affero General Public License v3.0 or later (see LICENSE-AGPL-3.0).
+#   - Under a commercial license (see LICENSE-COMMERCIAL.txt).
+#     Contact operations@inventzia.com.
+"""The Datum routing contract and its JSON / tagged-JSON codecs.
+
+    from inventzia.pulse.data.datum import Datum, to_tagged_json, from_tagged_json
+"""
+
+from inventzia.pulse.data.datum.datum import Datum
+from inventzia.pulse.data.datum.codec import (
+    from_json,
+    from_tagged_json,
+    to_json,
+    to_tagged_json,
+)
+
+__all__ = [
+    "Datum",
+    "to_json",
+    "from_json",
+    "to_tagged_json",
+    "from_tagged_json",
+]

inventzia/pulse/data/datum/codec.py

@@ -0,0 +1,94 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later OR LicenseRef-Inventzia-Commercial
+# Copyright (c) 2013-2026 Magrino Bini, Paola Apruzzese, Inventzia Science and Technology Ltd.
+#
+# This file is part of pulse-data.
+#
+# pulse-data is dual-licensed:
+#   - Under the GNU Affero General Public License v3.0 or later (see LICENSE-AGPL-3.0).
+#   - Under a commercial license (see LICENSE-COMMERCIAL.txt).
+#     Contact operations@inventzia.com.
+"""
+The Python counterpart of the Java ``DatumCodec``.
+
+pulse-data owns how a :class:`~inventzia.pulse.data.datum.datum.Datum` becomes
+JSON in *both* languages, so a value produced in one is consumed verbatim in the
+other. Pydantic does the field-level (de)serialisation; this module adds the two
+forms the transport layer uses:
+
+* **type-directed** — :func:`to_json` / :func:`from_json`, when the caller knows
+  the concrete model class (e.g. it knows the topic's payload type);
+* **self-describing (tagged)** — :func:`to_tagged_json` / :func:`from_tagged_json`,
+  which embed the ``TYPE_ID`` in a small envelope so a receiver can recover the
+  type from the message itself. Required wherever the type is not known ahead of
+  time: the in-process cross-language bridge, and later the socket/ZMQ transport.
+  The type is resolved through the composite
+  :mod:`inventzia.pulse.data.datum.registry` (the mirror of Java's
+  ``DatumTypeRegistry``). The tagged functions default to the process-wide registry;
+  pass ``registry=`` (or use :class:`TaggedCodec`) to bind an isolated one in tests.
+
+The tagged envelope is identical to the Java side::
+
+    {"typeId": "<TYPE_ID>", "payload": { ...fields... }}
+"""
+
+import json
+from typing import Optional, TypeVar
+
+from inventzia.pulse.data.datum.registry import Registry, default_registry
+
+_FIELD_TYPE_ID = "typeId"
+_FIELD_PAYLOAD = "payload"
+
+T = TypeVar("T")
+
+
+def to_json(datum) -> str:
+    """Serialise a datum to a single-line JSON string (flat, field names = wire names).
+
+    ``exclude_none=True`` omits absent optional fields, matching the Java codec's
+    ``@JsonInclude(NON_NULL)`` so the two languages produce identical envelopes.
+    """
+    return datum.model_dump_json(by_alias=True, exclude_none=True)
+
+
+def from_json(json_str: str, model_class: type[T]) -> T:
+    """Deserialise a JSON string into the given model class."""
+    return model_class.model_validate_json(json_str)
+
+
+def to_tagged_json(datum, registry: Optional[Registry] = None) -> str:
+    """Serialise a datum to the self-describing envelope ``{"typeId", "payload"}``.
+
+    ``registry`` defaults to the process-wide composite registry; pass an isolated one
+    (from ``build_registry``) to encode against a custom type universe.
+    """
+    reg = registry if registry is not None else default_registry()
+    payload = json.loads(datum.model_dump_json(by_alias=True, exclude_none=True))
+    return json.dumps({_FIELD_TYPE_ID: reg.type_id_of(datum), _FIELD_PAYLOAD: payload})
+
+
+def from_tagged_json(json_str: str, registry: Optional[Registry] = None):
+    """Deserialise a tagged envelope, recovering the concrete type from its ``typeId``.
+
+    ``registry`` defaults to the process-wide composite registry.
+    """
+    reg = registry if registry is not None else default_registry()
+    envelope = json.loads(json_str)
+    type_id = envelope.get(_FIELD_TYPE_ID)
+    if not isinstance(type_id, str):
+        raise ValueError(f"Tagged JSON missing textual {_FIELD_TYPE_ID!r}: {json_str}")
+    model_class = reg.class_for(type_id)
+    return model_class.model_validate(envelope.get(_FIELD_PAYLOAD))
+
+
+class TaggedCodec:
+    """A tagged codec bound to a specific :class:`Registry` (for tests / isolated universes)."""
+
+    def __init__(self, registry: Registry):
+        self._registry = registry
+
+    def to_tagged_json(self, datum) -> str:
+        return to_tagged_json(datum, self._registry)
+
+    def from_tagged_json(self, json_str: str):
+        return from_tagged_json(json_str, self._registry)

inventzia/pulse/data/datum/datum.py

@@ -0,0 +1,50 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later OR LicenseRef-Inventzia-Commercial
+# Copyright (c) 2013-2026 Magrino Bini, Paola Apruzzese, Inventzia Science and Technology Ltd.
+#
+# This file is part of pulse-data.
+#
+# pulse-data is dual-licensed:
+#   - Under the GNU Affero General Public License v3.0 or later (see LICENSE-AGPL-3.0).
+#   - Under a commercial license (see LICENSE-COMMERCIAL.txt).
+#     Contact operations@inventzia.com.
+"""
+Routing contract for all data types transported on the pulse-beacon bus.
+
+Python equivalent of the Java ``Datum`` interface.  Uses structural typing
+(``Protocol``) so generated Pydantic models satisfy the contract without
+explicit inheritance — they simply need ``datum_key`` and ``datum_time``
+properties.
+"""
+
+from typing import Protocol, runtime_checkable
+
+
+@runtime_checkable
+class Datum(Protocol):
+    """
+    Every generated schema class satisfies this protocol by exposing
+    ``datum_key`` and ``datum_time`` properties whose implementations
+    are generated from the ``x-datum-key`` and ``x-datum-time`` YAML
+    annotations on the source schema.
+
+    In Python the contract is structural: no explicit ``implements`` is
+    needed.  The pulse-beacon Python infrastructure reads these properties
+    by duck typing.
+    """
+
+    @property
+    def datum_key(self) -> str:
+        """
+        The routing key for this datum instance — e.g. an instrument
+        symbol, session ID, or tenant.  Never ``None``; return an empty
+        string when no key applies.
+        """
+        ...
+
+    @property
+    def datum_time(self) -> int:
+        """
+        The logical time of this datum in epoch milliseconds — when the
+        underlying event occurred, not when it was published or received.
+        """
+        ...

inventzia/pulse/data/datum/provider.py

@@ -0,0 +1,67 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later OR LicenseRef-Inventzia-Commercial
+# Copyright (c) 2013-2026 Magrino Bini, Paola Apruzzese, Inventzia Science and Technology Ltd.
+#
+# This file is part of pulse-data.
+#
+# pulse-data is dual-licensed:
+#   - Under the GNU Affero General Public License v3.0 or later (see LICENSE-AGPL-3.0).
+#   - Under a commercial license (see LICENSE-COMMERCIAL.txt).
+#     Contact operations@inventzia.com.
+"""The datum-type service-provider interface (SPI).
+
+Each package that contributes routed :class:`Datum` types (pulse-data itself, and
+independent extensions such as an adapter) publishes a :class:`DatumTypeProvider`.
+A provider is pure declarative metadata plus binding descriptors, discovered once and
+composed into an immutable registry (see :mod:`inventzia.pulse.data.datum.registry`).
+Provider construction and loading must have no network, authentication, or gateway
+side effects.
+
+Extensions register a provider through the ``inventzia.pulse.datum_types`` packaging
+entry-point group, whose value is a public zero-argument provider class; the registry
+instantiates it exactly once. The core provider is generated and seeded directly, not
+discovered.
+"""
+
+from dataclasses import dataclass
+from typing import Optional, Protocol, runtime_checkable
+
+#: The SPI contract version this pulse-data implements. Providers must match it exactly.
+SPI_VERSION = 1
+
+
+@dataclass(frozen=True)
+class DatumTypeBinding:
+    """One contributed type: its ``TYPE_ID``, ``TYPE_VERSION``, and model class.
+
+    Built from the class's own constants (``Model.TYPE_ID`` / ``Model.TYPE_VERSION``),
+    so nothing is duplicated. Mirrors the Java ``DatumTypeBinding`` record.
+    """
+
+    type_id: str
+    type_version: int
+    datum_class: type
+
+
+@runtime_checkable
+class DatumTypeProvider(Protocol):
+    """Declares a set of :class:`Datum` types contributed by one package."""
+
+    def provider_id(self) -> str:
+        """Reverse-DNS namespace root; every contributed ``TYPE_ID`` starts with it + '.'."""
+        ...
+
+    def spi_version(self) -> int:
+        """The SPI contract version this provider was built against."""
+        ...
+
+    def package_version(self) -> str:
+        """The contributing distribution's version (informational; baked at build time)."""
+        ...
+
+    def bindings(self) -> "list[DatumTypeBinding]":
+        """The type bindings this provider contributes."""
+        ...
+
+    def manifest(self) -> Optional[str]:
+        """Reserved for Phase 2 (schema-manifest fingerprinting). ``None`` in Phase 1."""
+        ...

inventzia/pulse/data/datum/registry.py

@@ -0,0 +1,269 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later OR LicenseRef-Inventzia-Commercial
+# Copyright (c) 2013-2026 Magrino Bini, Paola Apruzzese, Inventzia Science and Technology Ltd.
+#
+# This file is part of pulse-data.
+#
+# pulse-data is dual-licensed:
+#   - Under the GNU Affero General Public License v3.0 or later (see LICENSE-AGPL-3.0).
+#   - Under a commercial license (see LICENSE-COMMERCIAL.txt).
+#     Contact operations@inventzia.com.
+"""The composite datum-type registry: TYPE_ID <-> model class.
+
+Built once from the core provider (seeded directly) plus discovered extension
+providers, validated, then frozen. The tagged codec resolves types through it. This is
+hand-written infrastructure; the per-provider bindings are generated. Mirror of the Java
+``DatumTypeRegistry``.
+"""
+
+import hashlib
+import re
+import threading
+from dataclasses import dataclass
+from importlib.metadata import entry_points
+
+import pydantic
+
+from inventzia.pulse.data.datum.provider import SPI_VERSION, DatumTypeBinding, DatumTypeProvider
+
+_ENTRY_POINT_GROUP = "inventzia.pulse.datum_types"
+_ID_RE = re.compile(r"[A-Za-z0-9_]+(\.[A-Za-z0-9_]+)+")   # reverse-DNS-ish: dotted segments
+_HEX64 = re.compile(r"[0-9a-f]{64}")
+_MANIFEST_FORMAT = "pdm1"
+
+
+@dataclass(frozen=True)
+class ProviderInfo:
+    """Retained, immutable metadata for one contributing provider (for diagnostics / audit)."""
+
+    provider_id: str
+    package_version: str
+    manifest: "str | None"                       # canonical pdm1 string, or None (unverifiable)
+    entries: "tuple | None"                      # ((type_id, type_version, fingerprint), ...) or None
+
+
+class Registry:
+    """An immutable TYPE_ID <-> class registry. Build via :func:`build_registry`."""
+
+    __slots__ = ("_by_id", "_by_class", "_providers")
+
+    def __init__(self, by_id: dict, by_class: dict, providers: tuple):
+        self._by_id = by_id
+        self._by_class = by_class
+        self._providers = providers
+
+    def providers(self) -> tuple:
+        """Immutable :class:`ProviderInfo` snapshot for every contributing provider, in order."""
+        return self._providers
+
+    def unverifiable_providers(self) -> tuple:
+        """Provider IDs with no manifest (predating Phase 2); a fingerprint cannot include them."""
+        return tuple(pi.provider_id for pi in self._providers if pi.manifest is None)
+
+    def fingerprint(self) -> "str | None":
+        """SHA-256 hex of the providers' manifests (sorted by provider_id), or None if any is absent.
+
+        None means at least one provider is unverifiable (see :meth:`unverifiable_providers`);
+        the cross-language bridge treats that as fail-closed.
+        """
+        if any(pi.manifest is None for pi in self._providers):
+            return None
+        joined = "\n".join(pi.manifest for pi in sorted(self._providers, key=lambda pi: pi.provider_id))
+        return hashlib.sha256(joined.encode("utf-8")).hexdigest()
+
+    def class_for(self, type_id: str) -> type:
+        """Return the model class registered for a TYPE_ID."""
+        try:
+            return self._by_id[type_id]
+        except KeyError:
+            raise KeyError(f"Unknown TYPE_ID: {type_id!r}") from None
+
+    def type_id_of(self, datum) -> str:
+        """Return the TYPE_ID of a datum, verified against the registry.
+
+        Encoding must not emit a tagged envelope for a class that is not the registered
+        binding for its declared TYPE_ID, or a receiver could get a typeId no runtime can
+        decode. Mirrors the Java ``DatumTypeRegistry.typeIdOf`` check.
+        """
+        cls = type(datum)
+        type_id = self._by_class.get(cls)
+        if type_id is None:
+            raise KeyError(f"Unregistered datum type: {cls.__name__}")
+        return type_id
+
+
+def _fail(msg: str) -> "None":
+    raise ValueError(f"invalid datum-type registry: {msg}")
+
+
+def _validate_class(provider_id: str, b: DatumTypeBinding) -> None:
+    cls = b.datum_class
+    if cls is None:
+        _fail(f"provider '{provider_id}' has a binding with no class")
+    if not isinstance(cls, type) or not issubclass(cls, pydantic.BaseModel):
+        _fail(f"provider '{provider_id}' type '{b.type_id}': class {cls!r} is not a pydantic BaseModel "
+              "(the codec calls model_validate_json / model_dump_json)")
+    for prop in ("datum_key", "datum_time"):
+        if not hasattr(cls, prop):
+            _fail(f"provider '{provider_id}' type '{b.type_id}': class {cls.__name__} lacks '{prop}'")
+    cls_type_id = getattr(cls, "TYPE_ID", None)
+    if cls_type_id != b.type_id:
+        _fail(f"provider '{provider_id}': binding type_id '{b.type_id}' does not match "
+              f"{cls.__name__}.TYPE_ID {cls_type_id!r} (descriptor drift)")
+    tv = b.type_version
+    if type(tv) is not int or tv <= 0:
+        _fail(f"provider '{provider_id}' type '{b.type_id}': TYPE_VERSION must be a positive int, got {tv!r}")
+    cls_type_version = getattr(cls, "TYPE_VERSION", None)
+    if cls_type_version != tv:
+        _fail(f"provider '{provider_id}' type '{b.type_id}': binding type_version {tv} does not match "
+              f"{cls.__name__}.TYPE_VERSION {cls_type_version!r} (descriptor drift)")
+
+
+def _parse_manifest(provider, bindings) -> ProviderInfo:
+    """Parse and validate a provider's baked manifest against its bindings (see the SPI spec)."""
+    pid = provider.provider_id()
+    m = provider.manifest()
+    if m is None:
+        return ProviderInfo(pid, provider.package_version(), None, None)
+    if "\n" in m or "\r" in m:
+        _fail(f"provider '{pid}' manifest contains a newline")
+    parts = m.split("|")
+    if len(parts) != 3 or parts[0] != _MANIFEST_FORMAT:
+        _fail(f"provider '{pid}' manifest is not a {_MANIFEST_FORMAT} manifest")
+    _, embedded_pid, body = parts
+    if embedded_pid != pid:
+        _fail(f"provider '{pid}' manifest embeds provider id '{embedded_pid}'")
+
+    entries = []
+    type_ids = []
+    if body:
+        for entry in body.split(";"):
+            fields = entry.split(":")
+            if len(fields) != 3:
+                _fail(f"provider '{pid}' manifest has a malformed entry '{entry}'")
+            tid, ver_s, fp = fields
+            if not _HEX64.fullmatch(fp):
+                _fail(f"provider '{pid}' type '{tid}': fingerprint is not 64 lowercase hex")
+            try:
+                ver = int(ver_s)
+            except ValueError:
+                _fail(f"provider '{pid}' type '{tid}': non-integer version '{ver_s}'")
+            entries.append((tid, ver, fp))
+            type_ids.append(tid)
+    if type_ids != sorted(type_ids):
+        _fail(f"provider '{pid}' manifest entries are not sorted by TYPE_ID")
+    if len(set(type_ids)) != len(type_ids):
+        _fail(f"provider '{pid}' manifest has duplicate entries")
+
+    binding_ver = {b.type_id: b.type_version for b in bindings}
+    entry_ver = {tid: ver for (tid, ver, _) in entries}
+    if set(binding_ver) != set(entry_ver):
+        _fail(f"provider '{pid}' manifest does not match its bindings one-to-one")
+    for tid, ver in entry_ver.items():
+        if binding_ver[tid] != ver:
+            _fail(f"provider '{pid}' type '{tid}': manifest version {ver} != binding version {binding_ver[tid]}")
+    return ProviderInfo(pid, provider.package_version(), m, tuple(entries))
+
+
+def build_registry(providers) -> Registry:
+    """Validate ``providers`` and build an immutable composite registry.
+
+    ``providers`` is an ordered iterable of :class:`DatumTypeProvider` (core first). The
+    validation rejects, with the offending provider/type named: null providers or bindings;
+    empty or malformed provider / type IDs; blank package versions; an SPI version mismatch;
+    an empty provider; a class that is not a valid pydantic datum; TYPE_VERSION that is not a
+    positive int; a TYPE_ID outside ``provider_id + '.'``; a duplicate class within a provider;
+    a duplicate TYPE_ID across providers; and a class bound to more than one TYPE_ID.
+    """
+    by_id: dict = {}
+    by_class: dict = {}
+    seen_provider_ids: set = set()
+    provider_infos: list = []
+
+    for provider in providers:
+        if provider is None:
+            _fail("a provider is None")
+        pid = provider.provider_id()
+        if not pid or not pid.strip() or not _ID_RE.fullmatch(pid):
+            _fail(f"provider has an empty or malformed provider_id: {pid!r}")
+        if pid in seen_provider_ids:
+            _fail(f"duplicate provider_id '{pid}'")
+        seen_provider_ids.add(pid)
+        if provider.spi_version() != SPI_VERSION:
+            _fail(f"provider '{pid}' targets SPI version {provider.spi_version()}, "
+                  f"this pulse-data supports {SPI_VERSION}")
+        pv = provider.package_version()
+        if not pv or not pv.strip():
+            _fail(f"provider '{pid}' has a missing or blank package_version")
+
+        bindings = provider.bindings()
+        if bindings is None:
+            _fail(f"provider '{pid}' returned no bindings collection")
+        bindings = sorted(bindings, key=lambda b: (b.type_id or ""))
+        if not bindings:
+            _fail(f"provider '{pid}' contributes no datum types")
+
+        provider_classes: set = set()
+        for b in bindings:
+            if b is None:
+                _fail(f"provider '{pid}' has a None binding")
+            if not b.type_id or not b.type_id.strip():
+                _fail(f"provider '{pid}' has an empty or malformed type_id")
+            if not b.type_id.startswith(pid + "."):
+                _fail(f"provider '{pid}' type '{b.type_id}' is not under its namespace '{pid}.'")
+            _validate_class(pid, b)
+            if b.datum_class in provider_classes:
+                _fail(f"provider '{pid}' binds class {b.datum_class.__name__} more than once")
+            provider_classes.add(b.datum_class)
+            if b.type_id in by_id:
+                _fail(f"duplicate TYPE_ID '{b.type_id}' (provider '{pid}' conflicts with an earlier provider)")
+            if b.datum_class in by_class:
+                _fail(f"class {b.datum_class.__name__} is bound to more than one TYPE_ID")
+            by_id[b.type_id] = b.datum_class
+            by_class[b.datum_class] = b.type_id
+
+        provider_infos.append(_parse_manifest(provider, bindings))
+
+    return Registry(by_id, by_class, tuple(provider_infos))
+
+
+def _discover_providers() -> list:
+    """Seed the core provider directly, then discover extension providers.
+
+    Core is instantiated directly (never via discovery), so a source-tree or mis-packaged
+    install cannot lose its core types and core-only parity is guaranteed. Extensions are
+    loaded from the entry-point group and sorted by provider_id for determinism.
+    """
+    from inventzia.pulse.data.schemas.provider import CoreDatumTypeProvider
+
+    providers = [CoreDatumTypeProvider()]
+    extensions = []
+    for ep in entry_points(group=_ENTRY_POINT_GROUP):
+        provider_cls = ep.load()   # entry point resolves to the class, not an instance
+        extensions.append(provider_cls())
+    extensions.sort(key=lambda p: p.provider_id())
+    providers.extend(extensions)
+    return providers
+
+
+_default_lock = threading.Lock()
+_default_registry: "Registry | None" = None
+
+
+def default_registry() -> Registry:
+    """The process-wide composite registry, built once (lazily) and frozen."""
+    global _default_registry
+    if _default_registry is None:
+        with _default_lock:
+            if _default_registry is None:
+                _default_registry = build_registry(_discover_providers())
+    return _default_registry
+
+
+def class_for(type_id: str) -> type:
+    """Facade over :func:`default_registry`: TYPE_ID -> model class."""
+    return default_registry().class_for(type_id)
+
+
+def type_id_of(datum) -> str:
+    """Facade over :func:`default_registry`: verified TYPE_ID of a datum."""
+    return default_registry().type_id_of(datum)

inventzia/pulse/data/schemas/common/vector_value.py

@@ -0,0 +1,56 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later OR LicenseRef-Inventzia-Commercial
+# Copyright (c) 2013-2026 Magrino Bini, Paola Apruzzese, Inventzia Science and Technology Ltd.
+#
+# This file is part of pulse-data.
+#
+# pulse-data is dual-licensed:
+#   - Under the GNU Affero General Public License v3.0 or later (see LICENSE-AGPL-3.0).
+#   - Under a commercial license (see LICENSE-COMMERCIAL.txt).
+#     Contact operations@inventzia.com.
+#
+# THIS FILE IS GENERATED. DO NOT EDIT MANUALLY.
+# Source: schemas_yaml/common/vector_value.yaml
+# Regenerate: python schemas/schemas-generators/generate_python.py
+
+from __future__ import annotations
+from decimal import Decimal
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+from typing import ClassVar, Optional
+
+
+class VectorValue(BaseModel):
+    """
+    A generic timestamped vector of scalar observations, optionally labelled. A scalar value is simply the length-1 case. Suited to indicators that emit M components per timestamp (e.g. MACD -> [macd, signal, histogram]).
+    """
+
+    model_config = ConfigDict(extra="ignore", frozen=True)
+
+    TYPE_ID:      ClassVar[str] = "com.inventzia.pulse.data.schemas.common.VectorValue"
+    TYPE_VERSION: ClassVar[int] = 1
+
+    key: str
+    """The series or observation-source identifier"""
+    time: int
+    """Epoch milliseconds of the observation"""
+    values: tuple[Decimal, ...]
+    """The M scalar observations (length 1 for a scalar value)"""
+
+    value_ids: Optional[tuple[str, ...]] = Field(None, alias="valueIds")
+    """Optional labels, parallel to values (positional if absent)"""
+
+    @model_validator(mode="after")
+    def _check_parallel_lengths(self):
+        if self.value_ids is not None and len(self.value_ids) != len(self.values):
+            raise ValueError(
+                f"value_ids length ({len(self.value_ids)}) must equal values length ({len(self.values)})")
+        return self
+
+    # -- Datum protocol ---------------------------------------------------
+
+    @property
+    def datum_key(self) -> str:
+        return self.key
+
+    @property
+    def datum_time(self) -> int:
+        return self.time

inventzia/pulse/data/schemas/marketdata/cdf_bar.py

@@ -0,0 +1,70 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later OR LicenseRef-Inventzia-Commercial
+# Copyright (c) 2013-2026 Magrino Bini, Paola Apruzzese, Inventzia Science and Technology Ltd.
+#
+# This file is part of pulse-data.
+#
+# pulse-data is dual-licensed:
+#   - Under the GNU Affero General Public License v3.0 or later (see LICENSE-AGPL-3.0).
+#   - Under a commercial license (see LICENSE-COMMERCIAL.txt).
+#     Contact operations@inventzia.com.
+#
+# THIS FILE IS GENERATED. DO NOT EDIT MANUALLY.
+# Source: schemas_yaml/marketdata/cdf_bar.yaml
+# Regenerate: python schemas/schemas-generators/generate_python.py
+
+from __future__ import annotations
+from datetime import date
+from decimal import Decimal
+from pydantic import AwareDatetime, BaseModel, ConfigDict, Field
+from typing import ClassVar, Optional
+
+
+class CdfBar(BaseModel):
+    """
+    Common data format (CDF) market data bar.
+    """
+
+    model_config = ConfigDict(extra="ignore", frozen=True)
+
+    TYPE_ID:      ClassVar[str] = "com.inventzia.pulse.data.schemas.marketdata.CdfBar"
+    TYPE_VERSION: ClassVar[int] = 1
+
+    symb: str
+    """Instrument symbol or identifier"""
+    timestamp: int
+    """Epoch milliseconds representing the bar open time"""
+    op: Decimal
+    """Open price"""
+    hi: Decimal
+    """High price"""
+    lo: Decimal
+    """Low price"""
+    cl: Decimal
+    """Close price"""
+    vlm: Decimal
+    """Volume traded during this bar"""
+    datetime: AwareDatetime
+    """ISO 8601 datetime of the bar open time"""
+    date: date
+    """Trading date for the bar"""
+
+    vwap: Optional[Decimal] = None
+    """Volume-weighted average price (optional)"""
+    count: Optional[int] = None
+    """Number of trades aggregated in this bar (optional)"""
+    expiry: Optional[str] = None
+    """Option or futures expiry (optional)"""
+    strike: Optional[Decimal] = None
+    """Option strike price (optional)"""
+    sym_exp: Optional[str] = Field(None, alias="symExp")
+    """Symbol + expiry composite identifier (optional)"""
+
+    # -- Datum protocol ---------------------------------------------------
+
+    @property
+    def datum_key(self) -> str:
+        return self.symb
+
+    @property
+    def datum_time(self) -> int:
+        return self.timestamp