Metadata-Version: 2.5
Name: vixl-engine
Version: 0.25.1
Summary: A headless design engine for AI agents. Programmable, editable, checked.
Project-URL: Homepage, https://github.com/jxburros/Vixl
Project-URL: Documentation, https://github.com/jxburros/Vixl/tree/main/docs
Project-URL: Repository, https://github.com/jxburros/Vixl
Project-URL: Issues, https://github.com/jxburros/Vixl/issues
Project-URL: Changelog, https://github.com/jxburros/Vixl/blob/main/CHANGELOG.md
License-Expression: LicenseRef-PolyForm-Small-Business-1.0.0
License-File: LICENSE
Keywords: ai-agents,animation,automation,design,graphics,image,layers,mcp,pdf,svg
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Multimedia :: Graphics
Classifier: Topic :: Multimedia :: Graphics :: Editors
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.11
Requires-Dist: filelock<4,>=3.21
Requires-Dist: fonttools<5,>=4.59
Requires-Dist: httpx<1,>=0.28
Requires-Dist: jsonschema<5,>=4.23
Requires-Dist: mcp<2,>=1.12
Requires-Dist: numpy<3,>=2.0
Requires-Dist: pillow<13,>=11.3
Requires-Dist: python-bidi<1,>=0.6.6
Requires-Dist: resvg-py<1,>=0.5
Requires-Dist: segno<2,>=1.6
Requires-Dist: shapely<3,>=2.1.2
Requires-Dist: uharfbuzz<1,>=0.52
Provides-Extra: anthropic
Requires-Dist: anthropic<2,>=1.11; extra == 'anthropic'
Provides-Extra: dev
Requires-Dist: anthropic<2,>=1.11; extra == 'dev'
Requires-Dist: fastapi<1,>=0.115; extra == 'dev'
Requires-Dist: mcp<2,>=1.12; extra == 'dev'
Requires-Dist: pypdf<7,>=5; extra == 'dev'
Requires-Dist: pypdfium2<6,>=4.30; extra == 'dev'
Requires-Dist: pytest-xdist<4,>=3.6; extra == 'dev'
Requires-Dist: pytest<10,>=8; extra == 'dev'
Requires-Dist: python-pptx<2,>=1.0; extra == 'dev'
Requires-Dist: ruff>=0.12; extra == 'dev'
Requires-Dist: uvicorn<1,>=0.30; extra == 'dev'
Provides-Extra: mcp
Requires-Dist: mcp<2,>=1.12; extra == 'mcp'
Provides-Extra: pdf
Requires-Dist: pypdfium2<6,>=4.30; extra == 'pdf'
Provides-Extra: server
Requires-Dist: fastapi<1,>=0.115; extra == 'server'
Requires-Dist: uvicorn<1,>=0.30; extra == 'server'
Description-Content-Type: text/markdown

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="assets/brand/ripple/SVG/horizontal-reverse.svg">
  <img src="assets/brand/ripple/SVG/horizontal-color.svg" alt="Vixl" width="320">
</picture>

# Vixl

**Ideas become editable.** A design engine for AI agents.

Ask an AI for a poster and you usually get a picture of a poster. Vixl gives your agent the
real thing: layers, live text, fonts, a history you can rewind, and a `.vixl` master you can
still change next week. It checks contrast, spacing and bleed before export, so nobody finds
out at the print shop.

Works through MCP, CLI, Python or REST. No windows required.

