Metadata-Version: 2.4
Name: frontier-scholar
Version: 0.1.0
Summary: FrontierScholar (知沿学术): a research-frontier wiki of the scientific literature for agents - Python client and CLI
Author: FrontierScholar
License-Expression: Apache-2.0
Project-URL: Homepage, https://frontier-scholar.com
Project-URL: Documentation, https://frontier-scholar.com/docs/
Project-URL: Repository, https://github.com/FrontierScholar/FrontierScholar
Project-URL: Issues, https://github.com/FrontierScholar/FrontierScholar/issues
Keywords: research,literature,arxiv,agents,wiki,survey,llm
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

<p align="center">
  <img src="https://raw.githubusercontent.com/FrontierScholar/FrontierScholar/main/assets/logo.png" width="148" alt="FrontierScholar logo">
</p>

<h1 align="center">FrontierScholar 知沿学术</h1>
<p align="center"><em>The scientific literature, organised into a wiki agents can walk - down to the research frontier of every subtopic.</em></p>

<p align="center">
  <a href="https://frontier-scholar.com">Website</a> ·
  <a href="https://frontier-scholar.com/docs/">API documentation</a> ·
  <a href="https://github.com/FrontierScholar/FrontierScholar/blob/main/skills/frontier-scholar/SKILL.md">Agent skill</a> ·
  <a href="https://github.com/FrontierScholar/FrontierScholar/blob/main/README.zh.md">中文</a>
</p>

---

## What it is

A read-only JSON API over a wiki of the scientific literature, with a Python SDK and CLI (`pip install frontier-scholar`) and skills for coding agents. The goal is every field of science; the first release covers about **870k arXiv computer-science papers**, organised into 20 domains, 1,593 topics and 19,304 subtopics. Every subtopic has pages on its research problems, method families, datasets and benchmarks, plus a frontier page - and every claim on those pages cites the papers it comes from.

| | Command | |
|---|---|---|
| **Walk the field** | `nav` / `locate` | Domain → topic → subtopic, or let the service's model find the page for a request |
| **Read in layers** | `read` / `read-id` | A subtopic's index first, then only the pages you pick, within a token budget |
| **See the frontier** | `frontier` | Current approaches with their trend, open gaps with when they were first raised |
| **Compare results** | `bench` | One benchmark's result tables from every subtopic that reports it |
| **Check at the source** | `paper` / `dates` | A paper's problem, method, evaluation and mechanism; first-version arXiv dates |
| **Search** | `grep` / `search` | Literal and ranked keyword search inside a topic or subtopic |

## What problem it solves

Ask an agent "what is the state of the art in adaptive retrieval, and what is still open?" and it has two bad options. It can search and read abstracts, which name papers but never compare them. Or it can read dozens of full papers, which costs hundreds of thousands of tokens before any synthesis starts.

FrontierScholar does the reading ahead of time. Each subtopic's papers have already been read, compared and written up as problem, method and resource pages, so an agent can spend a few thousand tokens on the synthesis and then open only the papers it needs to verify. Every subtopic also has a frontier page: which approaches are rising, which gaps are open, and which paper first raised each one.

## Install

```bash
pip install frontier-scholar                      # the `frontier-scholar` CLI and the Python SDK (Python 3.8+, no dependencies)
npx skills add FrontierScholar/FrontierScholar    # the agent skills
```

