tensorless 0.1.0__py3-none-any.whl

tensorless/training/trainer.py

@@ -0,0 +1,234 @@
+"""The training loop.
+
+`run_training` is the single entry point that: prepares data, builds (or
+resumes) the model + optimizer, trains with early stopping, checkpoints
+periodically so interrupted runs can resume, and returns everything
+needed to write the final `.tl` file.
+"""
+
+from __future__ import annotations
+
+import time
+from typing import Any, Dict, Optional
+
+import torch
+import torch.nn as nn
+import torch.nn.functional as F
+
+from ..data.loader import Dataset
+from ..devices.device import get_torch_device
+from ..checkpoint.manager import CheckpointManager
+from ..models.registry import build_model
+from ..tokenization.char_tokenizer import CharTokenizer
+from ..data.tabular import TabularPreprocessor
+from .early_stopping import EarlyStopping
+from . import data_prep as dp
+
+
+def _build_optimizer(model: nn.Module, cfg: Dict[str, Any]) -> torch.optim.Optimizer:
+    name = cfg["optimizer"].lower()
+    lr = cfg["learning_rate"]
+    wd = cfg["weight_decay"]
+    if name == "adamw":
+        return torch.optim.AdamW(model.parameters(), lr=lr, weight_decay=wd)
+    elif name == "adam":
+        return torch.optim.Adam(model.parameters(), lr=lr, weight_decay=wd)
+    elif name == "sgd":
+        return torch.optim.SGD(model.parameters(), lr=lr, momentum=0.9, weight_decay=wd)
+    else:
+        raise ValueError(f"Unknown optimizer '{name}'")
+
+
+def _lr_lambda(step: int, warmup_steps: int, total_steps: int) -> float:
+    if warmup_steps > 0 and step < warmup_steps:
+        return (step + 1) / warmup_steps
+    if total_steps <= warmup_steps:
+        return 1.0
+    progress = (step - warmup_steps) / max(1, total_steps - warmup_steps)
+    return max(0.1, 1.0 - progress)
+
+
+def _compute_loss(task: str, model_type: str, model: nn.Module, batch, device, pad_id: int) -> torch.Tensor:
+    if model_type == "transformer" and task == "text-generation":
+        x, y = batch
+        x, y = x.to(device), y.to(device)
+        logits = model(x)
+        loss = F.cross_entropy(
+            logits.reshape(-1, logits.size(-1)), y.reshape(-1), ignore_index=pad_id
+        )
+        return loss
+    elif model_type == "transformer" and task == "text-classification":
+        input_ids, attn_mask, labels = batch
+        input_ids, attn_mask, labels = input_ids.to(device), attn_mask.to(device), labels.to(device)
+        logits = model(input_ids, attention_mask=attn_mask)
+        return F.cross_entropy(logits, labels)
+    elif model_type == "mlp" and task == "classification":
+        numeric, categorical, target = batch
+        numeric, categorical, target = numeric.to(device), categorical.to(device), target.to(device)
+        logits = model(numeric, categorical)
+        return F.cross_entropy(logits, target)
+    elif model_type == "mlp" and task == "regression":
+        numeric, categorical, target = batch
+        numeric, categorical, target = numeric.to(device), categorical.to(device), target.to(device)
+        pred = model(numeric, categorical)
+        return F.mse_loss(pred, target)
+    else:
+        raise ValueError(f"Unsupported task/model_type combination: {task}/{model_type}")
+
+
+def run_training(
+    ds: Dataset,
+    cfg: Dict[str, Any],
+    checkpoint_mgr: CheckpointManager,
+    dataset_fingerprint: str,
+    resume_state: Optional[Dict[str, Any]] = None,
+    log_fn=print,
+) -> Dict[str, Any]:
+    task = cfg["task"]
+    model_type = cfg["model_type"]
+    torch.manual_seed(cfg["seed"])
+
+    device = get_torch_device(cfg["device"])
+    if cfg["verbose"]:
+        log_fn(f"[tensorless] task={task} model={model_type} device={cfg['device']} precision={cfg['precision']}")
+
+    # ---- data prep (resume tokenizer/preprocessor if available) ----
+    tokenizer = None
+    preprocessor = None
+    if resume_state is not None:
+        if resume_state.get("tokenizer_state") is not None:
+            tokenizer = CharTokenizer.from_state_dict(resume_state["tokenizer_state"])
+        if resume_state.get("preprocessor_state") is not None:
+            preprocessor = TabularPreprocessor.from_state_dict(resume_state["preprocessor_state"])
+
+    if task == "text-generation":
+        prepared = dp.prepare_text_generation(ds, cfg, tokenizer=tokenizer)
+    elif task == "text-classification":
+        classes = resume_state["meta"]["classes"] if resume_state else None
+        prepared = dp.prepare_text_classification(ds, cfg, tokenizer=tokenizer, classes=classes)
+    elif task in ("classification", "regression"):
+        prepared = dp.prepare_tabular(ds, cfg, task=task, preprocessor=preprocessor)
+    else:
+        raise ValueError(f"Unsupported task '{task}'")
+
+    # ---- model / optimizer / scheduler ----
+    model = build_model(task, model_type, cfg, prepared.meta).to(device)
+    optimizer = _build_optimizer(model, cfg)
+
+    steps_per_epoch = max(1, len(prepared.train_loader))
+    total_steps = cfg.get("max_steps") or steps_per_epoch * cfg["epochs"]
+    scheduler = torch.optim.lr_scheduler.LambdaLR(
+        optimizer, lr_lambda=lambda s: _lr_lambda(s, cfg["warmup_steps"], total_steps)
+    )
+
+    early_stopper = EarlyStopping(patience=cfg["patience"], min_delta=cfg["min_delta"])
+    start_epoch = 0
+    global_step = 0
+
+    if resume_state is not None:
+        model.load_state_dict(resume_state["model_state_dict"])
+        optimizer.load_state_dict(resume_state["optimizer_state_dict"])
+        scheduler.load_state_dict(resume_state["scheduler_state_dict"])
+        start_epoch = resume_state["epoch"]
+        global_step = resume_state["global_step"]
+        early_stopper.best = resume_state.get("early_stopping_best", float("inf"))
+        early_stopper.num_bad_checks = resume_state.get("early_stopping_bad_checks", 0)
+        if cfg["verbose"]:
+            log_fn(f"[tensorless] resuming from checkpoint: epoch={start_epoch}, step={global_step}")
+
+    pad_id = prepared.meta.get("pad_id", 0)
+
+    def _checkpoint(epoch: int, training_complete: bool) -> None:
+        state = {
+            "epoch": epoch,
+            "global_step": global_step,
+            "model_state_dict": model.state_dict(),
+            "optimizer_state_dict": optimizer.state_dict(),
+            "scheduler_state_dict": scheduler.state_dict(),
+            "early_stopping_best": early_stopper.best,
+            "early_stopping_bad_checks": early_stopper.num_bad_checks,
+            "config": cfg,
+            "meta": prepared.meta,
+            "tokenizer_state": prepared.tokenizer.state_dict() if prepared.tokenizer else None,
+            "preprocessor_state": prepared.preprocessor.state_dict() if prepared.preprocessor else None,
+            "dataset_fingerprint": dataset_fingerprint,
+            "training_complete": training_complete,
+        }
+        checkpoint_mgr.save(state)
+
+    # ---- training loop ----
+    model.train()
+    stop = False
+    t0 = time.time()
+    last_val_loss = None
+    last_train_loss = None
+
+    for epoch in range(start_epoch, cfg["epochs"]):
+        for batch in prepared.train_loader:
+            loss = _compute_loss(task, model_type, model, batch, device, pad_id)
+            last_train_loss = loss.item()
+            optimizer.zero_grad()
+            loss.backward()
+            if cfg["grad_clip"]:
+                torch.nn.utils.clip_grad_norm_(model.parameters(), cfg["grad_clip"])
+            optimizer.step()
+            scheduler.step()
+            global_step += 1
+
+            if global_step % cfg["checkpoint_every"] == 0:
+                _checkpoint(epoch, training_complete=False)
+
+            if cfg.get("max_steps") and global_step >= cfg["max_steps"]:
+                stop = True
+                break
+        if stop:
+            break
+
+        # ---- validation / early stopping ----
+        if prepared.val_loader is not None:
+            model.eval()
+            losses = []
+            with torch.no_grad():
+                for batch in prepared.val_loader:
+                    losses.append(_compute_loss(task, model_type, model, batch, device, pad_id).item())
+            val_loss = sum(losses) / max(1, len(losses))
+            last_val_loss = val_loss
+            model.train()
+            is_best = early_stopper.step(val_loss, state=None)
+            if cfg["verbose"]:
+                log_fn(
+                    f"[tensorless] epoch {epoch + 1}/{cfg['epochs']} "
+                    f"train_loss={last_train_loss:.4f} val_loss={val_loss:.4f}"
+                    f"{' (best)' if is_best else ''}"
+                )
+            if early_stopper.should_stop:
+                if cfg["verbose"]:
+                    log_fn(f"[tensorless] early stopping at epoch {epoch + 1} (no improvement)")
+                _checkpoint(epoch, training_complete=True)
+                break
+        else:
+            if cfg["verbose"]:
+                log_fn(f"[tensorless] epoch {epoch + 1}/{cfg['epochs']} train_loss={last_train_loss:.4f}")
+
+        _checkpoint(epoch + 1, training_complete=(epoch + 1 >= cfg["epochs"]))
+
+    elapsed = time.time() - t0
+    if cfg["verbose"]:
+        log_fn(f"[tensorless] training finished in {elapsed:.1f}s ({global_step} steps)")
+
+    metrics = {
+        "final_train_loss": last_train_loss,
+        "final_val_loss": last_val_loss,
+        "global_step": global_step,
+        "elapsed_seconds": elapsed,
+    }
+
+    return {
+        "model": model,
+        "model_state_dict": model.state_dict(),
+        "meta": prepared.meta,
+        "tokenizer": prepared.tokenizer,
+        "preprocessor": prepared.preprocessor,
+        "metrics": metrics,
+        "device": device,
+    }

