Development Guide

Guide for contributing to HemoStat and setting up your development environment.

Development Setup

Install uv

HemoStat uses uv for fast Python package management:

# Install uv (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Or on Windows with PowerShell:
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

Set Up Virtual Environment

# Install all dependencies including dev tools
uv sync --all-extras

# Or just core dependencies
uv sync

Load Environment Configuration

# Copy from template
cp .env.example .env

# Edit .env with your API keys:
# - OPENAI_API_KEY (for GPT-4 analysis)
# - ANTHROPIC_API_KEY (for Claude analysis)
# - SLACK_WEBHOOK_URL (for notifications)

Code Quality Tools

HemoStat uses modern, fast tools from Astral (creators of uv):

Ruff (Linting & Formatting)

Fast Python linter and formatter (written in Rust):

# Format code
ruff format

# Lint and auto-fix
ruff check --fix

ty (Type Checking)

Modern type checker (written in Rust):

# Run type checker
ty check

Run All Quality Checks

# Using make (recommended)
make quality

# Or manually
ruff format && ruff check --fix && ty check

Pre-commit Hooks (Optional)

# Install pre-commit hooks
pre-commit install

# Run on all files
pre-commit run --all-files

Development Workflow

Running Agents Locally

Start Redis first (required for all agents):

docker compose up -d redis

Then run individual agents:

# Using make
make monitor
make analyzer
make responder
make alert

# Or directly
python -m agents.hemostat_monitor.main
python -m agents.hemostat_analyzer.main
python -m agents.hemostat_responder.main
python -m agents.hemostat_alert.main

Running the Dashboard

streamlit run dashboard/app.py
# Access at http://localhost:8501

Testing Changes

# Run all tests
pytest

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

# Run single test
pytest tests/test_monitor.py::TestMonitorAgent::test_cpu_threshold -v

# Run with coverage report
pytest --cov=agents --cov-report=html
# View report at htmlcov/index.html

Running Quality Checks

# Format code
make format

# Lint with auto-fix
make lint

# Type check
make typecheck

# Run all checks
make quality

Understanding the Architecture

Multi-Agent Message Flow

HemoStat uses a pub/sub architecture with four specialized agents communicating via Redis:

1. Monitor Agent - Continuously polls container metrics (CPU, memory, disk, process status)

2. Analyzer Agent - Receives health events, performs AI-powered root cause analysis using GPT-4 or Claude

3. Responder Agent - Receives remediation recommendations, executes safe container actions (restart, scale, cleanup)

4. Alert Agent - Receives remediation events, sends Slack notifications and stores event history

All agents inherit from HemoStatAgent base class which provides:

• Redis pub/sub communication primitives

• Shared state management

• Graceful shutdown handling and connection retry logic

See the Architecture documentation for detailed information.

Redis Channel Schema

hemostat:health_alert           (Monitor → Analyzer)
hemostat:remediation_needed     (Analyzer → Responder)
hemostat:remediation_complete   (Responder → Alert)
hemostat:false_alarm            (Analyzer → Alert)

See the API Protocol documentation for message formats.

Writing Docstrings

All code should include Google-style docstrings. These are automatically extracted and included in the API Reference documentation.

Example: Function Docstring

def analyze_container_health(container_name: str, metrics: Dict) -> Dict:
    """Analyze container health and determine if remediation is needed.
    
    Performs AI-powered root cause analysis on container metrics to determine
    if the issue is real or a false alarm. Returns analysis results with
    confidence scoring.
    
    Args:
        container_name: Name of the container to analyze
        metrics: Dictionary of container metrics (cpu_pct, memory_pct, etc.)
    
    Returns:
        Dictionary containing:
            - action: Recommended remediation action (restart, scale, etc.)
            - confidence: Confidence score (0.0-1.0)
            - reason: Human-readable explanation
    
    Raises:
        ValueError: If metrics are invalid or incomplete
        ConnectionError: If AI service is unavailable
    """
    # Implementation here
    pass

Example: Class Docstring

