Skip to content

Hironobu-Kawaguchi/arxiv-cli

BranchesTags

Repository files navigation

ArXiv CLI

AI研究者向けのArXiv論文検索・管理CLIアプリケーション

概要

ArXiv CLIは、ArXiv論文データベースを効率的に検索・管理できる論文検索ツールです。研究者が最新論文を素早く見つけ、整理できる機能を提供します。

主な機能

  • 論文検索: キーワード、著者名、カテゴリによる柔軟な論文検索
  • マルチフォーマット対応: PDF、LaTeX（予定）、Meta情報
  • ブックマーク管理: 興味のある論文をローカルに保存・管理
  • タグ機能: 論文の分類・整理
  • 設定管理: ユーザー設定のカスタマイズ

要件

環境

  • Python 3.12 以上
  • インターネット接続（ArXiv API アクセス用）

インストール

  1. リポジトリを取得してディレクトリへ移動します。 
    git clone <repository-url>
cd arxiv-cli
  2. 依存関係をロック & インストールします（.venv/ が自動作成されます）。 
    uv sync
  3. 一時的に仮想環境へ入る場合は source .venv/bin/activate を実行するか、以下のように uv run でコマンドを包みます。 
    uv run arxiv-cli --help
  4. 設定やデータを別ディレクトリで試したい場合は環境変数で指定します。 
    export ARXIV_CLI_CONFIG_DIR=$(pwd)/.tmp-config
uv run arxiv-cli config init
  5. ドメインモデルの読み込み確認（任意）。 
    uv run python -c "from src.domain.models import Paper, Author, Bookmark; print('ドメインモデル読み込み成功')"

実装状況（Implemented / Planned）

実装済み（主なもの）

  • 基盤とドメイン: クリーンレイヤー、Author/Paper/Bookmark、型・テスト整備
  • 設定/ログ/ストレージ: ConfigManager、JSONストレージ、ブックマークリポジトリ
  • API連携: ArXiv APIクライアント（レート制限・リトライ・パース）
  • アプリケーション層: Search/Bookmark/Download サービスとユースケース
  • CLI: search（著者/カテゴリ/日付/ページ）、bookmark（add/list/remove/tag/search/export）、download（pdf/run/batch）、config（list/set）
  • ダウンロード: PDF/LaTeX(.tar.gz)/Meta(json) の保存、上書き制御/サブディレクトリ対応、進捗表示（LaTeX）、履歴管理（JSON）
  • CLI出力整形: 端末幅に応じた表レイアウト、詳細パネルの装飾、--no-truncate/--plain 時の折返し制御、ダウンロード結果のバッジ表示

今後の予定（Planned）

  • テスト: さらなる統合/E2Eテスト、パフォーマンステスト
  • ドキュメント: 利用例の拡充、トラブルシューティング

トラブルシューティング

  • Paper not found: 指定IDの論文が見つからない場合、Paper not found: <id> と表示されます（IDを確認してください）。
  • ネットワーク/レート制限(429): 自動リトライします。失敗が続く場合は時間を空けるか、api.rate_limit_delay を上げてください（config set api.rate_limit_delay 5）。
  • 権限/ファイルI/O: ダウンロード先の権限/空き容量を確認。config list で storage.download_dir を確認・変更できます。
  • 設定不整合: config validate で検証、問題がある場合は config reset や config init --dir <path> を実行。
  • ログ出力が多い/少ない: config set log_level "\"DEBUG\"" や "INFO" で調整。
  • LaTeX 解凍エラー: .tar.gz は安全に展開しますが、壊れたアーカイブは抽出をスキップします。元ファイルは downloads/latex/ に残ります。
  • 履歴/キャッシュ破損: ~/.arxiv-cli/download_history.json を一時退避、~/.arxiv-cli/cache/ の不要ファイルを削除して再試行してください。

ディレクトリ構成

