how-agentic 0.1.0

How-Agentic: a tutorial-first framework for training a small agent model from scratch

How-Agentic

How-Agentic is a tutorial-first framework for training a small agent model from scratch.

The current release is the M0 closed-loop baseline. It is intentionally small and practical: the goal is to make the full path reproducible before moving on to more agentic behavior training.

tokenizer -> pretrain -> format-only SFT -> export -> infer -> HuggingFace-compatible export

M0 Status

M0 is complete and frozen.

• Pretrained checkpoint: out/hello_agent_100m/pretrain/final.pt
• SFT checkpoint: out/hello_agent_100m/sft/final.pt
• Tokenizer: tokenizers/hello-agent-16k
• Pretrain data: data/demo/pretrain_100k.jsonl
• SFT data: data/demo/m0_sft_format_500.jsonl
• Pretrain infer mode: completion
• SFT infer mode: chat

Model checkpoints and datasets are not included in the PyPI package.

Install

Minimal CLI install:

pip install how-agentic

M0 training environment, verified on Python 3.12 + CUDA 12.4:

pip install -r requirements/m0-py312-cu124.txt
pip install -e . --no-deps

Or with uv:

uv venv .venv --python 3.12
uv pip install -r requirements/m0-py312-cu124.txt
uv pip install -e . --no-deps

CLI

python -m how_agentic.cli --help

or:

how-agentic --help

M0 Quick Path

Train tokenizer:

python -m how_agentic.cli train-tokenizer \
  --data data/demo/pretrain_100k.jsonl \
  --output tokenizers/hello-agent-16k \
  --vocab-size 16000

Pretrain:

python -m how_agentic.cli train \
  --config configs/hello_agent_pretrain_100k.yaml

Export pretrained model:

python -m how_agentic.cli export \
  --checkpoint out/hello_agent_100m/pretrain/final.pt \
  --output models/hello_agent_100m_native

Infer with pretrained model:

python -m how_agentic.cli infer \
  --model models/hello_agent_100m_native \
  --prompt "Once upon a time" \
  --mode completion \
  --max-tokens 50 \
  --temperature 0

Build M0 format-only SFT data:

python scripts/build_m0_format_sft_dataset.py \
  --output data/demo/m0_sft_format_500.jsonl \
  --total 500 \
  --seed 42

Run M0 SFT:

python -m how_agentic.cli train \
  --config configs/hello_agent_sft.yaml

Export SFT model:

python -m how_agentic.cli export \
  --checkpoint out/hello_agent_100m/sft/final.pt \
  --output models/hello_agent_100m_sft_native

Infer with SFT model:

python -m how_agentic.cli infer \
  --model models/hello_agent_100m_sft_native \
  --prompt "What is the capital of France?" \
  --mode chat \
  --max-tokens 80 \
  --temperature 0

Expected shape:

<answer>
The capital of France is Paris.
</answer>

Docs

Quickstart:

docs/quickstart.md

M0 reproduction:

docs/m0-reproduction.md

CLI reference:

docs/cli-reference.md

Configuration guide:

docs/configuration.md

Roadmap:

docs/roadmap.md

Publishing:

docs/publishing.md

Package Boundary

PyPI contains the framework code and CLI.

The following are intentionally kept outside the wheel:

• checkpoints
• exported models
• tokenizer artifacts
• training data
• logs
• local caches

Use HuggingFace Hub for model weights and GitHub for reproducibility docs, configs, scripts, and tests.

License

This project is licensed under CC BY-NC-SA 4.0.

Attribution is required, commercial use is not allowed, and derivative works must use the same license.