conflens 0.1.14__py3-none-any.whl

conflens/llm.py

@@ -0,0 +1,336 @@
+"""Provider-agnostic LLM layer.
+
+Three backends share one interface (:meth:`LLMClient.structured`):
+
+* **anthropic** — Claude models via the ``anthropic`` SDK with native structured
+  outputs (``output_config.format``);
+* **openai** — any OpenAI or OpenAI-compatible endpoint via the ``openai`` SDK; and
+* **litellm** — the ``litellm`` SDK, which proxies 100+ providers and supports a
+  custom ``api_base`` (e.g. a self-hosted LiteLLM endpoint).
+
+For the OpenAI-compatible backends we request JSON-object responses and embed the
+target schema in the prompt, then parse defensively — this is the most portable
+approach across arbitrary proxied models. Anthropic uses its stricter native
+schema enforcement.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import random
+import re
+import time
+from typing import Any, Callable, Optional
+
+# ---------------------------------------------------------------------------
+# Provider / model catalogue (suggestions shown in the UI; any string works)
+# ---------------------------------------------------------------------------
+PROVIDERS = ["anthropic", "openai", "litellm"]
+
+DEFAULT_MODELS = {
+    "anthropic": "claude-opus-4-8",
+    "openai": "gpt-5.4",
+    "litellm": "gpt-5.4",  # user supplies, e.g. "openai/gpt-4o" or a proxy model name
+}
+
+MODEL_SUGGESTIONS = {
+    "anthropic": ["claude-opus-4-8", "claude-sonnet-4-6", "claude-haiku-4-5"],
+    "openai": ["gpt-5.4", "gpt-4o-mini", "gpt-4o", "gpt-4.1-mini", "o4-mini"],
+    "litellm": ["gpt-5.4","gpt-5.5","gpt-5.1"],
+}
+
+# Anthropic: the `effort` parameter is rejected (400) on models that don't
+# support it — notably Haiku 4.5. Only send it for models that accept it.
+_EFFORT_MODELS = {"claude-opus-4-8", "claude-sonnet-4-6"}
+
+
+class LLMError(RuntimeError):
+    pass
+
+
+# ---------------------------------------------------------------------------
+# Transient-error retry (rate limits, overload, 5xx, timeouts, connection)
+# ---------------------------------------------------------------------------
+_MAX_ATTEMPTS = 4
+_TRANSIENT_STATUS = {408, 409, 425, 429, 500, 502, 503, 504, 529}
+_TRANSIENT_HINTS = (
+    "rate limit",
+    "overloaded",
+    "timeout",
+    "timed out",
+    "temporarily unavailable",
+    "connection",
+    "econnreset",
+    "too many requests",
+)
+
+
+def _is_transient(exc: Exception) -> bool:
+    """Heuristically decide whether an LLM/provider error is worth retrying.
+
+    Works across SDKs without importing them: checks a numeric status code if
+    present, otherwise the exception class name / message.
+    """
+    status = getattr(exc, "status_code", None) or getattr(exc, "status", None)
+    if isinstance(status, int) and status in _TRANSIENT_STATUS:
+        return True
+    name = type(exc).__name__.lower()
+    if any(k in name for k in ("ratelimit", "timeout", "connection", "overloaded", "apistatus")):
+        # APIStatusError with a non-transient status is filtered above by the
+        # status check returning False only when a status is present; here it
+        # has no known status, so treat connection/timeout/ratelimit as transient.
+        if "apistatus" in name and not isinstance(status, int):
+            return False
+        return True
+    msg = str(exc).lower()
+    return any(h in msg for h in _TRANSIENT_HINTS)
+
+
+def _retry(fn: Callable[[], Any], *, max_attempts: int = _MAX_ATTEMPTS) -> Any:
+    """Call ``fn`` with exponential backoff on transient errors."""
+    last: Optional[Exception] = None
+    for attempt in range(max_attempts):
+        try:
+            return fn()
+        except Exception as e:  # noqa: BLE001 - provider exceptions vary
+            last = e
+            if attempt == max_attempts - 1 or not _is_transient(e):
+                raise
+            delay = min(1.5 * (2 ** attempt), 20.0) + random.uniform(0, 0.75)
+            time.sleep(delay)
+    assert last is not None
+    raise last
+
+
+# ---------------------------------------------------------------------------
+# Helpers shared by the OpenAI-compatible backends
+# ---------------------------------------------------------------------------
+def _schema_hint(schema: dict[str, Any]) -> str:
+    return (
+        "Respond with ONLY a single JSON object — no prose, no markdown code "
+        "fences — that conforms to this JSON Schema:\n"
+        + json.dumps(schema)
+    )
+
+
+def _extract_json(text: str) -> Any:
+    """Parse a JSON object from a model response, tolerating fences/prose."""
+    if text is None:
+        raise LLMError("Empty response from the model.")
+    s = text.strip()
+    if s.startswith("```"):
+        s = re.sub(r"^```[a-zA-Z0-9]*\s*", "", s)
+        s = re.sub(r"\s*```$", "", s)
+    try:
+        return json.loads(s)
+    except json.JSONDecodeError:
+        i, j = s.find("{"), s.rfind("}")
+        if 0 <= i < j:
+            try:
+                return json.loads(s[i : j + 1])
+            except json.JSONDecodeError as e:
+                raise LLMError(f"Model did not return valid JSON: {e}") from e
+        raise LLMError("Model did not return a JSON object.")
+
+
+# ---------------------------------------------------------------------------
+# Base + provider implementations
+# ---------------------------------------------------------------------------
+class LLMClient:
+    """Abstract base. Subclasses implement :meth:`structured`."""
+
+    model: str = ""
+
+    def structured(
+        self,
+        system: str,
+        user: str,
+        schema: dict[str, Any],
+        max_tokens: int = 8000,
+        effort: str = "medium",
+    ) -> Any:
+        raise NotImplementedError
+
+
+class AnthropicClient(LLMClient):
+    def __init__(
+        self, model: str, api_key: Optional[str] = None, base_url: Optional[str] = None
+    ) -> None:
+        try:
+            import anthropic
+        except ImportError as e:  # pragma: no cover
+            raise LLMError("The 'anthropic' package is not installed.") from e
+        self._anthropic = anthropic
+        self.model = model
+        kwargs: dict[str, Any] = {}
+        if api_key:
+            kwargs["api_key"] = api_key
+        if base_url:
+            kwargs["base_url"] = base_url
+        try:
+            self._client = anthropic.Anthropic(**kwargs)
+        except Exception as e:
+            raise LLMError(f"Could not initialise Anthropic client: {e}") from e
+
+    def structured(self, system, user, schema, max_tokens=8000, effort="medium"):
+        output_config: dict[str, Any] = {
+            "format": {"type": "json_schema", "schema": schema}
+        }
+        if self.model in _EFFORT_MODELS:
+            output_config["effort"] = effort
+        def _create():
+            return self._client.messages.create(
+                model=self.model,
+                max_tokens=max_tokens,
+                system=system,
+                messages=[{"role": "user", "content": user}],
+                output_config=output_config,
+            )
+
+        try:
+            resp = _retry(_create)
+        except self._anthropic.APIStatusError as e:
+            raise LLMError(f"Anthropic API error ({e.status_code}): {e.message}") from e
+        except self._anthropic.APIConnectionError as e:
+            raise LLMError(f"Network error talking to Anthropic: {e}") from e
+
+        if resp.stop_reason == "refusal":
+            raise LLMError("The model declined to respond to this request.")
+        text = next((b.text for b in resp.content if b.type == "text"), None)
+        return _extract_json(text)
+
+
+class OpenAIClient(LLMClient):
+    """OpenAI or any OpenAI-compatible endpoint (via ``base_url``)."""
+
+    def __init__(
+        self, model: str, api_key: Optional[str] = None, base_url: Optional[str] = None
+    ) -> None:
+        try:
+            from openai import OpenAI
+        except ImportError as e:
+            raise LLMError(
+                "The 'openai' package is not installed. Install it with "
+                "`uv sync --extra openai`."
+            ) from e
+        self.model = model
+        kwargs: dict[str, Any] = {
+            "api_key": api_key or os.environ.get("OPENAI_API_KEY") or "missing"
+        }
+        if base_url:
+            kwargs["base_url"] = base_url
+        try:
+            self._client = OpenAI(**kwargs)
+        except Exception as e:
+            raise LLMError(f"Could not initialise OpenAI client: {e}") from e
+
+    def structured(self, system, user, schema, max_tokens=8000, effort="medium"):
+        messages = [
+            {"role": "system", "content": system},
+            {"role": "user", "content": user + "\n\n" + _schema_hint(schema)},
+        ]
+        content = _openai_compat_call(
+            self._client.chat.completions.create, self.model, messages, max_tokens
+        )
+        return _extract_json(content)
+
+
+class LiteLLMClient(LLMClient):
+    """Unified access to many providers via the litellm SDK + a custom endpoint."""
+
+    def __init__(
+        self, model: str, api_key: Optional[str] = None, base_url: Optional[str] = None
+    ) -> None:
+        try:
+            import litellm
+        except ImportError as e:
+            raise LLMError(
+                "The 'litellm' package is not installed. Install it with "
+                "`uv sync --extra litellm`."
+            ) from e
+        if not model:
+            raise LLMError("A model name is required for the LiteLLM provider.")
+        self._litellm = litellm
+        self.model = model
+        self._api_key = api_key
+        self._base_url = base_url
+
+    def structured(self, system, user, schema, max_tokens=8000, effort="medium"):
+        messages = [
+            {"role": "system", "content": system},
+            {"role": "user", "content": user + "\n\n" + _schema_hint(schema)},
+        ]
+        extra: dict[str, Any] = {}
+        if self._base_url:
+            extra["api_base"] = self._base_url
+        if self._api_key:
+            extra["api_key"] = self._api_key
+        content = _openai_compat_call(
+            self._litellm.completion, self.model, messages, max_tokens, **extra
+        )
+        return _extract_json(content)
+
+
+def _openai_compat_call(create_fn, model, messages, max_tokens, **extra) -> str:
+    """Call an OpenAI-style ``create`` with graceful fallbacks.
+
+    Tries JSON-object mode + ``temperature=0`` first, then progressively drops
+    parameters that some models/endpoints reject (reasoning models disallow
+    ``temperature``; some proxies disallow ``response_format``).
+    """
+    attempts = [
+        {"response_format": {"type": "json_object"}, "temperature": 0},
+        {"temperature": 0},
+        {},
+    ]
+    last_err: Optional[Exception] = None
+    for opts in attempts:
+        def _create():
+            resp = create_fn(
+                model=model,
+                messages=messages,
+                max_tokens=max_tokens,
+                **opts,
+                **extra,
+            )
+            return resp.choices[0].message.content
+
+        try:
+            # Retry transient errors (rate limit / 5xx / timeout) for these opts;
+            # a non-transient error (e.g. param rejected) falls through to the
+            # next, less-demanding attempt.
+            return _retry(_create)
+        except Exception as e:  # noqa: BLE001 - provider exceptions vary widely
+            last_err = e
+    raise LLMError(f"LLM request failed: {last_err}")
+
+
+# ---------------------------------------------------------------------------
+# Factory + key detection
+# ---------------------------------------------------------------------------
+def make_client(
+    provider: str,
+    model: str,
+    api_key: Optional[str] = None,
+    base_url: Optional[str] = None,
+) -> LLMClient:
+    api_key = (api_key or "").strip() or None
+    base_url = (base_url or "").strip() or None
+    if provider == "anthropic":
+        return AnthropicClient(model, api_key, base_url)
+    if provider == "openai":
+        return OpenAIClient(model, api_key, base_url)
+    if provider == "litellm":
+        return LiteLLMClient(model, api_key, base_url)
+    raise LLMError(f"Unknown provider: {provider}")
+
+
+def env_key_for(provider: str) -> Optional[str]:
+    if provider == "anthropic":
+        return os.environ.get("ANTHROPIC_API_KEY") or os.environ.get("ANTHROPIC_AUTH_TOKEN")
+    if provider == "openai":
+        return os.environ.get("OPENAI_API_KEY")
+    if provider == "litellm":
+        return os.environ.get("LITELLM_API_KEY") or os.environ.get("OPENAI_API_KEY")
+    return None

conflens/models.py

@@ -0,0 +1,116 @@
+"""Shared data structures used across the pipeline."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import asdict, dataclass, field
+from typing import Optional
+
+
+@dataclass
+class Paper:
+    """A single paper scraped from the anthology."""
+
+    paper_id: str          # e.g. "2024.acl-long.1"
+    title: str
+    url: str               # canonical landing page
+    pdf_url: str
+    authors: list[str] = field(default_factory=list)
+    abstract: str = ""
+
+    # Filled in by the classifier
+    relevant: Optional[bool] = None
+    confidence: Optional[float] = None
+    reason: str = ""
+
+    # Filled in by topic modelling — a paper may belong to more than one topic
+    # (primary first).
+    topic_ids: list[int] = field(default_factory=list)
+
+    # Filled in by near-duplicate detection: the representative paper_id of the
+    # duplicate group (None if this paper is unique or the group's representative).
+    duplicate_of: Optional[str] = None
+
+    @property
+    def topic_id(self) -> Optional[int]:
+        """Primary topic (first assigned), for backward-compatible access."""
+        return self.topic_ids[0] if self.topic_ids else None
+
+    @property
+    def year(self) -> Optional[int]:
+        """Best-effort publication year parsed from the paper id (e.g. 2024.acl…)."""
+        m = re.match(r"(19|20)\d{2}", self.paper_id or "")
+        return int(m.group(0)) if m else None
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "Paper":
+        fields = set(cls.__dataclass_fields__)
+        return cls(**{k: v for k, v in d.items() if k in fields})
+
+
+@dataclass
+class Topic:
+    """A discovered topic within the selected theme."""
+
+    topic_id: int
+    name: str
+    description: str = ""
+    findings: list[str] = field(default_factory=list)  # common findings across the topic's papers
+    paper_ids: list[str] = field(default_factory=list)
+
+    @property
+    def count(self) -> int:
+        return len(self.paper_ids)
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "Topic":
+        fields = set(cls.__dataclass_fields__)
+        return cls(**{k: v for k, v in d.items() if k in fields})
+
+
+@dataclass
+class AnalysisResult:
+    """The full output of a run, ready to render."""
+
+    theme: str
+    event_url: str
+    scanned: int = 0
+    papers: list[Paper] = field(default_factory=list)        # all scanned
+    relevant_papers: list[Paper] = field(default_factory=list)
+    topics: list[Topic] = field(default_factory=list)
+    duplicate_groups: int = 0                                # near-duplicate clusters found
+    min_confidence: float = 0.5                              # threshold applied at run time (display default)
+
+    def to_dict(self) -> dict:
+        return {
+            "theme": self.theme,
+            "event_url": self.event_url,
+            "scanned": self.scanned,
+            "relevant_count": len(self.relevant_papers),
+            "duplicate_groups": self.duplicate_groups,
+            "min_confidence": self.min_confidence,
+            "topics": [t.to_dict() for t in self.topics],
+            "papers": [p.to_dict() for p in self.relevant_papers],
+        }
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "AnalysisResult":
+        """Rebuild a result from its ``to_dict`` form (for save/load of a run)."""
+        relevant = [Paper.from_dict(p) for p in d.get("papers", [])]
+        result = cls(
+            theme=d.get("theme", ""),
+            event_url=d.get("event_url", ""),
+            scanned=int(d.get("scanned", 0)),
+            papers=relevant,                 # all scanned isn't persisted; relevant is enough to render
+            relevant_papers=relevant,
+            topics=[Topic.from_dict(t) for t in d.get("topics", [])],
+            duplicate_groups=int(d.get("duplicate_groups", 0)),
+            min_confidence=float(d.get("min_confidence", 0.5)),
+        )
+        return result

