Source code for biblicus.api

"""
Typed Python application programming interface for the commands that Papyrus calls.

Each command has one Pydantic request model, one Pydantic response model and one plain function
that takes the request and returns the response. The command-line interface is a thin wrapper over
these functions and prints the response model as JSON. The :data:`API_COMMANDS` registry lists
every command so JSON Schemas can be generated and published.
"""

from __future__ import annotations

from typing import Any, Callable, Dict, NamedTuple, Type

from pydantic import BaseModel

from ._common import (
    ApiRequestModel,
    ApiResponseModel,
    InvalidRequestError,
    format_validation_error,
    open_request_corpus,
    validate_request,
)
from .analysis import (
    TopicContextRequest,
    TopicIdentityRequest,
    TopicTrendsRequest,
    analyze_topic_context,
    analyze_topic_identity,
    analyze_topic_trends,
)
from .context_pack import (
    ContextPackBuildBlocksRequest,
    ContextPackBuildBlocksResponse,
    context_pack_build_blocks,
)
from .graph import GraphExtractRequest, graph_extract
from .retrieval import QueryRequest, ReindexRequest, ReindexResponse, query, reindex
from .steering import (
    SteeringArtifactsRequest,
    SteeringExportRequest,
    SteeringGraphSignalsRequest,
    SteeringRenderSeedManifestRequest,
    steering_artifacts,
    steering_export,
    steering_graph_signals,
    steering_render_seed_manifest,
)
from .taxonomy import (
    TaxonomyDiscoverRequest,
    TaxonomyRecordRequest,
    taxonomy_discover,
    taxonomy_record,
)
from .topic_classifier import (
    TopicClassifierProjectRequest,
    TopicClassifierTrainRequest,
    topic_classifier_project,
    topic_classifier_train,
)
from .typed_extraction import TypedEntitiesRequest, extract_typed_entities
from .web import (
    ArticleTextRequest,
    ArticleTextResponse,
    SummarizeMapReduceRequest,
    SummarizeMapReduceResponse,
    UrlTextFailureDetails,
    UrlTextRequest,
    UrlTextResponse,
    WebMetadataRequest,
    WebMetadataResponse,
    extract_article_text,
    extract_url_text,
    extract_web_metadata,
    summarize_map_reduce,
)


