refkit 0.0.4rc4__tar.gz → 0.0.5__tar.gz

refkit-0.0.5/.agent-plugin/plugin.json

@@ -0,0 +1,13 @@
+{
+  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
+  "name": "refkit",
+  "description": "Parse, inspect, render, format, and edit bibliography data from Python and Polars.",
+  "license": "Apache-2.0",
+  "author": {
+    "name": "Péter Ferenc Gyarmati",
+    "email": "dev.petergy@gmail.com"
+  },
+  "homepage": "https://peter-gy.github.io/refkit/",
+  "repository": "https://github.com/peter-gy/refkit",
+  "keywords": ["bibliography", "bibtex", "citations", "python", "polars"]
+}

refkit-0.0.5/.agent-plugin/skills/refkit/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: refkit
+description: Use RefKit to parse, inspect, render, format, or safely edit BibTeX, BibLaTeX, and Hayagriva bibliography data from Python or Polars.
+---
+
+# RefKit
+
+RefKit exposes one portable bibliography core through Python objects and Polars expressions. Work through the public package APIs so notebook code, scripts, and applications share the same parsing, rendering, formatting, and error contracts.
+
+## Choose the data model
+
+- Use `refkit.Library` for normalized entries, diagnostics, selection, projection, citation rendering, and bibliography rendering.
+- Use `refkit.BibDocument` for source-order BibTeX blocks, duplicate occurrences, existing-field edits, and preserving writes.
+- Use `polars_refkit` when bibliography source already lives in eager or lazy Polars queries.
+
+Do not flatten these models into one generic dictionary workflow. Their ownership and failure behavior differ.
+
+## Working rules
+
+1. Prefer in-memory APIs inside the active Python process. Use `Library.parse_bibtex`, `Library.parse_yaml`, `BibDocument.parse`, and `tidy_bibtex` when source text is already available.
+2. Use `recovery="report"` when the task should retain recoverable entries. Always inspect and report `library.diagnostics` before consuming those entries. Use `recovery="error"` when malformed input must stop the operation.
+3. Project the fields needed for inspection with `Library.project`. Avoid dumping complete large libraries or render trees into notebook output.
+4. Build one `Document` from a prepared `Library`, `Style`, and locale. Pass the complete ordered citation sequence to one `render` call because order can affect numbering, disambiguation, position-sensitive formatting, and the cited bibliography.
+5. Choose `Rendered.text`, `Rendered.html`, or `Rendered.tree` at the consumer boundary. Treat HTML as rendered output and tree nodes as structured data.
+6. Select duplicate raw entry or field occurrences with `get_all` before editing an existing field. `BibEntry.key` is read-only. Preview `BibDocument.to_bibtex()` before writing a file.
+7. Inspect `TidyResult.warnings` before accepting canonical formatting, key generation, duplicate detection, or merges.
+8. Compare requested citation keys with `Library.keys()` before a batch render. A missing key aborts the complete render call, so return the requested, missing, and available keys and ask the user to resolve the mismatch.
+9. Let RefKit exceptions reach the agent runtime while diagnosing. Catch a specific error only when the workflow has a concrete recovery path.
+
+## Start with a bounded inspection
+
+```python
+import refkit as rk
+
+source = "@article{doe2024, title={Fast Citations}, year={2024}}"
+library = rk.Library.parse_bibtex(source, recovery="report")
+rows = library.project(["key", "entry_type", "title", "date", "doi"])
+diagnostics = list(library.diagnostics)
+```
+
+Return `rows` and `diagnostics` together when report recovery retains partial input.
+
+Read [references/workflows.md](references/workflows.md) for complete normalized, rendering, raw-edit, formatting, and Polars workflows. Read [references/contracts.md](references/contracts.md) when the task depends on lifecycle, duplicate, error, or output-shape details.
+
+The installed documentation map is available at `https://peter-gy.github.io/refkit/llms.txt`.

