nber-cli 0.1.3__tar.gz → 0.2.0__tar.gz

nber_cli-0.2.0/.claude/agents/code-to-docs.md

@@ -0,0 +1,67 @@
+---
+name: code-to-docs
+description: |
+  Use this agent when the user needs to generate, update, or complete project documentation based on source code.
+  Examples:
+  - "给 fetcher.py 加文档"
+  - "文档是不是漏了批量下载的说明"
+  - "更新一下 cli.md"
+  - "mcp.py 新增了 tool，文档需要同步"
+color: green
+---
+
+# Code-to-Docs Agent
+
+You are a documentation maintainer. Your job is to keep project documentation in sync with the source code.
+
+## Project Structure
+
+- Source code: `src/nber_cli/` (Python package)
+- English docs: `docs/en/` (Markdown files)
+- Chinese docs: `docs/zh/` (Markdown translations)
+- Site config: `mkdocs.yml`
+
+## Your Workflow
+
+1. **Identify Scope**: Determine which source files or doc files the user wants to update. If unclear, ask.
+
+2. **Read Source**: Use `Read` to examine the relevant Python source files. Understand:
+   - Public functions and their signatures
+   - CLI commands, arguments, and options
+   - Data models and their fields
+   - Configuration options
+   - Error handling and edge cases
+
+3. **Read Existing Docs**: Use `Read` to examine the current documentation in `docs/`. Note:
+   - What is already covered
+   - What is missing or outdated
+   - The writing style and formatting conventions
+
+4. **Compare and Identify Gaps**: Create a checklist of discrepancies between code and docs.
+
+5. **Generate or Update Docs**: Produce Markdown content that:
+   - Matches the existing style (tone, heading levels, code block formatting)
+   - Covers all public interfaces
+   - Includes accurate command examples
+   - Documents all options and their defaults
+   - Mentions error conditions where relevant
+
+6. **Write or Edit**: Use `Write` for new doc files, `Edit` for updating existing ones. Never overwrite without confirming the scope with the user.
+
+7. **Cross-reference mkdocs.yml**: Ensure any new doc files are reflected in the nav if needed.
+
+## Style Rules
+
+- CLI docs use tables for options and commands
+- API docs include function signatures and brief descriptions
+- Examples use realistic data (e.g., `w25000` for paper IDs)
+- Keep headings in sentence case for English docs
+- Do not invent features that do not exist in the code
+
+## Output Format
+
+When reporting to the user, summarize:
+- Which files you examined
+- What gaps you found
+- What changes you made (or propose to make)
+- Any files that still need attention

nber_cli-0.2.0/.claude/agents/sync-docs-for-i18n.md

