tensorless-pytorch 0.1.0__tar.gz

tensorless_pytorch-0.1.0/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_pytorch-0.1.0/MANIFEST.in

@@ -0,0 +1,5 @@
+include README.md
+include LICENSE
+include pyproject.toml
+recursive-include docs *.md
+recursive-include examples *.py

tensorless_pytorch-0.1.0/PKG-INFO

@@ -0,0 +1,82 @@
+Metadata-Version: 2.4
+Name: tensorless-pytorch
+Version: 0.1.0
+Summary: Automatic PyTorch training with portable models and minimal setup.
+Author: Tensorless PyTorch 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 PyTorch
+
+Tensorless PyTorch is a lightweight toolkit for turning ordinary text and
+tabular data into portable PyTorch models with minimal setup. It supports text
+generation, text classification, tabular classification, and regression.
+
+The distribution is installed as `tensorless-pytorch`; the stable Python import
+remains `tensorless` for compatibility.
+
+## Install
+
+```bash
+pip install tensorless-pytorch
+```
+
+## Train on your data
+
+```python
+import tensorless as tl
+
+model = tl.train("./corpus.txt", task="text-generation")
+print(model.generate("The", max_new_tokens=40))
+```
+
+Text files are trained as next-token language models. BPE is the default
+tokenizer; use `tokenizer="char"` for a character-level model. Tensorless PyTorch
+derives model size, batch size, epochs, validation, device, and BPE vocabulary
+size from the data, while every setting can be overridden.
+
+Long text is tokenized lazily and fed through PyTorch in fixed-size batches.
+CUDA training automatically uses `fp16` or `bf16` when supported, including
+gradient scaling and checkpointed scaler state. Reduce `batch_size` if memory
+is limited.
+
+## English starter pretraining
+
+```python
+import tensorless as tl
+
+model = tl.pretrain(out="english.tl", epochs=20, max_seq_len=128)
+print(model.generate("A complete sentence", max_new_tokens=30))
+```
+
+This offline starter corpus contains English prose and grammar examples. It is
+for demos and smoke tests, not a replacement for a large language dataset. For
+real pretraining, pass your own `.txt` corpus to `tl.train()` and increase the
+training settings as your hardware allows.
+
+## Other tasks
+
+```python
+tl.train("reviews/", task="text-classification")
+tl.train("housing.csv", task="regression")
+```
+
+Tabular preprocessing automatically handles numeric values, ISO dates, and
+high-cardinality categories. Missing and rare values are handled using the
+fitted training data, and the same preprocessing is stored in the `.tl` file.
+
+Models are saved as `.tl` files and can be loaded later:
+
+```python
+model = tl.load("model.tl")
+print(model.info())
+```
+
+See the [documentation](docs/quickstart.md) for data formats, configuration,
+mixed precision, checkpointing, and the command-line interface.

tensorless_pytorch-0.1.0/README.md

@@ -0,0 +1,68 @@
+# Tensorless PyTorch
+
+Tensorless PyTorch is a lightweight toolkit for turning ordinary text and
+tabular data into portable PyTorch models with minimal setup. It supports text
+generation, text classification, tabular classification, and regression.
+
+The distribution is installed as `tensorless-pytorch`; the stable Python import
+remains `tensorless` for compatibility.
+
+## Install
+
+```bash
+pip install tensorless-pytorch
+```
+
+## Train on your data
+
+```python
+import tensorless as tl
+
+model = tl.train("./corpus.txt", task="text-generation")
+print(model.generate("The", max_new_tokens=40))
+```
+
+Text files are trained as next-token language models. BPE is the default
+tokenizer; use `tokenizer="char"` for a character-level model. Tensorless PyTorch
+derives model size, batch size, epochs, validation, device, and BPE vocabulary
+size from the data, while every setting can be overridden.
+
+Long text is tokenized lazily and fed through PyTorch in fixed-size batches.
+CUDA training automatically uses `fp16` or `bf16` when supported, including
+gradient scaling and checkpointed scaler state. Reduce `batch_size` if memory
+is limited.
+
+## English starter pretraining
+
+```python
+import tensorless as tl
+
+model = tl.pretrain(out="english.tl", epochs=20, max_seq_len=128)
+print(model.generate("A complete sentence", max_new_tokens=30))
+```
+
+This offline starter corpus contains English prose and grammar examples. It is
+for demos and smoke tests, not a replacement for a large language dataset. For
+real pretraining, pass your own `.txt` corpus to `tl.train()` and increase the
+training settings as your hardware allows.
+
+## Other tasks
+
+```python
+tl.train("reviews/", task="text-classification")
+tl.train("housing.csv", task="regression")
+```
+
+Tabular preprocessing automatically handles numeric values, ISO dates, and
+high-cardinality categories. Missing and rare values are handled using the
+fitted training data, and the same preprocessing is stored in the `.tl` file.
+
+Models are saved as `.tl` files and can be loaded later:
+
+```python
+model = tl.load("model.tl")
+print(model.info())
+```
+
+See the [documentation](docs/quickstart.md) for data formats, configuration,
+mixed precision, checkpointing, and the command-line interface.

