Metadata-Version: 2.4
Name: honest-scholar
Version: 0.1.0
Summary: honest-scholar — a CLI for honest, defensible AI-assisted research (tooling for the honest-scholar plugin)
Project-URL: Homepage, https://honest-scholar.science/
Project-URL: Documentation, https://honest-scholar.science/
Project-URL: Repository, https://github.com/davorrunje/honest-scholar
Project-URL: Issues, https://github.com/davorrunje/honest-scholar/issues
Project-URL: Changelog, https://github.com/davorrunje/honest-scholar/blob/main/CHANGELOG.md
Author-email: Davor Runje <davor@synthpop.ai>
Maintainer-email: Davor Runje <davor@synthpop.ai>
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: claude-code,cli,dataset,literature,research,science
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Typing :: Typed
Requires-Python: <3.15,>=3.11
Requires-Dist: pooch>=1.8
Requires-Dist: pyyaml>=6.0
Requires-Dist: requests>=2.31
Requires-Dist: typer>=0.12
Provides-Extra: mcp
Description-Content-Type: text/markdown

# Honest Scholar

*Research you can defend.*

**Honest Scholar** helps you keep research honest — especially now that AI is in
the loop. You (not the AI) make and sign off every material decision, and you must
be able to explain and defend the work; the tool keeps the accounts, advises, and
probes. It **supports** honest, disclosable AI-assisted research — it does **not**
certify that any work is honest.

This package is the **CLI / tooling** behind the
[`honest-scholar` Claude Code plugin](https://github.com/davorrunje/honest-scholar).
The plugin (skills + methodology) stays pure-markdown; this package provides the
`honest-scholar` command it calls — `literature`, `dataset`, `defend`, `backlog`,
and `doctor` — installed **isolated**, so it never touches your project's ML
environment.

## Install

```bash
uv tool install honest-scholar     # recommended (isolated tool env)
# or: pipx install honest-scholar
# or: pip install honest-scholar

honest-scholar --version
honest-scholar doctor              # reports python / uv / rclone
```

**Documentation:** <https://honest-scholar.science/>

## CLI

```
honest-scholar --version
honest-scholar doctor                                           # environment report
honest-scholar literature resolve|cites|refs|enrich|neighbors   # citation graph (OpenAlex + S2)
honest-scholar dataset    validate|ingest|emit                  # manifest + Croissant
honest-scholar dataset    fetch|verify|mirror|audit             # SHA-256 retrieval + rclone mirror
honest-scholar defend     record                                # understanding-status record
honest-scholar backlog    park|add|list|rank|promote|drop       # exploration backlog
honest-scholar keys       set|list|check|unset|path             # API-key & credential store
```

Every command is implemented and emits JSON (the skills parse it). Network- and
`rclone`-backed commands degrade gracefully when a key or the binary is absent.

## API keys & credentials

Some services throttle hard without a key. Providing one is optional (the tooling
degrades gracefully) but lifts the ceiling:

| Key | Service | What it buys | How to obtain |
|---|---|---|---|
| `S2_API_KEY` | Semantic Scholar | Rate limit well above the shared keyless pool. | <https://www.semanticscholar.org/product/api#api-key> |
| `OPENALEX_MAILTO` | OpenAlex | The "polite pool" (a contact email) — faster, more reliable. | <https://docs.openalex.org/how-to-use-the-api/rate-limits-and-authentication> |
| `RCLONE_CONFIG_<REMOTE>_*` | Private dataset mirror | rclone remote credentials passed as scoped env vars (no config file). | Per your rclone remote. |

Keys live in a **CLI-managed JSON store** at `.honest-scholar/keys.json`
(gitignored, created `0600`), read with **`os.environ` > store > unset**
precedence, so an environment variable always wins. Manage it with `keys`:

```bash
honest-scholar keys set S2_API_KEY        # hidden prompt, or reads piped stdin
echo "$MY_KEY" | honest-scholar keys set S2_API_KEY
honest-scholar keys set < keys.json       # a JSON object sets many at once
honest-scholar keys list                  # presence + source (never the value)
honest-scholar keys check | unset | path
```

The value is read only from stdin or a hidden prompt — never `argv` — so it never
hits your shell history or the process list, and `list`/`check`/`doctor` report
presence only.

> **Plaintext at rest.** The store is **not encrypted**; gitignore + `0600` limit
> exposure but are not a vault. OS-keychain backing is a planned follow-up (#49).

## Learn more

- **Documentation:** <https://honest-scholar.science/>
- **User guide:** <https://honest-scholar.science/get-started/user-guide>
- **Plugin, source & full design record:** <https://github.com/davorrunje/honest-scholar>
- **Disclose your AI use & cite Honest Scholar:** <https://github.com/davorrunje/honest-scholar/blob/main/DISCLOSURE.md>

## Changelog

<https://github.com/davorrunje/honest-scholar/blob/main/CHANGELOG.md>

## License

[Apache-2.0](https://github.com/davorrunje/honest-scholar/blob/main/LICENSE).
