Metadata-Version: 2.4
Name: dustylm
Version: 0.1.0
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 two 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 | Footprint | Use case |
|---|---|---|---|
| `torch` (default) | `pip install dustylm` | ~800MB (PyTorch) | Inspectable, hackable |
| `onnx` | `pip install dustylm[onnx]` | ~10MB (ONNX) | Lightweight deployment |

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

## Loading from a local directory

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

The directory must contain `tokenizer.json` and either `model.pt` (torch) or `model_int8.onnx` (onnx).

## Advanced Usage: Loading Custom Training Runs

If you used the main [`dusty-lm`](https://github.com/khordoo/dusty-lm) repository to train your own character or experiment with different hyperparameters, the SDK will automatically detect your model's architecture from its `state_dict` shapes.

You can load your custom local checkpoints by pointing `from_pretrained` to your directory and specifying your exact file names:

```python
from dustylm import DustyLM

model = DustyLM.from_pretrained(
    "./my-custom-training-run/",
    model_file="step_20000.pt",
    tokenizer_file="my_custom_tokenizer.json"
)

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

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