Skip to main content

Tavola

Sources into a single, well-designed page.

Tavola turns one document into one infographic: a PNG, a PDF, or editable HTML. It runs on your machine, uses the language model you point it at (Ollama by default, or any OpenAI-compatible endpoint), and never sends your source anywhere else.

No account, no telemetry, no CDN, no hosted service.

source.pdf ──► brief ──► design plan ──► HTML/CSS ──► PNG · PDF · HTML

Tavola is the artefact half of a "NotebookLM for one page": it cares about the visual result, not about being a notebook app.

Download · Landing page · Source

Why it looks better than a prompt-and-fill script

One prompt that returns a title, three stats and four bullets produces a template, not a design. Tavola separates four decisions:

  1. Brief — typed facts, claims, numbers, citations, and the relationship between them (sequence, comparison, hierarchy, proportion).
  2. Design plan — the model chooses a layout from a catalog and a style pack; it does not write HTML.
  3. Render — deterministic, local HTML/CSS. Text is always exact; SVG export is M2.
  4. Quality gate — static checks for self-contained output and text budgets, then browser checks for overflow, clipping, tiny type, and contrast, plus optional best-of-3 vision scoring.

25 layouts × 6 style packs is 150 looks that share one renderer. See docs/LAYOUT-CONTRACT.md.

Install

The desktop builds are attached to GitHub Releases; macOS and Windows builds are unsigned for now. There is no PyPI release yet, so the wheel is also on the release page.

Python wheel:

pip install "tavola[serve,render] @ https://github.com/michael-borck/tavola/releases/download/v0.1.1/tavola-0.1.1-py3-none-any.whl"
playwright install chromium

From a checkout:

export UV_PROJECT_ENVIRONMENT="$HOME/.venvs/tavola"
uv sync --all-extras
uv run tavola --init-config
uv run playwright install chromium

For development on this machine (the repo lives on exFAT, so keep the venv on the internal disk):

export UV_PROJECT_ENVIRONMENT="$HOME/.venvs/tavola"
uv sync --all-extras
uv run --no-sync ruff check src tests
uv run --no-sync basedpyright
uv run --no-sync pytest

Configure

Layered, later wins: defaults → ~/.tavola.yaml → ./tavola.yaml → flags. Secrets can be ${VAR} references. The CLI never needs a plaintext key; the desktop first-run sheet writes the key to ~/.tavola.yaml with mode 600.

tavola --init-config
llm: ollama

# For the quality baseline used in this checkout:
#   llm: gemini
#   model: gemini-2.5-flash
#   export GEMINI_API_KEY=...
#   design.candidates: 3
#   design.judge: gemini
#   design.router: tev

llms:
  ollama:                       # local, no key, the default
    base_url: http://127.0.0.1:11434
    model: qwen3.5:4b
    think: false                # reasoning models otherwise spend the budget thinking

  openai-compatible:            # OpenAI, LM Studio, llama.cpp, OpenRouter
    base_url: https://api.openai.com/v1
    model: gpt-4o-mini
    api_key: "${OPENAI_API_KEY}"

  gemini:
    model: gemini-2.5-flash
    # api_key: "${GEMINI_API_KEY}"  # or set GEMINI_API_KEY

  anthropic:
    model: claude-sonnet-4-5
    api_key: "${ANTHROPIC_API_KEY}"

design:
  mode: structured              # structured | illustrated | auto
  layout: auto                  # or a layout id from `tavola layouts`
  style: professional           # professional | scientific | editorial | sketch
  orientation: portrait         # square | portrait | landscape
  density: standard             # concise | standard | detailed
  candidates: 1                 # 3 = best-of-3 with a vision judge
  judge: auto                   # auto | none | a provider label
  router: off                   # off | auto | tev (local System One router)

illustration:
  provider: off                 # off | gemini text-free hero art
  model: gemini-2.5-flash-image
  preset: editorial             # editorial | clay | sketch | minimal | papercut | cinematic
  direction: ""                 # optional; text inside images stays forbidden

render:
  measure: true                 # browser checks before saving

CLI

# The default command: one source in, one infographic out
tavola report.pdf
tavola notes.md -o page.png --style editorial --orientation square

# Diagram-shaped sources pick their own layout
tavola roadmap.txt --layout timeline --density concise

# Best-of-3 with a vision judge
tavola report.pdf --candidates 3 --judge gemini

# Write the editable artefact instead of a PNG
tavola paper.pdf -o paper.html

# Skip extraction and design from a saved Brief
tavola --brief brief.json -o page.png

# Inspect the catalog and the environment
tavola layouts
tavola styles
tavola formats
tavola models
tavola health --connect

# Web UI
tavola serve

Every artefact gets a versioned JSON sidecar next to it with the brief, the design plan, candidate scores, the provider, the warnings, and the render size — enough to reproduce or edit the page.

How the three passes work

1. Brief. The source is extracted (PDF, DOCX, Markdown, HTML, URL, text), condensed with map-reduce when it is long, then converted into a Brief: title, dek, one-sentence thesis, 3–6 claims (value, unit, source), 0–2 relationships, optional ordered series, a quote, citations. The relationship is what lets a timeline be a timeline instead of a pile of cards.

