From ac1f2b94145a295ba611441310948551e4f6ec20 Mon Sep 17 00:00:00 2001 From: Axect Date: Sat, 7 Feb 2026 15:05:02 +0800 Subject: [PATCH] Refactor README: promote TUI section, simplify Quick Start and AI Providers MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Rename Quick Demo → Quick Start, reduce from 6 steps to 3 - Move TUI section above CLI Reference as primary usage guide - Simplify AI Providers: remove Setup/How-it-works subsections, keep provider table + 3 essential commands - Condense Architecture: single-line recommendation algorithm summary Co-Authored-By: Claude Opus 4.6 --- README.md | 102 +++++++++++++++++------------------------------------- 1 file changed, 32 insertions(+), 70 deletions(-) diff --git a/README.md b/README.md index e0c93a9..59a8dae 100644 --- a/README.md +++ b/README.md @@ -54,33 +54,36 @@ axp --install-completion bash axp --install-completion zsh ``` -## Quick Demo +## Quick Start ```bash -# 1. Tell arXiv Explorer what you're interested in +# 1. Set your research interests axp prefs add-category hep-ph --priority 2 -axp prefs add-category cs.AI axp prefs add-keyword "deep learning" --weight 1.5 -# 2. Fetch and rank the last week's papers +# 2. Fetch and rank recent papers axp daily --days 7 --limit 10 -# 3. Found something interesting? Like it — this trains the recommender -axp like 2501.12345 - -# 4. Get an AI summary (uses your configured provider) -axp show 2501.12345 --summary - -# 5. Organize into a reading list -axp list create "GNN papers" -axp list add "GNN papers" 2501.12345 - -# 6. Or just launch the TUI for a full interactive experience +# 3. Launch the TUI for the full experience axp tui ``` See [QUICKSTART.md](QUICKSTART.md) for a full walkthrough. +## TUI + +Launch with `axp tui`. The terminal UI provides a full interactive experience with five tabs: + +| Tab | Key | Description | +|-----|-----|-------------| +| **Daily** | `1` | Browse personalized papers with detail panel | +| **Search** | `2` | Search arXiv interactively | +| **Lists** | `3` | Manage reading lists and track status | +| **Notes** | `4` | Browse and filter paper notes | +| **Prefs** | `5` | Manage categories, keywords, and AI settings | + +**Key bindings**: `Enter` open detail / `l` like / `d` dislike / `s` summarize / `t` translate / `n` note / `a` add to list / `r` refresh / `q` quit + ## CLI Reference ### Paper Discovery @@ -118,40 +121,9 @@ See [QUICKSTART.md](QUICKSTART.md) for a full walkthrough. | `axp config set-language LANG` | Change display language (en, ko) | | `axp config test` | Test current provider connection | -## TUI - -Launch with `axp tui`. The terminal UI provides a full interactive experience with five tabs: - -| Tab | Key | Description | -|-----|-----|-------------| -| **Daily** | `1` | Browse personalized papers with detail panel | -| **Search** | `2` | Search arXiv interactively | -| **Lists** | `3` | Manage reading lists and track status | -| **Notes** | `4` | Browse and filter paper notes | -| **Prefs** | `5` | Manage categories, keywords, and AI settings | - -**Key bindings**: `Enter` open detail / `l` like / `d` dislike / `s` summarize / `t` translate / `n` note / `a` add to list / `r` refresh / `q` quit - -## Architecture - -``` -src/arxiv_explorer/ - core/ # Data models, database schema, configuration - services/ # Business logic (recommendation, search, summarization, caching) - cli/ # Typer-based CLI commands - tui/ # Textual-based terminal UI (tabs: Daily, Search, Lists, Notes, Prefs) - utils/ # Display helpers -``` - -**Recommendation Algorithm** — Papers are scored using a weighted combination of: -- Content similarity (50%) — TF-IDF cosine similarity to liked papers -- Category matching (20%) — Priority-weighted category overlap -- Keyword matching (10%) — Weighted keyword presence -- Recency bonus (5%) — Papers published within the last 30 days - ## AI Providers -AI features (summarization and translation) work by calling external CLI tools via subprocess. No API keys are stored in the application — each tool manages its own authentication. +AI features (summarization and translation) call external CLI tools via subprocess — no API keys are stored in the application. | Provider | CLI command | Invocation | Default model | |----------|------------|------------|---------------| @@ -162,34 +134,24 @@ AI features (summarization and translation) work by calling external CLI tools v | **OpenCode** | `opencode` | `opencode run --model MODEL PROMPT` | (provider default) | | **Custom** | user-defined | template with `{prompt}` and optional `{model}` placeholders | — | -### Setup - ```bash -# Check which providers are available on your system -axp config show - -# Switch to a different provider -axp config set-provider claude - -# Override the default model -axp config set-model "claude-sonnet-4-5-20250929" - -# Set a custom command template -axp config set-custom "my-ai -m {model} -p {prompt}" -axp config set-provider custom - -# Verify that the provider works -axp config test +axp config set-provider claude # Switch provider +axp config set-model "claude-sonnet-4-5-20250929" # Override model +axp config test # Verify connection ``` -### How it works +## Architecture -1. The active provider receives a structured prompt requesting JSON output -2. The CLI tool processes the prompt using its own API key / local model -3. arXiv Explorer parses the JSON response and caches the result in SQLite -4. Subsequent requests for the same paper return instantly from cache +``` +src/arxiv_explorer/ + core/ # Data models, database schema, configuration + services/ # Business logic (recommendation, search, summarization, caching) + cli/ # Typer-based CLI commands + tui/ # Textual-based terminal UI (tabs: Daily, Search, Lists, Notes, Prefs) + utils/ # Display helpers +``` -Summarization and translation are available in both CLI (`axp show -s`, `axp translate`) and TUI (`s` / `t` keys in paper detail). +**Recommendation** — TF-IDF cosine similarity (50%) + category priority (20%) + keyword matching (10%) + recency bonus (5%). ## Comparison