Metadata-Version: 2.5
Name: telos-ml
Version: 1.7.3
Summary: Language modeling and discrete diffusion: pretraining, SFT and DPO post-training, evaluation, and Apple Foundation Models access.
Project-URL: Homepage, https://telos.research.wingit.tech
Project-URL: Repository, https://github.com/kazenoko-git/telos
Project-URL: Issues, https://github.com/kazenoko-git/telos/issues
Project-URL: Documentation, https://github.com/kazenoko-git/telos/blob/main/DEPLOYMENT.md
Project-URL: Changelog, https://github.com/kazenoko-git/telos/blob/main/CHANGELOG.md
Author: Ivan Samuel
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: apple-foundation-models,autoregressive,code-completion,cuda,discrete-diffusion,language-model,masked-diffusion,mlx,tpu
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Requires-Dist: datasets>=3.0.0
Requires-Dist: huggingface-hub>=0.25.0
Requires-Dist: numpy>=1.26.0
Requires-Dist: pyyaml>=6.0.0
Requires-Dist: safetensors>=0.4.0
Requires-Dist: tokenizers>=0.21.0
Requires-Dist: torch>=2.5.0
Requires-Dist: tqdm>=4.66.0
Provides-Extra: all
Requires-Dist: gradio>=5.0.0; extra == 'all'
Requires-Dist: matplotlib>=3.8.0; extra == 'all'
Requires-Dist: mlx>=0.22.0; (sys_platform == 'darwin' and platform_machine == 'arm64') and extra == 'all'
Requires-Dist: pytest>=8.0.0; extra == 'all'
Requires-Dist: ruff>=0.8.0; extra == 'all'
Provides-Extra: dev
Requires-Dist: gradio>=5.0.0; extra == 'dev'
Requires-Dist: matplotlib>=3.8.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.8.0; extra == 'dev'
Provides-Extra: eval-hf
Requires-Dist: accelerate>=1.0; extra == 'eval-hf'
Requires-Dist: transformers>=4.51; extra == 'eval-hf'
Provides-Extra: eval-mlx
Requires-Dist: mlx-lm>=0.32.2; (python_version >= '3.11' and sys_platform == 'darwin' and platform_machine == 'arm64') and extra == 'eval-mlx'
Provides-Extra: eval-pdf
Requires-Dist: playwright>=1.49; extra == 'eval-pdf'
Provides-Extra: mlx
Requires-Dist: mlx>=0.22.0; (sys_platform == 'darwin' and platform_machine == 'arm64') and extra == 'mlx'
Description-Content-Type: text/markdown

# télos (τέλος)