class ContainerMonitor(HemoStatAgent):
    """Monitors Docker container health and publishes alerts.
    
    Continuously polls container metrics and detects anomalies. When issues
    are detected, publishes health_alert events to Redis for the Analyzer
    to process.
    
    Attributes:
        polling_interval: Seconds between health checks (default: 30)
        thresholds: Dict of metric thresholds (cpu_pct, memory_pct, etc.)
    """
    
    def __init__(self, agent_name: str = "Monitor", **kwargs):
        """Initialize the Monitor Agent.
        
        Args:
            agent_name: Name for this agent instance
            **kwargs: Additional arguments passed to HemoStatAgent
        """
        super().__init__(agent_name=agent_name, **kwargs)

Adding Features

Adding a New Agent

1. Create agents/my_agent/my_agent.py

2. Import HemoStatAgent from agents.agent_base

3. Override run() method

4. Subscribe to relevant Redis channels

5. Publish events to specific channels

6. Add Dockerfile and update docker-compose.yml

7. Write comprehensive docstrings (they’ll appear in API docs!)

See the API Reference for the HemoStatAgent base class documentation.

Adding New Remediation Actions

1. Edit agents/hemostat_responder/responder.py

2. Add new method (e.g., scale_container())

3. Update _handle_remediation_request() to call new method

4. Update Analyzer to suggest new action

5. Document the new action with docstrings

Customizing Monitor Thresholds

Edit agents/hemostat_monitor/monitor.py:

self.thresholds = {
    'memory_pct': 80,   # Change to 70 for earlier alerts
    'cpu_pct': 85       # Change to 75 for earlier alerts
}

Testing with Dry-Run Mode

Test remediation actions without modifying containers:

# Set dry-run mode
export RESPONDER_DRY_RUN=true

# Run responder
python -m agents.hemostat_responder.main

# Actions will be logged but not executed

Contributing Guidelines

Code Style

• Follow Google-style docstrings (they’re auto-documented!)

• Use type hints for all function parameters and returns

• Line length: 100 characters (enforced by ruff)

• Use double quotes for strings (enforced by ruff)

Testing Requirements

• Write tests for new features

• Run make test before committing

• Aim for >80% code coverage

Documentation Requirements

• Write comprehensive docstrings (they appear in API docs!)

• Update relevant markdown files in docs/

• Update README.md if adding major features

Making Commits

# Run quality checks before committing
make quality

# Run tests
make test

# Commit with descriptive message
git commit -m "Add feature: description"

Project Phases

Phase 1: Core Architecture ✅

• Multi-agent system with Redis pub/sub

• Base agent class with communication primitives

• Logging and error handling

Phase 2: Agent Implementations ✅

• Monitor Agent - Container health polling

• Analyzer Agent - AI-powered analysis

• Responder Agent - Safe remediation

• Alert Agent - Slack notifications

Phase 3: Dashboard ✅

• Streamlit-based monitoring interface

• Real-time metrics and event visualization

• Historical data and trends

Phase 4: Testing & Monitoring 🔄

• Unit tests for all agents

• Integration tests

• Performance monitoring

• CI/CD pipeline

Useful Commands

# View logs for a specific service
docker-compose logs -f monitor

# Rebuild a service after code changes
docker-compose build analyzer --no-cache
docker-compose up -d analyzer

# Run agents locally (requires Redis)
make monitor

# Run quality checks
make quality

# Run tests with coverage
make test-cov

# View test coverage report
open htmlcov/index.html

# Clean up build artifacts
make clean

Getting Help

• Architecture questions: See Architecture documentation

• API questions: See API Reference (auto-generated from docstrings!)

• Common issues: See Troubleshooting guide

• Deployment: See Deployment guide

Documentation

Your docstrings are automatically included in the API Reference documentation! Write clear, comprehensive docstrings and they’ll be visible to all users.

To build and view documentation locally:

# Install docs dependencies
make docs-install

# Build documentation
make docs-build

# Serve locally
make docs-serve
# View at http://localhost:8000