# szczyglis-dev/py-gpt architecture

> Architecture diagram of the GitHub repository szczyglis-dev/py-gpt, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/szczyglis-dev/py-gpt
- Repository: https://github.com/szczyglis-dev/py-gpt

## Overview

PyGPT is a desktop AI assistant. A user works in its desktop interface, submits a prompt or media, and uses a selected mode to obtain a model response, tool action, or generated media; responses are rendered in the conversation. The README also documents agents, RAG, memory, realtime voice, search, integrations, and productivity features. The graph shows those major product areas, plus the sampled realtime-worker and provider-registration paths. Most feature wiring was not present in the excerpts, so uncertain internal calls are omitted.

Main entry points: [`src/pygpt_net/controller/chat`](https://github.com/szczyglis-dev/py-gpt/tree/master/src/pygpt_net/controller/chat) (Chat workflow), [`src/pygpt_net/core/llm/llm.py`](https://github.com/szczyglis-dev/py-gpt/blob/master/src/pygpt_net/core/llm/llm.py) (Model providers), [`src/pygpt_net/app.py`](https://github.com/szczyglis-dev/py-gpt/blob/master/src/pygpt_net/app.py) (Provider registration), [`src/pygpt_net/ui/main.py`](https://github.com/szczyglis-dev/py-gpt/blob/master/src/pygpt_net/ui/main.py) (Desktop window)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop experience"]
  node_window["Desktop window<br/>[main.py]"]
  node_controller["UI controllers"]
  node_app_registry["Provider registration<br/>[app.py]"]
end

subgraph group_conversation["Conversation runtime"]
  node_chat["Chat workflow"]
  node_render["Response rendering"]
end

subgraph group_capabilities["AI capabilities"]
  node_llm["Model providers<br/>[llm.py]"]
  node_provider_services["External model services"]
  node_agents["Agent workflows"]
  node_agent_v2["Agents v2"]
  node_rag["RAG and indexing"]
  node_plugins_tools["Plugins and tools<br/>[plugins.py]"]
  node_connectors["MCP connectors<br/>[connectors.py]"]
  node_media["Image and video<br/>[image.py]"]
  node_realtime_manager["Realtime manager<br/>[manager.py]"]
  node_realtime_worker["Realtime worker<br/>[worker.py]"]
  node_audio["Audio services<br/>[audio.py]"]
end

subgraph group_state["State and content"]
  node_ctx["Conversation context<br/>[manager.py]"]
  node_history_db[("Application database<br/>[database.py]")]
  node_calendar["Calendar and notes<br/>[calendar.py]"]
  node_notepad["Notepad<br/>[notepad.py]"]
end

node_user(("User"))

node_user -->|"uses"| node_window
node_window -->|"sets up"| node_controller
node_controller -->|"handles chat"| node_chat
node_chat -->|"requests completion"| node_llm
node_llm -->|"calls provider"| node_provider_services
node_chat -->|"renders response"| node_render
node_app_registry -->|"registers providers"| node_llm
node_app_registry -->|"registers tools"| node_plugins_tools
node_realtime_manager -->|"starts worker"| node_realtime_worker
node_realtime_worker -->|"processes audio"| node_audio
node_chat -->|"uses context"| node_ctx
node_ctx -->|"persists context"| node_history_db

click node_window "https://github.com/szczyglis-dev/py-gpt/blob/master/src/pygpt_net/ui/main.py"
click node_controller "https://github.com/szczyglis-dev/py-gpt/tree/master/src/pygpt_net/controller"
click node_chat "https://github.com/szczyglis-dev/py-gpt/tree/master/src/pygpt_net/controller/chat"
click node_render "https://github.com/szczyglis-dev/py-gpt/tree/master/src/pygpt_net/core/render"
click node_llm "https://github.com/szczyglis-dev/py-gpt/blob/master/src/pygpt_net/core/llm/llm.py"
click node_agents "https://github.com/szczyglis-dev/py-gpt/tree/master/src/pygpt_net/core/agents"
click node_agent_v2 "https://github.com/szczyglis-dev/py-gpt/tree/master/src/pygpt_net/core/agents_v2"
click node_rag "https://github.com/szczyglis-dev/py-gpt/tree/master/src/pygpt_net/core/idx"
click node_plugins_tools "https://github.com/szczyglis-dev/py-gpt/blob/master/src/pygpt_net/core/plugins/plugins.py"
click node_connectors "https://github.com/szczyglis-dev/py-gpt/blob/master/src/pygpt_net/core/connectors/connectors.py"
click node_media "https://github.com/szczyglis-dev/py-gpt/blob/master/src/pygpt_net/core/image/image.py"
click node_realtime_manager "https://github.com/szczyglis-dev/py-gpt/blob/master/src/pygpt_net/controller/realtime/manager.py"
click node_realtime_worker "https://github.com/szczyglis-dev/py-gpt/blob/master/src/pygpt_net/core/realtime/worker.py"
click node_audio "https://github.com/szczyglis-dev/py-gpt/blob/master/src/pygpt_net/core/audio/audio.py"
click node_ctx "https://github.com/szczyglis-dev/py-gpt/blob/master/src/pygpt_net/core/context_manager/manager.py"
click node_history_db "https://github.com/szczyglis-dev/py-gpt/blob/master/src/pygpt_net/core/db/database.py"
click node_calendar "https://github.com/szczyglis-dev/py-gpt/blob/master/src/pygpt_net/core/calendar/calendar.py"
click node_notepad "https://github.com/szczyglis-dev/py-gpt/blob/master/src/pygpt_net/core/notepad/notepad.py"
click node_app_registry "https://github.com/szczyglis-dev/py-gpt/blob/master/src/pygpt_net/app.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_window,node_controller,node_app_registry,node_user toneBlue
class node_chat,node_render toneAmber
class node_llm,node_provider_services,node_agents,node_agent_v2,node_rag,node_plugins_tools,node_connectors,node_media,node_realtime_manager,node_realtime_worker,node_audio toneMint
class node_ctx,node_history_db,node_calendar,node_notepad toneRose
```

## Components

### Desktop experience

- [Desktop window](https://github.com/szczyglis-dev/py-gpt/blob/master/src/pygpt_net/ui/main.py): `src/pygpt_net/ui/main.py`
- [UI controllers](https://github.com/szczyglis-dev/py-gpt/tree/master/src/pygpt_net/controller): `src/pygpt_net/controller`
- [Provider registration](https://github.com/szczyglis-dev/py-gpt/blob/master/src/pygpt_net/app.py): `src/pygpt_net/app.py`

### Conversation runtime

- [Chat workflow](https://github.com/szczyglis-dev/py-gpt/tree/master/src/pygpt_net/controller/chat): `src/pygpt_net/controller/chat`
- [Response rendering](https://github.com/szczyglis-dev/py-gpt/tree/master/src/pygpt_net/core/render): `src/pygpt_net/core/render`

### AI capabilities

- [Model providers](https://github.com/szczyglis-dev/py-gpt/blob/master/src/pygpt_net/core/llm/llm.py): `src/pygpt_net/core/llm/llm.py`
- **External model services**
- [Agent workflows](https://github.com/szczyglis-dev/py-gpt/tree/master/src/pygpt_net/core/agents): `src/pygpt_net/core/agents`
- [Agents v2](https://github.com/szczyglis-dev/py-gpt/tree/master/src/pygpt_net/core/agents_v2): `src/pygpt_net/core/agents_v2`
- [RAG and indexing](https://github.com/szczyglis-dev/py-gpt/tree/master/src/pygpt_net/core/idx): `src/pygpt_net/core/idx`
- [Plugins and tools](https://github.com/szczyglis-dev/py-gpt/blob/master/src/pygpt_net/core/plugins/plugins.py): `src/pygpt_net/core/plugins/plugins.py`
- [MCP connectors](https://github.com/szczyglis-dev/py-gpt/blob/master/src/pygpt_net/core/connectors/connectors.py): `src/pygpt_net/core/connectors/connectors.py`
- [Image and video](https://github.com/szczyglis-dev/py-gpt/blob/master/src/pygpt_net/core/image/image.py): `src/pygpt_net/core/image/image.py`
- [Realtime manager](https://github.com/szczyglis-dev/py-gpt/blob/master/src/pygpt_net/controller/realtime/manager.py): `src/pygpt_net/controller/realtime/manager.py`
- [Realtime worker](https://github.com/szczyglis-dev/py-gpt/blob/master/src/pygpt_net/core/realtime/worker.py): `src/pygpt_net/core/realtime/worker.py`
- [Audio services](https://github.com/szczyglis-dev/py-gpt/blob/master/src/pygpt_net/core/audio/audio.py): `src/pygpt_net/core/audio/audio.py`

### State and content

- [Conversation context](https://github.com/szczyglis-dev/py-gpt/blob/master/src/pygpt_net/core/context_manager/manager.py): `src/pygpt_net/core/context_manager/manager.py`
- [Application database](https://github.com/szczyglis-dev/py-gpt/blob/master/src/pygpt_net/core/db/database.py): `src/pygpt_net/core/db/database.py`
- [Calendar and notes](https://github.com/szczyglis-dev/py-gpt/blob/master/src/pygpt_net/core/calendar/calendar.py): `src/pygpt_net/core/calendar/calendar.py`
- [Notepad](https://github.com/szczyglis-dev/py-gpt/blob/master/src/pygpt_net/core/notepad/notepad.py): `src/pygpt_net/core/notepad/notepad.py`

### Other components

- **User**

## Connections

- User → Desktop window: uses
- Desktop window → UI controllers: sets up
- UI controllers → Chat workflow: handles chat
- Chat workflow → Model providers: requests completion
- Model providers → External model services: calls provider
- Chat workflow → Response rendering: renders response
- Provider registration → Model providers: registers providers
- Provider registration → Plugins and tools: registers tools
- Realtime manager → Realtime worker: starts worker
- Realtime worker → Audio services: processes audio
- Chat workflow → Conversation context: uses context
- Conversation context → Application database: persists context