What Jaithon is

Jaithon is a dynamically executed and garbage collected language with a bytecode VM. It takes heavy insp from the structure from Java (for its architecture) and insp for everything else from a combination of Rust & Python.

Pretty much everything (apart from the CORE primitive implementation stuff) is written in jaithon itself, making it VERY much bootstrapped and easy to extend with new features.

AI Usage

Most documentation within .jai and .c files is currently AI-generated to speed up development, though it is being rewritten as the language evolves. The README and most of LANGUAGE.md are hand-written, thoroughly reviewed, and are currently 100% accurate. Docstrings in the code may still be inaccurate, as they were generated by an LLM.

Additionally, around 80% of the raw code in this repository was produced with agentic coding tools (claude code). My workflow is to first design a feature or bug fix completley by hand, then use an LLM to help either finish it, integrate it with the codebase, catch additioal bugs before I push, improve performance, or correct me on bad assumptions. The resulting code is something I completley understand and something that I stand by, and something that belongs to me.

The architecture is also 100% my own, 100% human generated, and not AI assisted.

I see agent-assisted coding as the future of software engineering. It let me build Jaithon 3 far faster than I could have done alone, while still keeping a real human in the loop for the important decisions. Without agentic coding, Jaithon 3 probably wouldnt have existed, and Jaithon would have been stuck at a primal level. The entire codebase is reviewed by me and I would not consider myself a "vibecoder", or jaithon as "ai slop"; it is collaborative engineering with LLMs used as a multiplier to exponentiate my productivity.

Quick start

git clone https://github.com/abhiramasonny/jaithon
cd jaithon
make                        # builds ./jaithon
make test                   # this is optional, but it runs the benchmarks and tests and stuff
./scripts/install.sh        # also optional, it installs itself to /usr/local

The reqs to run jaithon are a C11 compiler and make, readline is used for the REPL if present. On macOS the Metal and Cocoa frameworks enable the GUI and GPU modules, however everything else builds and runs without them.

jaithon run program.jai     # run a file
jaithon                     # REPL
jaithon check src/          # type-check without running
jaithon fmt .               # canonical formatter, no options
jaithon test                # discover and run tests
jaithon doc --out docs/api  # generate API documentation
jaithon disasm program.jai  # bytecode listing

The REPL keeps its bindings across lines, continues an unfinished input on a ... prompt, and takes meta-commands. :help lists every one of them.

Examples of .jai Code

# let is immutable but var is not and const is compile time
let name = "Jaithon"
var count = 0
const MAX = 1 << 16

# types are optional, but they are checked if they are present
let ratio: float = 0.5
let names: list[str] = []
let lookup: dict[str, int] = {}
let maybe: int? = null           # T? is T | null

if names.len() > 0 { print(names[0]) }
print(maybe ?? -1)

# loops and ranges
for i in 0..10 { count += i }
'outer: for row in grid {
    for cell in row {
        if cell == target { break 'outer }
    }
}

# pattern matching
let kind = match code {
    200           => "ok",
    301 | 302     => "redirect",
    400..=499     => "client error",
    n if n >= 500 => "server error",
    _             => "unknown",
}

enum Shape {
    Circle(radius: float),
    Rect(w: float, h: float),
}

fn area(s: Shape) -> float {
    return match s {
        Shape.Circle(r)  => math.PI * r ** 2,
        Shape.Rect(w, h) => w * h,
    }
}

# traits are interfaces with default methods, and they are types.
trait Printable {
    fn to_str(self) -> str
    fn describe(self) -> str { return f"<{self.to_str()}>" }
}

# Errors are classes
fn load(path: str) -> str {
    let file = io.open(path, "r")
    defer { file.close() }
    return file.read()
}

# comphressons and lazy iterators.
let squares = [x ** 2 for x in 0..10 if x % 2 == 0]
let first_ten = iter(source).map(parse).filter(is_valid).take(10).collect()

