Metadata-Version: 2.4
Name: mxm-runtime
Version: 0.1.1
Summary: Runtime identity discovery and runtime context construction for Money Ex Machina.
License: MIT
License-File: LICENSE
Keywords: runtime,context,identity,configuration,deployment,infrastructure,orchestration,prefect,mxm
Author: mxm
Author-email: contact@moneyexmachina.com
Requires-Python: >=3.13,<3.15
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Typing :: Typed
Requires-Dist: mxm-config (>=0.6.2,<0.7)
Requires-Dist: mxm-secrets (>=0.3.2,<0.4)
Requires-Dist: mxm-types (>=0.3.1,<0.4.0)
Requires-Dist: rich (>=14.2,<16.0)
Requires-Dist: typer (>=0.20,<1.0)
Project-URL: Homepage, https://github.com/moneyexmachina/mxm-runtime
Project-URL: Repository, https://github.com/moneyexmachina/mxm-runtime
Description-Content-Type: text/markdown

# mxm-runtime

![Version](https://img.shields.io/github/v/release/moneyexmachina/mxm-runtime)
![License](https://img.shields.io/github/license/moneyexmachina/mxm-runtime)
![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/)

Runtime discovery, configuration-driven service construction, and RuntimeContext assembly for the Money Ex Machina ecosystem.

`mxm-runtime` is responsible for constructing the operational environment in which MXM applications execute.

It discovers runtime characteristics, loads and resolves configuration, constructs configured services, and assembles them into a single RuntimeContext.

## Purpose

MXM applications require more than configuration files.

They require an operational environment:

```text
Who am I?
Where am I running?
Which configuration applies?
Which services are available?
Where should data and artefacts live?
```

`mxm-runtime` answers these questions.

It exists to separate:

```text
application code
```

from:

```text
runtime discovery
configuration loading
service construction
deployment concerns
context assembly
```

Applications should not:

- discover machine characteristics,
- determine deployment substrate,
- load configuration directly,
- construct service APIs,
- or reason about deployment topology.

Instead, applications receive a configured RuntimeContext:

```python
context = build_runtime_context(
    identity=runtime_identity,
)
```

and consume the services and resources provided by that context.

## Architecture

`mxm-runtime` acts as the runtime constructor layer of the MXM architecture.

```text
RuntimeIdentity
    ↓
mxm-config
    ↓
Configuration Resolution
    ↓
Service Construction
    ↓
RuntimeContext
    ↓
Application
```

The package owns runtime construction.

It does not own configuration semantics or secret resolution semantics.

Those responsibilities belong to:

```text
mxm-config
```

and:

```text
mxm-secrets
```

respectively.

## Core Concepts

### RuntimeIdentity

Represents the operational identity of a running process.

Example:

```text
app          mxm-moneymachine
environment  dev
machine      bridge
substrate    local-process
role         marketdata
```

Runtime identity determines which configuration layers are selected and which services are constructed.

### Machine

A machine identifies a machine-specific configuration profile.

Examples:

```text
bridge
monolith
wildling
scribe
```

Machine values are derived from operating-system characteristics and are used to select machine-specific configuration.

They are configuration selectors rather than unique hardware identifiers.

### Substrate

Represents the execution substrate.

Examples:

```text
local-process
docker
```

Substrate allows runtime construction to adapt to deployment environment differences.

### RuntimeContext

Represents the fully constructed operational environment.

Current fields:

```python
RuntimeContext(
    identity=...,
    config=...,
    secrets=...,
)
```

Future versions may additionally materialise:

```text
paths
databases
reference data services
storage services
execution services
reporting services
```

Applications are expected to consume runtime services through RuntimeContext.

## Runtime Construction Flow

Runtime construction follows the sequence:

```text
RuntimeIdentity
    ↓
load_config(...)
    ↓
Configuration Views
    ↓
Service Construction
    ↓
RuntimeContext
```

For example:

```python
context = build_runtime_context(
    identity=identity,
)
```

which currently materialises:

```text
configuration
secret services
```

and returns a configured RuntimeContext.

## Runtime Discovery

`mxm-runtime` provides discovery utilities for determining runtime characteristics.

Examples:

```python
machine = discover_machine()
substrate = discover_substrate()
```

These functions derive MXM runtime selectors from operating-system facts.

The resulting values are suitable for configuration resolution and runtime construction.

## Relationship To mxm-config

`mxm-config` owns:

```text
configuration storage
configuration loading
configuration merging
configuration views
```

`mxm-runtime` consumes configuration and constructs runtime services from it.

Example:

```text
RuntimeIdentity
    ↓
mxm-config
    ↓
MXMConfig
    ↓
RuntimeContext
```

## Relationship To mxm-secrets

`mxm-secrets` owns:

```text
secret references
authorization
resolution
retrieval
```

`mxm-runtime` constructs configured secret services and makes them available through RuntimeContext.

Applications are expected to consume:

```python
context.secrets
```

rather than constructing SecretsApi instances directly.

## Installation

```bash
pip install mxm-runtime
```

## Usage

Construct a RuntimeContext:

```python
from mxm.runtime import build_runtime_context

context = build_runtime_context(
    identity=identity,
)
```

Access configured services:

```python
api_key = context.secrets.get_secret(
    "databento_api_key",
    identity=context.identity,
)
```

## Design Principles

- **Explicit runtime identity**
  Runtime identity is always represented explicitly.

- **Configuration-driven construction**
  Runtime behaviour is determined through configuration rather than hardcoded wiring.

- **Separation of concerns**
  Discovery, configuration, resolution, construction, and application logic remain separate.

- **Strict typing**
  Fully Pyright-clean and PEP 561 compliant.

- **Minimal implicit behaviour**
  Runtime construction is deterministic and inspectable.

- **Composable services**
  Runtime services are assembled from independent packages.

## Development

```bash
poetry install

make check
```

Run the RuntimeContext smoke test:

```bash
poetry run python scripts/smoke_runtime_context.py
```

## Status

Current release status:

```text
Runtime Identity Discovery Complete
RuntimeContext Construction Complete
Service Expansion In Progress
```

Current RuntimeContext materialises:

```text
configuration
secrets
```

Additional services will be added incrementally.

## License

MIT License. See [LICENSE](LICENSE).

