tools-only 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.