[![PyPI Version](https://img.shields.io/pypi/v/telos-ml.svg)](https://pypi.org/project/telos-ml/)
[![Python Versions](https://img.shields.io/pypi/pyversions/telos-ml.svg)](https://pypi.org/project/telos-ml/)
[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](https://github.com/kazenoko-git/telos/blob/main/LICENSE)
[![Hardware Support](https://img.shields.io/badge/hardware-Apple%20Silicon%20(MLX)%20%7C%20CUDA%20%7C%20TPU%20(XLA)-orange)](https://github.com/kazenoko-git/telos)

**Télos** is a high-performance Python framework for discrete diffusion and autoregressive language modeling. It features zero-config dimensional training across Apple Silicon (MLX), NVIDIA GPUs (CUDA), and Google Cloud TPUs (PyTorch-XLA), alongside native access to Apple on-device Foundation Models.

---

## Installation

### Standard Installation
Install the base package via `pip` or `uv`:

```bash
pip install telos-ml
```

### With Apple Silicon (MLX) Acceleration
For native Apple Silicon Metal acceleration on macOS (M1/M2/M3/M4):

```bash
pip install "telos-ml[mlx]"
```

### With Development & Evaluation Tools
```bash
pip install "telos-ml[dev]"
```

---

## Key Features

- **Discrete Diffusion & Autoregressive Paradigms**: Unified implementations of Masked Diffusion Language Models (MDLM), Uniform Noise Diffusion (UNDLM), Causal Autoregressive (AR), and Confidence-Routed Selective ReDiffusion (COROSred).
- **Multi-Backend Hardware Acceleration**:
  - **Apple Silicon**: Native Metal execution via Apple MLX (`mlx.core`).
  - **NVIDIA CUDA**: Scaled PyTorch training with FlashAttention-2, mixed precision (native BF16 or scaled FP16), and master weight accumulation.
  - **Google Cloud TPU**: Multi-core single-chip and Pod scaling with PJRT runtime.
- **Apple Foundation Models (AFM) Bridge**: Direct Python access to Apple's native on-device language models on macOS Sequoia via compiled Swift IPC.
- **Evaluation & Benchmarks**: 100 contextual probes, code execution suites (HumanEval, MBPP), cybersecurity audits, and tool-use verification.
- **High-Throughput Data Preparation**: Memory-mapped binary token streaming (`.bin`) with custom Byte-Level BPE tokenization.

---

## Quickstart

### 1. Command Line Interface (CLI)

Télos ships with a unified command-line dispatcher:

```bash
# Prepare dataset into high-speed binary token format
telos dataprep --source /path/to/code_corpus --output data/corpus.bin

# Train a 12M parameter model on automatically detected hardware
telos pretrain --paradigm mdlm --params 12M --tokens 1B

# Post-train a causal checkpoint with prompt/response JSONL
telos posttrain --method sft --checkpoint checkpoints/ar/checkpoint_final.pt \
  --data data/instructions.jsonl --output checkpoints/ar-sft

# Run hardware throughput benchmark (capped at 5 minutes)
telos bench --hardware auto

# Evaluate a trained checkpoint across evaluation suites
telos eval --checkpoint checkpoints/mdlm/checkpoint_final.pt

# Query on-device Apple Foundation Model status (macOS only)
telos afm status
```

For preference optimization, use `telos posttrain --method dpo` with JSONL records containing `prompt`, `chosen`, and `rejected` strings. Select `--hardware mlx`, `cuda`, `xla`, or `cpu`; Apple Silicon post-training uses MLX rather than PyTorch MPS. `telos train` remains an alias for `telos pretrain`.

With v1.7.0, add `--finetune lora` or `--finetune qlora` for adapter training. Configure `--lora-rank`, `--lora-alpha`, `--lora-dropout` and `--lora-targets`. Saves include merged native weights, adapter-only weights and complete resume state. PyTorch QLoRA uses portable packed NF4; MLX uses native affine int4. Embeddings/output heads remain unquantized; double quantization and paged optimizers are not implemented. v1.7.2 recomputes frozen NF4 weights during backward to reduce autograd retention and selects native CUDA precision automatically. v1.7.3 fixes MLX DPO gradients at zero preference margin, stages batches directly as int32 and reuses reference response scores across shuffled batches. Physical CUDA/TPU v1.7.2 reruns remain pending; the repository release validation notes audit the earlier single-device report. See the repository README for distributed training and precision options.

---

### 2. Python API

#### Defining and Initializing Models
```python
from telos.models import TelosConfig, TelosTransformer

# Configure a compact transformer architecture
config = TelosConfig(
    vocab_size=8192,
    d_model=512,
    n_layers=12,
    n_heads=8,
    n_kv_heads=8,
    max_seq_len=512,
    tied_embeddings=True,
    is_causal=False,  # Set to False for bidirectional diffusion, True for AR
)

# PyTorch Model
model = TelosTransformer(config)
```

#### Apple Silicon Metal (MLX)
```python
from telos.models import MLXTelosTransformer

# Direct Apple Silicon Metal transformer
mlx_model = MLXTelosTransformer(config)
```

#### Apple Foundation Models (macOS Sequoia)
Access Apple's system language model directly from Python:

```python
from telos import afm

# Verify system availability
status = afm.status()
if status["available"]:
    # Synchronous generation
    response = afm.generate("Explain discrete diffusion models in two sentences.")
    print(response)

    # Streaming generation
    for chunk in afm.stream("Write a Python binary search function."):
        print(chunk, end="", flush=True)
```

#### Loading Model Checkpoints Securely
Télos enforces `weights_only=True` to prevent arbitrary code execution during deserialization:

```python
from telos.eval.runner import load_model_from_checkpoint

# Safely loads weights into optimal runtime backend (MLX or PyTorch)
model, backend, vocab_size = load_model_from_checkpoint("checkpoints/model.pt")
```

---

## Hardware Support

| Backend | Hardware | Framework | Key Features |
| :--- | :--- | :--- | :--- |
| **`mlx`** | Apple Silicon (M1/M2/M3/M4) | Apple MLX | Zero-copy unified memory, Metal acceleration |
| **`cuda`** | NVIDIA GPUs (Ampere, Ada, Hopper) | PyTorch | `torch.compile`, FlashAttention-2, bfloat16 |
| **`xla`** | Google Cloud TPU (v2/v3/v4/v5) | PyTorch-XLA | PJRT runtime, distributed data-parallel |
| **`afm`** | Apple Silicon (macOS 15.0+) | Swift Bridge | SystemLanguageModel on-device inference |

---

## Documentation & Resources

- **GitHub Repository**: [github.com/kazenoko-git/telos](https://github.com/kazenoko-git/telos)
- **Deployment & Cloud Training Guide**: [DEPLOYMENT.md](https://github.com/kazenoko-git/telos/blob/main/DEPLOYMENT.md)
- **Changelog**: [CHANGELOG.md](https://github.com/kazenoko-git/telos/blob/main/CHANGELOG.md)
- **Issue Tracker**: [github.com/kazenoko-git/telos/issues](https://github.com/kazenoko-git/telos/issues)

---

## License

Télos is licensed under the [Apache 2.0 License](https://github.com/kazenoko-git/telos/blob/main/LICENSE).

### Resume pretraining

Use `telos pretrain --resume checkpoints/ar/checkpoint_step_1000.resume.npz` on MLX,
or pass a complete `.pt` training checkpoint on PyTorch. v1.5.1 restores training
state and the saved run configuration, and rejects changed
data or incompatible checkpoints. Older weights can start a new run through
`--init-checkpoint`. See the [resume guide](https://github.com/kazenoko-git/telos/blob/main/cli/README.md#resuming-pretraining).

## Evaluation displays

Télos 1.6.0 turns saved evaluation JSON into a portable, offline cream notebook:

```sh
telos eval report logs/evaluation.json --output evaluation.html
```

Use `--html-report evaluation.html` during evaluation to save a notebook when the run finishes. Live progress adapts to terminals and plain CI logs; control it with `--display auto|plain|off`. The viewer preserves recorded outcomes and missing metrics, and supports filters, exports, and source-evidence inspection for Reader-1 archives.

## Packaged document evaluation

The frozen 512-case document diagnostic suite ships in Télos 1.6.2. Replay the completed historical responses offline:

```bash
telos eval documents replay --reference --output replay.json --html-report replay.html
```

Run new predictions using existing generic backends with `telos eval --suite document512 --model MODEL --backend openai_api --api-base http://localhost:1234/v1 --track all --output run.json`. Direct QA, exact source extraction and the configured calculator remain separate metrics. See [document evaluation](https://github.com/kazenoko-git/telos/blob/v1.6.2/docs/document-evaluation.md) for model setup, revision pins and imported responses.
