Initial Build

.env.example

@@ -0,0 +1,6 @@
+GRANITE_MODEL_ID=ibm-granite/granite-docling-258M
+SUMMARIZER_MODEL_ID=google/pegasus-x-base-arxiv
+ENABLE_PEGASUS=1
+ENABLE_KOKORO=1
+MAX_AUDIO_CHARS=12000
+OUTPUT_DIR=outputs

.github/workflows/tests.yml

@@ -0,0 +1,20 @@
+name: tests
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Install lightweight test dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install pytest numpy
+      - name: Run tests that do not download models
+        run: pytest

.gitignore

@@ -0,0 +1,11 @@
+.venv/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+.env
+outputs/*
+!outputs/.gitkeep
+.huggingface/
+.DS_Store
+.vscode/settings.json

Dockerfile

@@ -0,0 +1,21 @@
+FROM python:3.11-slim
+
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1 \
+    GRADIO_SERVER_NAME=0.0.0.0 \
+    GRADIO_SERVER_PORT=7860
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    espeak-ng \
+    libsndfile1 \
+    git \
+    && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /app
+COPY requirements.txt .
+RUN pip install --no-cache-dir --upgrade pip && \
+    pip install --no-cache-dir -r requirements.txt
+
+COPY . .
+EXPOSE 7860
+CMD ["python", "app.py"]

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

app.py

@@ -0,0 +1,170 @@
+from __future__ import annotations
+
+import traceback
+
+import gradio as gr
+
+from src.pipeline import (
+    audio_from_state,
+    narration_from_state,
+    process_paper,
+    summarize_state,
+)
+from src.sections import section_table
+
+try:
+    import spaces
+
+    gpu_task = spaces.GPU
+except ImportError:
+    def gpu_task(function):
+        return function
+
+
+def _friendly_error(exc: Exception) -> str:
+    return f"{type(exc).__name__}: {exc}"
+
+
+@gpu_task
+def handle_process(uploaded_file, source_text, parser_label, page_limit):
+    try:
+        parser_mode = "granite" if parser_label.startswith("Granite") else "standard"
+        paper = process_paper(
+            uploaded_file=uploaded_file,
+            source_text=source_text,
+            parser_mode=parser_mode,
+            page_limit=int(page_limit),
+        )
+        state = paper.to_state()
+        metadata = paper.metadata
+        status = (
+            f"Processed with **{paper.parser_mode}** mode in "
+            f"**{metadata['conversion_seconds']} seconds**. "
+            f"Extracted **{metadata['word_count']} words** across "
+            f"**{metadata['section_count']} sections**."
+        )
+        return state, paper.markdown, section_table(paper.sections), status
+    except Exception as exc:  # Gradio callback boundary
+        traceback.print_exc()
+        return {}, "", [], f"Processing failed: {_friendly_error(exc)}"
+
+
+@gpu_task
+def handle_summary(state, technicality_label, summarizer_label):
+    try:
+        technicality = technicality_label.lower()
+        mode = "pegasus" if summarizer_label.startswith("PEGASUS") else "extractive"
+        state, summary = summarize_state(state or {}, technicality, mode)
+        return state, summary, f"Summary generated with **{mode}** mode."
+    except Exception as exc:
+        traceback.print_exc()
+        return state or {}, "", f"Summary failed: {_friendly_error(exc)}"
+
+
+def handle_narration(state):
+    try:
+        state, narration = narration_from_state(state or {})
+        return state, narration, "Narration script prepared."
+    except Exception as exc:
+        traceback.print_exc()
+        return state or {}, "", f"Narration failed: {_friendly_error(exc)}"
+
+
+@gpu_task
+def handle_audio(state, voice, speed):
+    try:
+        path = audio_from_state(state or {}, voice=voice, speed=float(speed))
+        return path, "Audio generated with Kokoro-82M."
+    except Exception as exc:
+        traceback.print_exc()
+        return None, f"Audio failed: {_friendly_error(exc)}"
+
+
+
+with gr.Blocks(title="PaperCast") as demo:
+    state = gr.State({})
+    gr.Markdown(
+        "# PaperCast \n"
+        "Convert scientific PDFs with Granite-Docling, summarize them, and generate an audio briefing."
+    )
+
+    with gr.Tab("1. Process paper"):
+        with gr.Row():
+            uploaded_file = gr.File(label="Upload a PDF", file_types=[".pdf"], type="filepath")
+            source_text = gr.Textbox(
+                label="Or enter an arXiv ID / PDF URL",
+                placeholder="2501.17887 or https://arxiv.org/pdf/2501.17887",
+            )
+        with gr.Row():
+            parser_label = gr.Radio(
+                ["Granite VLM", "Standard Docling"],
+                value="Granite VLM",
+                label="Parser",
+            )
+            page_limit = gr.Slider(1, 12, value=3, step=1, label="Pages to process")
+        process_button = gr.Button("Process paper", variant="primary")
+        process_status = gr.Markdown()
+        with gr.Row():
+            markdown_output = gr.Markdown(label="Structured output")
+            section_output = gr.Dataframe(
+                headers=["#", "Level", "Section", "Words"],
+                datatype=["number", "number", "str", "number"],
+                interactive=False,
+                label="Detected sections",
+            )
+        process_button.click(
+            handle_process,
+            inputs=[uploaded_file, source_text, parser_label, page_limit],
+            outputs=[state, markdown_output, section_output, process_status],
+        )
+
+    with gr.Tab("2. Summarize"):
+        with gr.Row():
+            technicality = gr.Radio(
+                ["Overview", "Intermediate", "Technical"],
+                value="Intermediate",
+                label="Technicality",
+            )
+            summarizer_label = gr.Radio(
+                ["Extractive baseline (fast)", "PEGASUS-X"],
+                value="Extractive baseline (fast)",
+                label="Summarizer",
+            )
+        summary_button = gr.Button("Generate summary", variant="primary")
+        summary_status = gr.Markdown()
+        summary_output = gr.Textbox(label="Summary", lines=18)
+        summary_button.click(
+            handle_summary,
+            inputs=[state, technicality, summarizer_label],
+            outputs=[state, summary_output, summary_status],
+        )
+
+    with gr.Tab("3. Audio"):
+        narration_button = gr.Button("Prepare narration script")
+        narration_status = gr.Markdown()
+        narration_output = gr.Textbox(label="Speech-friendly script", lines=15)
+        narration_button.click(
+            handle_narration,
+            inputs=[state],
+            outputs=[state, narration_output, narration_status],
+        )
+
+        with gr.Row():
+            voice = gr.Dropdown(
+                ["af_heart", "af_bella", "am_adam", "am_michael"],
+                value="af_heart",
+                label="Kokoro voice",
+            )
+            speed = gr.Slider(0.8, 1.25, value=1.0, step=0.05, label="Speech speed")
+        audio_button = gr.Button("Generate audio", variant="primary")
+        audio_status = gr.Markdown()
+        audio_output = gr.Audio(label="PaperCast audio", type="filepath")
+        audio_button.click(
+            handle_audio,
+            inputs=[state, voice, speed],
+            outputs=[audio_output, audio_status],
+        )
+
+
+if __name__ == "__main__":
+    demo.queue().launch()

packages.txt

@@ -0,0 +1,2 @@
+espeak-ng
+libsndfile1

pyproject.toml

@@ -0,0 +1,10 @@
+[tool.pytest.ini_options]
+pythonpath = ["."]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]

requirements-dev.txt

@@ -0,0 +1,3 @@
+-r requirements.txt
+pytest>=8,<10
+ruff>=0.9,<1

requirements.txt

@@ -0,0 +1,19 @@
+# Application and UI
+gradio>=5.0,<7
+
+# Document AI and model inference
+docling>=2.115,<3
+transformers>=4.51,<5
+torch>=2.8,<3
+accelerate>=1.0,<2
+sentencepiece>=0.2,<1
+protobuf>=5,<7
+
+# Text-to-speech
+kokoro>=0.9.2,<1
+soundfile>=0.12,<1
+numpy>=1.26,<3
+
+# Utilities
+huggingface_hub>=0.34,<2
+requests>=2.32,<3

scripts/smoke_test.py

@@ -0,0 +1,32 @@
+"""Small local smoke test that does not download neural models."""
+
+from pathlib import Path
+import sys
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+
+from src.narration import prepare_narration
+from src.sections import split_markdown_sections
+from src.sources import normalize_arxiv_reference
+from src.summarization import extractive_summary
+
+sample = """
+# Abstract
+We introduce a document-understanding system for scientific papers. The system preserves formulas and structure.
+
+# Method
+A multimodal transformer converts document-page images into structured tokens. A sequence-to-sequence transformer then summarizes selected sections.
+
+# Conclusion
+The combined pipeline produces text suitable for a neural text-to-speech model.
+"""
+
+sections = split_markdown_sections(sample)
+summary = extractive_summary(sections, "overview")
+narration = prepare_narration(summary, "overview")
+
+assert normalize_arxiv_reference("2501.17887")
+assert sections
+assert summary
+assert narration
+print("Smoke test passed.")

src/__init__.py

@@ -0,0 +1 @@
+"""PaperCast core package."""

src/config.py

@@ -0,0 +1,28 @@
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass(frozen=True, slots=True)
+class Settings:
+    app_name: str = "PaperCast"
+    granite_model_id: str = os.getenv(
+        "GRANITE_MODEL_ID", "ibm-granite/granite-docling-258M"
+    )
+    summarizer_model_id: str = os.getenv(
+        "SUMMARIZER_MODEL_ID", "google/pegasus-x-base-arxiv"
+    )
+
+    summarizer_tokenizer_id: str = os.getenv(
+    "SUMMARIZER_TOKENIZER_ID", "google/pegasus-x-base"
+)
+    output_dir: Path = Path(os.getenv("OUTPUT_DIR", "outputs"))
+    max_audio_chars: int = int(os.getenv("MAX_AUDIO_CHARS", "12000"))
+    enable_pegasus: bool = os.getenv("ENABLE_PEGASUS", "1") == "1"
+    enable_kokoro: bool = os.getenv("ENABLE_KOKORO", "1") == "1"
+
+
+SETTINGS = Settings()
+SETTINGS.output_dir.mkdir(parents=True, exist_ok=True)

src/models.py

@@ -0,0 +1,42 @@
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass, field
+from typing import Any
+
+
+@dataclass(slots=True)
+class Section:
+    """A Markdown section extracted from a converted paper."""
+
+    title: str
+    level: int
+    content: str
+
+    @property
+    def word_count(self) -> int:
+        return len(self.content.split())
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+
+@dataclass(slots=True)
+class PaperDocument:
+    """Application-friendly representation of a processed paper."""
+
+    source: str
+    parser_mode: str
+    markdown: str
+    sections: list[Section] = field(default_factory=list)
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    def to_state(self) -> dict[str, Any]:
+        return {
+            "source": self.source,
+            "parser_mode": self.parser_mode,
+            "markdown": self.markdown,
+            "sections": [section.to_dict() for section in self.sections],
+            "metadata": self.metadata,
+            "summary": "",
+            "narration": "",
+        }

src/narration.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+import re
+
+_MARKDOWN_LINK = re.compile(r"\[([^\]]+)\]\([^\)]+\)")
+_INLINE_CODE = re.compile(r"`([^`]+)`")
+_HEADING = re.compile(r"^#{1,6}\s*", re.MULTILINE)
+_LATEX_BLOCK = re.compile(r"\$\$(.+?)\$\$", re.DOTALL)
+_LATEX_INLINE = re.compile(r"(?<!\$)\$(?!\$)(.+?)(?<!\$)\$(?!\$)")
+
+
+def _verbalize_math(match: re.Match[str]) -> str:
+    expression = " ".join(match.group(1).split())
+    expression = expression.replace("\\", " ")
+    expression = expression.replace("_", " sub ").replace("^", " to the power of ")
+    expression = expression.replace("{", " ").replace("}", " ")
+    return f" The paper gives the mathematical expression: {expression}. "
+
+
+def prepare_narration(summary: str, technicality: str) -> str:
+    """Convert a written summary into a speech-friendly script.
+
+    This first version performs deterministic NLP cleanup. A later milestone can
+    add a generative 'explain this equation conceptually' model.
+    """
+
+    cleaned = _MARKDOWN_LINK.sub(r"\1", summary)
+    cleaned = _INLINE_CODE.sub(r"\1", cleaned)
+    cleaned = _HEADING.sub("", cleaned)
+    cleaned = _LATEX_BLOCK.sub(_verbalize_math, cleaned)
+    cleaned = _LATEX_INLINE.sub(_verbalize_math, cleaned)
+    cleaned = cleaned.replace("*", "").replace("#", "")
+    cleaned = re.sub(r"\s+", " ", cleaned).strip()
+
+    intros = {
+        "overview": "Here is a concise overview of the paper. ",
+        "intermediate": "Here is an explanatory walkthrough of the paper. ",
+        "technical": "Here is a technical briefing on the paper. ",
+    }
+    outro = " That concludes the PaperCast briefing."
+    return intros.get(technicality, intros["intermediate"]) + cleaned + outro

src/parsing.py

@@ -0,0 +1,85 @@
+from __future__ import annotations
+
+import time
+from functools import lru_cache
+from pathlib import Path
+from typing import Literal
+
+from .models import PaperDocument
+from .sections import split_markdown_sections
+
+ParserMode = Literal["standard", "granite"]
+
+
+@lru_cache(maxsize=1)
+def _standard_converter():
+    from docling.document_converter import DocumentConverter
+
+    return DocumentConverter()
+
+
+@lru_cache(maxsize=1)
+def _granite_converter():
+    from docling.datamodel import vlm_model_specs
+    from docling.datamodel.base_models import InputFormat
+    from docling.datamodel.pipeline_options import VlmPipelineOptions
+    from docling.document_converter import DocumentConverter, PdfFormatOption
+    from docling.pipeline.vlm_pipeline import VlmPipeline
+
+    pipeline_options = VlmPipelineOptions(
+        vlm_options=vlm_model_specs.GRANITEDOCLING_TRANSFORMERS,
+    )
+    return DocumentConverter(
+        format_options={
+            InputFormat.PDF: PdfFormatOption(
+                pipeline_cls=VlmPipeline,
+                pipeline_options=pipeline_options,
+            )
+        }
+    )
+
+
+def parse_document(
+    source: str,
+    parser_mode: ParserMode = "granite",
+    page_limit: int = 3,
+) -> PaperDocument:
+    """Convert a PDF/URL into structured Markdown with Docling.
+
+    Granite mode is the multimodal transformer path. Standard mode is a faster
+    fallback and a useful baseline for later extraction-quality comparisons.
+    """
+
+    if parser_mode not in {"standard", "granite"}:
+        raise ValueError(f"Unknown parser mode: {parser_mode}")
+    if page_limit < 1:
+        raise ValueError("page_limit must be at least 1")
+
+    converter = _granite_converter() if parser_mode == "granite" else _standard_converter()
+
+    started = time.perf_counter()
+    result = converter.convert(
+        source=source,
+        page_range=(1, page_limit),
+        raises_on_error=True,
+    )
+    elapsed = time.perf_counter() - started
+    markdown = result.document.export_to_markdown()
+    sections = split_markdown_sections(markdown)
+
+    filename = Path(source).name if not source.startswith("http") else source
+    metadata = {
+        "display_name": filename,
+        "pages_requested": page_limit,
+        "conversion_seconds": round(elapsed, 2),
+        "section_count": len(sections),
+        "word_count": len(markdown.split()),
+        "formula_markers": markdown.count("$$") + markdown.count("\\[") + markdown.count("\\("),
+    }
+    return PaperDocument(
+        source=source,
+        parser_mode=parser_mode,
+        markdown=markdown,
+        sections=sections,
+        metadata=metadata,
+    )

src/pipeline.py

@@ -0,0 +1,52 @@
+from __future__ import annotations
+
+from .models import PaperDocument, Section
+from .narration import prepare_narration
+from .parsing import parse_document
+from .sources import resolve_source
+from .summarization import summarize
+from .tts import generate_audio
+
+
+def process_paper(
+    uploaded_file: str | None,
+    source_text: str | None,
+    parser_mode: str,
+    page_limit: int,
+) -> PaperDocument:
+    source = resolve_source(uploaded_file, source_text)
+    return parse_document(source, parser_mode=parser_mode, page_limit=page_limit)
+
+
+def sections_from_state(state: dict) -> list[Section]:
+    return [Section(**item) for item in state.get("sections", [])]
+
+
+def summarize_state(state: dict, technicality: str, mode: str) -> tuple[dict, str]:
+    sections = sections_from_state(state)
+    if not sections:
+        raise ValueError("Process a paper before generating a summary.")
+    summary = summarize(sections, technicality=technicality, mode=mode)
+    updated = dict(state)
+    updated["summary"] = summary
+    updated["technicality"] = technicality
+    updated["summarizer_mode"] = mode
+    return updated, summary
+
+
+def narration_from_state(state: dict) -> tuple[dict, str]:
+    summary = state.get("summary", "").strip()
+    if not summary:
+        raise ValueError("Generate a summary before preparing narration.")
+    technicality = state.get("technicality", "intermediate")
+    narration = prepare_narration(summary, technicality)
+    updated = dict(state)
+    updated["narration"] = narration
+    return updated, narration
+
+
+def audio_from_state(state: dict, voice: str, speed: float) -> str:
+    narration = state.get("narration", "").strip()
+    if not narration:
+        raise ValueError("Prepare narration before generating audio.")
+    return str(generate_audio(narration, voice=voice, speed=speed))

src/sections.py

@@ -0,0 +1,42 @@
+from __future__ import annotations
+
+import re
+
+from .models import Section
+
+_HEADING = re.compile(r"^(#{1,6})\s+(.+?)\s*$")
+
+
+def split_markdown_sections(markdown: str) -> list[Section]:
+    """Split Markdown into heading-aware sections while preserving source order."""
+
+    lines = markdown.splitlines()
+    sections: list[Section] = []
+    current_title = "Document opening"
+    current_level = 1
+    current_lines: list[str] = []
+
+    def flush() -> None:
+        nonlocal current_lines
+        content = "\n".join(current_lines).strip()
+        if content:
+            sections.append(
+                Section(title=current_title, level=current_level, content=content)
+            )
+        current_lines = []
+
+    for line in lines:
+        heading = _HEADING.match(line)
+        if heading:
+            flush()
+            current_level = len(heading.group(1))
+            current_title = heading.group(2).strip()
+        else:
+            current_lines.append(line)
+
+    flush()
+    return sections
+
+
+def section_table(sections: list[Section]) -> list[list[object]]:
+    return [[index + 1, item.level, item.title, item.word_count] for index, item in enumerate(sections)]

src/sources.py

@@ -0,0 +1,56 @@
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from urllib.parse import urlparse
+
+_ARXIV_ID = re.compile(
+    r"^(?:arxiv:)?(?P<id>(?:\d{4}\.\d{4,5}|[a-z-]+/\d{7})(?:v\d+)?)$",
+    re.IGNORECASE,
+)
+_ARXIV_URL = re.compile(
+    r"https?://(?:www\.)?arxiv\.org/(?:abs|pdf)/(?P<id>[^?#]+?)(?:\.pdf)?(?:[?#].*)?$",
+    re.IGNORECASE,
+)
+
+
+def normalize_arxiv_reference(value: str) -> str | None:
+    """Return a canonical arXiv PDF URL, or None when value is not arXiv."""
+
+    cleaned = value.strip()
+    direct_match = _ARXIV_ID.match(cleaned)
+    if direct_match:
+        return f"https://arxiv.org/pdf/{direct_match.group('id')}"
+
+    url_match = _ARXIV_URL.match(cleaned)
+    if url_match:
+        paper_id = url_match.group("id").removesuffix(".pdf")
+        return f"https://arxiv.org/pdf/{paper_id}"
+
+    return None
+
+
+def resolve_source(uploaded_file: str | Path | None, source_text: str | None) -> str:
+    """Resolve an uploaded PDF or an arXiv/HTTP source into a Docling input."""
+
+    if uploaded_file:
+        path = Path(uploaded_file)
+        if not path.exists():
+            raise FileNotFoundError(f"Uploaded file does not exist: {path}")
+        if path.suffix.lower() != ".pdf":
+            raise ValueError("The uploaded file must be a PDF.")
+        return str(path)
+
+    if not source_text or not source_text.strip():
+        raise ValueError("Upload a PDF or enter an arXiv ID/URL.")
+
+    source_text = source_text.strip()
+    arxiv_url = normalize_arxiv_reference(source_text)
+    if arxiv_url:
+        return arxiv_url
+
+    parsed = urlparse(source_text)
+    if parsed.scheme in {"http", "https"} and parsed.netloc:
+        return source_text
+
+    raise ValueError("Enter a valid arXiv ID, arXiv URL, HTTP URL, or upload a PDF.")

src/summarization.py

@@ -0,0 +1,169 @@
+from __future__ import annotations
+
+import math
+import re
+from collections import Counter
+from functools import lru_cache
+from typing import Literal
+
+from .config import SETTINGS
+from .models import Section
+
+Technicality = Literal["overview", "intermediate", "technical"]
+SummarizerMode = Literal["extractive", "pegasus"]
+
+_SENTENCE = re.compile(r"(?<=[.!?])\s+(?=[A-Z0-9])")
+_WORD = re.compile(r"[A-Za-z][A-Za-z'-]{2,}")
+_STOPWORDS = {
+    "the", "and", "that", "with", "from", "this", "were", "have", "has", "had",
+    "for", "are", "was", "but", "not", "into", "their", "they", "our", "using",
+    "used", "than", "then", "which", "also", "can", "may", "such", "these",
+    "those", "between", "within", "where", "when", "while", "about", "paper",
+}
+
+
+def _preferred_text(sections: list[Section], technicality: Technicality) -> str:
+    if not sections:
+        return ""
+
+    preferred_terms = {
+        "overview": ("abstract", "introduction", "conclusion", "discussion"),
+        "intermediate": ("abstract", "introduction", "method", "result", "conclusion", "discussion"),
+        "technical": (),
+    }[technicality]
+
+    if not preferred_terms:
+        return "\n\n".join(section.content for section in sections)
+
+    selected = [
+        section.content
+        for section in sections
+        if any(term in section.title.lower() for term in preferred_terms)
+    ]
+    return "\n\n".join(selected or [section.content for section in sections])
+
+
+def extractive_summary(sections: list[Section], technicality: Technicality) -> str:
+    """Transparent baseline summarizer used when the neural model is unavailable."""
+
+    text = _preferred_text(sections, technicality)
+    sentences = [item.strip() for item in _SENTENCE.split(text) if len(item.split()) >= 7]
+    if not sentences:
+        return text[:3000].strip()
+
+    words = [word.lower() for word in _WORD.findall(text)]
+    frequencies = Counter(word for word in words if word not in _STOPWORDS)
+    if not frequencies:
+        return " ".join(sentences[:8])
+
+    max_frequency = max(frequencies.values())
+    normalized = {word: count / max_frequency for word, count in frequencies.items()}
+
+    scored: list[tuple[int, float, str]] = []
+    for index, sentence in enumerate(sentences):
+        sentence_words = [word.lower() for word in _WORD.findall(sentence)]
+        if not sentence_words:
+            continue
+        score = sum(normalized.get(word, 0.0) for word in sentence_words)
+        score /= math.sqrt(len(sentence_words))
+        scored.append((index, score, sentence))
+
+    target = {"overview": 8, "intermediate": 14, "technical": 22}[technicality]
+    chosen = sorted(sorted(scored, key=lambda item: item[1], reverse=True)[:target])
+    return "\n\n".join(sentence for _, _, sentence in chosen)
+
+
+@lru_cache(maxsize=1)
+def _load_pegasus():
+    import torch
+    from transformers import AutoModelForSeq2SeqLM, AutoTokenizer
+
+    tokenizer = AutoTokenizer.from_pretrained(
+        SETTINGS.summarizer_tokenizer_id,
+        use_fast=False,
+    )
+    model = AutoModelForSeq2SeqLM.from_pretrained(SETTINGS.summarizer_model_id)
+    
+    device = "cuda" if torch.cuda.is_available() else "cpu"
+    model.to(device)
+    model.eval()
+    return tokenizer, model, device
+
+
+def _token_chunks(tokenizer, text: str, chunk_size: int) -> list[list[int]]:
+    token_ids = tokenizer.encode(text, add_special_tokens=False)
+    return [token_ids[index:index + chunk_size] for index in range(0, len(token_ids), chunk_size)]
+
+
+def pegasus_summary(sections: list[Section], technicality: Technicality) -> str:
+    """Abstractive scientific summarization with a pretrained PEGASUS-X model."""
+
+    if not SETTINGS.enable_pegasus:
+        raise RuntimeError("PEGASUS is disabled. Set ENABLE_PEGASUS=1 to enable it.")
+
+    import torch
+
+    text = _preferred_text(sections, technicality)
+    if not text.strip():
+        raise ValueError("No paper text is available to summarize.")
+
+    tokenizer, model, device = _load_pegasus()
+    model_limit = getattr(tokenizer, "model_max_length", 4096)
+    if not isinstance(model_limit, int) or model_limit > 32768:
+        model_limit = 4096
+    chunk_size = min(model_limit - 64, 4096)
+
+    length_settings = {
+        "overview": (96, 260),
+        "intermediate": (160, 420),
+        "technical": (240, 620),
+    }
+    min_new_tokens, max_new_tokens = length_settings[technicality]
+
+    partial_summaries: list[str] = []
+    for ids in _token_chunks(tokenizer, text, chunk_size):
+        input_ids = torch.tensor([ids], device=device)
+        attention_mask = torch.ones_like(input_ids)
+        with torch.inference_mode():
+            output_ids = model.generate(
+                input_ids=input_ids,
+                attention_mask=attention_mask,
+                num_beams=4,
+                min_new_tokens=min_new_tokens,
+                max_new_tokens=max_new_tokens,
+                no_repeat_ngram_size=3,
+                length_penalty=1.0,
+                early_stopping=True,
+            )
+        partial_summaries.append(tokenizer.decode(output_ids[0], skip_special_tokens=True))
+
+    if len(partial_summaries) == 1:
+        return partial_summaries[0]
+
+    merged = "\n\n".join(partial_summaries)
+    merged_ids = tokenizer.encode(merged, add_special_tokens=False)[:chunk_size]
+    input_ids = torch.tensor([merged_ids], device=device)
+    attention_mask = torch.ones_like(input_ids)
+    with torch.inference_mode():
+        output_ids = model.generate(
+            input_ids=input_ids,
+            attention_mask=attention_mask,
+            num_beams=4,
+            min_new_tokens=min_new_tokens,
+            max_new_tokens=max_new_tokens,
+            no_repeat_ngram_size=3,
+            early_stopping=True,
+        )
+    return tokenizer.decode(output_ids[0], skip_special_tokens=True)
+
+
+def summarize(
+    sections: list[Section],
+    technicality: Technicality,
+    mode: SummarizerMode,
+) -> str:
+    if mode == "extractive":
+        return extractive_summary(sections, technicality)
+    if mode == "pegasus":
+        return pegasus_summary(sections, technicality)
+    raise ValueError(f"Unknown summarizer mode: {mode}")

src/tts.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+import uuid
+from functools import lru_cache
+from pathlib import Path
+
+import numpy as np
+
+from .config import SETTINGS
+
+
+@lru_cache(maxsize=1)
+def _kokoro_pipeline():
+    if not SETTINGS.enable_kokoro:
+        raise RuntimeError("Kokoro is disabled. Set ENABLE_KOKORO=1 to enable it.")
+    from kokoro import KPipeline
+
+    return KPipeline(lang_code="a")
+
+
+def generate_audio(
+    text: str,
+    voice: str = "af_heart",
+    speed: float = 1.0,
+) -> Path:
+    """Generate a WAV narration using the open-weight Kokoro TTS model."""
+
+    import soundfile as sf
+
+    normalized = text.strip()
+    if not normalized:
+        raise ValueError("Narration text is empty.")
+    normalized = normalized[: SETTINGS.max_audio_chars]
+
+    pipeline = _kokoro_pipeline()
+    audio_segments: list[np.ndarray] = []
+    for _, _, audio in pipeline(normalized, voice=voice, speed=speed):
+        audio_segments.append(np.asarray(audio, dtype=np.float32))
+
+    if not audio_segments:
+        raise RuntimeError("Kokoro returned no audio segments.")
+
+    combined = np.concatenate(audio_segments)
+    output_path = SETTINGS.output_dir / f"papercast-{uuid.uuid4().hex[:10]}.wav"
+    sf.write(output_path, combined, 24000)
+    return output_path

tests/test_narration.py

@@ -0,0 +1,9 @@
+from src.narration import prepare_narration
+
+
+def test_narration_removes_markdown_and_verbalizes_math():
+    text = "# Result\nThe state obeys $H|psi> = E|psi>$ and [details](https://example.com)."
+    narration = prepare_narration(text, "technical")
+    assert "#" not in narration
+    assert "https://" not in narration
+    assert "mathematical expression" in narration

tests/test_sections.py

@@ -0,0 +1,8 @@
+from src.sections import split_markdown_sections
+
+
+def test_split_sections():
+    markdown = """Opening text.\n\n# Introduction\nIntro content.\n\n## Method\nMethod content."""
+    sections = split_markdown_sections(markdown)
+    assert [section.title for section in sections] == ["Document opening", "Introduction", "Method"]
+    assert sections[-1].level == 2

tests/test_sources.py

@@ -0,0 +1,24 @@
+from pathlib import Path
+
+import pytest
+
+from src.sources import normalize_arxiv_reference, resolve_source
+
+
+def test_normalize_arxiv_id():
+    assert normalize_arxiv_reference("2501.17887") == "https://arxiv.org/pdf/2501.17887"
+
+
+def test_normalize_arxiv_url():
+    assert normalize_arxiv_reference("https://arxiv.org/abs/2501.17887") == "https://arxiv.org/pdf/2501.17887"
+
+
+def test_rejects_invalid_source():
+    with pytest.raises(ValueError):
+        resolve_source(None, "not a source")
+
+
+def test_local_pdf(tmp_path: Path):
+    paper = tmp_path / "paper.pdf"
+    paper.write_bytes(b"%PDF-test")
+    assert resolve_source(paper, None) == str(paper)