2. Design plan. The model sees the brief and a catalog of layouts and style packs. It returns a DesignPlan: layout id, style id, orientation, density, optional palette, emphasis, and asset prompts. Invalid ids are rejected and the model is asked once more; after that a deterministic heuristic picks a sensible layout with a warning. Set design.candidates: 3 or pass --candidates 3 to render three different plans, measure each, and let a vision model score legibility, composition, and hierarchy. Without vision support, Tavola keeps the first candidate that passed and reports why.

3. Render. Python builds the HTML from the chosen layout and theme tokens. No external CSS, no JavaScript, no network requests: Inter, Source Serif 4, and Caveat are embedded as latin-subset WOFF2 data URIs with system fallbacks. PNG and PDF go through headless Chromium; the HTML stays editable. SVG export is M2.

Layouts

id Best for Needs
hero-stat one headline number with context a numeric claim
bar-share parts of a whole or comparable figures 3+ numeric claims
donut-share parts of one whole with a legend 3+ numeric claims
dashboard a chart with a short insight rail 3+ comparable numbers + a text claim
stacked-share parts of a whole as one stacked bar 3+ comparable numbers
trend change over time as a line chart an ordered series
trend-dashboard KPI tiles plus a line chart and insight rail an ordered series
hierarchy a root with child nodes a hierarchy relationship
grouped-bars two aligned series as bars two series with shared labels
quadrant four competing priorities four claims
illustrated-comparison illustrated hero with two sides a comparison relationship
illustrated-quote illustrated hero with a quote a quote or strong thesis
illustrated an illustrated hero, thesis, and stat strip mixed numbers and narrative
illustrated-sequence hero art, KPI tiles, and a step flow a sequence relationship
illustrated-trend hero art, KPI tiles, and a line chart an ordered series
poster a large quote or thesis with abstract geometry a strong quote or argument
antv-comparison an automatic two-sided diagram a comparison relationship
antv-sequence an automatic horizontal sequence diagram a sequence relationship
antv-hierarchy an automatic tree diagram a hierarchy relationship
stat-row 3–4 comparable figures 3+ numeric claims
timeline things that happened in order a sequence or ordered claims
process how something works a sequence or ordered claims
comparison A vs B, before/after a comparison relationship
statement a strong quote or argument a quote or thesis
bento mixed evidence, 4–6 claims 4+ claims

Style packs: professional, scientific, editorial, sketch, noir, warm. They change tokens (colour, type, radius, texture), never structure. Bundled fonts: Inter, Source Serif 4, and Caveat (SIL OFL).

Orientations: square 1080×1080, portrait 1080×1350, landscape 1600×900.

Render modes

  • Structured (v0.1) — local HTML/CSS, exact text, editable in a browser.
  • Illustrated (shipped, opt-in) — a text-free generated hero image with exact native text, KPI tiles, and charts composed on top.
  • Painterly (planned, opt-in) — a whole poster from an image model, with the deterministic renderer available for text correction.

Privacy

  • Ollama runs locally. A cloud provider is used only if you configure one, with your key, and only the source text and brief are sent. Best-of-N is opt-in; it also sends the rendered candidate images to the judge provider, which can be the same local model or a different, explicitly configured one.
  • The web UI offers mode, theme, visual style, illustration on/off, art direction, format, and density. It keeps its gallery in memory. Generate writes the PNG and sidecar into serve.out_dir (~/Pictures/Tavola by default).
  • Nothing is logged, telegraphed, or phoned home. The artefact has no external references.

Desktop

A Tauri v2 shell wraps a uv-bootstrapped private runtime and the local tavola serve process, using the same pattern as Limn and Canturía. Unsigned installers come from GitHub Releases; see desktop/README.md.

License

MIT.

Metadata

Release files for tavola 0.1.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for tavola 0.1.1
File Size Uploaded Provenance Actions
tavola-0.1.1.tar.gz 5.9 MB Without provenance Details for tavola-0.1.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for tavola 0.1.1
File Interpreter ABI Platform Actions
tavola-0.1.1-py3-none-any.whl Python 3 none any Details for tavola-0.1.1-py3-none-any.whl

Total release size: 6.6 MB

Release files / tavola-0.1.1.tar.gz

Download URL tavola-0.1.1.tar.gz
Size 5.9 MB
Tags Source
SHA-256 checksum
How to use checksums
c5c9975bf8a59a083737c1b4e796dffc3e340eb13834f9592c980fbef7b478e6
BLAKE2b-256 checksum
How to use checksums
2f744c7dc6a3eb1d077802bf52cfeee79ab52754e14af8fa0b033feee4696bf1
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.0

Release files / tavola-0.1.1-py3-none-any.whl

Download URL tavola-0.1.1-py3-none-any.whl
Size 752.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
8392966feaa73f15d6698cb11869f00c87e9e0d037cb81df0e559db2faa6ad23
BLAKE2b-256 checksum
How to use checksums
573b532d4efd809105d5eeca2b1edb578c121f18eab843892ce6e7655b45ac6e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.0

Security for tavola 0.1.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.1 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page