Search, filter, and format entries from BibTeX or BibLaTeX .bib files for research workflows. Use when a user wants to find papers, search a bibliography, filter a library, or look up references by topic, author, year, venue, DOI, arXiv ID, keywords, annotation, abstract, or entry type. Handles Zotero-exported libraries. Supports compact search expressions such as author:, year-gte, type:, and has:, combined filters, research-oriented output fields, raw BibTeX export, and LaTeX/Typst citation snippet generation.
Use this skill when the user provides a .bib file and wants research-oriented retrieval rather than just a single citation key lookup. This skill is designed for large bibliographies with mixed standard and custom fields, including fields such as shorttitle, annotation, keywords, abstract, and file.
Follow this workflow:
.bib file to use.rtk is available, prefer it for exploratory steps such as locating .bib files and inspecting representative fields.scripts/search_bib.py on the .bib file and keep its JSON output uncompressed.scripts/preview_bib_search.py for a compact human-readable summary.The typical input is:
.bib file provided by the userauthor:cheng year>=2024 has:code type:articlelatex, typst, both, or raw BibTeXIf the user gives a natural-language request only, infer a reasonable search spec and say what assumptions you made. If the user writes a compact filter expression directly, preserve it as closely as possible instead of converting it into vague prose.
Before running the script, map the request into a search spec.
query: free-text topic queryfilters.year_min, filters.year_max, filters.years_in, filters.exclude_yearsfilters.author_contains, filters.author_excludesfilters.type_in, filters.exclude_type_infilters.has, filters.exclude_hasfilters.field_contains, filters.field_excludessort: relevance, year_desc, year_asc, or titlelimit: default 5 unless the user asks for morereturn_fields: fields to expose in the answerinclude_raw_bib: true when the user asks for the original entry or when exact export matterscitation_mode: latex, typst, both, or noneUse these defaults unless the user says otherwise:
sort: relevancelimit: 5key, title, shorttitle, author, year, venue, doi, eprint, keywords, annotation, abstractinclude_raw_bib: truecitation_mode: bothThe script can parse direct query expressions inside --query, and it can also parse them when they appear inside spec.query.
Supported compact operators:
author:chengyear>=2024year:2024 or year:2023,2024type:article,misc-type:mischas:code,doi-has:pdfannotation:CodeAvailablekeywords:mambasort:year_desclimit:10fields:key,title,year,doicite:latex, cite:typst, or cite:bothraw:trueUnstructured tokens that do not match the compact syntax remain part of the topic query.
has valuesThe script supports these useful has values:
doiabstractkeywordsannotationshorttitleeprintpdfcodecode is inferred from fields such as url, abstract, keywords, annotation, note, or howpublished that mention GitHub, GitLab, code, repository, or source.
For more examples, see references/query-syntax.md.
Run the script with a JSON spec, a spec file, or a compact query.
If rtk is available, prefer it only for model-facing exploration:
rtk find . -name "*.bib"rtk read /path/to/library.bib -l aggressive -m 80rtk grep "doi|keywords|annotation|eprint" /path/to/library.bibKeep machine-readable search results on the raw script path:
python scripts/search_bib.py ... whenever another tool or script needs JSONsearch_bib.py output with RTK compressionpython scripts/preview_bib_search.py only after JSON has already been producedpython scripts/search_bib.py \
--bib /path/to/library.bib \
--spec-json '{
"query": "mamba time series forecasting author:Cheng year>=2024 has:code",
"sort": "relevance",
"limit": 5,
"citation_mode": "both",
"include_raw_bib": false
}'
python scripts/search_bib.py \
--bib /path/to/library.bib \
--query 'mamba time series forecasting author:Cheng year>=2024 has:code type:article,misc cite:both limit:5'
python scripts/search_bib.py --bib /path/to/library.bib --spec-file /path/to/spec.json
python scripts/search_bib.py \
--bib /path/to/library.bib \
--query 'mamba time series forecasting author:Cheng year>=2024 has:code type:article,misc cite:both limit:5' \
| python scripts/preview_bib_search.py
If the user uploads a .bib file into the conversation, first make sure you know its local path in the execution environment, then run the script against that file.
When presenting results to the user, prefer this order:
For each selected entry, usually include:
If the user asked for a compact query, it is helpful to echo the interpreted filters briefly, especially when negation or multiple field filters are involved.
When using the preview helper:
search_bib.py as the source of truth for filtering, scoring, sorting, and citationsWhen citation_mode includes latex, expose:
\\cite{key}\\parencite{key}\\textcite{key}These are intended for biblatex workflows. If the user only wants one form, show only that form.
When citation_mode includes typst, expose:
@key when the key is simple enough for shorthand usage#cite(<key>) when shorthand is fine#cite(label("key")) when the key contains characters that make shorthand fragileIf the script reports typst.needs_label = true, prefer the explicit label("...") form instead of shorthand.
Before answering:
If the .bib file contains malformed entries (unbalanced braces, encoding issues, truncated fields), the script skips those entries silently and processes the rest. When a file fails to parse entirely, check the encoding (the script assumes UTF-8) and look for obvious structural corruption such as missing closing braces.
When zero entries match, suggest broadening the search:
has: constraints (e.g. has:code excludes many entries)The script is pure Python with a linear scan and no external dependencies. For typical academic libraries (up to ~10,000 entries) it completes in seconds. For very large files (50,000+ entries), expect proportionally longer runtimes but no functional issues.
scripts/search_bib.py: parses .bib files, applies filters, ranks results, and formats citation snippetsscripts/preview_bib_search.py: renders search_bib.py JSON into a compact human-readable summaryreferences/query-syntax.md: examples for mapping user requests into structured search specs and compact expressions