Skip to main content

télos (τέλος)

PyPI Version Python Versions License Hardware Support

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:

pip install telos-ml

With Apple Silicon (MLX) Acceleration

For native Apple Silicon Metal acceleration on macOS (M1/M2/M3/M4/M5):

pip install "telos-ml[mlx]"

With Development & Evaluation Tools

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:

# 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.

On MLX, --fused-vocab-loss --fused-vocab-chunk-axis metal enables experimental fused projection and cross entropy for tied-head AR pretraining. Large tested workloads reduced peak MLX allocation and took longer than the full projection.

For online reinforcement learning, use telos posttrain --method grpo with JSONL prompt and answer fields. GRPO samples completions, scores them with exact match or a custom Python verifier, and trains on their group-relative rewards. It supports single-device MLX, CUDA and CPU. See the GRPO quickstart.

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

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)

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:

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:

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


License

Télos is licensed under the Apache 2.0 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.

Evaluation displays

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

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:

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 for model setup, revision pins and imported responses.

Metadata

Release files for telos-ml 1.8.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for telos-ml 1.8.0
File Size Uploaded Provenance Actions
telos_ml-1.8.0.tar.gz 1.8 MB With provenance Details for telos_ml-1.8.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for telos-ml 1.8.0
File Interpreter ABI Platform Actions
telos_ml-1.8.0-py3-none-any.whl Python 3 none any Details for telos_ml-1.8.0-py3-none-any.whl

Total release size: 2.4 MB

Release files / telos_ml-1.8.0.tar.gz

Download URL telos_ml-1.8.0.tar.gz
Size 1.8 MB
Tags Source
SHA-256 checksum
How to use checksums
1f8e66139dc43a0d82b744bbc664a5e6bbb4b974f5e8fcfe9d95fd8d0a471de2
BLAKE2b-256 checksum
How to use checksums
84b2331bba35bd0c3b0969e9c67dbb038db4d7f58edc79987dbcc0eee89cf8eb
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.

Transparency log

Release files / telos_ml-1.8.0-py3-none-any.whl

Download URL telos_ml-1.8.0-py3-none-any.whl
Size 576.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
ca0df0124f8269bf066e2a717d2c1ddd13c0f67a076c079182e8fbe4fd841093
BLAKE2b-256 checksum
How to use checksums
b12b84a19f8b9b3019b8d7df7cebd9970aaf7574f18045717ccb3e5e153d5e50
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.

Transparency log

Security for telos-ml 1.8.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for telos_ml-1.8.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page