Metadata-Version: 2.4
Name: pybot-hf
Version: 0.1.2
Summary: PyBot on PyPI: a chatbot written in plain Python. No weights, no training, just rules.
License-Expression: Apache-2.0
Project-URL: Repository, https://github.com/huggingface/pybot
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

<p align="center"><img src="https://raw.githubusercontent.com/huggingface/pybot/main/assets/banner.png" alt="PyBot: no weights, no training, just rules" width="100%"></p>

<div align="center">
  <a href="https://huggingface.co/spaces/HuggingFaceSwarms/PyBot" target="_blank">
    <img alt="Hugging Face Space: PyBot demo" src="https://img.shields.io/badge/%F0%9F%A4%97%20Hugging%20Face-Demo-ffc107?color=ffc107&logoColor=white" />
  </a>
</div>

# pybot-hf

PyBot, on PyPI. A chatbot written entirely in plain Python — no weights, no training, just rules — built by a swarm of over 1,000 agents. Around 640,000 lines of code and zero dependencies, with a win rate on [SmolTalkBench](https://huggingface.co/datasets/HuggingFaceSwarms/SmolTalkBench) on par with SmolLM-360M-Instruct.

This is the PyPI distribution of [PyBot](https://github.com/huggingface/pybot) by Hugging Face.

## Install

```sh
pip install pybot-hf
```

Python 3.8 or newer. No packages to install, no model to download.

## Use it

```sh
pybot
```

That starts a chat in your terminal:

```text
    ____        ____        __
   / __ \__  __/ __ )____  / /_
  / /_/ / / / / __  / __ \/ __/
 / ____/ /_/ / /_/ / /_/ / /_
/_/    \__, /_____/\____/\__/
      /____/

A chatbot written in plain Python. No weights, no training, just rules.
Type a message and press Enter. /reset starts a new conversation, /exit quits.

user: hi, i'm Sam
pybot: Nice to meet you, Sam. What can I help with?

user: my kettle is full of limescale, how do i get rid of it?
pybot: Half fill the kettle with equal parts water and white vinegar, or a sachet of citric acid, boil it and leave it half an hour, then tip it out and boil fresh water twice before you use it again. In a hard-water area do it every couple of months: the scale forms because hard water leaves calcium behind as it boils, and a thick layer makes the kettle slow and puts a scum on the tea.

user: how long does that take
pybot: Half an hour.

user: what's my name?
pybot: You're Sam.
```

Type `/reset` to clear the screen and start a new conversation, and `/exit` to quit. PyBot takes a few seconds to start, because Python has about 640,000 lines of code to load, and about a second to reply.

One question and exit, or one reply per piped line:

```sh
pybot -p "Why do onions make you cry?"
echo "how long should i boil an egg" | pybot
```

| Option | What it does |
|---|---|
| `-p TEXT`, `--prompt TEXT` | reply to this one message and exit |
| `-i`, `--interactive` | with `-p`, keep chatting after the first reply |
| `-s N`, `--seed N` | fix PyBot's choice of wording, to get the same replies again |
| `-v`, `--verbose` | after each reply, show the module that produced it and the time it took |

You can also try it in the browser on [Hugging Face](https://huggingface.co/spaces/HuggingFaceSwarms/PyBot), where each reply shows which of PyBot's modules produced it.

## How it works

Chatbots predate LLMs by decades — ELIZA held conversations in the 1960s by matching patterns in what the user typed and answering with predefined templates. PyBot asks how far that approach goes when a swarm of agents writes the rules instead: over 1,000 agents wrote and evaluated more than 5,000 versions, and the win rate on SmolTalkBench, where an LLM judge compares each reply with a reference answer, climbed from 0% to 26%.

![PyBot's win rate over the evaluated commits on a log scale: every commit as a dot and the best so far as a line, with three SmolLM baselines as dashed lines, and its lines of Python code in grey on the right axis](https://raw.githubusercontent.com/huggingface/pybot/main/assets/progress.png)

Every turn, each module in `bot/modules/` may propose a reply, and an arbiter (`bot/modules/arbiter.py`) picks the one you get. The modules build on four shared parts:

| Part | Where | Lines |
|---|---|---:|
| Understanding engine: what you typed and meant, with typos, chat-speak, the topic and what "it" refers to | `bot/understanding/` | 25,000 |
| Memory store: what you and PyBot have said so far | `bot/memory/` | 109,000 |
| Knowledge base: facts about the world, kept as data | `bot/knowledge/` | 317,000 |
| Response composer: how a reply is phrased, and what to say when nothing fits | `bot/compose/` | 104,000 |

The modules themselves are another 81,000 lines.

## From source

```sh
git clone https://github.com/huggingface/pybot
cd pybot
pip install .
```

## License

Apache License 2.0. See [LICENSE](https://github.com/huggingface/pybot/blob/main/LICENSE).
