second-read 0.1.1__py3-none-any.whl

secondread/agents/factcheck/schemas.py

@@ -0,0 +1,124 @@
+"""Structured-output schemas the fact-checker asks the LLM for.
+
+These are internal to the fact-checker; they never leave the package. Code
+re-validates everything the model returns (URLs must be ones we retrieved,
+quotes must appear in the retrieved text, verdicts must be settled by the
+evidence), so a confused or manipulated model cannot mark a claim verified on
+its own say-so.
+"""
+
+from __future__ import annotations
+
+from enum import StrEnum
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+
+class QueryPlan(BaseModel):
+    """Reply to ``factcheck.queries``: search queries for one claim, best first."""
+
+    queries: list[str] = Field(default_factory=list)
+    rationale: str = ""
+
+
+class Stance(StrEnum):
+    """How one source bears on the claim."""
+
+    SUPPORTS = "supports"
+    CONTRADICTS = "contradicts"
+    IRRELEVANT = "irrelevant"
+
+
+class NextStep(StrEnum):
+    """What the research loop should do after assessing sources."""
+
+    STOP = "stop"
+    """Nothing more to gain (or the claim is settled)."""
+    REFINE = "refine"
+    """Search again with ``next_query``."""
+    FOLLOW = "follow"
+    """Fetch ``follow_url`` (usually the primary source a page cites)."""
+
+
+class SourceType(StrEnum):
+    """What kind of publication a source is (the model's reading, checked in code)."""
+
+    PRIMARY = "primary"
+    """The original record itself (official table, filing, transcript, dataset)."""
+    REFERENCE = "reference"
+    """An edited encyclopedia or reference work."""
+    MAJOR_NEWS = "major_news"
+    """An established national or international news organisation."""
+    OFFICIAL = "official"
+    """A government, governing body, league, or the organisation the claim is about."""
+    SPECIALIST = "specialist"
+    """A specialist publication or database with editorial standards."""
+    BLOG = "blog"
+    """A personal, fan or self-published site."""
+    SOCIAL = "social"
+    """Social media or other user-generated content."""
+    UNKNOWN = "unknown"
+
+
+REPUTABLE_SOURCE_TYPES = frozenset(
+    {SourceType.PRIMARY, SourceType.REFERENCE, SourceType.MAJOR_NEWS, SourceType.OFFICIAL}
+)
+"""Types that can verify (or refute) an uncontested claim on their own."""
+
+
+class SourceAssessment(BaseModel):
+    """The model's reading of one retrieved source."""
+
+    url: str
+    stance: Stance
+    source_type: SourceType = SourceType.UNKNOWN
+    is_primary: bool = False
+    quote: str = ""
+    """Verbatim sentence from the source that supports the stance."""
+
+
+class Assessment(BaseModel):
+    """Reply to ``factcheck.assess``: per-source stances and the next step."""
+
+    sources: list[SourceAssessment] = Field(default_factory=list)
+    next_step: NextStep = NextStep.STOP
+    next_query: str | None = None
+    follow_url: str | None = None
+    summary: str = ""
+    unverified_parts: list[str] = Field(default_factory=list)
+    """Checkable parts of the claim that no source seen so far confirms or
+    contradicts (a few words each). Empty when every part is covered."""
+
+
+class PartVerdict(BaseModel):
+    """The judge's verdict on one checkable part of a claim."""
+
+    part: str
+    verdict: Literal["verified", "wrong", "unsupported"]
+
+
+class Judgment(BaseModel):
+    """Reply to ``factcheck.judge``: the final verdict proposal for one claim."""
+
+    verdict: Literal["verified", "wrong", "unsupported"]
+    confidence: float = Field(default=0.5, ge=0.0, le=1.0)
+    explanation: str = ""
+    correction: str | None = None
+    """For wrong claims: what the evidence says instead."""
+    evidence_urls: list[str] = Field(default_factory=list)
+    parts: list[PartVerdict] = Field(default_factory=list)
+    """A verdict for each checkable part of the claim (number, date, name,
+    place, cause, sequence). The claim is verified only if every part is."""
+    contested: bool = True
+    """For a "wrong" verdict: True if any evidence supports the specific
+    detail the contradicting evidence disputes. Defaults to True (the cautious
+    reading) when the model does not say."""
+
+
+class DebateReply(BaseModel):
+    """Reply to ``factcheck.debate``: one response to the opposing evidence."""
+
+    argument: str
+    concedes: bool = False
+    evidence_urls: list[str] = Field(default_factory=list)

