API

Package librovore

🐲📚 Librovore - CLI and MCP server for consuming documentation.

librovore.main()

Entrypoint.

Module librovore.interfaces

Common enumerations and interfaces.

class librovore.interfaces.DisplayFormat(value)

Bases: Enum

Enumeration for CLI display formats.

Variables:
class librovore.interfaces.FilterCapability(*, name, description, type, values=None, required=False)

Bases: DataclassObject

Describes a filter supported by a processor.

Variables:
class librovore.interfaces.MatchMode(value)

Bases: str, Enum

Enumeration for different term matching modes.

Variables:
class librovore.interfaces.ProcessorCapabilities(*, processor_name, version, supported_filters, results_limit_max=None, response_time_typical=None, notes=None)

Bases: DataclassObject

Complete capability description for a processor.

Variables:
render_as_json()

Renders capabilities as JSON-compatible dictionary.

Parameters:

self

Return type:

dict[ str, typing_extensions.Any ]

render_as_markdown()

Renders capabilities as Markdown lines for display.

Parameters:

self

Return type:

tuple[ str, … ]

class librovore.interfaces.ProcessorGenera(value)

Bases: Enum

Enumeration for processor types/genera.

Variables:
class librovore.interfaces.SearchBehaviors(*, match_mode=MatchMode.Similar, similarity_score_min=50, contains_term=True, case_sensitive=False)

Bases: DataclassObject

Search behavior configuration for the search engine.

Variables:

  • match_mode (librovore.interfaces.MatchMode)

  • similarity_score_min (int)

  • contains_term (bool) – Enable substring matching in Exact and Similar modes. When enabled, allows terms to match as substrings.

  • case_sensitive (bool) – Enable case-sensitive matching. When False, performs case-insensitive matching (default).

Module librovore.cacheproxy

HTTP cache for documentation URL access.

type librovore.cacheproxy.HttpClientFactory = collections.abc.Callable[[], httpx.AsyncClient]
type librovore.cacheproxy.ContentResponse = appcore.generics.Result[bytes, Exception]
type librovore.cacheproxy.ProbeResponse = appcore.generics.Result[bool, Exception]
type librovore.cacheproxy.RobotsResponse = appcore.generics.Result[urllib.robotparser.RobotFileParser, Exception]
class librovore.cacheproxy.Cache(*, error_ttl=absence.absent, success_ttl=absence.absent, delay_function=<function sleep>)

Bases: Object

Cache base with shared configuration attributes.

Variables:
acquire_mutex_for(url)

Acquires mutex for HTTP request deduplication.

Parameters:

  • self

  • url (str)

class librovore.cacheproxy.CacheEntry(*, timestamp, ttl)

Bases: DataclassObject

Cache entry base.

Variables:
property invalid

Checks if cache entry has exceeded its TTL.

Parameters:

self

Return type:

bool

class librovore.cacheproxy.ContentCache(*, robots_cache=absence.absent, memory_max=absence.absent, **base_initargs)

Bases: Cache

Cache manager for URL content (GET requests) with memory tracking.

Variables:
async access(url)

Retrieves cached content if valid.

Parameters:

  • self

  • url (str)

Return type:

tuple[ bytes, httpx.Headers ] | absence.objects.AbsentSingleton

determine_ttl(response)

Determines appropriate TTL based on response type.

Parameters:
Return type:

float

classmethod from_configuration(configuration, robots_cache=absence.absent)

Creates ContentCache instance from application configuration.

Parameters:
Return type:

typing_extensions.Self

async retrieve_url(url, /, *, duration_max=30.0, client_factory=<class 'httpx.AsyncClient'>)

Convenience method for retrieving URL content.

Parameters:
Return type:

bytes

async store(url, response, headers, ttl)

Stores content in cache with memory management.

Parameters:
class librovore.cacheproxy.ContentCacheEntry(*, timestamp, ttl, response, headers, size_bytes)

Bases: CacheEntry

Cache entry for URL content with size tracking.

Variables:
property memory_usage

