How to Install ArcLM, Tokenize Text, and Run a Tiny Language Model

Want to experiment with language models in Python without starting by downloading a multi-gigabyte model?

You can begin with something much smaller: tokenize a sentence, create a tiny neural network, and inspect the model's output.

ArcLM is a Python framework for working with language models. Its 2.0 architecture separates lightweight utilities from compute-intensive functionality, so you can install the core package without making PyTorch a mandatory dependency.

In this tutorial, we'll go from installation to a model forward pass.

By the end, you'll know how to:

• Install ArcLM without PyTorch.
• Convert text into token IDs.
• Configure and save model settings.
• Run a tiny native causal language model.
• Use the ArcLM CLI to check your installation.

Prerequisites: Python 3.12, a terminal, and basic knowledge of Python. You can complete the first three steps without a GPU.

1. Install ArcLM

Start by creating a virtual environment:

python -m venv .venv

Activate it on Windows:

.venv\Scripts\activate

Or activate it on macOS and Linux:

source .venv/bin/activate

Install ArcLM:

python -m pip install arclm

The core installation includes dependencies such as NumPy and SentencePiece without requiring PyTorch.

Verify the installation:

import arclm

print(arclm.get_version())

For the version used in this tutorial, the output is:

2.0.0

The important point is that you can start exploring the framework without installing the runtime needed for native model execution.

2. Tokenize Your First Sentence

Language models do not process ordinary text directly. They operate on numerical representations.

A tokenizer converts text into tokens and maps those tokens to integer IDs.

ArcLM provides a simple word tokenizer that makes this process easy to inspect:

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))

The observed output on ArcLM 2.0.0 was:

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

Here's what happens:

1. Tokenizer(max_vocab=64) creates a tokenizer with a maximum vocabulary size of 64.
2. build(text) constructs a vocabulary from the supplied text.
3. encode_text() converts words into integer IDs.
4. decode() maps those IDs back to tokens.

This tokenizer is intentionally simple. It does not automatically lowercase text, so "Arc" and "arc" can be treated as different tokens. Words outside the vocabulary map to an unknown token.

For more flexible subword tokenization, ArcLM also provides SentencePiece support.

3. Configure a Model Without PyTorch

Configuration and execution are separate concerns.

You can define settings before installing the dependency required to execute a neural network.

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)

Output:

32
16
cpu

The settings describe aspects of a model or training workflow:

• embed_dim: the embedding dimension.
• block_size: the configured sequence or context length.
• num_epochs: the number of training epochs.
• device: the configured execution device.

You can also save the configuration to YAML:

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)

Output:

32

This allows you to keep experiment settings separate from your application code.

4. Run a Tiny Native Language Model

Now let's execute a neural network.

This step requires PyTorch. Install ArcLM with its training extra:

python -m pip install "arclm[train]"

If you need a CPU-only PyTorch installation, use the command provided by the official PyTorch installation selector.

Next, 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 the script:

python model_demo.py

The observed CPU output for this configuration was:

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

Let's break down the result.

Understanding the output shape

The input tensor has three dimensions of information in the processing pipeline:

• Batch size: 1
• Sequence length: 3
• Vocabulary size: 11

The input tensor itself has shape (1, 3). The output logits have shape (1, 3, 11).

Each position in the input sequence has an associated vector of scores over the vocabulary. These scores are called logits.

They are not probabilities by themselves. A generation procedure can process the logits to select a next token according to its decoding strategy.

Also notice that the model contains only 3,531 parameters. It is a teaching example, not a practical replacement for a pretrained LLM.

The goal is to understand the processing path:

Text → Token IDs → Neural Network → Logits

You have now executed a native causal language model without downloading a pretrained chat model.

5. Check the ArcLM CLI

ArcLM also provides a command-line interface.

To see the available commands, run:

arclm --help

You can alternatively use:

python -m arclm --help

For runtime diagnostics, run:

arclm doctor

The doctor command is designed to inspect the environment without requiring PyTorch. This is useful when you want to check the core installation before adding the training dependency.

ArcLM's CLI includes commands for configuration, data, run inspection, caching, security, and model workflows. Commands for training, evaluation, generation, and chat require the appropriate optional dependencies.

For this introduction, --help and doctor are enough.

Common Issues

PyTorch is missing

If a model-related import raises an OptionalDependencyError, install the training extra:

python -m pip install "arclm[train]"

The tokenizer returns unknown tokens

The words may not exist in the tokenizer's vocabulary. Build the vocabulary with more representative text, use consistent text normalization, or explore subword tokenization.

The model rejects the input sequence

Check the configured block_size. The sequence length must be compatible with the model's context-length configuration.

The arclm command is unavailable

Confirm that your virtual environment is active and that ArcLM is installed inside it. You can also use python -m arclm --help.

What We Built

In a few steps, we installed ArcLM, converted text into token IDs, created a configuration, and ran a tiny causal language model.

We also saw why separating the lightweight core from optional compute dependencies can be useful: you can begin exploring language-model tooling before committing to a full machine-learning installation.

There is an important distinction between running a randomly initialized model and using a pretrained LLM. This tutorial demonstrates the mechanics of tokenization and a forward pass, not how to build a useful conversational model.

Next step: load a pretrained model and explore text generation.

You can find ArcLM's source code and continue exploring the project on GitHub.

If you try the examples, share your results or questions in the comments.

Comments

[vinmay]

Interesting to see what you've built. Does ArcLM have a built-in way to swap out the attention mechanism when training a small language model or would I end up having to bypass its abstractions to do that?