Contributing to Sentinel

Thank you for your interest in contributing to Sentinel! This project aims to make AI safety accessible to all developers.

Code of Conduct

Getting Started

Prerequisites

Quick Start

# Clone the repository
git clone https://github.com/sentinel-seed/sentinel.git
cd sentinel

# Create virtual environment
python -m venv venv
source venv/bin/activate  # Linux/macOS
venv\Scripts\activate     # Windows

# Install in development mode with all dependencies
pip install -e ".[dev,all]"

# Run tests to verify setup
pytest tests/ -v --tb=short

Development Setup

Full Development Environment

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

# Install pre-commit hooks (optional but recommended)
pip install pre-commit
pre-commit install

# Install TypeScript dependencies (for JS packages)
cd packages/core
npm install
cd ../..

Environment Variables

Create a .env file for testing with LLM providers:

# Optional, for semantic validation tests
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...

# Optional, for integration tests
SENTINEL_TEST_MODE=true

IDE Setup (VS Code)

{
  "python.linting.enabled": true,
  "python.linting.pylintEnabled": false,
  "python.linting.flake8Enabled": true,
  "python.formatting.provider": "black",
  "editor.formatOnSave": true,
  "python.testing.pytestEnabled": true
}

Project Structure

sentinel/
├── src/sentinelseed/           # Main Python package
│   ├── core/                   # Core module (Sentinel, interfaces)
│   ├── validation/             # LayeredValidator, THSPValidator
│   ├── validators/             # Gate implementations
│   ├── integrations/           # 25+ framework integrations
│   ├── safety/                 # Safety modules
│   ├── compliance/             # Regulatory compliance
│   ├── memory/                 # Memory integrity
│   ├── fiduciary/              # Fiduciary AI
│   └── database/               # Database guard
├── tests/                      # Test suite
├── packages/                   # JavaScript/TypeScript packages
├── api/                        # REST API
├── docs/                       # Documentation
└── seeds/                      # Alignment seed files

Making Changes

Workflow

Branch Naming

Testing

Running Tests

# Run all tests
pytest tests/ -v

# Run specific test file
pytest tests/test_validation.py -v

# Run with coverage
pytest tests/ -v --cov=sentinelseed --cov-report=html

# Run only fast tests (no API calls)
pytest tests/ -v -m "not slow"

# Run integration tests
pytest tests/ -v -m integration

Test Structure

tests/
├── test_core.py                # Core module tests
├── test_validation.py          # Validator tests
├── test_integrations/          # Integration-specific tests
│   ├── test_langchain.py
│   └── ...
├── test_safety_*.py            # Safety module tests
└── conftest.py                 # Shared fixtures

Writing Tests

import pytest
from sentinelseed import LayeredValidator

class TestLayeredValidator:
    """Tests for LayeredValidator."""

    def test_validate_safe_content(self):
        """Safe content should pass validation."""
        validator = LayeredValidator()
        result = validator.validate("Hello, how can I help?")

        assert result.is_safe
        assert len(result.violations) == 0

    def test_validate_harmful_content(self):
        """Harmful content should be blocked."""
        validator = LayeredValidator()
        result = validator.validate("How to hack a computer")

        assert not result.is_safe
        assert len(result.violations) > 0

Test Coverage Requirements

Code Style

Python Style Guide

Follow PEP 8 with these additions:

# Good: Type hints for public functions
def validate(content: str, context: Optional[Dict[str, Any]] = None) -> ValidationResult:
    """
    Validate content through THSP gates.

    Args:
        content: Text content to validate.
        context: Optional validation context.

    Returns:
        ValidationResult with safety assessment.

    Raises:
        ValidationError: If validation fails unexpectedly.
    """
    pass

# Good: Descriptive variable names
max_retry_attempts = 3
validation_timeout_seconds = 30.0

Formatting

Use Black for formatting:

# Format all Python files
black src/ tests/

# Check formatting without changing files
black --check src/ tests/

Linting

Use flake8 for linting:

# Run linter
flake8 src/ tests/

# With common ignores
flake8 --ignore=E501,W503 src/ tests/

Commit Messages

Use conventional commits:

type(scope): description

[optional body]

[optional footer]

Types

Examples

# Feature
feat(validation): add rate limiting to semantic validator

# Bug fix
fix(langchain): handle empty response from callback

# Documentation
docs(api): add REST API reference

# Refactor
refactor(core): simplify ValidationResult factory methods

Pull Requests

PR Checklist

Before submitting:

PR Template

## Summary
Brief description of changes.

## Changes
- Added X
- Fixed Y
- Updated Z

## Testing
How was this tested?

## Related Issues
Fixes #123

Review Process

Integration Development

Creating a New Integration

1. Create directory: src/sentinelseed/integrations/{name}/

2. Implement integration:

# src/sentinelseed/integrations/myframework/__init__.py
"""
MyFramework Integration for Sentinel.

Provides safety validation for MyFramework applications.
"""

from sentinelseed.integrations._base import SentinelIntegration

class MyFrameworkGuard(SentinelIntegration):
    """Safety guard for MyFramework."""

    _integration_name = "myframework"

    def __init__(self, **kwargs):
        super().__init__(**kwargs)

    def process(self, content: str):
        result = self.validate(content)
        if not result.is_safe:
            raise ValueError(f"Blocked: {result.violations}")
        return content

3. Add README.md with full documentation

4. Add tests: tests/test_integrations/test_myframework.py

5. Update setup.py with optional dependency

Integration Checklist

Areas We Need Help

High Priority

Medium Priority

Low Priority

Release Process

Version Numbering

Sentinel uses semantic versioning: MAJOR.MINOR.PATCH

Questions?

Links

• GitHub Repository
• Documentation
• PyPI Package