conflens 0.1.14__tar.gz

conflens-0.1.14/.dockerignore

@@ -0,0 +1,12 @@
+.git
+.gitignore
+.venv
+venv
+__pycache__
+*.pyc
+*.egg-info
+.cache
+build
+dist
+*.whl
+docs

conflens-0.1.14/.env.example

@@ -0,0 +1,41 @@
+# Conference Paper Analyzer — environment variables
+#
+# Copy this file to `.env` and fill in the key(s) for the provider you use:
+#
+#     cp .env.example .env
+#
+# The app loads `.env` automatically on startup. Every value is optional — set
+# only what your chosen LLM provider needs. The in-app "API key" / "LLM endpoint"
+# fields override these at runtime.
+
+# ── Anthropic / Claude (default provider) ───────────────────────────────────
+ANTHROPIC_API_KEY=
+# Optional: custom Anthropic-compatible base URL
+# ANTHROPIC_BASE_URL=
+
+# ── OpenAI (install:  uv sync --extra openai) ───────────────────────────────
+OPENAI_API_KEY=
+# Optional: OpenAI-compatible base URL (the OpenAI SDK reads this automatically;
+# you can also set it per-run in the UI's "LLM endpoint" field)
+# OPENAI_BASE_URL=
+
+# ── LiteLLM (install:  uv sync --extra litellm) ─────────────────────────────
+# Key for your LiteLLM proxy/endpoint. If unset, LITELLM falls back to OPENAI_API_KEY.
+# Set the endpoint itself in the UI's "LLM endpoint" field.
+# LITELLM_API_KEY=
+#
+# LiteLLM also reads provider-native keys from the environment when it routes to
+# a given backend, e.g.:
+# AZURE_API_KEY=
+# AZURE_API_BASE=
+# GEMINI_API_KEY=
+# COHERE_API_KEY=
+
+# ── OpenReview source (ICLR / NeurIPS) ──────────────────────────────────────
+# Usually required. OpenReview now gates anonymous note queries behind an
+# anti-bot challenge (HTTP 403), so ICLR / NeurIPS venues need a logged-in
+# session. Provide credentials to authenticate (this also enables private
+# access). Use EITHER a pre-obtained token OR username + password.
+# OPENREVIEW_TOKEN=
+# OPENREVIEW_USERNAME=
+# OPENREVIEW_PASSWORD=

conflens-0.1.14/.github/workflows/lint.yml

@@ -0,0 +1,31 @@
+name: Lint
+
+# Ruff on every pushed commit (any branch) and every pull request. The
+# concurrency group keys on the branch name — shared by a branch's push and
+# pull_request events — so cancel-in-progress collapses the two into a single
+# run per commit and supersedes stale runs.
+on:
+  push:
+  pull_request:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.head_ref || github.ref_name }}
+  cancel-in-progress: true
+
+jobs:
+  ruff:
+    name: ruff
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+
+      - name: Sync dependencies (base + dev)
+        run: uv sync
+
+      - name: Lint (ruff)
+        run: uv run ruff check .

conflens-0.1.14/.github/workflows/release.yml

