# ruc-datalab/deepanalyze architecture

> Architecture diagram of the GitHub repository ruc-datalab/deepanalyze, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-24). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ruc-datalab/deepanalyze
- Repository: https://github.com/ruc-datalab/deepanalyze

## Overview

1. **Repository shape**
   - This is a **monorepo for the DeepAnalyze product**: a data-science agent system plus its demos, API layer, model-serving integration, training stacks, evaluation suites, and benchmark/playground cases.
   - The main architectural boundary is between **inference/runtime** (using a deployed LLM) and **training/finetuning** (separate packages and workflows).

2. **Core runtime path: user task → analysis report**
   - The central flow is: **user prompt + uploaded files/workspace → orchestration layer → LLM calls → tool/code execution → final report**.
   - DeepAnalyze is designed for **autonomous data-science workflows**: data prep, analysis, modeling, visualization, and report generation.

3. **API service boundary**
   - The `API/` package is the lightweight backend that exposes an **OpenAI-style API** and file endpoints.
   - Key modules:
     - `main.py`, `start_server.py`: server bootstrap
     - `chat_api.py`: chat/completions orchestration
     - `file_api.py`: upload/file registration
     - `models_api.py`, `admin_api.py`: model/admin endpoints
     - `storage.py`, `models.py`, `config.py`, `utils.py`: persistence and runtime config
   - This layer sits between clients and the model server, handling **file IDs, chat requests, and workspace-aware task execution**.

4. **Model serving**
   - The runtime model is expected to be served externally, typically via **vLLM**; the README shows `vllm serve` / `vllm.entrypoints.openai.api_server`.
   - The API layer forwards analysis requests to that model endpoint rather than embedding the LLM weights itself.
   - `quantize.py` supports model compression for lower-memory deployment.

5. **SDK entrypoint**
   - The top-level `deepanalyze.py` and package `deepanalyze/` expose a simple programmatic interface such as `DeepAnalyzeVLLM`.
   - This is the user-facing library boundary for embedding DeepAnalyze into scripts or applications without going through the UI.

6. **Web UI demos**
   - `demo/chat/` is the original web app: **Next.js frontend** plus a Python backend.
   - `demo/chat_v2/` is a newer split backend/frontend design:
     - `backend_app/routers`: chat, export, workspace
     - `backend_app/services`: chat orchestration, workspace management, execution, export, Docker-based execution
     - `frontend/`: Next.js UI
   - The v2 stack adds a clearer boundary around **workspace management** and **sandboxed code execution**.

7. **CLI and notebook interfaces**
   - `demo/cli/` provides a **terminal-based client** for chatting, file upload, and streaming responses.
   - `demo/jupyter/` turns DeepAnalyze into a **JupyterLab/MCP-style notebook experience**, mapping analysis text to markdown cells and code to executable cells.
   - These are alternative presentation layers over the same API/runtime flow.

8. **Execution and sandboxing**
   - Analysis is not just text generation; it can involve **running generated code** on uploaded data.
   - Execution paths vary by demo:
     - local or service-backed execution in the original demo
     - **Docker sandbox execution** in `demo/chat_v2`
     - mock and helper services in `demo/mock_vllm`
   - This is an important security boundary: **LLM reasoning is separated from code execution**.

9. **Training stack: ms-swift**
   - `deepanalyze/ms-swift/` is a large independent training and deployment framework used to build and adapt LLMs.
   - It contains:
     - model, template, dataset, and preprocessing registries
     - train/eval/infer/export CLI paths
     - tuners such as LoRA/QLoRA and other PEFT variants
     - RLHF / GRPO / PPO / DPO-style training support
     - UI wrappers for training and inference
   - Architecturally, this package is the **general-purpose model training and serving toolkit**.

10. **Training stack: SkyRL**
    - `deepanalyze/SkyRL/` is a second, separate RL-centric stack focused on **agentic training and rollout environments**.
    - Major parts:
      - `skyagent/`: agents, tools, tasks, verifiers, backend integrations
      - `skyrl_gym/`: task environments and tools for code/search/sql/gsm-style settings
      - `skyrl_train/`: distributed training, inference engines, trainers, workers
    - This stack provides the **agent-environment-training loop** used for reinforcement learning and tool-using behaviors.

11. **Evaluation and benchmark harnesses**
    - `playground/` contains benchmark-specific runners for datasets such as **DS-1000, DSBench, TableQA**, and other task suites.
    - These folders act as **evaluation adapters**, normalizing benchmark inputs into DeepAnalyze-compatible prompts and measuring outputs.
    - They are important for the outer loop of model validation, not core runtime.

12. **Example cases and packaged workflows**
    - `example/` and `deepanalyze/example/` contain end-to-end case studies with data files, prompts, and documentation.
    - These folders demonstrate the intended runtime contract: **input files + instruction → DeepAnalyze analysis output**.
    - They are useful as diagram anchors for “external data sources” feeding the system.

