How ruc-datalab/deepanalyze works
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: main.py API server · chat_api.py Chat API · chat_v2 Chat v2 · storage.py Storage
Components 22
Interaction layer
User-facing entrypoints and clients that submit analysis tasks or training jobs.
- deepanalyze.py · Top-level programmatic entrypoint for using DeepAnalyze from scripts or applications.
deepanalyze.py - deepanalyze · 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 · Bootstrap for the OpenAI-style API and file-aware backend service.
API/main.py - Chat API · Coordinates chat/completions requests and analysis task execution.
API/chat_api.py - File API · Registers uploads and manages file identifiers for workspace-aware analysis.
API/file_api.py - Admin API · Administrative model and system endpoints for the backend service.
API/admin_api.py - Storage · Persistence and runtime state backing files, chats, and model metadata.
API/storage.py - Models · Data models and configuration objects shared across the backend.
API/models.py - 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 · Deployed model endpoint that serves the LLM used by DeepAnalyze.
- Quantize · 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 · Original Next.js plus Python demo for interactive analysis sessions.
demo/chat - Chat v2 · Split frontend/backend demo with workspace management and sandboxed execution.
demo/chat_v2 - CLI demo · Command-line client for chatting, uploads, and streamed responses.
demo/cli - Jupyter demo · Notebook-style interface that maps analysis and code into cells.
demo/jupyter - Mock vLLM · 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 · General-purpose training, inference, export, and UI toolkit for LLM adaptation.
deepanalyze/ms-swift - SkyRL train · Distributed agentic training stack with environments, generators, and workers.
deepanalyze/SkyRL/skyrl-train - SkyAgent · Agent, tool, task, and verifier layer used by SkyRL-based workflows.
deepanalyze/SkyRL/skyagent - SkyRL gym · 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 · Benchmark runners and evaluation adapters for DeepAnalyze-compatible tasks.
playground - Examples · End-to-end example workflows and packaged datasets demonstrating the product contract.
example
Connections 22
- 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.