citesentry 0.1.1__tar.gz

citesentry-0.1.1/.claude/settings.local.json

@@ -0,0 +1,18 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(pip install *)",
+      "Bash(pip index *)",
+      "Bash(python *)",
+      "Bash(refsift check-one *)",
+      "Bash(python3 -c \"import json,sys; d=json.load\\(sys.stdin\\); print\\(d['overall_verdict'], d['reference']['title']\\)\")",
+      "Bash(refsift check *)",
+      "Bash(python3 *)",
+      "Bash(xargs sed -i '' 's/from refsift\\\\./from citesentry./g; s/from refsift import/from citesentry import/g; s/import refsift\\\\./import citesentry./g')"
+    ]
+  },
+  "enableAllProjectMcpServers": true,
+  "enabledMcpjsonServers": [
+    "semantic-scholar-mcp"
+  ]
+}

citesentry-0.1.1/.github/workflows/publish.yml

@@ -0,0 +1,26 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  build-and-publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # required for trusted publishing
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v4
+        with:
+          version: "latest"
+
+      - name: Build package
+        run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

citesentry-0.1.1/CLAUDE.md

@@ -0,0 +1,36 @@
+# citesentry — Claude Code session notes
+
+## Guardrails (non-negotiable)
+
+- Never label a reference "fake" or "fraudulent" — only "could not verify / needs review."
+- Never bypass CAPTCHA or bot-protection; classify as SKIPPED.
+- Never hardcode API keys; read from env; degrade gracefully when absent.
+- Core (`citesentry/core/`, `citesentry/checks/`, `citesentry/sources/`, `citesentry/parse/`) must never import Typer, Rich, or MCP.
+- MCP server stdout must stay clean (JSON-RPC stream). Log to stderr only.
+- Always send `mailto` to OpenAlex/Crossref; respect rate limits; cache aggressively.
+- Report all counts honestly: checked, skipped, errored — never silently drop.
+
+## Architecture
+
+```
+                 ┌──────────────────────────────┐
+   bib/pdf/txt → │   citesentry.core (library)  │ → VerificationReport (pydantic)
+                 └──────────────────────────────┘
+                      ▲                  ▲
+                      │                  │
+              citesentry.cli     citesentry.mcp_server
+            (Typer + Rich)         (FastMCP / stdio)
+```
+
+If verification logic ever appears inside `cli.py` or `mcp_server.py`, that is a bug — move it to core.
+
+## LLM strategy
+
+- MCP server: uses MCP sampling (`ctx.sample()`) — no API key needed.
+- CLI: uses DeepSeek via OpenAI-compatible endpoint; requires `DEEPSEEK_API_KEY`.
+- `--no-llm` skips relevance checks entirely; tool remains fully usable.
+
+## Verdict wording
+
+`NOT_FOUND` → "could not verify — likely fabricated, needs manual review"
+Never use the word "fake."

citesentry-0.1.1/PKG-INFO

