# kernelcero/bit-python-tutor architecture

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

- Interactive diagram: https://gitdiagram.com/kernelcero/bit-python-tutor
- Repository: https://github.com/kernelcero/bit-python-tutor
- Video tour (about a minute): https://gitdiagram.com/kernelcero/bit-python-tutor/video

## Overview

Bit is a local, terminal-based Python mentor. A student enters a question or `save` command; the terminal delegates to PythonTutor, which can enrich questions with referenced Python files, sends tutoring context to Ollama, and persists conversation history. The `save` path extracts Python code from the latest response into exercise files. README capabilities such as line-by-line explanations and challenges are implemented through the model prompt. The graph reflects the two sampled runtime files; it does not infer undocumented flows from requirements.

Main entry points: [`tutor_logic.py`](https://github.com/kernelcero/bit-python-tutor/blob/main/tutor_logic.py) (Python tutor), [`main.py`](https://github.com/kernelcero/bit-python-tutor/blob/main/main.py) (Terminal interface)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_terminal["Terminal session"]
  node_cli["Terminal interface<br/>[main.py]"]
end

subgraph group_mentor["Mentoring runtime"]
  node_tutor["Python tutor<br/>[tutor_logic.py]"]
  node_context["Code context<br/>[tutor_logic.py]"]
  node_prompt["Teaching prompt<br/>[tutor_logic.py]"]
end

subgraph group_localdata["Local learning data"]
  node_history[("Conversation history<br/>[tutor_logic.py]")]
  node_lessons["Saved exercises<br/>[tutor_logic.py]"]
end

subgraph group_ai["AI engine"]
  node_ollama{{"Ollama model"}}
end

node_student(("Student"))

node_student -->|"enters question"| node_cli
node_cli -->|"sends message"| node_tutor
node_tutor -->|"reads Python files"| node_context
node_tutor -->|"loads and saves"| node_history
node_tutor -->|"sets instructions"| node_prompt
node_tutor -->|"requests response"| node_ollama
node_tutor -->|"writes extracted code"| node_lessons
node_tutor -->|"returns response"| node_cli
node_cli -->|"displays answer"| node_student

click node_cli "https://github.com/kernelcero/bit-python-tutor/blob/main/main.py"
click node_tutor "https://github.com/kernelcero/bit-python-tutor/blob/main/tutor_logic.py"
click node_context "https://github.com/kernelcero/bit-python-tutor/blob/main/tutor_logic.py"
click node_prompt "https://github.com/kernelcero/bit-python-tutor/blob/main/tutor_logic.py"
click node_history "https://github.com/kernelcero/bit-python-tutor/blob/main/tutor_logic.py"
click node_lessons "https://github.com/kernelcero/bit-python-tutor/blob/main/tutor_logic.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 toneBlue
class node_tutor,node_context,node_prompt toneAmber
class node_history,node_lessons toneMint
class node_ollama toneRose
class node_student toneIndigo
```

## Components

### Terminal session

- [Terminal interface](https://github.com/kernelcero/bit-python-tutor/blob/main/main.py): `main.py`

### Mentoring runtime

- [Python tutor](https://github.com/kernelcero/bit-python-tutor/blob/main/tutor_logic.py): `tutor_logic.py`
- [Code context](https://github.com/kernelcero/bit-python-tutor/blob/main/tutor_logic.py): `tutor_logic.py`
- [Teaching prompt](https://github.com/kernelcero/bit-python-tutor/blob/main/tutor_logic.py): `tutor_logic.py`

### Local learning data

- [Conversation history](https://github.com/kernelcero/bit-python-tutor/blob/main/tutor_logic.py): `tutor_logic.py`
- [Saved exercises](https://github.com/kernelcero/bit-python-tutor/blob/main/tutor_logic.py): `tutor_logic.py`

### AI engine

- **Ollama model**

### Other components

- **Student**

## Connections

- Student → Terminal interface: enters question (evidence: `main.py`)
- Terminal interface → Python tutor: sends message (evidence: `main.py`)
- Python tutor → Code context: reads Python files (evidence: `tutor_logic.py`)
- Python tutor → Conversation history: loads and saves (evidence: `tutor_logic.py`)
- Python tutor → Teaching prompt: sets instructions (evidence: `tutor_logic.py`)
- Python tutor → Ollama model: requests response (evidence: `tutor_logic.py`)
- Python tutor → Saved exercises: writes extracted code (evidence: `tutor_logic.py`)
- Python tutor → Terminal interface: returns response (evidence: `main.py`)
- Terminal interface → Student: displays answer (evidence: `main.py`)
