# emocareai/chatpsychiatrist architecture

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

- Interactive diagram: https://gitdiagram.com/emocareai/chatpsychiatrist
- Repository: https://github.com/emocareai/chatpsychiatrist

## Overview

##### Project type and purpose
- ChatPsychiatrist is a domain-specific extension of the FastChat framework: a distributed LLM-based chatbot system fine-tuned on counseling dialogs for mental health support.
- It encompasses data processing, model training, serving (CLI + Web UI), evaluation/monitoring, and integration with external services (GPT-4 API, Huggingface Hub, Nginx).

##### File structure
- Top-level directories:
- assets, docker, docs – static assets, containerization, documentation
- fastchat – core modules (data, model adaption, training, serving, evaluation, protocol)
- llm-judge – legacy or parallel judging suite
- playground – experimental embedding tests
- scripts, tests – automation and CI tests
- fastchat sub-modules reveal architectural layers:
- data/… – data cleaning, conversion, dataset prep (Psych8K)
- model/… – model adapters, LORA/delta application, quantization, monkey patches
- train/… – training entrypoints and strategy scripts (Lora, FlashAttention, etc.)
- serve/… – controller, model_worker, multi_model_worker, gradio web UIs, API provider, gateway config, monitoring scripts
- llm_judge & eval/… – generation of model answers, judgments, scoring, table generation
- protocol/… – definition of API protocols (OpenAI style)

##### README insights
- Pipeline: raw counseling transcripts → clean & extract → GPT-4 to generate Q-A pairs → fine-tune LLaMA-7B → serve via CLI & Gradio UI → evaluate on counseling bench using custom metrics.
- Core technologies: Python, PyTorch, Huggingface transformers, FastChat, GPT-4 API, Gradio, Docker, Nginx, Huggingface Hub.