The skills can also come from the [GitHub CLI](https://cli.github.com/) v2.90.0 or later:

```bash
gh skill install FrontierScholar/FrontierScholar                         # choose interactively
gh skill install FrontierScholar/FrontierScholar frontier-scholar        # one skill
gh skill install FrontierScholar/FrontierScholar --agent claude-code     # or codex, cursor, gemini
```

The API needs a key, issued by the FrontierScholar team. Keep it in an environment variable, never in a command line or a repository:

```bash
export FRONTIER_SCHOLAR_API_KEY="wiki_…"
frontier-scholar nav                              # lists the domains when the key works
```

The CLI and the SDK talk to `https://frontier-scholar.com`; set `FRONTIER_SCHOLAR_BASE` if you were given another address.

## Usage

One investigation, start to finish: what is the frontier of adaptive retrieval - deciding when a RAG system should retrieve at all?

**1. Find the subtopic.** Walk down from a domain:

```bash
frontier-scholar nav information-retrieval
frontier-scholar nav information-retrieval/agentic-search
```

**2. Read its frontier.** One call returns the current approaches and the open gaps, each tied to papers and dated (output trimmed):

```bash
frontier-scholar frontier information-retrieval/agentic-search/adaptive-retrieval
```

```
== Adaptive Retrieval — Research Frontier | as of 2025-12-22 | 75 papers of 90 assigned
Approaches:
  - Training-free prefix-logit and margin gating [rising] papers: 2509.06472 2511.09803
  - Learned evidence-sufficiency and stopping control [rising] papers: 2505.02811 2508.17862 …
  - Cost-aware RL search agents with adaptive depth [rising] papers: 2505.17281 2510.00568 …
Gaps:
  - No universal threshold or calibration rule across models, datasets, and corpora
    [method, open, 6 papers; first 2024-02-26 2402.16457, latest 2025-12-18 2512.16883]
  - Cost and latency accounting is inconsistent and rarely end-to-end
    [efficiency, open, 6 papers; first 2024-10-22 2410.18141, latest 2025-10-17 2510.15719]
```

Give a topic or domain instead to survey every subtopic below it, and filter: `frontier-scholar frontier information-retrieval --trend rising --status open --query retrieval`. `--page` prints the full page, with its timeline and evidence.

**3. Read the pages behind it.** A folder's index lists every page with its size, so you choose what to spend tokens on:

```bash
frontier-scholar read information-retrieval/agentic-search/adaptive-retrieval/Methods
frontier-scholar read information-retrieval/agentic-search/adaptive-retrieval/Methods/confidence-gated-retrieval.md
```

**4. Verify at the source, and respect a cut-off.** Read only the facet you need, and check publication dates:

```bash
frontier-scholar paper 2511.09803 --facet evaluation
frontier-scholar dates 1706.03762 2511.09803 --before 2025-01-01
```

```
1706.03762	2017-06-12	before 2025-01-01: True
2511.09803	2025-11-12	before 2025-01-01: False
```

**5. Compare results on a benchmark.** The same benchmark has a Resources page in every subtopic that uses it; `bench` collects them:

```bash
frontier-scholar bench MIRACL --location information-retrieval
```

Scores from different splits or settings are not comparable, so each table keeps its protocol and the paper behind every number.

**In Python**, the same steps are methods of `Client`:

```python
from frontier_scholar import Client

client = Client()                                  # reads FRONTIER_SCHOLAR_API_KEY
frontier = client.frontier("information-retrieval/agentic-search/adaptive-retrieval")
for gap in frontier["subtopics"][0]["gaps"]:
    print(gap["name"], gap["status"], gap["first_raised"])

page = client.read_page("information-retrieval/agentic-search/adaptive-retrieval/Methods/confidence-gated-retrieval.md")
evaluation = client.paper("2511.09803", facets=["evaluation"])
dates = client.paper_dates(["1706.03762", "2511.09803"], before="2025-01-01")
miracl = client.benchmark_results("MIRACL", location="information-retrieval")
```

Every method returns the tool's `data`; errors raise `FrontierScholarError` with the API's `code`, `details` and `request_id`. `client.call(tool, arguments)` reaches any tool by name.

**Over HTTP**, every tool is the same call:

```bash
curl -sS https://frontier-scholar.com/api/v1/api/invoke \
  -H "X-API-Key: $FRONTIER_SCHOLAR_API_KEY" -H "Content-Type: application/json" \
  -d '{"tool": "retrieval.frontier", "arguments": {"location": "information-retrieval/agentic-search/adaptive-retrieval"}}'
```

## Agent skills

| Skill | |
|---|---|
| [`frontier-scholar`](https://github.com/FrontierScholar/FrontierScholar/blob/main/skills/frontier-scholar/SKILL.md) | The `frontier-scholar` commands and how to work with the wiki. Load this one first. |
| [`frontier-scholar-benchmark-sota`](https://github.com/FrontierScholar/FrontierScholar/blob/main/skills/frontier-scholar-benchmark-sota/SKILL.md) | A ranked, verified results table for one benchmark, with a date cut-off. |
| [`frontier-scholar-frontier-report`](https://github.com/FrontierScholar/FrontierScholar/blob/main/skills/frontier-scholar-frontier-report/SKILL.md) | A research-frontier report: approaches and trends, open gaps and since when, stated coverage. |

## Documentation

- **[frontier-scholar.com/docs](https://frontier-scholar.com/docs/)**: every tool with its parameters, a real response, and request examples in curl, Python and the CLI; errors and limits. In English and Chinese.
- **[skills/frontier-scholar/SKILL.md](https://github.com/FrontierScholar/FrontierScholar/blob/main/skills/frontier-scholar/SKILL.md)**: the operating instructions agents load.
- **`frontier-scholar -h`** and **`help(frontier_scholar.Client)`**: the CLI and SDK reference.

## License

Apache 2.0 - see [LICENSE](https://github.com/FrontierScholar/FrontierScholar/blob/main/LICENSE). Issues and questions: [github.com/FrontierScholar/FrontierScholar/issues](https://github.com/FrontierScholar/FrontierScholar/issues).
