StreamTeX

Think with AI. Present with StreamTeX.

StreamTeX is the first document library designed for generative AI. It uses mainly Python — one of the languages best understood by large language models — so an AI assistant can create, modify, and maintain your documents as naturally as a human developer. You keep full control at all times: every file is readable text, editable by hand or by AI, with no limits imposed by the software or provider.

Why StreamTeX?

Two paths, one tool

StreamTeX supports two complementary approaches that produce exactly the same result:

10 reasons to choose StreamTeX

1. Built for generative AI — The only document library that AI can create, modify, and maintain end-to-end. Describe what you want in plain language; keep full control over the result.
2. Zero HTML, zero CSS — All formatting through composable Style objects in Python. No web knowledge needed.
3. Pure Python, nothing else — One language for content, logic, and style. No proprietary syntax, no opaque binary format. Readable, diffable, reviewable.
4. Total composability — Styles combine with +, blocks nest freely, documents are structured like code: functions, modules, reuse.
5. Complete independence — No account, no subscription, no mandatory server. Your files are yours — Git-versioned, readable in any text editor.
6. Universal export — Self-contained HTML (single file), PDF, cloud deployment. Works everywhere, forever.
7. Built-in diagrams — Mermaid, PlantUML, TikZ, and LaTeX — no external tools to install.
8. Book navigation — Table of contents, pagination, markers, keyboard navigation. Documents that read like real books.
9. The Streamlit ecosystem — Access all Streamlit widgets while keeping professional typography and layout.
10. One-command deployment — Pre-configured Docker and Hetzner/Coolify. Local prototype to online document in minutes with stx deploy.

Who is StreamTeX for?

• Teachers & trainers — Interactive, navigable educational documents with professional layouts — no CSS required.
• Professionals & consultants — Self-contained exportable documents (HTML/PDF), independent of any vendor or subscription.
• Developers & engineers — Native Python, composable, Git-versioned, with syntax highlighting and integrated diagrams.
• Researchers & scientists — LaTeX-quality typesetting + web interactivity + built-in diagrams (Mermaid, PlantUML, TikZ).

Getting Started

Prerequisites

• Python 3.11+ — check with python3 --version
• git — check with git --version
• uv (recommended) — fast Python package manager

Install uv (if not already installed):

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# macOS with Homebrew
brew install uv

# Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# Or with pip (any platform)
pip install uv

Without uv? StreamTeX can also be installed with pip alone — see Manual Installation below.

StreamTeX supports 4 installation levels. Pick the one that fits your needs.

Quick Start (minimal, no workspace)

From zero to a running project in 3 commands:

uv tool install "streamtex[cli]" -U
stx project new my-project
cd my-project && uv sync && stx run

Standard Setup (recommended)

Full workspace with rich templates, documentation, and Claude AI profiles:

uv tool install "streamtex[cli]" -U
mkdir streamtex-dev && cd streamtex-dev
stx install
stx update
stx project new my-project --template project   # CLI templates: project, collection, slides
cd projects/my-project
stx claude install project .
stx run

Full Setup (all optional features)

Everything above, plus AI image generation, PDF export, and live inspector:

uv tool install "streamtex[cli]" -U
mkdir streamtex-dev && cd streamtex-dev
stx install --preset power --project my-project --template project
stx update
cd projects/my-project
stx run

The power preset automatically installs PDF export, AI image generation, and the live inspector into your project. To add Playwright for PDF export, run:

uv run playwright install chromium

Each uv add installs optional features into the current project's environment. Pick only what you need — or install individual AI providers:

uv add "streamtex[ai-openai]"    # OpenAI only
uv add "streamtex[ai-google]"    # Google Imagen only
uv add "streamtex[ai-fal]"       # fal.ai only

AI image generation requires API keys in your .env file: STX_OPENAI_API_KEY, STX_GOOGLE_AI_KEY, STX_FAL_KEY (only the providers you use). See the AI Guide for configuration details.

Zero-Code with Claude or Cursor

Install StreamTeX and a Claude AI profile, then let the AI build your project:

uv tool install "streamtex[cli]" -U
mkdir streamtex-dev && cd streamtex-dev
stx install && stx update
stx project new my-project
cd projects/my-project
stx claude install project .

Open in Claude Code or Cursor, then use slash commands:

/stx-block:init
> "Create a Docker course with 12 slides, dark theme,
>  table of contents and page navigation"

The AI agent designs the project structure, proposes it for your approval, and generates all files — blocks, styles, book.py — ready to run:

stx run

See the AI Guide for all commands, agents, and workflows.

Code-First with Python

import streamlit as st
import streamtex as sx
from streamtex.styles.core import Style

st.set_page_config(page_title="My Book", layout="wide")

style = Style("color: navy; font-size: 1.2em;", "my-style")
sx.st_write(style, "Hello StreamTeX!")

stx run app.py

Manual Installation (without stx CLI)

pip install streamtex
git clone https://github.com/nicolasguelfi/streamtex-claude.git
mkdir my-project && cd my-project
python ../streamtex-claude/install.py project .
stx run

