mxm-refdata 0.3.0__tar.gz

mxm_refdata-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 Money Ex Machina
+
+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.

mxm_refdata-0.3.0/PKG-INFO

@@ -0,0 +1,228 @@
+Metadata-Version: 2.4
+Name: mxm-refdata
+Version: 0.3.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,<4.0
+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: pandas (>=2.3.3,<3.0.0)
+Requires-Dist: pydantic-settings (>=2.14.1,<3.0.0)
+Requires-Dist: rich (>=15.0.0,<16.0.0)
+Requires-Dist: sqlalchemy (>=2.0.43,<3.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 and contract ontology for the Money Ex Machina (MXM) ecosystem.
+
+`mxm-refdata` provides canonical, programmatic definitions of financial instruments and trading structures, currently focused on:
+
+- futures products,
+- futures contracts,
+- lifecycle rules,
+- trading calendars,
+- periods and period cycles,
+- and deterministic contract generation.
+
+The package acts as the ontological reference layer for MXM systems such as `mxm-v1`.
+
+## Purpose
+
+`mxm-refdata` defines *what financial reference objects exist* and *how they are constructed*.
+
+For example, a futures contract such as:
+
+```text
+cme_gbp_futures.Mar-2032
+```
+
+is treated as a deterministic construct derived from:
+
+- product specifications,
+- listing rules,
+- period systems,
+- and trading-calendar semantics.
+
+This allows MXM systems to reason about financial structures independently of any specific market-data provider.
+
+`mxm-refdata` therefore models the constructive ontology of financial instruments, while observed prices, trades, quotes, and exchange events belong to the separate market-observation layer (`mxm-marketdata`).
+
+## Architecture
+
+`mxm-refdata` consists of four main layers:
+
+1. **Reference specifications**  
+   Human-authored product and lifecycle specifications bundled with the package.
+
+2. **Deterministic generation**  
+   Services that construct contracts, periods, lifecycle dates, and calendar relationships.
+
+3. **Materialised reference store**  
+   SQLite database containing generated products, contracts, periods, cycles, and lifecycle state.
+
+4. **Query and inspection interfaces**  
+   Typed Python API and operational CLI.
+
+## Installation
+
+```bash
+git clone https://github.com/moneyexmachina/mxm-refdata.git
+cd mxm-refdata
+poetry install
+```
+
+## Usage
+
+Build the local reference database:
+
+```bash
+mxm-refdata build
+```
+
+Rebuild from scratch:
+
+```bash
+mxm-refdata rebuild
+```
+
+Inspect products:
+
+```bash
+mxm-refdata products
+```
+
+Inspect contract coverage:
+
+```bash
+mxm-refdata coverage
+```
+
+Run operational smoke checks:
+
+```bash
+mxm-refdata smokecheck
+```
+
+## Python API
+
+```python
+from datetime import date
+
+from mxm.refdata.api.ref_data_api import RefDataAPI
+
+api = RefDataAPI()
+
+products = api.get_all_products()
+
+contracts = api.get_contracts_for_product(
+    "comex_gold_futures"
+)
+
+active_contracts = api.get_active_contracts(
+    as_of_date=date(2026, 5, 1),
+)
+```
+
+## Operating Modes
+
+### Buildable mode
+
+In buildable mode, the reference database is treated as deterministic derived state.
+
+If missing or empty, the package may automatically:
+
+- create the schema,
+- generate contracts,
+- and materialise the reference universe.
+
+This mode supports:
+
+- development,
+- CI,
+- local experimentation,
+- and early-stage deployments.
+
+### Managed mode
+
+Managed mode treats the reference database as governed operational state.
+
+Updates occur explicitly through controlled management and reconciliation workflows.
+
+## Development
+
+`mxm-refdata` is maintained as an `mxm-foundry` compliant package.
+
+Primary development gate:
+
+```bash
+make check
+```
+
+Validate repository compliance:
+
+```bash
+mxm-foundry check .
+```
+
+Setup:
+
+```bash
+poetry install
+```
+
+## Documentation
+
+- `docs/design.md`
+
+## Roadmap
+
+### v0
+
+- Futures product specifications
+- Deterministic futures contract generation
+- Trading calendar integration
+- Period and period-cycle models
+- Materialised SQLite reference store
+- Typed query API
+- Operational CLI and smoke checks
+- `mxm-foundry` compliance
+
+### v1
+
+- Broader futures product coverage
+- Stronger typed lifecycle-rule models
+- Explicit `TradingCalendarId` abstractions
+- Improved CLI inspection and filtering
+- Clearer ontology boundaries and documentation
+
+### v2
+
+- ETF and FX product support
+- Managed reference governance
+- Historical exchange rule evolution
+- External reconciliation workflows
+- Expanded multi-venue ontology
+- Integration boundaries with `mxm-marketdata`
+- Integration boundaries with future `mxm-calendar`
+
+## License
+
+MIT License. See [LICENSE](LICENSE).
+

mxm_refdata-0.3.0/README.md

@@ -0,0 +1,202 @@
+# 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 and contract ontology for the Money Ex Machina (MXM) ecosystem.
+
+`mxm-refdata` provides canonical, programmatic definitions of financial instruments and trading structures, currently focused on:
+
+- futures products,
+- futures contracts,
+- lifecycle rules,
+- trading calendars,
+- periods and period cycles,
+- and deterministic contract generation.
+
+The package acts as the ontological reference layer for MXM systems such as `mxm-v1`.
+
+## Purpose
+
+`mxm-refdata` defines *what financial reference objects exist* and *how they are constructed*.
+
+For example, a futures contract such as:
+
+```text
+cme_gbp_futures.Mar-2032
+```
+
+is treated as a deterministic construct derived from:
+
+- product specifications,
+- listing rules,
+- period systems,
+- and trading-calendar semantics.
+
+This allows MXM systems to reason about financial structures independently of any specific market-data provider.
+
+`mxm-refdata` therefore models the constructive ontology of financial instruments, while observed prices, trades, quotes, and exchange events belong to the separate market-observation layer (`mxm-marketdata`).
+
+## Architecture
+
+`mxm-refdata` consists of four main layers:
+
+1. **Reference specifications**  
+   Human-authored product and lifecycle specifications bundled with the package.
+
+2. **Deterministic generation**  
+   Services that construct contracts, periods, lifecycle dates, and calendar relationships.
+
+3. **Materialised reference store**  
+   SQLite database containing generated products, contracts, periods, cycles, and lifecycle state.
+
+4. **Query and inspection interfaces**  
+   Typed Python API and operational CLI.
+
+## Installation
+
+```bash
+git clone https://github.com/moneyexmachina/mxm-refdata.git
+cd mxm-refdata
+poetry install
+```
+
+## Usage
+
+Build the local reference database:
+
+```bash
+mxm-refdata build
+```
+
+Rebuild from scratch:
+
+```bash
+mxm-refdata rebuild
+```
+
+Inspect products:
+
+```bash
+mxm-refdata products
+```
+
+Inspect contract coverage:
+
+```bash
+mxm-refdata coverage
+```
+
+Run operational smoke checks:
+
+```bash
+mxm-refdata smokecheck
+```
+
+## Python API
+
+```python
+from datetime import date
+
+from mxm.refdata.api.ref_data_api import RefDataAPI
+
+api = RefDataAPI()
+
+products = api.get_all_products()
+
+contracts = api.get_contracts_for_product(
+    "comex_gold_futures"
+)
+
+active_contracts = api.get_active_contracts(
+    as_of_date=date(2026, 5, 1),
+)
+```
+
+## Operating Modes
+
+### Buildable mode
+
+In buildable mode, the reference database is treated as deterministic derived state.
+
+If missing or empty, the package may automatically:
+
+- create the schema,
+- generate contracts,
+- and materialise the reference universe.
+
+This mode supports:
+
+- development,
+- CI,
+- local experimentation,
+- and early-stage deployments.
+
+### Managed mode
+
+Managed mode treats the reference database as governed operational state.
+
+Updates occur explicitly through controlled management and reconciliation workflows.
+
+## Development
+
+`mxm-refdata` is maintained as an `mxm-foundry` compliant package.
+
+Primary development gate:
+
+```bash
+make check
+```
+
+Validate repository compliance:
+
+```bash
+mxm-foundry check .
+```
+
+Setup:
+
+```bash
+poetry install
+```
+
+## Documentation
+
+- `docs/design.md`
+
+## Roadmap
+
+### v0
+
+- Futures product specifications
+- Deterministic futures contract generation
+- Trading calendar integration
+- Period and period-cycle models
+- Materialised SQLite reference store
+- Typed query API
+- Operational CLI and smoke checks
+- `mxm-foundry` compliance
+
+### v1
+
+- Broader futures product coverage
+- Stronger typed lifecycle-rule models
+- Explicit `TradingCalendarId` abstractions
+- Improved CLI inspection and filtering
+- Clearer ontology boundaries and documentation
+
+### v2
+
+- ETF and FX product support
+- Managed reference governance
+- Historical exchange rule evolution
+- External reconciliation workflows
+- Expanded multi-venue ontology
+- Integration boundaries with `mxm-marketdata`
+- Integration boundaries with future `mxm-calendar`
+
+## License
+
+MIT License. See [LICENSE](LICENSE).

mxm_refdata-0.3.0/pyproject.toml

@@ -0,0 +1,68 @@
+[tool.poetry]
+name = "mxm-refdata"
+version = "0.3.0"
+description = "Canonical reference data for Money Ex Machina."
+authors = ["mxm <contact@moneyexmachina.com>"]
+license = "MIT"
+readme = "README.md"
+packages = [{ include = "mxm", from = "src" }]
+include = [
+    "src/mxm/refdata/py.typed",
+    "src/mxm/refdata/data/**/*",
+]
+[tool.poetry.scripts]
+mxm-refdata = "mxm.refdata.cli:app"
+
+[tool.poetry.urls]
+Homepage = "https://github.com/moneyexmachina/mxm-refdata"
+Repository = "https://github.com/moneyexmachina/mxm-refdata"
+Issues = "https://github.com/moneyexmachina/mxm-refdata/issues"
+
+[tool.poetry.dependencies]
+python = ">=3.13,<4.0"
+pandas = ">=2.3.3,<3.0.0"
+sqlalchemy = ">=2.0.43,<3.0.0"
+exchange-calendars = ">=4.11.1,<5.0.0"
+typer = "^0.25.1"
+rich = "^15.0.0"
+cachetools = "^7.1.1"
+pydantic-settings = "^2.14.1"
+
+[tool.poetry.group.dev.dependencies]
+black = "^25.9.0"
+ruff = "^0.13.2"
+isort = "^6.0.1"
+pytest = "^8.4.2"
+pytest-mock = "^3.15.1"
+pyright = "^1.1.408"
+pandas-stubs = "^3.0.0.260204"
+
+[build-system]
+requires = ["poetry-core>=2.0.0,<3.0.0"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.black]
+line-length = 88
+target-version = ["py313"]
+
+[tool.isort]
+profile = "black"
+line_length = 88
+known_first_party = ["mxm"]
+combine_as_imports = true
+
+[tool.ruff]
+line-length = 88
+target-version = "py313"
+
+[tool.ruff.lint]
+select = ["E","F","I","B","UP","C90","RUF"]
+ignore = ["E203","E501"]
+
+[tool.ruff.lint.isort]
+known-first-party = ["mxm"]
+
+[tool.pytest.ini_options]
+addopts = "-q"
+pythonpath = ["src"]
+

mxm_refdata-0.3.0/src/mxm/refdata/__init__.py

@@ -0,0 +1 @@
+"""Code for the core reference data service package."""

mxm_refdata-0.3.0/src/mxm/refdata/api/__init__.py

@@ -0,0 +1 @@
+"""Single access api for objects in the refData package."""