@@ -0,0 +1,84 @@
+---
+name: sync-docs-for-i18n
+description: |
+  Use this agent when the user needs to check or synchronize translated documentation against the English source.
+  Examples:
+  - "同步一下中文文档"
+  - "看看中文文档是不是都同步了"
+  - "zh 的 cli.md 是不是最新的"
+  - "检查所有翻译文件的完整性"
+color: cyan
+---
+
+# Sync-Docs-for-i18n Agent
+
+You are a documentation localization auditor. Your job is to ensure that translated documentation files stay in perfect sync with their English source files, checking every file individually.
+
+## Project Structure
+
+- English source docs: `docs/en/` (10 files: index.md, cli.md, configuration.md, contributing.md, development.md, getting-started.md, mcp.md, python-api.md, changelog.md, policy.md)
+- Chinese translations: `docs/zh/` (should mirror the above)
+- Site config: `mkdocs.yml` defines the nav structure
+
+## Your Workflow (Per-File)
+
+1. **List All Files**: Use `Bash` to list all `.md` files in `docs/en/` and `docs/zh/`. Confirm the file sets match.
+
+2. **File-by-File Comparison**: For each English file, read both the English source and the Chinese translation:
+   - `docs/en/index.md` vs `docs/zh/index.md`
+   - `docs/en/cli.md` vs `docs/zh/cli.md`
+   - `docs/en/configuration.md` vs `docs/zh/configuration.md`
+   - `docs/en/contributing.md` vs `docs/zh/contributing.md`
+   - `docs/en/development.md` vs `docs/zh/development.md`
+   - `docs/en/getting-started.md` vs `docs/zh/getting-started.md`
+   - `docs/en/mcp.md` vs `docs/zh/mcp.md`
+   - `docs/en/python-api.md` vs `docs/zh/python-api.md`
+   - `docs/en/changelog.md` vs `docs/zh/changelog.md`
+   - `docs/en/policy.md` vs `docs/zh/policy.md`
+
+3. **Check for These Issues on Every File**:
+   - **Missing file**: Chinese version does not exist
+   - **Missing sections**: A heading in English has no counterpart in Chinese
+   - **Extra sections**: A heading in Chinese has no counterpart in English
+   - **Content drift**: Same section but different information
+   - **Stale examples**: Code examples in Chinese differ from English
+   - **URL/link differences**: Cross-references or links differ
+   - **Table differences**: Option tables have different rows or columns
+   - **Heading level mismatch**: Same content but different heading hierarchy
+
+4. **Produce a Diff Report**: For each file, report:
+   - Status: `SYNCED`, `MISSING_FILE`, `PARTIAL`, or `OUTDATED`
+   - A bullet list of specific discrepancies
+   - Recommended actions
+
+5. **Generate Patch Content** (if user asks): Produce the exact Markdown content needed to bring the Chinese file into sync. Use `Edit` or `Write` only after user confirmation.
+
+## Comparison Rules
+
+- Command examples must be identical (only surrounding description text changes)
+- Option tables must have the same rows in the same order
+- All headings must have a 1-to-1 mapping
+- Links to other docs must point to correct translated paths
+
+## Output Format
+
+Present findings as:
+
+```
+## File Audit Summary
+
+| File | Status | Issues |
+|------|--------|--------|
+| index.md | SYNCED | None |
+| cli.md | PARTIAL | 2 sections missing |
+| ... | ... | ... |
+
+## Detailed Findings
+
+### docs/zh/cli.md
+- [ ] Section "Exit Codes" missing
+- [ ] Example `--per-page 100` not translated
+...
+```
+
+Always check every file. Do not sample or skip files.

nber_cli-0.2.0/.claude/settings.json

@@ -0,0 +1,25 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(uv add *)",
+      "Bash(uv run *)",
+      "Bash(uv lock *)",
+      "Bash(uv sync *)",
+      "Bash(nber-cli:*)",
+      "WebFetch(domain:openai.github.io)",
+      "WebFetch(domain:openai.com)",
+      "WebFetch(domain:nber.org)",
+      "WebFetch(domain:github.com)",
+      "mcp__ide__getDiagnostics",
+      "mcp__codex-mcp__codex",
+      "mcp__codex-mcp__codex-reply"
+    ],
+    "deny": [
+      "Read(.env)"
+    ]
+  },
+  "enabledMcpjsonServers": [
+    "codex-mcp",
+    "context7"
+  ]
+}

nber_cli-0.2.0/.claude-plugin/marketplace.json

@@ -0,0 +1,24 @@
+{
+  "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
+  "name": "nber-cli",
+  "description": "Claude Code marketplace for NBER-CLI research workflows.",
+  "version": "0.2.0",
+  "owner": {
+    "name": "Song Tan",
+    "email": "sepinetam@gmail.com",
+    "url": "https://github.com/sepinetam"
+  },
+  "plugins": [
+    {
+      "name": "nber-cli",
+      "description": "Use NBER-CLI to search, inspect, download, and serve NBER working paper workflows.",
+      "version": "0.2.0",
+      "author": {
+        "name": "Song Tan",
+        "email": "sepinetam@gmail.com"
+      },
+      "category": "development",
+      "source": "./plugins/nber-cli"
+    }
+  ]
+}

nber_cli-0.2.0/.codex/config.toml

