Documentation: Add docstrings to all classes and public methods

[coderabbitai]

Description

15+ classes are missing docstrings, making the codebase hard to understand and maintain.

Classes Without Docstrings

Models (models/schemas.py)

• Vulnerability
• ScanRequest, ScanResponse
• FixSuggestion, FixRequest, FixResponse
• KestraFlowRequest, KestraExecutionResponse
• KestraStatusResponse

Core Classes

• AdversaryAgent (core/adversary.py)
• DefenderAgent (core/defender.py)
• KestraClient (core/kestra_client.py)
• ConnectionManager (core/websocket_manager.py)
• Utils (core/utils.py)

API Models

• TaskUpdate (api/webhooks.py)
• ExecutionUpdate (api/webhooks.py)

Expected Format

For Classes:

class Vulnerability(BaseModel):
    """
    Represents a security vulnerability found by the Adversary agent.
    
    Attributes:
        id: Unique identifier (e.g., VULN-001)
        file: Path to the vulnerable file
        line: Line number where vulnerability exists
        severity: Risk level (CRITICAL, HIGH, MEDIUM, LOW)
        type: Vulnerability category (e.g., SQL Injection)
        description: Detailed explanation of the vulnerability
        payload: Example exploit payload
        fix_suggestion: Recommended remediation
    """

For Methods:

async def analyze_code(self, target_path: Path) -> List[Vulnerability]:
    """
    Analyze code for security vulnerabilities using Cline CLI.
    
    Args:
        target_path: Path to file or directory to scan
        
    Returns:
        List of detected vulnerabilities
        
    Raises:
        FileNotFoundError: If attack vectors or prompt file not found
    """

Acceptance Criteria

• All classes have docstrings
• All public methods have docstrings
• Docstrings follow Google or NumPy style
• Include type hints in descriptions
• Document exceptions raised
• Add usage examples for complex classes

Benefits

• Better IDE autocomplete
• Easier onboarding for contributors
• Auto-generated API documentation (Sphinx/MkDocs)
• Improved code maintainability

Related Issues

• Issue Add OpenAPI/Swagger documentation for API endpoints #21 (OpenAPI/Swagger documentation)

[haroon0x]

/assign @haroon0x