▓▒░ ArtScii ░▒▓

A local ASCII art studio with a web dashboard, terminal UI, and a built-in 1.58-bit LLM — no cloud, no subscriptions, runs entirely on your machine.

---

Features

Text → ASCII	500+ pyfiglet fonts with a visual font browser (live previews, favourites, search), 14 border styles with padding and embedded titles
Image → ASCII	Four render modes: grayscale charsets, full-colour ASCII, half-block hi-res colour (2× vertical resolution), and braille (2×4 dots per character). Brightness / contrast / gamma controls, Floyd–Steinberg dithering, custom character sets
AI generation	Type a natural language prompt — a local 1.58-bit model interprets intent and renders the art
Template library	220+ templates across 12 categories (frames, flowcharts, UI elements, animals, kaomoji, game art…) with search and hover preview, plus 420+ insertable symbols
Editor	ANSI colours, gradient & rainbow colourisers, borders, align/shift, flip H/V with character mirroring, find & replace, line tools
Workflow	Undo/redo, autosave, named gallery (browser-local), .txt import
Themes	Phosphor · Amber · Ice · Synthwave · Mono · Paper
Export	.txt, .html (with colours), .ans, .png image, copy as Markdown code block
Terminal UI	TUI version via Textual — core features, no browser needed

---

LLM Integration

ArtScii ships with support for Bonsai 1.7B, a 1.58-bit ternary model (~400–700 MB). It runs entirely on CPU — no GPU, no Ollama, no external server.

The LLM uses a hybrid pipeline:

"Create a banner for 'SB Tech' with a double border"
          │
          ▼
    Bonsai 1.7B  (intent parsing)
    → { type: "banner", text: "SB Tech", font: "big", border: "double" }
          │
          ▼
    pyfiglet engine  (precise rendering)
          │
          ▼
    Clean, aligned ASCII art

For freeform requests ("draw a house", "make a skull") the model generates raw ASCII directly.

---

Requirements

• Python 3.10+
• Windows, macOS, or Linux
• ~1 GB free disk space (for the model)

---

Setup

1 — Install core dependencies

pip install -r requirements.txt

2 — Install the LLM runtime

python setup_llm.py

This installs llama-cpp-python using pre-built CPU wheels — no compiler or MSVC required. Falls back to a source build if no wheel is available for your Python version.

3 — Download the model (one time)

python download_model.py

Downloads Bonsai 1.7B (ternary GGUF) from prism-ml/Ternary-Bonsai-1.7B-gguf into the models/ folder. The model is not committed to this repo — you download it once and it stays local.

Skipping the LLM? Steps 2 and 3 are optional. Everything except the AI tab works without any model.

---

Usage

# Web dashboard (opens at http://127.0.0.1:5000)
python run.py

# Web dashboard + auto-open browser
python run.py --open

# Terminal UI
python run.py --tui

# Custom port
python run.py --port 8080

Web dashboard

Once running, open http://127.0.0.1:5000 in any browser.

Tab	How to use
Text	Type text, pick a font from the visual browser (★ to favourite, double-click to generate), choose border/padding/title, hit Generate
AI	Click Load in the top bar, type a natural language prompt, Ctrl+Enter
Image	Drop an image, pick a mode (grayscale / colour / half-block / braille), tune brightness · contrast · gamma, enable Auto-update to preview live
Library	Search 220+ templates, hover to preview, click to insert · switch to Symbols for single characters
Edit	Select text and apply colours, or recolour everything with gradients / rainbow · flip, align, shift, find & replace
Files	Save named versions to the gallery, import .txt, export TXT / HTML / ANS / PNG

The canvas is fully editable — click anywhere and type. Everything autosaves to your browser and is restored next visit.

Keyboard shortcuts: Ctrl+Z/Y undo/redo · Ctrl+Enter generate · Ctrl+S save to gallery · Alt+1–6 switch tabs · ? help overlay

Terminal UI

Ctrl+G   Generate from text input
Ctrl+L   Generate with LLM
Ctrl+E   Export to exports/art.txt
Ctrl+R   Random font
Q        Quit

---

Project structure

ArtScii/
├── app/
│   ├── ascii_engine.py   # text → ASCII (pyfiglet), image → ASCII (4 modes), borders
│   ├── ansi.py           # ANSI escape codes, 16-colour palette, HTML conversion
│   ├── llm.py            # Bonsai GGUF wrapper (llama-cpp-python), hybrid pipeline
│   ├── server.py         # Flask REST API
│   └── tui.py            # Textual terminal UI
├── web/
│   ├── index.html        # Dashboard
│   ├── style.css         # Themeable terminal UI (6 themes)
│   ├── templates.js      # 220+ templates, 420+ symbols
│   └── app.js            # Frontend logic
├── models/               # GGUF model lives here (not committed)
├── exports/              # Exported art lands here (not committed)
├── download_model.py     # One-time model download from HuggingFace
├── setup_llm.py          # llama-cpp-python installer
├── requirements.txt      # Core Python dependencies
└── run.py                # Entry point

---

API endpoints

The Flask server exposes a small REST API, useful if you want to script or extend ArtScii.

Method	Path	Body	Description
GET	/api/fonts	—	List all available pyfiglet fonts
POST	/api/fonts/preview	{fonts[], text}	Render sample text in up to 80 fonts
GET	/api/palette	—	ANSI 16-colour palette
GET	/api/meta	—	Available charsets and border styles
POST	/api/generate/text	{text, font, border, width, centered, padding, title}	Text → ASCII
POST	/api/generate/image	{image (base64), mode, width, char_set, custom_chars, invert, dither, brightness, contrast, gamma}	Image → ASCII. mode: plain / color / halfblock / braille; colour modes also return html
POST	/api/art/border	{art, style, padding, title}	Add border to existing art
POST	/api/llm/load	—	Start loading the LLM model
GET	/api/llm/status	—	Model status (not_loaded / loading / ready / error)
POST	/api/llm/generate	{prompt}	Generate art from natural language
POST	/api/export	{art, format}	Export art (txt / html / ans)

---

Dependencies

Package	Purpose	Licence
Flask	Web server	BSD-3
pyfiglet	ASCII fonts	MIT
Pillow	Image → ASCII conversion	HPND
Textual	Terminal UI framework	MIT
Rich	Terminal rendering	MIT
llama-cpp-python	GGUF model inference	MIT
huggingface-hub	Model download	Apache-2.0

---

Licence

MIT