RAGL

Ragulraj's Advanced General Language
One language. Every domain.

language 1.0 · compiler 0.1.0 · runtime 0.1.0 · IR 1
Created by Ragulraj Dhamodharan · Shivoraa

---

RAGL is a memory-safe, dynamically typed, flexible-syntax language with a batteries-included standard library and a first-class AI engine.

Flexible syntax means many surface forms, one canonical meaning — every dialect is a deterministic rewrite to the same AST. RAGL has a formal grammar, a static checker, structured diagnostics and a conformance suite, and ragl explain will show you exactly what your program became.

create variable name with value "Ragulraj"     # all six of these
set name to "Ragulraj"                         # produce exactly
let name be "Ragulraj"                         # the same node:
name is "Ragulraj"                             #
name → "Ragulraj"                              #   Assign(name, 'Ragulraj')
name = "Ragulraj"                              #

---

Install

pip install ragl-lang            # the CLI is `ragl`

Note on the name: pip install ragl installs an unrelated retrieval-augmented-generation library that already owns that name on PyPI. The distribution here is ragl-lang; the import name and command are both ragl.

Optional extras:

pip install "ragl-lang[ai]"      # real model access for the `ai` phrases
pip install "ragl-lang[crypto]"  # AES-256-GCM and bcrypt (both have fallbacks)
pip install "ragl-lang[all]"

From source:

git clone https://github.com/ragulraj/ragl && cd ragl
pip install -e .
python -m unittest discover -s tests

Requires Python 3.9+. No mandatory dependencies.

Hello, RAGL

echo 'say "Hello World"' > hello.ragl
ragl run hello.ragl

Hello World

Plain English

Ordinary statements have an English form — no operators needed:

total = 10
add 5 to total              # total = total + 5
increase total by 100
decrease total by 15
multiply total by 2
divide total by 4
subtract 25 from total

if basket is empty
    say "nothing here yet"
end

Vibe coding with @ai, fenced off

Every other line in RAGL is deterministic. @ai is the one marked exception:

name = "priya"
scores = [72, 88, 95]

@ai greet the person by name, warmly

@ai
    work out the average of the scores
    print it rounded to one decimal place
end

say "back to ordinary RAGL"

ragl run app.ragl --ai anthropic --show-ai

The generated RAGL is cached beside your program in .ragl-ai-cache.json, so the model is asked once: later runs are identical, free and offline, and what the model wrote is a file you can read, diff and commit. Generated code is parsed before it runs — if it does not parse you get RGL6001, never a silent failure. On the offline engine @ai refuses rather than guessing.

The command line

Command	What it does
ragl run app.ragl	check, then run
ragl check app.ragl	diagnostics without running
ragl explain app.ragl	print the canonical IR
ragl repl	interactive session
ragl modules	built-in modules and their capabilities
ragl install ./lib · ragl list · ragl uninstall lib	packages
ragl ai ask "…" · generate · explain · fix	talk to the AI engine
ragl config show · config set api_key …	settings, including the AI key
ragl editor	install editor support into VS Code / Cursor / VSCodium
ragl version	all four version surfaces

Capabilities are granted, not assumed:

ragl run app.ragl --allow files            # files only
ragl run app.ragl --allow files,network
ragl run app.ragl --allow ""               # pure computation

Editor support

The VS Code extension ships inside the package, so it stays in step with the version you installed — no marketplace round trip:

pip install ragl-lang
ragl editor                 # detects VS Code, Cursor, VSCodium, Windsurf

Reload your editor and you get:

• ▶ Run button on the editor toolbar (also F5)
• Live error squiggles as you type, with the code, suggestion and docs link
• Autocomplete — keywords, block snippets, library phrases
• Hover docs on any keyword
• AI commands — ask a question, write a program, explain this code, fix this file, plus "Fix with RAGL AI" as a quick-fix on any error
• Syntax highlighting, ⌘/ comments, auto-indent, and the RAGL tab icon

For the icon in the file explorer, run Preferences: File Icon Theme → RAGL.

ragl editor uninstall removes it; ragl editor path prints where the extension lives.

A tour

# Conditions in three dialects, one meaning
if age is greater than 18
    say "Adult"
