catena/crates/bindings/python/catena/__init__.pyi

from typing import Any, Iterable, Mapping, Sequence

__version__: str

def chunk_markdown(
    markdown: str,
    *,
    target: int | None = ...,
    overlap: int | None = ...,
    min_tokens: int | None = ...,
    hard_max: int | None = ...,
) -> list[dict[str, Any]]: ...
def scrub(markdown: str, *, pages: bool = ...) -> str: ...
def count_tokens(text: str) -> int: ...
def parse_subtitles(
    content: str, *, keep_repeats: bool = ...
) -> list[dict[str, Any]]: ...
def pack_cues(
    cues: Iterable[Mapping[str, Any]],
    *,
    seconds: float | None = ...,
    max_tokens: int | None = ...,
) -> list[dict[str, Any]]: ...
def segment_cues(
    cues: Iterable[Mapping[str, Any]],
    *,
    duration: float | None = ...,
    embeddings: Sequence[Sequence[float]] | None = ...,
) -> list[dict[str, Any]]: ...
def cue_windows(cues: Iterable[Mapping[str, Any]]) -> list[str]: ...
def split_collection(markdown: str) -> list[dict[str, Any]]: ...
def fuse_hits(
    hits: Iterable[Mapping[str, Any]],
    *,
    k: float | None = ...,
    weights: Mapping[str, float] | None = ...,
    limit: int | None = ...,
) -> list[dict[str, Any]]: ...
def identify(name: str, data: bytes) -> dict[str, Any]: ...
def find_citations(text: str) -> list[dict[str, Any]]: ...
def looks_like_footnote_citations(text: str) -> bool: ...
def canonical_subject(
    scheme: Mapping[str, Any], name: str
) -> str | None: ...
def compose_subjects(
    scheme: Mapping[str, Any],
    subjects: Iterable[str],
    title: str | None = ...,
) -> list[str]: ...
def needs_subject(
    scheme: Mapping[str, Any], existing: Iterable[str]
) -> bool: ...
def suggest_author(
    title: str, front_matter: str | None = ...
) -> dict[str, Any] | None: ...
def citation_prompt(references: Iterable[Mapping[str, Any]]) -> str | None: ...
def merge_citation_reply(
    references: Iterable[Mapping[str, Any]], reply: str
) -> list[dict[str, Any]]: ...
def parse_identifier(text: str) -> dict[str, Any] | None: ...
def series_of(
    title: str, author: str | None = ...
) -> dict[str, Any] | None: ...
def clean_record(book: Mapping[str, Any]) -> dict[str, Any]: ...
def record_problems(
    title: str | None = ..., author: str | None = ..., isbn: str | None = ...
) -> list[str]: ...
def record_severity(reasons: Iterable[str]) -> int: ...
def title_in_author(title: str | None = ..., author: str | None = ...) -> bool: ...
def looks_like_person(author: str) -> bool: ...
def is_shouting(title: str) -> bool: ...
def title_case(title: str) -> str: ...
def clean_underscores(title: str) -> str: ...
def valid_isbn(text: str) -> bool: ...
def isbn_from_text(text: str) -> str | None: ...
def isbn_from_filename(name: str) -> str | None: ...
def same_work(ours: str, theirs: str) -> bool: ...

def read_colophon(
    text: str, pages: int = ..., shelf: str | None = ...
) -> dict[str, Any]:
    """What a book prints about itself in its opening pages.

    `shelf` is a closed list of headings to file the printed subjects onto,
    one per line, optionally `Heading = term, term`.
    """
    ...

def shelve(shelf: str, subjects: list[str]) -> tuple[list[str], list[str]]:
    """File subject headings onto a shelf. Returns (shelved, unshelved)."""
    ...

def fetch_identifier(
    id: str,
    kind: str = ...,
    polite: str | None = ...,
    timeout: int = ...,
    attempts: int = ...,
) -> dict[str, Any] | None:
    """Ask the register that assigns an identifier what it knows about one.

    Blocks on the network. `None` when no register answers about that kind.
    """
    ...

class Limited(Exception):
    """A register refused because it has been asked too often; ask again later."""

def fetch_cover(
    isbn: str,
    cover_id: int | None = ...,
    size: str = ...,
    polite: str | None = ...,
    timeout: int = ...,
    deadline: int = ...,
) -> dict[str, Any] | None:
    """The cover Open Library has for a book, by ISBN, then by cover id.

    A dict with `bytes`, `media_type`, `extension`, `source` and `url`, or
    `None` when there is none. Raises `Limited` when Open Library refused for
    being asked too often. Blocks on the network.
    """
    ...

def search_title(
    title: str,
    author: str | None = ...,
    limit: int = ...,
    polite: str | None = ...,
    timeout: int = ...,
    attempts: int = ...,
) -> list[dict[str, Any]]:
    """The editions the registers list for a title and author, in their order.

    Records shaped like `fetch_identifier`'s. Use `same_work` to decide which
    one is the book. Blocks on the network.
    """
    ...

def colophon_prompt(
    record: dict[str, Any], text: str, pages: int = ...
) -> str | None:
    """The question to put to a model about what the pages did not settle.

    None when the pages settled everything. Nothing is sent anywhere.
    """
    ...

def merge_colophon(
    record: dict[str, Any], reply: str
) -> tuple[dict[str, Any], int]:
    """A model's reply folded in. Returns (record, fields_settled).

    Only fills what the pages left unsettled; a model never overwrites what a
    book printed about itself.
    """
    ...