# 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**](docs/examples.md) — fridge scene, bedroom, landscape, iPhone mockup, cat manga, and more with previews.

## Quick Start

```bash
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:

```bash
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:

```bash
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:

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

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

## 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

| Category | Tools |
|----------|-------|
| **Document** | `create_document`, `clone_document`, `list_documents`, `delete_document`, `set_background`, `get_document` |
| **Create** | `create_element`, `create_primitive`, `create_curve`, `create_ellipse_band`, `create_text`, `insert_image`, `import_svg_path`, `generate_cloud`, `stroke_to_mass`, `flow_strokes` |
| **Edit** | `edit_element`, `edit_elements`, `refine_line`, `delete_element`, `copy_element`, `get_element`, `pull_boundary`, `split_shape_with_curve` |
| **Transform/reuse** | `transform_objects`, `warp_element`, `place_in_frame`, `project_quad`, `create_perspective_grid`, `create_facade_grid`, `create_surface_stripes`, `duplicate`, `boolean_operation` |
| **Depth** | `create_shadow`, `add_shading` |
| **Style** | `restyle`, `list_brush_presets`, `apply_brush_style`, `define_style_preset`, `apply_style_preset`, `list_style_presets`, `mix_element_colors`, `apply_fx`, `set_layer_role`, `apply_texture_effect`, `apply_depth_haze`, `generate_palette`, `define_gradient`, `apply_line_hierarchy`, `compare_style_consistency` |
| **Groups** | `edit_group`, `list_groups`, `list_layers`, `shift_layer_z` |
| **Comic** | `create_comic_panel_layout`, `create_panel_view`, `create_speech_balloon`, `create_caption`, `create_sfx` |
| **Procedural** | `create_line_pattern`, `generate_shape`, `generate_background_asset`, `add_bumps` |
| **View** | `render_preview`, `export_svg`, `describe_scene`, `find_objects`, `critique`, `checkpoint_diff`, `render_diff` |
| **History** | `checkpoint`, `restore`, `get_history`, `batch` |

### 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

```json
// 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

```json
// 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

```json
{"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

```json
{"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