@@ -0,0 +1,201 @@
+Metadata-Version: 2.4
+Name: citesentry
+Version: 0.1.1
+Summary: Citation verification tool: existence, URL liveness, and content relevance checks
+License: MIT
+Requires-Python: >=3.10
+Requires-Dist: bibtexparser>=1.4
+Requires-Dist: httpx>=0.27
+Requires-Dist: mcp[cli]>=1.0
+Requires-Dist: pdfminer-six>=20221105
+Requires-Dist: platformdirs>=4
+Requires-Dist: pydantic>=2
+Requires-Dist: rapidfuzz>=3
+Requires-Dist: rich>=13
+Requires-Dist: rispy>=0.9
+Requires-Dist: typer>=0.12
+Provides-Extra: cli-llm
+Requires-Dist: openai>=1.0; extra == 'cli-llm'
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Provides-Extra: domain
+Provides-Extra: pdf
+Requires-Dist: refextract; extra == 'pdf'
+Description-Content-Type: text/markdown
+
+# CiteSentry
+
+[![PyPI](https://img.shields.io/pypi/v/citesentry)](https://pypi.org/project/citesentry/)
+[![Python](https://img.shields.io/pypi/pyversions/citesentry)](https://pypi.org/project/citesentry/)
+[![CI](https://github.com/mkassaf/CiteSentry/actions/workflows/publish.yml/badge.svg)](https://github.com/mkassaf/CiteSentry/actions/workflows/publish.yml)
+
+Citation verification tool: check whether references actually exist, whether their URLs are live, and whether the content is relevant to the citation.
+
+## What it does
+
+Three checks per reference:
+
+1. **Existence** — resolves against OpenAlex, Crossref, Semantic Scholar, arXiv, and domain-specific databases (PubMed for biomedical, DBLP for CS)
+2. **URL liveness** — HTTP HEAD/GET check; classifies 2xx/4xx/timeout/bot-protection
+3. **Content relevance** — LLM-backed check comparing fetched content to the cited title/topic (requires `DEEPSEEK_API_KEY` for CLI use)
+
+Verdicts: `VERIFIED`, `METADATA_MISMATCH`, `DEAD_URL`, `CONTENT_DRIFT`, `NOT_FOUND`, `UNRESOLVABLE`.
+
+`NOT_FOUND` means "could not verify — likely fabricated, needs manual review." Never "fake."
+
+## Install
+
+```bash
+pip install citesentry                 # basic install
+pip install "citesentry[cli-llm]"      # + DeepSeek for relevance checks
+```
+
+For development:
+
+```bash
+git clone https://github.com/mkassaf/CiteSentry
+cd CiteSentry
+pip install -e ".[dev]"
+```
+
+## CLI usage
+
+```bash
+# Check a BibTeX file
+citesentry check refs.bib
+
+# Check a RIS/CSL-JSON/NBIB/plaintext file
+citesentry check refs.ris
+citesentry check refs.json
+
+# Read from stdin
+cat refs.txt | citesentry check -
+
+# Single ad-hoc reference
+citesentry check-one "Vaswani et al. (2017). Attention is all you need. NeurIPS."
+
+# Output formats: table (default), json, md
+citesentry check refs.bib --format json
+citesentry check refs.bib --format md > report.md
+
+# Skip checks
+citesentry check refs.bib --no-llm       # skip relevance (no API key needed)
+citesentry check refs.bib --no-url       # skip URL liveness
+
+# Domain adapters (auto by default)
+citesentry check refs.bib --domain pubmed   # force PubMed only
+citesentry check refs.bib --domain none     # disable domain adapters
+
+# Override plaintext style detection
+citesentry check refs.txt --style ieee
+```
+
+Exit code is non-zero if any reference is `NOT_FOUND` or `DEAD_URL` (useful in CI).
+
+## MCP server (Claude Desktop / Claude Code)
+
+Add to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "citesentry": {
+      "command": "citesentry-mcp",
+      "env": {
+        "CITESENTRY_MAILTO": "you@example.com",
+        "DEEPSEEK_API_KEY": "sk-..."
+      }
+    }
+  }
+}
+```
+
+Or with `uvx` (no prior install needed):
+
+```json
+{
+  "mcpServers": {
+    "citesentry": {
+      "command": "uvx",
+      "args": ["--from", "citesentry", "citesentry-mcp"],
+      "env": { "CITESENTRY_MAILTO": "you@example.com" }
+    }
+  }
+}
+```
+
+MCP tools exposed:
+- `verify_reference(reference, check_url, check_relevance)` — single reference
+- `verify_reference_list(references, format, check_url, check_relevance)` — batch
+- `check_url_alive(url)` — standalone URL check
+
+### Claude Code (CLI)
+
+Register the server once:
+
+```bash
+claude mcp add citesentry \
+  -e CITESENTRY_MAILTO=you@example.com \
+  -- uvx --from citesentry citesentry-mcp
+```
+
+Then in any Claude Code session, ask naturally:
+
+> "Use citesentry to verify this reference: Vaswani et al. (2017). Attention is all you need. NeurIPS."
+
+> "Check whether all the references in refs.bib are real."
+
+> "Is https://arxiv.org/abs/1706.03762 still live?"
+
+### Any MCP-compatible agent (Python example)
+
+```python
+import asyncio
+from mcp import ClientSession, StdioServerParameters
+from mcp.client.stdio import stdio_client
+
+server = StdioServerParameters(
+    command="uvx",
+    args=["--from", "citesentry", "citesentry-mcp"],
+    env={"CITESENTRY_MAILTO": "you@example.com"},
+)
+
+async def main():
+    async with stdio_client(server) as (read, write):
+        async with ClientSession(read, write) as session:
+            await session.initialize()
+
+            result = await session.call_tool(
+                "verify_reference",
+                {"reference": "Vaswani et al. (2017). Attention is all you need. NeurIPS."},
+            )
+            print(result.content[0].text)
+
+asyncio.run(main())
+```
+
+## Environment variables
+
+| Variable | Default | Description |
+|---|---|---|
+| `CITESENTRY_MAILTO` | `citesentry@example.com` | Polite email for OpenAlex/Crossref API |
+| `DEEPSEEK_API_KEY` | — | Required for relevance checks in CLI |
+| `DEEPSEEK_BASE_URL` | `https://api.deepseek.com/v1` | OpenAI-compatible endpoint |
+| `DEEPSEEK_MODEL` | `deepseek-chat` | Model for relevance judgments |
+
+## Supported input formats
+
+- BibTeX (`.bib`) — via bibtexparser
+- RIS (`.ris`) — via rispy; covers Zotero, Mendeley, EndNote, Web of Science
+- CSL JSON (`.json`) — Zotero exports
+- PubMed NBIB (`.nbib`)
+- DOI list (`.txt` with one DOI per line)
+- Plaintext reference sections — IEEE, APA, Vancouver, MLA, Chicago; auto-detected
+- PDF (`.pdf`) — extracts reference section text via pdfminer.six
+
+## Caching
+
+Results are cached in a SQLite database (`~/.cache/citesentry/cache.db`). Pass `--no-cache` to bypass.

citesentry-0.1.1/README.md

@@ -0,0 +1,173 @@
+# CiteSentry
+
+[![PyPI](https://img.shields.io/pypi/v/citesentry)](https://pypi.org/project/citesentry/)
+[![Python](https://img.shields.io/pypi/pyversions/citesentry)](https://pypi.org/project/citesentry/)
+[![CI](https://github.com/mkassaf/CiteSentry/actions/workflows/publish.yml/badge.svg)](https://github.com/mkassaf/CiteSentry/actions/workflows/publish.yml)
+
+Citation verification tool: check whether references actually exist, whether their URLs are live, and whether the content is relevant to the citation.
+
+## What it does
+
+Three checks per reference:
+
+1. **Existence** — resolves against OpenAlex, Crossref, Semantic Scholar, arXiv, and domain-specific databases (PubMed for biomedical, DBLP for CS)
+2. **URL liveness** — HTTP HEAD/GET check; classifies 2xx/4xx/timeout/bot-protection
+3. **Content relevance** — LLM-backed check comparing fetched content to the cited title/topic (requires `DEEPSEEK_API_KEY` for CLI use)
+
+Verdicts: `VERIFIED`, `METADATA_MISMATCH`, `DEAD_URL`, `CONTENT_DRIFT`, `NOT_FOUND`, `UNRESOLVABLE`.
+
+`NOT_FOUND` means "could not verify — likely fabricated, needs manual review." Never "fake."
+
+## Install
+
+```bash
+pip install citesentry                 # basic install
+pip install "citesentry[cli-llm]"      # + DeepSeek for relevance checks
+```
+
+For development:
+
+```bash
+git clone https://github.com/mkassaf/CiteSentry
+cd CiteSentry
+pip install -e ".[dev]"
+```
+
+## CLI usage
+
+```bash
+# Check a BibTeX file
+citesentry check refs.bib
+
+# Check a RIS/CSL-JSON/NBIB/plaintext file
+citesentry check refs.ris
+citesentry check refs.json
+
+# Read from stdin
+cat refs.txt | citesentry check -
+
+# Single ad-hoc reference
+citesentry check-one "Vaswani et al. (2017). Attention is all you need. NeurIPS."
+
+# Output formats: table (default), json, md
+citesentry check refs.bib --format json
+citesentry check refs.bib --format md > report.md
+
+# Skip checks
+citesentry check refs.bib --no-llm       # skip relevance (no API key needed)
+citesentry check refs.bib --no-url       # skip URL liveness
+
+# Domain adapters (auto by default)
+citesentry check refs.bib --domain pubmed   # force PubMed only
+citesentry check refs.bib --domain none     # disable domain adapters
+
+# Override plaintext style detection
+citesentry check refs.txt --style ieee
+```
+
+Exit code is non-zero if any reference is `NOT_FOUND` or `DEAD_URL` (useful in CI).
+
+## MCP server (Claude Desktop / Claude Code)
+
+Add to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "citesentry": {
+      "command": "citesentry-mcp",
+      "env": {
+        "CITESENTRY_MAILTO": "you@example.com",
+        "DEEPSEEK_API_KEY": "sk-..."
+      }
+    }
+  }
+}
+```
+
+Or with `uvx` (no prior install needed):
+
+```json
+{
+  "mcpServers": {
+    "citesentry": {
+      "command": "uvx",
+      "args": ["--from", "citesentry", "citesentry-mcp"],
+      "env": { "CITESENTRY_MAILTO": "you@example.com" }
+    }
+  }
+}
+```
+
+MCP tools exposed:
+- `verify_reference(reference, check_url, check_relevance)` — single reference
+- `verify_reference_list(references, format, check_url, check_relevance)` — batch
+- `check_url_alive(url)` — standalone URL check
+
+### Claude Code (CLI)
+
+Register the server once:
+
+```bash
+claude mcp add citesentry \
+  -e CITESENTRY_MAILTO=you@example.com \
+  -- uvx --from citesentry citesentry-mcp
+```
+
+Then in any Claude Code session, ask naturally:
+
+> "Use citesentry to verify this reference: Vaswani et al. (2017). Attention is all you need. NeurIPS."
+
+> "Check whether all the references in refs.bib are real."
+
+> "Is https://arxiv.org/abs/1706.03762 still live?"
+
+### Any MCP-compatible agent (Python example)
+
+```python
+import asyncio
+from mcp import ClientSession, StdioServerParameters
+from mcp.client.stdio import stdio_client
+
+server = StdioServerParameters(
+    command="uvx",
+    args=["--from", "citesentry", "citesentry-mcp"],
+    env={"CITESENTRY_MAILTO": "you@example.com"},
+)
+
+async def main():
+    async with stdio_client(server) as (read, write):
+        async with ClientSession(read, write) as session:
+            await session.initialize()
+
+            result = await session.call_tool(
+                "verify_reference",
+                {"reference": "Vaswani et al. (2017). Attention is all you need. NeurIPS."},
+            )
+            print(result.content[0].text)
+
+asyncio.run(main())
+```
+
+## Environment variables
+
+| Variable | Default | Description |
+|---|---|---|
+| `CITESENTRY_MAILTO` | `citesentry@example.com` | Polite email for OpenAlex/Crossref API |
+| `DEEPSEEK_API_KEY` | — | Required for relevance checks in CLI |
+| `DEEPSEEK_BASE_URL` | `https://api.deepseek.com/v1` | OpenAI-compatible endpoint |
+| `DEEPSEEK_MODEL` | `deepseek-chat` | Model for relevance judgments |
+
+## Supported input formats
+
+- BibTeX (`.bib`) — via bibtexparser
+- RIS (`.ris`) — via rispy; covers Zotero, Mendeley, EndNote, Web of Science
+- CSL JSON (`.json`) — Zotero exports
+- PubMed NBIB (`.nbib`)
+- DOI list (`.txt` with one DOI per line)
+- Plaintext reference sections — IEEE, APA, Vancouver, MLA, Chicago; auto-detected
+- PDF (`.pdf`) — extracts reference section text via pdfminer.six
+
+## Caching
+
+Results are cached in a SQLite database (`~/.cache/citesentry/cache.db`). Pass `--no-cache` to bypass.

citesentry-0.1.1/citesentry/__init__.py

@@ -0,0 +1,3 @@
+"""citesentry — citation verification tool."""
+
+__version__ = "0.1.1"

citesentry-0.1.1/citesentry/cache.py

@@ -0,0 +1,70 @@
+from __future__ import annotations
+
+import hashlib
+import json
+import sqlite3
+import time
+from pathlib import Path
+from typing import Any
+
+
+class Cache:
+    def __init__(self, path: Path) -> None:
+        self._path = path
+        self._path.parent.mkdir(parents=True, exist_ok=True)
+        self._conn = sqlite3.connect(str(path), check_same_thread=False)
+        self._init()
+
+    def _init(self) -> None:
+        self._conn.execute(
+            """CREATE TABLE IF NOT EXISTS cache (
+                key TEXT PRIMARY KEY,
+                value TEXT NOT NULL,
+                created_at REAL NOT NULL
+            )"""
+        )
+        self._conn.commit()
+
+    @staticmethod
+    def _key(namespace: str, identifier: str) -> str:
+        h = hashlib.sha256(f"{namespace}:{identifier}".encode()).hexdigest()
+        return h
+
+    def get(self, namespace: str, identifier: str) -> Any | None:
+        key = self._key(namespace, identifier)
+        row = self._conn.execute(
+            "SELECT value FROM cache WHERE key = ?", (key,)
+        ).fetchone()
+        if row is None:
+            return None
+        return json.loads(row[0])
+
+    def set(self, namespace: str, identifier: str, value: Any) -> None:
+        key = self._key(namespace, identifier)
+        self._conn.execute(
+            "INSERT OR REPLACE INTO cache (key, value, created_at) VALUES (?, ?, ?)",
+            (key, json.dumps(value), time.time()),
+        )
+        self._conn.commit()
+
+    def close(self) -> None:
+        self._conn.close()
+
+
+_cache: Cache | None = None
+
+
+def get_cache(path: Path | None = None) -> Cache:
+    global _cache
+    if _cache is None:
+        from citesentry.config import get_settings
+        p = path or get_settings().cache_path
+        _cache = Cache(p)
+    return _cache
+
+
+def reset_cache() -> None:
+    global _cache
+    if _cache is not None:
+        _cache.close()
+        _cache = None