Current tagged release: **0.25.1**. See the [changelog](CHANGELOG.md#0251) for release notes.
Run `vixl --version` to check your runtime;
record the Git commit when using a source checkout.

**[Documentation home](docs/README.md)** · [Getting started](docs/getting-started.md) ·
[Visual gallery](docs/gallery.md) · [Command reference](docs/commands.md) ·
[Downloads](https://github.com/jxburros/Vixl/releases/latest) · [Marketing pack](marketing/README.md)

![A diagram created entirely with editable Vixl layers](docs/assets/generated/workflow.png)

## Programmable. Editable. Checked.

- **Programmable.** One JSON operation format behind MCP, the CLI, Python and REST. Batches of up to
  10,000 operations apply atomically, so a half-finished edit never lands.
- **Editable.** Text stays text, effects stay a stack, and history branches. Charts open in PowerPoint
  as real charts, forms export as PDFs people can fill in, and every piece ships with its master.
- **Checked.** Contrast, spacing, bounds, fonts, trim and bleed are measured, your brief can be saved as
  a test suite, and you preview the render before anything is exported.

## What you can make

| Goal | Examples and guides |
| --- | --- |
| Posters, social graphics and branded variants | [Campaign tutorial](docs/tutorials/campaign.md), [sizes/layouts](docs/sizes-and-layouts.md), [brands](docs/brands.md), [design styles](docs/styles.md), [finishing looks](docs/looks.md), [CSV merge to print sheets](docs/imposition.md), [linked documents](docs/linked-documents.md) |
| Charts, diagrams and infographics | [Editable chart tutorial](docs/tutorials/charts.md), [data-bound charts](docs/charts.md), [flowcharts and diagrams](docs/diagrams.md), [design tools](docs/design-tools.md) |
| Photo edits, drawings and painted artwork | [Filters](docs/artistic-filters.md), [drawing cleanup](docs/drawing.md), [brushes](docs/brushes-and-animation.md), [organic shapes](docs/organic.md), [irregularity and torn edges](docs/irregular.md), [irregular image frames and paint drips](docs/design-tools.md#irregular-image-frames-and-paint-simulation) |
| Presentations, carousels and booklets | [Forms and decks tutorial](docs/tutorials/forms-and-decks.md), [slides/pages](docs/slides.md), [HTML presenter](docs/presenter.md), [rich text](docs/rich-text.md), [text flow](docs/text-flow.md) |
| Registration forms and filled copies | [Forms](docs/forms.md), including fillable PDFs and CSV-driven output |
| Motion, sprites and lyric videos | [Character rigs, audio and cameras](docs/animation-authoring.md), [six-second video templates](docs/animation-authoring.md#joint-pose-keys-and-short-templates), [app animation packages](docs/animation-authoring.md#app-animation-packages), [Motion tutorial](docs/tutorials/motion.md), [pixel animation](docs/pixel-animation-spacing.md), [lyric videos](docs/lyric-video.md) |
| Checked production and collaboration | [Production workflows](docs/production.md), [studio](docs/studio.md), [agent resources](docs/agent-resources.md), [Git-reviewable source folders](docs/commands.md#reviewing-editable-projects-in-git), [local screen capture](docs/commands.md#local-desktop-capture) |
| Reusable containers, templates and comics | [Container and template library](docs/containers-and-templates.md) |
| Editable emoji libraries and custom packs | [Emoji catalog, templates, replacements and Discord/Slack exports](docs/emojis.md) |
| Vector drawing and precise placement | [Vector paths and shape catalog](docs/vector-paths.md), [spatial queries and transforms](docs/spatial-transforms.md) |
| Texture, lighting and media review | [Creative media workflows](docs/media-craft.md) |
| Agent discovery and bounded diagnostics | [Agent workflow guide](docs/agent-discovery.md), [MCP toolset evaluation](docs/mcp-toolsets.md) |
| AI generation and vision | [Provider setup and capabilities](docs/providers.md); external services required |

## Install

On Windows, download the latest **Vixl-Setup-VERSION-windows-x64.exe** from
[GitHub Releases](https://github.com/jxburros/Vixl/releases/latest). It bundles Python,
REST and MCP, installs for your user account, and supports verified automatic updates.
If `vixl` is not found, reopen the terminal or see [PATH repair](docs/releases.md#using-the-current-terminal).

```text
vixl --version
vixl update --check
vixl update
```

For source development, use Python 3.11+:

```bash
git clone https://github.com/jxburros/Vixl.git
cd Vixl
python -m venv .venv
# macOS/Linux:
source .venv/bin/activate
# Windows PowerShell: .venv\Scripts\Activate.ps1
python -m pip install -e '.[server,pdf]'
vixl --version
```

The core install is `python -m pip install -e .`; MCP is included. Optional `server`
adds REST/live review, and `pdf` adds PDF page import. Pip installs use pip-managed
updates. [Installation and releases](docs/releases.md) covers pinned versions, Windows
rollback, agent bundles and packaging.

## Make your first design

Six commands, one checked design, still fully editable:

```bash
vixl new 800x600 --background '#18283b' -o hello.vixl
vixl -p hello.vixl text add 'Hello, Vixl' --name title --size 64 --color '#ffffff'
vixl -p hello.vixl align title center
vixl -p hello.vixl check --checks bounds contrast
vixl -p hello.vixl render --out hello-preview.png
vixl -p hello.vixl export hello.png
```

Editing commands autosave; pass `-p` explicitly in scripts. Inspect the preview before
handoff. The [first-design walkthrough](docs/getting-started.md) explains undo,
checkpoints, JSON batches and Python. Use the bundled font for proofing; choose suitable
[typography](docs/typography.md) for finished work.

## Connect an agent

Point your agent at a workspace folder and let it work:

```bash
vixl mcp --workspace . --tools core --schema slim
```

For a pinned tagged runtime with uv:

```bash
uvx --from https://github.com/jxburros/Vixl/archive/refs/tags/v0.25.1.tar.gz vixl mcp --workspace . --tools core --schema slim
```

The workspace must exist. Use `--tools compact --schema slim` for consolidated workflow
tools, `--tools ai` for provider-backed tools, or `--http` for Streamable HTTP.
[Interface setup](docs/interfaces.md) includes client JSON, multi-document sessions,
REST authentication, imports and live human review (`vixl -p hello.vixl view`).

The [Vixl agent skill](skills/vixl/SKILL.md) teaches the inspect → apply → check → preview
→ export loop, recipes and operation details. Copy its folder to your agent's skills
directory. AI functions use explicitly configured providers; Vixl contains no model weights.

## Use Python

```python
from vixl import Project

project = Project(800, 600, background="#18283b")
project.apply([
    {"type": "text", "name": "title", "text": "Hello, Vixl", "size": 64, "color": "#ffffff"},
    {"type": "align", "target": "title", "alignment": "center"},
])
project.save("hello.vixl")
project.export("hello.png")
```

All interfaces share canonical operations and atomic batches. Direct Python requires
an explicit save. See [document concepts](docs/concepts.md), [operation semantics](docs/operations.md)
and [Python/REST/MCP](docs/interfaces.md) for deeper integration.

## Examples and development

![Actual Vixl chart with illustrative data](docs/assets/generated/chart.png)

[Editable chart](docs/assets/generated/chart.vixl) · [Recipe](docs/assets/generated/chart.json)
· [Visual capability gallery](docs/gallery.md)

```bash
python -m pip install -e '.[dev]'
python examples/build_documentation.py
python examples/build_poster.py --output examples/output
python examples/build_sprite.py --output examples/output/sprite
python examples/build_filter_gallery.py
python examples/build_organic_gallery.py
python examples/build_irregular_gallery.py
python examples/build_drawing_pipeline.py
python -m pytest -q
```

The documentation builder creates diagrams, charts, artwork, forms, slides and motion
without AI credentials or network access. Every new visual has an editable master and
operation recipe; see [documentation maintenance](docs/documentation-maintenance.md).
[Explorations](explorations/README.md) showcase longer creative projects, and
[agent evaluations](evals/README.md) measure design tasks.

Vixl edits in RGBA8 sRGB and exports supported vectors or documented raster fallbacks.
CMYK is an export setting. RAW development, spot-color editing, PSD/XCF import
(PSD export is layered pixels) and a desktop GUI are outside this implementation. Review
[coverage and limitations](docs/coverage.md), [export behavior](docs/exporting.md) and
[architecture](docs/architecture.md) before choosing it for a workflow.
The [original product specification](docs/product-spec.md) is retained as design context.
The [Ripple identity kit](assets/brand/ripple/START-HERE.md) includes logos,
icons, an animated wordmark, usage guidance and editable masters.

## Licence

Vixl is source-available under the [PolyForm Small Business License 1.0.0](LICENSE): free for
individuals and for companies with fewer than 100 people and under US$1M (2019) revenue; larger
companies need a commercial licence from the licensor. Copies of Vixl must carry the licence and
its `Required Notice:` lines. If Vixl helped make your work, please credit it ("Made with Vixl").

Bundled assets keep their own terms: DejaVu Sans ([font licence](src/vixl/data/FONT-LICENSE.txt)), the Noto Sans,
Noto Sans Symbols, Noto Sans Symbols 2 and Noto Sans Math fallback fonts ([SIL OFL 1.1](src/vixl/data/NOTO-LICENSE.txt)),
the xkcd colour names (CC0), and VIXL Line emoji artwork adapted from OpenMoji
([CC BY-SA 4.0](src/vixl/data/emojis/LICENSE.txt); [Unicode data license](src/vixl/data/emojis/UNICODE-LICENSE.txt)).