@@ -0,0 +1,100 @@
+name: Release
+
+# When a pull request is merged into main, bump the version in pyproject.toml
+# (and keep uv.lock in sync), commit it back to main, create a matching tag,
+# then build and publish the package to PyPI.
+#
+# Bump level is patch by default; add a "minor" or "major" label to the PR to
+# bump those instead. The version-bump commit and tag are pushed with the
+# built-in GITHUB_TOKEN, which by design does NOT re-trigger workflows — so this
+# never loops (the `[skip ci]` marker is belt-and-suspenders). Publishing runs
+# in this same job (a separate tag-triggered workflow would never fire, since
+# GITHUB_TOKEN-pushed tags don't trigger workflows).
+#
+# PyPI publishing requires a repo secret PYPI_API_TOKEN (a PyPI API token; set
+# TWINE_USERNAME=__token__). Without it the publish step fails; the bump/tag
+# still succeed.
+on:
+  pull_request:
+    types: [closed]
+    branches: [main]
+
+permissions:
+  contents: write
+
+concurrency:
+  group: release
+  cancel-in-progress: false
+
+jobs:
+  tag:
+    if: github.event.pull_request.merged == true
+    runs-on: ubuntu-latest
+    env:
+      BUMP: >-
+        ${{ contains(github.event.pull_request.labels.*.name, 'major') && 'major'
+        || contains(github.event.pull_request.labels.*.name, 'minor') && 'minor'
+        || 'patch' }}
+      PR_NUMBER: ${{ github.event.pull_request.number }}
+      PR_TITLE: ${{ github.event.pull_request.title }}
+    steps:
+      - name: Checkout main
+        uses: actions/checkout@v4
+        with:
+          ref: main
+          fetch-depth: 0
+          fetch-tags: true
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+
+      - name: Configure git identity
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+
+      - name: Bump version and create tag
+        id: bump
+        run: |
+          set -euo pipefail
+          CUR=$(grep -m1 -E '^version *= *"' pyproject.toml | sed -E 's/.*"([^"]+)".*/\1/')
+          IFS='.' read -r MA MI PA <<< "$CUR"
+          case "$BUMP" in
+            major) MA=$((MA + 1)); MI=0; PA=0 ;;
+            minor) MI=$((MI + 1)); PA=0 ;;
+            *)     PA=$((PA + 1)) ;;
+          esac
+          NEW="${MA}.${MI}.${PA}"
+          TAG="v${NEW}"
+          echo "PR #${PR_NUMBER} merged — bumping ${CUR} -> ${NEW} (${BUMP})"
+
+          if git rev-parse -q --verify "refs/tags/${TAG}" >/dev/null; then
+            echo "Tag ${TAG} already exists — nothing to do."
+            echo "released=false" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+
+          sed -i -E "s/^version *= *\"[0-9]+\.[0-9]+\.[0-9]+\"/version = \"${NEW}\"/" pyproject.toml
+          # Keep the lockfile's project version in step with pyproject.toml.
+          uv lock
+          git add pyproject.toml uv.lock
+          git commit -m "chore: release ${TAG} [skip ci]"
+          git tag -a "${TAG}" -m "Release ${TAG} (PR #${PR_NUMBER}: ${PR_TITLE})"
+          git push origin HEAD:main
+          git push origin "${TAG}"
+          echo "released=true" >> "$GITHUB_OUTPUT"
+          echo "Released ${TAG}"
+
+      - name: Build distributions
+        if: steps.bump.outputs.released == 'true'
+        run: uv build   # builds from the just-bumped pyproject.toml -> dist/*
+
+      - name: Publish to PyPI
+        if: steps.bump.outputs.released == 'true'
+        env:
+          TWINE_USERNAME: __token__
+          TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}
+        # --skip-existing keeps re-runs idempotent if the version is already up.
+        run: uvx twine upload --non-interactive --skip-existing dist/*

conflens-0.1.14/.github/workflows/test.yml

@@ -0,0 +1,33 @@
+name: Tests
+
+# pytest + package build on every pushed commit (any branch) and every pull
+# request. Concurrency keys on the branch name so a branch's push and
+# pull_request events collapse into a single run and stale runs are superseded.
+on:
+  push:
+  pull_request:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.head_ref || github.ref_name }}
+  cancel-in-progress: true
+
+jobs:
+  pytest:
+    name: pytest + build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+
+      - name: Sync dependencies (base + dev)
+        run: uv sync
+
+      - name: Tests (pytest)
+        run: uv run pytest -q
+
+      - name: Build package
+        run: uv build

conflens-0.1.14/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*.pyc
+.venv/
+venv/
+.env
+*.egg-info/
+.cache/
+build/
+dist/
+*.whl

conflens-0.1.14/.python-version

@@ -0,0 +1 @@
+3.13

conflens-0.1.14/.readthedocs.yaml

@@ -0,0 +1,26 @@
+
+
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the OS, Python version, and other tools you might need
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.13"
+
+# Build documentation in the "docs/" directory with Sphinx
+sphinx:
+   configuration: docs/conf.py
+
+# Optionally, but recommended,
+# declare the Python requirements required to build your documentation
+# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
+# python:
+#    install:
+#    - requirements: docs/requirements.txt
+        
+

conflens-0.1.14/AGENTS.md

@@ -0,0 +1,116 @@
+# AGENTS.md
+
+Guidance for coding agents (and humans) working in this repository. See
+[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for diagrams.
+
+## What this is
+
+**ConfLens** — a NiceGUI web app that browses conference papers (ACL Anthology,
+EMNLP, NAACL, IJCAI, OpenReview / ICLR · NeurIPS, PSCC, and DBLP-indexed venues
+such as ISGT Europe), classifies them against a theme with an LLM, discovers
+topics, and synthesises per-topic findings. It also
+flags near-duplicate titles and offers a fully client-side results view
+(live confidence re-threshold, keyword search + highlight, sort/author facets,
+save/load a run). Python 3.13, managed with **uv**.
+
+## Setup & run
+
+```bash
+uv sync                        # base install (Anthropic, OpenAI, LiteLLM + NiceGUI)
+uv sync --extra bertopic       # + BERTopic topic backend (heavy)
+
+cp .env.example .env           # add provider key(s); loaded automatically
+uv run conflens                # NiceGUI GUI on http://localhost:6868
+uv run conflens --clear-cache  # wipe the on-disk cache
+```
+
+The GUI (`app.py`) is a thin **NiceGUI** presentation layer; all non-UI logic
+lives in `view.py` + `pipeline.py` — put behaviour changes there.
+
+Docker: `docker compose up --build` (see the README).
+
+## Checks before you commit
+
+Run the full gate — CI (GitHub Actions) runs the same three on every push/PR:
+
+```bash
+uv run ruff check .        # lint (also `ruff check --fix .` to auto-fix imports)
+uv run pytest -q           # test suite — network- and API-free, fast
+uv build                   # wheel + sdist build
+```
+
+The tests live in `tests/` and are deterministic: parsers run on HTML/JSON
+fixtures and the LLM stages use a fake `LLMClient` (a class with a
+`structured()` method), so **no network or API keys are needed**. When you add
+behaviour, add a test next to the matching `tests/test_*.py`.
+
+Beyond the automated gate, for changes with real runtime surface:
+
+- **Boot the app:** `uv run conflens`, confirm `GET /` returns 200
+  and the logs are clean.
+- **Scraper/source changes:** also validate against the live source (counts, a
+  sample record's title/authors/abstract). ACL listing pages are large and may
+  truncate mid-download — `_robust_get` retries for a complete read; don't cache
+  a partial. OpenReview's v2 API may challenge anonymous requests from some IPs —
+  set `OPENREVIEW_USERNAME`/`OPENREVIEW_PASSWORD` or `OPENREVIEW_TOKEN` to
+  authenticate (see `.env.example`).
+
+Keep changes ASCII-clean and match the surrounding style (dataclasses, targeted
+regexes over heavyweight parsers, small focused modules).
+
+## Where things live
+
+| Area | Module |
+|------|--------|
+| UI (NiceGUI) | `app.py` |
+| View logic | `view.py` (filter/sort/highlight/compute_view/exports) |
+| Exports | `pptx_export.py`, `bibtex.py` |
+| Orchestration | `pipeline.py` (`AnalysisConfig`, `run_analysis`) |
+| Sources | `sources.py` (registry + `make_source`; `IJCAISource`, `OpenReviewSource`, `PSCCSource`, `DBLPSource`), `scraper.py` (`AnthologyScraper` — also serves EMNLP/NAACL) |
+| LLM providers | `llm.py` (`LLMClient`, `make_client`) |
+| Classify / topics | `classifier.py`, `topics.py` |
+| Near-duplicate detection | `dedup.py` (`annotate_duplicates`) |
+| Cache / models | `cache.py`, `models.py` |
+
+## Conventions
+
+- **All LLM calls go through `llm.py`'s `structured()`** — never call a provider
+  SDK directly from `classifier.py` / `topics.py`.
+- **Add a conference**: implement `resolve_url` / `list_papers` /
+  `enrich_abstracts` in `sources.py`, then register it in `SOURCES`.
+- **Add an LLM provider**: add an `LLMClient` subclass + a branch in
+  `make_client()`. Everything downstream uses the same interface.
+- **Anything expensive should be cached** under `cache.default_cache_dir()`,
+  keyed so a re-run with the same inputs is free (see the caching table in
+  ARCHITECTURE.md). Respect the `force_refresh` flag.
+- **Never hardcode API keys.** Read from env / `.env` / the in-app field.
+
+## LLM / model notes
+
+- Default model is `gpt-5.4` (OpenAI); structured output uses
+  `output_config.format` (Anthropic) or JSON-object mode + schema-in-prompt
+  (OpenAI/LiteLLM).
+- The `effort` parameter is only sent to models that support it (e.g. **not**
+  Haiku 4.5 — it 400s). See `_EFFORT_MODELS` in `llm.py`.
+- OpenAI/LiteLLM calls fall back gracefully (drop `response_format`, then
+  `temperature`) for models/endpoints that reject them.
+
+## Git workflow
+
+- **Do not commit to `main` directly.** Create a feature branch per change and
+  open a PR into `main`. Name the branch with a `feat/…` or `fix/…` prefix, and
+  **the branch pushed to GitHub (the PR's source) must not contain "claude"** in
+  its name (see [CLAUDE.md](CLAUDE.md)).
+- **No AI-assistant / Claude Code attribution** anywhere — no `Co-Authored-By`,
+  `Claude-Session`, `🤖 Generated with …`, or `claude.ai/code` in commit
+  messages or PR descriptions, and don't attribute commit authorship to an
+  assistant. See [CLAUDE.md](CLAUDE.md). (The Anthropic *LLM provider* stays —
+  it's a feature.)
+- `.env`, `.venv`, `__pycache__`, `~/.cache/...` and build artefacts are
+  gitignored — never commit them.
+- **CI** is one workflow per concern under `.github/workflows/`: `lint.yml`
+  (ruff on every commit), `test.yml` (pytest + build), `release.yml`
+  (version bump + tag on PR merge). Keep lint and tests green.
+- **Releases are automated** (`.github/workflows/release.yml`): merging a PR into
+  `main` bumps the version and tags it. Don't bump `version` in `pyproject.toml`
+  by hand — control the bump with a `minor`/`major` PR label (default patch).

conflens-0.1.14/CLAUDE.md

@@ -0,0 +1,33 @@
+# ConfLens — project rules for agents
+
+See [AGENTS.md](AGENTS.md) for contributor/agent guidance and
+[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for the design.
+
+## Branch naming (persistent — applies to every session and agent)
+
+Develop each change on a feature branch named `feat/…` or `fix/…` and open a PR
+into `main`; never commit directly to `main`. **The branch pushed to GitHub (the
+PR's source branch) must not contain "claude" in its name** — this holds even if
+a session's setup designates a `claude/…` branch.
+
+## Attribution policy (persistent — applies to every session and agent)
+
+Do **not** add AI-assistant / "Claude Code" attribution anywhere in this
+repository or its GitHub artifacts:
+
+- **No** `Co-Authored-By:` trailers, `Claude-Session:` lines, `🤖 Generated
+  with …` footers, or `claude.ai/code` links in **commit messages** or
+  **pull-request descriptions**.
+- Keep source, docs, and config free of Claude Code / assistant references.
+- Do not attribute commit authorship to an AI assistant.
+
+**Exception:** Anthropic / Claude *as an LLM provider* is a genuine product
+feature (the `anthropic` provider and `claude-*` model ids in `llm.py`) and
+stays — this policy is about tooling attribution, not the app's providers.
+
+## Front-end (NiceGUI)
+
+The app has a single **NiceGUI** GUI in `conflens/app.py` (console script
+`conflens`). All non-UI logic (filtering, sorting, highlighting, the
+computed view, exports) lives in **`conflens/view.py`** and the pipeline — put
+behaviour changes there so the UI stays a thin presentation layer.

conflens-0.1.14/Dockerfile

@@ -0,0 +1,43 @@
+# syntax=docker/dockerfile:1
+
+# uv-managed image pinned to the project's Python (3.13).
+FROM ghcr.io/astral-sh/uv:python3.13-bookworm-slim
+
+# Which optional extras to install (e.g. bertopic).
+# Override at build time, e.g. --build-arg EXTRAS="--extra bertopic".
+ARG EXTRAS=""
+
+ENV PYTHONUNBUFFERED=1 \
+    UV_COMPILE_BYTECODE=1 \
+    UV_LINK_MODE=copy \
+    UV_PROJECT_ENVIRONMENT=/app/.venv
+
+WORKDIR /app
+
+# 1) Install dependencies in a cached layer (no project source yet).
+RUN --mount=type=cache,target=/root/.cache/uv \
+    --mount=type=bind,source=uv.lock,target=uv.lock \
+    --mount=type=bind,source=pyproject.toml,target=pyproject.toml \
+    uv sync --frozen --no-install-project ${EXTRAS}
+
+# 2) Copy the project and install it (the conflens entry point).
+COPY . /app
+COPY --link .env* /app/
+RUN --mount=type=cache,target=/root/.cache/uv \
+    uv sync --frozen ${EXTRAS}
+
+ENV PATH="/app/.venv/bin:${PATH}"
+
+# Run as a non-root user; keep the on-disk cache on a persistable path.
+RUN useradd --create-home --uid 1000 app \
+    && mkdir -p /home/app/.cache/conflens \
+    && chown -R app:app /app /home/app
+USER app
+ENV HOME=/home/app
+
+EXPOSE 6868
+
+# ENTRYPOINT + CMD: default launches the server; `docker run <image> --clear-cache`
+# (or any other flags) is appended to `conflens`.
+ENTRYPOINT ["conflens"]
+CMD ["--host", "0.0.0.0", "--port", "6868"]