Metadata-Version: 2.5
Name: moltengine
Version: 0.11.0a4
Summary: Thermally aware, memory-efficient local LLM fine-tuning for NVIDIA GPUs
Project-URL: Homepage, https://github.com/PraveenNimilka/MOLT
Project-URL: Documentation, https://github.com/PraveenNimilka/MOLT/tree/main/docs
Project-URL: Repository, https://github.com/PraveenNimilka/MOLT.git
Project-URL: Issues, https://github.com/PraveenNimilka/MOLT/issues
Project-URL: Changelog, https://github.com/PraveenNimilka/MOLT/blob/v0.11.0-alpha.4/docs/releases/0.11.0-alpha.4.md
Author: Praveen Nimilka
License-Expression: LicenseRef-PolyForm-Shield-1.0.0
License-File: LICENSE
License-File: NOTICE
License-File: THIRD_PARTY_NOTICES.md
License-File: TRADEMARKS.md
Keywords: energy-measurement,local-ai,machine-learning,qlora,training
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Operating System :: Microsoft :: Windows :: Windows 11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Typing :: Typed
Requires-Python: <3.13,>=3.12
Requires-Dist: numpy<3,>=2.1
Requires-Dist: nvidia-ml-py<14,>=13.580.65
Requires-Dist: psutil<8,>=7
Requires-Dist: torch<2.9,>=2.8
Provides-Extra: data
Requires-Dist: pyarrow<24,>=19; extra == 'data'
Provides-Extra: dev
Requires-Dist: pytest>=8.4.0; extra == 'dev'
Requires-Dist: ruff<1,>=0.13; extra == 'dev'
Provides-Extra: qlora
Requires-Dist: accelerate<2,>=1.10; extra == 'qlora'
Requires-Dist: bitsandbytes<1,>=0.48; extra == 'qlora'
Requires-Dist: peft<1,>=0.17; extra == 'qlora'
Requires-Dist: transformers<6,>=5; extra == 'qlora'
Provides-Extra: windows-fusion
Requires-Dist: torch==2.8.0; extra == 'windows-fusion'
Requires-Dist: triton-windows<3.5,>=3.4; (sys_platform == 'win32') and extra == 'windows-fusion'
Description-Content-Type: text/markdown

# MOLT

**Thermally aware, memory-efficient QLoRA fine-tuning for consumer NVIDIA GPUs.**

