mxm-refdata 0.3.0__py3-none-any.whl

mxm_refdata-0.3.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,64 @@
+mxm/refdata/__init__.py,sha256=wJwt_MY4SwmNCetfEEGaObbC5KTTyrA6z6FlN30r_Zw,56
+mxm/refdata/api/__init__.py,sha256=2RrQXV815YAX5hsIFKVBLLDQURar1cFBf1vxs8cxkiA,60
+mxm/refdata/api/ref_data_api.py,sha256=70BbjEXDqk8QLEwb_2cuGDp6qbsv1Ivqjm-ve-eeym8,22021
+mxm/refdata/cli.py,sha256=hGO5vFP0xJUmZ1f0fs_7hNrIXnbungS3uD2ACSPX9lw,6586
+mxm/refdata/data/first_day_of_interest_rule.json,sha256=NDgsMT08AxJhP_lvTo-FKeWDoe8hSM2YzgJgxXVm-3g,1929
+mxm/refdata/data/futures_products.csv,sha256=LE3dZCtWw2Qxum3vFeTken-Y5R3gx5mpkHgPuCGzU-w,2792
+mxm/refdata/data/last_trading_rule.json,sha256=ElEIR6xVdRqXBbxr1SSGVLER2KARwfNrOccwrY4IckY,944
+mxm/refdata/database/__init__.py,sha256=Dt4fslEjG1djbQxEmBOx7DKbcfeyIUCbm5EK1cGnbko,40
+mxm/refdata/database/sql_session_manager.py,sha256=kfIsZP4E-QaS14FaQCqTyIm5XjkC0nukR4_60QsRMxk,4344
+mxm/refdata/mappings/__init__.py,sha256=htjE6ZgOqOC3kP-hd90aqvfhaQ8onIV6RiAJKxHtktc,833
+mxm/refdata/mappings/futures_contract_vs_orm.py,sha256=uOkdYMZM2SljCTf8mNLsQUpetNLG_arJc7hM9DRrceQ,1885
+mxm/refdata/mappings/futures_product_vs_orm.py,sha256=gyxPfaKvjNihPRLHxSdi1Q1Hp4DgO3S1_loMPFjjoi4,2320
+mxm/refdata/mappings/period_cycles_vs_orm.py,sha256=gRiGpPAstEhq05LgUPM_CGDzPzY5YYNRSgRl9bXChi8,3053
+mxm/refdata/mappings/period_vs_orm.py,sha256=Ut_XYb-Wb2RJcF-r0ZKT6tlzwAukzT0IZQNo7I5TSTk,1049
+mxm/refdata/models/__init__.py,sha256=Jag4lLBdAmx5eMdivA4UyviwdFi_I1_Fqm7zkaZbxrg,849
+mxm/refdata/models/contracts/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+mxm/refdata/models/contracts/futures_contract.py,sha256=ltDc3u3VknHK4B6fxzzjB4kojETQ0EiWoOdvif1OMfs,868
+mxm/refdata/models/currencies.py,sha256=lxqlv4h9-ZsF7YBoilA780rG834m4--lW7udvzdEfhA,584
+mxm/refdata/models/months.py,sha256=67ojVaXltnwuHEePLqdJO7d2FtDJICOlopcsZK4Ipvk,1680
+mxm/refdata/models/orm/__init__.py,sha256=cecb7mZ3zQ9N_-3YVKGFlE2beHyfZzma_Z40tIaLEE0,407
+mxm/refdata/models/orm/base.py,sha256=kha9xmklzhuQAK8QEkNBn-mAHq8dUKbOM-3abaBpWmQ,71
+mxm/refdata/models/orm/futures_contracts.py,sha256=4soOTxLvWcHu-sDtAUxNc47BgxDXivXtqv7XZb3FvzQ,1721
+mxm/refdata/models/orm/futures_products.py,sha256=oaP5humP6yxfcsNmSCoKduOwVDzcWMpq3kGXjZKw_CU,2162
+mxm/refdata/models/orm/period_cycles.py,sha256=Zf3bNpSfrzKMZoelTn0IOkNuaVxfQ-l_TanAs1FWFSs,2493
+mxm/refdata/models/orm/periods.py,sha256=oXnfiqPahsbxhqX1c7eh5eSoZQQU3Gu43yFtJlAmxK8,948
+mxm/refdata/models/period_cycles.py,sha256=AWvNVnHjXK3H7G4H7ygkMwf6Nx89_o_6ras3qo53Ak4,2241
+mxm/refdata/models/periods.py,sha256=4zhtvHQf2nGZrdqwTQUQ2lSU7cWRTTnj5J-xovYXsnc,1964
+mxm/refdata/models/products/__init__.py,sha256=tyYvLLfha6vFgCbCDb425F8IZnL9MGhKmDte5Xuaq9w,37
+mxm/refdata/models/products/futures_product.py,sha256=9gFxypYB6HY4JXqp1yKaI-GlLa0O_kITjQS7XPbtL2U,1719
+mxm/refdata/models/products/settlement.py,sha256=4cP1HXMAKvg5K8HpAdcppclHjF2DUk1PAIS74vA0V8I,197
+mxm/refdata/models/reference_events.py,sha256=6O2zlecF2kJ7DeSDImHHm2KSYq298Hv_Ddm40YsCXZY,291
+mxm/refdata/models/units.py,sha256=TC9HTLvKKlk_WfEM7DEjutjIdHKpiazlYC4m2jhHAeE,1506
+mxm/refdata/models/weekdays.py,sha256=cNLCMWvaw12BxFsP5Nasc-sWPlVeR08kZBjfU7NcqmQ,1753
+mxm/refdata/parsing/__init__.py,sha256=f0PX8E2FU_zMNbvok2yV8I-cpv7MGMo43kAMpMxRlDE,71
+mxm/refdata/parsing/futures_products_from_csv.py,sha256=Asnvmx5GYlllSR4mNVDR7usv2E6JTCMu-0E5LSZTkqM,2822
+mxm/refdata/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+mxm/refdata/scripts/__init__.py,sha256=4V3G8NG1JHx9RKTqs2WVQLWySiVjv5203Usa5bYHGA0,43
+mxm/refdata/scripts/db_utils.py,sha256=1tKdPhEO4TaOMieI341_P5fKNKPuxSvgpbRG-Kl33hY,1813
+mxm/refdata/scripts/manage_static_ref_data.py,sha256=b8-SRf5KAyWAwpzxEP-lOYpttIx1ugv-Ehk_GlcGxN4,2407
+mxm/refdata/services/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+mxm/refdata/services/bootstrap.py,sha256=7wIDzlNF-Lvn6FwcWBqdIkyvtZTRA669Zi6wQCgsHcw,2608
+mxm/refdata/services/futures_contract_factory.py,sha256=meO886Jg-rSXzUV9UQzcMGwyzAJFLp5JGamQEJlygs0,4766
+mxm/refdata/services/futures_product_factory.py,sha256=atoZlBksnFyWXs7vJzH_P-aveIDgfn7PXN6mAjp31Uw,4449
+mxm/refdata/services/period_factory.py,sha256=p_686VSmTQvLcMAZpTXj7bUqcGvGRFthwi2FRjt_izk,12227
+mxm/refdata/services/ref_data_service.py,sha256=UDkdud7ZAHhoMUu8tIRrACOZGnXKp2mOCcANXUsaEGc,12603
+mxm/refdata/services/smokecheck.py,sha256=jeQRqy9IC4dj-hqYmY7su5wGCmHjpd_mPjKl2Jpm4Hc,10279
+mxm/refdata/trading_calendars/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+mxm/refdata/trading_calendars/first_day_of_interest.py,sha256=8ytalqoN_z9A0DHVboMLvEac66rHqPgdsc_TN3hVTlY,2807
+mxm/refdata/trading_calendars/last_trading_day.py,sha256=Rii58_1R1F7dzv2pEbUPBmka2iws4O6ni-URZVCZ7O8,3463
+mxm/refdata/trading_calendars/nth_business_day.py,sha256=_ORVFAzISY0cyXgOJExHJ4qx9WQA3w1XBfMXuxlSP9M,1940
+mxm/refdata/trading_calendars/nth_calendar_day_of_period.py,sha256=sxonbgZs3MK37h73kIATzXxiHjFXvttugTIMn3J7i2g,1545
+mxm/refdata/trading_calendars/nth_weekday_of_period.py,sha256=vv0iB5obyRgkGrKgRqDkvAKxyH1SjAPz7hO8vViG5ls,1738
+mxm/refdata/trading_calendars/trading_calendar.py,sha256=gVZit-AB5WGnmEAOypo5swJ1eAxv-X946pw1XQmGj5Y,6608
+mxm/refdata/utils/__init__.py,sha256=xPj5Al870MXouESHpYo8ZawzIeTfkd51Z618mnGHNYk,49
+mxm/refdata/utils/cache_manager.py,sha256=UIPc2D54azTuxcq5NCLPDbxqIt61iyeaBoL4rqKONro,960
+mxm/refdata/utils/config.py,sha256=-r4l7-GpKAM-oDoqUGf3ILDDxdi_a3spRENL6XE8jik,912
+mxm/refdata/utils/period_types_codec.py,sha256=iB0wr4yf1qM_W9XuJy-XaYmuBkf5oJOkRZ2qRHM8q9c,553
+mxm/refdata/utils/regex_patterns.py,sha256=ggL_qfV4yGO7oj4r6V_zL1qsiK0dJTyz96sGozwJpaE,568
+mxm/refdata/utils/resources.py,sha256=3D5aELWqmNQnBj5JvBdsq9fxvweLdse2oXLeNcqwy-0,872
+mxm_refdata-0.3.0.dist-info/METADATA,sha256=Nl9rIX-Pc2T5DtktpBwdIGstN63G5OUcJDEraMi4az0,5373
+mxm_refdata-0.3.0.dist-info/WHEEL,sha256=EGEvSphFYqXKs23-kQBeyNoJP1nrT8ZJKQoi5p5DYL8,88
+mxm_refdata-0.3.0.dist-info/entry_points.txt,sha256=CUOylXOtFIIghauVETtZsza1_ShDyz9wZ8Y4Sr_sseI,51
+mxm_refdata-0.3.0.dist-info/licenses/LICENSE,sha256=4_iKgf-rYcWbqm27b61H2XDN_22u7YUfPbrLYJMKHjc,1106
+mxm_refdata-0.3.0.dist-info/RECORD,,

mxm_refdata-0.3.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: poetry-core 2.4.0
+Root-Is-Purelib: true
+Tag: py3-none-any

mxm_refdata-0.3.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+mxm-refdata=mxm.refdata.cli:app
+

mxm_refdata-0.3.0.dist-info/licenses/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.