runai-publish

runai-publish is a small Python library and CLI for publishing text and document sources to production-friendly output formats. The initial focus is reliable conversion of Markdown, HTML, and plain text inputs into html, pdf, and docx.

The project is designed to work:

• as a pip-installable package,
• as a standalone CLI,
• later as a reusable backend component for RunAI, RunAI Studio, chatbot systems, TLex/TLinux, and related tools.

It works with or without AI. AI-generated content is a supported input source, not a requirement.

Status

This repository contains the initial export engine scaffold:

• input format inference from file extensions,
• a conversion planner based on a weighted graph,
• direct and staged conversion routes,
• CLI export commands with per-target success/failure reporting,
• graceful handling when external tools are not installed.

Requirements

Python 3.9+

External tools used by the current converters:

• pandoc
• wkhtmltopdf

Install those tools separately and ensure they are available on PATH.

Installation

Install the package locally:

pip install .

Usage

Export to all supported output formats:

runai-publish export sample.md --to all

Export a single target:

runai-publish export entry.html --to pdf

Export multiple targets:

runai-publish export sample.md --to html,pdf,docx

Convert plain text to HTML:

runai-publish export page.txt --to html

Control naming and route preference:

runai-publish export sample.md --to pdf --out release/sample --prefer-staged
runai-publish export sample.md --to html,pdf --doc-kind generic --prefer-direct

Design Philosophy

The implementation intentionally uses boring, reliable patterns:

• pathlib for file handling
• explicit converter classes
• a planner that treats formats as graph nodes and converters as edges
• minimal dependencies
• no hidden global state

The planner prefers direct routes by default, but it can also choose staged pipelines when direct conversion is unavailable or when --prefer-staged is selected.

Markdown is an important intermediate format, but not an enforced universal one. The architecture is meant to support future direct pipelines and richer publishing workflows, including XML-based or professional publishing systems.

Library Use

The package exposes a conversion engine that can be reused from Python:

from pathlib import Path

from runai_publish.engine import PublishEngine
from runai_publish.formats import OutputFormat

engine = PublishEngine.default()
result = engine.export_file(
    input_path=Path("sample.md"),
    targets=[OutputFormat.HTML, OutputFormat.PDF],
)

Testing

The included test suite focuses on unit tests that do not require external binaries:

• format inference
• route planning
• CLI target parsing
• graceful handling of unsupported input formats

Integration tests for pandoc and wkhtmltopdf are intentionally not included in the initial scaffold because they depend on external installations.

License

This project is intended to use the Business Source License 1.1.

Any use of the Licensed Work within a commercial organization or for revenue-generating purposes requires a separate commercial license from the Licensor.

Copyright

This project Copyright (C) David Joffe and DJ Software 2026

• David Joffe