Contributing to AgenticAI Core SDK¶

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

Ways to Contribute¶

There are many ways to contribute to AgenticAI Core:

🐛 Report Bugs - Help us identify and fix issues
✨ Suggest Features - Share ideas for new functionality
📝 Improve Documentation - Enhance guides, examples, and API docs
💻 Submit Code - Fix bugs or implement new features
🧪 Write Tests - Improve test coverage
📖 Share Examples - Contribute real-world usage examples

Getting Started¶

1. Fork and Clone¶

# Fork the repository on GitHub
# Then clone your fork
git clone https://github.com/YOUR_USERNAME/agentic-core.git
cd agentic-core

2. Set Up Development Environment¶

# Create a virtual environment
python3.10 -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

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

3. Create a Branch¶

git checkout -b feature/your-feature-name
# or
git checkout -b fix/bug-description

Development Workflow¶

Running Tests¶

# Run all tests
pytest

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

# Run specific test file
pytest tests/test_app.py

Code Style¶

We use the following tools to maintain code quality:

# Format code with black
black src/

# Sort imports with isort
isort src/

# Lint with ruff
ruff check src/

# Type check with mypy
mypy src/

Pre-commit Checks¶

Before committing, ensure:

✅ All tests pass
✅ Code is formatted with black
✅ Linting passes
✅ Type hints are added for new code
✅ Docstrings are added for public APIs

Documentation¶

When adding or modifying public APIs:

Add Docstrings - Use Google/NumPy style
Update API Docs - Add corresponding .md files in docs/api/
Add Examples - Include usage examples in docstrings
Update Guides - Update user guides if needed

Build and preview documentation:

mkdocs serve

Coding Standards¶

Python Style¶

Follow PEP 8 guidelines
Use type hints for function signatures
Maximum line length: 88 characters (black default)
Use meaningful variable and function names

Docstring Format¶

Use Google-style docstrings:

def my_function(param1: str, param2: int) -> bool:
    """Short description of the function.

    Longer description explaining the function's behavior,
    edge cases, and usage patterns.

    Args:
        param1: Description of param1.
        param2: Description of param2.

    Returns:
        Description of return value.

    Raises:
        ValueError: When param2 is negative.

    Example:
        ```python
        result = my_function("test", 42)
        print(result)  # True
        ```
    """
    if param2 < 0:
        raise ValueError("param2 must be non-negative")
    return True

Commit Messages¶

Follow conventional commit format:

type(scope): subject

body (optional)

footer (optional)

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

Examples:

feat(agent): add support for streaming responses

fix(memory): resolve session cleanup issue

docs(api): add examples for Tool.register decorator

Pull Request Process¶

1. Update Your Branch¶

# Sync with upstream main
git remote add upstream https://github.com/agenticai/agentic-core.git
git fetch upstream
git rebase upstream/main

2. Push Changes¶

git push origin feature/your-feature-name

3. Create Pull Request¶

Go to GitHub and create a Pull Request
Fill out the PR template:
Description: What does this PR do?
Related Issue: Link to related issue(s)
Testing: How was this tested?
Breaking Changes: Any breaking changes?

4. Code Review¶

Address reviewer feedback
Keep the PR focused and small
Update documentation as needed
Ensure CI/CD checks pass

5. Merge¶

Once approved, your PR will be merged by a maintainer.

Reporting Bugs¶

Before Reporting¶

Check if the bug has already been reported
Try to reproduce with the latest version
Gather relevant information

Bug Report Template¶

**Describe the bug**
A clear description of what the bug is.

**To Reproduce**
Steps to reproduce:
1. Create agent with...
2. Call method...
3. See error

**Expected behavior**
What you expected to happen.

**Actual behavior**
What actually happened.

**Environment:**
- Python version:
- AgenticAI Core version:
- OS:

**Additional context**
Any other relevant information.

Suggesting Features¶

We welcome feature suggestions! Please:

Check if similar features have been requested
Describe the use case clearly
Explain why this would benefit users
Consider implementation complexity

Feature Request Template¶

**Feature Description**
Clear description of the proposed feature.

**Use Case**
Why is this feature needed? What problem does it solve?

**Proposed Solution**
How should this feature work?

**Alternatives Considered**
Other approaches you've thought about.

**Additional Context**
Any other relevant information.

Code of Conduct¶

Our Pledge¶

We are committed to providing a welcoming and inclusive environment for all contributors.

Our Standards¶

Positive behavior: - Using welcoming and inclusive language - Being respectful of differing viewpoints - Gracefully accepting constructive criticism - Focusing on what's best for the community

Unacceptable behavior: - Harassment, discrimination, or offensive comments - Trolling, insulting/derogatory comments - Public or private harassment - Publishing others' private information

Enforcement¶

Instances of unacceptable behavior may be reported to Kore Support.

Development Setup Details¶

Project Structure¶

agentic-core/
├── src/
│   └── agenticai_core/
│       ├── designtime/      # Design-time models
│       ├── runtime/          # Runtime execution
│       ├── api/              # API clients
│       └── cli/              # CLI tools
├── tests/                    # Test suite
├── docs/                     # Documentation source
├── examples/                 # Example applications
└── mkdocs.yml               # Documentation config

Dependencies¶

Core dependencies: - pydantic>=2.0 - Data validation - typing-extensions - Type hints support

Development dependencies: - pytest - Testing framework - pytest-cov - Coverage reporting - black - Code formatter - ruff - Fast Python linter - mypy - Type checker

Documentation dependencies: - mkdocs - Documentation generator - mkdocs-material - Material theme - mkdocstrings[python] - API docs from docstrings

Running Specific Tests¶

# Test specific module
pytest tests/designtime/

# Test with verbose output
pytest -v

# Test with specific marker
pytest -m "not slow"

# Test with debugging
pytest -s --pdb

License¶

By contributing to AgenticAI Core SDK, you agree that your contributions will be licensed under the same license as the project (MIT License).

Questions?¶

If you have questions about contributing, please contact Kore Support

Thank you for contributing to AgenticAI Core!

Send Feedback