rag.core.catalog

Paper catalog and corpus-vs-paper query routing.

Attributes

CATALOG_FILE_NAME
TITLE_SNIPPET_CHARS

Classes

QueryScope	Whether a question is about one paper or the whole corpus.
CatalogJsonKey	Keys in the on-disk catalog JSON object.
PaperCatalogEntry	One PDF in the corpus catalog.
PaperCatalog	Ordered catalog of ingested papers.

Functions

classify_query_scope(→ QueryScope)	Classify a user question as paper-level or corpus-level.
title_from_text(→ str)	Collapse whitespace and truncate opening text for the catalog.
catalog_from_documents(→ PaperCatalog)	Build a catalog keyed by PDF path, using first-page text when present.
catalog_path(→ pathlib.Path)	Return the catalog JSON path under the Chroma directory.
write_paper_catalog(→ pathlib.Path)	Write catalog.json next to the Chroma store.
load_paper_catalog(→ PaperCatalog)	Load the catalog from disk, or filenames from papers_dir.

Module Contents

rag.core.catalog.CATALOG_FILE_NAME: Final = 'catalog.json'

rag.core.catalog.TITLE_SNIPPET_CHARS: Final = 220

class rag.core.catalog.QueryScope

Bases: enum.StrEnum

Whether a question is about one paper or the whole corpus.

PAPER = 'paper'

CORPUS = 'corpus'

class rag.core.catalog.CatalogJsonKey

Bases: enum.StrEnum

Keys in the on-disk catalog JSON object.

PAPERS = 'papers'

FILE_NAME = 'file_name'

TITLE = 'title'

class rag.core.catalog.PaperCatalogEntry

One PDF in the corpus catalog.

Variables:

• file_name (str) – PDF basename.

• title (str) – Opening-page snippet used as a title stand-in.

file_name: str

title: str

class rag.core.catalog.PaperCatalog

Ordered catalog of ingested papers.

Variables:

papers (tuple of PaperCatalogEntry) – One entry per PDF, typically ingest order.

papers: tuple[PaperCatalogEntry, Ellipsis]

to_markdown() → str

Render the catalog as a markdown bullet list.

to_json() → str

Serialize the catalog to a JSON string.

classmethod from_json(raw: str) → PaperCatalog

Parse a catalog JSON string.

Parameters:

raw (str) – JSON produced by to_json.

Returns:

Parsed catalog (empty when papers is missing).

Return type:

PaperCatalog

rag.core.catalog.classify_query_scope(*, question: str) → QueryScope

Classify a user question as paper-level or corpus-level.

Parameters:

question (str) – Natural-language question.

Returns:

CORPUS when the question is about the whole library.

Return type:

QueryScope

rag.core.catalog.title_from_text(*, text: str) → str

Collapse whitespace and truncate opening text for the catalog.

Parameters:

text (str) – First extractable page (or any snippet).

Returns:

Short title stand-in.

Return type:

str

rag.core.catalog.catalog_from_documents(*, pdf_paths: collections.abc.Sequence[pathlib.Path], documents: collections.abc.Sequence[Any]) → PaperCatalog

Build a catalog keyed by PDF path, using first-page text when present.

Parameters:

• pdf_paths (sequence of Path) – Source PDFs (defines order and completeness).

• documents (sequence) – Page-like objects with file_name metadata and text.

Returns:

One entry per PDF path.

Return type:

PaperCatalog

rag.core.catalog.catalog_path(*, chroma_dir: pathlib.Path) → pathlib.Path

Return the catalog JSON path under the Chroma directory.

Parameters:

chroma_dir (Path) – Persistence directory.

Returns:

chroma_dir / catalog.json.

Return type:

Path

rag.core.catalog.write_paper_catalog(*, catalog: PaperCatalog, chroma_dir: pathlib.Path) → pathlib.Path

Write catalog.json next to the Chroma store.

Parameters:

• catalog (PaperCatalog) – Catalog to persist.

• chroma_dir (Path) – Persistence directory (created if missing).

Returns:

Path written.

Return type:

Path

rag.core.catalog.load_paper_catalog(*, config: rag.core.config.RagConfig) → PaperCatalog

Load the catalog from disk, or filenames from papers_dir.

Parameters:

config (RagConfig) – Provides chroma_dir and papers_dir.

Returns:

Persisted catalog, or a filenames-only fallback.

Return type:

PaperCatalog