nber-cli 0.3.0__tar.gz → 0.4.0__tar.gz

nber_cli-0.4.0/CHANGELOG.md

@@ -0,0 +1,68 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [0.4.0] - 2026-06-04
+
+### Added
+- `nber-cli info --refresh` skips the local `info_cache` and re-fetches the paper from NBER. The new data is written back to the cache when the cache is enabled.
+- `nber-cli info cache --turn-on` / `--turn-off` toggle the `info_cache` lookup globally and persist the state to `~/.nber-cli/config.json`.
+- `nber-cli info cache --set-refresh <N>` sets the cache refresh interval in days. The value is persisted to `~/.nber-cli/config.json` and used as the TTL for every subsequent `info` call. Defaults to `30` days.
+- `nber-cli info cache clear` with `--days`, `--all`, `--start-date`, or `--end-date` mirrors the `feed clean` parameter set, using `last_fetched_at` from the `info_cache` table. `nber-cli info cache clean` is a convenience alias for `clear --all`.
+- `nber-cli info cache` (no sub-action) prints the current cache state, TTL, and cached row count.
+- New `nber_cli.config_store` module: centralised read and write of `~/.nber-cli/config.json` plus the `InfoCacheSettings` dataclass and helpers (`get_info_cache_settings`, `set_info_cache_enabled`, `set_info_cache_ttl_days`).
+- New `nber_cli.info_cache.get_paper_with_info_cache_result` async helper that returns an `InfoCacheLookupResult` carrying the `NBER` paper and a `from_cache` flag, so callers (CLI and MCP) can surface a "loaded from cache" hint.
+- Public Python API exports: `InfoCacheSettings`, `InfoCacheLookupResult`, `clear_info_cache`, `count_info_cache`, `get_info_cache_settings`, `get_info_cache_ttl_days`, `is_info_cache_enabled`, `is_info_cache_expired`, `set_info_cache_enabled`, `set_info_cache_ttl_days`, `NBERInfoCacheClearResult`.
+
+### Changed
+- `~/.nber-cli/config.json` now carries an `info` section: `info.cache_enabled` (default `true`) and `info.cache_ttl_days` (default `30`). Missing or malformed fields fall back to defaults.
+- `info` now prints a one-line stderr hint when the paper was served from the local cache, pointing to `nber-cli info <id> --refresh` for a fresh fetch.
+
+## [0.3.1] - 2026-06-03
+
+### Added
+- `db init` and `db migrate` top-level subcommands replace `feed init` and `feed migrate`. The database is now general-purpose and stores feed cache, behavior logs, and paper metadata cache.
+- `info_cache` table caches paper metadata fetched via `info` and the MCP `get_paper_info` tool. Subsequent lookups return immediately from the cache.
+- `query_log`, `download_log`, and `info_log` tables record search keywords, download outcomes, and paper info lookups for later auditing.
+- `schema_version` field written to `~/.nber-cli/config.json` so future schema migrations can roll forward safely.
+
+### Changed
+- Default database renamed from `feed.db` to `nber.db`. Existing `~/.nber-cli/feed.db` installations continue to work without manual steps.
+- Database schema upgraded from `user_version = 1` to `user_version = 2`. Existing v1 databases are upgraded automatically on next CLI invocation; original `feed_items` rows are preserved.
+- Database code consolidated into `nber_cli.db`. The original `init_feed_database`, `migrate_feed_database`, and `get_feed_database_path` helpers are kept as thin compatibility wrappers.
+
+## [0.3.0] - 2026-06-03
+
+### Added
+- `feed init` subcommand: initialize a local SQLite feed cache and write its path to user config.
+- `feed fetch` subcommand: fetch NBER's new working papers RSS feed, cache seen items, and show newly discovered papers by default.
+- `feed fetch --max-items`: limit displayed feed output. When used without `--display-all`, display-all behavior is enabled automatically.
+- `feed migrate` subcommand: move the feed cache database and SQLite sidecar files to a new path, then update user config.
+- `feed clean` subcommand: clean cached feed database records by age, date range, or all records after interactive confirmation.
+- Python API exports for feed cache helpers and feed result models.
+
+### Changed
+- Added user config support at `~/.nber-cli/config.json` for the feed cache database path.
+- Expanded English and Chinese documentation for feed commands, configuration, Python API, and release notes.
+
+## [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.3.0 → nber_cli-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nber-cli
-Version: 0.3.0
+Version: 0.4.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

