Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
358 lines (254 loc) · 7.71 KB

CONTRIBUTING.md

File metadata and controls

358 lines (254 loc) · 7.71 KB
Raw

Contributing to EDEN

Welcome to the EDEN project! This guide will help you get started with development.

🏗️ Team Structure

The EDEN codebase is organized into independent layers that can be developed in parallel:

  • Cognitive Layer Team (cognitive_layer/) - Memory, personality, decision-making
  • Input Layer Team (input_layer/) - Camera, vision, object detection
  • Context Gathering Team (context_gathering/) - Importance analysis, VLM integration
  • Planning Layer Team (planning_layer/) - Action planning, Cosmos integration
  • ROS Integration Team (ros_integration/) - Robot control, navigation
  • Frontend Team (electron-app/) - Visualization, UI

🚀 Development Workflow

1. Initial Setup

# Clone the repository
git clone <repo-url>
cd ShowcaseSoftware

# Copy environment template
cp .env.example .env

# Edit .env with your configuration
# At minimum, set SUPERMEMORY_API_KEY for cloud memory
nano .env

# Install dependencies
pip install -r requirements.txt --user

# Verify setup
python3 -c "from config import Config; Config.validate()"

2. Working on Your Layer

Each layer can be developed and tested independently:

Cognitive Layer

# Start cognitive layer server
python3 brain_server.py

# Access web interface
open http://localhost:8000

# Test API
curl http://localhost:8000/api/graph/state

Input Layer

# Terminal 1: Camera Server
python3 -m input_layer.camera_server

# Terminal 2: Frame Processor
python3 -m input_layer.frame_processor

# Test with webcam or video file

Planning Layer

# Start planning server
python3 -m planning_layer.planning_server

# Test planning API
curl -X POST http://localhost:8001/api/plan/generate \
  -H "Content-Type: application/json" \
  -d '{"goal": "Pick up the red cup", "scene_description": "Cup on table"}'

ROS Integration

# Source ROS 2
source /opt/ros/humble/setup.bash

# Start ROS bridge
python3 ros_integration/ros_cognitive_bridge.py

3. Environment Configuration

All configuration is managed through environment variables in .env:

# Core Services
COGNITIVE_LAYER_URL=http://localhost:8000
PLANNING_LAYER_URL=http://localhost:8001
OLLAMA_BASE_URL=http://localhost:11434

# Supermemory (Cloud Memory)
SUPERMEMORY_API_KEY=sk-your-key-here

# Development
DEBUG=false
DEMO_MODE=false  # Set to true for testing with fake data

Important: Never commit .env files! Use .env.example as a template.

4. Testing

# Run all tests
pytest tests/

# Run specific layer tests
pytest tests/unit/test_cognitive_layer.py
pytest tests/unit/test_input_layer.py
pytest tests/unit/test_planning_layer.py

# Run integration tests
pytest tests/integration/

# Test with demo data
DEMO_MODE=true python3 brain_server.py

5. Code Style

  • Python: Follow PEP 8
  • Type Hints: Use type hints for function signatures
  • Docstrings: Use Google-style docstrings
  • Imports: Group imports (stdlib, third-party, local)

Example:

def process_event(event: EventFrame, threshold: float = 0.5) -> Dict[str, Any]:
    """
    Process an event frame through cognitive analysis.
    
    Args:
        event: The event frame to process
        threshold: Importance threshold for memory formation
        
    Returns:
        Dictionary containing processing results
    """
    # Implementation
    pass

6. Git Workflow

# Create feature branch
git checkout -b feature/your-feature-name

# Make changes and commit
git add .
git commit -m "feat: add new feature"

# Push to remote
git push origin feature/your-feature-name

# Create pull request on GitHub

Commit Message Format

Use conventional commits:

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

7. Pull Request Guidelines