[![License: PolyForm Shield 1.0.0](https://img.shields.io/badge/License-PolyForm%20Shield%201.0.0-22c55e.svg)](https://github.com/PraveenNimilka/MOLT/blob/v0.11.0-alpha.4/LICENSE)
[![Python: 3.12](https://img.shields.io/badge/Python-3.12-22c55e.svg)](https://github.com/PraveenNimilka/MOLT/blob/v0.11.0-alpha.4/pyproject.toml)
[![Status: Alpha](https://img.shields.io/badge/Status-Alpha-4b5563.svg)](https://github.com/PraveenNimilka/MOLT/blob/v0.11.0-alpha.4/docs/releases/0.11.0-alpha.4.md)
[![Tests](https://github.com/PraveenNimilka/MOLT/actions/workflows/ci.yml/badge.svg)](https://github.com/PraveenNimilka/MOLT/actions/workflows/ci.yml)
[![PyPI: v0.11.0a4](https://img.shields.io/badge/PyPI-v0.11.0a4-blue.svg)](https://pypi.org/project/moltengine/0.11.0a4/)

MOLT provides a Windows-first workflow to prepare data, validate workload fit,
fine-tune supported local language models, safely resume interrupted runs, and
export adapters. It includes hardware telemetry, thermal controls, verified
checkpointing, and experimental optimized execution paths.

**Latest release: 0.11.0a4 · Source-available research alpha.**
Install the versioned release below; `main` may include unreleased changes.
Validate workloads before production use.

## Current evidence

On the development RTX 4060 Laptop GPU, six-pair matched diagnostic screens
produced the following means against the tested Unsloth configuration:

| Model family | Training time | Board energy | PyTorch allocator peak |
| --- | ---: | ---: | ---: |
| Qwen | 38.42% lower | 21.90% lower | 8.13% lower |
| Llama-family | 46.54% lower | 39.23% lower | 5.66% lower |
| Gemma | 73.38% lower | 47.51% lower | 0.47% lower |

![Diagnostic reductions in elapsed time, board energy, and allocator peak, with 95% paired confidence intervals where applicable](https://raw.githubusercontent.com/PraveenNimilka/MOLT/v0.11.0-alpha.4/docs/assets/benchmark-diagnostic-0.11.0a3.svg)

See the [calculation method and machine-readable aggregate](https://github.com/PraveenNimilka/MOLT/blob/v0.11.0-alpha.4/docs/benchmarks/README.md).

Every recorded pair favored MOLT for elapsed time and energy. These results are
diagnostic evidence, not a universal performance claim: graphics clocks were not
locked, one Gemma competitor arm had a power-limit transient, Soup has not yet
been compared, and 7B/8B endurance and independent reproduction remain open.

Public documentation covers supported interfaces, observable behavior, and
reproducible measurements. Internal optimization rationale and development
profiling records are not part of the documented API.

## Requirements

- Windows 10 or Windows 11, 64-bit
- Python 3.12
- A supported NVIDIA GPU and compatible driver
- Git for source installation
- Internet access and several GB of free disk space during installation

Model weights and datasets are not downloaded automatically.

## Installation

### Option 1: PyPI

Open PowerShell and create an isolated environment:

```powershell
py -3.12 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
```

Install the supported CUDA build of PyTorch first, then MOLT:

```powershell
python -m pip install torch==2.8.0 --index-url https://download.pytorch.org/whl/cu128
python -m pip install "moltengine[qlora,data,windows-fusion]==0.11.0a4"
```

Verify the installation:

```powershell
molt --version
molt doctor
```

### Option 2: Reproducible source installation

```powershell
git clone --branch v0.11.0-alpha.4 --depth 1 https://github.com/PraveenNimilka/MOLT.git
Set-Location MOLT
powershell -NoProfile -ExecutionPolicy Bypass -File .\install.ps1
.\.venv\Scripts\molt.exe doctor
```

The installer creates a project-local environment, uses the locked dependency
set, verifies the downloaded bootstrap script, checks CUDA backward execution,
and checks the optimized backend when enabled. It does not modify GPU drivers,
antivirus settings, fan curves, or persistent power settings.

To omit the optional optimized backend:

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File .\install.ps1 -EagerOnly
```

See [the complete installation guide](https://github.com/PraveenNimilka/MOLT/blob/v0.11.0-alpha.4/docs/INSTALL.md) for troubleshooting.

## First training run

### 1. Check the machine

```powershell
molt doctor
molt info
```

Resolve any reported CUDA or optional-dependency error before continuing.

### 2. Prepare a local model

Download a supported Hugging Face-format Qwen, Llama-family, or Gemma-family
model into a local directory. Review and accept the model's own license.

Example layout:

```text
C:\Models\Qwen2.5-0.5B\
  config.json
  tokenizer.json
  model.safetensors
```

### 3. Prepare training data

MOLT accepts UTF-8 `.txt`, `.jsonl`, and `.parquet`. Common `text`, chat
`messages`, and `prompt`/`completion` records are recognized.

```powershell
molt prepare C:\Data\training.jsonl `
  --model C:\Models\Qwen2.5-0.5B `
  --output C:\MoltRuns\prepared
```

The output directory contains prepared token data and a starter `training.json`.
MOLT will not overwrite an existing preparation directory.

### 4. Run a two-step fit test

```powershell
molt fit-test --config C:\MoltRuns\prepared\training.json
```

This validates real forward, backward, and optimizer steps at the configured
geometry. It is not an endurance test.

### 5. Validate without allocating the full workload

```powershell
molt train --config C:\MoltRuns\prepared\training.json --dry-run
```

### 6. Start training

```powershell
molt train --config C:\MoltRuns\prepared\training.json
```

Start with a small context and step count. Model fit depends on architecture,
rank, context, batch size, precision, optimizer, and available VRAM.

### 7. Inspect or resume

```powershell
molt runs
molt resume
```

MOLT stages checkpoints before publication and verifies their recorded hashes
before loading. Integrity checks do not make an untrusted checkpoint authentic.

### 8. Evaluate and export

```powershell
molt evaluate --help
molt export --help
```

QLoRA runs can export a PEFT-compatible safetensors adapter. The original base
model is still required for inference.

Experimental scratch pretraining is limited to MOLT's compact native causal
decoder configuration. It is not presented as a general pretraining framework
for arbitrary third-party architectures.

## Operating safely

- Treat models, datasets, configuration files, and checkpoints as untrusted.
- Do not enable third-party remote model code unless you trust its publisher.
- Keep important checkpoints backed up outside the active run directory.
- Use `molt optimize-gpu` only after reading its prompt and requirements; MOLT
  never changes clock settings implicitly.
- Do not treat a dry run or dependency check as proof that a model fits in VRAM.
- Do not publish private paths, data, credentials, or model weights in bug reports.

Report vulnerabilities through GitHub's private security-advisory workflow.
See [SECURITY.md](https://github.com/PraveenNimilka/MOLT/blob/v0.11.0-alpha.4/SECURITY.md).

## CLI overview

```powershell
molt --help
molt prepare --help
molt fit-test --help
molt train --help
molt resume --help
molt export --help
```

The stable customer path is:

```text
install -> doctor -> prepare -> fit-test -> train -> evaluate -> export
```

Research and benchmark commands are experimental and can change between alpha
releases.

## Release boundary

- Automated tests cover the public runtime and verify that the checked-in
  benchmark figure matches its data. See the release checks for results.
- Static source scanning found no high-severity issue.
- The auditable Python dependency set has no known reported vulnerability.
- GitHub Actions are commit-pinned and PyPI publishing uses short-lived OIDC.
- The final controlled-clock, Soup, large-model endurance, and independent
  comparison gates are not complete.

Read the [0.11.0a4 release notes](https://github.com/PraveenNimilka/MOLT/blob/v0.11.0-alpha.4/docs/releases/0.11.0-alpha.4.md),
[CLI reference](https://github.com/PraveenNimilka/MOLT/blob/v0.11.0-alpha.4/docs/cli.md), [support policy](https://github.com/PraveenNimilka/MOLT/blob/v0.11.0-alpha.4/SUPPORT.md), and
[licensing boundary](https://github.com/PraveenNimilka/MOLT/blob/v0.11.0-alpha.4/docs/licensing.md). Dependency attribution and branding
rules are recorded in [THIRD_PARTY_NOTICES.md](https://github.com/PraveenNimilka/MOLT/blob/v0.11.0-alpha.4/THIRD_PARTY_NOTICES.md) and
[TRADEMARKS.md](https://github.com/PraveenNimilka/MOLT/blob/v0.11.0-alpha.4/TRADEMARKS.md).

## License

Current MOLT source is available under the
[PolyForm Shield License 1.0.0](https://github.com/PraveenNimilka/MOLT/blob/v0.11.0-alpha.4/LICENSE). It is source-available, not OSI open
source, and restricts use to provide a product that competes with the licensor.
Models, datasets, and dependencies retain their own licenses. Public Python
packages can be inspected; the license is a legal boundary, not technical copy
prevention. Obtain qualified legal advice for commercial reliance.