Calculates total memory usage including metadata.

Parameters:

self

Return type:

int

class librovore.cacheproxy.ProbeCache(*, robots_cache=absence.absent, entries_max=absence.absent, **base_initargs)

Bases: Cache

Cache manager for URL probe results (HEAD requests).

Variables:
async access(url)

Retrieves cached probe result if valid.

Parameters:

  • self

  • url (str)

Return type:

bool | absence.objects.AbsentSingleton

determine_ttl(response)

Determines appropriate TTL based on response type.

Parameters:
Return type:

float

classmethod from_configuration(configuration, robots_cache=absence.absent)

Creates ProbeCache instance from application configuration.

Parameters:
Return type:

typing_extensions.Self

async probe_url(url, /, *, duration_max=10.0, client_factory=<class 'httpx.AsyncClient'>)

Convenience method for probing URL existence.

Parameters:
Return type:

bool

async store(url, response, ttl)

Stores probe result in cache.

Parameters:
class librovore.cacheproxy.ProbeCacheEntry(*, timestamp, ttl, response)

Bases: CacheEntry

Cache entry for URL probe results.

Variables:
class librovore.cacheproxy.RobotsCache(*, entries_max=absence.absent, ttl=absence.absent, request_timeout=absence.absent, user_agent=absence.absent, **base_initargs)

Bases: Cache

Cache manager for robots.txt files with crawl delay tracking.

Variables:
async access(domain)

Retrieves cached robots.txt parser if valid.

Parameters:

  • self

  • domain (str)

Return type:

urllib.robotparser.RobotFileParser | absence.objects.AbsentSingleton

assign_delay(domain, delay_seconds)

Sets next allowed request time for domain.

Parameters:

  • self

  • domain (str)

  • delay_seconds (float)

calculate_delay_remainder(domain)

Returns remaining crawl delay time for domain.

Parameters:

  • self

  • domain (str)

Return type:

float

determine_ttl(response)

Determines appropriate TTL based on response type.

Parameters:
Return type:

float

classmethod from_configuration(configuration)

Creates RobotsCache instance from application configuration.

Parameters:
Return type:

typing_extensions.Self

async store(domain, response, ttl)

Stores robots.txt parser in cache.

Parameters:
class librovore.cacheproxy.RobotsCacheEntry(*, timestamp, ttl, response)

Bases: CacheEntry

Cache entry for robots.txt parser.

Variables:
librovore.cacheproxy.prepare(auxdata)

Prepares cache instances from configuration.

Returns cache instances constructed from application configuration.

Parameters:

auxdata (appcore.state.Globals)

Return type:

tuple[ librovore.cacheproxy.ContentCache, librovore.cacheproxy.ProbeCache, librovore.cacheproxy.RobotsCache ]

async librovore.cacheproxy.probe_url(cache, url, *, duration_max=10.0, client_factory=<class 'httpx.AsyncClient'>)

Cached HEAD request to check URL existence.

Parameters:
Return type:

bool

async librovore.cacheproxy.retrieve_url(cache, url, *, duration_max=30.0, client_factory=<class 'httpx.AsyncClient'>)

Cached GET request to fetch URL content as bytes.

Parameters:
Return type:

bytes

async librovore.cacheproxy.retrieve_url_as_text(cache, url, *, duration_max=30.0, charset_default='utf-8', client_factory=<class 'httpx.AsyncClient'>)

Cached GET request to fetch URL content as text.

Parameters:
Return type:

str

Module librovore.detection

Documentation source detection system for plugin architecture.

class librovore.detection.DetectionsCache(*, ttl=3600, _entries=<factory>)

Bases: DataclassObject

Cache for source detection results with TTL support.

Variables:

ttl (int)

access_detection_optimal(source)

Returns the best detection for source, if unexpired.

Parameters:

  • self

  • source (str)

Return type:

librovore.processors.Detection | absence.objects.AbsentSingleton

access_detections(source)

Returns all detections for source, if unexpired.

Parameters:

  • self

  • source (str)

