DEV Community: Ahmad Al Dibo

Build a Reproducible Local Agent Tool with ArcLM (No GPU Required)

Ahmad Al Dibo — Fri, 16 Oct 2026 20:37:34 +0000

Build a Reproducible Local Agent Tool with ArcLM (No GPU Required)

An AI agent becomes useful when it can do more than generate text. It needs a way to call functions, validate their inputs, execute operations, and return structured results.

But giving an agent access to tools introduces engineering questions:

What arguments can a tool accept?
How do you prevent an agent from running indefinitely?
How can you inspect which tools were called?
What happens when a tool needs permission to modify a file?
How do you avoid exposing sensitive information in diagnostic output?

In this tutorial, we'll build a small calculator agent with ArcLM.

We'll define a typed Python function, register it as a tool, execute a bounded agent loop, inspect its trace, and examine how permissions and redaction fit into the design.

No GPU or external LLM API is required. We'll use a deterministic fake model adapter so that the same example can be reproduced without API credentials or the variability of a real language model.

The fake model is only a test adapter. It demonstrates the tool-calling pipeline, not the reasoning capabilities of an LLM.

1. Install ArcLM

Create and activate a Python virtual environment, then install the lightweight ArcLM package:

python -m venv .venv

On Windows:

.venv\Scripts\activate

On macOS or Linux:

source .venv/bin/activate

Install ArcLM:

python -m pip install arclm

The agent runtime does not require PyTorch for this example. You don't need a GPU, a downloaded language model, or an API key.

For the implementation details, see the ArcLM agent tools example.

2. Define a Typed Tool

Let's start with a simple function that adds two integers.

from arclm.agents import (
    SideEffectLevel,
    ToolPermission,
    tool,
)


@tool(
    category="utilities",
    permission=ToolPermission.PURE,
    side_effect=SideEffectLevel.NONE,
)
def add_numbers(left: int, right: int) -> int:
    """Add two integers."""
    return left + right

There are only a few lines of implementation, but the metadata matters.

The @tool decorator exposes the function as an ArcLM tool. Its type hints describe the expected arguments and return type, while the docstring supplies a description.

The category field groups the tool with related functionality.

The permission and side-effect declarations describe its operational behavior:

ToolPermission.PURE identifies an operation that doesn't require access to external resources.
SideEffectLevel.NONE declares that the operation has no side effects.

The function itself remains ordinary Python. ArcLM supplies the tool abstraction around it.

This distinction is useful when building larger systems: the business logic can remain independent of the agent runtime.

3. Register the Tool

ArcLM provides ToolRegistry for managing tools by name.

Create a registry and register the function:

from arclm.agents import ToolRegistry

registry = ToolRegistry()
registry.register_tool(add_numbers)

registered_tool = registry.get_tool("add_numbers")

print(registered_tool.name)
print(registered_tool.description)
print(registered_tool.input_schema)

The registry gives you a consistent way to retrieve registered tools and inspect their metadata.

The input_schema describes the expected arguments. An agent adapter can use this information when deciding how to formulate a tool call.

This is more explicit than simply exposing arbitrary Python functions to a model.

A schema can describe what a function accepts, but it doesn't prove that a tool is safe. You still need to validate arguments and control access to operations with side effects.

ArcLM's tool abstraction includes argument validation before invoking the underlying function. See src/arclm/agents/tool.py.

4. Build a Deterministic Agent

A real language model would decide when to call add_numbers and what arguments to provide. That introduces an external dependency and potentially nondeterministic behavior.

For this tutorial, we'll remove that variable by implementing a minimal fake model.

It will do two things:

Request a call to add_numbers with the arguments 2 and 5.
Read the structured tool result and return a final response.

Create a file named calculator_agent.py and use the following complete example:

import json

from arclm.agents import (
    Agent,
    AgentRunner,
    ModelResponse,
    SideEffectLevel,
    ToolCall,
    ToolPermission,
    ToolRegistry,
    tool,
)
from arclm.security import redact_sensitive_text


