agentic-search v1.1.8A

Immutable. This exact content never changes and is served at /api/v1/blob/beee7bb4149eb4c4.

---
name: agentic-search
description: Tiered academic paper discovery for quick search-bar lookup, balanced interactive research, or maximum-quality multi-round retrieval. Infer hidden entities, search PaperHub with keyword/title/citation paths, optionally use public web evidence, and return a precision-first tiered metadata set. Use for natural-language research needs that ask to find relevant papers, including requests with a time budget or speed/quality preference.
description_zh: "分档发现学术论文：支持搜索框快速查找、均衡的交互式研究，以及质量优先的多轮检索。推断查询中的隐含实体，通过 PaperHub 的关键词、标题和引用路径检索，按需补充公网证据，并返回以精准度优先、按档位组织的论文元数据。适用于用自然语言查找相关论文的需求，包括指定时间预算或速度与质量偏好的请求。"
version: "1.1.8"
---

# Agentic Literature Search

Return relevant papers in `metadata.json`. Do not generate a narrative report
unless the user explicitly asks for one.

For a standalone conversation search, after producing real non-empty `metadata.json`, publish the result with
`scholarseed-bridge literature result --json '{"run":"RESULT_DIR","checkpoint":"metadata","skill":"agentic-search"}'`,
replacing RESULT_DIR with the session-relative result directory. This displays the host's
conversation component and the host's full-result actions; it does not authorize full-text access.
The dedicated search-bar invocation owns its result tab and does not need this conversation call.
When invoked by another research Skill, leave publication to that parent's checkpoint
(for example research-idea-partner's candidates or literature-review's retrieval); do not publish twice.
Never invent papers to obtain a card; report an empty or blocked search as such.

## Select one mode

An explicit user mode wins. Otherwise infer from `time_budget_minutes`; with
neither, use Quality.

| Mode | Product target | Time target | Papers | Execution graph |
|---|---|---:|---:|---|
| Quick | search bar | <1 minute | up to 20 | at most one web batch + one runner call + deterministic ranking |
| Balanced | interactive research | 5–6 minutes | 38–40 | compact entity resolution + one logical round |
| Quality | maximum quality | unbounded | 38–40 | C1 provenance-recovery multi-round search |

Continuous budgets map as follows: `B <= 2` → Quick, `2 < B <= 6` → Balanced,
and `B > 6` → deadline-bounded Quality. Named Quick and Balanced default to one
and six minutes. State and search tools enforce the selected policy.

Quick uses a deliberately different execution graph: truncating the Quality
graph at 60 seconds does not leave enough time to select results. When Quick is
selected, follow only the Quick workflow below and stop. When Balanced is
selected, read [references/balanced-quality-workflow.md](references/balanced-quality-workflow.md)
completely. When Quality is selected, read
[references/c1-quality-workflow.md](references/c1-quality-workflow.md)
completely and follow its C1 coverage and stopping rules instead of the
Balanced graph.

## Paths and connectivity

1. `SKILL_DIR` is the absolute directory containing this file. Use absolute
   paths for bundled tools.
2. `WORK_DIR` is the user's current working directory. Write only under
   `WORK_DIR/agentic-search-results/<short-topic>/`; append a timestamp rather
   than overwrite existing results.
3. Treat PaperHub as an optional enhanced source. Authentication comes only
   from `SCHOLARSEED_API_KEY`; configuration is loaded by `tools/localconf.py`.
4. Read `SETUP.md` only when non-authentication configuration is invalid or a
   permitted network request fails. Never ask the user to provide a PaperHub or
   platform token when the credential is absent or rejected.
5. Route every public-web lookup through the separately installed `$web-search`
   skill; never call the runtime Web Search tool directly from this skill. The
   host owns the provider route required by that skill: the `official` profile
   (`provider: official-api`) first, then the `native` profile (`provider:
   codex-native`) only after a structured unavailable/failed result or artifact
   publication failure. Never use the `automatic` or `browser` profile. For
   official, require a delivered `web-search-result.json` artifact, gate on
   `schema: scholarseed.web_search.v1`, and decide the search outcome from its
   `status`, not the provider process exit code. `completed` and `empty` are
   terminal successes; `unavailable`, `failed`, and `action_required` are not
   successful candidate sets. Treat a nonzero publication command, missing or
   unreadable artifact, schema/query/provider mismatch, or malformed envelope
   as a failed leg. Never infer entities from status logs.
   Use PaperHub plus `$web-search` when
   PaperHub is available; otherwise use the Web-only fallback below. Do not call Brave merely
   because `BRAVE_API_KEY` exists. Use Brave only when the user explicitly opts
   in, or when both primary paths are unavailable and the user accepts a
   fallback search provider.
6. Run `tools/doctor.py` once only when readiness is genuinely unknown; add
   `--live` only for a needed network check. Trust its booleans and never print
   environment values.

For a `$web-search` native-profile fallback, require exactly one object between
`<scholarseed_web_search_results>` and `</scholarseed_web_search_results>`. Validate the
strict native envelope: `schema` = `scholarseed.web_search.v1`; `status` =
`completed` or `empty`; `provider` = `codex-native`; `query` exactly matches the
requested query; `candidates` contains at most 20 exact
`{title,url,description}` objects; and `error` is null. If native Web Search
cannot return that envelope, stop the public-web leg with a capability error.
Across both providers, consume only the common candidate core and accept
provider extension keys.

