AVGE Engine — AI-Native Vector Graphics Engine

Version: 0.5.14 | Tool set: m0b-v41

Vector illustration tools for AI agents — create editable vector art with shapes, armatures, materials, and rendering. Output is clean SVG you can open in Illustrator, Figma, or any vector editor. Runs as an MCP server.

View examples — fridge scene, bedroom, landscape, iPhone mockup, cat manga, and more with previews.

Quick Start

python -m avge_engine api       # FastAPI HTTP server (:8000)
python -m avge_engine mcp-sse   # MCP SSE server (:8001)
python -m avge_engine mcp       # MCP stdio server

Preview renders at http://localhost:8000/preview/<document_id>.png

Storage backends

File storage remains the default. To use transactional SQLite persistence:

AVGE_STORAGE_BACKEND=sqlite \
AVGE_SQLITE_PATH=.avge_data/avge.sqlite3 \
python -m avge_engine api

The SQLite schema is upgraded through the bundled Alembic migrations when the adapter starts. Alembic also honors AVGE_SQLITE_PATH for command-line schema operations, with AVGE_DATABASE_URL available as an explicit SQLAlchemy URL override. To migrate existing file-backed documents, preview the work first and then opt into writes:

avge-migrate-storage .avge_data
avge-migrate-storage .avge_data --write

The migration verifies IDs, metadata, element counts, and canonical checksums, and leaves the source JSON files untouched. It validates the complete selected set before opening SQLite and commits all documents in one transaction. Existing identical documents are skipped; divergent database documents are reported as conflicts so newer edits cannot be lost. Replace them only when that is intentional:

avge-migrate-storage .avge_data --write --overwrite

The source-tree compatibility wrapper remains available at scripts/migrate_file_storage_to_sqlite.py.

Related MCP server: illustrator-mcp

Features

• Normalized coordinates — 0.0–1.0 canvas, no pixel math

• Isometric box — 3-face box with z-ordering, shadows, per-face styling, top_slant for slanted surfaces, and attach pattern for anchor-to-anchor placement

• Procedural geometry — radial spread, offset outlines, guide lines, segmented chains, speech bubbles, bursts, armature skeletons, foreshortening, surface detail

• Armature skeletons — node-edge graphs with tapered segments, junction separation, filleted V-gaps, curved Catmull-Rom chains, and unary union merging

• Boolean operations — union, intersect, subtract, xor with Ramer-Douglas-Peucker simplification

• Perspective projection — true one-/two-point guides and homography-based panels, facades, windows, signs, floor tiles, and stripes

• HSL shading — auto highlight + shadow from light direction, plus gradient mode for architectural planes

• Depth shadows — create_shadow creates soft blurred grounding shadows or clipped cast shadows from existing outlines

• Scene critique — critique(mode="rules"|"visual"|"both") flags rule-based composition issues and visual-read problems

• Primitives — rects (including tapered/trapezoid), ellipses, ellipse/arc bands, lines, open polylines, compound paths, arcs, polygons, stars, and isometric boxes

• Text + images — SVG text with font family/style/anchor/letter-spacing/opacity/skew for isometric perspective, embedded images via <image>

• Gradient backgrounds — linear and radial gradient definitions, inline in create_document or via set_background

• Style system — fill, stroke, stroke-width, opacity, blend modes, dash patterns, rgba/hsla color support

• Material presets — restyle(material=...) for glass, brushed metal, concrete, wood, tile, and foliage with editable highlights, shadows, seams, and grain overlays

• Pixel stroke widths — stroke_width accepts canvas pixels for predictable rails, seams, branches, and cables

• Environment helpers — perspective grids, facade/window density, surface stripes, soft clouds, haze, and densify patterns for cornices, awnings, and rooftop props

• Line pattern helpers — wavy, zigzag, spiral, hatch, cross-hatch, contour hatch, scribble, stipple, and true tapered/pressure-width strokes

• Region pattern styling — apply dashed, dotted, wavy, zigzag, rough, sketch, tapered, pressure outlines, plus hatch/scribble/stipple fills, directly on primitives, freeform regions, curves, and ellipse bands

• Generic art workflow tools — brush presets, layer roles, clipped texture/effect overlays, halftones, bloom, particles, and gradient/rim lighting

• Shared selectors — targeting tools use one selector shape: ids, group_name, layer, fill, tags, bounds, z_min, z_max, has_stroke

• Atomic batch operations — execute multiple tools as one version/checkpoint/save; SQLite provides durable multi-document rollback, while file storage remains the compatibility backend for local documents