# 1. Define a typed tool.

@tool(
    category="utilities",
    permission=ToolPermission.PURE,
    side_effect=SideEffectLevel.NONE,
)
def add_numbers(left: int, right: int) -> int:
    """Add two integers."""
    return left + right


# 2. Register the tool.

registry = ToolRegistry()
registry.register_tool(add_numbers)


# 3. Create a deterministic fake model adapter.

class DeterministicFakeModel:
    def __init__(self):
        self.calls = 0

    def generate_response(
        self,
        *,
        messages,
        tools,
        instructions,
        session,
    ):
        self.calls += 1

        if self.calls == 1:
            return ModelResponse(
                tool_calls=[
                    ToolCall(
                        id="call_1",
                        name="add_numbers",
                        arguments={
                            "left": 2,
                            "right": 5,
                        },
                    )
                ]
            )

        # Read the actual result returned by the tool.
        for message in reversed(messages):
            if message.role == "tool":
                result = json.loads(message.content)

                if result["success"]:
                    return ModelResponse(
                        content=f"The sum is {result['value']}."
                    )

                return ModelResponse(
                    error_code="tool_failed",
                    error_message="The calculator tool failed.",
                )

        return ModelResponse(
            error_code="missing_tool_result",
            error_message="No calculator result was received.",
        )


# 4. Configure and run the agent.

agent = Agent(
    name="calculator",
    instructions="Use the available calculator tool to add integers.",
    model=DeterministicFakeModel(),
    tools=registry.list_tools(),
)

runner = AgentRunner(max_steps=2)

result = runner.run(
    agent,
    "Add 2 and 5.",
)

if not result.success:
    raise RuntimeError(
        f"Agent run failed: {result.error_code}"
    )


# 5. Inspect the result and execution trace.

report = {
    "success": result.success,
    "output": result.output,
    "tool_calls": [
        call.name for call in result.session.tool_calls
    ],
    "trace_events": [
        event.event_type for event in result.trace.events
    ],
}

print(json.dumps(report, indent=2))


# 6. Demonstrate sensitive-text redaction.

sample = "api_key=demo-secret"
print(redact_sensitive_text(sample))

Run the script:

python calculator_agent.py

This code is intended to produce a successful calculator run followed by a redaction demonstration. Execute it with your installed ArcLM version and capture the actual terminal output before publishing the tutorial.

What happens inside the agent loop?

The execution follows a sequence:

The runner sends the conversation and available tool descriptions to the fake model.
The model returns a structured ToolCall.
The runner checks whether the tool exists and is allowed.
ArcLM validates the arguments and invokes the function.
The tool result is added to the session.
The fake model reads that result and returns a final response.

Notice that the second response derives its answer from the returned tool result rather than hardcoding the number 7.

This makes the example useful for examining the interaction between an agent, a tool, and a model adapter.

5. Why Bound the Agent Loop?

The line below is an important part of the implementation:

runner = AgentRunner(max_steps=2)

An agent that repeatedly requests tools without reaching a final response can consume resources indefinitely unless execution is constrained.

max_steps limits the number of model-response steps in a run. In this example, two steps are sufficient: one tool request and one final response.

The limit is not a guarantee that every run will succeed. The model could request a nonexistent tool, return an invalid response, or fail to produce a final answer.

ArcLM represents execution outcomes through structured result objects, which lets the caller inspect success and failure without relying exclusively on printed text.

You can explore the implementation in src/arclm/agents/runner.py.

6. Add Permission and Side-Effect Controls

A calculator is a convenient first tool because it doesn't modify external state.

A file-writing tool is different. It may overwrite data, create files in unintended locations, or expose information to another process.

ArcLM separates permission declarations from side-effect classification.

For example, a tool that writes to a local workspace could declare:

from arclm.agents import (
    SideEffectLevel,
    ToolPermission,
    tool,
)


