Getting Started with ArcLM: Run a Tiny Language Model Without Installing PyTorch

Why Start with a Tiny Language Model

Downloading a pretrained large model that easily weighs tens of gigabytes is a test for both hardware and network. In reality, understanding how language models work doesn't require facing a giant from the start. ArcLM is a Python framework focused on the language model toolchain. Its 2.0 release separates lightweight utilities from heavy computation features, and the core package does not force a PyTorch dependency. This means you can run the complete workflow of text tokenization, configuration management, and forward propagation on an ordinary laptop first.

This tutorial will walk you through every step from installation to model output. By the end you'll know how to: use ArcLM's core features without installing PyTorch, convert text into Token IDs, save and load model configurations, run a tiny causal language model, and use the CLI to check environment status. The only prerequisites are Python 3.12, a terminal, and basic Python knowledge — the first three steps require no GPU at all.

Installing ArcLM: The Core Package Doesn't Need PyTorch

Start by creating and activating a virtual environment, which is a good habit for keeping dependencies clean:

python -m venv .venv
# Windows
.venv\Scripts\activate
# macOS/Linux
source .venv/bin/activate

Then install the core package:

python -m pip install arclm

The core installation automatically pulls in dependencies such as NumPy and SentencePiece, but it won't fetch PyTorch. Verify the installation succeeded:

import arclm
print(arclm.get_version())

The version output used in this tutorial is 2.0.0. The key design idea here is that you can explore the framework's interfaces and tools first, and defer installing the compute runtime until you actually need to execute neural networks. According to the official ArcLM GitHub repository and this tutorial's description, this layered architecture is the core improvement in the 2.0 release.

Text Tokenization: From Sentences to Token IDs

Language models can't process natural text directly; they need numerical input. The tokenizer is responsible for splitting text into Tokens and then mapping each Token to an integer ID. ArcLM ships with a simple word-level tokenizer so you can observe the whole process:

from arclm.tokenizers import Tokenizer

text = "arc lm trains tiny models on local text about language models"

tokenizer = Tokenizer(max_vocab=64)
tokenizer.build(text)

ids = tokenizer.encode_text("arc lm trains")

print("Token IDs:", ids)
print("Vocabulary size:", tokenizer.get_vocab_size())
print("Decoded tokens:", tokenizer.decode(ids))

Actual output on ArcLM 2.0.0:

Token IDs: [2, 3, 4]
Vocabulary size: 11
Decoded tokens: ['arc', 'lm', 'trains']

Breaking down the flow: Tokenizer(max_vocab=64) declares a maximum vocabulary capacity of 64; build(text) builds the vocabulary from the text; encode_text() turns words into integer IDs; decode() restores IDs back to Tokens. Note that this tokenizer doesn't automatically lowercase, so "Arc" and "arc" are treated as different Tokens, and words beyond the vocabulary get mapped to an unknown Token. If you need more flexible subword splitting, ArcLM also provides SentencePiece support.

The difference between word-level tokenization and subword tokenization is worth understanding in advance. A word-level tokenizer treats each complete word as a single Token — simple to implement, with intuitive IDs — but it can only fall back to an unknown Token when it encounters out-of-vocabulary words, and it can't handle spelling variants or unseen new words. Subword tokenization instead cuts words into smaller pieces; common algorithms include BPE, WordPiece, and Unigram, and SentencePiece is one language-agnostic engineering implementation. Subword approaches can cover almost any text while keeping vocabulary size manageable, at the cost that the same word may be split into different Token sequences, making it slightly less interpretable. ArcLM provides both: this tutorial prioritizes the word-level tokenizer so that Token IDs map one-to-one to words, making them easy to inspect; in actual training you'd typically switch to SentencePiece to improve generalization.

Configuring the Model: Define Parameters Without Executing Computation

ArcLM separates configuration from execution, which is a practical design. You can define model settings without installing PyTorch:

from arclm.configs import Config

config = Config(
    embed_dim=32,
    block_size=16,
    num_epochs=3,
    device="cpu",
)

print(config.embed_dim)
print(config.block_size)
print(config.device)

The output is 32, 16, cpu. These parameters control the embedding dimension, sequence length, number of training epochs, and execution device respectively. Configurations can also be saved as YAML for easy management separate from code:

from arclm.configs import save_config_yaml, load_config_yaml

save_config_yaml(config, "arclm-config.yaml")
loaded_config = load_config_yaml("arclm-config.yaml")
print(loaded_config.embed_dim)  # 32

Keeping experiment configuration independent of application code is a huge convenience when you're repeatedly tuning hyperparameters.

Running the Tiny Model: Observe Forward Propagation

Executing neural networks requires PyTorch. Install ArcLM with the training extras:

python -m pip install "arclm[train]"

If you need CPU-only PyTorch, you can refer to the command given by the official installation selector. Then create model_demo.py:

import torch
from arclm.tokenizers import Tokenizer
from arclm.models import ArcLM

