ardive 0.1.0__py3-none-any.whl

ardive/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

ardive/arxiv.py

@@ -0,0 +1,69 @@
+"""Fetch paper metadata and text from arXiv."""
+
+from __future__ import annotations
+
+import tempfile
+import urllib.request
+from dataclasses import dataclass
+
+import arxiv
+
+_client = arxiv.Client()
+
+
+@dataclass
+class Paper:
+    id: str
+    title: str
+    authors: str
+    abstract: str
+    full_text: str = ""
+
+
+def _result_to_paper(result: arxiv.Result, full_text: str = "") -> Paper:
+    return Paper(
+        id=result.get_short_id(),
+        title=result.title.strip(),
+        authors=", ".join(a.name for a in result.authors),
+        abstract=result.summary.strip(),
+        full_text=full_text,
+    )
+
+
+def _pdf_text(url: str) -> str:
+    from pypdf import PdfReader
+
+    req = urllib.request.Request(url, headers={"User-Agent": "arDive"})
+    with urllib.request.urlopen(req) as resp, tempfile.NamedTemporaryFile(
+        suffix=".pdf"
+    ) as tmp:
+        tmp.write(resp.read())
+        tmp.flush()
+        reader = PdfReader(tmp.name)
+        return "\n".join(page.extract_text() or "" for page in reader.pages).strip()
+
+
+def fetch_paper(arxiv_id: str) -> Paper:
+    """Fetch one paper by arXiv ID, including full text from its PDF."""
+    try:
+        result = next(_client.results(arxiv.Search(id_list=[arxiv_id])))
+    except StopIteration:
+        raise LookupError(f"No arXiv paper found with id '{arxiv_id}'.")
+
+    text = _pdf_text(result.pdf_url)
+
+    # Fall back to the abstract if text extraction came up empty.
+    return _result_to_paper(result, full_text=text or result.summary.strip())
+
+
+def search_topic(query: str, n: int) -> list[Paper]:
+    """Search arXiv by topic; returns metadata + abstracts (no PDF download)."""
+    search = arxiv.Search(
+        query=query,
+        max_results=n,
+        sort_by=arxiv.SortCriterion.Relevance,
+    )
+    papers = [_result_to_paper(r) for r in _client.results(search)]
+    if not papers:
+        raise LookupError(f"No arXiv papers found for topic '{query}'.")
+    return papers

ardive/cli.py