nber_cli-0.4.0/docs/en/changelog.md

@@ -0,0 +1,74 @@
+# Changelog
+
+All notable changes to this project will be documented here.
+
+## 0.4.0 - 2026-06-04
+
+### Added
+
+- Added `nber-cli info --refresh` to bypass the local `info_cache` and re-fetch paper metadata from NBER. The fresh data is written back to the cache when the cache is enabled.
+- Added `nber-cli info cache --turn-on` and `--turn-off` to toggle the `info_cache` lookup globally. The setting is persisted to `~/.nber-cli/config.json`.
+- Added `nber-cli info cache --set-refresh <N>` to set the cache refresh interval in days. The value is persisted to `~/.nber-cli/config.json` and applied as the TTL for every subsequent `info` call. Defaults to `30` days.
+- Added `nber-cli info cache clear` with the same parameter set as `feed clean`: `--days`, `--all`, `--start-date`, and `--end-date`. Filtering uses `last_fetched_at` from the `info_cache` table. `nber-cli info cache clean` is a convenience alias for `clear --all`.
+- Added `nber-cli info cache` (no sub-action) to print the current cache state, TTL, and cached row count.
+- Added `nber_cli.config_store` module with `InfoCacheSettings` and helpers (`get_info_cache_settings`, `set_info_cache_enabled`, `set_info_cache_ttl_days`) for reading and writing `~/.nber-cli/config.json`.
+- Added `nber_cli.info_cache.get_paper_with_info_cache_result` async helper that returns an `InfoCacheLookupResult` carrying the `NBER` paper and a `from_cache` flag.
+- Added public Python API exports for the new info cache helpers and `NBERInfoCacheClearResult` model.
+
+### Changed
+
+- `~/.nber-cli/config.json` now stores an `info` section: `info.cache_enabled` (default `true`) and `info.cache_ttl_days` (default `30`). Missing or malformed fields fall back to defaults.
+- `info` now prints a one-line stderr hint when the paper was served from the local cache, pointing to `nber-cli info <id> --refresh` for a fresh fetch.
+
+## 0.3.1 - 2026-06-03
+
+### Added
+
+- Added `nber-cli db init` and `nber-cli db migrate` for initializing and relocating the local database. These replace `feed init` and `feed migrate`.
+- Added `info_cache` table so repeated `nber-cli info` and MCP `get_paper_info` calls return immediately from cache.
+- Added `query_log`, `download_log`, and `info_log` tables for recording search keywords, download outcomes, and info lookups.
+- Added `schema_version` field in `~/.nber-cli/config.json` for forward-compatible schema upgrades.
+
+### Changed
+
+- Renamed default database file from `feed.db` to `nber.db`. Existing `~/.nber-cli/feed.db` installations keep working without manual steps.
+- Upgraded database schema from version 1 to version 2 with automatic upgrade on next invocation.
+- Consolidated database code into `nber_cli.db`. Old `init_feed_database` and `migrate_feed_database` helpers remain as thin compatibility wrappers.
+
+## 0.3.0 - 2026-06-03
+
+### Added
+
+- Added `nber-cli feed init` for creating a local SQLite feed cache.
+- Added `nber-cli feed fetch` for fetching NBER's new working papers RSS feed and showing newly cached items.
+- Added `nber-cli feed fetch --max-items` for limiting displayed feed output.
+- Added `nber-cli feed migrate` for moving the feed cache database and updating user config.
+- Added `nber-cli feed clean` for cleaning cached feed database records with confirmation.
+- Added Python API documentation for feed cache helpers and feed data models.
+
+### Changed
+
+- Added user config documentation for `~/.nber-cli/config.json` and `feed.db-path`.
+- Expanded English and Chinese feed cache documentation across CLI, getting started, configuration, and Python API pages.
+
+## 0.2.0 - 2026-05-27
+
+### Changed
+
+- Reworked the CLI into `nber-cli download ...` subcommand syntax.
+- Added `--file/-f` and `--save-base/-s` path handling behavior.
+- Added `--batch/-b` multi-ID download mode.
+- Removed database-backed download state tracking.
+- Simplified the downloader to direct async HTTP PDF fetches.
+- Updated documentation for the v0.2 command model.
+- Removed the 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` support for `python -m nber_cli`.
+- Added argument grouping for better CLI organization.
+- Added automatic help display when no arguments are provided.

{nber_cli-0.3.0 → nber_cli-0.4.0}/docs/en/cli.md

@@ -22,6 +22,7 @@ Running `nber-cli` without a subcommand prints the top-level help and exits succ
 | `download` | Download one or more paper PDFs. |
 | `info` | Show metadata and abstract for one paper. |
 | `search` | Search NBER working papers. |
+| `db` | Manage the local SQLite database. |
 | `feed` | Manage the NBER new working papers RSS feed cache. |
 | `mcp-server` | Start the MCP server for agents. |
 
@@ -99,6 +100,85 @@ nber-cli info w25000 -f json
 | `paper_id` | Required paper ID, with or without the `w` prefix. |
 | `--all`, `-a` | Include related fields and published-version information when available. |
 | `--format`, `-f` | Output format: `list` or `json`. Defaults to `list`. |
+| `--refresh` | Bypass the local `info_cache` and re-fetch from NBER. The new data is written back to the cache when the cache is enabled. |
+
+When the cache is enabled and the cached entry has not yet passed the configured TTL, repeated `info` calls are served from the local database. The first `info` call after a TTL expiry, or any call with `--refresh`, performs a live fetch.
+
+The MCP `get_paper_info` tool follows the same cache behavior, including the `--refresh` flag.
+
+## info cache
+
+Manage the `info_cache` lookup behavior and clear cached records.
+
+Show the current cache state, TTL, and row count:
+
+```bash
+nber-cli info cache
+```
+
+Toggle the cache globally:
+
+```bash
+nber-cli info cache --turn-on
+nber-cli info cache --turn-off
+```
+
+Set the cache refresh interval in days:
+
+```bash
+nber-cli info cache --set-refresh 7
+nber-cli info cache --set-refresh 30
+```
+
+`--set-refresh` requires a positive integer. The new value is written to `~/.nber-cli/config.json` and used as the TTL for every subsequent `info` call.
+
+Clean cached records not refreshed in the last 30 days:
+
+```bash
+nber-cli info cache clear
+nber-cli info cache clear --days 30
+```
+
+Clean all cached records:
+
+```bash
+nber-cli info cache clear --all
+nber-cli info cache clean
+```
+
+`info cache clean` is a convenience alias for `info cache clear --all`.
+
+Clean cached records by `last_fetched_at` date:
+
+```bash
+nber-cli info cache clear --end-date 2026-06-01
+nber-cli info cache clear --start-date 2026-05-01 --end-date 2026-06-01
+```
+
+`--end-date` without `--start-date` cleans from the earliest cached record through the end date. `--start-date` and `--end-date` are inclusive. Passing only `--start-date` is invalid.
+
+Before deleting anything, `info cache clear` prints how many cached records match and asks for confirmation:
+
+```text
+This operation is irreversible.
+Deleted info cache records may be fetched again from NBER.
+Continue? [y/N]:
+```
+
+Only `y` or `Y` continues. Any other response aborts without deleting records.
+
+### info cache Options
+
+| Subcommand | Option | Description |
+| --- | --- | --- |
+| (none) | `--turn-on` | Enable the info cache globally. |
+| (none) | `--turn-off` | Disable the info cache globally. |
+| (none) | `--set-refresh` | Set the info cache refresh interval in days. Must be a positive integer. |
+| `clear` | `--days` | Clean cached records not refreshed for this many days. Defaults to `30`. |
+| `clear` | `--all` | Clean all cached records. |
+| `clear` | `--start-date` | Clean cached records refreshed on or after this date, formatted `YYYY-MM-DD`. |
+| `clear` | `--end-date` | Clean cached records refreshed on or before this date, formatted `YYYY-MM-DD`. |
+| `clean` | — | Alias for `clear --all`. |
 
 ## search
 
@@ -142,18 +222,7 @@ When only `--start-date` is provided, NBER-CLI automatically uses the current da
 
 ## feed
 
-`feed` works with NBER's new working papers RSS feed and a local SQLite cache. The cache tracks which RSS items have already been seen, so `feed fetch` can show only newly discovered papers by default.
-
-### feed init
-
-Initialize the feed cache database and write the database path to the user config:
-
-```bash
-nber-cli feed init
-nber-cli feed init --db-path ~/.nber-cli/feed.db
-```
-
-If `--db-path` is omitted, the default database path is `~/.nber-cli/feed.db`.
+`feed` works with NBER's new working papers RSS feed and the local SQLite database. The database tracks which RSS items have already been seen, so `feed fetch` can show only newly discovered papers by default.
 
 ### feed fetch
 
@@ -185,16 +254,6 @@ nber-cli feed fetch --format json
 nber-cli feed fetch -f json
 ```
 
