API Reference

This page covers the interface of Sci-Fi-Parser defined in sci_fi_parser.api.

Public parsing API for running the Sci-Fi-Parser pipeline.

This module exposes a convenience function for parsing a folder of PDFs and a result object for accessing the parsed image and PDF sets, saving outputs, and loading benchmark-friendly data frames.

class sci_fi_parser.api.ParseResult(image_set: ImageSet, pdf_set: PdfSet, output_dir: str | Path | None = None)

Bases: object

Represents the result of one parsing run.

charts_dataframe() → DataFrame

Load charts.parquet as a DataFrame.

Returns:

A DataFrame loaded from tables/charts.parquet.

property images: ImageSet

Return the parsed images and associated metadata.

property output_dir: Path | None

Return the saved output directory, if one has been set.

property pdfs: PdfSet

Return the parsed PDFs and associated metadata.

points_dataframe() → DataFrame

Load points.parquet as a DataFrame.

Returns:

A DataFrame loaded from tables/points.parquet.

save(output_dir: str | Path) → None

Save the parsed dataset as JSONL and Parquet.

Parameters:

output_dir – Directory where the parsed dataset will be written.

series_dataframe() → DataFrame

Load series.parquet as a DataFrame.

Returns:

A DataFrame loaded from tables/series.parquet.

summary() → dict

Return a compact summary of the parsed dataset.

Returns:

A dictionary containing PDF and image counts.

sci_fi_parser.api.parse_folder(input_dir: str | Path, *, output_dir: str | Path | None = None, extracted_image_dir: str | Path = PosixPath('/home/docs/checkouts/readthedocs.org/user_builds/sci-fi-parser/checkouts/stable/temp/extracted_images'), vlm_config: str | Path = PosixPath('/home/docs/checkouts/readthedocs.org/user_builds/sci-fi-parser/checkouts/stable/src/sci_fi_parser/config/vlm.toml'), classify: bool = True, ocr: bool = True, vlm: bool = True) → ParseResult

Parse all PDFs inside a folder.

Parameters:

• input_dir – Folder containing PDF files.

• output_dir – If provided, save JSONL and Parquet outputs.

• extracted_image_dir – Temporary folder used during image extraction.

• vlm_config – Path to the VLM configuration file.

• classify – Whether to run chart classification.

• ocr – Whether to run OCR.

• vlm – Whether to run VLM extraction.

Returns:

A parse result containing the populated image and PDF sets.

VLM configuration helpers live in sci_fi_parser.vlm.vlm_config.

VLM endpoint configuration and its loading from .toml files.

class sci_fi_parser.vlm.vlm_config.VLMProfile(model: str = 'qwen2.5vl:7b', prompt: str = 'Extract the data from this chart.\nRules:\n- chart_type: one of vertical_bar, grouped_bar, stacked_bar, horizontal_bar, line, scatter, dot, none\n- log_scale: true if the chart is on the log scale, else false.\n- Use the x-axis category labels EXACTLY as printed. Do not invent dates, years, or names.\n- Series naming: if there is a legend, use the legend labels. If there is NO legend (single-series chart), use the y-axis title as the series name. Never leave the name blank.\n- Read each y-value from the y-axis scale and the bar / marker height. If numeric labels are printed on the bars, prefer those.\n- Watch y-axis units: \'200K\' = 200000, \'1.5M\' = 1500000, \'2.3B\' = 2300000000. Return plain numbers, no suffixes, no extra zeros.\n- Do not output series, categories, or values that do not appear on the chart. If the image is not a chart, set chart_type to "none" and series to an empty list.', base_url: str = 'http://localhost:11434', api_key: str = 'sk-no-key')

Bases: object

Connection and prompt settings for a VLM endpoint.

Defaults target a local Ollama instance.

model

Name of the model to request.

Type:

str

prompt

Prompt sent with each extraction request.

Type:

str

base_url

Base URL of the OpenAI-compatible endpoint.

Type:

str

api_key

API key for the endpoint; a dummy value if none is required.

Type:

str

sci_fi_parser.vlm.vlm_config.load_profile(path: Path) → VLMProfile

Loads a VLMProfile from a .toml file.

Keys missing from the file keep their VLMProfile defaults.

Parameters:

path – Path to the config .toml file.

Returns:

A VLMProfile with the loaded settings.

Raises:

ValueError – If the file contains keys that are not VLMProfile fields.