text = "arc lm trains tiny models on local text about language models"

tokenizer = Tokenizer(max_vocab=64)
tokenizer.build(text)

model = ArcLM(
    vocab_size=tokenizer.get_vocab_size(),
    embed_dim=16,
    block_size=8,
    num_blocks=1,
)

ids = tokenizer.encode_text("arc lm trains")[:8]
input_ids = torch.tensor([ids], dtype=torch.long)

logits = model(input_ids)

print("Logits shape:", tuple(logits.shape))
print("Parameters:", model.get_num_parameters())

Run python model_demo.py, and the output on CPU is:

Logits shape: (1, 3, 11)
Parameters: 3531

Understanding the Output Shape and Parameter Meaning

The input tensor has shape (1, 3), representing a batch size of 1 and a sequence length of 3. The output logits have shape (1, 3, 11), where 11 is the vocabulary size. This means each position in the sequence has a score vector spanning the entire vocabulary, and those scores are the logits. They aren't probabilities themselves — they need to go through a decoding strategy before selecting the next Token.

The model has only 3531 parameters, clearly a teaching example that can't possibly replace a pretrained large model. But the entire processing path has been run end-to-end: text → Token IDs → neural network → logits. You just executed a native causal language model forward pass without downloading any pretrained chat model.

A causal language model (Causal Language Model) means that when predicting the Token at position t in a sequence, the model can only see inputs at positions 1 through t, not future Tokens. This constraint is typically implemented via a causal mask, which sets the scores in the upper-right triangle of the attention matrix to negative infinity; after softmax, the weights at those positions become approximately 0. Autoregressive generative models like the GPT series and LLaMA fall into this category. Its counterpart is the bidirectional model (such as BERT), which uses context from both left and right sides during encoding, making it better suited for understanding tasks like classification and extraction, but not for direct word-by-word generation. The ArcLM in this tutorial is a minimal causal language model implementation, so given a length-3 input, it returns 3 score vectors for the next Token at each position.

Logits are the unnormalized scores output by the final linear transformation of a neural network; they span all real numbers and can be positive or negative. To turn them into a probability distribution, you need softmax: exponentiate each of the 11 scores at each position and divide by the sum, yielding a vector whose entries are non-negative and sum to 1. During training you typically don't do this explicitly, because the cross-entropy loss function already includes log-softmax internally — feeding raw logits directly is numerically more stable. At inference time you'd layer decoding strategies on top of softmax, such as greedy argmax, temperature sampling, top-k, or top-p truncation, which determine the final Token chosen. This tutorial only prints the logits shape, precisely to let readers see clearly the key fact that "the neural network outputs scores, not probabilities."

CLI Diagnostics: Quickly Check the Environment

ArcLM provides a command-line interface. View available commands:

arclm --help
# or
python -m arclm --help

Runtime diagnostics can be run with:

arclm doctor

The doctor command is designed to check environment status without depending on PyTorch, which is very useful for verifying the core installation before adding training dependencies. The CLI also includes commands for configuration, data, run checks, caching, security, and model workflows, but training, evaluation, generation, and chat-related commands require their corresponding optional dependencies. At the beginner stage, --help and doctor are enough.

Common Troubleshooting

PyTorch missing: If importing model-related modules raises OptionalDependencyError, simply install the training extras with python -m pip install "arclm[train]".

Tokenizer returns unknown Tokens: This means those words aren't in the vocabulary. Build the vocabulary from more representative text, unify text normalization, or switch to subword tokenization.

Model rejects input sequences: Check the block_size configuration; the sequence length must be compatible with the model's context length configuration.

arclm command unavailable: Confirm the virtual environment is activated and ArcLM is installed inside it, or use python -m arclm --help instead.

Next Steps

This tutorial has a clear scope: it demonstrates the mechanics of tokenization and forward propagation, not how to build a usable chat model. There's a fundamental difference between running a randomly initialized model and using a pretrained large model. Once you understand that difference, the next step is to load a pretrained model and explore text generation features. ArcLM's source code and more examples can be found in its GitHub repository.

One-line Summary

A complete tutorial on using ArcLM 2.0 to run tokenization, configuration, and forward propagation of a tiny causal language model without a GPU.

Paragraph Summary

The article uses ArcLM 2.0 to demonstrate how to run the language model toolchain without installing PyTorch. Step one creates a virtual environment, installs the core package, and verifies version 2.0.0; step two uses the built-in word-level tokenizer to split sentences into Tokens and map them to integer IDs, then decode them back, where max_vocab controls vocabulary capacity and the tokenizer doesn't auto-lowercase; step three uses Config to define embedding dimension, sequence length, epochs, and device, and can save/load it as YAML; step four installs arclm[train] and runs a tiny causal model with only 3531 parameters, taking input shape (1, 3) and producing logits shape (1, 3, 11). Finally it introduces the CLI's doctor command and common troubleshooting, emphasizing that this tutorial shows the processing mechanics rather than a usable chat model.