Development Guide

Relevant source files

• .gitignore
• packages/dbgpt-accelerator/dbgpt-acc-auto/pyproject.toml
• packages/dbgpt-accelerator/dbgpt-acc-auto/src/dbgpt_acc_auto/_version.py
• packages/dbgpt-accelerator/dbgpt-acc-flash-attn/pyproject.toml
• packages/dbgpt-accelerator/dbgpt-acc-flash-attn/src/dbgpt_acc_flash_attn/_version.py
• packages/dbgpt-app/pyproject.toml
• packages/dbgpt-app/src/dbgpt_app/_version.py
• packages/dbgpt-client/pyproject.toml
• packages/dbgpt-client/src/dbgpt_client/_version.py
• packages/dbgpt-core/pyproject.toml
• packages/dbgpt-core/src/dbgpt/_version.py
• packages/dbgpt-ext/pyproject.toml
• packages/dbgpt-ext/src/dbgpt_ext/_version.py
• packages/dbgpt-serve/pyproject.toml
• packages/dbgpt-serve/src/dbgpt_serve/_version.py
• pyproject.toml
• uv.lock

This guide provides comprehensive documentation for developers who want to contribute to DB-GPT or build applications using its framework. It covers environment setup, project structure, testing practices, and the contribution workflow. This guide assumes familiarity with Python development and modern development tools.

For deployment configuration, see Deployment and Configuration. For usage examples and scripts, see Example Usage and Scripts.

Overview

DB-GPT uses a monorepo architecture managed by uv, a fast Python package manager. The project is organized into seven independent packages that can be installed selectively based on use case. All packages use Hatchling as the build backend and follow PEP 517/PEP 660 standards for building and editable installs.

Prerequisites

Before contributing to DB-GPT, ensure you have the following installed:

Tool	Version	Purpose
Python	≥ 3.10	Required runtime
uv	Latest	Package and dependency management
Git	Latest	Version control
Make	Latest	Build automation (optional)

Additional requirements for specific features:

• CUDA 11.8/12.1/12.4: For GPU acceleration
• Docker: For containerized development
• Node.js ≥ 16: For web UI development

Sources: pyproject.toml13 packages/dbgpt-core/pyproject.toml13

Monorepo Architecture

Package Dependency Relationships

The monorepo consists of seven packages with the following dependency chain:

1. dbgpt-core: Base package with no dependencies on other workspace packages
2. dbgpt-ext: Depends on dbgpt-core, provides storage implementations
3. dbgpt-serve: Depends on dbgpt-ext, provides service layer
4. dbgpt-app: Depends on dbgpt-serve, dbgpt-client, dbgpt-acc-auto
5. dbgpt-client: Depends on dbgpt-core, standalone client SDK
6. dbgpt-acc-auto: Independent package for hardware acceleration
7. dbgpt-acc-flash-attn: Independent package for Flash Attention
8. dbgpt-sandbox: Independent package for code execution

Each package has its own pyproject.toml defining dependencies, optional extras, and build configuration.

Sources: pyproject.toml31-40 packages/dbgpt-core/pyproject.toml1-27 packages/dbgpt-ext/pyproject.toml12-15 packages/dbgpt-serve/pyproject.toml12-14 packages/dbgpt-app/pyproject.toml12-20

Development Workflow

Standard Development Cycle

1. Setup: Clone repository and install dependencies using uv
2. Branch: Create feature branch from main
3. Develop: Write code, following project conventions
4. Test: Run unit and integration tests locally
5. Lint: Apply code formatting and linting with ruff
6. Commit: Commit changes with descriptive messages
7. PR: Submit pull request on GitHub
8. CI: Automated tests run via GitHub Actions
9. Review: Maintainers review and provide feedback
10. Merge: Changes merged into main branch

Sources: pyproject.toml44-60 .gitignore1-193

Key Development Concepts

Package Management with uv

DB-GPT uses uv instead of traditional pip for significantly faster dependency resolution and installation. The workspace is defined in the root pyproject.toml with workspace members:

The single uv.lock file at workspace root locks all dependencies across packages, ensuring reproducible builds.

Sources: pyproject.toml31-40 uv.lock1-3

Optional Dependencies and Extras

Each package defines optional extras for selective feature installation:

Package	Extra	Purpose
dbgpt-core	client, cli, agent, simple_framework, framework, hf, code	Core features
dbgpt-ext	rag, graph_rag, datasource_*, storage_*	Storage backends
dbgpt-app	cache, observability, base, dbgpts	Application features
dbgpt-acc-auto	auto, cpu, cuda118, cuda121, cuda124, vllm, mlx	Hardware acceleration

