ml4t-specs

Serializable, runtime-neutral contracts for market data, artifacts, strategy lifecycles, and execution across the ML4T library ecosystem.

The stable support matrix is CPython 3.12, 3.13, and 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
• versioned strategy lifecycle and market-event semantics
• canonical targets, child orders, execution assumptions, and position-rule state
• 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 feed, lifecycle, strategy-intent, execution, and position-rule semantics
• ml4t-live for the same runtime-neutral execution contracts
• 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

pip install ml4t-specs

Quick Start

Normalize provider-specific field names into a portable feed contract:

from ml4t.specs import FeedSpec

feed = FeedSpec.from_mapping(
    {
        "time_col": "date",
        "symbol_col": "ticker",
        "price_col": "settle",
        "close_col": "settle",
        "calendar": "NYSE",
    }
)
assert feed.timestamp_col == "date"
assert feed.entity_col == "ticker"
assert feed.price_col == "settle"

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

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.

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

Lifecycle And Market Events

LifecycleContract defines callback ordering, available information, intent permissions, callback counts, exception behavior, and causal rank for each portable strategy phase. LIFECYCLE_V1 is the supported contract. MarketEvent supplies versioned event identity, validated payloads, provider sequence or gap evidence, and immutable JSON metadata. Phase declaration order is the serialization order; causal_rank defines causal ordering.

Strategy And Execution Contracts

CanonicalTargetIntent records a strategy decision before order construction. CanonicalChildOrderIntent records the resulting unsigned order, its target lineage, fill decision session, fill session, eligibility phase, time in force, and required execution capabilities. eligibility_phase is always a phase in decision_session. The two session fields permit a close decision to schedule a child for a later session's opening auction. Targets may schedule an arbitrary future effective session so allocation systems can register dated decisions in advance; venue calendars decide whether that date is tradable. ExecutionPolicy records the assumptions under which an engine or venue executes those orders. PositionRulePolicy and PositionRuleState make client-side and broker-native exit behavior portable and resumable. Persist one PositionRuleState per rule_id that carries runtime state, including composite parents and stateful leaves. Its remaining quantity is post-action; partial exit quantity and adjusted stop price are stored with the latest action. SCALED_EXIT sizes an exit order below the open position quantity; it does not require the venue to partially fill that smaller order, so it is independent of allow_partial_fills. Stop-loss, take-profit, and trailing-stop rules use the required fractional pct parameter in (0, 1]. Time exits use the required positive integer max_bars; scaled exits use ordered ScaledExitTarget values.

These contracts serialize to JSON-compatible mappings. Their comparison helpers report exact field-level differences, including generated identities and timestamps. Callers comparing two engines must align those fields first. Auction fill eligibility and auction time-in-force values require the matching declared capability. A decision that observes a completed close cannot fill at that same close. Instrument prices may be negative, while quantities, trailing amounts, and trailing percentages remain positive. Favorable and adverse excursions are signed fractional returns. Use validate_child_against_policy() before submission to reject child orders that need execution behavior disabled by the selected policy. Use validate_rule_policy_against_execution_policy() before activating position rules.

For intraday strategies, NEXT_PHASE from INTRABAR or MARKET_EVENT means the next event in that same phase. Cross-session opening fills use OPENING_AUCTION explicitly, with OPG time in force and the opening-auction capability. CURRENT_PHASE, including IOC and FOK, is available only for evolving MARKET_EVENT callbacks. Bar-based INTRABAR decisions have already observed the completed high and low and must use NEXT_PHASE. Engines must call validate_event_against_phase() before dispatch so a completed event cannot be presented as an evolving callback.

CanonicalChildOrderIntent requires both decision_session and effective_session. An order decided before the opening auction uses eligibility_phase=PRE_OPEN with fill_eligibility=OPENING_AUCTION; using eligibility_phase=OPENING_AUCTION means the decision already observed that session's open and is rejected for same-open execution.

Read And Write Spec Payloads

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

Read the contribution guide for issue scope, verification evidence, and contract compatibility requirements.

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

Resources

• Documentation
• Issue tracker
• Release notes
• License

License

MIT