🛠️ Development Guide

This guide covers development workflows, build automation, testing, and contribution guidelines for the OMD project.

📋 Table of Contents

Development Environment Setup
Build System
Testing
Code Quality
Development Workflows
Project Structure
Contributing

🚀 Development Environment Setup

Prerequisites

Python 3.11-3.13
uv package manager (recommended) or pip
Make (usually pre-installed on Unix-like systems)
Git
Ollama (for MCP integration)

Quick Setup

# Clone the repository
git clone https://github.com/rayhunter/omd.git
cd omd

# Set up development environment
./scripts/dev.sh setup

# This will:
# - Create virtual environment
# - Install all dependencies in development mode
# - Set up pre-commit hooks

Manual Setup

# Create virtual environment
python -m venv virtual
source virtual/bin/activate  # On Windows: virtual\Scripts\activate

# Install packages in development mode
cd enhanced_agent && pip install -e . && cd ..
cd OpenManus && pip install -e . && cd ..

# Install all dependencies
pip install -r enhanced_agent/requirements.txt
pip install -r OpenManus/requirements.txt

# Install development dependencies
pip install pytest pytest-asyncio pytest-cov black flake8 isort

Using UV (Recommended)

# Install UV
curl -LsSf https://astral.sh/uv/install.sh | sh

# Create virtual environment with UV
uv venv --python 3.12
source .venv/bin/activate

# Install dependencies with UV (faster)
uv pip install -r enhanced_agent/requirements.txt
uv pip install -r OpenManus/requirements.txt

🏗️ Build System

Makefile Commands

The project uses a Makefile for common development tasks:

# Installation
make install              # Install all packages in development mode
make install-dev          # Install with development dependencies

# Testing
make test                 # Run all tests
make test-unit           # Run unit tests only
make test-integration    # Run integration tests only
make test-fast           # Run fast tests (exclude slow tests)
make test-coverage       # Run tests with coverage reporting

# Code Quality
make lint                 # Run linting (black, flake8, isort)
make format              # Auto-format code
make check               # Run linting without making changes

# Maintenance
make clean               # Clean build artifacts and cache
make lock                # Update lock files
make update              # Update dependencies

Dev Script Commands

The scripts/dev.sh script provides a convenient interface:

# Help and documentation
./scripts/dev.sh help

# Setup and installation
./scripts/dev.sh setup              # Complete environment setup
./scripts/dev.sh install            # Install dependencies

# Testing
./scripts/dev.sh test               # Run all tests
./scripts/dev.sh test unit          # Run unit tests
./scripts/dev.sh test integration   # Run integration tests

# Running
./scripts/dev.sh run enhanced_agent.main    # Run specific module
./scripts/dev.sh streamlit                  # Start Streamlit interface

# Code quality
./scripts/dev.sh lint               # Run linting
./scripts/dev.sh format             # Format code

🧪 Testing

Test Organization

tests/
├── conftest.py              # Shared fixtures
├── unit/                    # Unit tests
│   ├── test_enhanced_agent.py
│   └── test_dspy_standalone.py
└── integration/             # Integration tests
    ├── test_dspy_integration.py
    ├── test_multi_mcp.py
    └── test_enhanced_agent_integration.py

Running Tests

# All tests
make test
# or
pytest

# Specific test categories
pytest -m unit                   # Unit tests only
pytest -m integration            # Integration tests only
pytest -m "not slow"             # Fast tests only

# Specific test file
pytest tests/unit/test_enhanced_agent.py

# With verbose output
pytest -v

# With coverage
make test-coverage
# or
pytest --cov=enhanced_agent --cov=OpenManus --cov-report=html

# View coverage report
open htmlcov/index.html

Test Markers

Tests are automatically marked based on location and content:

@pytest.mark.unit - Unit tests (in tests/unit/)
@pytest.mark.integration - Integration tests (in tests/integration/)
@pytest.mark.slow - Slow-running tests
@pytest.mark.requires_api - Tests requiring external APIs

Writing Tests

import pytest
from enhanced_agent.src.app import EnhancedResearchAgent

@pytest.mark.unit
def test_agent_initialization(mock_dspy_settings):
    """Test that agent initializes correctly."""
    agent = EnhancedResearchAgent()
    assert agent is not None

@pytest.mark.integration
@pytest.mark.slow
async def test_full_research_workflow(sample_test_queries):
    """Test complete research workflow."""
    agent = EnhancedResearchAgent()
    result = await agent.process(sample_test_queries["factual"])
    assert "Direct Answer" in result

Using Test Fixtures

Available fixtures in conftest.py:

def test_with_fixtures(
    project_root,           # Path to project root
    mock_openai_api,        # Mock OpenAI API
    mock_mcp_client,        # Mock MCP client
    sample_test_queries,    # Sample queries
    mock_dspy_settings      # Mock DSPy settings
):
    # Your test code
    pass

📐 Code Quality

Linting

# Run all linters
make lint

# Individual linters
black --check .              # Check formatting
flake8 .                     # Check style
isort --check-only .         # Check import order

Auto-formatting

# Format all code
make format

# Individual formatters
black .                      # Format with black
isort .                      # Sort imports

Code Style Guidelines

PEP 8 compliance
Black formatter with default settings
Import order: Standard library, third-party, local
Line length: 88 characters (Black default)
Docstrings: Google style

Example:

"""Module docstring explaining the module purpose.

This module provides functionality for X, Y, and Z.
"""

from typing import Optional
import asyncio

from enhanced_agent.src import utils


class MyClass:
    """Class docstring explaining the class.

    Attributes:
        attribute_name: Description of attribute
    """

    def my_method(self, param: str) -> Optional[str]:
        """Method docstring.

        Args:
            param: Description of parameter

        Returns:
            Description of return value

        Raises:
            ValueError: When parameter is invalid
        """
        pass

