Contributing

Warning

Under construction

We strive for SHARPIE to have a healthy community that works with and works on SHARPIE. You can contribute in many ways, either on the framework itself or in the wider ecosystem.

Development Installation

SHARPIE can only be installed in development mode using pip:

git clone https://github.com/hybrid-intelligence/SHARPIE.git
cd SHARPIE
pip install -e .[docs] # if you want to contribute to the documentation
pip install -e .[dev] # if you want to edit SHARPIE and contribute a bugfix
pip install -e .[dev,docs] # if you want to contribute a new feature or improvement, you will likely need to update the docs

SHARPIE cannot be run directly without installation because of fully specified import paths that are required for packaging and distribution using pip.

Development Server

If you are familiar with Django, you may expect to launch the development server by running python manage.py runserver from the sharpie/webserver/ directory.

SHARPIE, however, is distributed as a package which requires dedicated paths, which is not compatible with running from the sharpie/webserver directory.

SHARPIE therefore provides a dedicated entry point sharpie-web runserver that works wherever for convenience.

This command is specified in pyproject.toml in the [project.scripts] block.

Documentation

The documentation source files are located in docs/source and can be built using sphinx.

To build the documentation locally, make sure you have installed sharpie using the [docs] options.

cd docs/source
make clean # removes any old build
make html  # creates HTML files

Now open docs/build/html/index.html in your browser to view your local documentation build.

To have them dynamically generated with auto-browser refresh instead use

make livehtml

Look for the URL in the terminal output, it is likely to be 127.0.0.1:8000.

Tests

Warning

Under construction

Packaging and Distribution

To build the SHARPIE package, from the project root:

rm -rf build/ dist/ *.egg-info src/*.egg-info && python -m build

To distribute a new release, ensure you have completed the release checklist, obtain credentials for the sharpie pypi project and use twine to distribute.

Contributors Guide

Shared Interactive Human-AI Collaboration

Welcome to the SHARPIE project and thanks for your interest in contributing to the future of Shared Interactive Human-AI Experimentation.

1. Code of Conduct

By participating in this project, you agree to abide by our Code of Conduct. We are committed to providing a welcoming, safe, and collaborative environment for everyone, regardless of background or experience level. Be respectful, use inclusive language, and be open to constructive feedback.

2. How to Contribute

Reporting Bugs

Use the GitHub Issues tab.
Describe the bug clearly: what happened, what you expected to happen, and steps to reproduce.
Include SHARPIE version and environment details (OS, Python version, etc.).

Suggesting Enhancements

Open an Issue with the tag enhancement.
Explain why this feature is useful for Human-AI collaboration experiments.
Provide a brief sketch or logic flow for the proposed interaction.

2. Submitting Code Changes

2. Getting Started

To get started with SHARPIE:

Fork the repository to your own GitHub account.
Clone the repository locally:
```
git clone https://github.com/your-username/SHARPIE.git
```
and follow the development installation steps.
Create a branch: Use a descriptive name like feature/adaptive-feedback or fix/latency-issue. In case your fix includes a patch to a released version of python, please base your new branch on this version. All released versions come with a git tag.
Write Tests: If you are adding a feature, please include unit tests. We strive for 100% test coverage.
Follow Style Guides
Submit a Pull Request (PR):
- Reference the issue number (e.g., Fixes #42).
- Provide a summary of your changes.
- Tag a maintainer for review.

3. Documentation

We also welcome documentation updates.

Ensure all functions have clear docstrings.
Documentation sources are in the /docs folder.
We use Markdown for all documentation.

4. Your use case in the Gallery

To share your own experimental setup with the community, contribute it to the SHARPIE Gallery.
To install use cases from the Gallery locally, use the built-in sharpie-install command (see the quickstart guide for details).

5. Community & Communication

Discussions: Use the GitHub Discussions tab for high-level architectural ideas.
Chat: We have no dedicated chat yet, but are planning to set one up.

Thank you for helping us build a better partnership between humans and AI! — The SHARPIE Core Team