conflens/pipeline.py

@@ -0,0 +1,207 @@
+"""Orchestrates scrape -> classify -> topic-model into one analysis run."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Optional
+
+from . import classifier, dedup
+from . import topics as topic_mod
+from .llm import make_client
+from .models import AnalysisResult
+from .sources import make_source
+
+
+class AnalysisCancelled(Exception):
+    """Raised cooperatively when the user cancels a run."""
+
+
+@dataclass
+class Progress:
+    """Mutable progress state shared with the UI."""
+
+    stage: str = "idle"
+    message: str = ""
+    fraction: float = 0.0          # 0..1 within the current stage
+    log: list[str] = field(default_factory=list)
+    done: bool = False
+    error: Optional[str] = None
+    cancelled: bool = False        # set by the UI to request cooperative cancel
+
+    def set(self, stage: str, message: str, fraction: float = 0.0) -> None:
+        self.stage = stage
+        self.message = message
+        self.fraction = fraction
+        self.log.append(message)
+
+    def check_cancel(self) -> None:
+        if self.cancelled:
+            raise AnalysisCancelled()
+
+
+@dataclass
+class AnalysisConfig:
+    source: str = "aclanthology"   # "aclanthology" | "ijcai"
+    base_url: str = "https://aclanthology.org"
+    event: str = "acl-2026"
+    theme: str = "Agentic AI"
+    theme_definition: str = ""     # optional clarification of what the theme includes/excludes
+    provider: str = "openai"    # "anthropic" | "openai" | "litellm"
+    model: str = "gpt-5.4"
+    llm_base_url: str = ""         # custom endpoint (LiteLLM / OpenAI-compatible)
+    api_key: str = ""              # overrides the provider's env var if set
+    max_papers: int = 150
+    n_topics: int = 8
+    min_confidence: float = 0.5
+    topic_backend: str = "llm"     # "llm" | "bertopic"
+    refresh: bool = False          # bypass the scrape cache and refetch from source
+    source_auth: dict = field(default_factory=dict)  # per-source creds (OpenReview)
+
+
+def run_analysis(
+    cfg: AnalysisConfig,
+    progress: Progress,
+    cache_dir: Optional[str] = None,
+) -> AnalysisResult:
+    """Execute the full pipeline. Designed to run in a worker thread."""
+    scraper = make_source(
+        cfg.source, base_url=cfg.base_url, cache_dir=cache_dir, auth=cfg.source_auth
+    )
+    event_url = scraper.resolve_url(cfg.event)
+    result = AnalysisResult(
+        theme=cfg.theme, event_url=event_url, min_confidence=cfg.min_confidence
+    )
+
+    try:
+        # 1. List papers ------------------------------------------------
+        origin = "source" if cfg.refresh else "cache or source"
+        progress.set("listing", f"Fetching paper list from {event_url} ({origin})", 0.0)
+        papers = scraper.list_papers(cfg.event, force_refresh=cfg.refresh)
+        if not papers:
+            hints = {
+                "aclanthology": (
+                    " The proceedings may not be published yet — try a past event "
+                    "such as 'acl-2024'."
+                ),
+                "emnlp": (
+                    " The proceedings may not be published yet — try a past event "
+                    "such as 'emnlp-2023'."
+                ),
+                "naacl": (
+                    " The proceedings may not be published yet — try a past event "
+                    "such as 'naacl-2024'."
+                ),
+                "ijcai": " Check the URL points at the accepted-papers page.",
+                "openreview": (
+                    " Check the venue id (e.g. 'ICLR.cc/2024/Conference' or "
+                    "'NeurIPS.cc/2024/Conference') — decisions may not be posted yet."
+                ),
+                "pscc": (
+                    " PSCC is biennial — try a year that was held, e.g. '2024' or "
+                    "'2022'."
+                ),
+                "isgteurope": (
+                    " Check the venue + year (e.g. 'isgteurope 2024') — DBLP may "
+                    "not have indexed that edition yet."
+                ),
+            }
+            hint = hints.get(cfg.source, "")
+            progress.set("listing", "No papers found on that page." + hint, 1.0)
+            progress.done = True
+            return result
+        if cfg.max_papers and len(papers) > cfg.max_papers:
+            papers = papers[: cfg.max_papers]
+        progress.set("listing", f"Found {len(papers)} papers.", 1.0)
+        progress.check_cancel()
+
+        # 2. Abstracts --------------------------------------------------
+        def abs_prog(done: int, total: int) -> None:
+            progress.check_cancel()
+            progress.set("abstracts", f"Fetching abstracts ({done}/{total})", done / max(total, 1))
+
+        scraper.enrich_abstracts(papers, progress=abs_prog, force_refresh=cfg.refresh)
+        result.papers = papers
+        result.scanned = len(papers)
+        result.duplicate_groups = dedup.annotate_duplicates(papers)
+        if result.duplicate_groups:
+            progress.set("listing", f"Flagged {result.duplicate_groups} near-duplicate group(s).", 1.0)
+        progress.check_cancel()
+
+        # 3. Classify ---------------------------------------------------
+        client = make_client(cfg.provider, cfg.model, cfg.api_key, cfg.llm_base_url)
+
+        def cls_prog(done: int, total: int) -> None:
+            progress.set(
+                "classify", f"Classifying for '{cfg.theme}' ({done}/{total})", done / max(total, 1)
+            )
+
+        # Keep every paper the model judges relevant (threshold 0) so the UI can
+        # re-apply the confidence cut-off live without a re-run. The run's
+        # ``min_confidence`` is carried on the result as the default display cut.
+        relevant = classifier.classify_papers(
+            client,
+            cfg.theme,
+            papers,
+            min_confidence=0.0,
+            progress=cls_prog,
+            cache_dir=cache_dir,
+            cache_sig=f"{cfg.provider}:{cfg.model}",
+            force_refresh=cfg.refresh,
+            cancel=progress.check_cancel,
+            theme_definition=cfg.theme_definition,
+        )
+        result.relevant_papers = relevant
+        at_threshold = sum(1 for p in relevant if (p.confidence or 0) >= cfg.min_confidence)
+        progress.set(
+            "classify",
+            f"{at_threshold} of {len(papers)} papers match the theme "
+            f"(≥{cfg.min_confidence:.2f} confidence).",
+            1.0,
+        )
+
+        if not relevant:
+            progress.set("topics", "No matching papers — nothing to model.", 1.0)
+            progress.done = True
+            return result
+
+        # 4. Topic modelling --------------------------------------------
+        def top_prog(done: int, total: int) -> None:
+            progress.set("topics", f"Assigning topics ({done}/{total})", done / max(total, 1))
+
+        progress.set("topics", "Discovering topics…", 0.0)
+        result.topics = topic_mod.model_topics(
+            cfg.topic_backend,
+            client,
+            cfg.theme,
+            relevant,
+            n_topics=cfg.n_topics,
+            progress=top_prog,
+            theme_definition=cfg.theme_definition,
+        )
+        progress.check_cancel()
+
+        # 5. Per-topic synthesis (description + common findings) --------
+        def sum_prog(done: int, total: int) -> None:
+            progress.set("summarize", f"Summarising topics ({done}/{total})", done / max(total, 1))
+
+        progress.set("summarize", "Summarising topics…", 0.0)
+        topic_mod.summarize_topics(
+            client,
+            cfg.theme,
+            result.topics,
+            relevant,
+            progress=sum_prog,
+            cache_dir=cache_dir,
+            cache_sig=f"{cfg.provider}:{cfg.model}",
+            force_refresh=cfg.refresh,
+            cancel=progress.check_cancel,
+            theme_definition=cfg.theme_definition,
+        )
+
+        progress.set("done", f"Done — {len(result.topics)} topics across {len(relevant)} papers.", 1.0)
+        progress.done = True
+        return result
+    except AnalysisCancelled:
+        progress.set("cancelled", "Cancelled.", progress.fraction)
+        progress.done = True
+        return result