tensorless-0.1.0.dist-info/METADATA

@@ -0,0 +1,111 @@
+Metadata-Version: 2.4
+Name: tensorless
+Version: 0.1.0
+Summary: ML with maximum automation and minimum setup.
+Author: Tensorless Contributors
+License: MIT
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: torch>=2.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Dynamic: license-file
+
+# Tensorless
+
+**ML with maximum automation and minimum setup.**
+
+```python
+import tensorless as tl
+
+tl.train("./data")
+```
+
+That's it. Tensorless inspects your dataset, figures out what kind of
+task you're trying to solve, builds and configures a model, trains it,
+validates it, checkpoints it, and saves a single portable `model.tl`
+file you can move anywhere.
+
+```python
+model = tl.run("model.tl")   # interactive chat, if it's a text model
+# or
+model = tl.load("model.tl")
+model.predict(...)
+```
+
+Simple by default. Powerful when you need it:
+
+```python
+tl.train(
+    "./data",
+    d_model=512,
+    layers=6,
+    learning_rate=3e-4,
+    batch_size=32,
+)
+```
+
+## Why Tensorless
+
+Most ML frameworks assume you already know what model you want, how big
+it should be, which optimizer and learning rate to use, and how to wire
+up checkpointing and resumption yourself. Tensorless flips that: it
+makes a reasonable, working choice for all of that automatically, and
+lets you override exactly the parts you care about.
+
+It also remembers what it already did. Run `tl.train("./data")` twice on
+the same dataset and it won't retrain — it'll just hand you back the
+model it already trained. Change the data, and it retrains. Get
+interrupted partway through a long run, and the next call resumes right
+where it left off. This is the **Smart Auto Check**, and it's the core
+idea the whole framework is built around.
+
+## Install
+
+```bash
+pip install -e .
+```
+
+See [docs/installation.md](docs/installation.md) for details and
+requirements.
+
+## Documentation
+
+| Doc | What's in it |
+|---|---|
+| [Installation](docs/installation.md) | Requirements, install steps, verifying your setup |
+| [Quick Start](docs/quickstart.md) | The fastest path to a trained model |
+| [Beginner Tutorial](docs/tutorial.md) | A guided, from-scratch walkthrough |
+| [Automatic Mode](docs/automatic_mode.md) | How auto-detection and auto-configuration work, and the Smart Auto Check |
+| [Training](docs/training.md) | `tl.train()` in depth, all supported tasks and data formats |
+| [Inference](docs/inference.md) | `tl.run()`, `tl.load()`, and the prediction API |
+| [Checkpointing & Resume](docs/checkpointing.md) | How checkpoints work and how resumption is decided |
+| [The `.tl` Format](docs/tl_format.md) | What's inside a `.tl` file and why it's portable |
+| [Configuration](docs/configuration.md) | Every override you can pass, and what it does |
+| [CLI](docs/cli.md) | `tensorless train / run / inspect / info` |
+| [API Reference](docs/api_reference.md) | Full function/class signatures |
+| [Examples](docs/examples.md) | Worked examples for each supported task |
+| [Troubleshooting](docs/troubleshooting.md) | Common errors and what to do about them |
+| [Architecture](docs/architecture.md) | How the codebase is organized, for contributors |
+| [Contributing](docs/contributing.md) | How to add models, backends, or data formats |
+| [Roadmap](docs/roadmap.md) | What's planned |
+| [Limitations](docs/limitations.md) | What Tensorless deliberately doesn't do (yet) |
+
+## Supported today
+
+- **Text generation** (language modeling) from `.txt`/`.md` files or JSON/JSONL with a `text` field
+- **Text classification** from a directory of class subfolders (`positive/`, `negative/`, ...) or labeled JSON/JSONL
+- **Tabular classification and regression** from CSV/TSV/JSON/JSONL with a target column
+
+## Project status
+
+Tensorless is an early-stage, actively developed framework. The core
+loop — inspect, auto-configure, train, checkpoint, save, reload, infer —
+is real and tested end-to-end (see [tests/](tests/)). See
+[docs/limitations.md](docs/limitations.md) for what's intentionally out
+of scope right now, and [docs/roadmap.md](docs/roadmap.md) for what's next.
+
+## License
+
+MIT

