Writer Module (stx.writer)

LaTeX manuscript compilation, figure/table management, bibliography handling, and IMRAD writing guidelines.

Note

stx.writer wraps the standalone scitex-writer package. Install with: pip install scitex-writer.

Quick Reference

from scitex.writer import Writer
from pathlib import Path

writer = Writer(Path("my_paper"))

# Compile manuscript → PDF
result = writer.compile_manuscript()
if result.success:
    print(f"PDF: {result.output_pdf}")

# Compile supplementary materials
result = writer.compile_supplementary()

# Compile revision with change tracking
result = writer.compile_revision(track_changes=True)

CLI Usage

# Compile
scitex writer compile manuscript ./my-paper
scitex writer compile supplementary ./my-paper
scitex writer compile revision ./my-paper --track-changes

# Bibliography
scitex writer bib list ./my-paper
scitex writer bib add ./my-paper "@article{...}"

# Tables and figures
scitex writer tables add ./my-paper data.csv
scitex writer figures list ./my-paper

# Writing guidelines
scitex writer guidelines get abstract

Project Structure

A writer project follows this layout:

my_paper/
+-- 00_shared/
|   +-- bibliography.bib
|   +-- figures/
|   +-- tables/
+-- 01_manuscript/
|   +-- main.tex
|   +-- sections/
+-- 02_supplementary/
|   +-- main.tex
+-- 03_revision/
    +-- main.tex

Create a new project:

scitex template clone paper my_paper

Key Classes

  • Writer – Main entry point for compilation and project management

  • CompilationResult – Compilation outcome (success, output path, logs)

  • ManuscriptTree – Document tree for the main manuscript

  • SupplementaryTree – Document tree for supplementary materials

  • RevisionTree – Document tree for revision responses

Document Management

Figures:

# Add figure (copies image + creates caption file)
writer.add_figure("fig1", "plot.png", caption="Results")

# List figures
writer.list_figures()

# Convert between formats
writer.convert_figure("figure.pdf", "figure.png", dpi=300)

Tables:

# Add table from CSV
writer.add_table("tab1", csv_content, caption="Demographics")

# CSV ↔ LaTeX conversion
writer.csv_to_latex("data.csv", "table.tex")
writer.latex_to_csv("table.tex", "data.csv")

Bibliography:

# Add BibTeX entry
writer.add_bibentry('@article{key, title={...}, ...}')

# Merge multiple .bib files
writer.merge_bibfiles(output_file="bibliography.bib")

Writing Guidelines

IMRAD guidelines for each manuscript section:

scitex writer guidelines list
scitex writer guidelines get introduction

from scitex.writer import guidelines

# Get guideline for a section
guide = guidelines.get("methods")

# Build editing prompt: guideline + draft
prompt = guidelines.build("discussion", draft_text)

Compilation Options

result = writer.compile_manuscript(
    timeout=300,        # Max compilation time (seconds)
    no_figs=False,      # Exclude figures
    no_tables=False,    # Exclude tables
    draft=False,        # Draft mode (fast, lower quality)
    dark_mode=False,    # Dark color scheme
    quiet=False,        # Suppress output
)

API Reference

SciTeX Writer - LaTeX manuscript compilation system with MCP server.

Four Interfaces:

  • Python API: import scitex_writer as sw

  • CLI: scitex-writer <command>

  • GUI: scitex-writer gui (browser-based editor)

  • MCP: 38 tools for AI agents

Modules:

  • claim: Traceable scientific assertions (stats, figures, citations)

  • compile: Compile manuscripts to PDF

  • export: Export manuscript for arXiv submission

  • migration: Import from / export to external platforms (Overleaf)

  • project: Clone, info, get_pdf

  • tables: List, add, remove, csv_to_latex

  • figures: List, add, remove, convert

  • bib: List, add, remove, merge

  • guidelines: IMRAD writing tips

  • prompts: AI2 Asta integration

  • gui: Browser-based editor (Django)

scitex.writer.usage()

Get the usage guide with branding applied.

Returns:

Formatted usage guide string.

Return type:

str

class scitex.writer.Writer(project_dir, name=None, git_strategy='child', branch=None, tag=None)[source]

Bases: object

LaTeX manuscript compiler.

__init__(project_dir, name=None, git_strategy='child', branch=None, tag=None)[source]

Initialize for project directory.

If directory doesn’t exist, creates new project.

Parameters:

  • project_dir (Path) – Path to project directory.

  • name (str, optional) – Project name (used if creating new project).

  • git_strategy (str, optional) – Git initialization strategy: - ‘child’: Create isolated git in project directory (default) - ‘parent’: Use parent git repository - ‘origin’: Preserve template’s original git history - None or ‘none’: Disable git initialization

  • branch (str, optional) – Specific branch of template repository to clone. If None, clones the default branch. Mutually exclusive with tag.

  • tag (str, optional) – Specific tag/release of template repository to clone. If None, clones the default branch. Mutually exclusive with branch.

compile_manuscript(timeout=300, log_callback=None, progress_callback=None, runner=None)[source]

Compile manuscript to PDF with optional live callbacks.

Runs scripts/shell/compile_manuscript.sh with configured settings.

