ml4t-specs 0.1.0__tar.gz

ml4t_specs-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+.venv/
+dist/

ml4t_specs-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Stefan Jansen
+
+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.

ml4t_specs-0.1.0/PKG-INFO

@@ -0,0 +1,149 @@
+Metadata-Version: 2.4
+Name: ml4t-specs
+Version: 0.1.0
+Summary: Shared artifact and schema specifications for ML4T libraries
+Project-URL: Homepage, https://github.com/ml4t/specs
+Project-URL: Repository, https://github.com/ml4t/specs
+Project-URL: Issues, https://github.com/ml4t/specs/issues
+Project-URL: Changelog, https://github.com/ml4t/specs/releases
+License: MIT
+License-File: LICENSE
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: pyyaml>=6.0
+Description-Content-Type: text/markdown
+
+# ml4t-specs
+
+[![Python 3.12-3.14](https://img.shields.io/badge/python-3.12--3.14-blue.svg)](https://www.python.org/downloads/)
+[![PyPI](https://img.shields.io/pypi/v/ml4t-specs)](https://pypi.org/project/ml4t-specs/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Shared schema and artifact contracts for the ML4T library ecosystem.
+
+The stable support matrix is CPython 3.12 through 3.14 on Linux, macOS, and Windows.
+CPython 3.15 prereleases are tested on all three operating systems but are not advertised as
+stable until Python 3.15 is final.
+
+## What This Package Does
+
+`ml4t-specs` provides the small set of shared types that multiple ML4T libraries use to
+describe:
+
+- market data column mappings and feed semantics
+- artifact metadata and storage conventions
+- lightweight YAML/JSON spec payloads
+
+It exists so the higher-level libraries can exchange consistent contracts without re-defining
+the same dataclasses in multiple repos.
+
+Today it is used by:
+
+- `ml4t-backtest` for `FeedSpec` and market-data execution semantics
+- `ml4t-engineer` for artifact metadata
+- `ml4t-diagnostic` for artifact and backtest-result integration
+- `ml4t-models` as an optional integration bridge when `ml4t-specs` is installed
+
+## Installation
+
+```bash
+pip install ml4t-specs
+```
+
+## Main Types
+
+### FeedSpec
+
+`FeedSpec` defines how downstream libraries should interpret a tradable price table:
+
+- timestamp column
+- entity column
+- price / OHLCV columns
+- quote columns
+- calendar and timezone
+- data frequency and timestamp semantics
+
+```python
+from ml4t.specs import FeedSpec
+
+feed = FeedSpec(
+    timestamp_col="date",
+    entity_col="ticker",
+    close_col="settle",
+    price_col="settle",
+    calendar="NYSE",
+    timezone="America/New_York",
+    data_frequency="daily",
+)
+```
+
+### MarketDataSpec
+
+`MarketDataSpec` bundles schema, semantics, and artifact metadata into one serializable object.
+
+```python
+from ml4t.specs import ArtifactStorage, MarketDataSchema, MarketDataSemantics, MarketDataSpec
+
+spec = MarketDataSpec(
+    artifact_id="us_equities_daily",
+    schema=MarketDataSchema(timestamp_col="date", entity_col="ticker", close_col="close"),
+    semantics=MarketDataSemantics(calendar="NYSE", data_frequency="daily"),
+    storage=ArtifactStorage(path="data/us_equities_daily.parquet"),
+)
+```
+
+### Artifact Contracts
+
+The base artifact layer gives ML4T libraries a shared way to talk about persisted outputs:
+
+- `ArtifactKind`
+- `ArtifactStorage`
+- `ArtifactProvenance`
+- `ArtifactSpec`
+
+## Read And Write Spec Payloads
+
+```python
+from ml4t.specs import read_spec_payload, write_spec_payload
+
+write_spec_payload(spec, "market_data.yaml")
+loaded = read_spec_payload("market_data.yaml")
+```
+
+## Why This Exists
+
+The public ML4T libraries share a few contract types at their boundaries. Keeping them here:
+
+- reduces duplication
+- keeps cross-library serialization consistent
+- gives backtest, modeling, engineering, and diagnostics code one shared contract vocabulary
+
+This package is intentionally small. It is a support layer, not a full end-user workflow library.
+
+## Development
+
+```bash
+git clone https://github.com/ml4t/specs.git
+cd ml4t-specs
+uv sync --dev
+uv run ruff check src/ tests/
+uv run ty check
+uv run pytest tests/ -q
+uv build
+```
+
+## License
+
+MIT

ml4t_specs-0.1.0/README.md

@@ -0,0 +1,122 @@
+# ml4t-specs
+
+[![Python 3.12-3.14](https://img.shields.io/badge/python-3.12--3.14-blue.svg)](https://www.python.org/downloads/)
+[![PyPI](https://img.shields.io/pypi/v/ml4t-specs)](https://pypi.org/project/ml4t-specs/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Shared schema and artifact contracts for the ML4T library ecosystem.
+
+The stable support matrix is CPython 3.12 through 3.14 on Linux, macOS, and Windows.
+CPython 3.15 prereleases are tested on all three operating systems but are not advertised as
+stable until Python 3.15 is final.
+
+## What This Package Does
+
+`ml4t-specs` provides the small set of shared types that multiple ML4T libraries use to
+describe:
+
+- market data column mappings and feed semantics
+- artifact metadata and storage conventions
+- lightweight YAML/JSON spec payloads
+
+It exists so the higher-level libraries can exchange consistent contracts without re-defining
+the same dataclasses in multiple repos.
+
+Today it is used by:
+
+- `ml4t-backtest` for `FeedSpec` and market-data execution semantics
+- `ml4t-engineer` for artifact metadata
+- `ml4t-diagnostic` for artifact and backtest-result integration
+- `ml4t-models` as an optional integration bridge when `ml4t-specs` is installed
+
+## Installation
+
+```bash
+pip install ml4t-specs
+```
+
+## Main Types
+
+### FeedSpec
+
+`FeedSpec` defines how downstream libraries should interpret a tradable price table:
+
+- timestamp column
+- entity column
+- price / OHLCV columns
+- quote columns
+- calendar and timezone
+- data frequency and timestamp semantics
+
+```python
+from ml4t.specs import FeedSpec
+
+feed = FeedSpec(
+    timestamp_col="date",
+    entity_col="ticker",
+    close_col="settle",
+    price_col="settle",
+    calendar="NYSE",
+    timezone="America/New_York",
+    data_frequency="daily",
+)
+```
+
+### MarketDataSpec
+
+`MarketDataSpec` bundles schema, semantics, and artifact metadata into one serializable object.
+
+```python
+from ml4t.specs import ArtifactStorage, MarketDataSchema, MarketDataSemantics, MarketDataSpec
+
+spec = MarketDataSpec(
+    artifact_id="us_equities_daily",
+    schema=MarketDataSchema(timestamp_col="date", entity_col="ticker", close_col="close"),
+    semantics=MarketDataSemantics(calendar="NYSE", data_frequency="daily"),
+    storage=ArtifactStorage(path="data/us_equities_daily.parquet"),
+)
+```
+
+### Artifact Contracts
+
+The base artifact layer gives ML4T libraries a shared way to talk about persisted outputs:
+
+- `ArtifactKind`
+- `ArtifactStorage`
+- `ArtifactProvenance`
+- `ArtifactSpec`
+
+## Read And Write Spec Payloads
+
+```python
+from ml4t.specs import read_spec_payload, write_spec_payload
+
+write_spec_payload(spec, "market_data.yaml")
+loaded = read_spec_payload("market_data.yaml")
+```
+
+## Why This Exists
+
+The public ML4T libraries share a few contract types at their boundaries. Keeping them here:
+
+- reduces duplication
+- keeps cross-library serialization consistent
+- gives backtest, modeling, engineering, and diagnostics code one shared contract vocabulary
+
+This package is intentionally small. It is a support layer, not a full end-user workflow library.
+
+## Development
+
+```bash
+git clone https://github.com/ml4t/specs.git
+cd ml4t-specs
+uv sync --dev
+uv run ruff check src/ tests/
+uv run ty check
+uv run pytest tests/ -q
+uv build
+```
+
+## License
+
+MIT

ml4t_specs-0.1.0/pyproject.toml

@@ -0,0 +1,96 @@
+[build-system]
+requires = ["hatchling", "hatch-vcs"]
+build-backend = "hatchling.build"
+
+[tool.hatch.version]
+path = "src/ml4t/specs/__init__.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/ml4t"]
+namespaces = true
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "/src",
+    "/tests",
+    "/README.md",
+    "/LICENSE",
+]
+
+[project]
+name = "ml4t-specs"
+dynamic = ["version"]
+description = "Shared artifact and schema specifications for ML4T libraries"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.12"
+dependencies = [
+    "pyyaml>=6.0",
+]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Financial and Insurance Industry",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Office/Business :: Financial :: Investment",
+    "Topic :: Scientific/Engineering :: Information Analysis",
+    "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://github.com/ml4t/specs"
+Repository = "https://github.com/ml4t/specs"
+Issues = "https://github.com/ml4t/specs/issues"
+Changelog = "https://github.com/ml4t/specs/releases"
+
+[dependency-groups]
+dev = [
+    "pip-audit>=2.10.0",
+    "pytest>=8.0.0",
+    "pytest-cov>=6.0",
+    "ruff>=0.8.0",
+    "twine>=6.2.0",
+    "ty",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+python_classes = ["Test*"]
+python_functions = ["test_*"]
+addopts = [
+    "--cov=ml4t.specs",
+    "--cov-branch",
+    "--cov-fail-under=100",
+]
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+fix = true
+
+[tool.ruff.lint]
+select = [
+    "E",
+    "W",
+    "F",
+    "I",
+    "B",
+    "C4",
+    "UP",
+]
+ignore = [
+    "E501",
+    "B008",
+    "B905",
+]
+
+[tool.ty.environment]
+python-version = "3.12"
+root = ["src"]

ml4t_specs-0.1.0/src/ml4t/specs/__init__.py

@@ -0,0 +1,36 @@
+"""Shared artifact and schema specifications for ML4T libraries."""
+
+from .base import (
+    ArtifactKind,
+    ArtifactProvenance,
+    ArtifactSpec,
+    ArtifactStorage,
+    optional_str,
+    serialize_artifact_value,
+)
+from .io import read_spec_payload, write_spec_payload
+from .market_data import (
+    FeedSpec,
+    MarketDataSchema,
+    MarketDataSemantics,
+    MarketDataSpec,
+    TimestampSemantics,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "ArtifactKind",
+    "ArtifactProvenance",
+    "ArtifactSpec",
+    "ArtifactStorage",
+    "FeedSpec",
+    "MarketDataSchema",
+    "MarketDataSemantics",
+    "MarketDataSpec",
+    "TimestampSemantics",
+    "optional_str",
+    "read_spec_payload",
+    "serialize_artifact_value",
+    "write_spec_payload",
+]

ml4t_specs-0.1.0/src/ml4t/specs/base.py

@@ -0,0 +1,131 @@
+"""Shared base specifications for persisted ML4T artifacts."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from dataclasses import asdict, dataclass, field
+from enum import Enum, StrEnum
+from pathlib import Path
+from typing import Any
+
+
+class ArtifactKind(StrEnum):
+    """Kinds of persisted artifacts shared across ML4T workflows."""
+
+    MARKET_DATA = "market_data"
+    LABELS = "labels"
+    FEATURES = "features"
+    PREDICTIONS = "predictions"
+
+
+@dataclass(frozen=True, slots=True)
+class ArtifactStorage:
+    """Storage location and serialization hints for an artifact."""
+
+    path: str | Path = ""
+    format: str = "parquet"
+    partition_by: tuple[str, ...] = ()
+
+    @classmethod
+    def from_mapping(cls, mapping: Mapping[str, Any] | None) -> ArtifactStorage:
+        if mapping is None:
+            return cls()
+        if not isinstance(mapping, Mapping):
+            raise TypeError("storage must be a mapping or None")
+        partition_by = mapping.get("partition_by", ())
+        if isinstance(partition_by, str):
+            partition_by = (partition_by,)
+        elif not isinstance(partition_by, Sequence):
+            raise TypeError("storage partition_by must be a string or sequence")
+        return cls(
+            path=mapping.get("path", ""),
+            format=str(mapping.get("format", "parquet")),
+            partition_by=tuple(str(item) for item in partition_by),
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class ArtifactProvenance:
+    """Upstream lineage and content fingerprinting for an artifact."""
+
+    source_artifacts: tuple[str, ...] = ()
+    content_hash: str | None = None
+    created_by: str | None = None
+
+    @classmethod
+    def from_mapping(cls, mapping: Mapping[str, Any] | None) -> ArtifactProvenance:
+        if mapping is None:
+            return cls()
+        if not isinstance(mapping, Mapping):
+            raise TypeError("provenance must be a mapping or None")
+        source_artifacts = mapping.get("source_artifacts", ())
+        if isinstance(source_artifacts, str):
+            source_artifacts = (source_artifacts,)
+        elif not isinstance(source_artifacts, Sequence):
+            raise TypeError("provenance source_artifacts must be a string or sequence")
+        return cls(
+            source_artifacts=tuple(str(item) for item in source_artifacts),
+            content_hash=_optional_str(mapping.get("content_hash")),
+            created_by=_optional_str(mapping.get("created_by")),
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class ArtifactSpec:
+    """Base metadata shared by all persisted artifact specifications."""
+
+    artifact_id: str
+    kind: ArtifactKind
+    version: int = 1
+    storage: ArtifactStorage = field(default_factory=ArtifactStorage)
+    provenance: ArtifactProvenance = field(default_factory=ArtifactProvenance)
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.artifact_id, str) or not self.artifact_id.strip():
+            raise ValueError("artifact_id must be a non-empty string")
+        if isinstance(self.version, bool) or not isinstance(self.version, int) or self.version < 1:
+            raise ValueError("version must be a positive integer")
+
+    def to_dict(self) -> dict[str, Any]:
+        return _serialize(asdict(self))
+
+
+def optional_str(value: Any) -> str | None:
+    """Coerce a value to a non-empty string."""
+    return _optional_str(value)
+
+
+def serialize_artifact_value(value: Any) -> Any:
+    """Serialize enums and pathlib objects for YAML/JSON output."""
+    return _serialize(value)
+
+
+def _optional_str(value: Any) -> str | None:
+    if value is None:
+        return None
+    text = str(value)
+    return text if text else None
+
+
+def _serialize(value: Any) -> Any:
+    if isinstance(value, Enum):
+        return value.value
+    if isinstance(value, Path):
+        return str(value)
+    if isinstance(value, dict):
+        return {key: _serialize(item) for key, item in value.items()}
+    if isinstance(value, tuple):
+        return [_serialize(item) for item in value]
+    if isinstance(value, list):
+        return [_serialize(item) for item in value]
+    return value
+
+
+__all__ = [
+    "ArtifactKind",
+    "ArtifactProvenance",
+    "ArtifactSpec",
+    "ArtifactStorage",
+    "optional_str",
+    "serialize_artifact_value",
+]

ml4t_specs-0.1.0/src/ml4t/specs/io.py

@@ -0,0 +1,75 @@
+"""Low-level payload I/O for ML4T artifact specifications."""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Mapping
+from pathlib import Path
+from tempfile import NamedTemporaryFile
+from typing import Any
+
+import yaml
+
+from .base import ArtifactSpec
+
+_SUPPORTED_SUFFIXES = frozenset({".json", ".yaml", ".yml"})
+
+
+def _validated_suffix(path: Path) -> str:
+    suffix = path.suffix.lower()
+    if suffix not in _SUPPORTED_SUFFIXES:
+        choices = ", ".join(sorted(_SUPPORTED_SUFFIXES))
+        raise ValueError(f"Spec path extension must be one of: {choices}")
+    return suffix
+
+
+def _normalize_mapping(data: Any) -> dict[str, Any]:
+    if not isinstance(data, Mapping):
+        raise ValueError("Spec payload must be a mapping")
+    return {str(key): value for key, value in data.items()}
+
+
+def read_spec_payload(path_or_mapping: str | Path | Mapping[Any, Any]) -> dict[str, Any]:
+    """Load a spec payload from YAML/JSON or return a copied mapping."""
+    if isinstance(path_or_mapping, Mapping):
+        return _normalize_mapping(path_or_mapping)
+
+    path = Path(path_or_mapping)
+    suffix = _validated_suffix(path)
+    with path.open(encoding="utf-8") as f:
+        data = json.load(f) if suffix == ".json" else yaml.safe_load(f)
+    return _normalize_mapping({} if data is None else data)
+
+
+def write_spec_payload(payload: Mapping[Any, Any] | ArtifactSpec, path: str | Path) -> Path:
+    """Write a spec payload to YAML or JSON."""
+    dest = Path(path)
+    suffix = _validated_suffix(dest)
+    normalized = (
+        payload.to_dict() if isinstance(payload, ArtifactSpec) else _normalize_mapping(payload)
+    )
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    temporary_path: Path | None = None
+    try:
+        with NamedTemporaryFile(
+            "w",
+            encoding="utf-8",
+            dir=dest.parent,
+            prefix=f".{dest.name}.",
+            delete=False,
+        ) as temporary:
+            temporary_path = Path(temporary.name)
+            if suffix == ".json":
+                json.dump(normalized, temporary, indent=2)
+                temporary.write("\n")
+            else:
+                yaml.safe_dump(normalized, temporary, sort_keys=False)
+        temporary_path.replace(dest)
+    except Exception:
+        if temporary_path is not None:
+            temporary_path.unlink(missing_ok=True)
+        raise
+    return dest
+
+
+__all__ = ["read_spec_payload", "write_spec_payload"]