@@ -0,0 +1,15 @@
+[mcp_servers.claude-code-docs]
+url = "https://code.claude.com/docs/mcp"
+
+[mcp_servers.claude-code-docs.tools.search_claude_code_docs]
+approval_mode = "approve"
+
+[mcp_servers.claude-code-docs.tools.query_docs_filesystem_claude_code_docs]
+approval_mode = "approve"
+
+[mcp_servers.context7]
+url = "https://mcp.context7.com/mcp"
+
+[mcp_servers.codex-mcp]
+command = "codex"
+args = ["mcp-server"]

nber_cli-0.2.0/.github/workflows/docs.yml

@@ -0,0 +1,61 @@
+name: Docs
+
+on:
+  push:
+    branches:
+      - master
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: pages-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+
+      - name: Install dependencies
+        run: uv sync --group docs
+
+      - name: Build documentation
+        run: uv run --group docs mkdocs build --strict
+
+      - name: Upload Pages artifact
+        if: github.event_name == 'push' && github.ref == 'refs/heads/master'
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+
+  deploy:
+    if: github.event_name == 'push' && github.ref == 'refs/heads/master'
+    needs: build
+    runs-on: ubuntu-latest
+
+    permissions:
+      pages: write
+      id-token: write
+
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

nber_cli-0.2.0/.github/workflows/lint.yml

@@ -0,0 +1,32 @@
+name: Lint
+
+on:
+  push:
+    branches:
+      - master
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+
+      - name: Install dependencies
+        run: uv sync --dev
+
+      - name: Run ruff
+        run: uv run ruff check .

nber_cli-0.2.0/.github/workflows/pytest.yml

@@ -0,0 +1,32 @@
+name: Pytest
+
+on:
+  push:
+    branches:
+      - master
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+
+      - name: Install dependencies
+        run: uv sync --dev
+
+      - name: Run pytest
+        run: uv run pytest

{nber_cli-0.1.3 → nber_cli-0.2.0}/.gitignore

@@ -6,6 +6,8 @@ dist/
 wheels/
 *.egg-info
 
+release/
+
 # Virtual environments
 .venv
 
@@ -17,3 +19,14 @@ wheels/
 
 # OS X
 *.DS_Store
+
+# local files
+*.local.*
+
+# Coverage
+.coverage
+htmlcov/
+site/
+
+# Files
+*.pdf

nber_cli-0.2.0/.mcp.json

@@ -0,0 +1,16 @@
+{
+  "mcpServers": {
+    "codex-mcp": {
+      "type": "stdio",
+      "command": "codex",
+      "args": [
+        "mcp-server"
+      ],
+      "env": {}
+    },
+    "context7": {
+      "type": "http",
+      "url": "https://mcp.context7.com/mcp"
+    }
+  }
+}

nber_cli-0.2.0/CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [0.2.0] - 2026-05-31
+
+### Added
+- `download` subcommand: single paper ID or batch mode (`--batch`), explicit file path (`--file`), target directory (`--save-base`).
+- `info` subcommand: paper metadata with `--all` flag for full details and `--format json` option.
+- `search` subcommand: full-text search with date filters (`--start-date`, `--end-date`), pagination (`--page`, `--per-page`), `--format json` option.
+- `mcp-server` subcommand: MCP server for AI agent integration with stdio and streamable_http transports.
+
+### Changed
+- Reworked CLI into subcommand syntax (`nber-cli <subcommand>`).
+- Simplified downloader to direct async HTTP PDF fetches (removed database-backed state tracking).
+- Removed legacy web UI module and script entrypoint.
+
+## [0.1.4] - 2025-08-09
+
+### Added
+- Added `--version` / `-v` flag to display current version.
+- Added comprehensive help message with examples.
+- Added `__main__.py` file to support `python -m nber_cli` usage.
+- Added argument grouping for better CLI organization.
+- Added automatic help display when no arguments are provided.

nber_cli-0.2.0/PKG-INFO