arxiv-cli/
├── src/
│   ├── cli/                    # CLI層 - ユーザーUI
│   ├── application/            # アプリケーション層 - ビジネスロジック
│   ├── domain/                 # ドメイン層 - ビジネスルールとモデル
│   └── infrastructure/         # インフラ層 - 外部連携
├── tests/                      # テスト関連
├── config/                     # 設定ファイル
└── docs/                       # ドキュメント

開発・テスト

開発コマンド

# 依存関係インストール
uv sync

# テスト実行
uv run pytest                   # 全テスト
uv run pytest tests/unit/      # 単体テスト
uv run pytest tests/integration/  # 統合テスト
uv run pytest tests/e2e/          # E2Eスモーク
uv run pytest tests/perf/         # パフォーマンスガード
uv run pytest --cov=src        # カバレッジ測定

# コード品質チェック
uv run black .                  # コードフォーマット
uv run mypy src/               # 型チェック
uv run flake8                  # リント
pre-commit run --all-files     # 事前フックで一括チェック

# デモ・動作確認
uv run python examples/domain_model_demo.py  # ドメインモデル実行例

利用例

CLI クイックスタート

# 論文検索（カテゴリ・著者・期間フィルタ）
uv run arxiv-cli search run "diffusion model" --category cs.AI --author Song --from 2024-01-01 --to 2024-12-31 --page-size 5

# 詳細出力
uv run arxiv-cli search run "graph neural networks" --details

# ブックマーク登録と一覧
uv run arxiv-cli bookmark add 2401.12345 --tag followup
uv run arxiv-cli bookmark list --no-truncate

# 指定フォーマットでダウンロード
uv run arxiv-cli download run 2401.12345 --format pdf --format meta

# 設定確認と更新
uv run arxiv-cli config list
uv run arxiv-cli config set display.max_results 20

# pre-commit をセットアップ
pre-commit install

アプリケーション層（サービス/ユースケース）

  • サービス: SearchService, BookmarkService, DownloadService
  • ユースケース: src/application/usecases/ の薄い関数（CLI から呼び出しやすい形）

Python コードから直接利用する場合の例:

from src.application.services.search_service import SearchService
s = SearchService()
papers = s.search("machine learning", max_results=5)
for paper in papers:
    print(paper.title)

Python API 使用例

from datetime import datetime
from src.domain.models import Paper, Author, Bookmark

# 著者作成
authors = [
    Author(name="Geoffrey Hinton", affiliation="University of Toronto"),
    Author(name="Yoshua Bengio", affiliation="University of Montreal")
]

# 論文作成
paper = Paper(
    id="2301.12345",
    title="Deep Learning Advances in 2023",
    authors=authors,
    summary="Latest developments in deep learning...",
    published_date=datetime(2023, 1, 15),
    updated_date=datetime(2023, 1, 20),
    categories=["cs.AI", "cs.LG"],
    pdf_url="https://arxiv.org/pdf/2301.12345.pdf",
    abs_url="https://arxiv.org/abs/2301.12345"
)

# ブックマーク作成・管理
bookmark = Bookmark(paper_id=paper.id)
bookmark.add_tag("deep-learning")
bookmark.add_tag("important")
bookmark.set_rating(5)
bookmark.set_read_status("reading")

print(f"論文: {paper}")
print(f"著者: {paper.get_authors_string()}")
print(f"ブックマーク: {bookmark}")

API仕様

ArXiv APIとの連携仕様・パラメータの詳細は docs/api_spec.md を参照してください。クエリの組み立て方法、レスポンスマッピング、レート制限ポリシー、ダウンロードエンドポイントを網羅しています。

設定

アプリケーション設定は ~/.arxiv-cli/config.json に保存されます。

{
  "api": {
    "base_url": "http://export.arxiv.org/api/query",
    "timeout": 30,
    "rate_limit_delay": 3.0
  },
  "storage": {
    "download_dir": "~/Downloads/arxiv",
    "cache_dir": "~/.arxiv-cli/cache"
  },
  "display": {
    "max_results": 10,
    "date_format": "%Y-%m-%d"
  },
  "download": {
    "default_formats": ["pdf"],
    "create_subdirs": true
  }
}

