VQL - Visual Query Language

before

uri2vql pipeline-analyze --image /tmp/screen.png --out app.vql.json --llm

after

uri2vql vql-to-image --program app.vql.json --out app.render.png

VQL objects app.vql.json

{
"version": "1.0",
"render_target": "svg",
"scene": {
"width": 2560.0,
"height": 1600.0,
"background": "#FFFFFF",
"url": "file:///tmp/screen.png",
"app": "desktop",
"layers": [
{
"id": "screen_regions",
"objects": [
{
"id": "region_000",
"primitives": [
{
"shape_type": "rectangle",
"params": {
"width": 213.0,
"height": 133.0
}
}
],
"style": {
"color": "#2F342E",
"fill": true,
"stroke_width": 0.0,

AI Cost Tracking

• 🤖 LLM usage: $11.5573 (8 commits)
• 👤 Human dev: ~$659 (6.6h @ $100/h, 30min dedup)

Generated on 2026-06-24 using openrouter/qwen/qwen3-coder-next

---

VQL (Visual Query Language) — język wektorowego opisu fotografii, rysunków i zrzutów ekranu.

Samodzielna paczka Python z IR (VQLProgram), kompilatorem NL→VQL, walidacją i rendererami SVG/PNG. Sterowana przez DSL i bus CQRS/ES w paczkach *2vql.

Ekosystem: SUMD (opis) → DOQL (deklaracja) → Makefile/taskfile (automation) → testql (weryfikacja)

Dokumentacja:docs/README.md · Przykłady:examples/README.md · SUMD:SUMD.md

Instalacja

pip install vql # core
pip install vql[png] # eksport PNG (cairosvg)
pip install vql[desktop] # zrzut ekranu (pillow, mss)
bash install-dev.sh # pełny stack dev

Szybki start — rysowanie

fromvqlimportnl_to_program, render_to_svgprogram=nl_to_program("narysuj czerwone koło", width=400, height=400)
svg=render_to_svg(program)

dsl2vql -c 'COMPILE "narysuj niebieski kwadrat"'
rest2vql serve --port 8216

Szybki start — zrzut ekranu → VQL

# Automatyzacja LLM: vdisplay → imgl (bez dialogu GNOME, gdy mirror działa)
imgl capture -o /tmp/screen.png --verify --analyze --lang eng+pol
# Alternatywa: portal GNOME (docs/desktop-capture.md)
uri2vql capture-screen --interactive --out /tmp/screen.png
# All-in-one
uri2vql capture-and-analyze --out app.vql.json --diagnose
# Lub krok po kroku
uri2vql analyze-window --image /tmp/screen.png --out app.vql.json --grid 12
uri2vql adopt-ui --image /tmp/screen.png --out ui.vql.json --locale pl
uri2img2svg query "img2svg://svg?path=/tmp/screen.png&out=/tmp/screen.svg"
uri2vql query "vql://window/summary?file=app.vql.json&live=1&image=/tmp/screen.png"

Pełny skrypt: bash examples/full-pipeline.sh

Fotografia ↔ VQL (roundtrip)

Opis z obrazu i odtworzenie z metadanych — zależnie od typu obrazu:

# Test roundtrip (próbki + raport fidelity)
python examples/photo-roundtrip-test.py
make test-roundtrip
# Opis mozaiką kolorów
img2svg vql photo.png --out photo.vql.json --grid 20
# Wektoryzacja kolorowa (lepsza dla płaskich kształtów)
pip install 'img2svg[vtracer]'
img2svg vql photo.png --out photo.vql.json --method vtracer
# Odtworzenie
python -c "from vql import VQLProgram, render_to_pngimport jsonp = VQLProgram.from_dict(json.load(open('photo.vql.json')))render_to_png(p, 'reconstructed.png')"

Macierz jakości i biblioteki: docs/photo-roundtrip.md

Interfejsy

Warstwa	Window / screenshot	SVG
CLI	uri2vql, img2vql	img2svg, uri2img2svg, dsl2img2svg
URI	vql://window/*	img2svg://vectorize|svg|vql
REST	POST /v1/window/* :8216	planowane
MCP	vql_detect_ui, vql_diagnose_window, …	—

REST: docs/rest-window-api.md · URI: docs/window-uri.md · SVG: docs/img2svg-uri.md

Desktop adopt + img2nl

Etap	Narzędzie	Co robi
Capture	imgl capture (vdisplay) / uri2vql capture-screen	PNG + provenance / portal
Grid adopt	analyze-window	scalone regiony + fingerprint
UI detect	img2vql / adopt-ui	okna, przyciski, bbox, relations
Wektoryzacja	img2svg / uri2img2svg	PNG → SVG / VQL
Diagnose	diagnose-window	routing LLM + auto-OCR
Compare	compare-window	phash — zmiana ekranu?
OCR semantyczny	adopt-imgl / imgl	tekst + role + interakcja

Pipeline: docs/window-pipeline.md · LLM capture: docs/vdisplay-imgl-automation.md · Portal: docs/desktop-capture.md

Przykłady

bash examples/live-capture-test.sh
bash examples/full-pipeline.sh
bash examples/img2nl-vql-flow.sh /tmp/screen.png
VQL_TEST_IMAGE=/tmp/screen.png bash examples/full-pipeline.sh

Development

make install-dev # pełny stack *2vql
make test# pytest core + dsl2vql
make test-all # wszystkie pakiety
make serve # rest2vql :8216
make goal # test + commit + publish (goal.yaml)
bash project.sh # SUMD + DOQL + testql + analiza

Zmienne LLM: skopiuj .env.example → .env (OPENROUTER_API_KEY, LLM_MODEL).

Struktura monorepo

src/vql/ — domena (schema, compiler, renderers, adopt/window)
packages/
dsl2vql/ uri2vql/ nlp2vql/ cli2vql/ rest2vql/ mcp2vql/
img2vql/ — detekcja UI + img2nl diagnose (v0.2)
img2svg/ — obraz → SVG / VQL (v0.1)
uri2img2svg/ — img2svg:// URI (v0.1)
dsl2img2svg/ — VECTORIZE / TO_VQL DSL (v0.1)
docs/ — dokumentacja
examples/ — skrypty demo (README w examples/)
testql-scenarios/ — kontrakty testql (CLI, pytest)

Skala (SUMD): 151 modułów · 278 funkcji · ~12.5k LOC · CC̄=4.2

Szczegóły: packages/README.md · docs/packages.md

Status

• TODO.md — checklist + analiza
• CHANGELOG.md — historia zmian
• SUMD.md — auto-opis projektu (DOQL, testql, call graph)

License

Licensed under Apache-2.0.