Note
RefKit is alpha software. Public APIs may change before 1.0.
RefKit turns BibTeX,
BibLaTeX, and
Hayagriva YAML into normalized
bibliography records. It renders citations and bibliographies with
Citation Style Language styles, produces plain
text, HTML, or structured trees, and preserves raw BibTeX for targeted edits.
The polars-refkit package exposes the same parsing, rendering, inspection,
and formatting capabilities as expressions for Polars
eager and lazy queries.
Render a citation
Add refkit to a Python 3.11 through 3.14 environment:
python -m pip install refkit
Parse a bibliography, load the APA style, and render one citation:
import refkit as rk
library = rk.Library.parse_bibtex(
"""
@article{doe2024,
author = {Doe, Jane},
title = {Fast Citations},
journal = {Journal of Citation Tests},
year = {2024}
}
"""
)
document = rk.Document(library, rk.Style.load("apa"), locale="en-US")
rendered = document.render([rk.Citation("intro", "doe2024")])
print(rendered["intro"].text)
print(rendered.bibliography.text)
(Doe, 2024)
Doe, J. (2024). Fast Citations. Journal of Citation Tests.
Library owns normalized entries and parser diagnostics. Document combines
a library, style, and locale for one ordered render call. Each Rendered value
exposes text, HTML, and a structured render tree.
Choose a bibliography model
| Model | Preserves | Use it for |
|---|---|---|
Library | Normalized entries and diagnostics | Lookup, projection, citation rendering, and full bibliographies. |
BibDocument | Source-order blocks, duplicate occurrences, and byte spans | Raw BibTeX inspection, targeted field edits, and source-preserving writes. |
TidyOptions configures canonical BibTeX formatting and duplicate handling
for tidy_bibtex() and BibDocument.tidy().
Work with bibliography data
| Task | Interface | Start here |
|---|---|---|
| Parse, render, inspect, and edit from Python | refkit | Python quickstart |
| Apply bibliography operations to eager or lazy dataframes | polars-refkit and pl.Expr.refkit | Polars guide |
| Run the Python interfaces in a browser-hosted Python runtime | WebAssembly wheels for Pyodide | Pyodide guide |
| Give a code-mode agent a version-matched RefKit workflow | refkit.agent and its packaged Agent Skill | Agent integration |
A plain string passed to a Polars expression names a column. Wrap literal
bibliography source or citation keys with pl.lit(...).
Use with code-mode agents
The refkit wheel contains the Python library, an
Agent Plugin, and a version-matched
Agent Skill. Installing refkit places
the library and agent resources in the same Python environment. A code-mode
agent that can execute Python can inspect the dynamic module documentation:
import refkit.agent as refkit_agent
help(refkit_agent)
For programmatic access, instructions() returns the packaged skill as Markdown
and resources() returns its known files by skill-relative name:
instructions = refkit_agent.instructions()
resources = refkit_agent.resources()
workflow = resources["references/workflows.md"].read_text()
The agent workflow uses the same Library, Document, BibDocument, and tidy
APIs as other Python callers. Any code-mode environment that can execute Python
can use these imports directly. Marimo, for example,
discovers refkit.agent automatically through the capability entry point
installed with the wheel.
Documentation
- Get started reaches a complete render result.
- How RefKit works defines the state owners and transitions.
- Guides cover Python, Polars, raw BibTeX editing, and custom Citation Style Language files.
- Reference records the Python, Polars, Rust, data-shape, tidy, error, and agent contracts.
- Performance publishes reproducible benchmark evidence.
- Troubleshooting maps common failures to recovery steps.
Development
The development documentation covers setup, architecture, testing, documentation delivery, packaging, releases, and benchmarks. Report defects through GitHub Issues.
License
RefKit is licensed under the Apache License 2.0. NOTICE records upstream citation and bibliography components.