# koziev/chatbot architecture

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

- Interactive diagram: https://gitdiagram.com/koziev/chatbot
- Repository: https://github.com/koziev/chatbot

## Overview

##### Project type and purpose
- This is a dialog Q&A chatbot written in Python. It implements a “neurosymbolic” pipeline combining neural models (ruT5 text interpreter, sentence‐transformer retriever, ruGPT chitchat/reasoner, Rubert paraphrase detector) with a scripting engine (DSL rules & scenarios) and a plain-text facts knowledge base.
- The bot exposes multiple frontends (console, Flask REST, Telegram) and is delivered as a Docker image.

##### File‐structure analysis
- Top‐level:
- data/ – profiles, facts, rules, scenarios
- ruchatbot/
– bot/ – core pipeline code, base classes, model wrappers, conversation_engine.py
– frontend/ – adapters (console_chatbot, flask_service_bot, telegram_bot)
– scripting/ – DSL rule & scenario engine, matcher, generator
– utils/ – shared text utilities, tokenizer, lemmatizer, logging helpers
- docs/ – architecture write-ups, PDFs
- scripts/ – tg_bot.sh launch script
- dockerfile – container packaging
- Key orchestration: ruchatbot/bot/conversation_engine.py
- Models are wrapped under bot/: interpreter, retriever, chitchat, detectors, model_applicator
- Frontend adapters call ConversationEngine APIs and handle I/O.

