class Trimmer:
    """Reuse trimming configuration and an optional semantic backend."""

    def __init__(
        self,
        config: TrimConfig | None = None,
        *,
        embedding_callback: EmbeddingCallback | None = None,
        async_embedding_callback: AsyncEmbeddingCallback | None = None,
    ) -> None:
        """Create a trimmer with validated reusable dependencies.

        Args:
            config: Optional custom configuration.
            embedding_callback: Optional synchronous query-and-passage embedder.
            async_embedding_callback: Optional asynchronous query-and-passage embedder.

        Raises:
            TypeError: If a supplied callback is not callable.
            ValueError: If both callback execution models are supplied.
        """
        if embedding_callback is not None and not callable(embedding_callback):
            raise TypeError("embedding_callback must be callable or None")
        if async_embedding_callback is not None and not callable(async_embedding_callback):
            raise TypeError("async_embedding_callback must be callable or None")
        if embedding_callback is not None and async_embedding_callback is not None:
            raise ValueError("only one embedding callback may be supplied")
        self.config = config or TrimConfig()
        self._embedding_callback = embedding_callback
        self._async_embedding_callback = async_embedding_callback
        self._semantic = SemanticEmbedder(self.config)

    def trim(
        self,
        text: str,
        limit: int,
        *,
        unit: BudgetUnit | str = BudgetUnit.TOKENS,
        strategy: Strategy | str = Strategy.AUTO,
        query: str | None = None,
        token_counter: Callable[[str], int] | None = None,
    ) -> TrimResult:
        """Retain high-signal source fragments within an exact budget.

        Args:
            text: Whole source string to trim.
            limit: Maximum output size in ``unit``.
            unit: Token, whitespace-word, or code-point character budget.
            strategy: Structural, lexical, semantic, hybrid, or automatic ranking.
            query: Task or question required by query-aware strategies.
            token_counter: Optional synchronous token measurement callback.

        Returns:
            Measured extractive trimming result.

        Raises:
            TypeError: If an argument is invalid or only an async embedder is available.
            ValueError: If an argument value or strategy/query combination is invalid.
            SemanticBackendError: If an explicitly requested semantic backend fails.
        """
        return self._trim(_TrimArguments(text, limit, unit, strategy, query, token_counter))

    async def atrim(
        self,
        text: str,
        limit: int,
        *,
        unit: BudgetUnit | str = BudgetUnit.TOKENS,
        strategy: Strategy | str = Strategy.AUTO,
        query: str | None = None,
        token_counter: Callable[[str], int] | None = None,
    ) -> TrimResult:
        """Run CPU and synchronous work outside the event loop.

        A configured asynchronous embedding callback is awaited on the calling event loop.
        Cancellation propagates to that callback, but cannot stop a worker thread already running.

        Args:
            text: Whole source string to trim.
            limit: Maximum output size in ``unit``.
            unit: Token, whitespace-word, or code-point character budget.
            strategy: Structural, lexical, semantic, hybrid, or automatic ranking.
            query: Task or question required by query-aware strategies.
            token_counter: Optional synchronous token measurement callback.

        Returns:
            Measured extractive trimming result.

        Raises:
            TypeError: If an argument has an unsupported type.
            ValueError: If an argument value or strategy/query combination is invalid.
            SemanticBackendError: If an explicitly requested semantic backend fails.
        """
        arguments = _TrimArguments(text, limit, unit, strategy, query, token_counter)
        callback = self._async_embedding_callback
        if callback is None:
            return await asyncio.to_thread(self._trim, arguments)

        prepared = await asyncio.to_thread(self._prepare, arguments)
        if isinstance(prepared, TrimResult):
            return prepared
        if prepared.request.strategy not in {Strategy.SEMANTIC, Strategy.HYBRID}:
            return await asyncio.to_thread(self._complete, prepared)

        query_text = prepared.request.query or ""
        passages = await asyncio.to_thread(_contextual_ranking_texts, prepared.segments)
        output = await invoke_async_embedding_callback(callback, query_text, passages)
        return await asyncio.to_thread(self._complete_with_embedding_output, prepared, output)

    def _trim(self, arguments: _TrimArguments) -> TrimResult:
        """Run one synchronous call through preparation, ranking, and selection.

        Args:
            arguments: Unvalidated public call values.

        Returns:
            Measured extractive trimming result.
        """
        prepared = self._prepare(arguments)
        if isinstance(prepared, TrimResult):
            return prepared
        return self._complete(prepared)

    def _prepare(self, arguments: _TrimArguments) -> TrimResult | _PreparedTrim:
        """Validate, measure, and segment without invoking a semantic backend.

        Args:
            arguments: Unvalidated public call values.

        Returns:
            An early result or prepared long input awaiting ranking.
        """
        resolved_unit = _parse_unit(arguments.unit)
        resolved_strategy, normalized_query = _resolve_strategy(
            _parse_strategy(arguments.strategy),
            arguments.query,
        )
        request = _TrimRequest(
            arguments.text,
            arguments.limit,
            resolved_unit,
            resolved_strategy,
            normalized_query,
            arguments.token_counter,
        )
        _validate_request(request)
        measurer = Measurer(
            resolved_unit,
            self.config.token_encoding,
            arguments.token_counter,
        )
        input_count = measurer.count(arguments.text)
        if arguments.limit == 0:
            return _result(
                _ComposedOutput("", ()), input_count, request, resolved_strategy, measurer
            )
        if input_count <= arguments.limit:
            spans = (SourceSpan(0, len(arguments.text)),) if arguments.text else ()
            output = _ComposedOutput(arguments.text, spans)
            return _result(output, input_count, request, resolved_strategy, measurer)

        segments = segment_text(arguments.text)
        if resolved_strategy is Strategy.STRUCTURAL:
            segments = _expand_structural_plaintext(segments)
        return _PreparedTrim(request, input_count, segments, measurer)

    def _complete(self, prepared: _PreparedTrim) -> TrimResult:
        """Rank and select one prepared input through a synchronous backend.

        Args:
            prepared: Validated, measured, and segmented input.

        Returns:
            Measured extractive trimming result.
        """
        request = _ranking_request(prepared)
        return self._select(prepared, self._rank(request))

    def _complete_with_embedding_output(
        self,
        prepared: _PreparedTrim,
        output: EmbeddingOutput,
    ) -> TrimResult:
        """Normalize asynchronous callback output before ranking and selection.

        Args:
            prepared: Validated, measured, and segmented input.
            output: Caller-provided query and passage vectors.

        Returns:
            Measured extractive trimming result.
        """
        vectors = normalize_callback_output(output, len(prepared.segments))
        ranking = _rank_with_semantic_vectors(_ranking_request(prepared), vectors)
        return self._select(prepared, ranking)

    def _rank(self, request: _RankingRequest) -> CandidateRanking:
        """Dispatch to the resolved ranking algorithm without a strategy hierarchy.

        Args:
            request: Segments and resolved ranking inputs.

        Returns:
            Strategy-specific candidate ranking.
        """
        if request.strategy is Strategy.STRUCTURAL:
            return rank_structural(request.segments, request.measurer)
        if request.strategy is Strategy.LEXICAL:
            return rank_lexical(request.segments, request.query or "", request.measurer)

        if self._async_embedding_callback is not None:
            raise TypeError("trim() cannot use async_embedding_callback; use atrim()")
        query = request.query or ""
        passages = _contextual_ranking_texts(request.segments)
        if self._embedding_callback is not None:
            vectors = embed_with_callback(self._embedding_callback, query, passages)
        else:
            vectors = self._semantic.embed(query, passages)
        return _rank_with_semantic_vectors(request, vectors)

    def _select(
        self,
        prepared: _PreparedTrim,
        ranking: CandidateRanking,
    ) -> TrimResult:
        """Select, compose, and measure ranked source fragments.

        Args:
            prepared: Validated, measured, and segmented input.
            ranking: Strategy-specific candidate scores and similarity behavior.

        Returns:
            Final measured extractive result.
        """
        request = prepared.request
        context = _SelectionContext(
            request.text,
            prepared.segments,
            ranking,
            prepared.measurer,
            request.limit,
            self.config.omission_marker,
            self.config.mmr_lambda,
        )
        output = (
            _select_structural(context)
            if request.strategy is Strategy.STRUCTURAL
            else _select_query_aware(context)
        )
        if output is None:
            output = _fallback_output(context)
        return _result(
            output,
            prepared.input_count,
            request,
            request.strategy,
            prepared.measurer,
        )