Parameters:

  • timeout (int, optional) – Maximum compilation time in seconds (default: 300).

  • log_callback (callable, optional) – Called with each log line: log_callback(“Running pdflatex…”).

  • progress_callback (callable, optional) – Called with progress: progress_callback(50, “Pass 2/3”).

Returns:

With success status, PDF path, and errors/warnings.

Return type:

CompilationResult

Examples

>>> writer = Writer(Path("my_paper"))
>>> result = writer.compile_manuscript()
>>> if result.success:
...     print(f"PDF created: {result.output_pdf}")

runner is the underlying compile implementation; it defaults to scitex_writer._compile.compile_manuscript(). Exposed so callers and tests can supply an alternate implementation without patching module internals.

compile_supplementary(timeout=300, log_callback=None, progress_callback=None, runner=None)[source]

Compile supplementary materials to PDF with optional live callbacks.

Runs scripts/shell/compile_supplementary.sh with configured settings.

Parameters:

  • timeout (int, optional) – Maximum compilation time in seconds (default: 300).

  • log_callback (callable, optional) – Called with each log line.

  • progress_callback (callable, optional) – Called with progress updates.

Returns:

With success status, PDF path, and errors/warnings.

Return type:

CompilationResult

Examples

>>> writer = Writer(Path("my_paper"))
>>> result = writer.compile_supplementary()
>>> if result.success:
...     print(f"PDF created: {result.output_pdf}")

runner defaults to scitex_writer._compile.compile_supplementary(); exposed for injection without patching module internals.

compile_revision(track_changes=False, timeout=300, log_callback=None, progress_callback=None, runner=None)[source]

Compile revision document with optional change tracking and live callbacks.

Runs scripts/shell/compile_revision.sh with configured settings.

Parameters:

  • track_changes (bool, optional) – Enable change tracking in compiled PDF (default: False).

  • timeout (int, optional) – Maximum compilation time in seconds (default: 300).

  • log_callback (callable, optional) – Called with each log line.

  • progress_callback (callable, optional) – Called with progress updates.

Returns:

With success status, PDF path, and errors/warnings.

Return type:

CompilationResult

Examples

>>> writer = Writer(Path("my_paper"))
>>> result = writer.compile_revision(track_changes=True)
>>> if result.success:
...     print(f"Revision PDF: {result.output_pdf}")

runner defaults to scitex_writer._compile.compile_revision(); exposed for injection without patching module internals.

get_section(section_name, doc_type='manuscript')[source]

Get a DocumentSection by name and document type.

Parameters:

  • section_name (str) – Section name (e.g., ‘abstract’, ‘introduction’, ‘title’).

  • doc_type (str) – Document type: ‘shared’, ‘manuscript’, ‘supplementary’, or ‘revision’.

Returns:

Section object with .read(), .write(), .commit(), .history(), .diff().

Return type:

DocumentSection

Raises:

ValueError – If doc_type is unknown or section_name not found.

read_section(section_name, doc_type='manuscript')[source]

Read a section’s content as string.

Parameters:

  • section_name (str) – Section name (e.g., ‘abstract’, ‘introduction’).

  • doc_type (str) – Document type: ‘shared’, ‘manuscript’, ‘supplementary’, or ‘revision’.

Returns:

Section content. Empty string if section file is empty or missing.

Return type:

str

Examples

>>> writer = Writer(Path("my_paper"))
>>> text = writer.read_section("abstract")
>>> text = writer.read_section("title", "shared")
write_section(section_name, content, doc_type='manuscript')[source]

Write content to a section.

Parameters:

  • section_name (str) – Section name (e.g., ‘abstract’, ‘introduction’).

  • content (str) – Content to write.

  • doc_type (str) – Document type: ‘shared’, ‘manuscript’, ‘supplementary’, or ‘revision’.

Returns:

True if write succeeded.

Return type:

bool

Examples

>>> writer = Writer(Path("my_paper"))
>>> writer.write_section("abstract", "New abstract text.")
True
watch(on_compile=None, runner=None)[source]

Auto-recompile on file changes.

runner defaults to scitex_writer._utils._watch.watch_manuscript(); exposed for injection without patching module internals.

Return type:

None

get_pdf(doc_type='manuscript')[source]

Get output PDF path (Read).

Return type:

Optional[Path]

delete()[source]

Delete project directory (Delete).

Return type:

bool

scitex.writer.ensure_workspace(project_dir, git_strategy='child', **kwargs)[source]

Ensure writer workspace exists at {project_dir}/.scitex/writer/.

If the directory already exists, returns the path without modification. If not, clones the full scitex-writer template.

Parameters:

  • project_dir (str or Path) – Root project directory. Writer workspace will be at {project_dir}/.scitex/writer/ (hidden, dotfile convention).

  • git_strategy (str, optional) – Git initialization strategy (‘child’, ‘parent’, ‘origin’, None).

  • **kwargs – Forwarded to Writer constructor (branch, tag, etc.).

Returns:

Path to the writer workspace directory.

Return type:

pathlib.Path

scitex.writer.gui(project_dir, port=5050, host='127.0.0.1', open_browser=True, desktop=False, hot_reload=False)

Launch the Django editor server locally.

Tries scitex_app._standalone.run_standalone first (gets the full workspace shell from scitex-ui). Falls back to a bare runserver bootstrap if scitex-app is not installed.

Return type:

None