Contributing

Dev Setup

git clone <repo-url>
cd agenticraft-foundation
uv sync --group dev
uv run pytest tests/ -v

Code Style

• Formatter/linter: Ruff (line-length 100, target py310)
• Type checker: mypy in strict mode
• Docstrings: Google style
• Imports: Always use from __future__ import annotations at the top of every module

Standard import order:

from __future__ import annotations

import logging
from typing import TYPE_CHECKING, Any

if TYPE_CHECKING:
    from some_module import SomeType

Testing

• Framework: pytest
• Coverage minimum: 90%
• Test naming: test_<module>_<function>_<scenario>
• Marks:
  • @pytest.mark.slow -- long-running tests
  • @pytest.mark.integration -- integration tests

Running Tests

# Full test suite
uv run pytest tests/ -v

# With coverage report
uv run pytest tests/ --cov=agenticraft_foundation --cov-report=html

# Only fast tests
uv run pytest tests/ -v -m "not slow"

# Single file
uv run pytest tests/test_algebra.py -v

Linting

# Check for lint errors
uv run ruff check src/ tests/

# Auto-format
uv run ruff format src/ tests/

# Type check
uv run mypy src/

PR Process

Branch Naming

• feat/<name> -- new features
• fix/<name> -- bug fixes
• docs/<name> -- documentation changes

Commit Messages

Use conventional commit format:

feat(algebra): add new CSP operator
fix(topology): correct eigenvalue computation
docs(examples): add consensus walkthrough
refactor(mpst): simplify projection logic
test(protocols): add edge case coverage
chore(ci): update GitHub Actions workflow

Guidelines

• Keep PRs focused on a single change.
• Include tests for new functionality.
• Ensure all existing tests pass before submitting.
• Run the linter and formatter before pushing.

Adding New Modules

1. Follow the patterns established by existing modules (e.g., algebra, topology, mpst).
2. Add comprehensive tests in the tests/ directory.
3. Export public API symbols from __init__.py.
4. Add type annotations to all public functions and classes.
5. Write Google-style docstrings for all public APIs.