[docs] class ApiCommand(NamedTuple): """ Registry entry tying a command to its request model, response model and function. :ivar name: Stable schema file stem, for example ``taxonomy-discover``. :vartype name: str :ivar group: Command-line group, for example ``taxonomy``. :vartype group: str :ivar request_model: Pydantic request model class. :vartype request_model: type[pydantic.BaseModel] :ivar response_model: Pydantic response model class. :vartype response_model: type[pydantic.BaseModel] :ivar function: Plain function taking the request and returning the response. :vartype function: collections.abc.Callable """ name: str group: str request_model: Type[BaseModel] response_model: Type[BaseModel] function: Callable[..., Any]
def _registry_entries() -> Dict[str, ApiCommand]: from ..context import ContextBlockBuildRequest, ContextBlockBuildResult from ..graph.models import GraphSnapshotManifest from ..models import RetrievalResult from ..steering import ( SteeringArtifactInventory, SteeringExportBundle, SteeringRenderSeedManifestOutput, ) from ..steering_proposals import SteeringProposalBundle from ..taxonomy import TaxonomyDiscoveryOutput, TaxonomyRecordOutput from ..topic_classifier import TopicClassifierProjectionOutput, TopicClassifierTrainOutput from ..topic_context import TopicContextOutput from ..topic_identity import TopicIdentityOutput from ..topic_trends import TopicTrendOutput from ..typed_extraction import TypedEntitiesOutput from ..web_transform import ArticleInput, TransformResult entries = [ ( "taxonomy-record", "taxonomy", TaxonomyRecordRequest, TaxonomyRecordOutput, taxonomy_record, ), ( "taxonomy-discover", "taxonomy", TaxonomyDiscoverRequest, TaxonomyDiscoveryOutput, taxonomy_discover, ), ( "steering-export", "steering", SteeringExportRequest, SteeringExportBundle, steering_export, ), ( "steering-artifacts", "steering", SteeringArtifactsRequest, SteeringArtifactInventory, steering_artifacts, ), ( "steering-graph-signals", "steering", SteeringGraphSignalsRequest, SteeringProposalBundle, steering_graph_signals, ), ( "steering-render-seed-manifest", "steering", SteeringRenderSeedManifestRequest, SteeringRenderSeedManifestOutput, steering_render_seed_manifest, ), ( "topic-classifier-train", "topic-classifier", TopicClassifierTrainRequest, TopicClassifierTrainOutput, topic_classifier_train, ), ( "topic-classifier-project", "topic-classifier", TopicClassifierProjectRequest, TopicClassifierProjectionOutput, topic_classifier_project, ), ( "analyze-topic-context", "analyze", TopicContextRequest, TopicContextOutput, analyze_topic_context, ), ( "analyze-topic-trends", "analyze", TopicTrendsRequest, TopicTrendOutput, analyze_topic_trends, ), ( "analyze-topic-identity", "analyze", TopicIdentityRequest, TopicIdentityOutput, analyze_topic_identity, ), ( "extract-typed-entities", "extract", TypedEntitiesRequest, TypedEntitiesOutput, extract_typed_entities, ), ( "context-pack-build-blocks", "context-pack", ContextBlockBuildRequest, ContextBlockBuildResult, context_pack_build_blocks, ), ( "summarize-map-reduce", "summarize", SummarizeMapReduceRequest, TransformResult, summarize_map_reduce, ), ("extract-url-text", "extract", UrlTextRequest, UrlTextResponse, extract_url_text), ( "extract-article-text", "extract", ArticleInput, TransformResult, extract_article_text, ), ( "extract-web-metadata", "extract", WebMetadataRequest, WebMetadataResponse, extract_web_metadata, ), ("query", "query", QueryRequest, RetrievalResult, query), ("reindex", "reindex", ReindexRequest, ReindexResponse, reindex), ("graph-extract", "graph", GraphExtractRequest, GraphSnapshotManifest, graph_extract), ] return {name: ApiCommand(name, group, req, res, fn) for name, group, req, res, fn in entries} API_COMMANDS: Dict[str, ApiCommand] = _registry_entries()
[docs] def build_api_schemas() -> Dict[str, Dict[str, Any]]: """ Build the JSON Schema for every request and response model. Request schemas use validation mode and response schemas use serialization mode, so a response schema describes exactly the JSON the command prints. :return: Mapping of ``<command>.request`` and ``<command>.response`` to a JSON Schema object. :rtype: dict[str, dict[str, Any]] """ schemas: Dict[str, Dict[str, Any]] = {} for command in API_COMMANDS.values(): schemas[f"{command.name}.request"] = command.request_model.model_json_schema() schemas[f"{command.name}.response"] = command.response_model.model_json_schema( mode="serialization" ) return schemas
__all__ = [ "API_COMMANDS", "ApiCommand", "ApiRequestModel", "ApiResponseModel", "ArticleTextRequest", "ArticleTextResponse", "ContextPackBuildBlocksRequest", "ContextPackBuildBlocksResponse", "GraphExtractRequest", "QueryRequest", "ReindexRequest", "ReindexResponse", "SteeringArtifactsRequest", "SteeringExportRequest", "SteeringGraphSignalsRequest", "SteeringRenderSeedManifestRequest", "SummarizeMapReduceRequest", "SummarizeMapReduceResponse", "TaxonomyDiscoverRequest", "TaxonomyRecordRequest", "TopicClassifierProjectRequest", "TopicClassifierTrainRequest", "TopicContextRequest", "TopicIdentityRequest", "TopicTrendsRequest", "TypedEntitiesRequest", "UrlTextRequest", "UrlTextFailureDetails", "UrlTextResponse", "WebMetadataRequest", "WebMetadataResponse", "analyze_topic_context", "analyze_topic_trends", "build_api_schemas", "context_pack_build_blocks", "extract_article_text", "extract_typed_entities", "extract_url_text", "extract_web_metadata", "InvalidRequestError", "format_validation_error", "graph_extract", "open_request_corpus", "query", "reindex", "steering_artifacts", "steering_export", "steering_graph_signals", "steering_render_seed_manifest", "summarize_map_reduce", "taxonomy_discover", "taxonomy_record", "topic_classifier_project", "topic_classifier_train", "validate_request", ]