Return type:

collections.abc.Mapping[ str, librovore.processors.Detection ] | absence.objects.AbsentSingleton

add_entry(source, detections)

Adds or updates cache entry with fresh results.

Parameters:
Return type:

typing_extensions.Self

clear()

Clears all cached entries.

Parameters:

self

Return type:

typing_extensions.Self

class librovore.detection.DetectionsCacheEntry(*, detections, timestamp, ttl)

Bases: DataclassObject

Cache entry for source detection results.

Variables:
invalid(current_time)

Checks if cache entry has expired.

Parameters:

  • self

  • current_time (float)

Return type:

bool

property detection_optimal

Returns the detection with highest confidence.

Parameters:

self

Return type:

librovore.processors.Detection | absence.objects.AbsentSingleton

async librovore.detection.access_detections(auxdata, source, /, *, genus)

Accesses detections via appropriate cache.

Parameters:
Return type:

tuple[ collections.abc.Mapping[ str, librovore.processors.Detection ], librovore.processors.Detection | absence.objects.AbsentSingleton ]

async librovore.detection.access_detections_ll(auxdata, source, /, *, cache, processors)

Accesses detections via appropriate cache.

Detections are performed to fill cache, if necessary.

Low-level function accepting arbitrary cache and processors list.

Parameters:
Return type:

tuple[ collections.abc.Mapping[ str, librovore.processors.Detection ], librovore.processors.Detection | absence.objects.AbsentSingleton ]

async librovore.detection.detect(auxdata, source, /, genus, *, processor_name=absence.absent)

Detects processors for source through cache system.

Parameters:
Return type:

librovore.processors.Detection

async librovore.detection.detect_inventory(auxdata, source, /, *, processor_name=absence.absent)

Detects inventory processors for source through cache system.

Parameters:

  • auxdata (librovore.state.Globals)

  • source (str)

  • processor_name (str | absence.objects.AbsentSingleton)

Return type:

librovore.processors.InventoryDetection

async librovore.detection.detect_structure(auxdata, source, /, *, processor_name=absence.absent)

Detects structure processors for source through cache system.

Parameters:

  • auxdata (librovore.state.Globals)

  • source (str)

  • processor_name (str | absence.objects.AbsentSingleton)

Return type:

librovore.processors.StructureDetection

async librovore.detection.determine_detection_optimal_ll(auxdata, source, /, *, cache, processors)

Determines which processor can best handle the source.

Low-level function accepting arbitrary cache and processors list.

Parameters:
Return type:

librovore.processors.Detection | absence.objects.AbsentSingleton

librovore.detection.resolve_source_url(url)

Resolves source URL through redirect cache, returns working URL.

Parameters:

url (str)

Return type:

str

Module librovore.functions

Core business logic shared between CLI and MCP server.

type librovore.functions.LocationArgument = str
async librovore.functions.detect(auxdata, location, /, genus, processor_name=absence.absent)

Detects relevant processors of particular genus for location.

Parameters:
Return type:

librovore.results.DetectionsResult

async librovore.functions.query_content(auxdata, location, term, /, *, processor_name=absence.absent, search_behaviors=SearchBehaviors(match_mode=<MatchMode.Similar: 'similar'>, similarity_score_min=50, contains_term=True, case_sensitive=False), filters=frigid.dictionaries.Dictionary( {} ), content_id=absence.absent, results_max=10, lines_max=None)

Searches documentation content with relevance ranking.

Parameters:
Return type:

librovore.results.ContentQueryResult

async librovore.functions.query_inventory(auxdata, location, term, /, *, processor_name=absence.absent, search_behaviors=SearchBehaviors(match_mode=<MatchMode.Similar: 'similar'>, similarity_score_min=50, contains_term=True, case_sensitive=False), filters=frigid.dictionaries.Dictionary( {} ), results_max=5)

Searches object inventory by name.

Returns configurable detail levels. Always includes object names plus requested detail flags (signatures, summaries, documentation).

Parameters:
Return type:

librovore.results.InventoryQueryResult

async librovore.functions.survey_processors(auxdata, /, genus, name=None)

Lists processor capabilities for specified genus, filtered by name.

Parameters:
Return type:

librovore.results.ProcessorsSurveyResult

Module librovore.search

Centralized search engine for universal matching across processors.

librovore.search.filter_by_name(objects, term, /, *, search_behaviors=SearchBehaviors(match_mode=<MatchMode.Similar: 'similar'>, similarity_score_min=50, contains_term=True, case_sensitive=False))

Filters objects by name using specified match mode and options.

Parameters:
Return type:

tuple[ librovore.results.SearchResult, … ]

Module librovore.cli

Command-line interface.

class librovore.cli.Cli(*, display=<factory>, command, logfile=None)

Bases: DataclassObject

MCP server CLI.

Variables:
prepare_invocation_args()

Prepares arguments for initial configuration.

Parameters:

self

Return type:

collections.abc.Mapping[ str, typing_extensions.Any ]

class librovore.cli.DetectCommand(*, location, genus, processor_name=None)

Bases: _CliCommand

Detect which processors can handle a documentation source.

Variables:
class librovore.cli.DisplayOptions(*, format=DisplayFormat.Markdown, target_stream=TargetStream.Stderr, target_file=None, color=True)

Bases: DataclassObject

Consolidated display configuration for CLI output.

Variables:
decide_rich_markdown(stream)

Determines whether to use Rich markdown rendering.

Parameters:
Return type:

bool

async provide_stream(exits)

Provides the target output stream.

Parameters:
Return type:

TextIO

class librovore.cli.QueryContentCommand(*, location, term, search_behaviors=<factory>, filters=<factory>, results_max=10, lines_max=40, content_id=None, reveal_internals=False)

Bases: _CliCommand

Searches documentation with flexible preview/extraction modes.

Workflows:

  • Sample: Use –lines-max 5-10 to preview results and identify relevant content

  • Extract: Use –content-id from sample results to retrieve full content

  • Direct: Search with higher –lines-max for immediate full results

Variables:
class librovore.cli.QueryInventoryCommand(*, location, term, filters=<factory>, search_behaviors=<factory>, results_max=5, reveal_internals=False)

Bases: _CliCommand

Explores documentation structure and object inventory.

Use before content searches to:

  • Discover available topics and object types

  • Identify relevant search terms and filters

  • Understand documentation scope and organization

Variables:
class librovore.cli.ServeCommand(*, port=None, transport=None, extra_functions=False, serve_function=<function serve>)

Bases: _CliCommand

Starts MCP server.

Variables:
class librovore.cli.SurveyProcessorsCommand(*, genus, name=None)

Bases: _CliCommand

List processors for specified genus and their capabilities.

Variables:
class librovore.cli.TargetStream(value)

Bases: Enum

Output stream selection.

librovore.cli.decide_rich_markdown(stream, colorize)

Determines whether to use Rich markdown rendering.

librovore.cli.execute()

Entrypoint for CLI execution.

librovore.cli.intercept_errors()

Decorator for CLI handlers to intercept exceptions.

Catches Omnierror exceptions and renders them appropriately. Other exceptions are logged and formatted simply.

Module librovore.server

MCP server implementation.

type librovore.server.FiltersMutable = dict[str, typing_extensions.Any]
type librovore.server.GroupByArgument = str | None
type librovore.server.TermArgument = str
type librovore.server.ResultsMax = int
type librovore.server.LocationArgument = str
type librovore.server.ContainsTerm = bool
type librovore.server.CaseSensitive = bool
class librovore.server.SearchBehaviorsMutable(*, match_mode=MatchMode.Similar, similarity_score_min=50)

Bases: object

Mutable version of SearchBehaviors for FastMCP/Pydantic compatibility.

Note: Fields are manually duplicated from SearchBehaviors to avoid immutable dataclass internals leaking into JSON schema generation.

Variables:
librovore.server.intercept_errors(func)