# ML Training
import jaitensor as jt

@trace
fn logits(x: Tensor[float, 32, 10]) -> Tensor[float, 32, 10] {
    return x
}

let model = jt.Sequential([
    jt.Conv2d(16, 3, padding: 1),
    jt.Flatten(),
    jt.Dense(10, activation: jt.Activation.Softmax),
])
model.compile(jt.Adam(), mixed_precision: true)
model.fit(data, epochs: 5, batch_size: 512, shuffle: true)

more idepth file -> LANGUAGE.md. The ML type and runtime contracts are in spec/ml.md.

Also you can checkout the examples directory.

Packages

Libraries that can ship outside the Jaithon standard library can be found under packages/. Each package owns its source, tests, version, and dependency manifest. Jaithon finds workspace packages from a checkout and from an installed share/jaithon/packages directory.

jaicv is computer vision with OpenCV's API, on the GPU: Mat on a Metal buffer, imgproc, codecs, camera capture and AVI writing, windows, contours and shape analysis, features, optical flow and background subtraction, calibration, denoising, and classical machine learning. Around seven hundred recorded cases are replayed against the real OpenCV to keep it honest; see packages/jaicv/README.md for what matches exactly and what does not.

jaiframe is columnar data frames with pandas' API, on the GPU: typed nullable Column lanes on a Metal buffer, one Index class covering range, plain and multi-indexes, selection and alignment, arithmetic, missing data, reductions and rolling windows, group-by, joins, reshaping, timeseries, and CSV and JSON. Integers and timestamps are stored across two float32 lanes and are exact to 48 bits, and text is dictionary-encoded so a string key hashes and joins like a number; see packages/jaiframe/README.md for what that buys and what it costs.

jainum is n-dimensional arrays with numpy's API, on the GPU: NDArray as a strided window onto a Metal buffer, dtypes as semantic tags over float32 storage, broadcasting, ufuncs, reductions, sorting, linear algebra, FFTs, random numbers, and statistics. Indexing takes an int, a range, a Slice or a sentinel rather than slice syntax; see packages/jainum/README.md for why, and for what numpy has that this does not.

jaiplot is a library for Matplotlib-style figures and axes with file and window backends.

jaisci is scientific computing with scipy's API: optimisation and root finding, least squares and curve fitting, linear programming, quadrature and initial value problems, interpolation and splines, FFTs and spectral estimates, filter design, convolution, sparse matrices and Krylov solvers, distributions, hypothesis tests, and spatial structures. It obeys two rules throughout — host arithmetic in float64 and device arithmetic in float32, so small dense work stays on the host, and only quadratic-and-up work becomes a Metal kernel. See packages/jaisci/README.md.

jaitensor is GPU-first training: Metal-resident tensors, autograd, and a Keras-style Sequential API. Dense, conv, norm, and attention layers, mixed precision compute, a GPU DataLoader, SGD and Adam, validation, prediction, and JSON weight files. The examples cover MNIST, Fashion-MNIST, and a nonlinear spiral classifier.

Errors

Every error is in this format, so hopefully its easy to debug

error[E0301]: cannot assign to immutable binding `x`
  --> examples/demo.jai:7:5
   |
 5 | let x = 1
   |     - `x` declared immutable here
 ...
 7 |     x = 2
   |     ^^^^^ assignment to immutable binding
   |
help: change the declaration to `var x = 1`

These are what the codes mean:

---

Architecture

source --> lexer --> parser --> resolver --> type checker --> codegen --> VM
            |         │           │              │               │         │
          tokens     AST      symbols +      types +          bytecode   values
                               slots          shapes          + JIT      + GC
                                              + casts         + @trace   + GPU

Contributing

make debug            # -O0 -g, assertions on
make check            # type-check the whole tree
make test             # full suite
make bootstrap        # differential front-end verification
jaithon fmt --check . # formatting gate

License

MIT. See LICENSE.

Created by Abhirama Sonny.