Skip to content

Development Setup

Welcome! This guide will help you set up your development environment for LlamaBot using pixi, our dependency management tool.

Prerequisites

Before you begin, make sure you have:

Python Installation

You don't need to install Python separately. Pixi will manage the Python version for you (this project requires Python 3.10-3.13).

Initial Setup

1. Clone the Repository

git clone https://github.com/ericmjl/llamabot.git
cd llamabot

2. Install Dependencies with Pixi

This project uses pixi for dependency management. Install all dependencies:

pixi install

This will create a pixi environment with all the necessary dependencies, including:

  • Core dependencies (defined in [project.dependencies])
  • Optional dependencies for notebooks, RAG, agents, and CLI tools
  • Development tools (pytest, pre-commit, etc.)
  • Documentation tools (mkdocs, etc.)

3. Activate the Development Environment

You have two options:

pixi shell

This activates the pixi environment in your current shell.

Option B: Prefix commands with pixi run

pixi run python -c "import llamabot"

Always use pixi

All commands must be run with the pixi run prefix or within a pixi shell session. This ensures proper dependency management and environment isolation.

Development Workflow

Running Tests

Run the full test suite:

pixi run test

Run a specific test file:

pixi run -e tests pytest tests/path/to/specific_test.py

Run a specific test function:

pixi run -e tests pytest tests/path/to/specific_test.py::test_function

Test Environment

Tests run in a separate environment (tests). Use pixi run -e tests when running pytest commands directly.

Running the CLI

Test that the CLI is working:

pixi run llamabot-cli

This runs llamabot --help to verify the CLI is properly installed.

Working with Documentation

Serve documentation locally:

pixi run docs

This starts a local MkDocs server (usually at http://127.0.0.1:8000).

Build documentation:

pixi run build-docs

Marimo Notebooks

This project uses Marimo notebooks (.py files), not traditional Jupyter notebooks (.ipynb files). When creating or editing notebooks, always run uvx marimo check <path/to/notebook.py to validate them.

Building MCP Documentation

Build the MCP documentation database:

pixi run build-mcp-docs

Code Quality

Pre-commit Hooks

This project uses pre-commit hooks to ensure code quality. Pre-commit should be installed globally:

uv tool install pre-commit

Install the hooks:

pre-commit install

The hooks will automatically run on commit and check for:

  • Code formatting (Black)
  • Linting (Ruff)
  • Docstring coverage (interrogate)
  • Docstring style (pydoclint)
  • And more

Run hooks manually:

pre-commit run --all-files

Markdown Linting

Markdown files are linted using markdownlint. Install it globally:

pixi global install markdownlint

Lint a markdown file:

markdownlint filename.md

Always run markdownlint on any markdown file you edit.

Project Structure

Key Directories

  • llamabot/ - Main source code
  • bot/ - Bot implementations (SimpleBot, QueryBot, etc.)
  • components/ - Modular components (messages, docstore, tools, etc.)
  • cli/ - CLI commands
  • web/ - Web interface (FastAPI + HTMX)
  • tests/ - Test suite (mirrors source structure)
  • docs/ - Documentation
  • examples/ - Example scripts
  • notebooks/ - Marimo notebooks

Environment Features

Pixi environments are organized by features (defined in pyproject.toml):

  • default - Full development environment (tests, devtools, docs, notebooks, rag, agent, cli)
  • tests - Testing dependencies (pytest, hypothesis, etc.)
  • docs - Documentation tools (mkdocs, etc.)
  • notebooks - Notebook dependencies (ollama, etc.)
  • bare - Minimal environment (devtools only)

Common Tasks

Adding a New Dependency

  1. Add it to the appropriate section in pyproject.toml:
  2. [project.dependencies] for runtime dependencies
  3. [project.optional-dependencies.<group>] for optional dependencies
  4. [tool.pixi.feature.<feature>.pypi-dependencies] for feature-specific dependencies
  5. Run pixi install to update the environment

Running Python Code

Always use pixi:

# ✅ Correct
pixi run python script.py

# ❌ Incorrect (will fail)
python script.py

Installing the Package in Editable Mode

The package is automatically installed in editable mode when you run pixi install. You can verify:

pixi run python -c "import llamabot; print(llamabot.__file__)"

Getting Help

  • Check the AGENTS.md file for detailed development patterns
  • Review existing code in the repository for examples
  • Open an issue on GitHub for questions or problems

Next Steps

Once your environment is set up:

  1. Explore the codebase structure
  2. Read the AGENTS.md for development patterns
  3. Pick an issue or feature to work on
  4. Write tests for your changes
  5. Submit a pull request

Happy contributing!