@tool(
    category="filesystem",
    permission=ToolPermission.WRITE_LOCAL,
    side_effect=SideEffectLevel.REVERSIBLE,
)
def write_report(path: str, content: str) -> str:
    """Write a report to an approved workspace location."""
    # Implement explicit path validation and file-writing policy here.
    ...

This is a classification example, not a file-writing implementation. A production tool also needs to validate its destination, restrict allowed paths, handle errors, and define overwrite behavior.

The distinction between the two metadata fields is important:

permission declares the kind of access a tool requires.
side_effect describes the operational consequences of the tool.

Declaring a side effect alone does not enforce approval. ArcLM's approval policy uses the tool's permission classification and the configured ToolPolicy.

By default, permissions such as WRITE_LOCAL, READ_NETWORK, EXTERNAL_ACTION, and SENSITIVE require approval. The default approval handler denies operations that require approval unless an appropriate handler is configured.

For a real application, provide a ToolApprovalHandler through AgentRunner(approval_handler=...) and define how approval is requested, granted, denied, and audited.

Never treat a descriptive tool schema as a substitute for access control.

7. Redact Sensitive Information

Tool outputs and execution logs can contain credentials, tokens, or other sensitive values.

ArcLM provides a redaction utility:

from arclm.security import redact_sensitive_text

sample = "api_key=demo-secret"

safe_text = redact_sensitive_text(sample)

print(safe_text)

The intended transformation is:

api_key=[REDACTED]

ArcLM also redacts tool-result payloads when trace redaction is enabled by the agent's security policy.

However, redaction has limits. It detects supported patterns; it cannot guarantee that every secret or item of personal information will be recognized.

It is also important to distinguish tool-result redaction from complete session sanitization. For example, the session records tool-call arguments. You should not pass real credentials as tool arguments simply because result redaction is enabled.

For sensitive workflows:

Avoid putting secrets into prompts and tool arguments.
Keep credentials in an appropriate secret-management mechanism.
Minimize what you include in diagnostic output.
Test redaction with representative examples from your application.

The relevant implementation is available in src/arclm/security/redaction.py.

8. Inspect the Trace

A final answer tells you what the agent returned. A trace helps explain how it reached that outcome.

The example collects the trace event names using:

trace_events = [
    event.event_type
    for event in result.trace.events
]

The runner records events such as:

run_started
model_responded
tool_requested
tool_started
tool_completed
step_completed
run_completed

These events help answer practical debugging questions.

Did the model request a tool? Did the runner start it? Did it complete? Did the agent reach a final response or exhaust its step limit?

For the current example, inspecting event names is enough. In a larger application, you can also examine the structured trace and result metadata.

Before persisting traces, decide what information should be retained, who can access it, and how sensitive data should be handled.

What This Example Demonstrates

This small example separates several responsibilities that are often mixed together in agent implementations:

Tools define capabilities. A typed function exposes a specific operation with a discoverable schema.

The registry manages available tools. Tools can be registered and selected explicitly.

The adapter defines model interaction. Our deterministic adapter demonstrates the protocol without requiring a provider.

The runner controls execution. It validates tool calls, coordinates results, and limits the number of steps.

Permissions and redaction address different security concerns. Permissions govern access and approval, while redaction reduces exposure of recognized sensitive values.

This is not a production-ready autonomous agent, nor does it demonstrate real language-model reasoning. It is a small, inspectable foundation for understanding how tool-calling systems fit together.

If you want to go further, start with the ArcLM repository and inspect the canonical custom tool agent example.

The next experiment is to replace the fake adapter with a real model adapter while keeping the same tool boundary, step limit, permission policy, and trace inspection.

That separation is the useful part: you can change the model backend without having to redesign the tool's Python implementation.

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

Ahmad Al Dibo — Fri, 16 Oct 2026 20:27:37 +0000

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:

Tokenizer(max_vocab=64) creates a tokenizer with a maximum vocabulary size of 64.
build(text) constructs a vocabulary from the supplied text.
encode_text() converts words into integer IDs.
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:

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.