citesentry 0.1.1__py3-none-any.whl

citesentry/__init__.py

@@ -0,0 +1,3 @@
+"""citesentry — citation verification tool."""
+
+__version__ = "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

citesentry/checks/existence.py

@@ -0,0 +1,219 @@
+from __future__ import annotations
+
+import time
+from typing import Any
+
+from rapidfuzz import fuzz
+
+from citesentry.models import Candidate, CheckCost, CheckResult, CheckStatus, Reference, Verdict
+from citesentry.sources.base import SourceAdapter
+
+_TITLE_PASS_THRESHOLD = 85.0
+_TITLE_WARN_THRESHOLD = 70.0
+
+
+def _surname(name: str) -> str:
+    """Extract surname from 'Last, First' or 'First Last' format."""
+    name = name.strip()
+    if "," in name:
+        return name.split(",")[0].strip().lower()
+    parts = name.split()
+    return parts[-1].lower() if parts else ""
+
+
+def _author_overlap(ref_authors: list[str], cand_authors: list[str]) -> float:
+    if not ref_authors or not cand_authors:
+        return 0.5
+    ref_surnames = {_surname(a) for a in ref_authors}
+    cand_surnames = {_surname(a) for a in cand_authors}
+    intersection = ref_surnames & cand_surnames
+    # Use subset recall when cited list is much shorter than found list
+    # (covers et al. truncation and papers with many authors).
+    if len(ref_surnames) < len(cand_surnames) * 0.5:
+        return len(intersection) / len(ref_surnames) if ref_surnames else 0.0
+    union = ref_surnames | cand_surnames
+    return len(intersection) / len(union) if union else 0.0
+
+
+def _year_score(ref_year: int | None, cand_year: int | None) -> float:
+    if ref_year is None or cand_year is None:
+        return 0.5
+    diff = abs(ref_year - cand_year)
+    if diff == 0:
+        return 1.0
+    if diff == 1:
+        return 0.7
+    return 0.0
+
+
+def _score_candidate(ref: Reference, cand: Candidate) -> tuple[float, dict[str, Any]]:
+    evidence: dict[str, Any] = {}
+
+    title_score = 0.0
+    if ref.title and cand.title:
+        title_score = fuzz.token_set_ratio(ref.title.lower(), cand.title.lower()) / 100.0
+    evidence["title_score"] = round(title_score, 3)
+
+    author_score = _author_overlap(ref.authors, cand.authors)
+    evidence["author_score"] = round(author_score, 3)
+
+    year_score = _year_score(ref.year, cand.year)
+    evidence["year_score"] = round(year_score, 3)
+
+    venue_score = 0.5
+    if ref.venue and cand.venue:
+        venue_score = fuzz.token_set_ratio(ref.venue.lower(), cand.venue.lower()) / 100.0
+    evidence["venue_score"] = round(venue_score, 3)
+
+    if title_score == 0.0:
+        composite = 0.0
+    else:
+        composite = (
+            title_score * 0.55
+            + author_score * 0.25
+            + year_score * 0.15
+            + venue_score * 0.05
+        )
+    evidence["composite"] = round(composite, 3)
+    return composite, evidence
+
+
+def _check_metadata_consistency(ref: Reference, best: Candidate) -> list[str]:
+    mismatches = []
+    if ref.year and best.year and abs(ref.year - best.year) > 2:
+        mismatches.append(f"year: cited={ref.year}, found={best.year}")
+    if ref.doi and best.doi and ref.doi.lower().strip("/") != best.doi.lower().strip("/"):
+        mismatches.append(f"doi: cited={ref.doi}, found={best.doi}")
+    if ref.authors and best.authors:
+        overlap = _author_overlap(ref.authors, best.authors)
+        if overlap < 0.3:
+            mismatches.append(
+                f"authors: low overlap ({overlap:.2f}), "
+                f"cited={ref.authors[:2]}, found={best.authors[:2]}"
+            )
+    return mismatches
+
+
+async def check_existence(
+    ref: Reference,
+    sources: list[SourceAdapter],
+    domain_sources: list[SourceAdapter] | None = None,
+    use_cache: bool = True,
+) -> CheckResult:
+    start = time.monotonic()
+    api_calls = 0
+    candidates: list[tuple[float, dict, Candidate]] = []
+    evidence: dict[str, Any] = {}
+
+    if use_cache:
+        from citesentry.cache import get_cache
+        cache = get_cache()
+        cache_key = ref.doi or (f"{ref.title}|{ref.year}" if ref.title else None)
+        if cache_key:
+            cached = cache.get("existence", cache_key)
+            if cached is not None:
+                elapsed = (time.monotonic() - start) * 1000
+                return CheckResult(
+                    name="existence",
+                    status=CheckStatus(cached["status"]),
+                    confidence=cached["confidence"],
+                    evidence={**cached["evidence"], "from_cache": True},
+                    cost=CheckCost(api_calls=0, elapsed_ms=elapsed),
+                )
+
+    if ref.doi:
+        for src in sources:
+            try:
+                cand = await src.lookup_doi(ref.doi)
+                api_calls += 1
+                if cand:
+                    score, ev = _score_candidate(ref, cand)
+                    candidates.append((score, {**ev, "source": src.name, "via": "doi_lookup"}, cand))
+            except Exception as e:
+                evidence[f"{src.name}_error"] = str(e)
+
+    if not candidates:
+        for src in sources:
+            try:
+                results = await src.search(ref)
+                api_calls += 1
+                for cand in results:
+                    score, ev = _score_candidate(ref, cand)
+                    candidates.append((score, {**ev, "source": src.name, "via": "search"}, cand))
+            except Exception as e:
+                evidence[f"{src.name}_error"] = str(e)
+
+    if not candidates and domain_sources:
+        for src in domain_sources:
+            try:
+                if ref.doi:
+                    cand = await src.lookup_doi(ref.doi)
+                    api_calls += 1
+                    if cand:
+                        score, ev = _score_candidate(ref, cand)
+                        candidates.append((score, {**ev, "source": src.name, "via": "doi_lookup"}, cand))
+                results = await src.search(ref)
+                api_calls += 1
+                for cand in results:
+                    score, ev = _score_candidate(ref, cand)
+                    candidates.append((score, {**ev, "source": src.name, "via": "search"}, cand))
+            except Exception as e:
+                evidence[f"{src.name}_error"] = str(e)
+
+    elapsed = (time.monotonic() - start) * 1000
+
+    if not candidates:
+        result = CheckResult(
+            name="existence",
+            status=CheckStatus.FAIL,
+            confidence=0.9 if (ref.title or ref.doi) else 0.5,
+            evidence={**evidence, "verdict": "not_found", "candidates_checked": 0},
+            cost=CheckCost(api_calls=api_calls, elapsed_ms=elapsed),
+        )
+    else:
+        candidates.sort(key=lambda x: x[0], reverse=True)
+        best_score, best_ev, best_cand = candidates[0]
+        evidence.update(best_ev)
+        evidence["best_candidate_title"] = best_cand.title
+        evidence["best_candidate_source"] = best_cand.source
+        evidence["total_candidates"] = len(candidates)
+
+        title_score = best_ev.get("title_score", 0.0)
+
+        # High title match always warrants a look, even if other fields diverge
+        if title_score >= 0.85 or best_score * 100 >= _TITLE_PASS_THRESHOLD:
+            mismatches = _check_metadata_consistency(ref, best_cand)
+            if mismatches:
+                evidence["mismatches"] = mismatches
+                status = CheckStatus.WARN
+                confidence = min(max(title_score, best_score), 0.85)
+            else:
+                status = CheckStatus.PASS
+                confidence = max(title_score, best_score)
+        elif best_score * 100 >= _TITLE_WARN_THRESHOLD:
+            status = CheckStatus.WARN
+            confidence = best_score * 0.7
+        else:
+            status = CheckStatus.FAIL
+            confidence = 0.7
+
+        result = CheckResult(
+            name="existence",
+            status=status,
+            confidence=confidence,
+            evidence=evidence,
+            cost=CheckCost(api_calls=api_calls, elapsed_ms=elapsed),
+        )
+
+    if use_cache:
+        from citesentry.cache import get_cache
+        cache = get_cache()
+        cache_key = ref.doi or (f"{ref.title}|{ref.year}" if ref.title else None)
+        if cache_key:
+            cache.set("existence", cache_key, {
+                "status": result.status.value,
+                "confidence": result.confidence,
+                "evidence": result.evidence,
+            })
+
+    return result