• Pluggable persistence — file storage or SQLAlchemy-backed SQLite with Alembic migrations, compressed checksummed bodies, metadata queries, and optimistic concurrency

• Palette generation — HSL harmony presets (complementary, triadic, analogous, etc.)

• Named gradients — define once with define_gradient, reference by name in restyle

• Cross-document copy — copy elements between documents with offset

• Reusable framed views — place linked documents, groups, or elements with cached 2D crop views, focal point, fit mode, and per-instance overrides

• Comic-page construction — managed panel borders, linked panel art, speech balloons, captions, SFX lettering, and comic-aware critique

• Durable affine transforms — mixed primitives, images, text, explicit Bézier handles, masks, and managed companions stay aligned across composed edits

• SVG arc support — A/a commands in import_svg_path (elliptical arcs with sweep/large-arc flags)

• Relative positioning — place elements relative to a parent region's bounding box

• PNG rasterization — via rsvg-convert (librsvg) with Unicode/emoji font support

• Per-document tracking — durable bounded checkpoint/restore history and tool usage stats

74 MCP Tools

Coordinates

All coordinates are normalized 0.0–1.0 where (0, 0) = top-left and (1, 1) = bottom-right.

Isometric Box — 5 calls for a table with 4 legs

// Frame — one call
{"pattern": "isometric_box", "params": {"new_prefix": "frame",
  "x": 0.35, "y": 0.35, "width": 0.35, "depth": 0.22, "height": 0.05,
  "fill": "#A0522D", "z_index": 5, "shadow": true}}

// Legs — attach by named anchor, zero coordinate math
{"pattern": "attach", "params": {"parent": "frame_top",
  "parent_anchor": "bottom_left", "child_anchor": "top_left_corner",
  "width": 0.06, "depth": 0.06, "height": 0.15, "fill": "#666",
  "flush": true, "z_index": 0}}

{"pattern": "attach", "params": {"parent": "frame_top",
  "parent_anchor": "bottom_right", "child_anchor": "top_right_corner",
  "width": 0.06, "depth": 0.06, "height": 0.15, "fill": "#555",
  "flush": true, "z_index": 0}}

{"pattern": "attach", "params": {"parent": "frame_top",
  "parent_anchor": "bottom_back_left", "child_anchor": "top_left_corner",
  "width": 0.06, "depth": 0.06, "height": 0.15, "fill": "#777",
  "flush": true, "z_index": 0}}

{"pattern": "attach", "params": {"parent": "frame_top",
  "parent_anchor": "bottom_back_right", "child_anchor": "top_right_corner",
  "width": 0.06, "depth": 0.06, "height": 0.15, "fill": "#888",
  "flush": true, "z_index": 0}}

Text with Isometric Perspective

// Text skewed to match a right face (slope = -30°)
{"tool": "create_text", "x": 0.25, "y": 0.55, "text": "THE BOOK",
 "font_size": 0.025, "skew_y": -30, "fill": "#FFF", "font_weight": "bold"}

Gradient by Name

{"tool": "define_gradient", "name": "gold_top", "stops": [
  {"offset": 0, "color": "#FFD700"}, {"offset": 1, "color": "#DAA520"}], "angle": 160}

{"tool": "restyle", "fill_gradient": "gold_top", "selector": {"ids": ["panel_1"]}}

Material Presets

{"tool": "restyle", "selector": {"ids": ["window"]}, "material": "glass"}
{"tool": "restyle", "selector": {"ids": ["floor"]}, "material": "tile", "material_intensity": 0.8}

Architecture

avge_engine/
├── controllers/      # MCP tool definitions (region, scene_ops, style, procedural, ...)
├── document/         # In-memory document models, session, and domain repository
├── geometry/         # Curve fitting, procedural patterns, types
├── effects/          # Style dataclass, HSL color transforms
├── renderer/         # SVG serializer + PNG rasterization
├── services/         # Application and art services
├── storage/          # Adapter boundary, compact codec, file backend
│   └── db/           # SQLAlchemy models, repositories, services, migrations
├── api.py            # FastAPI HTTP server
└── server.py         # MCP server setup (FastMCP)

• Python 3.12 with FastMCP (MCP SDK)

• Normalized coordinates, resolved at render time

• Catmull-Rom → cubic Bézier curve fitting (deterministic, closed-form)

• SVG output with text, images, gradient defs, skew transforms

• PNG preview via rsvg-convert with fontconfig/Unicode support

• File or SQLite persistence behind one document storage adapter