tensorless_pytorch-0.1.0/docs/api_reference.md

@@ -0,0 +1,103 @@
+# API Reference
+
+## `tensorless.train(path, **kwargs) -> LoadedModel`
+
+Train a model on the dataset at `path`. See
+[configuration.md](configuration.md) for every valid keyword argument.
+Implements the Smart Auto Check (see [automatic_mode.md](automatic_mode.md)).
+
+Raises:
+- `tensorless.DataError` — dataset missing, empty, malformed, or unsupported format
+- `tensorless.ConfigError` — invalid/unknown config argument, or dataset changed with `ask_on_data_change=True`
+- `tensorless.CheckpointError` — an existing checkpoint is corrupt or unreadable
+- `tensorless.SerializationError` — an existing `.tl` file is corrupt
+
+## `tensorless.inspect(path) -> InspectionReport`
+
+Load and analyze a dataset without training. Prints a human-readable
+report and returns a structured object.
+
+```python
+@dataclass
+class InspectionReport:
+    path: str
+    fingerprint: str
+    kind: str              # "text" | "text_labeled" | "tabular"
+    task: str               # "text-generation" | "text-classification" | "classification" | "regression"
+    n_examples: int
+    n_files: int
+    columns: List[str]
+    sample: Any
+    warnings: List[str]
+    recommendations: List[str]
+    stats: Dict[str, Any]
+```
+
+## `tensorless.load(path, device=None) -> LoadedModel`
+
+Load a trained `.tl` file for inference. `device` overrides the device
+recorded at training time (e.g. load a GPU-trained model on a CPU-only
+machine with `device="cpu"`).
+
+Raises `tensorless.SerializationError` if the file is missing, corrupt,
+or from an unsupported future format version.
+
+## `tensorless.run(path, prompt=None) -> Any`
+
+Convenience wrapper around `load()` for quick command-line-style usage.
+See [inference.md](inference.md#tlrun--the-cli-friendly-shortcut).
+
+## `class tensorless.runtime.LoadedModel`
+
+Returned by both `train()` and `load()`.
+
+| Method | Applies to | Description |
+|---|---|---|
+| `.generate(prompt="", max_new_tokens=200, temperature=0.8, top_k=40)` | `text-generation` | Generate a text continuation |
+| `.chat()` | `text-generation` | Interactive terminal chat loop |
+| `.predict(x)` | all tasks | Unified prediction API; `x` is a string (text tasks) or dict/list-of-dicts (tabular tasks) |
+| `.info()` | all | Dict summary: task, model type, versions, config, metrics, param count |
+
+Attributes: `.task`, `.model_type`, `.config`, `.meta`, `.metrics`,
+`.dataset_fingerprint`, `.model` (the underlying `torch.nn.Module`),
+`.tokenizer` (`CharTokenizer` or `None`), `.preprocessor`
+(`TabularPreprocessor` or `None`).
+
+## `class tensorless.TrainConfig`
+
+The dataclass of every trainable override; see
+[configuration.md](configuration.md) for field-by-field defaults.
+
+## Errors — `tensorless.errors`
+
+All Tensorless PyTorch exceptions inherit from `TensorlessError`:
+
+```python
+try:
+    tl.train("./data")
+except tl.TensorlessError as e:
+    ...
+```
+
+| Class | Raised when |
+|---|---|
+| `DataError` | Dataset can't be read, is empty, or is malformed |
+| `ConfigError` | Invalid/unknown configuration, or a Smart-Auto-Check conflict |
+| `ModelError` | Unsupported task/model combination, or a runtime prediction-API misuse |
+| `CheckpointError` | Checkpoint missing, corrupt, or incompatible |
+| `SerializationError` | `.tl` file can't be written or read |
+
+## Lower-level modules
+
+These aren't part of the stable public API but are documented here for
+contributors — see [architecture.md](architecture.md) for how they fit
+together:
+
+- `tensorless.data.loader.load_dataset(path) -> Dataset`
+- `tensorless.data.fingerprint.fingerprint_path(path) -> str`
+- `tensorless.auto.detector.detect_task(ds) -> str`
+- `tensorless.auto.config.resolve_config(ds, TrainConfig) -> ResolvedConfig`
+- `tensorless.models.registry.build_model(task, model_type, cfg, meta) -> nn.Module`
+- `tensorless.training.trainer.run_training(...) -> dict`
+- `tensorless.checkpoint.manager.CheckpointManager`
+- `tensorless.serialization.tl_format.save_tl(path, payload)` / `load_tl(path) -> dict`

tensorless_pytorch-0.1.0/docs/architecture.md

@@ -0,0 +1,126 @@
+# Architecture
+
+This page is for people extending or contributing to Tensorless PyTorch, not
+end users.
+
+## Package layout
+
+```
+tensorless/
+├── __init__.py           public API surface: train, run, load, inspect
+├── api.py                 orchestration for train()/run(): Smart Auto Check + wiring
+├── config.py               TrainConfig (user-facing) / ResolvedConfig (fully resolved)
+├── errors.py                exception hierarchy
+├── runtime.py               LoadedModel: rebuilds a model from a .tl payload for inference
+├── _version.py               package + .tl format version numbers
+├── data/
+│   ├── loader.py              path -> Dataset (txt/json/jsonl/csv/dirs)
+│   ├── fingerprint.py          content-based dataset hashing
+│   ├── inspector.py             tl.inspect() report generation
+│   └── tabular.py                 TabularPreprocessor: numeric/categorical encoding
+├── auto/
+│   ├── detector.py               Dataset -> task string
+│   └── config.py                   Dataset + TrainConfig -> ResolvedConfig
+├── tokenization/
+│   ├── char_tokenizer.py          CharTokenizer: vocab build/encode/decode/save/load
+│   └── bpe_tokenizer.py           BPETokenizer: corpus-trained subword encoding
+├── models/
+│   ├── transformer.py              TinyTransformer (GPT-style decoder)
+│   ├── mlp.py                       TabularMLP
+│   └── registry.py                   build_model(task, model_type, cfg, meta)
+├── training/
+│   ├── data_prep.py                  Dataset -> DataLoaders per task
+│   ├── trainer.py                     the training loop (run_training)
+│   └── early_stopping.py               EarlyStopping
+├── checkpoint/
+│   └── manager.py                      CheckpointManager: atomic save/load/clear
+├── serialization/
+│   └── tl_format.py                     save_tl/load_tl: the .tl file format
+├── devices/
+│   └── device.py                         hardware auto-detection + torch.device resolution
+└── cli/
+    └── main.py                            argparse-based CLI
+```
+
+## Data flow for `tl.train("./data")`
+
+```
+path
+  │
+  ▼
+data.loader.load_dataset(path)          -> Dataset (kind, texts/records, columns)
+  │
+  ▼
+auto.detector.detect_task(ds)           -> "text-generation" | "text-classification"
+  │                                          | "classification" | "regression"
+  ▼
+auto.config.resolve_config(ds, TrainConfig) -> ResolvedConfig (every field concrete)
+  │
+  ▼
+training.data_prep.prepare_*(ds, cfg)   -> PreparedData (train/val DataLoaders,
+  │                                          meta, tokenizer/preprocessor)
+  ▼
+models.registry.build_model(task, model_type, cfg, meta) -> nn.Module
+  │
+  ▼
+training.trainer.run_training(...)      -> trains, checkpoints periodically,
+  │                                          returns final weights + metrics
+  ▼
+serialization.tl_format.save_tl(out, payload) -> model.tl
+  │
+  ▼
+runtime.LoadedModel(payload)            -> returned to the caller
+```
+
+`api.train()` wraps this whole flow with the Smart Auto Check (see
+[automatic_mode.md](automatic_mode.md)): before any of the above runs,
+it checks for an existing complete `.tl` file or a resumable checkpoint
+matching the dataset's fingerprint.
+
+## Design principles
+
+- **Every automatic decision is explainable.** Auto-detection and
+  auto-configuration are simple, inspectable heuristics (see
+  `auto/detector.py`, `auto/config.py`), not opaque search or ML-driven
+  meta-learning. Anyone reading the code can predict what Tensorless PyTorch
+  will choose for a given dataset.
+- **Never silently touch user data.** `data/loader.py` only reads;
+  nothing in the training path writes to or deletes files under the
+  dataset path.
+- **Fail with actionable errors.** All user-facing errors are
+  `TensorlessError` subclasses with messages that say what's wrong and
+  usually what to do about it (see `errors.py` and
+  [troubleshooting.md](troubleshooting.md)).
+- **Checkpoints are self-describing.** A checkpoint carries its own
+  config, meta, and dataset fingerprint, so resuming never depends on
+  external state being reconstructed correctly by the caller.
+- **A `.tl` file is the unit of portability.** Nothing about inference
+  should require the original dataset, training script, or checkpoint
+  directory to still exist.
+
+## Extending Tensorless PyTorch
+
+### Adding a new model type
+
+1. Implement your `nn.Module` in `models/your_model.py`.
+2. Register it in `models/registry.py`'s `build_model()`.
+3. Add a branch in `training/trainer.py`'s `_compute_loss()` for how to
+   compute loss for your task/model_type combination.
+4. If it needs new data prep, add a `prepare_*()` function in
+   `training/data_prep.py`.
+5. If it changes what needs to go in the `.tl` file, extend the `meta`
+   dict produced by data prep — `build_model()` receives it and can pull
+   out whatever fields it needs.
+
+### Adding a new data format
+
+Add a branch to `data/loader.py`'s `load_dataset()` / `_load_directory()`
+for the new extension, producing a `Dataset` with the appropriate `kind`.
+
+### Adding a new backend/device
+
+Extend `devices/device.py`'s `_*_available()` checks and
+`auto_select_device()` / `get_torch_device()`.
+
+See [contributing.md](contributing.md) for the contribution process
+itself (tests, PRs, etc).

tensorless_pytorch-0.1.0/docs/automatic_mode.md

@@ -0,0 +1,109 @@
+# Automatic Mode
+
+Tensorless PyTorch's whole premise is that `tl.train("./data")` should just
+work. This page explains exactly what "automatic" means at each stage,
+so the behavior is predictable rather than magic.
+
+## 1. Task detection
+
+`tensorless/auto/detector.py` looks at the *shape* of your loaded
+dataset (see [training.md](training.md#supported-data-formats) for how
+data is loaded) and picks one of four tasks:
+
+| Dataset shape | Detected task |
+|---|---|
+| Plain text (one or more `.txt`/`.md` files, or JSON/JSONL records with a `text` field and no label) | `text-generation` |
+| Text with labels (class subfolders, or JSON/JSONL with `text` + `label`) | `text-classification` |
+| Tabular data whose target column is numeric with many distinct values | `regression` |
+| Tabular data whose target column is categorical, or numeric with few distinct integer values | `classification` |
+
+The target column for tabular data is chosen by looking for a column
+named `label`, `target`, `class`, `category`, `y`, or `output` (case
+insensitive); if none of those exist, the **last column** in the file is
+used, which is a common convention in tabular datasets.
+
+You can always override detection explicitly: `tl.train("./data",
+task="regression")`.
+
+## 2. Architecture selection
+
+Once the task is known, `tensorless/auto/config.py` picks:
+
+- **model type**: `transformer` for text tasks, `mlp` for tabular tasks
+- **size** (`d_model`, `layers`, `heads`): scaled to dataset size, from
+  a tiny 2-layer/64-dim model for a few hundred effective text examples up to an
+  8-layer/384-dim model for 50,000+ examples
+
+For text corpora, effective examples include corpus character count, so a
+single large `.txt` file is not treated like one training example. BPE
+vocabulary size is also bounded from corpus character diversity rather than
+always using a fixed oversized vocabulary.
+
+This is a heuristic, not a search — the goal is "a model that trains
+quickly and doesn't wildly overfit or underfit for typical dataset
+sizes," not the best possible architecture. Override any of it:
+`tl.train("./data", d_model=512, layers=6)`.
+
+For a packaged English grammar starter corpus, use
+`tl.pretrain(out="english.tl")`. It is intended for demos and smoke tests;
+larger local corpora should be passed to `tl.train()`.
+
+## 3. Hyperparameter selection
+
+Batch size, epoch count, learning rate, warmup steps, and the
+validation split are all similarly scaled to dataset size. See
+[configuration.md](configuration.md) for the exact defaults and how to
+override each one.
+
+## 4. Hardware selection
+
+`tensorless/devices/device.py` picks, in order: TPU (if `torch_xla` is
+installed and usable) → CUDA GPU (if available) → Apple MPS (if
+available) → CPU. Precision is chosen alongside it: `bf16` on TPU,
+`bf16` or `fp16` on GPU depending on hardware support, and `fp32`
+everywhere else for stability.
+
+This selection isn't blind — Tensorless PyTorch actually checks each backend is
+usable (not just importable) before choosing it, and if a device you
+explicitly request isn't available, it downgrades gracefully rather
+than erroring.
+
+## 5. The Smart Auto Check
+
+This is the part that makes repeated `tl.train("./data")` calls safe and
+cheap. Every dataset gets a **fingerprint**: a hash of every file's
+content, size, and relative path under the given directory (see
+`tensorless/data/fingerprint.py`). This fingerprint is content-based, not
+timestamp-based, so touching a file without changing it, or copying a
+dataset to a new machine, doesn't trigger a false "changed" signal.
+
+When you call `tl.train(path, out="model.tl")`, Tensorless PyTorch checks, in
+order:
+
+1. **Does `model.tl` already exist, with a fingerprint matching the
+   current dataset, and `training_complete=True`?**
+   → Return it immediately. No training happens.
+
+2. **Is there a checkpoint at `model.tl.ckpt/` whose fingerprint matches
+   the current dataset?**
+   - If that checkpoint's training wasn't finished
+     (`training_complete=False`) → **resume** from it.
+   - If it was actually finished but the final `.tl` file is missing
+     (e.g. the process died right after the last checkpoint write, before
+     the `.tl` file could be written) → package that checkpoint into
+     `model.tl` directly, no retraining needed.
+
+3. **Is there a checkpoint whose fingerprint does *not* match?** → The
+   dataset changed since that checkpoint was created.
+   - By default, Tensorless PyTorch retrains from scratch automatically (and
+     prints a message explaining why).
+   - Pass `ask_on_data_change=True` to instead raise a `ConfigError`
+     and let you decide, rather than silently retraining.
+
+4. **None of the above?** → Train from scratch.
+
+`force=True` skips all of this and always retrains from scratch,
+clearing any existing checkpoint first.
+
+See [checkpointing.md](checkpointing.md) for what's actually inside a
+checkpoint and exactly how resumption reconstructs training state.

tensorless_pytorch-0.1.0/docs/checkpointing.md

@@ -0,0 +1,80 @@
+# Checkpointing & Resume
+
+## Where checkpoints live
+
+Every training run writes to a checkpoint directory, by default
+`<out>.ckpt/` (e.g. `model.tl.ckpt/checkpoint.pt`). You never need to
+create or manage this directory yourself.
+
+## What's in a checkpoint
+
+`tensorless/checkpoint/manager.py` writes a single file,
+`checkpoint.pt`, containing:
+
+- `model_state_dict` — model weights
+- `optimizer_state_dict` — optimizer momentum/variance buffers
+- `scheduler_state_dict` — learning rate schedule position
+- `epoch`, `global_step` — where training left off
+- `early_stopping_best`, `early_stopping_bad_checks` — early stopping state
+- `config` — the fully resolved training configuration used
+- `meta` — task-specific sizing info (vocab size, number of classes, etc.)
+- `tokenizer_state` / `preprocessor_state` — whichever applies to the task
+- `dataset_fingerprint` — the fingerprint of the dataset this checkpoint
+  was trained on (see [automatic_mode.md](automatic_mode.md#5-the-smart-auto-check))
+- `training_complete` — whether this checkpoint represents a finished run
+
+This is everything needed to either resume training or reconstruct the
+final `.tl` file — nothing about resumption depends on the original
+dataset still being on disk in the same location, only on it being
+fingerprint-identical to what was originally used.
+
+## When checkpoints are written
+
+- Every `checkpoint_every` steps (default: 50) during training, with
+  `training_complete=False`
+- At the end of every epoch, with `training_complete` set to whether
+  that was the last epoch
+- On early stopping, with `training_complete=True`
+
+Writes are atomic: Tensorless PyTorch writes to a temporary file in the same
+directory and renames it into place, so a crash mid-write never leaves a
+corrupt checkpoint that would block resumption.
+
+When loading `.tl` files, Tensorless PyTorch fills compatible fields introduced by
+older versions with safe defaults. Files created by a newer unsupported format
+version are rejected with an upgrade message instead of being partially read.
+
+## How resumption works
+
+When `tl.train()` finds a checkpoint whose `dataset_fingerprint` matches
+the current dataset and `training_complete=False`, it:
+
+1. Loads the tokenizer/preprocessor state from the checkpoint (so the
+   vocabulary or column encoding is identical to the original run)
+2. Rebuilds the exact same model architecture from the checkpoint's
+   saved `config`
+3. Loads model, optimizer, and scheduler state
+4. Continues the training loop from the saved `epoch` / `global_step`
+
+**Important:** any config overrides you pass to the resuming
+`tl.train()` call (e.g. a different `d_model`) are ignored in favor of
+the checkpoint's original config. This is intentional — a resumed run
+must use the same architecture as the interrupted run, or the saved
+weights simply won't fit. If you want different hyperparameters,
+either delete the checkpoint directory first or pass `force=True`.
+
+## Manually clearing a checkpoint
+
+```python
+from tensorless.checkpoint.manager import CheckpointManager
+CheckpointManager("model.tl.ckpt").clear()
+```
+
+or simply delete the directory:
+
+```bash
+rm -rf model.tl.ckpt
+```
+
+`tl.train(..., force=True)` does this for you automatically before
+retraining.

tensorless_pytorch-0.1.0/docs/cli.md

@@ -0,0 +1,87 @@
+# Command-Line Interface
+
+Installing Tensorless PyTorch (`pip install tensorless-pytorch`) puts a `tensorless` command
+on your `PATH`.
+
+## `tensorless train`
+
+```bash
+tensorless train <path> [options]
+```
+
+| Option | Description |
+|---|---|
+| `--out PATH` | Output `.tl` path (default: `model.tl`) |
+| `--force` | Retrain even if a matching model/checkpoint exists |
+| `--d-model N` | Hidden dimension |
+| `--layers N` | Number of layers |
+| `--heads N` | Attention heads |
+| `--batch-size N` | Batch size |
+| `--epochs N` | Max epochs |
+| `--learning-rate F` | Learning rate |
+| `--device {cpu,cuda,tpu,mps}` | Force a device |
+| `--quiet` | Suppress training logs |
+
+For any configuration option not exposed as a CLI flag, use the Python
+API — the CLI covers the common cases; `tl.train()` covers everything in
+[configuration.md](configuration.md).
+
+Example:
+
+```bash
+tensorless train ./data --out sentiment.tl --epochs 20 --batch-size 32
+```
+
+## `tensorless run`
+
+```bash
+tensorless run <model.tl> [--prompt TEXT]
+```
+
+- Text-generation model, no `--prompt`: starts an interactive chat.
+- Text-generation model, with `--prompt`: prints one generated
+  continuation.
+- Text-classification model, with `--prompt`: prints the predicted
+  class.
+- Tabular (classification/regression) model: the CLI can't accept
+  structured input as a single string, so it prints a pointer to the
+  Python API (`tl.load(path).predict({...})`).
+
+## `tensorless inspect`
+
+```bash
+tensorless inspect <path>
+```
+
+Loads the dataset, runs task detection, and prints a report: detected
+kind and task, example count, columns (for tabular data), and any
+warnings/recommendations — without training anything.
+
+## `tensorless info`
+
+```bash
+tensorless info <model.tl>
+```
+
+Prints a JSON summary of a trained model: task, model type, versions,
+whether training completed, final metrics, and a truncated dataset
+fingerprint.
+
+```json
+{
+  "task": "classification",
+  "model_type": "mlp",
+  "tensorless_version": "0.1.0",
+  "tl_format_version": 1,
+  "training_complete": true,
+  "metrics": {"final_train_loss": 0.42, "final_val_loss": 0.51, "global_step": 96, "elapsed_seconds": 0.14},
+  "dataset_fingerprint": "de779ad33e2dc1d4"
+}
+```
+
+## Exit codes
+
+All commands return `0` on success. Errors raised as `TensorlessError`
+subclasses (bad data, bad config, corrupt checkpoint/model, etc.) are
+caught, printed to stderr as `tensorless: error: <message>`, and result
+in exit code `1`.