PROJECT LUMI

LuminaMoon (luminamoon) is the official reference implementation and central monorepo of PROJECT LUMI, providing low-precision numerical optimization, multimodal dataset streaming, and formal verification suites developed by Lumina Moon (@cloverx-id) and Silver Moon (@cloverxion).

Built with a modular architecture under the PROJECT LUMI specification, luminamoon connects specialized components for CPU/GPU hardware execution, low-latency streaming, and verified numerical stability:

System Architecture

flowchart TD
    Shards["Dataset Sources (HF / PyTorch / Shards)"] --> DataLoader["LuminaMoon Data Engine (SIMD + StringTensor + XXH3)"]
    DataLoader --> TrainLoop["Training Loop (Batch Stream)"]
    DataLoader --> Checkpoint["128B Ping-Pong Checkpoint & WAL"]
    TrainLoop --> Checkpoint
    TrainLoop --> Dispatcher["LuminaV Hardware Dispatcher"]
    Eval["LSO-Eval Suite (Z3 SMT & Parity Gate)"] -.-> Dispatcher
    Dispatcher --> Triton["Triton AOT/JIT GPU (CUDA / ROCm)"]
    Dispatcher --> Vulkan["Vulkan 1.3/1.4 Compute (UMA / SPIR-V)"]
    Dispatcher --> SIMD["Rayon CPU SIMD (AVX-512 / AVX2)"]
    Dispatcher --> Scalar["Reference Scalar Core (Fallback)"]

Projects & Components

Quickstart

Installation

Install the compiled package wheel from PyPI:

pip install luminamoon

Or build from source using Maturin and the Rust 2024 toolchain:

git clone https://github.com/cloverx-id/luminamoon.git
cd luminamoon
pip install maturin
maturin develop --release

Basic Usage (LuminaV Optimizer)

import numpy as np
from luminamoon import LuminaV

# Initialize parameters
weights = np.random.randn(64, 10).astype(np.float32)
biases = np.zeros(10, dtype=np.float32)

# Instantiate LuminaV optimizer
optimizer = LuminaV([weights, biases], lr=1e-3, buffer=2)

# Execute optimization step with explicit gradients
grad_w = np.random.randn(64, 10).astype(np.float32)
grad_b = np.random.randn(10, dtype=np.float32)
optimizer.step(grads=[grad_w, grad_b])

For PyTorch deep learning workflows, see the PyTorch Integration Guide.

LuminaV Algorithm & Data Engine Versioning (v1.5.3)

luminamoon natively implements the canonical LuminaV v1.5.3 reference algorithm and provides explicit version introspection, locking, and backward-compatible modular resolution:

from luminamoon import LuminaV
import luminamoon.data as lmd

# 1. Introspect default algorithm version (Canonical baseline: v1.5.3)
print(LuminaV.getVersion())   # "1.5.3"
print(lmd.get_version())       # "1.0.3"

# 2. Lock or select a specific version per-instance or globally
opt = LuminaV([weights, biases], lr=1e-3, version="1.5.3")
opt.setVersion("1.5.3")        # Instance-level version lock
LuminaV.setVersion("1.5.3")    # Class-level default

# 3. Dynamic modular resolution & legacy support
# Legacy/historical versions (e.g. "0.9.0", "1.0.0") are automatically resolved
# via on-demand local caching (~/.cache/luminamoon/versions/<ver>/) without failure.
opt_legacy = LuminaV([weights, biases], version="0.9.0")

Basic Usage (LuminaMoon Data Engine: Fused Preprocessing & Zero-Copy Pipeline)

from luminamoon.data import FusedPipeline, StringTensor, create_resumable_collate, ResumablePipeline

# 1. Ultra-fast fused single-pass preprocessing (>400k records/s) in Rust
pipeline = FusedPipeline(
    trim_whitespace=True,
    normalize_newlines=True,  # AVX-512 / AVX2 / NEON SIMD
    min_chars=10,
    min_entropy=2.0,
)
string_tensor = pipeline(["  sample 1\r\n", "sample 2 with proper prose text"])

# 2. Zero-copy export to Apache Arrow, Polars, and GPU-ready PyTorch buffers
polars_series = string_tensor.to_polars()
arrow_array = string_tensor.to_arrow()
offsets_tensor, payload_tensor = string_tensor.to_torch_gpu(device="cuda")

# 3. Stream dataset with async prefetching & 128B Ping-Pong crash-recovery
pipe = ResumablePipeline(
    source=raw_data,
    fused_pipeline=pipeline,
    batch_size=64,
    prefetch_batches=4,
    checkpoint_path="./cache/checkpoint.meta",
)
for batch in pipe:
    # Training step...
    pipe.commit()  # Atomically persists Dual-Slot A/B checkpoint and deduplication WAL

For detailed architecture, Shannon entropy heuristics, MinHash deduplication, and PyTorch collate_fn adapters, see the Data Engine Guide.

Verification & CI/CD

All pull requests and releases are validated across Linux, Windows, and macOS:

# Enforce zero-warning static analysis across the Rust workspace
cargo clippy --workspace --all-targets -- -D warnings

# Run Rust workspace unit and differential parity tests (Optimizer + DataLoader)
cargo test --workspace

# Run Python static type check
npx pyright python/luminamoon

# Run standalone NumPy, PyTorch, and DataLoader verification suites
python optimizer/tests/test_standalone_numpy.py
python optimizer/tests/test_end_to_end_training.py
python -B tests/test_data_modular.py
python -B tests/test_gpu_vs_cpu_strings.py

# Run LSO-Eval formal verification suite
python -m eval

Developer Resources

For contributors and systems engineers building on or extending PROJECT LUMI (luminamoon):

• Optimizer Modular Documentation: docs/optimize/
• Data Engine Modular Documentation: data/
• Optimizer Library Audits: docs/library_audit/
• Data Standalone Library Audits: data/docs/library_audit/
• Data Engine Architecture & User Guide: data/README.md
• User Documentation: docs/en/

Authors & Maintenance

PROJECT LUMI (luminamoon) is engineered and maintained by:

• Silver Moon (@cloverxion)
• Lumina Moon (@cloverx-id)

License

Licensed under the Apache License, Version 2.0. See LICENSE for details.