-### feed migrate
-
-Move the feed cache database to a new path and update the user config:
-
-```bash
-nber-cli feed migrate ~/data/nber-feed.db
-```
-
-Migration moves the SQLite database file and any SQLite sidecar files such as `-wal`, `-shm`, and `-journal`. The target path must not already exist.
-
 ### feed clean
 
 Clean cached feed database records. This deletes records from the local cache, not from NBER. Deleted cache records may be fetched again as new items if they still appear in the RSS feed.
@@ -235,16 +294,48 @@ Only `y` or `Y` continues. Any other response aborts without deleting records.
 
 | Subcommand | Option | Description |
 | --- | --- | --- |
-| `init` | `--db-path` | SQLite cache database path. Defaults to `~/.nber-cli/feed.db`. |
 | `fetch` | `--display-all [true|false]` | Display all fetched RSS items instead of only new items. |
 | `fetch` | `--format`, `-f` | Output format: `list` or `json`. Defaults to `list`. |
 | `fetch` | `--max-items` | Maximum number of feed items to display. |
-| `migrate` | `new_db_path` | New SQLite cache database path. |
 | `clean` | `--days` | Clean cached records not seen for this many days. Defaults to `30`. |
 | `clean` | `--all` | Clean all cached feed records. |
 | `clean` | `--start-date` | Clean cached records last seen on or after this date, formatted `YYYY-MM-DD`. |
 | `clean` | `--end-date` | Clean cached records last seen on or before this date, formatted `YYYY-MM-DD`. |
 