refkit-0.0.5/.agent-plugin/skills/refkit/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "RefKit"
+  short_description: "Work with bibliography data through RefKit"
+  default_prompt: "Use $refkit to parse, inspect, render, format, or edit bibliography data."

refkit-0.0.5/.agent-plugin/skills/refkit/references/contracts.md

@@ -0,0 +1,61 @@
+# RefKit Contracts
+
+## State owners
+
+| Object | Owns |
+| --- | --- |
+| `Library` | Normalized entries and parser diagnostics. |
+| `BibDocument` | Source-order raw BibTeX, occurrence identity, and preserving writeback. |
+| `Style` | A prepared Citation Style Language style. |
+| `Document` | Prepared library, style, and locale inputs. |
+| One render call | Fresh ordered citation processor state and its cited bibliography. |
+| `Rendered` | Text, HTML, and a structured render tree for one result. |
+
+## Input boundaries
+
+- `Library.read` infers BibTeX, BibLaTeX, or Hayagriva YAML from a filesystem extension.
+- `Library.parse_bibtex` accepts BibTeX or BibLaTeX text.
+- `recovery="error"` raises on malformed input. `recovery="report"` retains recoverable entries and records ignored blocks or duplicate keys in `Library.diagnostics`. Report recovery still raises `RefkitError` when no entry survives.
+- `Library.parse_yaml` accepts Hayagriva bibliography YAML.
+- `BibDocument` accepts raw BibTeX and preserves blocks that normalized parsing does not expose.
+- `tidy_bibtex` accepts raw BibTeX text and rejects the first malformed block with `TidySyntaxError`.
+
+## Projection boundaries
+
+`Library.project` and the Polars `entries` expression accept `key`, `entry_type`, `type`, `title`, `date`, `doi`, and `volume`. `type` is an output-name alias for `entry_type`. The default projection contains `key`, `title`, `doi`, and `volume`.
+
+## Duplicate boundaries
+
+Normalized `Library` keys are unique. Report recovery retains the first recoverable entry for a duplicate key and records a diagnostic.
+
+Raw `BibDocument` entries and fields preserve duplicate occurrences. Direct lookup requires one match. Use `get_all` to select a source-order occurrence before editing.
+
+`BibEntry.key` is read-only. Canonical formatting can generate new keys, but accepting generated keys also requires updating downstream citations that refer to the old keys.
+
+## Render boundaries
+
+A `Cite` identifies one bibliography key with an optional locator and label. A `CitationGroup` combines cite items into one rendered citation. A `Citation` gives the rendered occurrence an ID used to retrieve it from `RenderedDocument`.
+
+Citation order can affect numbering, disambiguation, position-sensitive formatting, subsequent-name rules, and the cited bibliography. Separate render calls have independent processor state.
+
+A missing reference aborts the complete render call with `MissingReferenceError`. When citation keys come from user or external input, compare them with `Library.keys()` before rendering and ask the user to resolve missing keys.
+
+## Error boundaries
+
+| Error | Use |
+| --- | --- |
+| `RefkitError` | Filesystem, parser, raw ambiguity, and renderer failures. |
+| `MissingReferenceError` | A render request names a key absent from the `Library`. |
+| `TidyError` | Key generation or another formatting operation fails. |
+| `TidySyntaxError` | Raw BibTeX contains a malformed block. Inspect its line, column, byte, character, and message fields. |
+| `TypeError`, `ValueError`, `KeyError` | Python shape, option, label, lookup, and identifier failures. |
+
+## Output discipline for code-mode agents
+
+- Show a bounded projection before printing complete source.
+- Prefer `Rendered.text` for inspection and `Rendered.html` for an HTML consumer.
+- Traverse `Rendered.tree` when structured formatting or link metadata is required.
+- Report diagnostics and tidy warnings beside the affected input.
+- When report recovery retains partial input, return projected entries and diagnostics together.
+- When citation keys are missing, return the requested, missing, and available keys before asking the user to resolve the mismatch.
+- Preview preserving writes and generated keys before committing filesystem changes.