secondread/agents/factcheck/sources.py

@@ -0,0 +1,295 @@
+"""Deterministic helpers for handling retrieved sources.
+
+Everything here treats page text as untrusted data: it is searched, sliced
+and quoted, never interpreted.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from datetime import datetime
+from urllib.parse import urlsplit
+
+from secondread.agents.factcheck.schemas import REPUTABLE_SOURCE_TYPES, SourceType, Stance
+from secondread.contracts import Evidence, utcnow
+
+MAX_PASSAGES = 5
+"""Passages kept per page by ``find_in_page``."""
+
+MAX_PASSAGE_CHARS = 400
+MAX_EXCERPT_CHARS = 500
+
+_WORD = re.compile(r"[a-z0-9][a-z0-9.,%-]*", re.IGNORECASE)
+_SENTENCE = re.compile(r"(?<=[.!?])\s+|\n+")
+_STOPWORD_TEXT = (
+    "a an and are as at be by for from has have in is it its of on or that the their "
+    "there this to was were with than any other more most"
+)
+_STOPWORDS = frozenset(_STOPWORD_TEXT.split())
+
+_PRIMARY_HOST_SUFFIXES = (".gov", ".edu", ".int", ".mil")
+_PRIMARY_HOSTS = frozenset(
+    {"doi.org", "arxiv.org", "pubmed.ncbi.nlm.nih.gov", "data.worldbank.org", "sec.gov"}
+)
+
+_LOW_QUALITY_HOSTS = frozenset(
+    {
+        "facebook.com",
+        "instagram.com",
+        "youtube.com",
+        "youtu.be",
+        "tiktok.com",
+        "x.com",
+        "twitter.com",
+        "reddit.com",
+        "pinterest.com",
+        "quora.com",
+        "linkedin.com",
+        "threads.net",
+    }
+)
+"""Social and user-generated hosts. Shown as evidence, but they never count
+towards settling a claim."""
+
+_REPUTABLE_HOSTS = frozenset(
+    {
+        "wikipedia.org",
+        "britannica.com",
+        "bbc.com",
+        "bbc.co.uk",
+        "reuters.com",
+        "apnews.com",
+        "nytimes.com",
+        "theguardian.com",
+        "washingtonpost.com",
+        "ft.com",
+        "economist.com",
+        "espn.com",
+        "skysports.com",
+        "uefa.com",
+        "fifa.com",
+        "premierleague.com",
+        "history.com",
+        "nature.com",
+        "science.org",
+        "who.int",
+        "un.org",
+    }
+)
+"""Edited reference works, major news organisations and official bodies. One
+of these is enough to verify a claim nothing contradicts."""
+
+_INJECTION = re.compile(
+    r"ignore\s+(all\s+|any\s+)?(previous|prior|above)\s+instructions"
+    r"|disregard\s+(all\s+|the\s+)?(previous|prior|above)"
+    r"|(mark|label|rate|classify)\s+(this|the)\s+(claim\s+)?(as\s+)?(verified|true|correct)"
+    r"|you\s+are\s+now\s+"
+    r"|system\s+prompt"
+    r"|as\s+an?\s+(ai|language\s+model|fact-?checker)[, ]+you\s+must",
+    re.IGNORECASE,
+)
+
+
+def domain(url: str) -> str:
+    """Host of ``url`` without a leading ``www.`` (used for source independence)."""
+    host = (urlsplit(url).hostname or url).lower()
+    return host.removeprefix("www.")
+
+
+def _host_in(url: str, hosts: frozenset[str]) -> bool:
+    host = domain(url)
+    return any(host == h or host.endswith("." + h) for h in hosts)
+
+
+def is_low_quality(url: str) -> bool:
+    """True for social and user-generated hosts."""
+    return _host_in(url, _LOW_QUALITY_HOSTS)
+
+
+def is_reputable(url: str) -> bool:
+    """True for edited reference works, major news and official bodies."""
+    host = domain(url)
+    return (
+        _host_in(url, _REPUTABLE_HOSTS)
+        or host in _PRIMARY_HOSTS
+        or host.endswith(_PRIMARY_HOST_SUFFIXES)
+    )
+
+
+def is_http_url(url: str) -> bool:
+    """True for absolute http(s) URLs."""
+    parts = urlsplit(url)
+    return parts.scheme in {"http", "https"} and bool(parts.hostname)
+
+
+def primary_hint(url: str) -> bool:
+    """Cheap guess that a URL is a primary source (used only to order fetches)."""
+    host = domain(url)
+    path = urlsplit(url).path.lower()
+    return (
+        host in _PRIMARY_HOSTS
+        or host.endswith(_PRIMARY_HOST_SUFFIXES)
+        or host.startswith("data.")
+        or path.endswith(".pdf")
+    )
+
+
+def looks_like_injection(text: str) -> bool:
+    """True if the text contains instructions aimed at the reviewer.
+
+    Such pages are dropped as evidence: a source that tries to steer the
+    fact-checker is not trustworthy evidence of anything.
+    """
+    return bool(_INJECTION.search(text))
+
+
+_TERM_PREFIX = 6
+"""Words are compared on their first letters, so spelling and inflection
+variants match ("refueling"/"refuelling", "charter"/"chartered")."""
+
+
+def _terms(text: str) -> set[str]:
+    terms: set[str] = set()
+    for raw in _WORD.findall(text):
+        word = raw.strip(".,-").lower()
+        if len(word) <= 1 or word in _STOPWORDS:
+            continue
+        terms.add(word if any(ch.isdigit() for ch in word) else word[:_TERM_PREFIX])
+    return terms
+
+
+_NUMBER_WORDS = (
+    r"one|two|three|four|five|six|seven|eight|nine|ten|eleven|twelve|twenty|thirty|"
+    r"forty|fifty|hundred|thousand|million|billion|half|third|quarter|twice|percent"
+)
+_CHECKABLE_DETAIL = re.compile(rf"\d|\b({_NUMBER_WORDS})\b", re.IGNORECASE)
+
+
+def has_checkable_detail(text: str) -> bool:
+    """True if ``text`` states a number, year or quantity that can be checked.
+
+    Used to fact-check argumentative claims that still carry facts ("Spain won
+    Euro 2008 by passing teams to death"), not just claims typed as factual.
+    """
+    return bool(_CHECKABLE_DETAIL.search(text))
+
+
+def find_in_page(text: str, claim: str, query: str = "") -> list[str]:
+    """Return up to ``MAX_PASSAGES`` sentences of ``text`` most relevant to the claim.
+
+    Scores sentences by term overlap with the claim (and query); numbers count
+    double since factual claims usually hinge on them. Passages keep page
+    order so context reads naturally.
+    """
+    wanted = _terms(claim) | _terms(query)
+    if not wanted:
+        return []
+    numbers = {t for t in wanted if any(ch.isdigit() for ch in t)}
+    scored: list[tuple[float, int, str]] = []
+    for index, raw in enumerate(_SENTENCE.split(text)):
+        sentence = " ".join(raw.split())
+        if not sentence:
+            continue
+        terms = _terms(sentence)
+        score = len(terms & wanted) + len(terms & numbers)
+        if score > 0:
+            scored.append((score, index, sentence[:MAX_PASSAGE_CHARS]))
+    best = sorted(scored, key=lambda s: (-s[0], s[1]))[:MAX_PASSAGES]
+    return [s for _, _, s in sorted(best, key=lambda s: s[1])]
+
+
+def _norm(text: str) -> str:
+    return " ".join(text.split()).casefold()
+
+
+def verified_quote(quote: str, source_text: str, fallback: str) -> str:
+    """``quote`` if it appears verbatim in ``source_text``, else ``fallback``.
+
+    Keeps evidence excerpts honest: an excerpt is always text we retrieved.
+    """
+    quote = " ".join(quote.split())
+    if quote and _norm(quote) in _norm(source_text):
+        return quote[:MAX_EXCERPT_CHARS]
+    return " ".join(fallback.split())[:MAX_EXCERPT_CHARS]
+
+
+@dataclass
+class Source:
+    """One retrieved source the loop has read (a fetched page or a snippet)."""
+
+    url: str
+    title: str
+    text: str
+    """The retrieved text excerpts are validated against (untrusted)."""
+    passages: list[str]
+    """What the model is shown (a few relevant sentences)."""
+    kind: str = "page"
+    """``page``, ``snippet``, ``prior-evidence`` or ``counter-evidence``."""
+    can_be_primary: bool = True
+    """False when we only saw a snippet, so we cannot confirm it is primary."""
+    suspicious: bool = False
+    retrieved_at: datetime = field(default_factory=utcnow)
+    stance: Stance | None = None
+    evidence: Evidence | None = None
+    source_type: SourceType = SourceType.UNKNOWN
+    """The model's reading of what kind of publication this is."""
+
+    @property
+    def domain(self) -> str:
+        """Host used to judge independence between sources."""
+        return domain(self.url)
+
+
+def relevant(sources: list[Source], stance: Stance) -> list[Source]:
+    """Assessed sources with ``stance`` and evidence, primary sources first."""
+    hits = [s for s in sources if s.stance is stance and s.evidence is not None]
+    return sorted(hits, key=lambda s: not (s.evidence and s.evidence.is_primary))
+
+
+def settles(sources: list[Source], stance: Stance) -> bool:
+    """True if a primary source, or two independent sources, take ``stance``.
+
+    Social and user-generated hosts do not count towards the two.
+    """
+    hits = relevant(sources, stance)
+    if any(s.evidence is not None and s.evidence.is_primary for s in hits):
+        return True
+    return len({s.domain for s in hits if not is_low_quality(s.url)}) >= 2
+
+
+def is_reputable_source(source: Source) -> bool:
+    """True if one fetched ``source`` can verify or refute an uncontested claim.
+
+    Either its host is on the known list, or the assessing model classed it as
+    a primary record, reference work, major news organisation or official
+    body. Social and user-generated hosts never qualify, whatever the model
+    says, and search snippets never do (the page itself must have been read).
+    """
+    if not source.can_be_primary or is_low_quality(source.url):
+        return False
+    return is_reputable(source.url) or source.source_type in REPUTABLE_SOURCE_TYPES
+
+
+def reputably_supported(sources: list[Source]) -> bool:
+    """True if a reputable source supports the claim and nothing contradicts it.
+
+    The relaxed rule for uncontested facts: one edited, reputable source that
+    was actually fetched (not just a search snippet) is enough when no
+    retrieved source disagrees.
+    """
+    if relevant(sources, Stance.CONTRADICTS):
+        return False
+    return any(is_reputable_source(s) for s in relevant(sources, Stance.SUPPORTS))
+
+
+def reputably_contradicted(sources: list[Source]) -> bool:
+    """True if a reputable source that was actually fetched contradicts the claim."""
+    return any(is_reputable_source(s) for s in relevant(sources, Stance.CONTRADICTS))
+
+
+def shared_terms(claim: str, text: str) -> int:
+    """How many of the claim's terms appear in ``text`` (numbers count double)."""
+    wanted = _terms(claim)
+    found = wanted & _terms(text)
+    return len(found) + sum(1 for t in found if any(ch.isdigit() for ch in t))

secondread/agents/originality/__init__.py

@@ -0,0 +1,29 @@
+"""Originality checker agent.
+
+Samples distinctive sentences, searches for near-matches and reports possible
+matches with URLs. Every finding is heuristic (``Finding.heuristic``) with
+``Severity.CONSIDER``; no ledger updates.
+"""
+
+from secondread.agents.originality.agent import (
+    DEFAULT_SAMPLE_SIZE,
+    DEFAULT_THRESHOLD,
+    OriginalityAgent,
+    build_query,
+)
+from secondread.agents.originality.sentences import Sentence, distinctive_sentences, split_sentences
+from secondread.agents.originality.similarity import Match, normalize_url, same_url, similarity
+
+__all__ = [
+    "DEFAULT_SAMPLE_SIZE",
+    "DEFAULT_THRESHOLD",
+    "Match",
+    "OriginalityAgent",
+    "Sentence",
+    "build_query",
+    "distinctive_sentences",
+    "normalize_url",
+    "same_url",
+    "similarity",
+    "split_sentences",
+]