+## db
+
+`db` manages the local SQLite database used by `info`, `search`, `download`, and `feed` for cache and behavior logs.
+
+### db init
+
+Initialize the database and write its path to the user config:
+
+```bash
+nber-cli db init
+nber-cli db init --db-path ~/.nber-cli/nber.db
+```
+
+If `--db-path` is omitted, the default database path is `~/.nber-cli/nber.db`.
+
+If an existing `~/.nber-cli/feed.db` from 0.3.0 is present and no `nber.db` exists yet, NBER-CLI uses that legacy file in place. Schema is automatically upgraded from version 1 to version 2 on first use.
+
+### db migrate
+
+Move the database to a new path and update the user config:
+
+```bash
+nber-cli db migrate ~/data/nber.db
+```
+
+Migration moves the SQLite database file and any SQLite sidecar files such as `-wal`, `-shm`, and `-journal`. The target path must not already exist.
+
+### db Options
+
+| Subcommand | Option | Description |
+| --- | --- | --- |
+| `init` | `--db-path` | SQLite database path. Defaults to `~/.nber-cli/nber.db`. |
+| `migrate` | `new_db_path` | New SQLite database path. |
+
 ## mcp-server
 
 Start the default stdio MCP server:

nber_cli-0.4.0/docs/en/configuration.md