データ保存

  • ブックマークは ~/.arxiv-cli/bookmarks.json に JSON 形式で保存されます。
  • API 応答等のキャッシュは ~/.arxiv-cli/cache/ に保存され、有効期限で自動的にパージ可能です。
  • これらのパスは設定ファイル（storage セクション）で変更できます。テストや一時利用では ConfigManager(config_dir=...) で分離可能です。

ダウンロード先フォルダ

  • 既定のダウンロードルート: ~/Downloads/arxiv
  • サブディレクトリ（download.create_subdirs = true の場合）
    • pdf/ に PDF、latex/ にソース（.tar.gz）、meta/ にメタデータJSON
  • ファイル名: {id}_{title} をベースに安全化して保存（長いタイトルは一部切り詰め）
  • 上書き: download.overwrite_existing で制御（false なら既存を再利用）
  • 変更: config list で現状確認、config set storage.download_dir "\"/path\"" で更新
  • 履歴: ~/.arxiv-cli/download_history.json にダウンロード履歴を保存（ID/形式/パス/時刻）

CLI 基本使用

インストール後は arxiv-cli が利用できます。テストや一時利用では設定ルートを環境変数で切り替えられます。

# ヘルプ
arxiv-cli --help

# 検索（API にアクセス）
arxiv-cli search run "machine learning" --page 1 --page-size 5
arxiv-cli search run --author Hinton --category cs.AI --from 2024-01-01 --to 2024-12-31

# ブックマーク
ARXIV_CLI_CONFIG_DIR=/tmp/acli arxiv-cli bookmark add 2301.12345 --tag ai
ARXIV_CLI_CONFIG_DIR=/tmp/acli arxiv-cli bookmark list
ARXIV_CLI_CONFIG_DIR=/tmp/acli arxiv-cli bookmark tag add 2301.12345 ml
ARXIV_CLI_CONFIG_DIR=/tmp/acli arxiv-cli bookmark search --tag ai --all
ARXIV_CLI_CONFIG_DIR=/tmp/acli arxiv-cli bookmark export --out /tmp/acli/export.json

# 設定表示
arxiv-cli config list
arxiv-cli config path

# 設定の初期化/リセット/検証
arxiv-cli config init                      # 既定ディレクトリに初期化
arxiv-cli config init --dir /tmp/acli-cfg  # 任意ディレクトリに初期化
arxiv-cli config reset                     # 既定に戻す
arxiv-cli config validate                  # バリデーション

# 設定の更新
arxiv-cli config set api.timeout 45
arxiv-cli config set display.max_results 20

将来の使用方法（予定）

# 論文検索
arxiv-cli search "machine learning"
arxiv-cli search --author "Hinton" --category "cs.AI"

# ブックマーク管理
arxiv-cli bookmark add 2301.12345
arxiv-cli bookmark list --tag "important"

# ダウンロード
arxiv-cli download pdf 2301.12345
arxiv-cli download run 2301.12345                  # 既定: pdf, meta, latex
arxiv-cli download run 2301.12345 -f pdf -f meta   # 明示指定
arxiv-cli download batch                           # ブックマーク一括（既定: 全形式）

# ダウンロード履歴
arxiv-cli download history list        # 全履歴
arxiv-cli download history list --limit 20

開発方針

このプロジェクトは仕様駆動開発（SDD）とテスト駆動開発（TDD）の手法で開発されています。

  1. 仕様ファイル: requirements.md, design.md, tasks.md による設計・開発
  2. 品質管理: 全機能実装後にテスト実行、品質チェック、tasks.md進捗更新、コミット
  3. マイルストーン: 12段階の開発マイルストーンによる管理

貢献

[貢献ガイドは準備中]

参考資料

About

No description, website, or topics provided.

Resources

Readme
Activity

Stars

2 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

1 tags

Packages

 
 
 

Contributors

Languages