README.md

---
title: MLOL — MultiDomain LLM Optimisation Lab
emoji: 🧪
colorFrom: green
colorTo: gray
sdk: gradio
sdk_version: 5.34.2
app_file: app.py
pinned: false
license: apache-2.0
---

# 🧪 MLOL — MultiDomain LLM Optimisation Lab

A complete LLM fine-tuning and optimisation laboratory on a Hugging Face Space:

```
Choose Base Model → Upload Dataset → Validation & Cleaning → Configure →
Hardware Recommendation → Baseline Eval → Fine-Tune → Post-Eval →
Comparison → Optimisation Analysis → Performance Certificate → Report → Deploy
```

**Design:** the Space is the *control plane*. Training runs on the right
backend per the routing engine — ZeroGPU for bounded demos (≤1.5B), pinned
Colab export packages (free), or HF Jobs (managed). All experiment state
persists to a private Hub dataset repo; the Space is stateless and
restart-safe. Full blueprint: [docs/MASTER_SPEC.md](docs/MASTER_SPEC.md) ·
usage: [docs/USER_GUIDE.md](docs/USER_GUIDE.md).

## Modules

Home · **Tier 1 — General Fine-Tuning Lab** · **Tier 2 — Domain Foundry**
(premium; 11 domains) · Evaluation Lab (seeded samples, CIs, paired
significance tests) · Reports (9-section Model Performance Certificate,
PDF/CSV/JSON) · Adapter Library · Hardware Advisor · Documentation ·
**AI Research Assistant** (bottom-right; General/Experiment/Hardware/Report
modes, config-driven providers).

Model and provider catalogues are **pure configuration** (`configs/*.yaml`) —
add newly released models with zero code changes.

## Space setup

- **Hardware:** ZeroGPU (PRO) recommended; works on CPU with reduced function.
- **Secrets:** `HF_TOKEN` (gated models + Hub persistence),
  `PREMIUM_ACCESS_CODES` (Tier 2 gate; unset = open dev mode).
- Premium / custom domains: **finpy07@gmail.com**.

## Repo layout

```
app.py                      # UI (control plane only)
configs/                    # models, providers, domains, hardware, limits
src/schemas.py              # Pydantic configs + experiment manifest/state machine
src/config_loader.py        # startup schema validation
src/services/               # persistence, dataset_prep, routing, training
                            # backends (mock/zerogpu/colab/jobs), evaluation,
                            # reporting, assistant
src/inference/engine.py     # base+adapter inference
src/data/, src/training/    # legacy FinLLM pipeline (reused as training payload)
docs/MASTER_SPEC.md         # the binding blueprint (v1.1)
```

> Research platform — outputs are not investment, legal, medical, or other
> professional advice.