Build Structured Paper Filters with Sciverse

Use meta-catalog to discover fields and meta-search to filter papers precisely

View on GitHub

Scenario

Users need advanced search over papers by year, venue, author, subject, citation count, or other metadata fields.

Estimated calls

~2-5 API calls

Tools

meta-catalogmeta-search

Pipeline

meta-catalog→ 可用字段 + 算子→ meta-search(filters, sort)→ 结构化结果

Input example

Search target:
- topic: graph neural networks for materials discovery
- year >= 2020
- venue in Nature / Science / Cell
- sort by citation_count desc

Output example

Filtered results:
1. title=..., year=2023, venue=Nature, citation_count=...
2. title=..., year=2022, venue=Science, citation_count=...

Agent Prompt example

You are a structured literature search assistant. First call meta-catalog to discover fields and supported operators. Then construct a meta-search request from the user constraints.

Implementation steps

Step 1: Set up the environment

Configure API token and HTTP client

!pip install httpx
import os
os.environ["SCIVERSE_API_TOKEN"] = "sv-your-token-here"  # 替换为你的真实值

Step 2: Query available fields

Call meta-catalog to inspect filterable and sortable fields

import os
import asyncio
import httpx

BASE = "https://api.sciverse.space"
TOKEN = os.environ["SCIVERSE_API_TOKEN"]
HEADERS = {"Authorization": f"Bearer {TOKEN}"}

async def get_catalog():
    async with httpx.AsyncClient(timeout=30) as client:
        resp = await client.get(f"{BASE}/meta-catalog", headers=HEADERS)
        resp.raise_for_status()
        return resp.json()

async def main():
    catalog = await get_catalog()
    print("Available fields:")
    for field in catalog["fields"]:
        print(f"  {field['name']} ({field.get('type','')}) - operators: {field.get('operators', [])}")
    return catalog

catalog = await main()

Step 3: Build filters and search

Construct filters, sort options, and pagination for meta-search

async def search_papers(filters: list, query: str = None, sort: list = None, page_size: int = 20):
    """调用 meta-search 进行结构化检索
    
    提示: query 与 sort 可共用（传 sort 按字段硬排）。常见用法：
    - 要相关性排序：传 query，不传 sort
    - 要字段排序（如引用数）：传 sort，不传 query
    
    filters 格式: [{field, operator, value}]
    operator 枚举: FILTER_OP_EQ / FILTER_OP_IN / FILTER_OP_GTE / FILTER_OP_LTE
    sort 格式: [{field, order}]
    order 枚举: SORT_ORDER_ASC / SORT_ORDER_DESC
    """
    async with httpx.AsyncClient(timeout=30) as client:
        body = {"filters": filters, "page_size": page_size}
        if query:
            body["query"] = query
        if sort:
            body["sort"] = sort
        resp = await client.post(
            f"{BASE}/meta-search", headers=HEADERS, json=body
        )
        resp.raise_for_status()
        return resp.json()

async def main():
    # 示例 1: 按引用数排序（不传 query）
    results = await search_papers(
        filters=[
            {"field": "publication_published_year", "operator": "FILTER_OP_GTE", "value": 2022},
            {"field": "publication_published_year", "operator": "FILTER_OP_LTE", "value": 2024},
            {"field": "publication_venue_name_unified", "operator": "FILTER_OP_IN", "value": ["Nature", "Science"]}
        ],
        sort=[{"field": "citation_count", "order": "SORT_ORDER_DESC"}]
    )
    print(f"Found {results.get('total_count', 0)} papers")
    for h in (results.get("results") or [])[:5]:
        print(f"  {h['title']} ({h.get('publication_published_year','')}, "
              f"{h.get('publication_venue_name_unified','')}, "
              f"citations: {h.get('citation_count', 'N/A')})")

    # 示例 2: 按相关性排序（传 query，不传 sort）
    results2 = await search_papers(
        query="CRISPR gene editing delivery",
        filters=[
            {"field": "publication_published_year", "operator": "FILTER_OP_GTE", "value": 2023}
        ]
    )
    print(f"\
Relevance search: {results2.get('total_count', 0)} papers")

await main()

Notes

Read meta-catalog at runtime instead of hard-coding fields.
Use only operators supported by each field.
Validate user constraints before sending the request.
Keep pagination explicit for reproducible result sets.
Sort by citation_count or date only when the field is available.
For semantic relevance, combine structured filtering with agentic-search.
Use conservative defaults when a field is missing.

FAQ

什么时候用 meta-search?

当需要按 DOI、年份、期刊、引用数等结构化字段检索时使用。

为什么先调用 meta-catalog?

meta-catalog 可以确认哪些字段和操作符可用，避免 Agent 生成非法查询。

和 agentic-search 有什么区别?

meta-search 偏结构化筛选，agentic-search 偏自然语言语义证据召回。

适合批量任务吗?

适合构建候选论文池、排序列表和后续语义筛选输入。

Next steps

Need an API key?

Create one in Console > Tokens.The same API key works for enabled Sciverse, DianShi, and Skills capabilities, with starter quota available according to account permissions.

Open console