CONTRIBUTING.md

# Contributing to Multi-Agent Debate

Thank you for your interest in contributing to AGI-HEDGE-FUND! This document provides guidelines and instructions for contributing to the project.

## Table of Contents

- [Code of Conduct](#code-of-conduct)
- [Getting Started](#getting-started)
- [Development Environment](#development-environment)
- [Project Structure](#project-structure)
- [Contributing Code](#contributing-code)
- [Adding New Agents](#adding-new-agents)
- [Adding New LLM Providers](#adding-new-llm-providers)
- [Extending Diagnostic Tools](#extending-diagnostic-tools)
- [Documentation](#documentation)
- [Pull Request Process](#pull-request-process)
- [Core Development Principles](#core-development-principles)

## Code of Conduct

This project and everyone participating in it is governed by our [Code of Conduct](CODE_OF_CONDUCT.md). By participating, you are expected to uphold this code.

## Getting Started

1. Fork the repository on GitHub
2. Clone your fork to your local machine
3. Set up the development environment
4. Make your changes
5. Submit a pull request

## Development Environment

To set up your development environment:

```bash
# Clone the repository
git clone https://github.com/your-username/agi-hedge-fund.git
cd agi-hedge-fund

# Create and activate a virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install development dependencies
pip install -e ".[dev]"
```

## Project Structure

Understanding the project structure is important for effective contributions:

```
agi-hedge-fund/
├── src/
│   ├── agents/                  # Agent implementations
│   │   ├── base.py              # Base agent architecture
│   │   ├── graham.py            # Value investor agent
│   │   ├── wood.py              # Innovation investor agent
│   │   └── ...                  # Other agent implementations
│   ├── cognition/               # Recursive reasoning framework
│   │   ├── graph.py             # LangGraph reasoning implementation
│   │   ├── memory.py            # Temporal memory shell
│   │   ├── attribution.py       # Decision attribution tracing
│   │   └── arbitration.py       # Consensus mechanisms
│   ├── market/                  # Market data interfaces
│   │   ├── sources/             # Data provider integrations
│   │   ├── environment.py       # Market simulation environment
│   │   └── backtesting.py       # Historical testing framework
│   ├── llm/                     # Language model integrations
│   │   ├── models/              # Model-specific implementations
│   │   ├── router.py            # Multi-model routing logic
│   │   └── prompts/             # Structured prompting templates
│   ├── utils/                   # Utility functions
│   │   ├── diagnostics/         # Interpretability tools
│   │   ├── visualization.py     # Performance visualization
│   │   └── metrics.py           # Performance metrics
│   ├── portfolio/               # Portfolio management
│   │   ├── manager.py           # Core portfolio manager
│   │   ├── allocation.py        # Position sizing logic
│   │   └── risk.py              # Risk management
│   └── main.py                  # Entry point
├── examples/                    # Example usage scripts
├── tests/                       # Test suite
├── docs/                        # Documentation
└── notebooks/                   # Jupyter notebooks
```

## Contributing Code

We follow a standard GitHub flow:

1. Create a new branch from `main` for your feature or bugfix
2. Make your changes
3. Add tests for your changes
4. Run the test suite to ensure all tests pass
5. Format your code with Black
6. Submit a pull request to `main`

### Coding Style

We follow these coding standards:

- Use [Black](https://github.com/psf/black) for code formatting
- Use [isort](https://pycqa.github.io/isort/) for import sorting
- Follow [PEP 8](https://www.python.org/dev/peps/pep-0008/) naming conventions
- Use type hints for function signatures
- Write docstrings in the Google style

To check and format your code:

```bash
# Format code with Black
black src tests examples

# Sort imports with isort
isort src tests examples

# Run type checking with mypy
mypy src
```

## Adding New Agents

To add a new philosophical agent:

1. Create a new file in `src/agents/` following existing agents as templates
2. Extend the `BaseAgent` class
3. Implement required methods: `process_market_data` and `generate_signals`
4. Add custom reasoning nodes to the agent's reasoning graph
5. Set appropriate memory decay and reasoning depth parameters
6. Add tests in `tests/agents/`

Example:

```python
from multi_agent_debate.agents.base import BaseAgent, AgentSignal

class MyNewAgent(BaseAgent):
    def __init__(
        self,
        reasoning_depth: int = 3,
        memory_decay: float = 0.2,
        initial_capital: float = 100000.0,
        model_provider: str = "anthropic",
        model_name: str = "claude-3-sonnet-20240229",
        trace_enabled: bool = False,
    ):
        super().__init__(
            name="MyNew",
            philosophy="My unique investment philosophy",
            reasoning_depth=reasoning_depth,
            memory_decay=memory_decay,
            initial_capital=initial_capital,
            model_provider=model_provider,
            model_name=model_name,
            trace_enabled=trace_enabled,
        )
        
        # Configure reasoning graph
        self._configure_reasoning_graph()
    
    def _configure_reasoning_graph(self) -> None:
        """Configure the reasoning graph with custom nodes."""
        # Add custom reasoning nodes
        self.reasoning_graph.add_node(
            "my_custom_analysis",
            self._my_custom_analysis
        )
        
        # Configure reasoning flow
        self.reasoning_graph.set_entry_point("my_custom_analysis")
        
    def process_market_data(self, data):
        # Implement custom market data processing
        pass
        
    def generate_signals(self, processed_data):
        # Implement custom signal generation
        pass
        
    def _my_custom_analysis(self, state):
        # Implement custom reasoning node
        pass
```

## Adding New LLM Providers

To add a new LLM provider:

1. Extend the `ModelProvider` class in `src/llm/router.py`
2. Implement required methods
3. Update the `ModelRouter` to include your provider
4. Add tests in `tests/llm/`

Example:

```python
from multi_agent_debate.llm.router import ModelProvider, ModelCapability

class MyCustomProvider(ModelProvider):
    """Custom model provider."""
    
    def __init__(self, api_key: Optional[str] = None):
        """
        Initialize custom provider.
        
        Args:
            api_key: API key (defaults to environment variable)
        """
        self.api_key = api_key or os.environ.get("MY_CUSTOM_API_KEY")
        
        # Define models and capabilities
        self.models = {
            "my-custom-model": [
                ModelCapability.REASONING,
                ModelCapability.CODE_GENERATION,
                ModelCapability.FINANCE,
            ],
        }
    
    def generate(self, prompt: str, **kwargs) -> str:
        """Generate text from prompt."""
        # Implementation
        pass
    
    def get_available_models(self) -> List[str]:
        """Get list of available models."""
        return list(self.models.keys())
    
    def get_model_capabilities(self, model_name: str) -> List[ModelCapability]:
        """Get capabilities of a specific model."""
        return self.models.get(model_name, [])
```

## Extending Diagnostic Tools

To add new diagnostic capabilities:

1. Add new shell patterns in `src/utils/diagnostics.py`
2. Implement detection logic
3. Update visualization tools to support the new pattern
4. Add tests in `tests/utils/`

Example:

```python
from multi_agent_debate.utils.diagnostics import ShellPattern

# Add new shell pattern
class MyCustomShellPattern(ShellPattern):
    CUSTOM_PATTERN = "v999 CUSTOM-PATTERN"

# Configure shell pattern detection
shell_diagnostics.shell_patterns[MyCustomShellPattern.CUSTOM_PATTERN] = {
    "pattern": r"custom.*pattern|unique.*signature",
    "custom_threshold": 0.5,
}

# Implement detection logic
def _detect_custom_pattern(self, trace_type: str, content: Dict[str, Any]) -> bool:
    content_str = json.dumps(content, ensure_ascii=False).lower()
    pattern = self.shell_patterns[MyCustomShellPattern.CUSTOM_PATTERN]["pattern"]
    
    # Check if pattern matches
    if re.search(pattern, content_str, re.IGNORECASE):
        # Add additional validation logic
        return custom_validation_logic(content)
    
    return False
```

## Documentation

Good documentation is crucial for the project. When contributing:

1. Update docstrings for any modified functions or classes
2. Update README.md if you're adding major features
3. Add examples for new features in the examples directory
4. Consider adding Jupyter notebooks for complex features

## Pull Request Process

1. Ensure your code follows our coding standards
2. Add tests for your changes
3. Update documentation as needed
4. Submit a pull request with a clear description of your changes
5. Address any feedback from reviewers

## Core Development Principles

When contributing to AGI-HEDGE-FUND, keep these core principles in mind:

1. **Transparency**: All agent decisions should be traceable and explainable
2. **Recursion**: Favor recursive approaches that enable deeper reasoning
3. **Attribution**: Maintain clear attribution chains for all decisions
4. **Interpretability**: Design for introspection and understanding
5. **Extensibility**: Make it easy to extend and customize the framework

By following these principles, you'll help maintain the project's coherence and quality.

Thank you for contributing to AGI-HEDGE-FUND!