# huggingface/pybot architecture

> Architecture diagram of the GitHub repository huggingface/pybot, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/huggingface/pybot
- Repository: https://github.com/huggingface/pybot

## Overview

PyBot is a rule-based conversational chatbot: a user sends a line through the CLI, the understanding lane interprets it, conversation memory supplies context, reply modules propose candidates, and the arbiter selects the response. The README documents four shared capabilities—understanding, memory, knowledge, and composition—alongside the per-turn proposal and arbitration workflow. The sampled files and README support these major relationships; many individual reply and knowledge modules were not sampled, so their internal connections are not inferred.

Main entry points: [`bot/modules`](https://github.com/huggingface/pybot/tree/main/bot/modules) (Reply modules), [`bot/compose/__init__.py`](https://github.com/huggingface/pybot/blob/main/bot/compose/__init__.py) (Response composer), [`bot/understanding/__init__.py`](https://github.com/huggingface/pybot/blob/main/bot/understanding/__init__.py) (Understanding lane), [`bot/modules/memory_store.py`](https://github.com/huggingface/pybot/blob/main/bot/modules/memory_store.py) (Memory store)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Chat entry"]
  node_cli["CLI<br/>[pybot.py]"]
  node_runtime["Chat runtime<br/>[runtime.py]"]
end

subgraph group_interpret["Understanding"]
  node_interpret_lane["Understanding lane<br/>[__init__.py]"]
  node_normalization["Text normalization<br/>[normalize.py]"]
  node_classification["Intent and kind<br/>[kinds.py]"]
  node_topic_reading["Topic reading<br/>[topics.py]"]
  node_lexicon["Word lexicon<br/>[lexicon.py]"]
end

subgraph group_context["Conversation context"]
  node_memory_lane["Memory store<br/>[memory_store.py]"]
  node_memory_topics["Topic memory<br/>[topics.py]"]
  node_memory_history["Turn history<br/>[history.py]"]
  node_memory_facts["Fact memory<br/>[facts.py]"]
end

subgraph group_answers["Answering"]
  node_knowledge_lookup["Knowledge matching<br/>[lookup.py]"]
  node_knowledge_base["Domain knowledge"]
  node_reply_modules["Reply modules"]
  node_arbiter["Reply arbiter<br/>[arbiter.py]"]
  node_memory_ack["Acknowledgement reply<br/>[ack.py]"]
end

subgraph group_phrasing["Response composition"]
  node_composer["Response composer<br/>[__init__.py]"]
  node_fallback["Fallback replies<br/>[fallback.py]"]
  node_goodnews["Good-news replies<br/>[goodnews.py]"]
  node_badnews["Hard-news patterns<br/>[badnews.py]"]
  node_loss["Loss responses<br/>[loss.py]"]
end

node_user(("Chat user"))

node_user -->|"sends message"| node_cli
node_cli -->|"starts"| node_runtime
node_runtime -->|"loads modules"| node_reply_modules
node_reply_modules -->|"proposes replies"| node_arbiter
node_arbiter -->|"returns selected reply"| node_user
node_interpret_lane -->|"normalizes text"| node_normalization
node_interpret_lane -->|"classifies line"| node_classification
node_interpret_lane -->|"reads topics"| node_topic_reading
node_normalization -->|"uses vocabulary"| node_lexicon
node_reply_modules -->|"reads interpretation"| node_interpret_lane
node_reply_modules -->|"uses turn memory"| node_memory_lane
node_memory_lane -->|"writes topic state"| node_memory_topics
node_memory_lane -->|"updates facts"| node_memory_facts
node_memory_history -->|"reads topics"| node_memory_topics
node_reply_modules -->|"matches knowledge"| node_knowledge_lookup
node_knowledge_lookup -->|"searches entries"| node_knowledge_base
node_reply_modules -->|"requests acknowledgement"| node_memory_ack
node_arbiter -->|"selects composed replies"| node_composer
node_composer -->|"provides fallback"| node_fallback
node_composer -->|"uses good-news replies"| node_goodnews
node_composer -->|"checks hard-news patterns"| node_badnews
node_composer -->|"handles loss"| node_loss
node_badnews -->|"coordinates replies"| node_goodnews
node_memory_ack -->|"phrases response"| node_composer

click node_cli "https://github.com/huggingface/pybot/blob/main/pybot.py"
click node_runtime "https://github.com/huggingface/pybot/blob/main/bot/runtime.py"
click node_interpret_lane "https://github.com/huggingface/pybot/blob/main/bot/understanding/__init__.py"
click node_normalization "https://github.com/huggingface/pybot/blob/main/bot/understanding/normalize.py"
click node_classification "https://github.com/huggingface/pybot/blob/main/bot/understanding/kinds.py"
click node_topic_reading "https://github.com/huggingface/pybot/blob/main/bot/understanding/topics.py"
click node_lexicon "https://github.com/huggingface/pybot/blob/main/bot/understanding/lexicon.py"
click node_memory_lane "https://github.com/huggingface/pybot/blob/main/bot/modules/memory_store.py"
click node_memory_topics "https://github.com/huggingface/pybot/blob/main/bot/memory/topics.py"
click node_memory_history "https://github.com/huggingface/pybot/blob/main/bot/memory/history.py"
click node_knowledge_lookup "https://github.com/huggingface/pybot/blob/main/bot/knowledge/lookup.py"
click node_knowledge_base "https://github.com/huggingface/pybot/tree/main/bot/knowledge"
click node_reply_modules "https://github.com/huggingface/pybot/tree/main/bot/modules"
click node_arbiter "https://github.com/huggingface/pybot/blob/main/bot/modules/arbiter.py"
click node_memory_ack "https://github.com/huggingface/pybot/blob/main/bot/memory/ack.py"
click node_memory_facts "https://github.com/huggingface/pybot/blob/main/bot/memory/facts.py"
click node_composer "https://github.com/huggingface/pybot/blob/main/bot/compose/__init__.py"
click node_fallback "https://github.com/huggingface/pybot/blob/main/bot/compose/fallback.py"
click node_goodnews "https://github.com/huggingface/pybot/blob/main/bot/compose/goodnews.py"
click node_badnews "https://github.com/huggingface/pybot/blob/main/bot/compose/badnews.py"
click node_loss "https://github.com/huggingface/pybot/blob/main/bot/compose/loss.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_runtime,node_user toneBlue
class node_interpret_lane,node_normalization,node_classification,node_topic_reading,node_lexicon toneAmber
class node_memory_lane,node_memory_topics,node_memory_history,node_memory_facts toneMint
class node_knowledge_lookup,node_knowledge_base,node_reply_modules,node_arbiter,node_memory_ack toneRose
class node_composer,node_fallback,node_goodnews,node_badnews,node_loss toneIndigo
```

## Components

### Chat entry

- [CLI](https://github.com/huggingface/pybot/blob/main/pybot.py): `pybot.py`
- [Chat runtime](https://github.com/huggingface/pybot/blob/main/bot/runtime.py): `bot/runtime.py`

### Understanding

- [Understanding lane](https://github.com/huggingface/pybot/blob/main/bot/understanding/__init__.py): `bot/understanding/__init__.py`
- [Text normalization](https://github.com/huggingface/pybot/blob/main/bot/understanding/normalize.py): `bot/understanding/normalize.py`
- [Intent and kind](https://github.com/huggingface/pybot/blob/main/bot/understanding/kinds.py): `bot/understanding/kinds.py`
- [Topic reading](https://github.com/huggingface/pybot/blob/main/bot/understanding/topics.py): `bot/understanding/topics.py`
- [Word lexicon](https://github.com/huggingface/pybot/blob/main/bot/understanding/lexicon.py): `bot/understanding/lexicon.py`

### Conversation context

- [Memory store](https://github.com/huggingface/pybot/blob/main/bot/modules/memory_store.py): `bot/modules/memory_store.py`
- [Topic memory](https://github.com/huggingface/pybot/blob/main/bot/memory/topics.py): `bot/memory/topics.py`
- [Turn history](https://github.com/huggingface/pybot/blob/main/bot/memory/history.py): `bot/memory/history.py`
- [Fact memory](https://github.com/huggingface/pybot/blob/main/bot/memory/facts.py): `bot/memory/facts.py`

### Answering

- [Knowledge matching](https://github.com/huggingface/pybot/blob/main/bot/knowledge/lookup.py): `bot/knowledge/lookup.py`
- [Domain knowledge](https://github.com/huggingface/pybot/tree/main/bot/knowledge): `bot/knowledge`
- [Reply modules](https://github.com/huggingface/pybot/tree/main/bot/modules): `bot/modules`
- [Reply arbiter](https://github.com/huggingface/pybot/blob/main/bot/modules/arbiter.py): `bot/modules/arbiter.py`
- [Acknowledgement reply](https://github.com/huggingface/pybot/blob/main/bot/memory/ack.py): `bot/memory/ack.py`

### Response composition

- [Response composer](https://github.com/huggingface/pybot/blob/main/bot/compose/__init__.py): `bot/compose/__init__.py`
- [Fallback replies](https://github.com/huggingface/pybot/blob/main/bot/compose/fallback.py): `bot/compose/fallback.py`
- [Good-news replies](https://github.com/huggingface/pybot/blob/main/bot/compose/goodnews.py): `bot/compose/goodnews.py`
- [Hard-news patterns](https://github.com/huggingface/pybot/blob/main/bot/compose/badnews.py): `bot/compose/badnews.py`
- [Loss responses](https://github.com/huggingface/pybot/blob/main/bot/compose/loss.py): `bot/compose/loss.py`

### Other components

- **Chat user**

## Connections

- Chat user → CLI: sends message (evidence: `README.md`)
- CLI → Chat runtime: starts (evidence: `pybot.py`)
- Chat runtime → Reply modules: loads modules (evidence: `bot/runtime.py`)
- Reply modules → Reply arbiter: proposes replies (evidence: `README.md`)
- Reply arbiter → Chat user: returns selected reply (evidence: `README.md`)
- Understanding lane → Text normalization: normalizes text (evidence: `bot/understanding/__init__.py`)
- Understanding lane → Intent and kind: classifies line (evidence: `bot/understanding/__init__.py`)
- Understanding lane → Topic reading: reads topics (evidence: `bot/understanding/__init__.py`)
- Text normalization → Word lexicon: uses vocabulary (evidence: `bot/understanding/normalize.py`)
- Reply modules → Understanding lane: reads interpretation (evidence: `bot/understanding/__init__.py`)
- Reply modules → Memory store: uses turn memory (evidence: `README.md`)
- Memory store → Topic memory: writes topic state (evidence: `bot/memory/topics.py`)
- Memory store → Fact memory: updates facts (evidence: `bot/modules/memory_store.py`)
- Turn history → Topic memory: reads topics (evidence: `bot/memory/history.py`)
- Reply modules → Knowledge matching: matches knowledge (evidence: `bot/knowledge/lookup.py`)
- Knowledge matching → Domain knowledge: searches entries (evidence: `bot/knowledge/lookup.py`)
- Reply modules → Acknowledgement reply: requests acknowledgement (evidence: `bot/memory/ack.py`)
- Reply arbiter → Response composer: selects composed replies (evidence: `bot/modules/arbiter.py`)
- Response composer → Fallback replies: provides fallback (evidence: `bot/compose/__init__.py`)
- Response composer → Good-news replies: uses good-news replies (evidence: `bot/compose/goodnews.py`)
- Response composer → Hard-news patterns: checks hard-news patterns (evidence: `bot/compose/badnews.py`)
- Response composer → Loss responses: handles loss (evidence: `bot/compose/loss.py`)
- Hard-news patterns → Good-news replies: coordinates replies (evidence: `bot/compose/badnews.py`)
- Acknowledgement reply → Response composer: phrases response (evidence: `bot/memory/ack.py`)
