Contributing to AgentSociety 2¶

Thank you for your interest in contributing to AgentSociety 2!

Ways to Contribute¶

Report bugs: Submit issues with reproducible examples
Suggest features: Share your ideas for improvements
Submit code: Submit pull requests with your changes
Improve documentation: Help make documentation clearer
Share examples: Add useful examples to the collection

Report Bugs¶

When reporting bugs, please include:

Python version
AgentSociety 2 version
Minimal reproducible example
Expected vs actual behavior
Any error messages or tracebacks

See the bug report template for details.

Suggest Features¶

Feature suggestions are welcome! Please:

Clearly describe the use case
Explain why it would be useful
Consider if it fits the project scope
Be open to discussion

Submit Pull Requests¶

Before submitting a PR:

Check existing issues for related discussions
Fork the repository
Create a branch for your work
Make changes with clear commit messages
Update documentation as needed
Submit Pull Requests

PR Guidelines¶

Keep changes focused and atomic
Follow existing code style
Add docstrings for new functions/classes
Update relevant documentation
Ensure CI passes

Code Review Process¶

All PRs go through code review:

Maintainers will review your changes
Address any feedback or requests
After approval, PR will be merged
Large changes may require multiple iterations

Development Setup¶

# Clone your fork
git clone https://github.com/your-username/agentsociety.git
cd agentsociety

# Install in development mode
uv sync
pip install -e "packages/agentsociety2[dev]"

# Install pre-commit hooks
cd packages/agentsociety2
pre-commit install

Adding New Features¶

When adding new features:

Open an issue for discussion first
Implement the feature
Update documentation
Add examples if helpful

Example Structure¶

tests/
├── test_agent.py
├── test_env.py
└── test_storage.py

agentsociety2/
├── new_module/
│   ├── __init__.py
│   ├── core.py
│   └── utils.py
└── new_module/
    ├── __init__.py
    └── implementation.py

Documentation Standards¶

Python docstrings use Sphinx/reST consistently (:param:, :returns:, :raises:, :ivar:, etc.) so autodoc API reference stays aligned; follow the same convention when adding or changing code.

def example_function(param1: str, param2: int) -> bool:
    """Brief description of the function.

    Longer description with more details.

    :param param1: Description of param1.
    :param param2: Description of param2.
    :returns: Description of return value.
    :raises ValueError: If something goes wrong.
    """
    pass

Community Guidelines¶

Be respectful and constructive
Welcome new contributors
Focus on what’s best for the community
Show empathy toward other community members

Getting Help¶

GitHub Issues: For bugs and feature requests
GitHub Discussions: For questions and ideas
Documentation: Check documentation first

License¶

By contributing to AgentSociety 2, you agree that your contributions will be licensed under the Apache License 2.0.