Workspace Presets

The stx install command supports 5 presets:

stx install --preset user       # Claude profiles only
stx install                     # standard (default)
stx install --preset developer  # full developer setup
stx install --preset power --project my-project  # all extras with a project

Developer shortcut: --dev

When you've already registered a local streamtex source via stx dev register streamtex /path/to/streamtex, add --dev to stx install --project NAME to immediately link that source into the new project's venv — equivalent to running stx dev link streamtex inside the project after creation, but in one command.

stx install --project my-project --dev               # auto-link streamtex from global registration
stx install --preset power --project my-project --dev  # full setup + dev-link in one shot

--dev is a no-op (with a hint) when streamtex is not registered globally, and warns if used without --project.

Upgrade an existing workspace to a higher preset:

stx install --preset developer
stx update

Optional Extras

StreamTeX uses optional dependency groups so you install only what you need:

uv add "streamtex[ai]"           # AI image generation (OpenAI + Google Imagen + fal.ai)
uv add "streamtex[ai-openai]"    # AI images — OpenAI only
uv add "streamtex[ai-google]"    # AI images — Google Imagen only
uv add "streamtex[ai-fal]"       # AI images — fal.ai only
uv add "streamtex[pdf]"          # PDF export via Playwright
uv add "streamtex[inspector]"    # Live code inspector sidebar
uv add "streamtex[cli]"          # stx CLI (already installed as a global tool above)

See the AI Image Generation section in the AI Guide for configuration and usage.

AI-Powered Features

StreamTeX ships with the stx-block (15 commands), stx-ce (14 commands), and stx-pe (7 commands) slash command groups, specialized agents, and 4 project templates for AI-assisted development.

Project Creation & Customization

Design & Content

Migration

Pack Engineering (/stx-pe) — orchestrated pack lifecycle

Single user-facing pack-orchestrator agent delegates to six invisible specialists; 4 validation gates (G1–G4). PE drives the deterministic stx component / pack / kit CLI commands and adds AI-assisted analysis, design, and retrofit.

AI Agents

See the AI Guide for the complete reference.

Claude & Cursor Integration

StreamTeX provides installable AI profiles via streamtex-claude:

Install a profile — two ways (since 0.7.35):

# Classic: copy the profile into the project once, update it on demand
stx claude install project ./my-project      # --dry-run shows what would change
stx claude update ./my-project               # --commit to commit the untracking

# Project mode: declare the profile in the project's stx.toml …
#   [claude]
#   mode = "project"
#   profile = "presentation"      # optional include = [...] / exclude = [...]
# … then let stx keep .claude/ in line with it (records .claude/stx.lock)
stx claude sync                               # --dry-run, --force, --remove

A CLAUDE.md you wrote is never overwritten (the profile text goes to .claude/CLAUDE.md), and stx never commits in your project unless asked. The commands stx used to copy into ~/.claude/commands are listed and removed with stx claude global status / stx claude global remove --yes.

Reuse architecture (stx pack / stx component / stx ds / stx kit)

The reuse architecture ships components, design systems, and kits as Python packs via PEP 621 entry points. The official pack is streamtex-pack-design, in the streamtex-packs monorepo.

# Add a pack to a project (git, local, or PyPI)
stx pack add 'git:https://github.com/nicolasguelfi/streamtex-packs@pack-design-v0.3.0#subdirectory=streamtex-pack-design'

# List installed packs and components
stx pack list
stx component list

# Install a kit (design system + curated components + samples)
stx kit install streamtex_design:project-default

# Validate the project's stx.toml + packs + components + DS + kits
stx validate

Validate, run several documents, deploy

# Run the real build() of every block of every book.py, headless:
# exceptions, media that resolve to nothing, inlined media > 512 KB
stx validate --build
stx validate --build --snapshot before.json   # per-block HTML fingerprint …
stx validate --build --against before.json    # … then: which blocks changed?
stx validate --build --published              # against the PUBLISHED streamtex

# Several documents of one project ([[run.documents]] in stx.toml: id, book, port)
stx run --set            # all of them, in the background; --doc ID, --lang fr
stx run --list           # their state;  stx run --kill  to stop them

# Deployment files
stx deploy diff          # how Dockerfile / entrypoint.sh / nginx.conf differ from the templates
stx deploy ci            # write .github/workflows/stx-validate.yml (ruff + validate --build)

The snapshot fingerprints the HTML that blocks emit; text rendered through st_markdown() / show_explanation() is not part of it.

When you scaffold a project with stx install --preset standard --project NAME, the streamtex-design pack is added automatically to the project's stx.toml; skip with --no-design-pack (or in CI for silent skip).

Features

