403 lines
10 KiB
Markdown
403 lines
10 KiB
Markdown
# Architecture Diagram - Agent Media
|
|
|
|
## System Overview
|
|
|
|
```mermaid
|
|
flowchart TB
|
|
subgraph Client["👤 Client"]
|
|
CHAT[Chat Interface<br/>OpenWebUI / CLI / Custom]
|
|
end
|
|
|
|
subgraph AgentMedia["🎬 Agent Media"]
|
|
subgraph API["API Layer"]
|
|
FASTAPI[FastAPI Server<br/>:8000]
|
|
end
|
|
|
|
subgraph Core["Core"]
|
|
AGENT[🤖 Agent<br/>Orchestrator]
|
|
MEMORY[🧠 Memory<br/>LTM + STM + Episodic]
|
|
end
|
|
|
|
subgraph Tools["Tools"]
|
|
T1[📁 Filesystem]
|
|
T2[🔍 Search]
|
|
T3[⬇️ Download]
|
|
end
|
|
end
|
|
|
|
subgraph LLM["🧠 LLM Provider"]
|
|
DEEPSEEK[DeepSeek API]
|
|
OLLAMA[Ollama<br/>Local]
|
|
end
|
|
|
|
subgraph External["☁️ External Services"]
|
|
TMDB[(TMDB<br/>Movie Database)]
|
|
KNABEN[(Knaben<br/>Torrent Search)]
|
|
QBIT[qBittorrent<br/>Download Client]
|
|
end
|
|
|
|
subgraph Storage["💾 Storage"]
|
|
JSON[(memory_data/<br/>ltm.json)]
|
|
MEDIA[(Media Folders<br/>/movies /tvshows)]
|
|
end
|
|
|
|
CHAT <-->|OpenAI API| FASTAPI
|
|
FASTAPI <--> AGENT
|
|
AGENT <--> MEMORY
|
|
AGENT <--> Tools
|
|
AGENT <-->|Chat Completion| LLM
|
|
|
|
T1 <--> MEDIA
|
|
T2 --> TMDB
|
|
T2 --> KNABEN
|
|
T3 --> QBIT
|
|
|
|
MEMORY <--> JSON
|
|
QBIT --> MEDIA
|
|
|
|
style AgentMedia fill:#1a1a2e,color:#fff
|
|
style AGENT fill:#ff6b6b,color:#fff
|
|
style MEMORY fill:#4ecdc4,color:#fff
|
|
```
|
|
|
|
## Detailed Architecture
|
|
|
|
```mermaid
|
|
flowchart TB
|
|
subgraph Clients["Clients"]
|
|
direction LR
|
|
OWU[OpenWebUI]
|
|
CLI[CLI Client]
|
|
CURL[cURL / HTTP]
|
|
end
|
|
|
|
subgraph LoadBalancer["Entry Point"]
|
|
NGINX[Nginx / Reverse Proxy<br/>Optional]
|
|
end
|
|
|
|
subgraph Application["Agent Media Application"]
|
|
direction TB
|
|
|
|
subgraph Presentation["Presentation Layer"]
|
|
EP1["/v1/chat/completions"]
|
|
EP2["/v1/models"]
|
|
EP3["/health"]
|
|
EP4["/memory/state"]
|
|
end
|
|
|
|
subgraph AgentLayer["Agent Layer"]
|
|
direction LR
|
|
AG[Agent]
|
|
PB[PromptBuilder]
|
|
REG[Registry]
|
|
end
|
|
|
|
subgraph ToolsLayer["Tools Layer"]
|
|
direction LR
|
|
FS_TOOL[Filesystem Tools<br/>set_path, list_folder]
|
|
API_TOOL[API Tools<br/>find_torrent, add_torrent]
|
|
end
|
|
|
|
subgraph AppLayer["Application Layer"]
|
|
direction LR
|
|
UC1[SearchMovie<br/>UseCase]
|
|
UC2[SearchTorrents<br/>UseCase]
|
|
UC3[AddTorrent<br/>UseCase]
|
|
UC4[SetFolderPath<br/>UseCase]
|
|
end
|
|
|
|
subgraph DomainLayer["Domain Layer"]
|
|
direction LR
|
|
ENT[Entities<br/>Movie, TVShow, Subtitle]
|
|
VO[Value Objects<br/>ImdbId, Quality, FilePath]
|
|
REPO_INT[Repository<br/>Interfaces]
|
|
end
|
|
|
|
subgraph InfraLayer["Infrastructure Layer"]
|
|
direction TB
|
|
|
|
subgraph Persistence["Persistence"]
|
|
MEM[Memory Manager]
|
|
REPO_IMPL[JSON Repositories]
|
|
end
|
|
|
|
subgraph APIClients["API Clients"]
|
|
TMDB_C[TMDB Client]
|
|
KNAB_C[Knaben Client]
|
|
QBIT_C[qBittorrent Client]
|
|
end
|
|
|
|
subgraph FSManager["Filesystem"]
|
|
FM[FileManager]
|
|
end
|
|
end
|
|
end
|
|
|
|
subgraph LLMProviders["LLM Providers"]
|
|
direction LR
|
|
DS[DeepSeek<br/>api.deepseek.com]
|
|
OL[Ollama<br/>localhost:11434]
|
|
end
|
|
|
|
subgraph ExternalAPIs["External APIs"]
|
|
direction LR
|
|
TMDB_API[TMDB API<br/>api.themoviedb.org]
|
|
KNAB_API[Knaben API<br/>knaben.eu]
|
|
QBIT_API[qBittorrent WebUI<br/>localhost:8080]
|
|
end
|
|
|
|
subgraph DataStores["Data Stores"]
|
|
direction LR
|
|
LTM_FILE[(ltm.json<br/>Persistent Config)]
|
|
MEDIA_DIR[(Media Directories<br/>/downloads /movies /tvshows)]
|
|
end
|
|
|
|
%% Client connections
|
|
Clients --> LoadBalancer
|
|
LoadBalancer --> Presentation
|
|
|
|
%% Internal flow
|
|
Presentation --> AgentLayer
|
|
AgentLayer --> ToolsLayer
|
|
ToolsLayer --> AppLayer
|
|
AppLayer --> DomainLayer
|
|
AppLayer --> InfraLayer
|
|
InfraLayer -.->|implements| DomainLayer
|
|
|
|
%% Agent to LLM
|
|
AgentLayer <-->|HTTP| LLMProviders
|
|
|
|
%% Infrastructure to External
|
|
TMDB_C -->|HTTP| TMDB_API
|
|
KNAB_C -->|HTTP| KNAB_API
|
|
QBIT_C -->|HTTP| QBIT_API
|
|
|
|
%% Persistence
|
|
MEM <--> LTM_FILE
|
|
FM <--> MEDIA_DIR
|
|
QBIT_API --> MEDIA_DIR
|
|
```
|
|
|
|
## Memory System Architecture
|
|
|
|
```mermaid
|
|
flowchart TB
|
|
subgraph MemoryManager["Memory Manager"]
|
|
direction TB
|
|
|
|
subgraph LTM["💾 Long-Term Memory"]
|
|
direction LR
|
|
LTM_DESC["Persistent across restarts<br/>Stored in ltm.json"]
|
|
|
|
subgraph LTM_DATA["Data"]
|
|
CONFIG["config{}<br/>folder paths, API keys"]
|
|
PREFS["preferences{}<br/>quality, languages"]
|
|
LIBRARY["library{}<br/>movies[], tv_shows[]"]
|
|
FOLLOWING["following[]<br/>watchlist"]
|
|
end
|
|
end
|
|
|
|
subgraph STM["🧠 Short-Term Memory"]
|
|
direction LR
|
|
STM_DESC["Session-based<br/>Cleared on restart"]
|
|
|
|
subgraph STM_DATA["Data"]
|
|
HISTORY["conversation_history[]<br/>last 20 messages"]
|
|
WORKFLOW["current_workflow{}<br/>type, stage, target"]
|
|
ENTITIES["extracted_entities{}<br/>title, year, quality"]
|
|
TOPIC["current_topic<br/>searching, downloading"]
|
|
end
|
|
end
|
|
|
|
subgraph EPISODIC["⚡ Episodic Memory"]
|
|
direction LR
|
|
EPIS_DESC["Transient state<br/>Cleared on restart"]
|
|
|
|
subgraph EPIS_DATA["Data"]
|
|
SEARCH["last_search_results{}<br/>indexed torrents"]
|
|
DOWNLOADS["active_downloads[]<br/>in-progress"]
|
|
ERRORS["recent_errors[]<br/>last 5 errors"]
|
|
PENDING["pending_question{}<br/>awaiting user input"]
|
|
EVENTS["background_events[]<br/>notifications"]
|
|
end
|
|
end
|
|
end
|
|
|
|
subgraph Storage["Storage"]
|
|
FILE[(memory_data/ltm.json)]
|
|
end
|
|
|
|
subgraph Lifecycle["Lifecycle"]
|
|
SAVE[save()]
|
|
LOAD[load()]
|
|
CLEAR[clear_session()]
|
|
end
|
|
|
|
LTM <-->|read/write| FILE
|
|
SAVE --> LTM
|
|
LOAD --> LTM
|
|
CLEAR --> STM
|
|
CLEAR --> EPISODIC
|
|
|
|
style LTM fill:#4caf50,color:#fff
|
|
style STM fill:#2196f3,color:#fff
|
|
style EPISODIC fill:#ff9800,color:#fff
|
|
```
|
|
|
|
## Request Flow
|
|
|
|
```mermaid
|
|
flowchart LR
|
|
subgraph Request["1️⃣ Request"]
|
|
USER[User Message]
|
|
end
|
|
|
|
subgraph Parse["2️⃣ Parse"]
|
|
FASTAPI[FastAPI<br/>Extract message]
|
|
end
|
|
|
|
subgraph Context["3️⃣ Build Context"]
|
|
PROMPT[PromptBuilder<br/>+ Memory context<br/>+ Tool descriptions]
|
|
end
|
|
|
|
subgraph Think["4️⃣ Think"]
|
|
LLM[LLM<br/>Decide action]
|
|
end
|
|
|
|
subgraph Act["5️⃣ Act"]
|
|
TOOL[Execute Tool<br/>or respond]
|
|
end
|
|
|
|
subgraph Store["6️⃣ Store"]
|
|
MEM[Update Memory<br/>STM + Episodic]
|
|
end
|
|
|
|
subgraph Response["7️⃣ Response"]
|
|
RESP[JSON Response]
|
|
end
|
|
|
|
USER --> FASTAPI --> PROMPT --> LLM
|
|
LLM -->|Tool call| TOOL --> MEM --> LLM
|
|
LLM -->|Text response| MEM --> RESP
|
|
|
|
style Think fill:#ff6b6b,color:#fff
|
|
style Act fill:#4ecdc4,color:#fff
|
|
style Store fill:#45b7d1,color:#fff
|
|
```
|
|
|
|
## Deployment Architecture
|
|
|
|
```mermaid
|
|
flowchart TB
|
|
subgraph Host["Host Machine"]
|
|
subgraph Docker["Docker (Optional)"]
|
|
AGENT_CONTAINER[Agent Media<br/>Container]
|
|
end
|
|
|
|
subgraph Native["Native Services"]
|
|
QBIT_SERVICE[qBittorrent<br/>:8080]
|
|
OLLAMA_SERVICE[Ollama<br/>:11434]
|
|
end
|
|
|
|
subgraph Storage["Local Storage"]
|
|
CONFIG_DIR[/config<br/>memory_data/]
|
|
MEDIA_DIR[/media<br/>downloads, movies, tvshows]
|
|
end
|
|
end
|
|
|
|
subgraph Cloud["Cloud Services"]
|
|
DEEPSEEK[DeepSeek API]
|
|
TMDB[TMDB API]
|
|
KNABEN[Knaben API]
|
|
end
|
|
|
|
subgraph Client["Client"]
|
|
BROWSER[Browser<br/>OpenWebUI]
|
|
end
|
|
|
|
BROWSER <-->|:8000| AGENT_CONTAINER
|
|
AGENT_CONTAINER <-->|:8080| QBIT_SERVICE
|
|
AGENT_CONTAINER <-->|:11434| OLLAMA_SERVICE
|
|
AGENT_CONTAINER <--> CONFIG_DIR
|
|
AGENT_CONTAINER <--> MEDIA_DIR
|
|
QBIT_SERVICE --> MEDIA_DIR
|
|
|
|
AGENT_CONTAINER <-->|HTTPS| Cloud
|
|
```
|
|
|
|
## Technology Stack
|
|
|
|
```mermaid
|
|
mindmap
|
|
root((Agent Media))
|
|
API
|
|
FastAPI
|
|
Uvicorn
|
|
OpenAI Compatible
|
|
Agent
|
|
Python 3.11+
|
|
Dataclasses
|
|
Protocol typing
|
|
LLM
|
|
DeepSeek
|
|
Ollama
|
|
OpenAI compatible
|
|
Storage
|
|
JSON files
|
|
Filesystem
|
|
External APIs
|
|
TMDB
|
|
Knaben
|
|
qBittorrent WebUI
|
|
Architecture
|
|
DDD
|
|
Clean Architecture
|
|
Hexagonal
|
|
```
|
|
|
|
## Security Considerations
|
|
|
|
```mermaid
|
|
flowchart TB
|
|
subgraph Security["Security Layers"]
|
|
direction TB
|
|
|
|
subgraph Input["Input Validation"]
|
|
PATH_VAL[Path Traversal Protection<br/>FileManager._sanitize_path]
|
|
INPUT_VAL[Input Sanitization<br/>Tool parameters]
|
|
end
|
|
|
|
subgraph Auth["Authentication"]
|
|
API_KEYS[API Keys<br/>Environment variables]
|
|
QBIT_AUTH[qBittorrent Auth<br/>Username/Password]
|
|
end
|
|
|
|
subgraph Access["Access Control"]
|
|
FOLDER_RESTRICT[Folder Restrictions<br/>Configured paths only]
|
|
SAFE_PATH[Safe Path Checks<br/>_is_safe_path()]
|
|
end
|
|
end
|
|
|
|
subgraph Env["Environment"]
|
|
ENV_FILE[.env file<br/>DEEPSEEK_API_KEY<br/>TMDB_API_KEY<br/>QBITTORRENT_*]
|
|
end
|
|
|
|
ENV_FILE --> Auth
|
|
Input --> Access
|
|
```
|
|
|
|
## Legend
|
|
|
|
| Icon | Meaning |
|
|
|------|---------|
|
|
| 🎬 | Agent Media System |
|
|
| 🤖 | AI Agent |
|
|
| 🧠 | Memory / LLM |
|
|
| 💾 | Persistent Storage |
|
|
| ⚡ | Transient / Fast |
|
|
| 📁 | Filesystem |
|
|
| 🔍 | Search |
|
|
| ⬇️ | Download |
|
|
| ☁️ | Cloud / External |
|
|
| 👤 | User / Client |
|