Source code for biblicus.api.steering

"""
Typed requests and functions for the ``steering`` command group.
"""

from __future__ import annotations

from pathlib import Path
from typing import Optional

from pydantic import Field

from ..steering import (
    SteeringArtifactInventory,
    SteeringExportBundle,
    SteeringRenderSeedManifestOutput,
    build_steering_artifact_inventory,
    build_steering_export,
    render_steering_seed_manifest,
)
from ..steering_feedback import load_steering_feedback
from ..steering_proposals import SteeringProposalBundle, build_steering_graph_signal_bundle
from ._common import ApiRequestModel, open_request_corpus


[docs] class SteeringExportRequest(ApiRequestModel): """ Request to export a stable steering bundle. :ivar corpus_path: Corpus path or uniform resource identifier. :vartype corpus_path: str :ivar classifier_id: Topic classifier identifier used to load the accepted topic set. :vartype classifier_id: str :ivar topic_governance_snapshot_id: Topic governance snapshot, or None for the latest pointer. :vartype topic_governance_snapshot_id: str or None """ corpus_path: str = Field(min_length=1) classifier_id: str = Field(min_length=1) topic_governance_snapshot_id: Optional[str] = Field(default=None, min_length=1)
[docs] class SteeringArtifactsRequest(ApiRequestModel): """ Request to list stable artifact references. :ivar corpus_path: Corpus path or uniform resource identifier. :vartype corpus_path: str """ corpus_path: str = Field(min_length=1)
[docs] class SteeringGraphSignalsRequest(ApiRequestModel): """ Request to emit topic-informed graph steering signals. :ivar corpus_path: Corpus path or uniform resource identifier. :vartype corpus_path: str :ivar classifier_id: Topic classifier identifier used to load accepted topics. :vartype classifier_id: str :ivar graph_snapshot: Graph snapshot reference in ``extractor_id:snapshot_id`` form. :vartype graph_snapshot: str :ivar steering_feedback_path: Optional reviewed steering feedback JSON path. :vartype steering_feedback_path: str or None """ corpus_path: str = Field(min_length=1) classifier_id: str = Field(min_length=1) graph_snapshot: str = Field(min_length=1) steering_feedback_path: Optional[str] = Field(default=None, min_length=1)
[docs] class SteeringRenderSeedManifestRequest(ApiRequestModel): """ Request to render an accepted steering topic set as a seed manifest. :ivar input_path: Accepted steering topic-set JSON input path. :vartype input_path: str :ivar output_path: Destination seed-manifest path. :vartype output_path: str """ input_path: str = Field(min_length=1) output_path: str = Field(min_length=1)
[docs] def steering_export(request: SteeringExportRequest) -> SteeringExportBundle: """ Export a stable steering bundle for an external application. :param request: Validated request. :type request: SteeringExportRequest :return: Steering export bundle. :rtype: SteeringExportBundle """ return build_steering_export( corpus=open_request_corpus(request.corpus_path), classifier_id=request.classifier_id, topic_governance_snapshot_id=request.topic_governance_snapshot_id, )
[docs] def steering_artifacts(request: SteeringArtifactsRequest) -> SteeringArtifactInventory: """ List stable artifact references for an external steering worker. :param request: Validated request. :type request: SteeringArtifactsRequest :return: Artifact inventory. :rtype: SteeringArtifactInventory """ return build_steering_artifact_inventory(open_request_corpus(request.corpus_path))
[docs] def steering_graph_signals(request: SteeringGraphSignalsRequest) -> SteeringProposalBundle: """ Emit topic-informed graph steering signals. :param request: Validated request. :type request: SteeringGraphSignalsRequest :return: Steering proposal bundle. :rtype: SteeringProposalBundle """ steering_feedback = ( load_steering_feedback(Path(request.steering_feedback_path)) if request.steering_feedback_path else None ) return build_steering_graph_signal_bundle( corpus=open_request_corpus(request.corpus_path), classifier_id=request.classifier_id, graph_snapshot=request.graph_snapshot, steering_feedback=steering_feedback, )
[docs] def steering_render_seed_manifest( request: SteeringRenderSeedManifestRequest, ) -> SteeringRenderSeedManifestOutput: """ Render an accepted steering topic set as a Biblicus seed manifest. :param request: Validated request. :type request: SteeringRenderSeedManifestRequest :return: Description of the rendered manifest. :rtype: SteeringRenderSeedManifestOutput """ return render_steering_seed_manifest( input_path=Path(request.input_path), output_path=Path(request.output_path), )