citesentry/checks/relevance.py

@@ -0,0 +1,176 @@
+from __future__ import annotations
+
+import json
+import time
+from typing import Any
+
+import httpx
+
+from citesentry.models import CheckCost, CheckResult, CheckStatus, RelevanceLabel, Reference
+
+_RELEVANCE_PROMPT = """\
+You are a citation relevance judge. Given a reference title/topic and fetched content from the cited source, determine if the content matches the citation.
+
+Reference title: {title}
+Reference topic context: {context}
+
+Fetched content (first 1500 chars):
+{content}
+
+Respond with ONLY valid JSON in this exact format:
+{{"label": "<RELEVANT|PARTIAL|UNRELATED|CANNOT_DETERMINE>", "confidence": <0.0-1.0>, "rationale": "<one sentence>"}}
+
+Labels:
+- RELEVANT: content clearly matches the cited title/topic
+- PARTIAL: content partially matches or is in the same general area
+- UNRELATED: content does not match the citation at all
+- CANNOT_DETERMINE: paywalled, JS-only page, no meaningful content to judge
+"""
+
+
+async def _fetch_content(url: str, doi: str | None = None) -> str:
+    """Fetch content for relevance check. Returns text snippet."""
+    headers = {
+        "User-Agent": (
+            "Mozilla/5.0 (compatible; citesentry/0.1; citation verification bot)"
+        )
+    }
+    try:
+        async with httpx.AsyncClient(timeout=15.0, follow_redirects=True) as client:
+            r = await client.get(url, headers=headers)
+            if 200 <= r.status_code < 300:
+                text = r.text[:3000]
+                text = " ".join(text.split())
+                return text[:1500]
+    except httpx.HTTPError:
+        pass
+    return ""
+
+
+async def check_relevance(
+    ref: Reference,
+    llm_client: object,
+    abstract: str | None = None,
+    use_cache: bool = True,
+) -> CheckResult:
+    start = time.monotonic()
+
+    if llm_client is None:
+        return CheckResult(
+            name="relevance",
+            status=CheckStatus.SKIPPED,
+            confidence=0.0,
+            evidence={"reason": "no_llm_client"},
+            cost=CheckCost(elapsed_ms=0.0),
+        )
+
+    if not ref.title and not ref.doi:
+        return CheckResult(
+            name="relevance",
+            status=CheckStatus.SKIPPED,
+            confidence=0.0,
+            evidence={"reason": "insufficient_reference_data"},
+            cost=CheckCost(elapsed_ms=0.0),
+        )
+
+    cache_key = ref.doi or (f"{ref.title}|{','.join(ref.urls[:1])}" if ref.title else None)
+    if use_cache and cache_key:
+        from citesentry.cache import get_cache
+        cache = get_cache()
+        cached = cache.get("relevance", cache_key)
+        if cached is not None:
+            elapsed = (time.monotonic() - start) * 1000
+            return CheckResult(
+                name="relevance",
+                status=CheckStatus(cached["status"]),
+                confidence=cached["confidence"],
+                evidence={**cached["evidence"], "from_cache": True},
+                cost=CheckCost(elapsed_ms=elapsed),
+            )
+
+    content = abstract or ""
+    if not content and ref.urls:
+        content = await _fetch_content(ref.urls[0])
+
+    if not content:
+        return CheckResult(
+            name="relevance",
+            status=CheckStatus.WARN,
+            confidence=0.3,
+            evidence={"reason": "no_content_available", "label": "CANNOT_DETERMINE"},
+            cost=CheckCost(elapsed_ms=(time.monotonic() - start) * 1000),
+        )
+
+    context = ""
+    if ref.venue:
+        context += f"Published in: {ref.venue}. "
+    if ref.year:
+        context += f"Year: {ref.year}."
+
+    prompt = _RELEVANCE_PROMPT.format(
+        title=ref.title or "Unknown title",
+        context=context,
+        content=content,
+    )
+
+    tokens_used = 0
+    label = RelevanceLabel.CANNOT_DETERMINE
+    confidence = 0.3
+    rationale = ""
+    evidence: dict[str, Any] = {"content_source": "abstract" if abstract else "fetched"}
+
+    try:
+        from citesentry.llm.base import LLMClient
+        response_text = await llm_client.complete(prompt)  # type: ignore[union-attr]
+        tokens_used = len(prompt.split()) + len(response_text.split())
+
+        response_text = response_text.strip()
+        if response_text.startswith("```"):
+            lines = response_text.split("\n")
+            response_text = "\n".join(
+                l for l in lines if not l.startswith("```")
+            ).strip()
+
+        parsed = json.loads(response_text)
+        label = RelevanceLabel(parsed.get("label", "CANNOT_DETERMINE"))
+        confidence = float(parsed.get("confidence", 0.3))
+        rationale = parsed.get("rationale", "")
+        evidence["label"] = label.value
+        evidence["rationale"] = rationale
+
+    except (json.JSONDecodeError, ValueError, KeyError):
+        label = RelevanceLabel.CANNOT_DETERMINE
+        confidence = 0.2
+        evidence["parse_error"] = True
+    except Exception as e:
+        evidence["llm_error"] = str(e)
+        label = RelevanceLabel.CANNOT_DETERMINE
+        confidence = 0.1
+
+    if label == RelevanceLabel.RELEVANT:
+        status = CheckStatus.PASS
+    elif label == RelevanceLabel.PARTIAL:
+        status = CheckStatus.WARN
+    elif label == RelevanceLabel.UNRELATED:
+        status = CheckStatus.FAIL
+    else:
+        status = CheckStatus.WARN
+
+    result = CheckResult(
+        name="relevance",
+        status=status,
+        confidence=confidence,
+        evidence=evidence,
+        cost=CheckCost(tokens_used=tokens_used, elapsed_ms=(time.monotonic() - start) * 1000),
+    )
+
+    if use_cache and cache_key:
+        from citesentry.cache import get_cache
+        cache = get_cache()
+        cache.set("relevance", cache_key, {
+            "status": result.status.value,
+            "confidence": result.confidence,
+            "evidence": evidence,
+        })
+
+    return result

