local-deep-research/docs/developing.md

Developer Guide

Architecture Documentation

• Architecture Overview - System components, research flow, and module responsibilities
• Database Schema - Database models and relationships
• Extension Guide - How to add custom search engines, strategies, and LLM providers
• Testing and CI - GitHub Actions workflows, pre-commit hooks, and security scanning

Configuring the Environment

The most convenient way to configure the Python environment is to use PDM. After installing PDM, configure the environment and install dependencies:

pdm install --no-self

You can run a command in the environment by prefixing it with pdm run. You can also activate the environment with pdm venv activate.

Setting up Pre-Commit Hooks

These hooks will automatically run linting for every commit. You need to initialize them once after configuring the environment:

pre-commit install
pre-commit install-hooks

Running the Application

You can run the application directly using Python module syntax:

# Activate the environment.
pdm venv activate
# You need to be in the src directory if you are not.
cd src

# Run the web interface
python -m local_deep_research.web.app
# Run the CLI version
python -m local_deep_research.main

Building a Package

To build a wheel and source distribution, simply run pdm build.

Building Frontend Assets

If you're developing from source and want to use the Web UI, you need to build the frontend assets:

npm install
npm run build

This builds the Vite frontend into src/local_deep_research/web/static/dist/.

Note: pip users don't need this step - pre-built assets are included in the PyPI package.