Decorator for MCP functions to intercept self-rendering exceptions.

Catches Omnierror exceptions and returns their JSON representation instead of raising them. Other exceptions are re-raised unchanged.

Parameters:

func (collections.abc.Callable[ ..., collections.abc.Awaitable[ dict[ str, typing_extensions.Any ] ] ])

Return type:

collections.abc.Callable[ …, collections.abc.Awaitable[ dict[ str, typing_extensions.Any ] ] ]

async librovore.server.serve(auxdata, /, *, port=0, transport='stdio', extra_functions=False)

Runs MCP server.

Parameters:

  • auxdata (librovore.state.Globals)

  • port (int)

  • transport (str)

  • extra_functions (bool)

Module librovore.exceptions

Family of exceptions for package API.

exception librovore.exceptions.ContentExtractFailure(processor_name, source, meaningful_results, requested_objects)

Bases: StructureProcessFailure

Failed to extract meaningful content from documentation.

exception librovore.exceptions.ContentIdInvalidity(content_id, cause)

Bases: Omnierror, ValueError

Content ID has invalid format or encoding.

render_as_json()

Renders content ID invalidity as JSON-compatible dictionary.

Parameters:

self

Return type:

frigid.dictionaries.Dictionary[ str, typing_extensions.Any ]

render_as_markdown(*, reveal_internals=True)

Renders content ID invalidity as Markdown lines for display.

Parameters:

  • self

  • reveal_internals (bool)

Return type:

tuple[ str, … ]

exception librovore.exceptions.ContentIdLocationMismatch(content_id_location, term_location)

Bases: Omnierror, ValueError

Content ID location does not match term query location.

render_as_json()

Renders content ID location mismatch as JSON-compatible dict.

Parameters:

self

Return type:

frigid.dictionaries.Dictionary[ str, typing_extensions.Any ]

render_as_markdown(*, reveal_internals=True)

Renders content ID location mismatch as Markdown lines.

Parameters:

  • self

  • reveal_internals (bool)

Return type:

tuple[ str, … ]

exception librovore.exceptions.ContentIdObjectAbsence(object_name, location)

Bases: Omnierror, ValueError

Object specified in content ID not found in location.

render_as_json()

Renders content ID object absence as JSON-compatible dict.

Parameters:

self

Return type:

frigid.dictionaries.Dictionary[ str, typing_extensions.Any ]

render_as_markdown(*, reveal_internals=True)

Renders content ID object absence as Markdown lines.

Parameters:

  • self

  • reveal_internals (bool)

Return type:

tuple[ str, … ]

exception librovore.exceptions.DetectionConfidenceInvalidity(confidence)

Bases: Omnierror, ValueError

Detection confidence value is out of valid range.

exception librovore.exceptions.DocumentationContentAbsence(url)

Bases: Omnierror, ValueError

Documentation main content container not found.

exception librovore.exceptions.DocumentationInaccessibility(url, cause)

Bases: Omnierror, RuntimeError

Documentation file or resource absent or inaccessible.

exception librovore.exceptions.DocumentationObjectAbsence(object_id, url)

Bases: Omnierror, ValueError

Requested object not found in documentation page.

exception librovore.exceptions.DocumentationParseFailure(url, cause)

Bases: Omnierror, ValueError

Documentation HTML parsing failed or content malformed.

exception librovore.exceptions.ExtensionCacheFailure(cache_path, message)

Bases: Omnierror, RuntimeError

Extension cache operation failed.

exception librovore.exceptions.ExtensionConfigurationInvalidity(extension_name, message)

Bases: Omnierror, ValueError

Extension configuration is invalid.

exception librovore.exceptions.ExtensionInstallFailure(package_spec, message)

Bases: Omnierror, RuntimeError

Extension package installation failed.

exception librovore.exceptions.ExtensionRegisterFailure(message)

Bases: Omnierror, TypeError

Invalid plugin could not be registered.

exception librovore.exceptions.ExtensionVersionConflict(package_name, required, available)