Install with extras: uv sync --extra rag --extra storage_milvus

Sources: packages/dbgpt-core/pyproject.toml34-166 packages/dbgpt-ext/pyproject.toml27-88 packages/dbgpt-accelerator/dbgpt-acc-auto/pyproject.toml26-103

Version Management

All packages maintain synchronized versions. The version is defined in multiple locations:

• pyproject.toml: version = "0.7.5"
• _version.py: version = "0.7.5"

When releasing, all versions must be updated across:

• Root pyproject.toml
• Each package's pyproject.toml
• Each package's _version.py

Sources: pyproject.toml3 packages/dbgpt-core/src/dbgpt/_version.py1 packages/dbgpt-ext/src/dbgpt_ext/_version.py1 packages/dbgpt-app/src/dbgpt_app/_version.py1

Build System

DB-GPT uses Hatchling as the PEP 517 build backend:

Each package specifies:

• packages: Source directories to include in wheel
• exclude: Patterns to exclude (tests, examples)

Build a package: uv build packages/dbgpt-core

Sources: packages/dbgpt-core/pyproject.toml167-203

Testing Framework

DB-GPT uses pytest with custom configuration:

Test organization:

• Unit tests: Test individual components in isolation
• Integration tests: Test component interactions
• pytest-asyncio: For async test support
• pytest-mock: For mocking dependencies

Run tests: pytest packages/dbgpt-core/tests

Sources: pyproject.toml63-66

Code Quality Tools

Ruff is used for linting and formatting:

Commands:

• Check: ruff check .
• Format: ruff format .
• Fix: ruff check --fix .

Sources: pyproject.toml68-86

Directory Structure

Important Directories

Path	Purpose
packages/dbgpt-core/src/dbgpt/	Core framework code
packages/dbgpt-ext/src/dbgpt_ext/	Storage implementations
packages/dbgpt-app/src/dbgpt_app/	Application layer
packages/dbgpt-serve/src/dbgpt_serve/	Service components
packages/*/tests/	Test files (excluded from builds)
examples/	Usage examples
docker/	Docker build files
web/	Next.js web interface
.venv/	Virtual environment (gitignored)
logs/	Log files (gitignored)
.plugin_env	Plugin configuration (gitignored)

Sources: .gitignore1-193 packages/dbgpt-core/pyproject.toml194-203

Common Development Tasks

Installing Development Environment

Running Tests

Code Formatting and Linting

Building Packages

Working with Virtual Environments

Sources: pyproject.toml42-60

Git Workflow

Ignored Files

The .gitignore file excludes:

• Build artifacts: build/, dist/, *.egg-info/
• Python cache: __pycache__/, *.pyc
• Virtual environments: .venv/, venv/, ENV/
• IDE files: .vscode/, .idea/
• Configuration: .env*, .plugin_env
• Data files: logs/, .vectordb/, pilot/data/
• Test artifacts: .pytest_cache/, .coverage
• Extensions: dbgpt/util/extensions/
• Web artifacts: web/.next/, web/node_modules/

Sources: .gitignore1-193

Branch Naming Conventions

Follow these conventions for branch names:

• feature/: New features (feature/add-milvus-support)
• bugfix/: Bug fixes (bugfix/fix-memory-leak)
• docs/: Documentation (docs/update-api-docs)
• refactor/: Code refactoring (refactor/storage-interface)
• test/: Test additions (test/add-rag-tests)

Next Steps

For detailed information on specific development topics, see:

• Development Environment Setup: Detailed setup instructions for various platforms and IDEs
• Project Structure and Build System: Deep dive into monorepo organization, Makefile commands, and publishing
• Testing and Quality Assurance: Comprehensive testing guide, coverage requirements, and CI/CD integration
• Plugin System and Extensions: Creating custom plugins and extensions
• Contributing and Release Process: Contribution guidelines, PR process, and release procedures

Sources: pyproject.toml1-86 packages/dbgpt-core/pyproject.toml1-205 packages/dbgpt-ext/pyproject.toml1-106 packages/dbgpt-app/pyproject.toml1-65 packages/dbgpt-serve/pyproject.toml1-44 packages/dbgpt-client/pyproject.toml1-47 packages/dbgpt-accelerator/dbgpt-acc-auto/pyproject.toml1-197 packages/dbgpt-accelerator/dbgpt-acc-flash-attn/pyproject.toml1-33 uv.lock1-20 .gitignore1-193