##### README insights
- Describes 4 neural sub‐components + scripting engine.
- Profiles drive the knowledge base and constants injection.
- Rules (“greedy” and “smalltalk”) augment or override generative output.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Direction
    %% Top-level user
    User["User"]:::external

    %% Frontend Adapters
    subgraph "Frontend Adapters"
        direction TB
        ConsoleBot["Console Bot"]:::frontend
        FlaskService["Flask REST Service"]:::frontend
        TelegramBot["Telegram Bot"]:::frontend
    end

    %% API Layer / Dispatcher
    ConversationEngine["ConversationEngine\n(Orchestrator)"]:::core

    %% Core Engine Stages
    subgraph "Interpretation Module"
        direction TB
        BaseInterpreter["Base Utterance Interpreter"]:::module
        RuT5Interpreter["ruT5 Interpreter"]:::module
    end

    subgraph "Retrieval Module"
        direction TB
        SBERTDetector["SBERT Relevancy Detector"]:::module
        BaseStorage["Base Facts Storage"]:::module
        SimpleStorage["Simple In-Memory Storage"]:::module
        FactsDB["Facts Database Loader"]:::module
        ProfileFactsReader["Profile Facts Reader"]:::module
    end

    subgraph "Generation Module"
        direction TB
        RuGPTBase["ruGPT Base"]:::module
        RuGPTChitchat["ruGPT Chitchat"]:::module
        RuGPTConfabulator["ruGPT Confabulator"]:::module
        RuGPTInterpreter["ruGPT Interpreter"]:::module
    end

    subgraph "Paraphrase/Similarity Detectors"
        direction TB
        RubertDetector["Rubert Synonymy Detector"]:::module
        SBERTParaphrase["SBERT Paraphrase Detector"]:::module
        GeneralRelevancy["General Relevancy Detector"]:::module
    end

    subgraph "Scripting Engine"
        direction TB
        ScriptingModule["Core Scripting Module"]:::module
        BotScripting["Bot Scripting Entrypoint"]:::module
        DialogRule["Dialog Rule Definitions"]:::module
        RunningScenario["Scenario Runner"]:::module
        RunningDialogStatus["Dialog Status Runner"]:::module
        GenerativeTemplate["Generative Template"]:::module
        Matcher["Matcher Components"]:::module
    end

    %% Knowledge Base
    subgraph "Knowledge Base"
        direction TB
        AphoristicFacts["aphoristic_facts.dat"]:::data
        ProfileFacts["profile_facts_1.dat"]:::data
        SharedFacts["shared_facts.dat"]:::data
        SharedWikiFacts["shared_facts_wiki.dat"]:::data
        ProfileConstants["profile_1.json"]:::data
        ProfileRules["profile_rules_1.yaml"]:::data
        ProfileScenarios["profile_scenarios_1.yaml"]:::data
        SharedRules["shared_rules.yaml"]:::data
    end

    %% External Services
    subgraph "External Services / Environment"
        direction TB
        HFModels["HuggingFace Model Store"]:::external
        DockerEnv["Docker Container"]:::external
    end

    %% Connections
    User --> ConsoleBot
    User --> FlaskService
    User --> TelegramBot

    ConsoleBot --> ConversationEngine
    FlaskService --> ConversationEngine
    TelegramBot --> ConversationEngine

    ConversationEngine --> BaseInterpreter
    ConversationEngine --> SBERTDetector
    ConversationEngine --> RuGPTBase
    ConversationEngine --> RubertDetector
    ConversationEngine --> ScriptingModule

    BaseInterpreter -->|"normalized utterance"| SBERTDetector
    SBERTDetector --> FactsDB
    SBERTDetector --> ProfileFactsReader
    SBERTDetector --> BaseStorage
    SBERTDetector --> SimpleStorage

    FactsDB --> AphoristicFacts
    ProfileFactsReader --> ProfileFacts
    BaseStorage --> SharedFacts
    BaseStorage --> SharedWikiFacts

    ConversationEngine --> RuGPTChitchat
    ConversationEngine --> RuGPTConfabulator
    ConversationEngine --> RuGPTInterpreter

    RuGPTBase --> HFModels
    RuGPTChitchat --> HFModels
    RuGPTConfabulator --> HFModels
    RuGPTInterpreter --> HFModels

    ConversationEngine --> RubertDetector
    ConversationEngine --> SBERTParaphrase
    ConversationEngine --> GeneralRelevancy

    RubertDetector --> HFModels
    SBERTParaphrase --> HFModels
    GeneralRelevancy --> HFModels

    ConversationEngine --> ScriptingModule
    ScriptingModule --> BotScripting
    ScriptingModule --> DialogRule
    ScriptingModule --> RunningScenario
    ScriptingModule --> RunningDialogStatus
    ScriptingModule --> GenerativeTemplate
    ScriptingModule --> Matcher

    DialogRule --> ProfileRules
    RunningScenario --> ProfileScenarios
    RunningScenario --> SharedRules
    GenerativeTemplate --> ProfileScenarios

    ConversationEngine --> ProfileConstants
    ConversationEngine --> DockerEnv

    ConversationEngine --> ConsoleBot
    ConversationEngine --> FlaskService
    ConversationEngine --> TelegramBot

    ConsoleBot --> User
    FlaskService --> User
    TelegramBot --> User

    %% Click Events
    click ConsoleBot "https://github.com/koziev/chatbot/blob/core_v4/ruchatbot/frontend/console_chatbot.py"
    click FlaskService "https://github.com/koziev/chatbot/blob/core_v4/ruchatbot/frontend/flask_service_bot.py"
    click TelegramBot "https://github.com/koziev/chatbot/blob/core_v4/ruchatbot/frontend/telegram_bot.py"
    click ConversationEngine "https://github.com/koziev/chatbot/blob/core_v4/ruchatbot/bot/conversation_engine.py"
    click BaseInterpreter "https://github.com/koziev/chatbot/blob/core_v4/ruchatbot/bot/base_utterance_interpreter.py"
    click RuT5Interpreter "https://github.com/koziev/chatbot/blob/core_v4/ruchatbot/bot/rut5_interpreter.py"
    click SBERTDetector "https://github.com/koziev/chatbot/blob/core_v4/ruchatbot/bot/sbert_relevancy_detector.py"
    click BaseStorage "https://github.com/koziev/chatbot/blob/core_v4/ruchatbot/bot/base_facts_storage.py"
    click SimpleStorage "https://github.com/koziev/chatbot/blob/core_v4/ruchatbot/bot/simple_facts_storage.py"
    click FactsDB "https://github.com/koziev/chatbot/blob/core_v4/ruchatbot/bot/facts_database.py"
    click ProfileFactsReader "https://github.com/koziev/chatbot/blob/core_v4/ruchatbot/bot/profile_facts_reader.py"
    click RuGPTBase "https://github.com/koziev/chatbot/blob/core_v4/ruchatbot/bot/rugpt_base.py"
    click RuGPTChitchat "https://github.com/koziev/chatbot/blob/core_v4/ruchatbot/bot/rugpt_chitchat.py"
    click RuGPTConfabulator "https://github.com/koziev/chatbot/blob/core_v4/ruchatbot/bot/rugpt_confabulator.py"
    click RuGPTInterpreter "https://github.com/koziev/chatbot/blob/core_v4/ruchatbot/bot/rugpt_interpreter.py"
    click RubertDetector "https://github.com/koziev/chatbot/blob/core_v4/ruchatbot/bot/rubert_synonymy_detector.py"
    click SBERTParaphrase "https://github.com/koziev/chatbot/blob/core_v4/ruchatbot/bot/sbert_paraphrase_detector.py"
    click GeneralRelevancy "https://github.com/koziev/chatbot/blob/core_v4/ruchatbot/bot/relevancy_detector.py"
    click ScriptingModule "https://github.com/koziev/chatbot/blob/core_v4/ruchatbot/scripting/scripting_module.py"
    click BotScripting "https://github.com/koziev/chatbot/blob/core_v4/ruchatbot/scripting/bot_scripting.py"
    click DialogRule "https://github.com/koziev/chatbot/blob/core_v4/ruchatbot/scripting/dialog_rule.py"
    click RunningScenario "https://github.com/koziev/chatbot/blob/core_v4/ruchatbot/scripting/running_scenario.py"
    click RunningDialogStatus "https://github.com/koziev/chatbot/blob/core_v4/ruchatbot/scripting/running_dialog_status.py"
    click GenerativeTemplate "https://github.com/koziev/chatbot/blob/core_v4/ruchatbot/scripting/generator/generative_template.py"
    click Matcher "https://github.com/koziev/chatbot/tree/core_v4/ruchatbot/scripting/matcher/"

    click AphoristicFacts "https://github.com/koziev/chatbot/blob/core_v4/data/aphoristic_facts.dat"
    click ProfileFacts "https://github.com/koziev/chatbot/blob/core_v4/data/profile_facts_1.dat"
    click SharedFacts "https://github.com/koziev/chatbot/blob/core_v4/data/shared_facts.dat"
    click SharedWikiFacts "https://github.com/koziev/chatbot/blob/core_v4/data/shared_facts_wiki.dat"
    click ProfileConstants "https://github.com/koziev/chatbot/blob/core_v4/data/profile_1.json"
    click ProfileRules "https://github.com/koziev/chatbot/blob/core_v4/data/profile_rules_1.yaml"
    click ProfileScenarios "https://github.com/koziev/chatbot/blob/core_v4/data/profile_scenarios_1.yaml"
    click SharedRules "https://github.com/koziev/chatbot/blob/core_v4/data/shared_rules.yaml"
    click DockerEnv "https://github.com/koziev/chatbot/tree/core_v4/dockerfile"
    click TelegramBot "https://github.com/koziev/chatbot/blob/core_v4/scripts/tg_bot.sh"

    %% Styles
    classDef frontend fill:#AED6F1,stroke:#1F618D,color:#1F618D
    classDef core fill:#A9DFBF,stroke:#196F3D,color:#196F3D
    classDef module fill:#D5F5E3,stroke:#117A65,color:#117A65
    classDef data fill:#F9E79F,stroke:#B9770E,color:#B9770E
    classDef external fill:#D2B4DE,stroke:#7D3C98,color:#7D3C98
```