🔄 Development Workflows

Feature Development

# 1. Create feature branch
git checkout -b feature/my-feature

# 2. Make changes
# Edit files...

# 3. Format and lint
make format
make lint

# 4. Run tests
make test-fast          # Quick check
make test               # Full test suite

# 5. Commit changes
git add .
git commit -m "feat: add my feature"

# 6. Push and create PR
git push origin feature/my-feature

Bug Fix Workflow

# 1. Create bug fix branch
git checkout -b fix/issue-123

# 2. Write failing test
# Add test that reproduces the bug

# 3. Fix the bug
# Edit code to fix

# 4. Verify fix
pytest tests/test_specific.py -v

# 5. Run full test suite
make test

# 6. Commit and push
git add .
git commit -m "fix: resolve issue #123"
git push origin fix/issue-123

Testing Workflow

# Watch mode for continuous testing
pytest --watch

# Test specific functionality
pytest tests/unit/test_enhanced_agent.py::test_specific_function -v

# Debug test failures
pytest --pdb                 # Drop into debugger on failure
pytest -vv                   # Very verbose output
pytest --tb=short            # Short traceback

Documentation Workflow

# Update documentation
# Edit docs/*.md files

# Check documentation links
make check-docs

# Preview documentation locally
# (if using mkdocs or similar)
mkdocs serve

📁 Project Structure

omd/
├── enhanced_agent/              # Main package
│   ├── src/
│   │   ├── app.py              # Application entry
│   │   ├── dspy_mcp_integration.py
│   │   ├── mcp_client.py
│   │   └── enhanced_mcp_client.py
│   ├── config/                 # Configuration files
│   │   ├── mcp.json
│   │   └── mcp_extended.json
│   ├── tests/                  # Package tests
│   └── requirements.txt
├── OpenManus/                   # OpenManus framework
│   ├── app/
│   │   ├── agent/              # Agent implementations
│   │   ├── tool/               # Tool integrations
│   │   ├── flow/               # Workflow orchestration
│   │   └── sandbox/            # Sandbox environment
│   ├── config/                 # OpenManus config
│   └── requirements.txt
├── tests/                       # Project-wide tests
│   ├── conftest.py
│   ├── unit/
│   └── integration/
├── docs/                        # Documentation
│   ├── QUICK_START.md
│   ├── DEVELOPMENT.md
│   ├── OBSERVABILITY.md
│   └── INTEGRATION.md
├── scripts/                     # Development scripts
│   └── dev.sh
├── Makefile                     # Build automation
├── pytest.ini                   # Pytest configuration
├── pyproject.toml              # Project metadata
├── .env.example                # Environment template
└── README.md                   # Main documentation

🤝 Contributing

Getting Started

Fork the repository
Clone your fork: git clone https://github.com/YOUR_USERNAME/omd.git
Set up development environment: ./scripts/dev.sh setup
Create a feature branch: git checkout -b feature/my-feature

Commit Guidelines

Use conventional commits:

feat: Add new feature
fix: Fix bug
docs: Update documentation
test: Add or update tests
refactor: Code refactoring
style: Code style changes
chore: Maintenance tasks

Pull Request Process

Ensure tests pass: make test
Format code: make format
Update documentation if needed
Create PR with clear description
Respond to review feedback

Code Review Checklist

🐛 Debugging

Debug Mode

# Run with debug logging
export DEBUG=1
python enhanced_agent/main.py

# Python debugger
import pdb; pdb.set_trace()

# Pytest with debugger
pytest --pdb

Common Issues

Import Errors

# Reinstall in development mode
pip install -e enhanced_agent/
pip install -e OpenManus/

Test Failures

# Run with more verbosity
pytest -vvs

# Check fixtures
pytest --fixtures

# Clear cache
pytest --cache-clear

Virtual Environment Issues

# Clean and recreate
rm -rf virtual
python -m venv virtual
source virtual/bin/activate
pip install -r enhanced_agent/requirements.txt

📚 Additional Resources

Questions? Open an issue or discussion on GitHub.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

🛠️ Development Guide

📋 Table of Contents

🚀 Development Environment Setup

Prerequisites

Quick Setup

Manual Setup

Using UV (Recommended)

🏗️ Build System

Makefile Commands

Dev Script Commands

🧪 Testing

Test Organization

Running Tests

Test Markers

Writing Tests

Using Test Fixtures

📐 Code Quality

Linting

Auto-formatting

Code Style Guidelines

🔄 Development Workflows

Feature Development

Bug Fix Workflow

Testing Workflow

Documentation Workflow

📁 Project Structure

🤝 Contributing

Getting Started

Commit Guidelines

Pull Request Process

Code Review Checklist

🐛 Debugging

Debug Mode

Common Issues

📚 Additional Resources

FilesExpand file tree

DEVELOPMENT.md

Latest commit

History

DEVELOPMENT.md

File metadata and controls

🛠️ Development Guide

📋 Table of Contents

🚀 Development Environment Setup

Prerequisites

Quick Setup

Manual Setup

Using UV (Recommended)

🏗️ Build System

Makefile Commands

Dev Script Commands

🧪 Testing

Test Organization

Running Tests

Test Markers

Writing Tests

Using Test Fixtures

📐 Code Quality

Linting

Auto-formatting

Code Style Guidelines

🔄 Development Workflows

Feature Development

Bug Fix Workflow

Testing Workflow

Documentation Workflow

📁 Project Structure

🤝 Contributing

Getting Started

Commit Guidelines

Pull Request Process

Code Review Checklist

🐛 Debugging

Debug Mode

Common Issues

📚 Additional Resources