Metadata-Version: 2.4
Name: how-agentic
Version: 0.1.0
Summary: How-Agentic: a tutorial-first framework for training a small agent model from scratch
Project-URL: Homepage, https://github.com/how-agentic/how-agentic
Project-URL: Documentation, https://github.com/how-agentic/how-agentic#readme
Project-URL: Repository, https://github.com/how-agentic/how-agentic
Author: HowAgentic Team
License-Expression: CC-BY-NC-SA-4.0
License-File: LICENSE
Keywords: agent,dpo,grpo,llm,ppo,rl,sft,training
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: Free for non-commercial use
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: <3.13,>=3.12
Requires-Dist: pyyaml<6.1.0,>=6.0.3
Provides-Extra: all
Requires-Dist: accelerate<1.14.0,>=1.13.0; extra == 'all'
Requires-Dist: datasets<4.9.0,>=4.8.4; extra == 'all'
Requires-Dist: mypy<1.21.0,>=1.20.1; extra == 'all'
Requires-Dist: pytest-cov<7.2.0,>=7.1.0; extra == 'all'
Requires-Dist: pytest<9.1.0,>=9.0.3; extra == 'all'
Requires-Dist: ruff<0.16.0,>=0.15.11; extra == 'all'
Requires-Dist: safetensors<0.8.0,>=0.7.0; extra == 'all'
Requires-Dist: swanlab<0.8.0,>=0.7.15; extra == 'all'
Requires-Dist: tokenizers<0.23.0,>=0.22.2; extra == 'all'
Requires-Dist: torch<2.7.0,>=2.6.0; extra == 'all'
Requires-Dist: tqdm<4.68.0,>=4.67.3; extra == 'all'
Requires-Dist: transformers<5.6.0,>=5.5.4; extra == 'all'
Requires-Dist: typing-extensions<5.0.0,>=4.15.0; extra == 'all'
Requires-Dist: wandb<0.27.0,>=0.26.0; extra == 'all'
Provides-Extra: dev
Requires-Dist: mypy<1.21.0,>=1.20.1; extra == 'dev'
Requires-Dist: pytest-cov<7.2.0,>=7.1.0; extra == 'dev'
Requires-Dist: pytest<9.1.0,>=9.0.3; extra == 'dev'
Requires-Dist: ruff<0.16.0,>=0.15.11; extra == 'dev'
Provides-Extra: train
Requires-Dist: accelerate<1.14.0,>=1.13.0; extra == 'train'
Requires-Dist: datasets<4.9.0,>=4.8.4; extra == 'train'
Requires-Dist: safetensors<0.8.0,>=0.7.0; extra == 'train'
Requires-Dist: swanlab<0.8.0,>=0.7.15; extra == 'train'
Requires-Dist: tokenizers<0.23.0,>=0.22.2; extra == 'train'
Requires-Dist: torch<2.7.0,>=2.6.0; extra == 'train'
Requires-Dist: tqdm<4.68.0,>=4.67.3; extra == 'train'
Requires-Dist: transformers<5.6.0,>=5.5.4; extra == 'train'
Requires-Dist: typing-extensions<5.0.0,>=4.15.0; extra == 'train'
Requires-Dist: wandb<0.27.0,>=0.26.0; extra == 'train'
Description-Content-Type: text/markdown

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

```text
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:

```bash
pip install how-agentic
```

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

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

Or with uv:

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

## CLI

```bash
python -m how_agentic.cli --help
```

or:

```bash
how-agentic --help
```

## M0 Quick Path

Train tokenizer:

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

Pretrain:

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

Export pretrained model:

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

Infer with pretrained model:

```bash
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:

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

Run M0 SFT:

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

Export SFT model:

```bash
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:

```bash
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:

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

## Docs

Quickstart:

```text
docs/quickstart.md
```

M0 reproduction:

```text
docs/m0-reproduction.md
```

CLI reference:

```text
docs/cli-reference.md
```

Configuration guide:

```text
docs/configuration.md
```

Roadmap:

```text
docs/roadmap.md
```

Publishing:

```text
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.