13. **Deployment and operational scripts**
    - Root `scripts/`, `docker/`, and various `run_*.sh` files provide deployment orchestration for:
      - single-machine usage
      - multi-node training
      - RL loops
      - API/UI startup and shutdown
    - These are operational wrappers around the core packages, not separate subsystems.

14. **How to diagram the system**
    - Draw three main layers:
      1. **Interaction layer**: Web UI, CLI, Jupyter, API clients
      2. **Orchestration/runtime layer**: API service, workspace/file handling, sandboxed execution, report generation
      3. **Model/training layer**: external vLLM inference, ms-swift training, SkyRL agent training, evaluation/playgrounds
    - Show files/workspaces flowing into the API, prompts going to the LLM, generated code optionally going to a sandbox, and results returning as a report or interactive answer.

Main entry points: [`API/main.py`](https://github.com/ruc-datalab/deepanalyze/blob/main/API/main.py) (API server), [`API/chat_api.py`](https://github.com/ruc-datalab/deepanalyze/blob/main/API/chat_api.py) (Chat API), [`demo/chat_v2`](https://github.com/ruc-datalab/deepanalyze/tree/main/demo/chat_v2) (Chat v2), [`API/storage.py`](https://github.com/ruc-datalab/deepanalyze/blob/main/API/storage.py) (Storage)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interaction["Interaction layer"]
  node_deepanalyze_py["deepanalyze.py<br/>SDK entrypoint<br/>[deepanalyze.py]"]
  node_deepanalyze_pkg["deepanalyze<br/>package SDK"]
end

subgraph group_runtime["Runtime layer"]
  node_api_main["API server<br/>backend service<br/>[main.py]"]
  node_api_chat["Chat API<br/>orchestration<br/>[chat_api.py]"]
  node_api_file["File API<br/>upload service<br/>[file_api.py]"]
  node_api_admin["Admin API<br/>admin endpoints<br/>[admin_api.py]"]
  node_api_storage["Storage<br/>persistence<br/>[storage.py]"]
  node_api_models["Models<br/>[models.py]"]
  node_api_config["Config<br/>[config.py]"]
end

subgraph group_serving["Serving layer"]
  node_vllm_server[("vLLM server<br/>external inference")]
  node_quantize["Quantize<br/>model compression<br/>[quantize.py]"]
end

subgraph group_demos["Demo apps"]
  node_demo_chat["Chat demo<br/>web demo"]
  node_demo_chat_v2["Chat v2<br/>web demo"]
  node_demo_cli["CLI demo<br/>terminal client"]
  node_demo_jupyter["Jupyter demo<br/>notebook interface"]
  node_demo_mock_vllm["Mock vLLM<br/>test server"]
end

subgraph group_training["Training layer"]
  node_ms_swift["ms-swift<br/>training toolkit"]
  node_skyrl_train["SkyRL train<br/>RL training"]
  node_skyagent["SkyAgent<br/>agent runtime"]
  node_skyrl_gym["SkyRL gym<br/>task envs"]
end

subgraph group_eval["Evaluation layer"]
  node_playground["Playground<br/>bench harness"]
  node_examples["Examples<br/>case studies"]
end

node_deepanalyze_py -->|"boots"| node_api_main
node_deepanalyze_pkg -->|"calls"| node_api_chat
node_demo_chat -->|"uses"| node_api_main
node_demo_chat_v2 -->|"uses"| node_api_main
node_demo_cli -->|"uses"| node_api_main
node_demo_jupyter -->|"uses"| node_api_main
node_demo_mock_vllm -.->|"mocks"| node_vllm_server
node_api_main -->|"loads"| node_api_config
node_api_main -->|"persists"| node_api_storage
node_api_main -->|"binds"| node_api_models
node_api_chat -->|"forwards"| node_vllm_server
node_api_chat -->|"reads files"| node_api_file
node_api_file -->|"stores"| node_api_storage
node_api_admin -->|"manages"| node_api_storage
node_api_chat -.->|"executes"| node_demo_chat_v2
node_demo_chat_v2 -.->|"deploys"| node_quantize
node_ms_swift -->|"exports"| node_vllm_server
node_skyrl_train -->|"uses"| node_skyagent
node_skyrl_train -->|"trains on"| node_skyrl_gym
node_playground -->|"benchmarks"| node_deepanalyze_pkg
node_examples -->|"demonstrates"| node_api_main
node_examples -.->|"documents"| node_demo_chat

click node_deepanalyze_py "https://github.com/ruc-datalab/deepanalyze/blob/main/deepanalyze.py"
click node_deepanalyze_pkg "https://github.com/ruc-datalab/deepanalyze/tree/main/deepanalyze"
click node_api_main "https://github.com/ruc-datalab/deepanalyze/blob/main/API/main.py"
click node_api_chat "https://github.com/ruc-datalab/deepanalyze/blob/main/API/chat_api.py"
click node_api_file "https://github.com/ruc-datalab/deepanalyze/blob/main/API/file_api.py"
click node_api_admin "https://github.com/ruc-datalab/deepanalyze/blob/main/API/admin_api.py"
click node_api_storage "https://github.com/ruc-datalab/deepanalyze/blob/main/API/storage.py"
click node_api_models "https://github.com/ruc-datalab/deepanalyze/blob/main/API/models.py"
click node_api_config "https://github.com/ruc-datalab/deepanalyze/blob/main/API/config.py"
click node_quantize "https://github.com/ruc-datalab/deepanalyze/blob/main/quantize.py"
click node_demo_chat "https://github.com/ruc-datalab/deepanalyze/tree/main/demo/chat"
click node_demo_chat_v2 "https://github.com/ruc-datalab/deepanalyze/tree/main/demo/chat_v2"
click node_demo_cli "https://github.com/ruc-datalab/deepanalyze/tree/main/demo/cli"
click node_demo_jupyter "https://github.com/ruc-datalab/deepanalyze/tree/main/demo/jupyter"
click node_demo_mock_vllm "https://github.com/ruc-datalab/deepanalyze/tree/main/demo/mock_vllm"
click node_ms_swift "https://github.com/ruc-datalab/deepanalyze/tree/main/deepanalyze/ms-swift"
click node_skyrl_train "https://github.com/ruc-datalab/deepanalyze/tree/main/deepanalyze/SkyRL/skyrl-train"
click node_skyagent "https://github.com/ruc-datalab/deepanalyze/tree/main/deepanalyze/SkyRL/skyagent"
click node_skyrl_gym "https://github.com/ruc-datalab/deepanalyze/tree/main/deepanalyze/SkyRL/skyrl-gym"
click node_playground "https://github.com/ruc-datalab/deepanalyze/tree/main/playground"
click node_examples "https://github.com/ruc-datalab/deepanalyze/tree/main/example"

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_deepanalyze_py,node_deepanalyze_pkg toneBlue
class node_api_main,node_api_chat,node_api_file,node_api_admin,node_api_storage,node_api_models,node_api_config toneAmber
class node_vllm_server,node_quantize toneMint
class node_demo_chat,node_demo_chat_v2,node_demo_cli,node_demo_jupyter,node_demo_mock_vllm toneRose
class node_ms_swift,node_skyrl_train,node_skyagent,node_skyrl_gym toneIndigo
class node_playground,node_examples toneTeal
```

## Components

### Interaction layer

User-facing entrypoints and clients that submit analysis tasks or training jobs.

- [deepanalyze.py](https://github.com/ruc-datalab/deepanalyze/blob/main/deepanalyze.py): SDK entrypoint · Top-level programmatic entrypoint for using DeepAnalyze from scripts or applications. · `deepanalyze.py`
- [deepanalyze](https://github.com/ruc-datalab/deepanalyze/tree/main/deepanalyze): package SDK · Python package surface for embedding the product runtime and model wrappers. · `deepanalyze`

### Runtime layer

API and execution path that turns prompts, files, and workspace state into analysis outputs.

- [API server](https://github.com/ruc-datalab/deepanalyze/blob/main/API/main.py): backend service · Bootstrap for the OpenAI-style API and file-aware backend service. · `API/main.py`
- [Chat API](https://github.com/ruc-datalab/deepanalyze/blob/main/API/chat_api.py): orchestration · Coordinates chat/completions requests and analysis task execution. · `API/chat_api.py`
- [File API](https://github.com/ruc-datalab/deepanalyze/blob/main/API/file_api.py): upload service · Registers uploads and manages file identifiers for workspace-aware analysis. · `API/file_api.py`
- [Admin API](https://github.com/ruc-datalab/deepanalyze/blob/main/API/admin_api.py): admin endpoints · Administrative model and system endpoints for the backend service. · `API/admin_api.py`
- [Storage](https://github.com/ruc-datalab/deepanalyze/blob/main/API/storage.py): persistence · Persistence and runtime state backing files, chats, and model metadata. · `API/storage.py`
- [Models](https://github.com/ruc-datalab/deepanalyze/blob/main/API/models.py): runtime models · Data models and configuration objects shared across the backend. · `API/models.py`
- [Config](https://github.com/ruc-datalab/deepanalyze/blob/main/API/config.py): runtime config · Configuration loading and environment wiring for the API layer. · `API/config.py`

### Serving layer

External model serving and deployment utilities used by the runtime.

- **vLLM server**: external inference · Deployed model endpoint that serves the LLM used by DeepAnalyze.
- [Quantize](https://github.com/ruc-datalab/deepanalyze/blob/main/quantize.py): model compression · Model compression helper for lower-memory deployment of serving models. · `quantize.py`

### Demo apps

Alternative UI and notebook surfaces built on top of the same backend/runtime.

- [Chat demo](https://github.com/ruc-datalab/deepanalyze/tree/main/demo/chat): web demo · Original Next.js plus Python demo for interactive analysis sessions. · `demo/chat`
- [Chat v2](https://github.com/ruc-datalab/deepanalyze/tree/main/demo/chat_v2): web demo · Split frontend/backend demo with workspace management and sandboxed execution. · `demo/chat_v2`
- [CLI demo](https://github.com/ruc-datalab/deepanalyze/tree/main/demo/cli): terminal client · Command-line client for chatting, uploads, and streamed responses. · `demo/cli`
- [Jupyter demo](https://github.com/ruc-datalab/deepanalyze/tree/main/demo/jupyter): notebook interface · Notebook-style interface that maps analysis and code into cells. · `demo/jupyter`
- [Mock vLLM](https://github.com/ruc-datalab/deepanalyze/tree/main/demo/mock_vllm): test server · Mock model-server utilities for local and integration testing. · `demo/mock_vllm`

### Training layer

Independent training, alignment, and agent-environment stacks for model adaptation.

- [ms-swift](https://github.com/ruc-datalab/deepanalyze/tree/main/deepanalyze/ms-swift): training toolkit · General-purpose training, inference, export, and UI toolkit for LLM adaptation. · `deepanalyze/ms-swift`
- [SkyRL train](https://github.com/ruc-datalab/deepanalyze/tree/main/deepanalyze/SkyRL/skyrl-train): RL training · Distributed agentic training stack with environments, generators, and workers. · `deepanalyze/SkyRL/skyrl-train`
- [SkyAgent](https://github.com/ruc-datalab/deepanalyze/tree/main/deepanalyze/SkyRL/skyagent): agent runtime · Agent, tool, task, and verifier layer used by SkyRL-based workflows. · `deepanalyze/SkyRL/skyagent`
- [SkyRL gym](https://github.com/ruc-datalab/deepanalyze/tree/main/deepanalyze/SkyRL/skyrl-gym): task envs · Task environments and tools for code, search, SQL, and math-style settings. · `deepanalyze/SkyRL/skyrl-gym`

### Evaluation layer

Benchmark and playground adapters used to measure DeepAnalyze behavior.

- [Playground](https://github.com/ruc-datalab/deepanalyze/tree/main/playground): bench harness · Benchmark runners and evaluation adapters for DeepAnalyze-compatible tasks. · `playground`
- [Examples](https://github.com/ruc-datalab/deepanalyze/tree/main/example): case studies · End-to-end example workflows and packaged datasets demonstrating the product contract. · `example`

## Connections

- deepanalyze.py → API server: boots · SDK users can reach the backend API path through the package entrypoint.
- deepanalyze → Chat API: calls · Package-level interfaces route analysis requests into chat orchestration.
- Chat demo → API server: uses · Original web demo talks to the API backend for task execution.
- Chat v2 → API server: uses · Newer web demo uses the same backend service boundary.
- CLI demo → API server: uses · CLI client submits requests to the backend API.
- Jupyter demo → API server: uses · Notebook interface interacts with the backend for analysis and execution.
- Mock vLLM → vLLM server: mocks · Mock server substitutes for the deployed LLM endpoint in tests and local development.
- API server → Config: loads · Server bootstrap loads runtime configuration.
- API server → Storage: persists · Backend stores chats, files, and state through the storage layer.
- API server → Models: binds · Backend initializes shared models and runtime schemas.
- Chat API → vLLM server: forwards · Chat orchestration forwards prompts and tools to the deployed model endpoint.
- Chat API → File API: reads files · Analysis requests are workspace-aware and can resolve uploaded files.
- File API → Storage: stores · Uploaded file metadata and registrations are persisted through storage.
- Admin API → Storage: manages · Admin operations inspect and mutate backend state via storage.
- Chat API → Chat v2: executes · Workspace-aware analysis may trigger the v2 execution subsystem.
- Chat v2 → Quantize: deploys · Deployment path can include compressed models for efficient serving.
- ms-swift → vLLM server: exports · Training toolkit can export or deploy models to vLLM-style serving endpoints.
- SkyRL train → SkyAgent: uses · RL training stack depends on the agent runtime for rollouts and tools.
- SkyRL train → SkyRL gym: trains on · Training loop consumes environments and tools from SkyRL Gym.
- Playground → deepanalyze: benchmarks · Evaluation harnesses exercise the DeepAnalyze runtime through the package interface.
- Examples → API server: demonstrates · Packaged examples show the end-to-end file-plus-prompt analysis flow.
- Examples → Chat demo: documents · Examples also anchor the intended interactive workflow shown in the demos.
