Ragul

A pipeline scripting language where transformation is built into the syntax itself. Each word is a suffix chain — a left-to-right pipeline stacked onto a root value. Inspired by the structural principles of agglutinative grammar (Hungarian).

data-into  [7, 2, 15, 3, 9, 1, 12, 4]-it.
result-into  data-unique-sorted-5-above-it.
result-print-doing.
// [7, 9, 12, 15]

📖 Full documentation →

Install

pip install ragul-lang

Requires Python 3.11+.

To also enable AI-assisted error explanations:

pip install ragul-lang[ai]

What is this? When Ragul finds a type error in your code, this optional feature sends the error and the relevant source lines to Claude (an AI assistant by Anthropic) and prints a plain-English explanation of what went wrong and how to fix it.

This is completely optional and nothing is ever sent automatically. To activate it, set your own ANTHROPIC_API_KEY environment variable — a personal access token you create at console.anthropic.com. Ragul never stores or logs your key; it is sent directly to Anthropic's API only when a diagnostic fires. Without the key, the compiler works identically with no network calls whatsoever.

Or install from source:

git clone https://github.com/kory75/ragul.git
cd ragul
pip install -e ".[dev]"        # toolchain + dev tools
pip install -e ".[ai,dev]"     # + AI support

Quick Start

# Run a program
ragul run hello.ragul

# Type-check without running
ragul check hello.ragul

# Interactive REPL
ragul repl

# Start the LSP server (for editor integration)
ragul lsp

# Scaffold a new project
ragul new project myapp

Hungarian primary names (futtat, ellenőriz, repl, új) are also accepted.

Examples

Hello World

program-ours-effect
    greeting-into  "Hello, World!"-it.
    greeting-print-doing.

Arithmetic pipeline

program-ours-effect
    x-into  10-it.
    y-into  x-3-add-2-mul-it.   // (10 + 3) × 2 = 26
    y-print-doing.

Filter and sort a list

program-ours-effect
    data-into    [7, 2, 15, 3, 9, 1, 12, 4]-it.
    result-into  data-unique-sorted-5-above-it.
    result-print-doing.
// [7, 9, 12, 15]

Define and call a custom suffix

// Define -double as a reusable suffix
double-ours
    num-yours.
    num-num-add-it.

program-ours-effect
    x-into  7-it.
    y-into  x-double-it.    // 14
    y-print-doing.

Conditionals

classify-ours-if
    num-yours.
    num-100-above-if
        "large"-it.
    -else-if  num-50-above-if
        "medium"-it.
    -else
        "small"-it.

program-ours-effect
    category-into  75-classify-if-it.
    category-print-doing.
// medium

Loops

// Sum a list using fold
summer-ours-fold
    item-yours.
    total-yours.
    total-item-add-it.

program-ours-effect
    list-into    [1, 2, 3, 4, 5]-it.
    result-into  list-summer-fold-it  0-with.
    result-print-doing.
// 15

Date and time

program-ours-effect
    now-into   0-now-it.

    // Format with PHP-style codes
    iso-into   now-dateformat-it  "Y-m-d H:i:s"-with.
    long-into  now-dateformat-it  "l, F j, Y"-with.
    iso-print-doing.     // 2026-03-22 09:05:07
    long-print-doing.    // Sunday, March 22, 2026

    // Arithmetic
    nextweek-into  now-7-adddays-it.
    nw-into  nextweek-dateformat-it  "Y-m-d"-with.
    nw-print-doing.      // 2026-03-29

    // Parse a date string
    parsed-into  "2000-01-01"-parse-it  "Y-m-d"-with.
    yr-into      parsed-year-it.
    yr-print-doing.      // 2000

Error handling

program-ours-effect
    content-into  "data.txt"-filein-it-?.
    content-print-doing.
    -catch
        hiba-print-doing.

What's in v0.3.2

Architecture

ragul/
├── model.py          # Word, Sentence, Scope, RagulType + alias table
├── lexer.py          # Tokeniser with alias normalisation at lex time
├── parser.py         # Two-pass: word construction + scope tree assembly
├── typechecker.py    # Static type checker, E001–E009, W001
├── interpreter.py    # Tree-walking interpreter
├── errors.py         # Structured error types and formatters
├── config.py         # ragul.config TOML loader
├── main.py           # CLI entry point
├── stdlib/
│   ├── core.py       # Arithmetic, comparison, logical, string concat
│   ├── modules.py    # matematika, szöveg, lista, adatok, minta modules
│   ├── screen.py     # képernyő — terminal I/O (5 suffixes)
│   ├── time.py       # idő — timing (-sleep)
│   └── datum.py      # dátum — date/time (15 suffixes)
├── agents/
│   ├── orchestrator.py   # Coordinates the pipeline; Claude AI error analysis
│   ├── task.py           # Task / TaskResult message protocol
│   └── ...               # LexerAgent, ParserAgent, TypeAgent, InterpAgent, ...
├── repl/
│   └── repl.py       # Interactive REPL
└── lsp/
    └── server.py     # pygls LSP server

Running Tests

pytest ragul/tests/ -v

With type checking:

python -m mypy ragul/ --ignore-missing-imports

Suffix Alias Quick Reference

Each suffix has a canonical Hungarian form plus English and symbolic aliases:

REPL

ragul repl

>>> x-into  3-it.
>>> y-into  x-double-it.
>>> y-print-doing.
6
>>> :show
x = 3  (Szám)
y = 6  (Szám)
>>> :exit

ragul.config

Place at your project root:

[projekt]
nev     = "my-project"
verzio  = "0.1.0"
belepes = "main.ragul"

[ellenorzes]
harmonia = "warn"   # "warn" | "strict" | "off"
tipus    = "warn"   # "warn" | "strict" | "off"

License

Apache 2.0 — see LICENSE for the full text.