@dataclass(frozen=True, slots=True)
class TrimConfig:
    """Configure reusable measurement, ranking, and omission behavior.

    Attributes:
        token_encoding: Tiktoken encoding used for token budgets and lexical ranking.
        embedding_model: FastEmbed model used by semantic strategies.
        fastembed_options: Additional keyword arguments for ``TextEmbedding``.
        embedding_batch_size: Passage batch size used during inference.
        mmr_lambda: Balance between relevance and diversity.
        omission_marker: Text inserted where source content was omitted.
    """

    token_encoding: str = "o200k_base"
    embedding_model: str = "sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2"
    fastembed_options: Mapping[str, Any] = field(default_factory=dict)
    embedding_batch_size: int = 256
    mmr_lambda: float = 0.7
    omission_marker: str = "[…omitted…]"

    def __post_init__(self) -> None:
        """Validate configuration and freeze a defensive options copy.

        Raises:
            TypeError: If FastEmbed options are not a mapping.
            ValueError: If a configured value is outside its supported domain.
        """
        if not isinstance(self.token_encoding, str):
            raise TypeError("token_encoding must be a string")
        if not self.token_encoding.strip():
            raise ValueError("token_encoding must not be blank")
        if not isinstance(self.embedding_model, str):
            raise TypeError("embedding_model must be a string")
        if not self.embedding_model.strip():
            raise ValueError("embedding_model must not be blank")
        if not isinstance(self.omission_marker, str):
            raise TypeError("omission_marker must be a string")
        if not self.omission_marker.strip():
            raise ValueError("omission_marker must not be blank")
        if (
            isinstance(self.embedding_batch_size, bool)
            or not isinstance(self.embedding_batch_size, int)
            or self.embedding_batch_size <= 0
        ):
            raise ValueError("embedding_batch_size must be a positive integer")
        if (
            isinstance(self.mmr_lambda, bool)
            or not isinstance(self.mmr_lambda, (int, float))
            or not 0 <= self.mmr_lambda <= 1
        ):
            raise ValueError("mmr_lambda must be between 0 and 1")
        if not isinstance(self.fastembed_options, Mapping):
            raise TypeError("fastembed_options must be a mapping")

        options = dict(self.fastembed_options)
        if any(not isinstance(key, str) for key in options):
            raise ValueError("fastembed_options keys must be strings")
        if "model_name" in options:
            raise ValueError("model_name belongs in embedding_model")
        object.__setattr__(self, "fastembed_options", MappingProxyType(options))