citesentry/checks/url_liveness.py

@@ -0,0 +1,143 @@
+from __future__ import annotations
+
+import asyncio
+import time
+from typing import Any
+
+import httpx
+
+from citesentry.config import get_settings
+from citesentry.models import CheckCost, CheckResult, CheckStatus
+
+_BOT_PROTECTION_HOSTS = {
+    "linkedin.com", "www.linkedin.com",
+    "twitter.com", "x.com", "www.twitter.com",
+    "facebook.com", "www.facebook.com",
+    "instagram.com", "www.instagram.com",
+}
+
+_BOT_PROTECTION_INDICATORS = [
+    "cloudflare", "just a moment", "enable javascript", "checking your browser",
+    "ddos protection", "attention required",
+]
+
+_HEADERS = {
+    "User-Agent": (
+        "Mozilla/5.0 (compatible; citesentry/0.1; citation verification bot; "
+        "+https://github.com/mkassaf/CiteSentry)"
+    )
+}
+
+
+def _is_bot_protected(url: str, status: int, body: str) -> bool:
+    from urllib.parse import urlparse
+    host = urlparse(url).hostname or ""
+    if host in _BOT_PROTECTION_HOSTS:
+        return True
+    if status == 403 and any(ind in body.lower() for ind in _BOT_PROTECTION_INDICATORS):
+        return True
+    return False
+
+
+async def _check_single_url(
+    client: httpx.AsyncClient, url: str
+) -> tuple[str, CheckStatus, dict[str, Any]]:
+    evidence: dict[str, Any] = {"url": url}
+    try:
+        r = await client.head(url, headers=_HEADERS, follow_redirects=True)
+        if r.status_code == 405:
+            r = await client.get(url, headers=_HEADERS, follow_redirects=True)
+        final_url = str(r.url)
+        evidence["status_code"] = r.status_code
+        evidence["final_url"] = final_url
+        evidence["redirected"] = final_url != url
+
+        body = ""
+        if r.status_code == 403:
+            try:
+                body = r.text[:2000]
+            except Exception:
+                pass
+
+        if _is_bot_protected(final_url, r.status_code, body):
+            evidence["bot_protection"] = True
+            return url, CheckStatus.SKIPPED, evidence
+
+        if 200 <= r.status_code < 300:
+            return url, CheckStatus.PASS, evidence
+        else:
+            evidence["error"] = f"HTTP {r.status_code}"
+            return url, CheckStatus.FAIL, evidence
+
+    except httpx.TimeoutException:
+        evidence["error"] = "timeout"
+        return url, CheckStatus.WARN, evidence
+    except httpx.HTTPError as e:
+        evidence["error"] = str(e)
+        return url, CheckStatus.FAIL, evidence
+
+
+async def check_url_liveness(
+    urls: list[str],
+    use_cache: bool = True,
+) -> CheckResult:
+    start = time.monotonic()
+
+    if not urls:
+        return CheckResult(
+            name="url_liveness",
+            status=CheckStatus.SKIPPED,
+            confidence=1.0,
+            evidence={"reason": "no urls"},
+            cost=CheckCost(elapsed_ms=0.0),
+        )
+
+    results: list[dict[str, Any]] = []
+    settings = get_settings()
+
+    async with httpx.AsyncClient(
+        timeout=settings.request_timeout, follow_redirects=True
+    ) as client:
+        for url in urls:
+            if use_cache:
+                from citesentry.cache import get_cache
+                cache = get_cache()
+                cached = cache.get("url_liveness", url)
+                if cached is not None:
+                    results.append({**cached, "from_cache": True})
+                    continue
+
+            _, status, evidence = await _check_single_url(client, url)
+            results.append({"status": status.value, "evidence": evidence})
+
+            if use_cache:
+                from citesentry.cache import get_cache
+                cache = get_cache()
+                cache.set("url_liveness", url, {"status": status.value, "evidence": evidence})
+
+            await asyncio.sleep(settings.politeness_delay)
+
+    elapsed = (time.monotonic() - start) * 1000
+
+    statuses = [CheckStatus(r["status"]) for r in results]
+
+    if any(s == CheckStatus.FAIL for s in statuses):
+        overall = CheckStatus.FAIL
+        confidence = 0.9
+    elif any(s == CheckStatus.WARN for s in statuses):
+        overall = CheckStatus.WARN
+        confidence = 0.7
+    elif all(s == CheckStatus.SKIPPED for s in statuses):
+        overall = CheckStatus.SKIPPED
+        confidence = 0.5
+    else:
+        overall = CheckStatus.PASS
+        confidence = 0.95
+
+    return CheckResult(
+        name="url_liveness",
+        status=overall,
+        confidence=confidence,
+        evidence={"url_results": results, "total_urls": len(urls)},
+        cost=CheckCost(api_calls=len(urls), elapsed_ms=elapsed),
+    )