@@ -0,0 +1,129 @@
+Metadata-Version: 2.4
+Name: nber-cli
+Version: 0.2.0
+Summary: A command line interface for reaching the National Bureau of Economic Research (NBER) paper without brower.
+Project-URL: Homepage, https://github.com/sepinetam/nber-cli
+Project-URL: Repository, https://github.com/sepinetam/nber-cli
+Project-URL: Issues, https://github.com/sepinetam/nber-cli/issues
+Project-URL: Documentation, https://sepinetam.github.io/nber-cli/
+Author-email: Song Tan <sepinetam@gmail.com>
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: cli,mcp,nber,research,working-papers
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Utilities
+Requires-Python: >=3.11
+Requires-Dist: aiohttp
+Requires-Dist: aiohttp-retry
+Requires-Dist: certifi
+Requires-Dist: fake-useragent
+Requires-Dist: mcp>=1.27.1
+Description-Content-Type: text/markdown
+
+# NBER-CLI
+A command line interface for reaching the National Bureau of Economic Research (NBER) paper without brower.
+
+[![Pytest](https://github.com/sepinetam/nber-cli/actions/workflows/pytest.yml/badge.svg)](https://github.com/sepinetam/nber-cli/actions/workflows/pytest.yml)
+[![Lint](https://github.com/sepinetam/nber-cli/actions/workflows/lint.yml/badge.svg)](https://github.com/sepinetam/nber-cli/actions/workflows/lint.yml)
+[![Docs](https://github.com/sepinetam/nber-cli/actions/workflows/docs.yml/badge.svg)](https://github.com/sepinetam/nber-cli/actions/workflows/docs.yml)
+[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
+
+[简体中文](README.zh-CN.md) | [Documentation](docs/en/index.md)
+
+> **NBER** is a registered trademark of the [National Bureau of Economic Research](https://www.nber.org). This project is an independent open-source tool and is **not affiliated with, endorsed by, or sponsored by** the National Bureau of Economic Research. By using this project, you agree to the [Usage Policy](docs/en/policy.md).
+
+## Features
+
+- Search NBER working papers by title, paper number, author, abstract, or keyword.
+- Fetch structured metadata and abstracts for a paper ID such as `w25000`.
+- Download single papers or batches as PDF files.
+- Expose the same core workflows as MCP tools for AI agents.
+- Return human-readable output by default, with JSON output for automation.
+
+## Quick Start
+
+### Use in Agents
+
+NBER-CLI can be used by agents through plugins, the MCP server, and the skill. Claude Code and Codex should install the NBER-CLI plugin first; OpenClaw and other agents should use the MCP server plus the skill.
+
+If you want an agent to install and check NBER-CLI automatically, send it this prompt:
+
+```text
+Install NBER-CLI globally for yourself from https://github.com/sepinetam/nber-cli, and check the status.
+```
+
+After installation, verify it with either prompt:
+
+```text
+I remember that in 2025, Anton had a paper on NBER about Agent for Econ. Download it to the current directory.
+```
+
+```text
+I remember that paper w25000 was interesting. Show me its abstract.
+```
+
+If you are an agent, visit the [Agent Guides](docs/en/agents/index.md).
+
+### CLI Mode
+Run commands directly with `uvx`:
+
+```bash
+uvx nber-cli search "Labor Economic"
+uvx nber-cli info w25000
+uvx nber-cli download w34567
+```
+
+Or install the command first:
+
+```bash
+uv tool install nber-cli
+nber-cli search "Labor Economic"
+nber-cli info w25000
+nber-cli download w34567
+```
+
+### MCP Server Mode
+
+NBER-CLI can run as a stdio MCP server:
+
+```bash
+uvx nber-cli mcp-server
+```
+
+Example MCP client configuration:
+
+```json
+{
+  "mcpServers": {
+    "nber-cli-mcp": {
+      "command": "uvx",
+      "args": ["nber-cli", "mcp-server"]
+    }
+  }
+}
+```
+
+The MCP server exposes tools for paper lookup, search, and PDF download.
+
+## Documentation
+
+More usage details, command references, MCP setup, Python API examples, development notes, and release history are available in the [documentation](docs/en/index.md).
+
+## Development
+
+```bash
+uv sync --dev --group docs
+uv run pytest
+uv run ruff check .
+uv run --group docs mkdocs serve
+```
+
+## License
+
+NBER-CLI is released under the [Apache-2.0 License](LICENSE).

nber_cli-0.2.0/README.md

@@ -0,0 +1,101 @@
+# NBER-CLI
+A command line interface for reaching the National Bureau of Economic Research (NBER) paper without brower.
+
+[![Pytest](https://github.com/sepinetam/nber-cli/actions/workflows/pytest.yml/badge.svg)](https://github.com/sepinetam/nber-cli/actions/workflows/pytest.yml)
+[![Lint](https://github.com/sepinetam/nber-cli/actions/workflows/lint.yml/badge.svg)](https://github.com/sepinetam/nber-cli/actions/workflows/lint.yml)
+[![Docs](https://github.com/sepinetam/nber-cli/actions/workflows/docs.yml/badge.svg)](https://github.com/sepinetam/nber-cli/actions/workflows/docs.yml)
+[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
+
+[简体中文](README.zh-CN.md) | [Documentation](docs/en/index.md)
+
+> **NBER** is a registered trademark of the [National Bureau of Economic Research](https://www.nber.org). This project is an independent open-source tool and is **not affiliated with, endorsed by, or sponsored by** the National Bureau of Economic Research. By using this project, you agree to the [Usage Policy](docs/en/policy.md).
+
+## Features
+
+- Search NBER working papers by title, paper number, author, abstract, or keyword.
+- Fetch structured metadata and abstracts for a paper ID such as `w25000`.
+- Download single papers or batches as PDF files.
+- Expose the same core workflows as MCP tools for AI agents.
+- Return human-readable output by default, with JSON output for automation.
+
+## Quick Start
+
+### Use in Agents
+
+NBER-CLI can be used by agents through plugins, the MCP server, and the skill. Claude Code and Codex should install the NBER-CLI plugin first; OpenClaw and other agents should use the MCP server plus the skill.
+
+If you want an agent to install and check NBER-CLI automatically, send it this prompt:
+
+```text
+Install NBER-CLI globally for yourself from https://github.com/sepinetam/nber-cli, and check the status.
+```
+
+After installation, verify it with either prompt:
+
+```text
+I remember that in 2025, Anton had a paper on NBER about Agent for Econ. Download it to the current directory.
+```
+
+```text
+I remember that paper w25000 was interesting. Show me its abstract.
+```
+
+If you are an agent, visit the [Agent Guides](docs/en/agents/index.md).
+
+### CLI Mode
+Run commands directly with `uvx`:
+
+```bash
+uvx nber-cli search "Labor Economic"
+uvx nber-cli info w25000
+uvx nber-cli download w34567
+```
+
+Or install the command first:
+
+```bash
+uv tool install nber-cli
+nber-cli search "Labor Economic"
+nber-cli info w25000
+nber-cli download w34567
+```
+
+### MCP Server Mode
+
+NBER-CLI can run as a stdio MCP server:
+
+```bash
+uvx nber-cli mcp-server
+```
+
+Example MCP client configuration:
+
+```json
+{
+  "mcpServers": {
+    "nber-cli-mcp": {
+      "command": "uvx",
+      "args": ["nber-cli", "mcp-server"]
+    }
+  }
+}
+```
+
+The MCP server exposes tools for paper lookup, search, and PDF download.
+
+## Documentation
+
+More usage details, command references, MCP setup, Python API examples, development notes, and release history are available in the [documentation](docs/en/index.md).
+
+## Development
+
+```bash
+uv sync --dev --group docs
+uv run pytest
+uv run ruff check .
+uv run --group docs mkdocs serve
+```
+
+## License
+
+NBER-CLI is released under the [Apache-2.0 License](LICENSE).