Source code for biblicus.api.topic_classifier

"""
Typed requests and functions for the ``topic-classifier`` command group.
"""

from __future__ import annotations

from pathlib import Path
from typing import List

from pydantic import Field

from .. import topic_classifier as topic_classifier_module
from ..configuration import (
    apply_dotted_overrides,
    load_configuration_view,
    parse_dotted_overrides,
)
from ..corpus import Corpus
from ..models import ExtractionSnapshotReference
from ..topic_classifier import TopicClassifierProjectionOutput, TopicClassifierTrainOutput
from ._common import ApiRequestModel, open_request_corpus


[docs] class TopicClassifierTrainRequest(ApiRequestModel): """ Request to train a topic classifier model version. :ivar corpus_path: Corpus path or uniform resource identifier. :vartype corpus_path: str :ivar manifest_path: Topic classifier seed manifest path. :vartype manifest_path: str :ivar configuration_paths: Configuration YAML paths; later files override earlier ones. :vartype configuration_paths: list[str] :ivar overrides: ``key=value`` overrides applied after composing configurations. :vartype overrides: list[str] :ivar configuration_name: Human-readable configuration name that keys the snapshot identity. :vartype configuration_name: str :ivar extraction_snapshot: Extraction snapshot supplying item text. :vartype extraction_snapshot: ExtractionSnapshotReference """ corpus_path: str = Field(min_length=1) manifest_path: str = Field(min_length=1) configuration_paths: List[str] = Field(min_length=1) overrides: List[str] = Field(default_factory=list) configuration_name: str = Field(default="default", min_length=1) extraction_snapshot: ExtractionSnapshotReference
[docs] class TopicClassifierProjectRequest(ApiRequestModel): """ Request to project a classifier from an authority corpus onto a target corpus. :ivar classifier_corpus_path: Corpus path holding classifier artifacts. :vartype classifier_corpus_path: str :ivar target_corpus_path: Corpus path holding the items to classify. :vartype target_corpus_path: str :ivar classifier_id: Topic classifier identifier. :vartype classifier_id: str :ivar extraction_snapshot: Target corpus extraction snapshot. :vartype extraction_snapshot: ExtractionSnapshotReference :ivar project_all: True to project onto every target item. :vartype project_all: bool :ivar item_ids: Target item identifiers to project. :vartype item_ids: list[str] :ivar review_threshold: Minimum confidence before review is recommended. :vartype review_threshold: float :ivar top_k: Maximum ranked topic candidates to include. :vartype top_k: int :ivar record: True to persist projection predictions as audit records. :vartype record: bool """ classifier_corpus_path: str = Field(min_length=1) target_corpus_path: str = Field(min_length=1) classifier_id: str = Field(min_length=1) extraction_snapshot: ExtractionSnapshotReference project_all: bool = False item_ids: List[str] = Field(default_factory=list) review_threshold: float = 0.35 top_k: int = Field(default=5, ge=1) record: bool = False
[docs] def topic_classifier_train(request: TopicClassifierTrainRequest) -> TopicClassifierTrainOutput: """ Train a topic classifier model version. :param request: Validated request. :type request: TopicClassifierTrainRequest :return: Training output. :rtype: TopicClassifierTrainOutput """ corpus = open_request_corpus(request.corpus_path) configuration_data = load_configuration_view( request.configuration_paths, configuration_label="Topic classifier configuration", mapping_error_message="Topic classifier configuration must be a mapping/object", ) configuration_data = apply_dotted_overrides( configuration_data, parse_dotted_overrides(request.overrides) ) return topic_classifier_module.train_topic_classifier( corpus=corpus, manifest_path=Path(request.manifest_path).resolve(), configuration_name=request.configuration_name, configuration=configuration_data, extraction_snapshot=request.extraction_snapshot, )
[docs] def topic_classifier_project( request: TopicClassifierProjectRequest, ) -> TopicClassifierProjectionOutput: """ Project a topic classifier from an authority corpus onto a target corpus. :param request: Validated request. :type request: TopicClassifierProjectRequest :return: Projection output. :rtype: TopicClassifierProjectionOutput """ return topic_classifier_module.project_topic_classifier_items( classifier_corpus=Corpus.open(request.classifier_corpus_path), target_corpus=Corpus.open(request.target_corpus_path), classifier_id=request.classifier_id, extraction_snapshot=request.extraction_snapshot, project_all=request.project_all, item_ids=request.item_ids, review_threshold=request.review_threshold, top_k=request.top_k, record=request.record, )