Metadata-Version: 2.4
Name: ragl-lang
Version: 0.3.0
Summary: RAGL — a memory-safe, flexible-syntax, AI-native programming language
Author-email: Ragulraj Dhamodharan <rag@shivoraa.in>
License: MIT
Project-URL: Homepage, https://shivoraa.in
Project-URL: Documentation, https://github.com/ragulraj/ragl/tree/main/docs
Project-URL: Source, https://github.com/ragulraj/ragl
Project-URL: Issues, https://github.com/ragulraj/ragl/issues
Keywords: ragl,programming-language,interpreter,compiler,ai-native,flexible-syntax,dsl
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Compilers
Classifier: Topic :: Software Development :: Interpreters
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: ai
Requires-Dist: anthropic>=0.40; extra == "ai"
Provides-Extra: crypto
Requires-Dist: cryptography>=42.0; extra == "crypto"
Requires-Dist: bcrypt>=4.0; extra == "crypto"
Provides-Extra: all
Requires-Dist: anthropic>=0.40; extra == "all"
Requires-Dist: cryptography>=42.0; extra == "all"
Requires-Dist: bcrypt>=4.0; extra == "all"
Dynamic: license-file

<p align="center">
  <img src="assets/ragl-logo.svg" alt="RAGL" width="140">
</p>

<h1 align="center">RAGL</h1>

<p align="center">
  <em>Ragulraj's Advanced General Language</em><br>
  <strong>One language. Every domain.</strong>
</p>

<p align="center">
  language <code>1.0</code> · compiler <code>0.1.0</code> · runtime <code>0.1.0</code> · IR <code>1</code><br>
  Created by Ragulraj Dhamodharan · Shivoraa
</p>

---

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.

```ragl
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

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

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

```sh
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

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

```
Hello World
```

## Plain English

Ordinary statements have an English form — no operators needed:

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

```ragl
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"
```

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

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

```sh
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

```ragl
# 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/`](examples) and
[`tests/`](tests/test_ragl.py).

## Examples

```sh
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 |
|---|---|
| [01 — Language Specification](docs/01-language-specification.md) | the normative language reference |
| [02 — Compiler](docs/02-compiler.md) | lexer, intent resolver, parser, IR, checker |
| [03 — Runtime](docs/03-runtime.md) | execution, memory, concurrency, security, objects |
| [04 — Standard Library](docs/04-standard-library.md) | every module and phrase |
| [05 — Package Manager](docs/05-package-manager.md) | packages, resolution, versioning |
| [06 — AI Engine](docs/06-ai-engine.md) | providers, agents, non-goals |
| [07 — Errors](docs/07-errors.md) | the full diagnostic catalogue |
| [08 — Grammar](docs/08-grammar.ebnf) | formal EBNF |
| [09 — Scope](docs/09-scope.md) | what RAGL is, and what it deliberately is not |
| [10 — Roadmap](docs/10-roadmap.md) | versioning, plan, governance |
| [11 — AI for your users](docs/11-ai-for-your-users.md) | 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](docs/09-scope.md).

## Publishing (maintainer)

```sh
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