• Styled text — st_write with tuple support for inline mixed-style text
• CSS Grid layouts — st_grid with responsive columns
• Block containers — st_block / st_span context managers
• Lists — st_list with ul/ol, custom bullets, centered alignment
• Images — st_image with base64 encoding and MIME detection
• AI image generation — st_image(prompt=..., editable=True, name=...) with OpenAI, Google Imagen, fal.ai (built-in editor panel)
• Code blocks — st_code with Pygments syntax highlighting
• Diagrams — Mermaid, PlantUML, TikZ with pan/zoom
• LaTeX — math formulas and full documents
• Bibliography — BibTeX/RIS/CSL-JSON import, citations, formatted references
• Book orchestration — st_book with paginated and continuous modes
• Table of Contents — auto-numbering and anchor navigation
• Navigation markers — slide-like PageUp/PageDown navigation
• Collections — multi-project hubs with TOML configuration
• HTML export — self-contained dual-rendering pipeline
• Style composition — Style objects with + / - operators
• Zoom controls — CSS-based width and zoom adjustments
• Block inspector — live code editor in sidebar (optional)
• Block helpers — DI-injectable helpers with 3 usage modes

Documentation

Online manuals (read & explore)

• All manuals (hub)
• Introduction
• Advanced
• AI & Claude
• Deployment Guide
• Developer Guide

Examples (source code)

The manuals are also available as source code — clone and run them locally to study the examples:

git clone https://github.com/nicolasguelfi/streamtex-docs
cd streamtex-docs
uv sync
cd manuals/stx_manual_intro && stx run

See streamtex-docs for the full list of example projects.

Reference

• AI Guide — zero-code workflows with Claude/Cursor
• Cheatsheet (EN)
• Coding Standards

Project Structure

A StreamTeX project follows this layout:

my-project/
├── .claude/                     # AI profiles (commands, skills, agents)
├── .streamlit/
│   └── config.toml              # enableStaticServing = true
├── blocks/
│   ├── __init__.py              # Block registry
│   └── bck_intro.py             # Your blocks (build() function each)
├── static/
│   └── images/                  # Static assets
├── custom/
│   └── styles.py                # Project-specific styles
└── book.py                      # Entry point with st_book()

Installation

# With uv (recommended) — install or upgrade the CLI as a global tool
uv tool install "streamtex[cli]" -U

# With pip (alternative — no uv required)
pip install "streamtex[cli]"

# Or as a project dependency
uv add streamtex          # uv
pip install streamtex     # pip

Optional extras:

uv add "streamtex[cli]"          # stx CLI commands
uv add "streamtex[inspector]"    # Live code inspector sidebar
uv add "streamtex[ai]"           # AI image generation (OpenAI + Google Imagen + fal.ai)
uv add "streamtex[ai-openai]"    # AI images — OpenAI only
uv add "streamtex[ai-google]"    # AI images — Google Imagen only
uv add "streamtex[ai-fal]"       # AI images — fal.ai only
uv add "streamtex[pdf]"          # PDF export via Playwright

Replace uv add with pip install if you don't use uv.

Project Configuration

StreamTeX projects using from streamtex import * require this ruff config in pyproject.toml (automatically generated by stx project new):

[tool.ruff.lint]
ignore = ["F403", "F405", "E701", "E741"]

If your project uses [tool.uv.sources] for editable installs, set UV_NO_SOURCES=1 in CI environments so uv resolves from PyPI instead of local paths.

Keeping Up to Date

Update the CLI

The stx CLI is installed as a global tool with its own frozen copy of the library. You must upgrade it explicitly after each release:

uv tool install "streamtex[cli]" -U

Update your workspace

cd streamtex-dev/
stx update                   # pulls repos, syncs deps, updates profiles

Fine-grained control:

stx update --skip-sync      # skip uv sync
stx update --skip-profiles  # skip Claude profile update

Check workspace status

stx status                   # show preset, repos, profiles, project list

Upgrade a project

stx project upgrade          # upgrade project deps and extras to match current preset

Update a standalone project (no workspace)

cd my-project/
uv add streamtex --upgrade   # update the library dependency

Use /stx-guide update inside Claude Code for guided assistance.

Report Issues & Feedback

Found a bug? Have a suggestion? We'd love to hear from you.

• Bug report: Open a bug report — include the error message, steps to reproduce, and your environment
• Feature request: Request a feature — describe the problem and your proposed solution
• Questions & discussions: GitHub Discussions — ask questions, share ideas, show your projects

When reporting a bug, please include:

1. The full error traceback (copy-paste from the terminal)
2. The command you ran (e.g. stx project new, /stx-block:init, stx run)
3. Your StreamTeX version (uv pip show streamtex | grep Version)

Contributing

See CONTRIBUTING.md for guidelines on code, content, and AI profile contributions.

Support the Project

If StreamTeX is useful to you, consider sponsoring the project to help maintain and improve it.

Acknowledgments

• Armando Freitas — A huge thank you to Armando, who worked alongside me to design and build the very first exploratory prototype that ultimately gave birth to StreamTeX. This project wouldn't be what it is today without that early collaboration.

License

BUSL-1.1 — Copyright (c) 2026 Nicolas Guelfi Converts to Apache 2.0 on 2030-11-29.