6. Development Setup#

This guide walks you through setting up a Maeser development environment from scratch. You’ll learn how to clone the repository, configure your Python environment, install dependencies, run tests, build the docs, and (optionally) set up on Windows via WSL.

6.1. Prerequisites#

Python 3.10+
Git
Make (on macOS/Linux) or Make for Windows (e.g. via Git Bash)
Optional: Poetry for dependency management
Optional (WSL): Windows Subsystem for Linux, if you’re on Windows

6.2. 1. Clone the Repository#

git clone https://github.com/byu-cpe/Maeser.git
cd Maeser

This gives you the latest main branch of the Maeser source code and examples.

6.3. 2. Create & Activate a Virtual Environment#

You have two options: use plain venv / pip, or Poetry.

6.3.1. 2.1. Using `venv` + `pip`#

# Create the virtual environment
python3 -m venv .venv

# Activate (macOS/Linux)
source .venv/bin/activate

# Activate (Windows PowerShell)
.venv\Scripts\Activate.ps1

6.3.2. 2.2. Using Poetry#

# Install Poetry if you haven't already
pip install poetry

# Let Poetry install dependencies and activate venv
poetry install
poetry shell

6.4. 3. Install Maeser & Dependencies#

Once your virtual environment is active:

6.4.1. 3.1. Editable Install (for development)#

pip install -e .

This installs Maeser in “editable” mode so that changes you make locally take effect immediately.

6.4.2. 3.2. Install All Requirements via Make#

A convenient shortcut:

make setup

This will:

Install the editable package (pip install -e .)
Install development dependencies (including Sphinx, pytest, etc.)
Run the test suite once to verify everything is working

6.5. 4. Environment Configuration#

Maeser uses a small configuration file for API keys, file paths, and settings.

Copy the example:
```
cp config_example.yaml config.yaml
```

Open config.yaml and set:

OPENAI_API_KEY: "your-openai-key-here"
# (Optional) GitHub OAuth Client ID/Secret if you plan to enable login
GITHUB_CLIENT_ID: ""
GITHUB_CLIENT_SECRET: ""
# (Optional) Other settings (e.g., vectorstore paths, LDAP server details, etc.)

Environment variables are also supported:

export OPENAI_API_KEY="your-openai-key-here"

6.6. 5. Running Tests#

Validate your setup by running:

pytest tests

Or simply:

make test

All tests should pass before you start making changes.

6.7. 6. Building the Documentation#

Maeser’s docs use Sphinx (with MyST for Markdown support). To build the HTML site locally:

cd sphinx-docs
make html

Then open sphinx-docs/build/html/index.html in your browser.

6.8. 7. Windows Setup (WSL)#

If you’re on Windows, we recommend using WSL for a smoother experience:

Install WSL following Microsoft’s guide:
https://learn.microsoft.com/windows/wsl/install
In your WSL terminal, follow Steps 1–6 above as if on Linux.
Use your WSL path (e.g., /mnt/c/Users/you/Maeser) for the cloned repo.

6.9. 8. Additional Tips#

Hot-reload during development: Run the Flask example in debug mode to auto-restart on code changes.
IDE integration: Point your IDE’s interpreter to the .venv or Poetry venv for linting and Intellisense.
Keep your branches tidy: Create a feature branch for each change and open a PR against main.
Update docs as you code: If you add or modify functionality, update the corresponding .md or .rst file in sphinx-docs/source/.

6.10. 9. Developer Tools & Troubleshooting#

Linting & Formatting: Use Black and Flake8 to maintain consistent code style. Install with pip install black flake8 and consider setting up pre-commit hooks to run them automatically.
Type Checking: Integrate Mypy for static type verification by installing pip install mypy and running mypy maeser/ as part of your development cycle.
Pre-commit Hooks: Add a .pre-commit-config.yaml to configure hooks (e.g., black, flake8, isort) and install via pre-commit install for automated checks on commits.
Continuous Integration (CI): Configure GitHub Actions (or another CI provider) to run tests, linting, type checks, and documentation builds on each pull request to ensure code quality.
Docker Support (Optional): Create a Dockerfile and docker-compose.yml to containerize Maeser and its dependencies, enabling reproducible environments and easy on-boarding for developers.
Troubleshooting Common Issues:
- Missing API Keys: Ensure config.yaml and environment variables (e.g., OPENAI_API_KEY) are set correctly.
- FAISS Installation Errors: On Windows, use the WSL environment or install via conda install -c conda-forge faiss-cpu to avoid build issues.
- Permission Errors: Verify file and directory permissions for log files, vectorstores, and the config.yaml file.
- Dependency Conflicts: If you encounter version mismatches, recreate your virtual environment and pin dependencies in pyproject.toml or requirements.txt.

Development Setup

Contents