Developer Guide

Welcome to the OmniEmbodied developer documentation. This guide covers everything you need to know for contributing to and extending OmniEmbodied.

Contributing to OmniEmbodied

Getting Started

For Contributors:

Contributing to OmniEmbodied - How to contribute to the project
testing - Running tests and ensuring code quality
Development setup and workflow

For Extenders:

extending - Creating custom components and integrations
architecture - Understanding the system design
Plugin development and integration points

For Maintainers:

debugging - Debugging techniques and tools
release_process - Release procedures and guidelines
Code review and maintenance practices

Development Environment

Prerequisites:

# Clone the repository
git clone https://github.com/ZJU-REAL/OmniEmbodied.git
cd OmniEmbodied

# Create development environment
conda create -n omniembodied-dev python=3.8
conda activate omniembodied-dev

# Install in development mode
pip install -e .
pip install -e OmniSimulator/

# Install development dependencies
pip install -r requirements-dev.txt

Development Dependencies:

# Testing
pytest>=6.0.0
pytest-cov>=2.10.0
pytest-mock>=3.3.0

# Code Quality
black>=21.0.0
flake8>=3.8.0
isort>=5.9.0
mypy>=0.910

# Documentation
sphinx>=4.0.0
sphinx-rtd-theme>=1.0.0

Code Organization

OmniEmbodied follows a modular architecture:

OmniEmbodied/
├── OmniSimulator/           # Core simulation engine
│   ├── core/               # Core simulation logic
│   ├── action/             # Action system
│   ├── agent/              # Agent interfaces
│   ├── environment/        # Environment management
│   └── utils/              # Utilities and helpers
├── evaluation/             # Evaluation framework
├── modes/                  # Agent implementation modes
│   ├── single_agent/       # Single agent implementations
│   └── centralized/        # Multi-agent implementations
├── llm/                    # LLM integrations
├── config/                 # Configuration management
├── data_generation/        # Data generation tools
└── utils/                  # Global utilities

Key Design Principles:

Modularity: Clear separation of concerns
Extensibility: Plugin architecture for custom components
Testability: Comprehensive test coverage
Documentation: Self-documenting code and comprehensive docs

Development Workflow

Standard Workflow:

Create Feature Branch:

git checkout -b feature/your-feature-name

Implement Changes:
- Write code following project conventions
- Add comprehensive tests
- Update documentation as needed

Run Quality Checks:

# Format code
black .
isort .

# Check style
flake8 .

# Type checking
mypy .

# Run tests
pytest tests/

Submit Pull Request:
- Create pull request with clear description
- Link to related issues
- Ensure CI passes

Code Standards:

Python Style: Follow PEP 8 with Black formatting
Type Hints: Use type hints for all public APIs
Documentation: Docstrings for all classes and public methods
Testing: Comprehensive unit tests for new functionality

Testing Strategy

OmniEmbodied uses a comprehensive testing approach:

Unit Tests:

import pytest
from OmniSimulator.core.engine import SimulationEngine

def test_engine_initialization():
    engine = SimulationEngine()
    assert engine is not None
    assert engine.state is not None

Integration Tests:

def test_full_simulation_workflow():
    engine = SimulationEngine()
    results = engine.run_simulation(scenario_id="test_scenario")
    assert results["status"] == "completed"

Performance Tests:

import time

def test_simulation_performance():
    start_time = time.time()
    # Run simulation
    duration = time.time() - start_time
    assert duration < 60  # Should complete within 1 minute

Test Organization:

tests/
├── unit/                   # Unit tests
│   ├── test_engine.py
│   ├── test_actions.py
│   └── test_agents.py
├── integration/            # Integration tests
│   ├── test_simulation.py
│   └── test_evaluation.py
├── fixtures/               # Test data and fixtures
└── conftest.py            # Pytest configuration

Documentation Standards

Code Documentation:

class SimulationEngine:
    """Main simulation engine for OmniEmbodied.

    The SimulationEngine coordinates between agents, environments,
    and task verification systems to run embodied AI simulations.

    Args:
        config: Configuration dictionary or ConfigManager instance

    Attributes:
        state: Current simulation state
        agents: Registered agents
        environment: Environment manager

    Example:
        >>> engine = SimulationEngine()
        >>> results = engine.run_simulation("00001")
        >>> print(results["success_rate"])
    """

API Documentation:

Use Google-style docstrings
Include parameter types and return values
Provide usage examples
Document exceptions and edge cases

User Documentation:

Write documentation from user perspective
Include practical examples
Provide troubleshooting guidance
Keep documentation up-to-date with code changes

Debugging and Profiling

Logging Configuration:

import logging

# Enable debug logging
logging.basicConfig(level=logging.DEBUG)

# For specific modules
logger = logging.getLogger("OmniSimulator.core")
logger.setLevel(logging.DEBUG)

Performance Profiling:

import cProfile
import pstats

# Profile simulation
pr = cProfile.Profile()
pr.enable()

# Run simulation
engine.run_simulation("00001")

pr.disable()
stats = pstats.Stats(pr)
stats.sort_stats('cumulative')
stats.print_stats()

Common Debugging Techniques:

Use appropriate log levels (DEBUG, INFO, WARNING, ERROR)
Add timing information for performance analysis
Use assertions for internal consistency checks
Implement graceful error handling and recovery

Extension Points

OmniEmbodied is designed for extensibility:

Custom Actions:

from OmniSimulator.action.actions.base_action import BaseAction

class CustomAction(BaseAction):
    def execute(self, agent, target, **kwargs):
        # Custom action logic
        return result

Custom Agents:

from core.base_agent import BaseAgent

class CustomAgent(BaseAgent):
    def decide_action(self, observation):
        # Custom decision logic
        return action

Custom Evaluators:

from evaluation.evaluator import BaseEvaluator

class CustomEvaluator(BaseEvaluator):
    def evaluate(self, results):
        # Custom evaluation logic
        return metrics

Community Guidelines

Communication:

Be respectful and constructive in all interactions
Use clear, descriptive commit messages
Provide detailed pull request descriptions
Respond promptly to code review feedback

Code Review Process:

All changes require at least one approval
Automated tests must pass
Documentation must be updated
Breaking changes require discussion

Issue Management:

Use appropriate labels and milestones
Provide clear reproduction steps for bugs
Include system information and error messages
Link related issues and pull requests

Community Support:

Help answer questions in issues
Review pull requests from other contributors
Share knowledge and best practices
Mentor new contributors

Next Steps

Ready to contribute? Here’s what to do next:

Set up Development Environment - Follow the setup instructions above
Read Contributing Guide - Review Contributing to OmniEmbodied for detailed guidelines
Understand Architecture - Study architecture to understand the system
Pick an Issue - Find a good first issue on GitHub to work on
Join the Community - Participate in issues and code reviews

For specific development tasks:

Adding Features: See extending for extension patterns
Fixing Bugs: Check debugging for troubleshooting techniques
Writing Tests: Review testing for testing best practices
Improving Docs: Documentation contributions are always welcome!