Metadata-Version: 2.4
Name: mxm-refdata
Version: 0.5.0
Summary: Canonical reference data for Money Ex Machina.
License: MIT
License-File: LICENSE
Author: mxm
Author-email: contact@moneyexmachina.com
Requires-Python: >=3.13,<3.15
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Dist: cachetools (>=7.1.1,<8.0.0)
Requires-Dist: exchange-calendars (>=4.11.1,<5.0.0)
Requires-Dist: mxm-config (>=0.6.2,<0.7)
Requires-Dist: mxm-runtime (>=0.1.2,<0.2)
Requires-Dist: mxm-types (>=0.3.1,<0.4)
Requires-Dist: pandas (>=2.3.3,<3.0.0)
Requires-Dist: psycopg[binary] (>=3.3.4,<4.0.0)
Requires-Dist: pydantic-settings (>=2.14.1,<3.0.0)
Requires-Dist: rich (>=15.0.0,<16.0.0)
Requires-Dist: typer (>=0.25.1,<0.26.0)
Project-URL: Homepage, https://github.com/moneyexmachina/mxm-refdata
Project-URL: Issues, https://github.com/moneyexmachina/mxm-refdata/issues
Project-URL: Repository, https://github.com/moneyexmachina/mxm-refdata
Description-Content-Type: text/markdown

# mxm-refdata