a. Main components
- Data Pipeline
- Model Training & Adaptation
- Model Registry/Hub (Huggingface)
- Serving Layer
– Controller (coordination)
– Worker(s) (model inference)
– API Provider & Gateway (nginx)
– Gradio Web UI & CLI
- Evaluation & Monitoring
- External Services
– OpenAI GPT-4 API (dataset creation, judgment)
– Huggingface Hub (model download/upload)
b. Relationships / data flow
1. Data Pipeline outputs Psych8K dataset → Training module
2. Training produces model artifacts → optionally compress/quantize → upload to Huggingface Hub
3. Serving layer pulls model artifacts from Hub → Controller schedules inference requests to Workers
4. User interacts via CLI or Web UI → requests go through API Provider → routed by Controller to Worker → responses return to UI/CLI
5. Evaluation module invokes model (via CLI API) on bench questions → uses GPT-4 API to judge outputs → generates metrics and tables
6. Monitoring scripts collect logs/metrics from serve/worker processes → dashboard or CSV/HTML
c. Architectural patterns & principles
- Modular layered architecture: clear separation of data, model, training, serve, evaluation
- Distributed worker pattern: Controller + Worker processes for horizontal scaling
- Plugin/adaptor pattern: protocol adapters (OpenAI, API), model adapters (LORA, Delta)
- CI/CD and containerization: Docker + docker-compose for reproducible environments
d. Relevant technologies & frameworks
- FastChat framework (core orchestration)
- Transformers & PEFT (LORA, delta) for fine-tuning
- vLLM, FlashAttention, xFormers for performance
- Gradio for Web UI, CLI for terminal usage
- Nginx for HTTP gateway
- Docker for environment isolation
- OpenAI GPT-4 API for data generation and judging
- Huggingface Hub for model hosting

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data & Training
    subgraph "Data & Training"
        direction TB
        DataPipeline["Data Pipeline"]:::batch
        ModelTraining["Model Training"]:::batch
        ModelAdaptation["Model Adaptation"]:::batch
        ModelRegistry["Model Registry/Hub\n(Huggingface)"]:::external
    end

    %% Serving Layer
    subgraph "Serving" 
        direction TB
        Controller["Controller"]:::serving
        APIProvider["API Provider"]:::serving
        Gateway["Nginx Gateway"]:::serving
        CLI["CLI Interface"]:::serving
        subgraph "Workers"
            direction TB
            ModelWorker["Model Worker"]:::serving
            MultiModelWorker["Multi-Model Worker"]:::serving
            vLLMWorker["vLLM Worker"]:::serving
            BardWorker["Bard Worker"]:::serving
        end
        subgraph "Web UIs"
            direction TB
            SingleWebUI["Single-model UI"]:::serving
            MultiWebUI["Multi-model UI"]:::serving
            BlockArenaAnon["Block Arena UI (Anon)"]:::serving
            BlockArenaNamed["Block Arena UI (Named)"]:::serving
        end
    end

    %% Evaluation & Monitoring
    subgraph "Evaluation & Monitoring"
        direction TB
        EvaluationService["Evaluation Service"]:::batch
        Monitoring["Monitoring & Metrics"]:::serving
    end

    %% External Services
    subgraph "External Services"
        direction TB
        GPT4["OpenAI GPT-4 API"]:::external
        HFHub["Huggingface Hub"]:::external
    end

    %% Data & Training Flow
    DataPipeline -->|"produces Psych8K"| ModelTraining
    ModelTraining -->|"fine-tuned artifacts"| ModelAdaptation
    ModelAdaptation -->|"uploads model"| ModelRegistry

    %% Serving Flow
    HFHub -->|"pulls model"| Controller
    Controller -->|"dispatch tasks"| ModelWorker
    Controller -->|"dispatch tasks"| MultiModelWorker
    Controller -->|"dispatch tasks"| vLLMWorker
    Controller -->|"dispatch tasks"| BardWorker

    %% API & UI Flow
    CLI -->|"CLI requests"| APIProvider
    SingleWebUI -->|"HTTP requests"| APIProvider
    MultiWebUI -->|"HTTP requests"| APIProvider
    BlockArenaAnon -->|"HTTP requests"| APIProvider
    BlockArenaNamed -->|"HTTP requests"| APIProvider
    APIProvider -->|"routes"| Controller
    Gateway -->|"proxies to API"| APIProvider

    %% Evaluation Flow
    EvaluationService -->|"calls CLI/API"| APIProvider
    EvaluationService -->|"uses GPT-4"| GPT4
    Controller -->|"logs"| Monitoring
    ModelWorker -->|"metrics"| Monitoring
    MultiModelWorker -->|"metrics"| Monitoring
    vLLMWorker -->|"metrics"| Monitoring
    BardWorker -->|"metrics"| Monitoring

    %% External Interactions
    DataPipeline -->|"GPT-4 data gen"| GPT4
    ModelRegistry --> HFHub

    %% Click Events
    click DataPipeline "https://github.com/emocareai/chatpsychiatrist/tree/master/fastchat/data/"
    click ModelTraining "https://github.com/emocareai/chatpsychiatrist/tree/master/fastchat/train/"
    click ModelAdaptation "https://github.com/emocareai/chatpsychiatrist/tree/master/fastchat/model/"
    click ModelRegistry "https://github.com/emocareai/chatpsychiatrist/blob/master/fastchat/model/upload_hub.py"
    click Controller "https://github.com/emocareai/chatpsychiatrist/blob/master/fastchat/serve/controller.py"
    click ModelWorker "https://github.com/emocareai/chatpsychiatrist/blob/master/fastchat/serve/model_worker.py"
    click MultiModelWorker "https://github.com/emocareai/chatpsychiatrist/blob/master/fastchat/serve/multi_model_worker.py"
    click vLLMWorker "https://github.com/emocareai/chatpsychiatrist/blob/master/fastchat/serve/vllm_worker.py"
    click BardWorker "https://github.com/emocareai/chatpsychiatrist/blob/master/fastchat/serve/bard_worker.py"
    click APIProvider "https://github.com/emocareai/chatpsychiatrist/blob/master/fastchat/serve/api_provider.py"
    click Gateway "https://github.com/emocareai/chatpsychiatrist/blob/master/fastchat/serve/gateway/nginx.conf"
    click CLI "https://github.com/emocareai/chatpsychiatrist/blob/master/fastchat/serve/cli.py"
    click SingleWebUI "https://github.com/emocareai/chatpsychiatrist/blob/master/fastchat/serve/gradio_web_server.py"
    click MultiWebUI "https://github.com/emocareai/chatpsychiatrist/blob/master/fastchat/serve/gradio_web_server_multi.py"
    click BlockArenaAnon "https://github.com/emocareai/chatpsychiatrist/blob/master/fastchat/serve/gradio_block_arena_anony.py"
    click BlockArenaNamed "https://github.com/emocareai/chatpsychiatrist/blob/master/fastchat/serve/gradio_block_arena_named.py"
    click EvaluationService "https://github.com/emocareai/chatpsychiatrist/tree/master/fastchat/eval/"
    click Monitoring "https://github.com/emocareai/chatpsychiatrist/tree/master/fastchat/serve/monitor/"
    click GPT4 "https://github.com/emocareai/chatpsychiatrist/blob/master/fastchat/llm_judge/gen_model_answer.py"
    click GPT4 "https://github.com/emocareai/chatpsychiatrist/blob/master/fastchat/llm_judge/gen_api_answer.py"
    click GPT4 "https://github.com/emocareai/chatpsychiatrist/blob/master/fastchat/llm_judge/gen_judgment.py"
    click HFHub "https://github.com/emocareai/chatpsychiatrist/blob/master/fastchat/model/upload_hub.py"

    %% Styles
    classDef batch fill:#BBDEFB,stroke:#1E88E5,color:#0D47A1
    classDef serving fill:#C8E6C9,stroke:#43A047,color:#1B5E20
    classDef external fill:#FFE0B2,stroke:#FB8C00,color:#E65100
```
