Contributing

Contribute to Helios development

We welcome contributions to Helios. This guide covers the development workflow.

Getting Started

1. Fork and clone

   git clone https://github.com/YOUR-USERNAME/helios.git
   cd helios
   
2. Install dependencies

   uv sync
   
3. Run tests

   uv run pytest tests/ -v
   

Development Workflow

Running Tests

# All unit tests
uv run pytest tests/ -v

# Specific test file
uv run pytest tests/test_task.py -v

# With coverage
uv run pytest tests/ --cov=src/helios --cov-report=term-missing

Integration Tests

Integration tests require Docker and built images:

# Build required images
docker build -t cua-desktop -f docker/Dockerfile.desktop .
docker build -t click-test -f tasks/click-test/environment/Dockerfile tasks/click-test/environment/

# Run integration tests
uv run pytest tests/integration/ -v --run-integration -m "integration"

Linting

# Check for issues
uv run ruff check src/

# Auto-fix issues
uv run ruff check --fix src/

Type Checking

uv run pyright src/

Code Style

General Guidelines

• Use type hints for all function signatures
• Write docstrings for public functions and classes
• Keep functions focused and small
• Use meaningful variable names

Logging

Always use the logger, never print():

import logging

logger = logging.getLogger(__name__)

def my_function():
    logger.debug("Detailed debug info")
    logger.info("General info message")
    logger.warning("Warning message")
    logger.error("Error message")

Exception Handling

Add debug logging to exception handlers:

try:
    do_something()
except SomeException as e:
    logger.debug(f"Operation failed: {e}")
    raise

Abstract Methods

Use ellipsis (...) not pass in abstract method bodies:

from abc import ABC, abstractmethod

class BaseClass(ABC):
    @abstractmethod
    def my_method(self) -> None:
        ...  # Not 'pass'

Project Structure

Key areas for contribution:

Area	Location	Description
Core runtime	src/helios/runner.py	Task execution
LLM providers	src/helios/gateway/	Add new LLM backends
Environments	src/helios/environment/	Container management
Tools	src/helios/tools/	Agent capabilities
Web viewer	src/helios/server/	Real-time UI

Adding a New LLM Provider

1. Create gateway implementation

   Create src/helios/gateway/newprovider.py:

   from .base import BaseGateway
   
   class NewProviderGateway(BaseGateway):
       async def send_message(self, messages, tools):
           # Implementation
           ...
   
2. Update factory

   Add routing in src/helios/gateway/factory.py:

   if model.startswith("newprovider/"):
       return NewProviderGateway(model)
   
3. Add tool implementations

   Create provider-specific tools in src/helios/tools/newprovider/.

4. Add tests

   Create tests in tests/test_newprovider.py.

Adding a New Environment Provider

1. Create environment implementation

   Create src/helios/environment/newenv.py:

   from .base import Environment
   
   class NewEnvironment(Environment):
       async def start(self):
           ...
   
       async def execute(self, command: str) -> str:
           ...
   
       async def screenshot(self) -> bytes:
           ...
   
       async def stop(self):
           ...
   
2. Update factory

   Add to src/helios/environment/factory.py:

   if provider == "newenv":
       return NewEnvironment(config)
   
3. Add tests

   Create tests in tests/test_newenv.py.

Pull Request Process

1. Create a branch

   git checkout -b feature/my-feature
   
2. Make changes

   Write code, add tests, update documentation.

3. Run all checks

   uv run pytest tests/ -v
   uv run ruff check src/
   uv run pyright src/
   
4. Commit with clear message

   git commit -m "Add support for new feature X"
   
5. Push and create PR

   git push origin feature/my-feature
   

   Then create a pull request on GitHub.

Testing Your Changes

Before submitting:

1. Unit tests pass: uv run pytest tests/ -v
2. Linting passes: uv run ruff check src/
3. Types check: uv run pyright src/
4. Manual testing: Run a real task with your changes

Testing with Real Tasks

# Run a simple task
uv run helios tasks/create-hello-file

# Run with your changes visible
uv run helios tasks/explore-desktop --watch

Documentation

Documentation lives in docs/ and uses Mintlify.

Local Preview

npm install -g mintlify
mintlify dev docs

Adding Documentation

1. Create .mdx files in the appropriate directory
2. Update mint.json navigation
3. Use Mintlify components (Cards, Tabs, Accordions, etc.)

Getting Help

• Open an issue on GitHub
• Check existing issues for similar problems
• Include reproduction steps and logs

License

Contributions are licensed under Apache 2.0.