"""
ChunkHive Scoring Base Module
=============================

Defines scoring interfaces and result structures for modular ranking.
All scoring strategies must inherit from BaseScorer.

This layer is model-agnostic and LLM-independent.
"""

from abc import ABC, abstractmethod
from dataclasses import dataclass
from typing import Dict, Any


# =============================================================================
# SCORE RESULT
# =============================================================================

@dataclass
class ScoreResult:
    """
    Represents a scoring result for a chunk.
    
    Attributes:
        score: Final numeric score
        details: Optional metadata explaining how score was computed
    """
    score: float
    details: Dict[str, Any]


# =============================================================================
# BASE SCORER
# =============================================================================

class BaseScorer(ABC):
    """
    Abstract base class for all scoring strategies.
    
    Every scorer must implement:
        score(query, chunk) -> ScoreResult
    """

    def __init__(self, weight: float = 1.0):
        """
        Args:
            weight: Multiplier applied to this scorer’s output
        """
        self.weight = weight

    @abstractmethod
    def score(self, query: str, chunk) -> ScoreResult:
        """
        Compute score for a single chunk.

        Args:
            query: User search query
            chunk: SemanticChunk object

        Returns:
            ScoreResult
        """
        pass
