Contributing

Thank you for your interest in contributing to structx! This document provides guidelines and instructions for contributing to the project.

Getting Started

1. Fork the Repository: Start by forking the structx repository.

2. Clone Your Fork:

git clone https://github.com/your-username/structx.git
cd structx

1. Set Up Development Environment:

uv sync --extra dev --extra docs --extra mkdocs

1. Create a Branch:

git checkout -b feature/your-feature-name

Development Guidelines

Code Style

We use Black for formatting:

# Format code
uv run black structx tests

Type Hints

We use type hints throughout the codebase. Please add appropriate type hints to your code:

def example_function(param1: str, param2: int = 0) -> bool:
    """Example function with type hints"""
    return param1.startswith(str(param2))

Documentation

• Add docstrings to all public functions, classes, and methods
• Use Google style docstrings
• Update documentation when adding new features

Pull Request Process

1. Update Documentation: Ensure that documentation is updated to reflect your changes.
2. Add Tests: Add tests for your changes.
3. Run Tests: Ensure all tests pass.

uv run pytest
uv run pytest --run-integration
uv run --extra mkdocs mkdocs build --strict

Live endpoint tests are opt-in. Configure OPENAI_API_KEY and OPENAI_BASE_URL in .env, optionally set STRUCTX_TEST_MODEL, and run:

uv run pytest --run-live tests/test_live_llm.py

Neither the normal suite nor --run-integration makes external model calls.

1. Commit Your Changes:

git add .
git commit -s -m "feat(scope): describe the change"

1. Push to Your Fork:

git push origin feature/your-feature-name

1. Submit a Pull Request: Go to the structx repository and submit a pull request.

Feature Requests and Bug Reports

• Feature Requests: Open an issue with the tag enhancement
• Bug Reports: Open an issue with the tag bug and include:
• Description of the bug
• Steps to reproduce
• Expected behavior
• Screenshots (if applicable)
• Environment information

License

By contributing to structx, you agree that your contributions will be licensed under the project's MIT License.