Contributing¶

Join our community of contributors

Help us build the most comprehensive AI agent framework with 400+ modules

Framework Statistics

400+ Total Modules - Comprehensive coverage
237 Enterprise Modules - Production-ready
1036+ Tests - 66% coverage
14 Enterprise Categories - Full enterprise support

Report Bugs

Found an issue? Let us know

Report
Suggest Features

Have an idea? Share it

Suggest
Submit Code

Contribute code changes

Contribute
Improve Docs

Enhance documentation

Write

[![Contributors](https://img.shields.io/github/contributors/isathish/agenticaiframework)](https://github.com/isathish/agenticaiframework/graphs/contributors) [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://github.com/isathish/agenticaiframework/pulls) [![License](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/isathish/agenticaiframework/blob/main/LICENSE)

Welcome Contributors!¶

Thank you for your interest in contributing to AgenticAI Framework! This document provides guidelines and instructions for contributing to the project.

Community Guidelines¶

We are committed to providing a welcoming and inclusive environment for all contributors. By participating in this project, you agree to:

Be respectful and professional in all interactions
Provide constructive feedback
Accept constructive criticism gracefully
Focus on what is best for the community
Show empathy towards other community members

Please report any unacceptable behavior to the maintainers.

Ways to Contribute¶

Report Bugs¶

Found a bug? Help us fix it:

Check existing issues to avoid duplicates
Use the bug report template
Provide detailed information:
Steps to reproduce
Expected vs actual behavior
Environment details
Error messages/logs
Code samples

Report a Bug →

Suggest Features¶

Have an idea? Share it:

Check existing feature requests
Use the feature request template
Explain the use case
Describe the proposed solution

Request a Feature →

Improve Documentation¶

Documentation is always welcome:

Fix typos or unclear explanations
Add examples and tutorials
Improve API documentation
Translate documentation

Submit Code¶

Contribute code improvements:

Fix bugs
Implement features
Optimize performance
Add tests

Write Tests¶

Help improve test coverage:

Unit tests
Integration tests
End-to-end tests
Performance tests

Getting Started¶

Prerequisites¶

Python 3.10+ (3.13+ recommended)
Git
GitHub account
Text editor/IDE (VS Code, PyCharm, etc.)

Fork and Clone¶

Fork the repository on GitHub
Clone your fork:

Bash
git clone https://github.com/YOUR_USERNAME/agenticaiframework.git
cd agenticaiframework

Add upstream remote:

Bash
git remote add upstream https://github.com/isathish/agenticaiframework.git

Development Setup¶

1. Create Virtual Environment¶

Bash
# Using venv
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate

# Using conda
conda create -n agenticai python=3.11
conda activate agenticai

2. Install Dependencies¶

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

# Or install specific extras
pip install -e ".[dev,test,docs]"

3. Install Pre-commit Hooks¶

Bash
# Install pre-commit
pip install pre-commit

# Install hooks
pre-commit install

# Run manually
pre-commit run --all-files

4. Verify Installation¶

Bash
# Run tests
pytest

# Check code style
ruff check .

# Check types
mypy agenticaiframework

Making Changes¶

1. Create a Branch¶

Bash
# Sync with upstream
git fetch upstream
git checkout main
git merge upstream/main

# Create feature branch
git checkout -b feature/amazing-feature

# Or bugfix branch
git checkout -b fix/bug-description

Branch Naming Convention¶

feature/description - New features
fix/description - Bug fixes
docs/description - Documentation changes
test/description - Test additions/changes
refactor/description - Code refactoring
perf/description - Performance improvements

2. Make Your Changes¶

Write clean, readable code
Follow coding standards
Add/update tests
Update documentation
Add docstrings

3. Commit Your Changes¶

Follow Conventional Commits:

Bash
# Format: <type>(<scope>): <description>

git commit -m "feat(agents): add multi-agent collaboration"
git commit -m "fix(memory): resolve memory leak in cache"
git commit -m "docs(api): update API reference"
git commit -m "test(agents): add agent lifecycle tests"

Commit Types: - feat: New feature - fix: Bug fix - docs: Documentation - test: Tests - refactor: Code refactoring - perf: Performance improvement - chore: Maintenance

Pull Request Process¶

1. Push Your Changes¶

Bash
git push origin feature/amazing-feature

2. Create Pull Request¶

Go to your fork on GitHub
Click "Compare & pull request"
Fill out the PR template
Link related issues
Request reviews

3. PR Template Checklist¶

4. Code Review Process¶

Automated Checks: CI/CD runs tests, linting, type checking
Peer Review: At least one approval required
Maintainer Review: Final review by maintainers
Changes Requested: Address feedback and update PR

5. After Approval¶

Maintainer will merge your PR
Delete your feature branch
Sync your fork

Bash
git checkout main
git pull upstream main
git push origin main

Coding Standards¶

Python Style Guide¶

Follow PEP 8 with these specifics:

Python
# Line length: 100 characters
# Indentation: 4 spaces
# Quotes: Double quotes for strings
# Import order: stdlib, third-party, local

# Good
def calculate_score(data: dict) -> float:
    """Calculate score from data.

    Args:
        data: Input data dictionary

    Returns:
        Calculated score
    """
    return sum(data.values()) / len(data)

# Bad
def calc(d): # No type hints, no docstring
    return sum(d.values())/len(d) # No spaces

Code Formatting¶

We use automated formatters:

Bash
# Format code
ruff format .

# Check linting
ruff check .

# Fix auto-fixable issues
ruff check --fix .

Type Hints¶

Use type hints for all functions:

Python
from typing import List, Dict, Optional

def process_agents(
    agents: List[Agent],
    config: Dict[str, Any],
    timeout: Optional[int] = None
) -> Dict[str, Any]:
    """Process agents with given configuration."""
    ...

Docstrings¶

Use Google-style docstrings:

Python
def execute_task(self, task: Task, agent_id: str) -> TaskResult:
    """Execute a task using specified agent.

    Args:
        task: The task to execute
        agent_id: ID of the agent to use

    Returns:
        Result of task execution

    Raises:
        AgentNotFoundError: If agent_id doesn't exist
        TaskExecutionError: If task execution fails

    Example:
        ```python
        result = manager.execute_task(task, "agent_001")
        logger.info(result.output)
        ```
    """
    ...

Testing Guidelines¶

Writing Tests¶

Python
import pytest
from agenticaiframework.agents import Agent

class TestAgent:
    """Test agent functionality."""

    def test_agent_creation(self):
        """Test agent can be created successfully."""
        agent = Agent(name="test_agent", role="tester")

        assert agent.name == "test_agent"
        assert agent.role == "tester"
        assert agent.status == "initialized"

    def test_agent_execution(self):
        """Test agent can execute tasks."""
        agent = Agent(name="test_agent", role="tester")
        result = agent.execute_task(lambda: "success")

        assert result == "success"

    @pytest.mark.asyncio
    async def test_async_execution(self):
        """Test async task execution."""
        agent = Agent(name="test_agent", role="tester")
        result = await agent.execute_task_async(async_function)

        assert result is not None

Test Structure¶

Text Only

tests/
├── unit/ # Unit tests
│ ├── test_agents.py
│ ├── test_tasks.py
│ └── test_memory.py
├── integration/ # Integration tests
│ ├── test_workflows.py
│ └── test_pipelines.py
├── e2e/ # End-to-end tests
│ └── test_scenarios.py
├── conftest.py # Pytest fixtures
└── __init__.py

Running Tests¶

Bash
# Run all tests
pytest

# Run specific file
pytest tests/unit/test_agents.py

# Run specific test
pytest tests/unit/test_agents.py::TestAgent::test_agent_creation

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

# Run with markers
pytest -m "not slow"

# Verbose output
pytest -v

# Stop on first failure
pytest -x

Test Coverage¶

Target: 80%+ coverage

Bash
# Generate coverage report
pytest --cov=agenticaiframework --cov-report=term-missing

# HTML report
pytest --cov=agenticaiframework --cov-report=html
open htmlcov/index.html

Documentation¶

Code Documentation¶

Docstrings: All public APIs
Type hints: All function signatures
Comments: Complex logic only
Examples: Usage examples in docstrings

User Documentation¶

Located in docs/: