# gmsoft-tuxicoman/gmbot architecture

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

- Interactive diagram: https://gitdiagram.com/gmsoft-tuxicoman/gmbot
- Repository: https://github.com/gmsoft-tuxicoman/gmbot

## Overview

GMbot is an asyncio IRC bot that engages when mentioned, follows active conversations using an OpenAI-compatible chat model, and returns to idle when the model ends the exchange or it times out. The runtime path is IRC messages through Bot’s routing and debounce logic, prompt construction from conversation history/persona/memory, LLM response parsing, then paced IRC replies and memory updates. Owner commands provide a separate direct-control path. The README documents protocol, memory, and command capabilities; some implementation details are unsampled, so unsupported links are omitted.

Main entry points: [`gmbot/bot.py`](https://github.com/gmsoft-tuxicoman/gmbot/blob/master/gmbot/bot.py) (Bot orchestration), [`gmbot/irc.py`](https://github.com/gmsoft-tuxicoman/gmbot/blob/master/gmbot/irc.py) (IRC client), [`gmbot/__main__.py`](https://github.com/gmsoft-tuxicoman/gmbot/blob/master/gmbot/__main__.py) (Runtime entry), [`gmbot/commands.py`](https://github.com/gmsoft-tuxicoman/gmbot/blob/master/gmbot/commands.py) (Owner commands)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Runtime setup"]
  node_main["Runtime entry<br/>[__main__.py]"]
  node_config["Configuration<br/>[config.py]"]
end

subgraph group_irc["IRC transport"]
  node_ircclient["IRC client<br/>[irc.py]"]
end

subgraph group_chat["Conversation engine"]
  node_bot["Bot orchestration<br/>[bot.py]"]
  node_conversation["Conversation state<br/>[conversation.py]"]
  node_llm["LLM client<br/>[llm.py]"]
end

subgraph group_context["Context and memory"]
  node_history["History and prompts<br/>[history.py]"]
  node_instructions["Persona file<br/>[INSTRUCTIONS.md]"]
  node_memory[("Long-term memory<br/>[memory.py]")]
end

subgraph group_control["Owner control"]
  node_commands["Owner commands<br/>[commands.py]"]
end

node_operator(("Operator"))
node_ircserver(("IRC server"))
node_endpoint(("Chat endpoint"))

node_operator -->|"starts bot"| node_main
node_main -->|"loads settings"| node_config
node_main -->|"runs"| node_bot
node_bot -->|"receives messages"| node_ircclient
node_ircclient -->|"connects and exchanges"| node_ircserver
node_ircclient -->|"dispatches messages"| node_bot
node_bot -->|"routes owner commands"| node_commands
node_commands -->|"sends control actions"| node_ircclient
node_commands -->|"manages facts"| node_memory
node_bot -->|"activates and tracks"| node_conversation
node_bot -->|"records messages"| node_history
node_bot -->|"loads persona"| node_instructions
node_bot -->|"updates and reads facts"| node_memory
node_bot -->|"builds prompt context"| node_history
node_bot -->|"requests generation"| node_llm
node_llm -->|"posts completions"| node_endpoint
node_bot -->|"parses model decisions"| node_conversation
node_bot -->|"sends replies"| node_ircclient
node_ircclient -->|"sends paced IRC output"| node_ircserver

click node_main "https://github.com/gmsoft-tuxicoman/gmbot/blob/master/gmbot/__main__.py"
click node_config "https://github.com/gmsoft-tuxicoman/gmbot/blob/master/gmbot/config.py"
click node_bot "https://github.com/gmsoft-tuxicoman/gmbot/blob/master/gmbot/bot.py"
click node_ircclient "https://github.com/gmsoft-tuxicoman/gmbot/blob/master/gmbot/irc.py"
click node_commands "https://github.com/gmsoft-tuxicoman/gmbot/blob/master/gmbot/commands.py"
click node_conversation "https://github.com/gmsoft-tuxicoman/gmbot/blob/master/gmbot/conversation.py"
click node_history "https://github.com/gmsoft-tuxicoman/gmbot/blob/master/gmbot/history.py"
click node_instructions "https://github.com/gmsoft-tuxicoman/gmbot/blob/master/INSTRUCTIONS.md"
click node_memory "https://github.com/gmsoft-tuxicoman/gmbot/blob/master/gmbot/memory.py"
click node_llm "https://github.com/gmsoft-tuxicoman/gmbot/blob/master/gmbot/llm.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_main,node_config toneBlue
class node_ircclient toneAmber
class node_bot,node_conversation,node_llm,node_ircserver toneMint
class node_history,node_instructions,node_memory toneRose
class node_commands,node_operator,node_endpoint toneIndigo
```

## Components

### Runtime setup

- [Runtime entry](https://github.com/gmsoft-tuxicoman/gmbot/blob/master/gmbot/__main__.py): `gmbot/__main__.py`
- [Configuration](https://github.com/gmsoft-tuxicoman/gmbot/blob/master/gmbot/config.py): `gmbot/config.py`

### IRC transport

- [IRC client](https://github.com/gmsoft-tuxicoman/gmbot/blob/master/gmbot/irc.py): `gmbot/irc.py`

### Conversation engine

- [Bot orchestration](https://github.com/gmsoft-tuxicoman/gmbot/blob/master/gmbot/bot.py): `gmbot/bot.py`
- [Conversation state](https://github.com/gmsoft-tuxicoman/gmbot/blob/master/gmbot/conversation.py): `gmbot/conversation.py`
- [LLM client](https://github.com/gmsoft-tuxicoman/gmbot/blob/master/gmbot/llm.py): `gmbot/llm.py`

### Context and memory

- [History and prompts](https://github.com/gmsoft-tuxicoman/gmbot/blob/master/gmbot/history.py): `gmbot/history.py`
- [Persona file](https://github.com/gmsoft-tuxicoman/gmbot/blob/master/INSTRUCTIONS.md): `INSTRUCTIONS.md`
- [Long-term memory](https://github.com/gmsoft-tuxicoman/gmbot/blob/master/gmbot/memory.py): `gmbot/memory.py`

### Owner control

- [Owner commands](https://github.com/gmsoft-tuxicoman/gmbot/blob/master/gmbot/commands.py): `gmbot/commands.py`

### Other components

- **Operator**
- **IRC server**
- **Chat endpoint**

## Connections

- Operator → Runtime entry: starts bot (evidence: `README.md`)
- Runtime entry → Configuration: loads settings (evidence: `gmbot/__main__.py`)
- Runtime entry → Bot orchestration: runs (evidence: `gmbot/__main__.py`)
- Bot orchestration → IRC client: receives messages (evidence: `gmbot/bot.py`)
- IRC client → IRC server: connects and exchanges (evidence: `README.md`)
- IRC client → Bot orchestration: dispatches messages (evidence: `gmbot/bot.py`)
- Bot orchestration → Owner commands: routes owner commands (evidence: `gmbot/bot.py`)
- Owner commands → IRC client: sends control actions (evidence: `gmbot/commands.py`)
- Owner commands → Long-term memory: manages facts (evidence: `gmbot/commands.py`)
- Bot orchestration → Conversation state: activates and tracks (evidence: `gmbot/bot.py`)
- Bot orchestration → History and prompts: records messages (evidence: `gmbot/bot.py`)
- Bot orchestration → Persona file: loads persona (evidence: `README.md`)
- Bot orchestration → Long-term memory: updates and reads facts (evidence: `gmbot/bot.py`)
- Bot orchestration → History and prompts: builds prompt context (evidence: `README.md`)
- Bot orchestration → LLM client: requests generation (evidence: `gmbot/bot.py`)
- LLM client → Chat endpoint: posts completions (evidence: `gmbot/llm.py`)
- Bot orchestration → Conversation state: parses model decisions (evidence: `gmbot/bot.py`)
- Bot orchestration → IRC client: sends replies (evidence: `gmbot/bot.py`)
- IRC client → IRC server: sends paced IRC output (evidence: `README.md`)