![Version](https://img.shields.io/github/v/release/moneyexmachina/mxm-refdata)
![License](https://img.shields.io/github/license/moneyexmachina/mxm-refdata)
![Python](https://img.shields.io/badge/python-3.13+-blue)
[![Checked with pyright](https://microsoft.github.io/pyright/img/pyright_badge.svg)](https://microsoft.github.io/pyright/)

Reference-data generation, materialisation, and read access for the Money Ex Machina (MXM) ecosystem.

`mxm-refdata` defines deterministic futures products, contracts, periods, lifecycle dates, and trading-calendar relationships. It materialises the resulting operational reference state into PostgreSQL and exposes it through typed application and read-only interfaces.

It is intended to answer questions such as:

```text
What futures products exist?

What contracts exist for a product?

When does a contract become active?

When is its last trading day?

Which contracts are active on a given date?

Which source specification produced this operational state?
```

without depending on any market-data vendor.

For the full architectural specification, see [`docs/design.md`](docs/design.md).

## Purpose

Reference data describes the identity and lifecycle of financial instruments.

For example:

```text
cme_eurusd_futures.Mar-2032
```

is deterministically derived from:

- a futures-product specification;
- period definitions;
- valid contract months;
- trading-calendar semantics;
- first-day-of-interest rules;
- last-trading-day rules.

Observed prices, quotes, trades, settlements, and vendor histories are separate concerns and belong in packages such as `mxm-marketdata`.

## Architecture

The principal reference-data path is:

```text
mxm-refdata-source
        ↓
source adapter
        ↓
FuturesProduct + provenance
        ↓
deterministic generation
        ↓
desired reference-data state
        ↓
plain-SQL PostgreSQL materialisation
        ↓
RefDataReader
        ↓
downstream MXM applications
```

Runtime construction is explicit:

```text
RuntimeIdentity
        ↓
RuntimeContext
        ↓
composition
        ↓
RefData
```

### Authoritative source

Curated futures-product specifications live in the Git-controlled `mxm-refdata-source` repository.

PostgreSQL stores the operational materialised state together with provenance such as source identity, digest, metadata, and source-repository revision.

The canonical source specification remains in `mxm-refdata-source`; it is not duplicated as a second canonical copy inside PostgreSQL.

### Generation

Period and futures-contract generation is deterministic and stateless where practical.

Contract identity follows:

```text
{product_id}.{period_id}
```

for example:

```text
cbot_10_year_us_treasury_note_futures.Dec-2046
```

### Application capabilities

`RefData` is the complete composed application capability. It exposes:

```text
build()
rebuild()
diagnostics()
reader
```

`RefDataReader` is the restricted read-only capability intended for downstream consumers.

### Persistence

Operational structured reference data is stored in PostgreSQL using:

```text
Psycopg 3
+ explicit SQL
+ version-controlled SQL migrations
```

`mxm-refdata` owns the PostgreSQL schema:

```text
refdata
```

There is no SQLAlchemy ORM or SQLite persistence path in the accepted runtime architecture.

## Materialisation lifecycle

Reference data is deterministic derived state.

### Build

```text
construct desired state
→ migrate if required
→ persist non-destructively
```

Equivalent repeated builds are idempotent and do not create duplicate authoritative state.

### Rebuild

```text
construct desired state
→ validate owned schema
→ drop owned schema
→ apply migrations
→ rematerialise
```

`rebuild` is intentionally destructive only within the owned reference-data schema.

Desired state is constructed before destructive reset.

## CLI

The CLI operates through the resolved MXM runtime context. Database credentials, source roots, and operational configuration are not passed as ad hoc command-line overrides.

Check prerequisites:

```bash
mxm-refdata preflight
```

Materialise reference data non-destructively:

```bash
mxm-refdata build
```

Recreate the owned reference-data schema from deterministic source state:

```bash
mxm-refdata rebuild
```

Run operational readiness checks:

```bash
mxm-refdata smokecheck
```

Inspect the materialised universe:

```bash
mxm-refdata products
mxm-refdata product cme_eurusd_futures
mxm-refdata contracts cme_eurusd_futures
mxm-refdata coverage
```

Inspect active contracts using the supported `active` command:

```bash
mxm-refdata active --help
```

## Python usage

Applications should obtain reference data through the normal MXM composition boundary.

Conceptually:

```text
from mxm.refdata import RefData, build_refdata

refdata: RefData = build_refdata(ctx)
```

Downstream code that needs read access only should depend on:

```text
RefDataReader
```

rather than constructing database or configuration dependencies independently.

The detailed application and composition boundaries are documented in [`docs/design.md`](docs/design.md).

## Runtime configuration

Runtime configuration is resolved through the MXM runtime and configuration systems.

The composition root resolves:

- the `mxm_refdata` configuration view;
- the authoritative futures-product source root;
- the configured contract horizon;
- the `operational_state` PostgreSQL target;
- database credentials through the runtime secrets capability.

Lower application layers receive concrete resolved dependencies and do not resolve runtime secrets or deployment configuration themselves.

## Current V1 operational scope

The current configured V1 deployment covers futures on:

```text
CBOT
CME
COMEX
NYMEX
```

The accepted V1 materialisation currently contains:

```text
products:          86
product_sources:   86
periods:           799
contracts:      31,490
cycles:              2
memberships:        752
```

The configured contract horizon is:

```text
2000–2046 inclusive
```

These counts describe the currently accepted MXM V1 deployment rather than universal package constants.

## Development

Install dependencies:

```bash
poetry install
```

Run the standard validation suite:

```bash
make check
```

This runs the tests that require neither PostgreSQL nor the private product-source repository.

### PostgreSQL integration

On `monolith`:

```bash
poetry run pytest -q -m postgres
```

These tests use real PostgreSQL, disposable schemas, and synthetic public fixtures.

They verify:

- migrations;
- schema constraints;
- SQL adapters;
- materialisation;
- Reader behaviour;
- diagnostics;
- lifecycle semantics.

### Private deployment acceptance

On `monolith`:

```bash
poetry run pytest -q -m acceptance
```

This uses the real MXM runtime, configuration, secrets, private `mxm-refdata-source`, and PostgreSQL target while materialising into a disposable acceptance schema.

It verifies the complete configured V1 universe independently from the operational `refdata` schema.

Repository compliance:

```bash
mxm-foundry check .
```

## Package boundaries

`mxm-refdata` owns:

- reference-data domain models;
- futures-product source interpretation;
- deterministic period and contract generation;
- trading-calendar lifecycle calculations;
- PostgreSQL reference-data persistence;
- materialisation lifecycle;
- read semantics;
- readiness diagnostics;
- runtime composition;
- the reference-data CLI.

It does not own:

- market data;
- broker or exchange acquisition clients;
- portfolio construction;
- signals;
- risk;
- execution;
- workflow orchestration;
- the broader MXM operation-level provenance system.

See [`docs/design.md`](docs/design.md) for the detailed boundary definitions and design principles.

## Documentation

- [`docs/design.md`](docs/design.md) — current architecture and design principles
- [`CHANGELOG.md`](CHANGELOG.md) — repository changes by release / unreleased state

## License

MIT License. See `LICENSE`.