Bases: Omnierror, ImportError

Extension has incompatible version requirements.

exception librovore.exceptions.HttpContentTypeInvalidity(url, content_type, operation)

Bases: Omnierror, ValueError

HTTP content type is not suitable for requested operation.

exception librovore.exceptions.InventoryFilterInvalidity(message)

Bases: Omnierror, ValueError

Inventory filter is invalid.

exception librovore.exceptions.InventoryInaccessibility(source, cause=None)

Bases: Omnierror, RuntimeError

Inventory file or resource absent or inaccessible.

render_as_json()

Renders inventory inaccessibility as JSON-compatible dict.

Parameters:

self

Return type:

frigid.dictionaries.Dictionary[ str, typing_extensions.Any ]

render_as_markdown(*, reveal_internals=True)

Renders inventory inaccessibility as Markdown lines.

Parameters:

  • self

  • reveal_internals (bool)

Return type:

tuple[ str, … ]

exception librovore.exceptions.InventoryInvalidity(source, cause)

Bases: Omnierror, ValueError

Inventory has invalid format or cannot be parsed.

render_as_json()

Renders inventory invalidity as JSON-compatible dict.

Parameters:

self

Return type:

frigid.dictionaries.Dictionary[ str, typing_extensions.Any ]

render_as_markdown(*, reveal_internals=True)

Renders inventory invalidity as Markdown lines.

Parameters:

  • self

  • reveal_internals (bool)

Return type:

tuple[ str, … ]

exception librovore.exceptions.InventoryUrlInvalidity(source)

Bases: Omnierror, ValueError

Inventory URL is malformed or invalid.

exception librovore.exceptions.InventoryUrlNoSupport(url, component, value=absence.absent)

Bases: Omnierror, NotImplementedError

Inventory URL has unsupported component.

exception librovore.exceptions.Omnierror(*posargs, **nomargs)

Bases: Omniexception, Exception

Base for error exceptions with self-rendering capability.

abstract render_as_json()

Renders exception as JSON-compatible dictionary.

Parameters:

self

Return type:

frigid.dictionaries.Dictionary[ str, typing_extensions.Any ]

abstract render_as_markdown(*, reveal_internals=True)

Renders exception as Markdown lines for display.

Parameters:

  • self

  • reveal_internals (bool) – Controls whether implementation-specific details (internal field names, version numbers, priority scores) are included. When False, only user-facing information is shown.

Return type:

tuple[ str, … ]

exception librovore.exceptions.Omniexception(*posargs, **nomargs)

Bases: Object, BaseException

Base for all exceptions raised by package API.

exception librovore.exceptions.ProcessorGenusInvalidity(genus)

Bases: Omnierror, ValueError

Invalid processor genus provided.

exception librovore.exceptions.ProcessorInavailability(source, genus=absence.absent)

Bases: Omnierror, RuntimeError

No processor found to handle source.

render_as_json()

Renders processor unavailability as JSON-compatible dictionary.

Parameters:

self

Return type:

frigid.dictionaries.Dictionary[ str, typing_extensions.Any ]

render_as_markdown(*, reveal_internals=True)

Renders processor unavailability as Markdown lines for display.

Parameters:

  • self

  • reveal_internals (bool)

Return type:

tuple[ str, … ]

exception librovore.exceptions.ProcessorInvalidity(expected, actual)

Bases: Omnierror, TypeError

Processor has wrong type.

exception librovore.exceptions.StructureIncompatibility(processor_name, source)

Bases: Omnierror, ValueError

Documentation structure incompatible with processor.

exception librovore.exceptions.StructureProcessFailure(processor_name, source, cause)

Bases: Omnierror, RuntimeError

Structure processor failed to complete processing.

exception librovore.exceptions.ThemeDetectFailure(processor_name, source, theme_error)

Bases: StructureProcessFailure

Theme detection failed during processing.

exception librovore.exceptions.UrlImpermissibility(url, user_agent)

Bases: Omnierror, PermissionError

URL access blocked by robots.txt directive.