fabricatio-typst

MIT

Academic article generation and Typst document tooling, built on Fabricatio's event-based agent framework.

Installation

pip install fabricatio[typst]

For RAG-backed article writing:

pip install fabricatio[typst,rag]

Overview

Two layers compose this package:

Rust extension (fabricatio_typst.rust) — performance-critical utilities:

• TeX-to-Typst math conversion (raw LaTeX and delimited $/$$/\(/\[ math)
• BibTeX bibliography management with fuzzy citation lookup
• Typst comment manipulation and YAML front-matter handling
• Markdown section extraction

Python layer — staged, typed academic content generation:

• Extract paper essences and propose structured research proposals
• Plan an article level by level — article, chapters, sections, subsections — then write every subsection against the running text
• RAG-backed composition that retrieves each subsection's own references and cites them inline
• Store and query article chunks in LanceDB
• Compile .typ documents to PDF, PNG, or SVG via the typst compiler

Rust API

from fabricatio_typst.rust import (
    BibManager,
    tex_to_typst,
    convert_all_tex_math,
    comment,
    uncomment,
    strip_comment,
    split_out_metadata,
    to_metadata,
    extract_body,
    replace_thesis_body,
    extract_sections,
    fix_misplaced_labels,
)

TeX Conversion

tex_to_typst(r"\frac{1}{\sqrt{x^2 + 1}}")
# => '#frac(1, sqrt(x^2 + 1))'

convert_all_tex_math("Einstein's $E = mc^2$ is famous.")
# => "Einstein's $E = m c^2$ is famous."

Comment Utilities

BibManager

Loads a BibTeX bibliography file and provides fuzzy citation lookup.

bib = BibManager("references.bib")
cite_key = bib.get_cite_key_by_title("Attention Is All You Need")
# => "vaswani2017attention"

key = bib.get_cite_key_fuzzy("transformers attention mechanism")
authors = bib.get_author_by_key(key)
abstract = bib.get_abstract_by_key(key)

Document Utilities

Python Models

Hierarchical article representation from proposal through completed paper:

The staged pipeline plans through one flat plan model per level and writes into a typed context tree; the outline ladder above is the artifact that tree assembles into:

Actions

Each action is a Fabricatio Action — an async callable unit in the agent workflow. Available actions:

Content Extraction

Staged Composition

Every stage runs one segment of the compose_article chain and then persists a whole-tree snapshot under <persist_dir>/stage_<name>, so a wrong result can be traced back to the stage that produced it.

The actions below are the run's side utilities:

RAG-Backed Writing

Compilation

from pathlib import Path
from fabricatio_typst.actions.article import CompileArticle, CompileTypstDocument

# Compile a standalone .typ file
result = await CompileTypstDocument().act({
    "typst_source": Path("paper.typ"),
    "output_path": Path("paper.pdf"),
})
# result["compiled_path"] → Path("paper.pdf")

# Compile a generated article (after DumpFinalizedOutput)
result = await CompileArticle().act({
    "article_path": Path("output.typ"),
})
# result["compiled_path"] → Path("output.pdf")

Citation Capability

CitationLancedbRAG — citation-aware iterative search that expands queries over multiple rounds and deduplicates by bibtex key.

CitationSubsectionCompose — the composition leaf that mixes that search into a subsection's write: retrieval is seeded with the running text and the subsection's own plan, the model writes [[n]] markers, and the manager rewrites them into typst @cite notation paragraph by paragraph.

Workflows

Pre-composed action pipelines:

The task init context carries the run's inputs: article_briefing or article_briefing_path, article_language (detected from the briefing when unset), writing_constraint, skills, persist_dir (the stage snapshots) and article_output_path (the dumped deliverable). Driving the stages directly keeps the same inputs and writes into the same context:

from pathlib import Path

from fabricatio_typst.workflows.article import ArticleWorkflow

cxt = {
    "article_briefing_path": Path("article_briefing.txt"),
    "article_output_path": Path("article.typ"),
    "persist_dir": Path("persistent"),
}
for stage in ArticleWorkflow.iter_actions():
    cxt = await stage.act(cxt)

print(cxt["task_output"])  # Path("article.typ")

Dependencies

• fabricatio-core — agent framework and core models
• fabricatio-tool — filesystem utilities
• fabricatio-capabilities — capability mixins (Extract, WordCount, FinalizedDumpAble, etc.)
• fabricatio-context — the typed context log the pipeline's trees narrow
• fabricatio-skill — skill documents the planning and writing prompts render
• typst — Typst compiler Python bindings (for compilation actions)

Optional for the staged pipeline:

• fabricatio-improve, fabricatio-rule — the ruleset-driven repair pass (CensoredSubsectionRepair)

Optional for RAG features:

• fabricatio-lancedb — vector storage and retrieval

CLI

The package includes the ttm (TeX to Typst Math) binary:

# Convert math in a file
ttm file input.md -o output.md

# Convert raw LaTeX string
ttm raw "\frac{a}{b}"

# Convert a string with math delimiters
ttm string "The formula $\int_0^\infty e^{-x} dx$ is useful."

Configuration

All options below are read through the fabricatio configuration chain (see the Configuration Guide). Set them under the [ext.typst] table in fabricatio.toml, equivalently under [tool.fabricatio.ext.typst] in pyproject.toml, or via FABRICATIO_EXT__TYPST__<FIELD_UPPER> environment variables.

[ext.typst]
chap_summary_template = "built-in/chap_summary"

Access at runtime: from fabricatio_typst.config import typst_config.

License

MIT — see LICENSE