Class ExtractionStats

explainshell/extraction/types.py:14–60

Extensible bag of metrics. Adding a stat = one new field with a default. All additive fields default to zero so that aggregate accumulators (``total = ExtractionStats(); total += per_file_stats``) start correctly. Per-file extractors set ``chunks = 1`` (or higher) at extraction time.

@dataclass
class ExtractionStats:
    """Extensible bag of metrics. Adding a stat = one new field with a default.

    All additive fields default to zero so that aggregate accumulators
    (``total = ExtractionStats(); total += per_file_stats``) start correctly.
    Per-file extractors set ``chunks = 1`` (or higher) at extraction time.
    """

    # LLM input token count (batch-level aggregate).
    input_tokens: int = 0
    # LLM output token count (batch-level aggregate).
    output_tokens: int = 0
    # LLM reasoning/thinking tokens (subset of output).
    reasoning_tokens: int = 0
    # Number of text chunks sent to the LLM for this file.
    chunks: int = 0
    # Character count of the manpage plain text after filtering.
    plain_text_len: int = 0
    # Wall-clock time for extraction.
    elapsed_seconds: float = 0.0
    # Options skipped due to invalid LLM output that could not be recovered
    # by normalization (e.g. missing lines, structurally broken dicts).
    malformed_options: int = 0
    # Options recovered by normalize_option_fields (e.g. has_argument: null → False,
    # list[int] → list[str]).
    normalized_options: int = 0
    # Options removed by drop_empty in postprocessing because they had no
    # flags (short/long) and no positional name — typically caused by the
    # LLM omitting the flag from its response.
    dropped_empty: int = 0
    # Options removed as duplicates (exact-match or strict-subset) by
    # dedup_options in postprocessing.
    deduped_options: int = 0

    def __iadd__(self, other: ExtractionStats) -> ExtractionStats:
        """Accumulate numeric fields."""
        self.input_tokens += other.input_tokens
        self.output_tokens += other.output_tokens
        self.reasoning_tokens += other.reasoning_tokens
        self.chunks += other.chunks
        self.plain_text_len += other.plain_text_len
        self.elapsed_seconds += other.elapsed_seconds
        self.malformed_options += other.malformed_options
        self.normalized_options += other.normalized_options
        self.dropped_empty += other.dropped_empty
        self.deduped_options += other.deduped_options
        return self


class ExtractionOutcome(enum.Enum):