Metadata-Version: 2.4
Name: dustylm
Version: 0.1.1
Summary: The official Python SDK for DustyLM: an 8M-parameter model that talks like a robot vacuum.
Author-email: Mahmood Khordoo <m.khordoo@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/khordoo/dustylm-sdk
Project-URL: Source, https://github.com/khordoo/dustylm-sdk
Keywords: llm,slm,small-language-model,transformer,pytorch,onnx,inference
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Education
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: torch>=2.0
Requires-Dist: tokenizers>=0.15
Requires-Dist: huggingface-hub>=0.20
Requires-Dist: numpy>=1.24
Provides-Extra: onnx
Requires-Dist: onnxruntime>=1.15; extra == "onnx"

<p align="center">
  <img src="https://raw.githubusercontent.com/khordoo/dustylm-sdk/main/assets/logo.png" alt="DustyLM Logo" width="200"/>
</p>

# dustylm

Run DustyLM, the 8M parameter robot vacuum language model, in a few lines.

```
pip install dustylm
```

```python
from dustylm import DustyLM
model = DustyLM.from_pretrained("mkhordoo/dusty-8m-sft")
response = model.chat([{"role": "user", "content": "who are you?"}])
print(response["choices"][0]["message"]["content"])

# beep. i am a little robot. i clean floors and find crumbs.
```

## Backends

| Backend | Install | Model file | Best for |
|---|---|---:|---|
| `torch` (default) | `pip install dustylm` | ~32 MB (FP32) | Inspection and experimentation |
| `onnx` | `pip install dustylm[onnx]` | ~8–10 MB (int8) | A compact model artifact |

These sizes describe the model files, not the complete Python environment.
Installation size varies by platform. Both backends currently include PyTorch as
an SDK dependency.

```python
# ONNX backend
model = DustyLM.from_pretrained("mkhordoo/dusty-8m-sft", backend="onnx")
```

## Loading Local Checkpoints

Pass a Hugging Face repository ID to download its model and tokenizer
automatically, as shown in the quick-start example:

```python
model = DustyLM.from_pretrained("mkhordoo/dusty-8m-sft")
```

For files already downloaded to your machine, pass their local directory
instead. With the default filenames, that directory must contain
`tokenizer.json` and either `model.pt` (PyTorch) or `model_int8.onnx` (ONNX):

```python
model = DustyLM.from_pretrained("./my-checkpoint/")
```

You can use any local directory as the artifact root. `model_file` and
`tokenizer_file` are resolved relative to that directory, so they may use
different filenames or relative paths.

If you trained a model with the main
[`dusty-lm`](https://github.com/khordoo/dusty-lm) repository, its checkpoint and
tokenizer are stored in separate artifact directories. Load the promoted SFT
checkpoint with:

```python
from dustylm import DustyLM

model = DustyLM.from_pretrained(
    "artifacts/checkpoints",
    model_file="dusty8m_sft.pt",
    tokenizer_file="../tokenizers/dusty_tokenizer.json",
)

response = model.chat([{"role": "user", "content": "who are you?"}])
```

To inspect an intermediate checkpoint instead, change `model_file` to an
existing step file such as `dusty8m_sft_step_100.pt`.

The SDK infers several architecture dimensions from PyTorch checkpoint shapes
and currently expects DustyLM-compatible configurations.

## API

### DustyLM.from_pretrained

```python
DustyLM.from_pretrained(
    repo_id_or_path: str = "mkhordoo/dusty-8m-sft",
    *,
    model_file: str | None = None,
    tokenizer_file: str | None = None,
    backend: str = "torch",
)
```

| Argument | Default | Description |
|---|---|---|
| `repo_id_or_path` | `"mkhordoo/dusty-8m-sft"` | HF Hub repo ID or local directory path |
| `model_file` | `"model.pt"` (torch) / `"model_int8.onnx"` (onnx) | Override the model filename in the directory |
| `tokenizer_file` | `"tokenizer.json"` | Override the tokenizer filename |
| `backend` | `"torch"` | `"torch"` or `"onnx"` |

### DustyLM.chat

```python
model.chat(
    messages: list[dict],
    temperature: float = 0.7,
    max_tokens: int = 64,
    top_p: float = 0.9,
) -> dict
```

Returns an OpenAI-style chat completion dict.

---

Built from the [dusty-lm](https://github.com/khordoo/dusty-lm) training repository.
