CONTRIBUTING.md

Contributing to FlowLLM Python SDK

Thank you for your interest in contributing to FlowLLM! 🎉

Getting Started

1. Fork the repository

   git clone https://github.com/flowllm/flowllm-python.git
   cd flowllm-python

2. Install dependencies

   # Install Poetry
   curl -sSL https://install.python-poetry.org | python3 -
   
   # Install project dependencies
   poetry install
   
   # Activate virtual environment
   poetry shell

3. Set up environment

   cp .env.example .env
   # Add your API keys for testing

Development Workflow

Code Style

We use several tools to maintain code quality:

# Format code
poetry run black .

# Lint code
poetry run ruff check .

# Type checking
poetry run mypy flowllm

# Run all checks
poetry run black . && poetry run ruff check . && poetry run mypy flowllm

Testing

# Run all tests
poetry run pytest

# Run with coverage
poetry run pytest --cov=flowllm --cov-report=html

# Run specific test file
poetry run pytest tests/test_providers.py

# Run specific test
poetry run pytest tests/test_providers.py::test_openai_provider

Making Changes

1. Create a branch

   git checkout -b feature/your-feature-name

2. Make your changes

   • Write clean, documented code
   • Add tests for new features
   • Update documentation as needed

3. Test your changes

   poetry run pytest
   poetry run mypy flowllm

4. Commit your changes

   git add .
   git commit -m "feat: add your feature description"

   We follow Conventional Commits:

   • feat: - New feature
   • fix: - Bug fix
   • docs: - Documentation changes
   • test: - Test changes
   • refactor: - Code refactoring
   • chore: - Maintenance tasks

5. Push and create a Pull Request

   git push origin feature/your-feature-name

Code Guidelines

Python Style

• Follow PEP 8 guidelines
• Use type hints for all functions
• Write docstrings for classes and functions
• Keep functions small and focused

Example:

from typing import Optional

async def example_function(param: str, optional: Optional[int] = None) -> dict:
    """
    Brief description of what the function does.
    
    Args:
        param: Description of param
        optional: Description of optional parameter
        
    Returns:
        Description of return value
        
    Raises:
        ValueError: When something goes wrong
    """
    # Implementation
    return {"result": "value"}

Adding a New Provider

1. Create a new file in flowllm/providers/
2. Inherit from BaseLLMProvider
3. Implement required methods
4. Add tests in tests/test_providers.py
5. Update documentation

Adding a New Feature

1. Discuss the feature in an issue first
2. Write tests before implementation (TDD)
3. Update relevant documentation
4. Add examples if applicable

Project Structure

flowllm-python/
├── flowllm/              # Main package
│   ├── core/             # Core functionality (agent, memory, tools)
│   ├── providers/        # LLM provider implementations
│   ├── mcp/              # MCP integration
│   └── utils/            # Utility functions
├── tests/                # Test files
├── examples/             # Example scripts
├── docs/                 # Documentation
└── pyproject.toml        # Project configuration

Testing Guidelines

• Write tests for all new features
• Maintain test coverage above 80%
• Use pytest fixtures for common setup
• Mock external API calls

Example test:

import pytest
from flowllm import define_agent
from flowllm.providers import OpenAIProvider

@pytest.mark.asyncio
async def test_agent_execution():
    """Test basic agent execution."""
    agent = define_agent(
        provider=OpenAIProvider(model="gpt-4o-mini"),
        system_prompt="You are helpful."
    )
    
    response = await agent.execute("Hello")
    assert response.content is not None
    assert len(response.content) > 0

Documentation

• Update README.md for major features
• Add examples for new functionality
• Update ARCHITECTURE.md for structural changes
• Keep QUICKSTART.md simple and beginner-friendly

Questions?

• Open an issue for bugs or feature requests
• Start a discussion for questions or ideas
• Check existing issues and PRs first

Code of Conduct

• Be respectful and inclusive
• Provide constructive feedback
• Help others learn and grow
• Follow GitHub's Community Guidelines

License

By contributing, you agree that your contributions will be licensed under the MIT License.