@dataclass(frozen=True, slots=True)
class TrimResult:
    """Describe the resolved strategy and measured truncation result.

    Attributes:
        text: Extractive output that fits the requested limit.
        input_count: Measured size of the original input.
        output_count: Measured size of the returned output.
        limit: Requested maximum output size.
        unit: Unit used for all counts.
        strategy: Concrete strategy used after resolving ``auto``.
        trimmed: Whether the output differs from the input.
        spans: Ordered, nonoverlapping ranges retained from the original input.
    """

    text: str
    input_count: int
    output_count: int
    limit: int
    unit: BudgetUnit
    strategy: Strategy
    trimmed: bool
    spans: tuple[SourceSpan, ...] = ()

@dataclass(frozen=True, slots=True)
class SourceSpan:
    """Identify a retained range in the original input string.

    Attributes:
        start: Inclusive Python-string offset.
        end: Exclusive Python-string offset.
    """

    start: int
    end: int

class Strategy(str, Enum):
    """Select the evidence-ranking method used during truncation."""

    AUTO = "auto"
    STRUCTURAL = "structural"
    LEXICAL = "lexical"
    SEMANTIC = "semantic"
    HYBRID = "hybrid"

class BudgetUnit(str, Enum):
    """Define how an input and output budget is measured."""

    TOKENS = "tokens"
    WORDS = "words"
    CHARACTERS = "characters"

class SemanticBackendError(RuntimeError):
    """Report an optional semantic backend failure without hiding its cause."""