Code / scripts/ml_training/essay_scoring/features/results.py

scripts/ml_training/essay_scoring/features/results.py

View this file on Codeberg

  1
  """Feature extraction result envelope for research pipelines.


  2
  


  3
  Purpose:


  4
      Keep the model-ready feature matrix together with ledger artifact bundles


  5
      and offload provenance so downstream feature-store persistence can record


  6
      exactly which evidence produced each matrix.


  7
  


  8
  Relationships:


  9
      - Returned by `FeaturePipeline.extract`.


  10
      - Consumed by ML runners and CV feature-store preparation before persisting


  11
        warm-cache manifests and offline writing-issue artifacts.


  12
  """


  13
  


  14
  from __future__ import annotations


  15
  


  16
  from dataclasses import dataclass, field


  17
  from typing import TYPE_CHECKING


  18
  


  19
  from huleedu_nlp_shared.writing_issues import OfflineLedgerArtifactBundleV3


  20
  


  21
  from ..datasets.prompt_authority import SemanticPromptAuthority


  22
  from ..features.combiner import FeatureMatrix


  23
  


  24
  if TYPE_CHECKING:


  25
      from ..offload.extract_bundle_decoder import (


  26
          DecodedCandidateArtifact,


  27
          DecodedCandidateEmbeddingArtifact,


  28
      )


  29
      from ..offload.extract_client import (


  30
          RemoteExtractTransportAttempt,


  31
      )


  32
      from ..offload.extract_models import ExtractMeta


  33
      from ..offload.extract_outcome_models import (


  34
          ExtractAcceptedRowOutcome,


  35
      )


  36
  


  37
  


  38
  @dataclass(frozen=True)


  39
  class FeatureExtractionResult:


  40
      """Feature matrix plus provenance needed by durable feature stores."""


  41
  


  42
      feature_matrix: FeatureMatrix


  43
      ledger_bundles: list[OfflineLedgerArtifactBundleV3]


  44
      outcomes: tuple[ExtractAcceptedRowOutcome, ...]


  45
      prompt_authorities: list[SemanticPromptAuthority] = field(default_factory=list)


  46
      offload_meta: ExtractMeta | None = None


  47
      candidate_artifacts: tuple[DecodedCandidateArtifact, ...] = ()


  48
      candidate_embedding_artifacts: tuple[DecodedCandidateEmbeddingArtifact, ...] = ()


  49
      transport_attempts: tuple[RemoteExtractTransportAttempt, ...] = ()