Source code for biblicus.api.graph
"""
Typed request and function for the ``graph extract`` command.
"""
from __future__ import annotations
from typing import Any, Callable, Dict, List, Optional
from pydantic import Field
from ..configuration import (
apply_dotted_overrides,
load_configuration_view,
parse_dotted_overrides,
)
from ..graph.models import GraphSnapshotManifest
from ..models import ExtractionSnapshotReference
from ._common import ApiRequestModel, open_request_corpus
[docs]
class GraphExtractRequest(ApiRequestModel):
"""
Request to build a graph extraction snapshot.
:ivar corpus_path: Corpus path or uniform resource identifier.
:vartype corpus_path: str
:ivar extractor_id: Graph extractor identifier, for example ``cooccurrence``.
:vartype extractor_id: str
:ivar extraction_snapshot: Extraction snapshot supplying item text.
:vartype extraction_snapshot: ExtractionSnapshotReference
:ivar configuration_name: Human-readable configuration name that keys the snapshot identity.
:vartype configuration_name: 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 max_items: Maximum extraction items to process, or None for all.
:vartype max_items: int or None
:ivar item_timeout_seconds: Per-item timeout in seconds; zero or less disables the timeout.
:vartype item_timeout_seconds: float
:ivar item_retry_attempts: Retries per item after a timeout or error.
:vartype item_retry_attempts: int
:ivar heartbeat_interval_seconds: Progress heartbeat interval; zero or less disables it.
:vartype heartbeat_interval_seconds: float
"""
corpus_path: str = Field(min_length=1)
extractor_id: str = Field(min_length=1)
extraction_snapshot: ExtractionSnapshotReference
configuration_name: str = Field(default="default", min_length=1)
configuration_paths: List[str] = Field(default_factory=list)
overrides: List[str] = Field(default_factory=list)
max_items: Optional[int] = None
item_timeout_seconds: float = 60.0
item_retry_attempts: int = Field(default=0, ge=0)
heartbeat_interval_seconds: float = 10.0
[docs]
def graph_extract(
request: GraphExtractRequest,
*,
progress_callback: Optional[Callable[[str, Dict[str, Any]], None]] = None,
) -> GraphSnapshotManifest:
"""
Build a graph extraction snapshot.
:param request: Validated request.
:type request: GraphExtractRequest
:param progress_callback: Optional callback receiving progress event names and payloads.
:type progress_callback: collections.abc.Callable or None
:return: Graph snapshot manifest.
:rtype: GraphSnapshotManifest
"""
from ..graph import extraction as graph_extraction_module
corpus = open_request_corpus(request.corpus_path)
base_configuration: Dict[str, object] = {}
if request.configuration_paths:
base_configuration = load_configuration_view(
request.configuration_paths,
configuration_label="Graph extraction configuration",
mapping_error_message="Graph extraction configuration must be a mapping/object",
)
configuration = apply_dotted_overrides(
base_configuration, parse_dotted_overrides(request.overrides)
)
return graph_extraction_module.build_graph_snapshot(
corpus,
extractor_id=request.extractor_id,
configuration_name=request.configuration_name,
configuration=configuration,
extraction_snapshot=request.extraction_snapshot,
max_items=request.max_items,
item_timeout_seconds=request.item_timeout_seconds,
item_retry_attempts=request.item_retry_attempts,
heartbeat_interval_seconds=request.heartbeat_interval_seconds,
progress_callback=progress_callback,
)