@@ -0,0 +1,139 @@
+# Configuration
+
+Most NBER-CLI runtime behavior uses built-in defaults. The local database also uses a small user config file to remember the SQLite database path selected by `nber-cli db init` or `nber-cli db migrate`.
+
+## Runtime Defaults
+
+| Setting | Default | Description |
+| --- | --- | --- |
+| Request timeout | `60` seconds | Total timeout for network requests. |
+| Retry count | `3` | Failed eligible requests are retried before surfacing the error. |
+| Request attempts | `4` | Derived from retry count plus the first attempt. |
+| Download connection limit | `100` | Maximum concurrent download connections. |
+| Per-host connection limit | `10` | Maximum concurrent connections to one host. |
+| Search page sizes | `20`, `50`, `100` | Accepted values for `--per-page`. |
+
+These values live in `NBERCLIConfig` and `NBER_CLI_CONFIG`.
+
+## User Config File
+
+The user config file is:
+
+```text
+~/.nber-cli/config.json
+```
+
+Current schema:
+
+```json
+{
+  "schema_version": 2,
+  "feed": {
+    "db-path": "/Users/name/.nber-cli/nber.db"
+  },
+  "info": {
+    "cache_enabled": true,
+    "cache_ttl_days": 30
+  }
+}
+```
+
+`feed.db-path` points to the SQLite database used by `info`, `search`, `download`, and `feed`. The historical `feed` key name is preserved for backward compatibility; the database itself is general-purpose.
+
+`schema_version` records the current database schema version. NBER-CLI updates it after `db init` or schema upgrades.
+
+`info.cache_enabled` controls the `info_cache` lookup globally. Set to `false` to force every `info` call (and the MCP `get_paper_info` tool) to go straight to NBER. Defaults to `true`.
+
+`info.cache_ttl_days` sets the refresh interval in days. Cached entries older than this threshold are treated as cache misses and re-fetched on the next `info` call. Must be a positive integer. Defaults to `30`.
+
+Both `info` keys are managed by `nber-cli info cache --turn-on/--off/--set-refresh <N>`. Missing or malformed fields fall back to defaults and never cause NBER-CLI to fail.
+
+## Local Database
+
+Default database path:
+
+```text
+~/.nber-cli/nber.db
+```
+
+Initialize the default database:
+
+```bash
+nber-cli db init
+```
+
+Initialize at a custom path:
+
+```bash
+nber-cli db init --db-path ~/data/nber.db
+```
+
+Move an existing database and update the config:
+
+```bash
+nber-cli db migrate ~/data/nber.db
+```
+
+If you upgraded from 0.3.0 and still have `~/.nber-cli/feed.db`, NBER-CLI will keep using that legacy file when no `nber.db` is present. The schema is upgraded automatically on first invocation.
+
+The database holds:
+
+- `feed_items` and `feed_fetches`: RSS cache used by `feed fetch` and `feed clean`.
+- `info_cache`: paper metadata cache used by `info` and the MCP `get_paper_info` tool. Cache reads are gated by `info.cache_enabled` and respect the `info.cache_ttl_days` TTL.
+- `query_log`, `download_log`, `info_log`: behavior logs for search keywords, download outcomes, and info lookups.
+
+## Output Paths
+
+Single download default:
+
+```bash
+nber-cli download w34567
+```
+
+Creates:
+
+```text
+./w34567.pdf
+```
+
+Directory-based download:
+
+```bash
+nber-cli download w34567 --save-base ~/papers/nber
+```
+
+Creates:
+
+```text
+~/papers/nber/w34567.pdf
+```
+
+Explicit file download:
+
+```bash
+nber-cli download w34567 --file ~/papers/custom-name.pdf
+```
+
+Creates exactly the requested path, including parent directories when possible.
+
+## Date Filtering
+
+Search dates use `YYYY-MM-DD`.
+
+```bash
+nber-cli search "trade" --start-date 2024-01-01 --end-date 2024-12-31
+```
+
+If `--start-date` is provided without `--end-date`, NBER-CLI uses the current date as the end date.
+
+## Network Behavior
+
+NBER-CLI sends a browser-like user agent, uses retries for transient failures, and raises readable errors for common download failures:
+
+- HTTP 403 can mean a newly released paper is still under NBER's first-week access restriction.
+- HTTP 404 means the paper PDF was not found.
+- Timeout and connection failures are reported as network errors.
+
+## No Credentials Required
+
+NBER-CLI does not require an API key. It works against public NBER web pages and NBER's public working paper search endpoint.

{nber_cli-0.3.0 → nber_cli-0.4.0}/docs/en/getting-started.md

@@ -75,10 +75,10 @@ nber-cli info w25000 --all
 
 ## Follow New Papers with the Feed Cache
 
-Initialize the local RSS feed cache:
+Initialize the local database:
 
 ```bash
-nber-cli feed init
+nber-cli db init
 ```
 
 Fetch the NBER new working papers RSS feed:

{nber_cli-0.3.0 → nber_cli-0.4.0}/docs/en/python-api.md

@@ -92,14 +92,14 @@ async def main() -> None:
 asyncio.run(main())
 ```
 
-## Work with the Feed Cache
+## Work with the Local Database
 
-Initialize the default feed cache:
+Initialize the default database:
 
 ```python