Before submitting a PR:

  1. ✅ All tests pass: pytest tests/
  2. ✅ Code follows style guidelines
  3. ✅ Documentation updated (if needed)
  4. ✅ No hardcoded values (use config)
  5. ✅ .env not committed
  6. ✅ Clear PR description with:
    • What changed
    • Why it changed
    • How to test it

🧪 Testing Your Changes

Unit Tests

Test individual components in isolation:

# tests/unit/test_cognitive_layer.py
def test_event_processing():
    from cognitive_layer import EgoGraph
    
    ego_graph = EgoGraph()
    event = {
        "description": "Test event",
        "user_name": "TestUser"
    }
    
    result = ego_graph.process_event_frame(event)
    assert result["status"] == "processed"

Integration Tests

Test interactions between layers:

# tests/integration/test_full_pipeline.py
def test_camera_to_cognitive():
    # Start services
    # Send frame through pipeline
    # Verify cognitive layer receives event
    pass

Manual Testing

# Test with demo data
DEMO_MODE=true python3 brain_server.py

# Test with real camera
python3 -m input_layer.camera_server

# Test Supermemory integration
SUPERMEMORY_API_KEY=sk-your-key python3 scripts/test_supermemory.py "test memory"

📦 Adding Dependencies

  1. Add to requirements.txt
  2. Document why it's needed
  3. Update .env.example if new config needed
  4. Test fresh install: pip install -r requirements.txt

🐛 Debugging

Enable Debug Mode

# In .env
DEBUG=true
LOG_LEVEL=DEBUG

# Or temporarily
DEBUG=true python3 brain_server.py

Check Service Status

# Cognitive Layer
curl http://localhost:8000/api/graph/state

# Planning Layer
curl http://localhost:8001/api/plan/status

# Ollama
curl http://localhost:11434/api/tags

Common Issues

Issue: ModuleNotFoundError: No module named 'config'

  • Fix: Make sure you're running from the project root

Issue: SUPERMEMORY_API_KEY not set

  • Fix: Add key to .env or set DEMO_MODE=true

Issue: Connection refused to localhost:8000

  • Fix: Start the cognitive layer server first

📚 Documentation

When adding new features:

  1. Update relevant README in layer directory
  2. Add docstrings to functions/classes
  3. Update API documentation if endpoints change
  4. Add examples to EXAMPLE_PROMPTS.md

🤝 Getting Help

  • Questions: Open a GitHub issue with question label
  • Bugs: Open a GitHub issue with bug label
  • Features: Open a GitHub issue with enhancement label

🎯 Development Tips

Working on Cognitive Layer

  • Test with DEMO_MODE=true for quick iteration
  • Use WebSocket to see real-time graph updates
  • Check chroma_db/ for local memory storage

Working on Input Layer

  • Use video files for consistent testing
  • Mock cognitive layer API for isolated testing
  • Test with different lighting conditions

Working on Planning Layer

  • Download Cosmos model before showcase: huggingface-cli download nvidia/Cosmos-Reason1-7B
  • Test Ollama fallback: stop Cosmos and verify Ollama takes over
  • Monitor GPU usage: nvidia-smi -l 1

Working on ROS Integration

  • Test in simulation first (Gazebo)
  • Verify location mappings in turtlebot3_house_map.json
  • Check ROS topics: ros2 topic list

🚢 Deployment

Docker (Recommended)

# Build and run all services
docker-compose up

# Build specific service
docker-compose build cognitive-layer

# View logs
docker-compose logs -f cognitive-layer

Manual Deployment

# Production mode (no demo data)
DEMO_MODE=false python3 brain_server.py

# With Supermemory
SUPERMEMORY_API_KEY=sk-your-key python3 brain_server.py

📝 License

[Add license information]

🙏 Acknowledgments

  • Texas A&M TURTLE Lab
  • Ollama for LLM capabilities
  • NVIDIA for Cosmos models
  • Supermemory for cloud memory storage

Happy coding! 🚀