## PaperHub-unavailable fallback

Do not add a credential-preflight tool call. Follow the selected mode normally
unless the host explicitly states that PaperHub is unavailable. If
`quick_search.py` or `search_round.py` returns `fallback_required` with
`PAPERHUB_AUTH_MISSING`, `PAPERHUB_HTTP_401`, `PAPERHUB_HTTP_403`, or an
exhausted source-level transport error, switch to public-web retrieval:

1. Do not retry PaperHub, perform PaperHub citation tracking, open setup
   instructions, or ask the user for a token.
2. Reuse any `$web-search` results already obtained. Quick permits its existing
   batch plus one additional batch of at most three queries only when fewer than
   five verifiable papers remain. Balanced permits at most two total web
   batches. Unbudgeted Quality may perform gap-driven web batches until central
   coverage is adequate, two batches add no valuable candidates, or four total
   batches complete. Respect an explicit deadline.
3. Keep only actual papers with a direct paper URL, DOI, or arXiv ID. Never
   convert a project page, repository, blog, or search-results page into a paper.
   Supply `abstract` only when a public result actually exposes it; do not
   relabel a generic search snippet as an abstract.
4. Order credible candidates by relevance and call the deterministic fallback
   finalizer exactly once, using the selected mode. Never write or edit
   `metadata.json` or `fallback_event.json` directly:

```bash
scholarseed-skill-python "SKILL_DIR/tools/web_fallback.py" \
  --query "FULL_USER_QUERY" --mode "quick|balanced|quality" \
  --paperhub-error-code "ERROR_CODE_FROM_RUNNER" \
  --output-dir "RESULT_DIR" <<'JSON'
{"search_queries":["..."],"papers":[{"title":"...","url":"...","year":2024,"doi":"","arxiv_id":"","authors":[],"venue":"","abstract":"","reason":"...","subtopics_covered":[]}]}
JSON
```

The finalizer marks any result below the requested count as
`result_status: partial` and writes a credential-free `fallback_event.json`
with the source error and fallback counts; never pad with noise. If `$web-search` is also
unavailable or yields no verifiable paper, stop with a clear capability error
instead of creating a successful empty artifact. On success, disclose that the
result used public-web fallback and lacks PaperHub metadata and citation
expansion. Do not treat an empty but otherwise successful PaperHub query as a
source outage.

## Quick workflow

The whole Quick path is defined here; do not inspect the output schema, other
references, tool source/help, or configuration before running it.

### 1. Plan once

Infer hidden named methods, datasets, projects, standards, and likely landmark
titles from the full clue bundle. Make one logical `$web-search` batch with
three complementary queries, even when the surface topic is explicit; its
purpose is to resolve concrete paper titles. Run the three explicit skill
invocations concurrently when the host supports it, and follow the skill's
`official-api` → `codex-native` route for each query:

1. the full rare clue bundle plus `paper`;
2. the central comparison/relationship plus `original study paper`;
3. the rarest mechanism, population, dataset, or method clues plus `paper title`.

Do not open result pages or make a second web call. Extract clean scholarly
titles from the batch, then produce 3–6 short English relevance concepts and at
most 12 PaperHub queries:

- 3–4 complementary keyword queries for the central relationship and compared
  method/evidence families;
- 6–8 exact or near-exact title queries for the most likely core entities and
  founding papers;
- prioritize queries that jointly explain multiple rare clues, but retain bare
  canonical-title queries for central entities;
- for “before YEAR” or “before January YEAR”, set `--year-end YEAR-1`.

Do not call the runtime Web Search tool directly, call Brave, open web pages,
use a pool-inspection tool, or run a
model-based selection pass. Do not create a result directory or plan file
yourself.

### 2. Run once

Make exactly one shell call. Repeat `--keyword` and `--title` flags for the
planned queries:

```bash
scholarseed-skill-python "SKILL_DIR/tools/quick_search.py" \
  --query "FULL_USER_QUERY" \
  --concepts "entity,mechanism,method,dataset" \
  --keyword "central relation query" \
  --keyword "comparison family query" \
  --title "Likely Foundational Paper Title" \
  --title "Canonical Method or Dataset" \
  --year-end 2025 \
  --output-dir "RESULT_DIR"
```

Use normal shell argument quoting; never interpolate credentials. The runner
creates the directory and trace plan, initializes Quick state, executes the
single serial PaperHub graph, automatically tracks references from two ranked
anchors, and selects papers using relevance, exact-title match, citation
provenance, and diversity. It writes compact `metadata.json` without abstracts
or a report. Add `--include-abstract` only when the caller explicitly needs
abstracts. On success, return the metadata path and paper count without rereading
the file or running another command.

If the runner returns `fallback_required`, it has not succeeded and has not
written `metadata.json`; execute only the conditional fallback above. This is
the sole exception to the one-shell-call Quick path.

The <1 minute target assumes Codex was started with the
`agentic-search-quick` profile. A skill cannot change an already-running
session's model; a slower or high-reasoning session may exceed the SLO even
though the Quick graph is followed.

## Follow-ups

For follow-up requests, preserve the existing pool and query history. Quick is
a one-shot product response; use Balanced or Quality when the user wants gap
filling or iterative refinement. Never restart a completed search unless the
user requests an independent fresh run.