@@ -0,0 +1,91 @@
+"""arDive command-line interface."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+SECTIONS = {
+    "abstract": "abstract",
+    "intro": "introduction",
+    "methodology": "methodology",
+    "related": "related works",
+    "citations": "citations / references",
+}
+
+
+def positive_int(value: str) -> int:
+    n = int(value)
+    if n <= 0:
+        raise argparse.ArgumentTypeError("must be a positive integer")
+    return n
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    common = argparse.ArgumentParser(add_help=False)
+    common.add_argument(
+        "--eli5", action="store_true", help="explain like I'm 5"
+    )
+
+    parser = argparse.ArgumentParser(
+        prog="ardive",
+        description="Pull papers from arXiv and summarize / explain them with a local open-source model.",
+    )
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p_sum = sub.add_parser(
+        "sum", parents=[common], help="summarize a paper in bullet points"
+    )
+    p_sum.add_argument("arxiv_id", help="arXiv id, e.g. 2410.12345")
+    p_sum.add_argument(
+        "--section", choices=list(SECTIONS), help="focus on one section"
+    )
+    p_sum.add_argument(
+        "--max-bullets", type=positive_int, help="cap the number of bullets"
+    )
+
+    p_comp = sub.add_parser(
+        "comp", parents=[common], help="compare two or more papers"
+    )
+    p_comp.add_argument("arxiv_ids", nargs="+", help="two or more arXiv ids")
+
+    p_dig = sub.add_parser(
+        "dig", parents=[common], help="digest a topic of papers"
+    )
+    p_dig.add_argument("topic", help="topic / search query")
+    p_dig.add_argument(
+        "-n", "--num", type=positive_int, default=8, help="papers to pull (default 8)"
+    )
+
+    return parser
+
+
+def _run(args: argparse.Namespace) -> str:
+    # Imported lazily so `ardive --help` works without the model deps running.
+    from . import arxiv, llm
+
+    if args.command == "sum":
+        paper = arxiv.fetch_paper(args.arxiv_id)
+        section = SECTIONS[args.section] if args.section else None
+        return llm.summarize(paper, section, args.max_bullets, args.eli5)
+
+    if args.command == "comp":
+        if len(args.arxiv_ids) < 2:
+            raise ValueError("comp needs at least two arXiv ids")
+        papers = [arxiv.fetch_paper(i) for i in args.arxiv_ids]
+        return llm.compare(papers, args.eli5)
+
+    if args.command == "dig":
+        papers = arxiv.search_topic(args.topic, args.num)
+        return llm.digest(args.topic, papers, args.eli5)
+
+    raise ValueError(f"unknown command: {args.command}")
+
+
+def main() -> None:
+    args = _build_parser().parse_args()
+    try:
+        print(_run(args))
+    except Exception as exc:  # clean message, no traceback for expected failures
+        print(f"error: {exc}", file=sys.stderr)
+        sys.exit(1)

ardive/llm.py

@@ -0,0 +1,109 @@
+"""Open-source LLM (Ollama) backed summarize / compare / digest builders.
+
+Uses a local Ollama server (https://ollama.com) — free, no API key. Swap the
+model with the ARDIVE_MODEL env var; point at a remote server with OLLAMA_HOST.
+"""
+
+from __future__ import annotations
+
+import os
+
+import ollama
+
+from .arxiv import Paper
+
+MODEL = os.environ.get("ARDIVE_MODEL", "llama3.2")
+# Context window. Papers are long; raise this (and your RAM) for big papers.
+NUM_CTX = int(os.environ.get("ARDIVE_NUM_CTX", "8192"))
+# Char budget for supplied paper text, leaving room for the prompt + response so
+# the model sees the instruction and the start of the paper instead of truncating.
+INPUT_CHARS = max(2000, (NUM_CTX - 1500) * 4)
+
+SYSTEM = (
+    "You are arDive, a research-paper explainer. You read arXiv papers and "
+    "respond in clear Markdown bullet points. Be accurate and concise; do not "
+    "invent results that are not in the provided text."
+)
+
+
+def _eli5_clause(eli5: bool) -> str:
+    if not eli5:
+        return ""
+    return (
+        " Explain like I'm 5: use plain language and everyday analogies, and "
+        "avoid jargon and equations."
+    )
+
+
+def _bullets_clause(max_bullets: int | None) -> str:
+    return f" Use at most {max_bullets} bullet points." if max_bullets else ""
+
+
+def _ask(user: str) -> str:
+    try:
+        response = ollama.chat(
+            model=MODEL,
+            messages=[
+                {"role": "system", "content": SYSTEM},
+                {"role": "user", "content": user},
+            ],
+            options={"num_ctx": NUM_CTX},
+        )
+    except ConnectionError:
+        raise RuntimeError(
+            "could not reach Ollama. Install it from https://ollama.com, then "
+            "run `ollama serve` and `ollama pull " + MODEL + "`."
+        )
+    except ollama.ResponseError as exc:
+        raise RuntimeError(f"Ollama error: {exc}. Try `ollama pull {MODEL}`.")
+    return response["message"]["content"].strip()
+
+
+def _clip(text: str, max_chars: int) -> str:
+    if len(text) <= max_chars:
+        return text
+    return text[:max_chars] + "\n[... text truncated to fit the context window ...]"
+
+
+def _paper_block(paper: Paper, body: str) -> str:
+    return f"Title: {paper.title}\nAuthors: {paper.authors}\n\n{body}"
+
+
+def summarize(
+    paper: Paper,
+    section: str | None,
+    max_bullets: int | None,
+    eli5: bool,
+) -> str:
+    focus = f" Focus only on the {section} section of the paper." if section else ""
+    instruction = (
+        "Summarize the following paper in bullet-point form."
+        + focus
+        + _bullets_clause(max_bullets)
+        + _eli5_clause(eli5)
+    )
+    body = _clip(paper.full_text, INPUT_CHARS)
+    return _ask(f"{instruction}\n\n{_paper_block(paper, body)}")
+
+
+def compare(papers: list[Paper], eli5: bool) -> str:
+    instruction = (
+        "Compare the following papers in bullet-point form. Cover what they "
+        "share, how they differ, and their relative strengths and weaknesses."
+        + _eli5_clause(eli5)
+    )
+    per_paper = INPUT_CHARS // max(1, len(papers))
+    blocks = "\n\n---\n\n".join(
+        _paper_block(p, _clip(p.full_text, per_paper)) for p in papers
+    )
+    return _ask(f"{instruction}\n\n{blocks}")
+
+
+def digest(query: str, papers: list[Paper], eli5: bool) -> str:
+    instruction = (
+        f"Digest the arXiv literature on '{query}' in bullet-point form. "
+        "Cover the main themes, the most notable papers, and open questions."
+        + _eli5_clause(eli5)
+    )
+    blocks = "\n\n".join(_paper_block(p, p.abstract) for p in papers)
+    return _ask(f"{instruction}\n\n{blocks}")

ardive-0.1.0.dist-info/METADATA

@@ -0,0 +1,92 @@
+Metadata-Version: 2.4
+Name: ardive
+Version: 0.1.0
+Summary: Command-line agent that pulls papers from arXiv and summarizes / explains them with a local open-source model.
+Author-email: Rohan Kosalge <rohankosalge06@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/rohankosalge/arDive
+Project-URL: Repository, https://github.com/rohankosalge/arDive
+Keywords: arxiv,summarization,cli,ollama,llm
+Classifier: Programming Language :: Python :: 3
+Classifier: Environment :: Console
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: ollama>=0.3
+Requires-Dist: arxiv>=2.1
+Requires-Dist: pypdf>=4.0
+Dynamic: license-file
+
+# arDive: a simple dive into your ArXiv
+
+A small command-line agent that pulls papers from arXiv and uses Llama3.2 to
+summarize, explain, compare, and digest them. Anyone can easily install and use without the need of a paid plan.
+
+## Install
+
+```bash
+# 1. Install Ollama (free, runs models locally): https://ollama.com
+ollama pull llama3.2        # or any open model you like
+
+# 2. Install arDive
+pip install ardive
+```
+
+That's it. arDive talks to the local Ollama server. Pick a
+different model with `ARDIVE_MODEL` (e.g. `export ARDIVE_MODEL=qwen2.5`), or
+point at a remote Ollama with `OLLAMA_HOST`.
+
+### From source
+
+```bash
+git clone https://github.com/rohankosalge/arDive
+cd arDive
+pip install -e .
+```
+
+## Usage
+
+```bash
+# Summarize a paper as bullet points
+ardive sum 1234.56789
+
+# Focus on one section, cap the bullets
+ardive sum 1234.56789 --section methodology --max-bullets 5
+
+# Explain like I'm 5 (works on every command)
+ardive sum 1234.56789 --eli5
+
+# Compare two or more papers
+ardive comp 1234.56789 9876.54321
+
+# Digest a topic (searches arXiv, default 8 papers)
+ardive dig "diffusion models for protein folding"
+ardive dig "graph neural networks" -n 12
+```
+
+### Commands
+
+| Command | What it does |
+| --- | --- |
+| `sum <id>` | Bullet-point summary of one paper (full PDF text). |
+| `comp <id> <id> [...]` | Compare two or more papers. |
+| `dig <topic>` | Search arXiv by topic and digest the top results. |
+
+### Flags
+
+- `--eli5` — explain in plain, jargon-free language (all commands).
+- `--section {abstract,intro,methodology,related,citations}` — `sum` only; focus on one section.
+- `--max-bullets N` — `sum` only; cap the number of bullets (positive integer).
+- `-n/--num N` — `dig` only; how many papers to pull (default 8).
+
+## How it works
+
+`sum` and `comp` download each paper's PDF and extract its full text; `dig`
+searches arXiv and works from abstracts. The text is sent to a local
+open-source model via Ollama (default `llama3.2`) with a prompt tailored to the
+command, and the bullet-point response is printed to stdout.
+
+Long papers can exceed the model's context window and be truncated. arDive asks
+Ollama for an 8192-token window by default; raise it (at the cost of more RAM)
+with `export ARDIVE_NUM_CTX=16384`.

ardive-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+ardive/__init__.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+ardive/arxiv.py,sha256=0vicbSuyTu6yO2ei0lXXSKfwxw-QG-5SvHa0aOGfaCs,1949
+ardive/cli.py,sha256=X_RPjvSwj0BlG73-NDiyuYSiXpts5gE2IuD2sQ4_gcU,2814
+ardive/llm.py,sha256=ajiY8aE71yGFMcXB28kxS7FEPZ56r4SS6OHT2ewJs5A,3619
+ardive-0.1.0.dist-info/licenses/LICENSE,sha256=ZxD8S4Ut4ORpsXtj0iXNgXV3fyn5EE3tDdH_QtMBrU4,1070
+ardive-0.1.0.dist-info/METADATA,sha256=5Lg-88MPGery2oBi0ou7b5uBVlt0WDEUu-wlib-XvJQ,2993
+ardive-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+ardive-0.1.0.dist-info/entry_points.txt,sha256=MmcwypMni9-LYbUGoUaynMonpyrtjJ2BUEFZW0nnx2Y,43
+ardive-0.1.0.dist-info/top_level.txt,sha256=BGRIa1zv_vvqhk-HZh2Z1DQlgUNJ1T12kFt9VTY2wYo,7
+ardive-0.1.0.dist-info/RECORD,,

ardive-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

ardive-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+ardive = ardive.cli:main

ardive-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rohan Kosalge
+
+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.

ardive-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+ardive