tensorless-0.1.0.dist-info/RECORD

@@ -0,0 +1,38 @@
+tensorless/__init__.py,sha256=iNj7LjFkWkVXaDR9SIwDitpOwyXzKxcZKLDDih2VWt0,701
+tensorless/_version.py,sha256=po3YK2JiKEcipFrlKt1aaEDfkSF_VT1s5zH4SW3ta8E,224
+tensorless/api.py,sha256=zoEh4nKFa8XayVFapaaSAgD9YHFvxFl96xwTyWC8GA4,8707
+tensorless/config.py,sha256=muhxE11UMdFkw1DDh846_0w4tM2BofT1zJ5L4t05T3M,3703
+tensorless/errors.py,sha256=txzlMyNC_R7FdVxX3wbu46vYC02eGaWzFXPuTw7Pqk8,902
+tensorless/runtime.py,sha256=ZNSrTIDf9A3W8OP8s3bsaFNwNnJnmgbV53DMi6fk-P8,6858
+tensorless/auto/__init__.py,sha256=ZkV-4-VQul6gfkwiX90y6miW-ISIkXdK8uV5rfUSXZQ,114
+tensorless/auto/config.py,sha256=zi9L4o7KuzU6iFL-Lhwadta1MldzAhbeu29zY3zTMiw,3905
+tensorless/auto/detector.py,sha256=o_IPLT-M6uPG6pQAfNRES_z-DNe9SiQX9-92wgOy7Ik,3186
+tensorless/checkpoint/__init__.py,sha256=pyEWGR1upD_HTjG90dW1Bosbk4vbKm_8Fpn1JLdl2WA,72
+tensorless/checkpoint/manager.py,sha256=OOyExS6Mi2pWVSmrPX59jVcEBWbDSLAZTjmrif7hrQY,2343
+tensorless/cli/__init__.py,sha256=9EVxmFiWsAoqWJ6br1bc3BxlA71JyOQP28fUHhX2k7E,43
+tensorless/cli/main.py,sha256=iKBllAKmRkR6MjaC4o4DUq3Xr8TwWT4qKh43QOYZIOQ,4399
+tensorless/data/__init__.py,sha256=737HGk7mGC1qjJNte51YFFnBuelhC3HhctO0mehzJwg,256
+tensorless/data/fingerprint.py,sha256=UdnDB-Ii5Vm31QO2pO26cuMPFd4ROfxbklBcBBu-ors,2449
+tensorless/data/inspector.py,sha256=HUfx0M0TkQDDwAavsfOAxSqkrtwCn3VcX3Yy-ZckaWA,5406
+tensorless/data/loader.py,sha256=2zCmI9mXO0lkdPHfaTAGa8qfnbmAz2xy7CuuiJj3978,9201
+tensorless/data/tabular.py,sha256=0FQ1dE9Uz1K9HTu_N1QzzKfalu-2bkoy8DGKpbfDmjI,6953
+tensorless/devices/__init__.py,sha256=pxVve4VnSZn3T6ou31lbap7NDXokkdN9HUkMSxAbwPE,111
+tensorless/devices/device.py,sha256=3zxuV-tjyWJ3ffMgEOTii4ucS3xH-Jkr5KQijsQmXas,3150
+tensorless/models/__init__.py,sha256=_yOv4b3szXxd5a05BNvYS8oKIn4bOMVekKsz1ise_XE,163
+tensorless/models/mlp.py,sha256=FML511OOEeFvD5eA08kSVgumn4HOjWp4RyiLYC2yImY,2019
+tensorless/models/registry.py,sha256=ZrNARaQEgyvACiVPYKdT9JMXjtxia42wE9MeEJao6PY,1862
+tensorless/models/transformer.py,sha256=IZr3x-iM87qRNiET0512QzGX23KE16GestuZBk-0Lks,6669
+tensorless/serialization/__init__.py,sha256=jsPMigSc4vU3P2DJBy1nbw762LcDNmqFenXv1iMTtfo,74
+tensorless/serialization/tl_format.py,sha256=Yop7VpVej2Lc0rsaRRwySwlMLzcCZB5g9cLZBZctAG8,2930
+tensorless/tokenization/__init__.py,sha256=MNnWY_R9RjIGx_WkzjhS_isUKxVQWq3SB8VBKXiS5z4,71
+tensorless/tokenization/char_tokenizer.py,sha256=sJdlt4MQfpNdFTapX6IH2d7QCel3ppnFHIcK3Oko_rU,2601
+tensorless/training/__init__.py,sha256=p7DBWI6lYwQJ7EnSBFUf2cerAqDDqDmIzXBqyzBDYbk,121
+tensorless/training/data_prep.py,sha256=jJ3t8CZ6eYj7CSZ25lXJNJC4N7wS_qIwSFE0g8oBZmY,7384
+tensorless/training/early_stopping.py,sha256=kqaeU_L2jQLtaBgWfzxeYemofwLxUe7GWiSCGEyhz9E,999
+tensorless/training/trainer.py,sha256=99fkkL0EKGP5Q13sz2wE0R2ATtzR0DgjlFen9HbrSQ4,9469
+tensorless-0.1.0.dist-info/licenses/LICENSE,sha256=REl9_4muewZT_xO8osRhVQi4anHcbxh4C2hYMMLYnAE,1080
+tensorless-0.1.0.dist-info/METADATA,sha256=66Q1GZ6FISDysqWkRB50APV_bFYP0CRo5fk0KmtLTqg,4108
+tensorless-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+tensorless-0.1.0.dist-info/entry_points.txt,sha256=LaYKVgR59khkVHc_EUi8Ls_OxrjI-oxwsL3UduwoQDc,56
+tensorless-0.1.0.dist-info/top_level.txt,sha256=hyLdNLPR3-nmOST5BedRzsOVWVYc24GVsUCkjBKsTuY,11
+tensorless-0.1.0.dist-info/RECORD,,

tensorless-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

tensorless-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+tensorless = tensorless.cli.main:main

tensorless-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tensorless Contributors
+
+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.

tensorless-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+tensorless