otherwise
    say "Minor"
end

say "Adult" if age > 18

# Loops with skip / stop / retry
for each item at index in ["red", "green", "blue"]
    skip if item is "green"
    say "{index}: {item}"
end

# Functions, defaults, lambdas, closures
define greet with who, greeting = "Hello"
    return "{greeting}, {who}!"
end
double = value → value * 2

# The full object model
interface Shape
    needs area
end

abstract class Figure implements Shape
    has name
    has private id
    shared created = 0
    define area
        return 0
    end
end

class Circle extends Figure
    has radius
    create with radius
        super create with "Circle"
        self.radius = radius
    end
    define area
        return PI * self.radius * self.radius
    end
    define text
        return "Circle(r={self.radius})"
    end
end

c = new Circle(2)
say c.area                # 12.56636 — a zero-parameter method reads as a property
say c is a Shape          # true
say c                     # Circle(r=2)

# Files
write to file "notes.txt" with "Hello RAGL"
say read file "notes.txt"

# A real database
connect to database "app.db"
create table Users with
    id auto increment primary
    name text required
    email text unique required
end
insert into Users
    name = "Ragulraj"
    email = "rag@shivoraa.in"
end
say get from Users where name == "Ragulraj"

# Security, with the construction documented
hashed = hash "myPassword" using bcrypt
say check if "myPassword" matches hashed

# AI — offline by default, so this runs with no key
say ai analyze "I love this product" for sentiment     # positive

# An HTTP API
start server on port 8080
route GET "/"
    send "Welcome to the RAGL API"
end

# Concurrency
run together
    a = secure get "https://example.com/one"
    b = secure get "https://example.com/two"
end

Every snippet above is exercised by examples/ and tests/.

Examples

ragl run examples/01-hello.ragl          # the six dialects
ragl run examples/02-basics.ragl         # types, conditions, loops, functions
ragl run examples/03-collections.ragl    # lists, dicts, sets, stacks, queues
ragl run examples/04-objects.ragl        # the full object model
ragl run examples/05-errors.ragl         # structured errors
ragl run examples/06-files.ragl          # file handling
ragl run examples/07-database.ragl       # SQLite
ragl run examples/08-security.ragl       # hashing, encryption, JWT
ragl run examples/09-ai.ragl             # the AI engine
ragl run examples/10-web.ragl            # page → HTML
ragl run examples/11-server.ragl         # HTTP API (Ctrl-C to stop)
ragl run examples/12-concurrency.ragl    # parallel, background, timers
ragl run examples/13-plain-english.ragl  # @ai — needs --ai anthropic

How it works

source ─▶ lexer ─▶ intent resolver ─▶ parser ─▶ canonical AST ─▶ checker ─▶ interpreter
                   (deterministic,                    │
                    no model call)                    └─ `ragl explain` prints this

The canonical AST is the contract between the front end and the runtime. A bytecode VM can replace the interpreter without changing what any program means.

Documentation

Document	Covers
00 — Syntax Reference	every construct on one page — start here
01 — Language Specification	the normative language reference
02 — Compiler	lexer, intent resolver, parser, IR, checker
03 — Runtime	execution, memory, concurrency, security, objects
04 — Standard Library	every module and phrase
05 — Package Manager	packages, resolution, versioning
06 — AI Engine	providers, agents, non-goals
07 — Errors	the full diagnostic catalogue
08 — Grammar	formal EBNF
09 — Scope	what RAGL is, and what it deliberately is not
10 — Roadmap	versioning, plan, governance
11 — AI for your users	keys, gateways, and what never to publish

What RAGL does not do

RAGL states its boundary rather than implying there isn't one. It has no raw pointers, no manual memory management, no templates, and no multiple implementation inheritance — those contradict its memory-safety guarantee or its dynamic type system. Generators, operator overloading and a bytecode VM are planned, not present. Benchmarks will be published only once the VM exists. Details: docs/09-scope.md.

Publishing (maintainer)

python -m build                  # → dist/ragl_lang-0.1.0-py3-none-any.whl + .tar.gz
python -m twine upload dist/*    # needs your PyPI credentials

License

MIT © 2026 Ragulraj Dhamodharan