-from nber_cli import init_feed_database
+from nber_cli import init_database
 
-db_path = init_feed_database()
+db_path = init_database()
 print(db_path)
 ```
 
@@ -123,14 +123,14 @@ from nber_cli import fetch_feed
 result = fetch_feed(display_all=True, max_items=5)
 ```
 
-Move the feed cache database:
+Move the database:
 
 ```python
 from pathlib import Path
 
-from nber_cli import migrate_feed_database
+from nber_cli import migrate_database
 
-old_path, new_path = migrate_feed_database(Path("~/data/nber-feed.db"))
+old_path, new_path = migrate_database(Path("~/data/nber.db"))
 ```
 
 Clean cached feed database records:
@@ -147,6 +147,84 @@ print(result.deleted_count)
 
 `clean_feed_cache` deletes local cache records only. If deleted records still appear in the RSS feed, a later `fetch_feed` call may return them as new items again.
 
+Read or write the paper metadata cache directly:
+
+```python
+from nber_cli import read_info_cache, write_info_cache
+from nber_cli import get_nber
+import asyncio
+
+paper = read_info_cache(None, "w25000")
+if paper is None:
+    paper = asyncio.run(get_nber(25000))
+    write_info_cache(None, paper)
+print(paper.title)
+```
+
+Read the paper metadata cache through the high-level helper, which respects the user-config TTL and the global cache toggle:
+
+```python
+import asyncio
+
+from nber_cli import get_paper_with_info_cache_result
+
+
+async def main() -> None:
+    result = await get_paper_with_info_cache_result(25000)
+    if result.from_cache:
+        print("Served from local info cache")
+    print(result.paper.title)
+
+
+asyncio.run(main())
+```
+
+`refresh=True` skips the cache lookup and re-fetches from NBER before optionally writing back:
+
+```python
+import asyncio
+
+from nber_cli import get_paper_with_info_cache_result
+
+
+async def main() -> None:
+    result = await get_paper_with_info_cache_result(25000, refresh=True)
+    print(result.paper.title)
+
+
+asyncio.run(main())
+```
+
+Manage the user config (`~/.nber-cli/config.json`):
+
+```python
+from nber_cli import (
+    get_info_cache_settings,
+    set_info_cache_enabled,
+    set_info_cache_ttl_days,
+)
+
+print(get_info_cache_settings())
+set_info_cache_enabled(False)
+set_info_cache_ttl_days(7)
+```
+
+Clean cached paper metadata:
+
+```python
+from nber_cli import clear_info_cache, count_info_cache
+
+print(f"Cached rows: {count_info_cache()}")
+
+preview = clear_info_cache(days=30, dry_run=True)
+print(f"Matched: {preview.matched_count}")
+
+result = clear_info_cache(days=30)
+print(f"Deleted: {result.deleted_count}")
+```
+
+The same `clear_info_cache` function also supports `delete_all=True` and `start_date` / `end_date` filters that mirror `clean_feed_cache`.
+
 ## Data Models
 
 ### NBER
@@ -212,6 +290,33 @@ print(result.deleted_count)
 | `end_date` | `str` or `None` | Inclusive end date for `date-range` mode. |
 | `dry_run` | `bool` | Whether the operation only counted matching records. |
 
+### NBERInfoCacheClearResult
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `database_path` | `Path` | SQLite cache database path. |
+| `matched_count` | `int` | Number of cache records matching the clean criteria. |
+| `deleted_count` | `int` | Number of cache records deleted. |
+| `mode` | `str` | Clean mode: `days`, `all`, or `date-range`. |
+| `days` | `int` or `None` | Day threshold for `days` mode. |
+| `start_date` | `str` or `None` | Inclusive start date for `date-range` mode. |
+| `end_date` | `str` or `None` | Inclusive end date for `date-range` mode. |
+| `dry_run` | `bool` | Whether the operation only counted matching records. |
+
+### InfoCacheSettings
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `cache_enabled` | `bool` | Global toggle for the `info_cache` lookup. |
+| `cache_ttl_days` | `int` | Cache refresh interval in days. |
+
+### InfoCacheLookupResult
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `paper` | `NBER` | The paper returned by the lookup. |
+| `from_cache` | `bool` | `True` when the paper was served from the local `info_cache`. |
+
 ### DownloadFailure
 
 | Field | Type | Description |