refkit-0.0.5/.agent-plugin/skills/refkit/references/workflows.md

@@ -0,0 +1,112 @@
+# RefKit Workflows
+
+## Parse and inspect normalized data
+
+```python
+import refkit as rk
+
+source = """
+@article{doe2024,
+  author = {Doe, Jane},
+  title = {Fast Citations},
+  year = {2024}
+}
+"""
+
+library = rk.Library.parse_bibtex(source, recovery="report")
+rows = library.project(["key", "entry_type", "title", "date", "doi"])
+diagnostics = list(library.diagnostics)
+```
+
+`Library` preserves normalized entry order. Recovery diagnostics describe repairs applied before typed entries were accepted.
+
+## Render an ordered citation document
+
+```python
+document = rk.Document(library, rk.Style.load("apa"), locale="en-US")
+rendered = document.render(
+    [
+        rk.Citation(id="introduction", citation="doe2024"),
+        rk.Citation(
+            id="detail",
+            citation=rk.CitationGroup([rk.Cite("doe2024", locator="12", label="page")]),
+        ),
+    ]
+)
+
+citation_text = rendered["detail"].text
+bibliography_html = rendered.bibliography.html
+```
+
+Each `render` call creates fresh citation processor state. Keep related citations in one ordered call.
+
+## Edit raw BibTeX while preserving surrounding source
+
+```python
+duplicate_source = """% Keep this comment.
+@article{doe2024, TITLE={First title}, year={2024}}
+@article{doe2024, tItLe={Second title}, year={2025}}
+"""
+raw = rk.BibDocument.parse(duplicate_source)
+entries = raw.entries.get_all("doe2024")
+if len(entries) != 2:
+    raise ValueError(f"expected two doe2024 entries, found {len(entries)}")
+
+entry = entries[1]
+field = entry.fields.get_all("title")[0]
+field.value = "Corrected title"
+
+preview = raw.to_bibtex()
+print(preview)
+```
+
+Entry keys are case-sensitive. Field lookup is case-insensitive and preserves the source spelling of the field name. `get_all` makes duplicate occurrence selection explicit. `to_bibtex()` returns preview text and performs no filesystem write.
+
+After inspecting `preview`, commit the preserving write to the intended path:
+
+```python
+raw.write("references.bib")
+```
+
+## Format and inspect warnings
+
+```python
+duplicate_source = """
+@article{same, title={First}}
+@book{same, title={Second}}
+"""
+result = rk.tidy_bibtex(
+    duplicate_source,
+    options=rk.TidyOptions(
+        duplicates=["key"],
+        sort_fields=True,
+        wrap=88,
+    ),
+)
+
+formatted = result.bibtex
+warnings = [
+    {"code": warning.code, "rule": warning.rule, "message": warning.message}
+    for warning in result.warnings
+]
+```
+
+`duplicates=None` skips duplicate detection. `duplicates=["key"]` emits a `duplicate_entry` warning for repeated citation keys. `TidyResult.count` records parsed entry occurrences before duplicate merges.
+
+## Process bibliography columns with Polars
+
+Install `polars-refkit` separately, then import it once to register the expression namespace:
+
+```python
+import polars as pl
+import polars_refkit
+
+frame = pl.DataFrame({"bibtex": [source], "key": ["doe2024"]})
+result = frame.select(
+    citation_from_column=pl.col("bibtex").refkit.cite("key"),
+    citation_from_literal=pl.col("bibtex").refkit.cite(pl.lit("doe2024")),
+    entries=pl.col("bibtex").refkit.entries(fields=["key", "entry_type", "title"]),
+)
+```
+
+A plain string argument names a column. Wrap literal source or citation keys with `pl.lit(...)`. Importing `polars_refkit` registers `pl.Expr.refkit`. Citation expressions return null for row-local parse failures, missing keys, or rendering failures.