namingpaper 0.1.0__tar.gz

namingpaper-0.1.0/.agent/workflows/openspec-apply.md

@@ -0,0 +1,20 @@
+---
+description: Implement an approved OpenSpec change and keep tasks in sync.
+---
+<!-- OPENSPEC:START -->
+**Guardrails**
+- Favor straightforward, minimal implementations first and add complexity only when it is requested or clearly required.
+- Keep changes tightly scoped to the requested outcome.
+- Refer to `openspec/AGENTS.md` (located inside the `openspec/` directory—run `ls openspec` or `openspec update` if you don't see it) if you need additional OpenSpec conventions or clarifications.
+
+**Steps**
+Track these steps as TODOs and complete them one by one.
+1. Read `changes/<id>/proposal.md`, `design.md` (if present), and `tasks.md` to confirm scope and acceptance criteria.
+2. Work through tasks sequentially, keeping edits minimal and focused on the requested change.
+3. Confirm completion before updating statuses—make sure every item in `tasks.md` is finished.
+4. Update the checklist after all work is done so each task is marked `- [x]` and reflects reality.
+5. Reference `openspec list` or `openspec show <item>` when additional context is required.
+
+**Reference**
+- Use `openspec show <id> --json --deltas-only` if you need additional context from the proposal while implementing.
+<!-- OPENSPEC:END -->

namingpaper-0.1.0/.agent/workflows/openspec-archive.md

@@ -0,0 +1,24 @@
+---
+description: Archive a deployed OpenSpec change and update specs.
+---
+<!-- OPENSPEC:START -->
+**Guardrails**
+- Favor straightforward, minimal implementations first and add complexity only when it is requested or clearly required.
+- Keep changes tightly scoped to the requested outcome.
+- Refer to `openspec/AGENTS.md` (located inside the `openspec/` directory—run `ls openspec` or `openspec update` if you don't see it) if you need additional OpenSpec conventions or clarifications.
+
+**Steps**
+1. Determine the change ID to archive:
+   - If this prompt already includes a specific change ID (for example inside a `<ChangeId>` block populated by slash-command arguments), use that value after trimming whitespace.
+   - If the conversation references a change loosely (for example by title or summary), run `openspec list` to surface likely IDs, share the relevant candidates, and confirm which one the user intends.
+   - Otherwise, review the conversation, run `openspec list`, and ask the user which change to archive; wait for a confirmed change ID before proceeding.
+   - If you still cannot identify a single change ID, stop and tell the user you cannot archive anything yet.
+2. Validate the change ID by running `openspec list` (or `openspec show <id>`) and stop if the change is missing, already archived, or otherwise not ready to archive.
+3. Run `openspec archive <id> --yes` so the CLI moves the change and applies spec updates without prompts (use `--skip-specs` only for tooling-only work).
+4. Review the command output to confirm the target specs were updated and the change landed in `changes/archive/`.
+5. Validate with `openspec validate --strict --no-interactive` and inspect with `openspec show <id>` if anything looks off.
+
+**Reference**
+- Use `openspec list` to confirm change IDs before archiving.
+- Inspect refreshed specs with `openspec list --specs` and address any validation issues before handing off.
+<!-- OPENSPEC:END -->

namingpaper-0.1.0/.agent/workflows/openspec-proposal.md

@@ -0,0 +1,25 @@
+---
+description: Scaffold a new OpenSpec change and validate strictly.
+---
+<!-- OPENSPEC:START -->
+**Guardrails**
+- Favor straightforward, minimal implementations first and add complexity only when it is requested or clearly required.
+- Keep changes tightly scoped to the requested outcome.
+- Refer to `openspec/AGENTS.md` (located inside the `openspec/` directory—run `ls openspec` or `openspec update` if you don't see it) if you need additional OpenSpec conventions or clarifications.
+- Identify any vague or ambiguous details and ask the necessary follow-up questions before editing files.
+- Do not write any code during the proposal stage. Only create design documents (proposal.md, tasks.md, design.md, and spec deltas). Implementation happens in the apply stage after approval.
+
+**Steps**
+1. Review `openspec/project.md`, run `openspec list` and `openspec list --specs`, and inspect related code or docs (e.g., via `rg`/`ls`) to ground the proposal in current behaviour; note any gaps that require clarification.
+2. Choose a unique verb-led `change-id` and scaffold `proposal.md`, `tasks.md`, and `design.md` (when needed) under `openspec/changes/<id>/`.
+3. Map the change into concrete capabilities or requirements, breaking multi-scope efforts into distinct spec deltas with clear relationships and sequencing.
+4. Capture architectural reasoning in `design.md` when the solution spans multiple systems, introduces new patterns, or demands trade-off discussion before committing to specs.
+5. Draft spec deltas in `changes/<id>/specs/<capability>/spec.md` (one folder per capability) using `## ADDED|MODIFIED|REMOVED Requirements` with at least one `#### Scenario:` per requirement and cross-reference related capabilities when relevant.
+6. Draft `tasks.md` as an ordered list of small, verifiable work items that deliver user-visible progress, include validation (tests, tooling), and highlight dependencies or parallelizable work.
+7. Validate with `openspec validate <id> --strict --no-interactive` and resolve every issue before sharing the proposal.
+
+**Reference**
+- Use `openspec show <id> --json --deltas-only` or `openspec show <spec> --type spec` to inspect details when validation fails.
+- Search existing requirements with `rg -n "Requirement:|Scenario:" openspec/specs` before writing new ones.
+- Explore the codebase with `rg <keyword>`, `ls`, or direct file reads so proposals align with current implementation realities.
+<!-- OPENSPEC:END -->

namingpaper-0.1.0/.claude/commands/openspec/apply.md

@@ -0,0 +1,23 @@
+---
+name: OpenSpec: Apply
+description: Implement an approved OpenSpec change and keep tasks in sync.
+category: OpenSpec
+tags: [openspec, apply]
+---
+<!-- OPENSPEC:START -->
+**Guardrails**
+- Favor straightforward, minimal implementations first and add complexity only when it is requested or clearly required.
+- Keep changes tightly scoped to the requested outcome.
+- Refer to `openspec/AGENTS.md` (located inside the `openspec/` directory—run `ls openspec` or `openspec update` if you don't see it) if you need additional OpenSpec conventions or clarifications.
+
+**Steps**
+Track these steps as TODOs and complete them one by one.
+1. Read `changes/<id>/proposal.md`, `design.md` (if present), and `tasks.md` to confirm scope and acceptance criteria.
+2. Work through tasks sequentially, keeping edits minimal and focused on the requested change.
+3. Confirm completion before updating statuses—make sure every item in `tasks.md` is finished.
+4. Update the checklist after all work is done so each task is marked `- [x]` and reflects reality.
+5. Reference `openspec list` or `openspec show <item>` when additional context is required.
+
+**Reference**
+- Use `openspec show <id> --json --deltas-only` if you need additional context from the proposal while implementing.
+<!-- OPENSPEC:END -->

namingpaper-0.1.0/.claude/commands/openspec/archive.md

@@ -0,0 +1,27 @@
+---
+name: OpenSpec: Archive
+description: Archive a deployed OpenSpec change and update specs.
+category: OpenSpec
+tags: [openspec, archive]
+---
+<!-- OPENSPEC:START -->
+**Guardrails**
+- Favor straightforward, minimal implementations first and add complexity only when it is requested or clearly required.
+- Keep changes tightly scoped to the requested outcome.
+- Refer to `openspec/AGENTS.md` (located inside the `openspec/` directory—run `ls openspec` or `openspec update` if you don't see it) if you need additional OpenSpec conventions or clarifications.
+
+**Steps**
+1. Determine the change ID to archive:
+   - If this prompt already includes a specific change ID (for example inside a `<ChangeId>` block populated by slash-command arguments), use that value after trimming whitespace.
+   - If the conversation references a change loosely (for example by title or summary), run `openspec list` to surface likely IDs, share the relevant candidates, and confirm which one the user intends.
+   - Otherwise, review the conversation, run `openspec list`, and ask the user which change to archive; wait for a confirmed change ID before proceeding.
+   - If you still cannot identify a single change ID, stop and tell the user you cannot archive anything yet.
+2. Validate the change ID by running `openspec list` (or `openspec show <id>`) and stop if the change is missing, already archived, or otherwise not ready to archive.
+3. Run `openspec archive <id> --yes` so the CLI moves the change and applies spec updates without prompts (use `--skip-specs` only for tooling-only work).
+4. Review the command output to confirm the target specs were updated and the change landed in `changes/archive/`.
+5. Validate with `openspec validate --strict --no-interactive` and inspect with `openspec show <id>` if anything looks off.
+
+**Reference**
+- Use `openspec list` to confirm change IDs before archiving.
+- Inspect refreshed specs with `openspec list --specs` and address any validation issues before handing off.
+<!-- OPENSPEC:END -->

namingpaper-0.1.0/.claude/commands/openspec/proposal.md

@@ -0,0 +1,28 @@
+---
+name: OpenSpec: Proposal
+description: Scaffold a new OpenSpec change and validate strictly.
+category: OpenSpec
+tags: [openspec, change]
+---
+<!-- OPENSPEC:START -->
+**Guardrails**
+- Favor straightforward, minimal implementations first and add complexity only when it is requested or clearly required.
+- Keep changes tightly scoped to the requested outcome.
+- Refer to `openspec/AGENTS.md` (located inside the `openspec/` directory—run `ls openspec` or `openspec update` if you don't see it) if you need additional OpenSpec conventions or clarifications.
+- Identify any vague or ambiguous details and ask the necessary follow-up questions before editing files.
+- Do not write any code during the proposal stage. Only create design documents (proposal.md, tasks.md, design.md, and spec deltas). Implementation happens in the apply stage after approval.
+
+**Steps**
+1. Review `openspec/project.md`, run `openspec list` and `openspec list --specs`, and inspect related code or docs (e.g., via `rg`/`ls`) to ground the proposal in current behaviour; note any gaps that require clarification.
+2. Choose a unique verb-led `change-id` and scaffold `proposal.md`, `tasks.md`, and `design.md` (when needed) under `openspec/changes/<id>/`.
+3. Map the change into concrete capabilities or requirements, breaking multi-scope efforts into distinct spec deltas with clear relationships and sequencing.
+4. Capture architectural reasoning in `design.md` when the solution spans multiple systems, introduces new patterns, or demands trade-off discussion before committing to specs.
+5. Draft spec deltas in `changes/<id>/specs/<capability>/spec.md` (one folder per capability) using `## ADDED|MODIFIED|REMOVED Requirements` with at least one `#### Scenario:` per requirement and cross-reference related capabilities when relevant.
+6. Draft `tasks.md` as an ordered list of small, verifiable work items that deliver user-visible progress, include validation (tests, tooling), and highlight dependencies or parallelizable work.
+7. Validate with `openspec validate <id> --strict --no-interactive` and resolve every issue before sharing the proposal.
+
+**Reference**
+- Use `openspec show <id> --json --deltas-only` or `openspec show <spec> --type spec` to inspect details when validation fails.
+- Search existing requirements with `rg -n "Requirement:|Scenario:" openspec/specs` before writing new ones.
+- Explore the codebase with `rg <keyword>`, `ls`, or direct file reads so proposals align with current implementation realities.
+<!-- OPENSPEC:END -->

namingpaper-0.1.0/.claude/settings.local.json

@@ -0,0 +1,51 @@
+{
+  "permissions": {
+    "allow": [
+      "mcp__context7__resolve-library-id",
+      "mcp__context7__query-docs",
+      "Bash(uv sync:*)",
+      "Bash(uv run pytest:*)",
+      "Bash(uv pip install:*)",
+      "Bash(uv run namingpaper --help:*)",
+      "Bash(uv run namingpaper rename --help:*)",
+      "Bash(uv run:*)",
+      "Bash(uv pip list:*)",
+      "Bash(ls:*)",
+      "Bash(cat:*)",
+      "Bash(/Users/tsaipingjui/Documents/Namingpaper/.venv/bin/python3:*)",
+      "Bash(.venv/bin/python:*)",
+      "Bash(uv venv:*)",
+      "Bash(.venv/bin/namingpaper:*)",
+      "Bash(uv lock:*)",
+      "Bash(echo:*)",
+      "Bash(curl:*)",
+      "Bash(python3:*)",
+      "Bash(ollama pull:*)",
+      "Bash(NAMINGPAPER_MODEL_NAME=qwen3:1.7b uv run:*)",
+      "Bash(NAMINGPAPER_MODEL_NAME=qwen3:0.6b uv run:*)",
+      "Bash(NAMINGPAPER_MODEL_NAME=qwen3:4b uv run:*)",
+      "Bash(openspec list:*)",
+      "Bash(openspec validate:*)",
+      "Bash(python -m pytest:*)",
+      "Bash(uv python install:*)",
+      "mcp__github__get_me",
+      "mcp__github__create_repository",
+      "Bash(gh auth status:*)",
+      "Bash(gh repo create:*)",
+      "Bash(git -C /Users/tsaipingjui/Documents/Namingpaper add .gitignore .python-version AGENTS.md CLAUDE.md README.md openspec/ pyproject.toml src/ tests/)",
+      "Bash(git -C /Users/tsaipingjui/Documents/Namingpaper diff --cached --stat)",
+      "Bash(git -C /Users/tsaipingjui/Documents/Namingpaper commit -m \"$\\(cat <<''EOF''\nInitial commit: namingpaper CLI tool\n\nA CLI tool that renames academic PDF papers using AI-extracted metadata.\nSupports Claude, OpenAI, Gemini, and Ollama providers with batch processing,\ncustom templates, and dry-run safety.\n\nCo-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>\nEOF\n\\)\")",
+      "Bash(git -C /Users/tsaipingjui/Documents/Namingpaper branch:*)",
+      "Bash(git -C /Users/tsaipingjui/Documents/Namingpaper push -u origin main)",
+      "Bash(git -C /Users/tsaipingjui/Documents/Namingpaper status)",
+      "Bash(git -C /Users/tsaipingjui/Documents/Namingpaper diff)",
+      "Bash(git -C /Users/tsaipingjui/Documents/Namingpaper log --oneline -5)",
+      "Bash(git -C /Users/tsaipingjui/Documents/Namingpaper add README.md pyproject.toml)",
+      "Bash(git -C /Users/tsaipingjui/Documents/Namingpaper commit -m \"$\\(cat <<''EOF''\nFix installation docs and add missing httpx dependency\n\n- Add httpx to pyproject.toml \\(required by Ollama provider\\)\n- Fix Ollama model names to match code defaults \\(deepseek-ocr + llama3.1:8b\\)\n- Replace placeholder GitHub URLs with actual repo URL\n- Clarify Claude is included by default, use uv sync --extra for optional providers\n- Remove uv add instructions since package is not yet on PyPI\n\nCo-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>\nEOF\n\\)\")",
+      "Bash(git -C /Users/tsaipingjui/Documents/Namingpaper push)",
+      "Bash(git -C /Users/tsaipingjui/Documents/Namingpaper tag -a v0.1.0 -m \"v0.1.0: Initial release\")",
+      "Bash(git -C /Users/tsaipingjui/Documents/Namingpaper push origin v0.1.0)",
+      "Bash(gh release create:*)"
+    ]
+  }
+}

namingpaper-0.1.0/.gitignore

@@ -0,0 +1,54 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+.nox/
+
+# IDEs
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Environment
+.env
+.env.local
+
+# Config with secrets
+.namingpaper/
+
+# uv
+uv.lock

namingpaper-0.1.0/.python-version

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

namingpaper-0.1.0/AGENTS.md

@@ -0,0 +1,18 @@
+<!-- OPENSPEC:START -->
+# OpenSpec Instructions
+
+These instructions are for AI assistants working in this project.
+
+Always open `@/openspec/AGENTS.md` when the request:
+- Mentions planning or proposals (words like proposal, spec, change, plan)
+- Introduces new capabilities, breaking changes, architecture shifts, or big performance/security work
+- Sounds ambiguous and you need the authoritative spec before coding
+
+Use `@/openspec/AGENTS.md` to learn:
+- How to create and apply change proposals
+- Spec format and conventions
+- Project structure and guidelines
+
+Keep this managed block so 'openspec update' can refresh the instructions.
+
+<!-- OPENSPEC:END -->

namingpaper-0.1.0/CLAUDE.md

@@ -0,0 +1,18 @@
+<!-- OPENSPEC:START -->
+# OpenSpec Instructions
+
+These instructions are for AI assistants working in this project.
+
+Always open `@/openspec/AGENTS.md` when the request:
+- Mentions planning or proposals (words like proposal, spec, change, plan)
+- Introduces new capabilities, breaking changes, architecture shifts, or big performance/security work
+- Sounds ambiguous and you need the authoritative spec before coding
+
+Use `@/openspec/AGENTS.md` to learn:
+- How to create and apply change proposals
+- Spec format and conventions
+- Project structure and guidelines
+
+Keep this managed block so 'openspec update' can refresh the instructions.
+
+<!-- OPENSPEC:END -->

namingpaper-0.1.0/PKG-INFO

@@ -0,0 +1,336 @@
+Metadata-Version: 2.4
+Name: namingpaper
+Version: 0.1.0
+Summary: CLI tool to rename academic papers using AI-extracted metadata
+Requires-Python: <3.14,>=3.11
+Requires-Dist: anthropic>=0.30.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pdf2image>=1.16.0
+Requires-Dist: pdfplumber>=0.10.0
+Requires-Dist: pillow>=10.0.0
+Requires-Dist: pydantic-settings>=2.0.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: typer>=0.9.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Provides-Extra: gemini
+Requires-Dist: google-generativeai>=0.5.0; extra == 'gemini'
+Provides-Extra: openai
+Requires-Dist: openai>=1.0.0; extra == 'openai'
+Description-Content-Type: text/markdown
+
+# namingpaper
+
+A CLI tool that renames academic PDF papers using AI-extracted metadata.
+
+**Before:** `1-s2.0-S0304405X13000044-main.pdf`
+
+**After:** `Fama, French, (1993, JFE), Common risk factors in the returns....pdf`
+
+## Features
+
+- Extracts metadata (authors, year, journal, title) from PDFs using AI
+- Supports multiple AI providers: Claude, OpenAI, Gemini, and Ollama (local)
+- **Batch processing** - rename entire directories at once
+- **Custom templates** - flexible filename formatting
+- Dry-run mode by default for safety
+- Copy to output directory (keeps original file)
+- Handles filename collisions (skip, increment, or overwrite)
+- Common journal abbreviations (JFE, AER, QJE, etc.)
+
+## Installation
+
+```bash
+# Install from source
+git clone https://github.com/DanTsai0903/namingpaper.git
+cd namingpaper
+uv sync
+
+# With optional providers
+uv sync --extra openai    # OpenAI support
+uv sync --extra gemini    # Gemini support
+```
+
+## Quick Start
+
+```bash
+# Default uses Ollama (local, no API key needed)
+# Make sure Ollama is running with the required models
+ollama pull deepseek-ocr
+ollama pull llama3.1:8b
+
+# Preview the rename (dry run)
+namingpaper rename paper.pdf
+
+# Actually rename the file
+namingpaper rename paper.pdf --execute
+
+# Batch rename all PDFs in a directory
+namingpaper batch ~/Downloads/papers --execute
+```
+
+### Using Cloud Providers
+
+If you want to use Claude, OpenAI, or Gemini instead of local Ollama:
+
+```bash
+# Option 1: Set environment variable (temporary, current session only)
+export NAMINGPAPER_ANTHROPIC_API_KEY=sk-ant-api03-xxxxx
+namingpaper rename paper.pdf -p claude
+
+# Option 2: Add to shell profile (permanent)
+# For zsh (macOS default):
+echo 'export NAMINGPAPER_ANTHROPIC_API_KEY=sk-ant-api03-xxxxx' >> ~/.zshrc
+source ~/.zshrc
+
+# For bash:
+echo 'export NAMINGPAPER_ANTHROPIC_API_KEY=sk-ant-api03-xxxxx' >> ~/.bashrc
+source ~/.bashrc
+
+# Option 3: Use config file (~/.namingpaper/config.toml)
+mkdir -p ~/.namingpaper
+cat > ~/.namingpaper/config.toml << EOF
+ai_provider = "claude"
+anthropic_api_key = "sk-ant-api03-xxxxx"
+EOF
+```
+
+## Usage
+
+### Rename Command
+
+Rename a single PDF file.
+
+```bash
+namingpaper rename <pdf_path> [OPTIONS]
+
+Options:
+  -x, --execute              Actually rename (default is dry-run)
+  -y, --yes                  Skip confirmation prompt
+  -p, --provider TEXT        AI provider (claude, openai, gemini, ollama)
+  -o, --output-dir DIR       Copy to directory (keeps original)
+  -c, --collision STRATEGY   Handle collisions: skip, increment, overwrite
+```
+
+### Batch Command
+
+Rename multiple PDF files in a directory.
+
+```bash
+namingpaper batch <directory> [OPTIONS]
+
+Options:
+  -x, --execute              Actually rename (default is dry-run)
+  -y, --yes                  Skip confirmation prompt
+  -r, --recursive            Scan subdirectories
+  -f, --filter PATTERN       Only process files matching pattern (e.g., '2023*')
+  -p, --provider TEXT        AI provider (claude, openai, gemini, ollama)
+  -t, --template TEXT        Filename template or preset name
+  -o, --output-dir DIR       Copy to directory (keeps originals)
+  -c, --collision STRATEGY   Handle collisions: skip, increment, overwrite
+  --parallel N               Concurrent extractions (default: 1)
+  --json                     Output results as JSON
+```
+
+### Templates Command
+
+Show available filename templates.
+
+```bash
+namingpaper templates
+```
+
+## Examples
+
+### Single File
+
+```bash
+# Dry run with Ollama (default)
+namingpaper rename paper.pdf
+
+# Execute rename
+namingpaper rename paper.pdf --execute
+
+# Copy to a different folder (keeps original)
+namingpaper rename paper.pdf -o ~/Papers --execute
+
+# Use Claude
+namingpaper rename paper.pdf -p claude --execute
+
+# Use OpenAI
+namingpaper rename paper.pdf -p openai --execute
+
+# Auto-increment on collision
+namingpaper rename paper.pdf -c increment --execute
+
+# Skip confirmation
+namingpaper rename paper.pdf -xy
+```
+
+### Batch Processing
+
+```bash
+# Preview all renames in a directory
+namingpaper batch ~/Downloads/papers
+
+# Execute batch rename
+namingpaper batch ~/Downloads/papers --execute
+
+# Recursive scan with subdirectories
+namingpaper batch ~/Downloads/papers -r --execute
+
+# Filter by pattern (only 2023 papers)
+namingpaper batch ~/Downloads/papers -f "2023*" --execute
+
+# Use compact template
+namingpaper batch ~/Downloads/papers -t compact --execute
+
+# Custom template
+namingpaper batch ~/Downloads/papers -t "{year} - {authors} - {title}" --execute
+
+# Copy to organized folder
+namingpaper batch ~/Downloads -o ~/Papers/Organized --execute
+
+# Parallel processing (faster)
+namingpaper batch ~/Downloads/papers --parallel 4 --execute
+
+# Output as JSON (for scripting)
+namingpaper batch ~/Downloads/papers --json
+```
+
+### View Configuration
+
+```bash
+namingpaper config --show
+```
+
+## Filename Templates
+
+Templates control how the output filename is formatted.
+
+### Preset Templates
+
+| Name | Pattern | Example |
+|------|---------|---------|
+| `default` | `{authors}, ({year}, {journal}), {title}` | `Fama, French, (1993, JFE), Common risk....pdf` |
+| `compact` | `{authors} ({year}) {title}` | `Fama, French (1993) Common risk....pdf` |
+| `full` | `{authors}, ({year}, {journal_full}), {title}` | `Fama, French, (1993, Journal of Financial Economics), Common....pdf` |
+| `simple` | `{authors}_{year}_{title}` | `Fama, French_1993_Common risk....pdf` |
+
+### Template Placeholders
+
+| Placeholder | Description |
+|-------------|-------------|
+| `{authors}` | Author surnames (comma-separated, "et al" if >3) |
+| `{year}` | Publication year |
+| `{journal}` | Journal abbreviation (or full name if no abbrev) |
+| `{journal_abbrev}` | Journal abbreviation only |
+| `{journal_full}` | Full journal name |
+| `{title}` | Paper title (truncated) |
+
+### Custom Templates
+
+```bash
+# Year-first format
+namingpaper batch ~/papers -t "{year} - {authors} - {title}"
+
+# Minimal format
+namingpaper batch ~/papers -t "{authors} {year}"
+
+# Full journal name
+namingpaper batch ~/papers -t "{authors}, ({year}, {journal_full}), {title}"
+```
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `NAMINGPAPER_ANTHROPIC_API_KEY` | Anthropic API key (for Claude) |
+| `NAMINGPAPER_OPENAI_API_KEY` | OpenAI API key |
+| `NAMINGPAPER_GEMINI_API_KEY` | Google Gemini API key |
+| `NAMINGPAPER_AI_PROVIDER` | Provider: `ollama` (default), `claude`, `openai`, `gemini` |
+| `NAMINGPAPER_MODEL_NAME` | Override default model for provider |
+| `NAMINGPAPER_OLLAMA_BASE_URL` | Ollama API URL (default: `http://localhost:11434`) |
+| `NAMINGPAPER_MAX_AUTHORS` | Max authors before "et al" (default: 3) |
+| `NAMINGPAPER_MAX_FILENAME_LENGTH` | Max filename length (default: 200) |
+
+### Config File
+
+Create `~/.namingpaper/config.toml`:
+
+```toml
+# Default provider (ollama requires no API key)
+ai_provider = "ollama"
+ollama_base_url = "http://localhost:11434"
+
+# Or use cloud providers
+# ai_provider = "claude"
+# anthropic_api_key = "sk-ant-..."
+
+# Formatting options
+max_authors = 3
+max_filename_length = 200
+```
+
+## AI Providers
+
+### Ollama (Default)
+
+Local LLM, no API key needed. Just have Ollama running.
+
+```bash
+# Pull a vision model
+ollama pull llama3.2-vision
+
+# Use it (default provider)
+namingpaper rename paper.pdf
+
+# Or specify a different model
+NAMINGPAPER_MODEL_NAME=deepseek-ocr namingpaper rename paper.pdf
+```
+
+### Claude (included by default)
+
+```bash
+export NAMINGPAPER_ANTHROPIC_API_KEY=sk-ant-...
+namingpaper rename paper.pdf -p claude
+```
+
+### OpenAI
+
+```bash
+uv sync --extra openai
+export NAMINGPAPER_OPENAI_API_KEY=sk-...
+namingpaper rename paper.pdf -p openai
+```
+
+### Gemini
+
+```bash
+uv sync --extra gemini
+export NAMINGPAPER_GEMINI_API_KEY=...
+namingpaper rename paper.pdf -p gemini
+```
+
+## Development
+
+```bash
+# Clone and setup
+git clone https://github.com/DanTsai0903/namingpaper.git
+cd namingpaper
+uv sync --extra dev
+
+# Run tests
+uv run pytest -v
+
+# Run a specific test
+uv run pytest tests/test_formatter.py -v
+```
+
+## License
+
+MIT