debai/CONTRIBUTING.md

Contributing to Debai

Thank you for your interest in contributing to Debai! This document provides guidelines and instructions for contributing.

Code of Conduct

By participating in this project, you agree to maintain a respectful and inclusive environment for everyone.

How to Contribute

Reporting Bugs

1. Check if the bug has already been reported in Issues
2. If not, create a new issue with:
   • Clear, descriptive title
   • Steps to reproduce
   • Expected vs actual behavior
   • System information (OS, Python version, etc.)
   • Relevant logs or screenshots

Suggesting Features

1. Check existing issues and discussions for similar suggestions
2. Create a new issue with:
   • Clear description of the feature
   • Use cases and benefits
   • Possible implementation approach

Submitting Code

1. Fork the repository
2. Create a branch for your changes:

   git checkout -b feature/your-feature-name
   

3. Make your changes following our coding standards
4. Write tests for new functionality
5. Run tests to ensure everything passes:

   pytest tests/
   

6. Commit with clear messages:

   git commit -m "feat: add new agent template for network monitoring"
   

7. Push to your fork
8. Create a Pull Request

Development Setup

Prerequisites

• Python 3.10 or later
• GTK 4.0 and libadwaita 1.0
• Docker Engine from official Docker repository (for model testing)

Setting Up

# Clone your fork
git clone https://github.com/YOUR_USERNAME/debai.git
cd debai

# Install Docker Engine from official repository (if not already installed)
# Add Docker's official GPG key
sudo apt-get update
sudo apt-get install ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/debian/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

# Add the repository to Apt sources
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/debian \
  $(. /etc/os-release && echo \"$VERSION_CODENAME\") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt-get update

# Install Docker Engine
sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

# Create virtual environment
python3 -m venv venv
source venv/bin/activate

# Install in development mode
pip install -e ".[dev]"

# Install pre-commit hooks
pre-commit install

Running Tests

# Run all tests
pytest

# Run with coverage
pytest --cov=debai --cov-report=html

# Run specific test file
pytest tests/test_agent.py

# Run with verbose output
pytest -v

Code Style

We use the following tools for code quality:

• Black for code formatting
• isort for import sorting
• Ruff for linting
• mypy for type checking

Run all checks:

# Format code
black src/
isort src/

# Lint
ruff check src/

# Type check
mypy src/

Commit Message Convention

We follow Conventional Commits:

type(scope): description

[optional body]

[optional footer]

Types:

• feat: New feature
• fix: Bug fix
• docs: Documentation changes
• style: Code style changes (formatting)
• refactor: Code refactoring
• test: Adding or updating tests
• chore: Maintenance tasks

Examples:

feat(agent): add support for scheduled tasks
fix(gui): resolve memory leak in agent list
docs: update installation instructions

Project Structure

debai/
├── src/debai/           # Main package
│   ├── core/            # Core business logic
│   │   ├── agent.py     # Agent management
│   │   ├── model.py     # Model management
│   │   ├── task.py      # Task management
│   │   └── system.py    # System utilities
│   ├── cli/             # Command-line interface
│   ├── gui/             # GTK4 graphical interface
│   └── generators/      # Image generators
├── tests/               # Test suite
├── docs/                # Documentation
├── data/                # Data files and resources
└── debian/              # Debian packaging

Testing Guidelines

1. Write tests for all new functionality
2. Maintain or improve code coverage
3. Use meaningful test names
4. Group related tests in classes
5. Use fixtures for common setup

Example test:

import pytest
from debai.core.agent import Agent, AgentConfig

class TestAgent:
    @pytest.fixture
    def agent_config(self):
        return AgentConfig(
            name="Test Agent",
            model_id="llama3.2:3b",
        )
    
    def test_agent_creation(self, agent_config):
        agent = Agent(agent_config)
        assert agent.name == "Test Agent"
        assert agent.status.value == "stopped"
    
    @pytest.mark.asyncio
    async def test_agent_start_stop(self, agent_config):
        agent = Agent(agent_config)
        # Test start/stop behavior

Documentation

• Update docstrings for new/modified functions
• Use Google-style docstrings
• Update README.md for user-facing changes
• Add man page entries for new CLI commands

Example docstring:

def create_agent(config: AgentConfig) -> Agent:
    """Create a new AI agent.
    
    Args:
        config: Configuration for the agent including name,
            type, and model settings.
    
    Returns:
        The newly created Agent instance.
    
    Raises:
        ValueError: If an agent with the same ID already exists.
    
    Example:
        >>> config = AgentConfig(name="My Agent", model_id="llama3.2:3b")
        >>> agent = create_agent(config)
    """

Pull Request Process

1. Ensure all tests pass
2. Update documentation as needed
3. Add entry to CHANGELOG.md
4. Request review from maintainers
5. Address review feedback
6. Squash commits if requested

Release Process

Maintainers follow this process for releases:

1. Update version in pyproject.toml
2. Update CHANGELOG.md
3. Create release tag
4. Build and publish packages
5. Update documentation

Getting Help

• Open an issue for questions
• Join discussions on GitHub
• Check existing documentation

License

By contributing, you agree that your contributions will be licensed under the GPL-3.0 license.