Metadata-Version: 2.4
Name: jitto
Version: 0.2.0
Summary: A universal AST to x86-64 & ARM64 machine code JIT compiler engine for Python language creators
Author-email: Bennnto <ben.promkaew@icloud.com>
License: MIT
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Compilers
Requires-Python: >=3.11
Description-Content-Type: text/markdown

# jitto 🚀

**`jitto`** is a lightweight, zero-dependency Universal Just-In-Time (JIT) Compilation Engine for Python language creators, interpreters, and compilers.

It was created to power custom programming languages—such as **`new_eval`**—by ingesting their AST nodes and compiling them directly into **native ARM64 (Apple Silicon) and 64-bit x86 (Intel/AMD) machine code** for hardware-speed execution.

---

## Key Features

- **Universal AST Agnostic**: Ingests AST nodes from custom language parsers (like `new_eval`) without requiring custom glue code.
- **Multi-Architecture Support**: Automatically detects and emits native **ARM64 (AArch64)** or **x86-64** machine code instructions.
- **Zero External Dependencies**: Uses pure Python built-in modules (`mmap`, `ctypes`, `struct`).
- **Variable Scope Binding**: Evaluates expressions with dynamic variable environment dictionaries (`variables={"x": 10}`).
- **Thread-Safe Memory Allocation**: Verified under concurrent multi-threaded JIT compilation workloads.

---

## Installation

```bash
pip install jitto
```

Or for local development:

```bash
pip install -e .
```

---

## Quickstart

### 1-Liner JIT Execution

```python
import ast
from jitto import run_jit

# Compiles AST directly to native machine code & executes on CPU hardware
result = run_jit(ast.parse("100 - (15 * 4)", mode="eval"))
print("JIT Execution Result:", result)  # Outputs: 40
```

---

## Universal AST Examples

### 1. Integration Example: Giving `new_eval` a Native JIT Compiler

If your custom language (like `new_eval`) uses `@dataclass` nodes or custom parser objects:

```python
from dataclasses import dataclass
from jitto import run_jit

# AST nodes from the new_eval language parser
@dataclass
class Int_Node:
    value: int

@dataclass
class BinOps_Node:
    left: any
    ops: str
    right: any

# new_eval AST: 10 + (20 * 3)
new_eval_ast = BinOps_Node(
    left=Int_Node(10),
    ops="+",
    right=BinOps_Node(left=Int_Node(20), ops="*", right=Int_Node(3))
)

# Run new_eval AST natively on hardware CPU!
result = run_jit(new_eval_ast)
print("new_eval JIT Execution Result:", result)  # Outputs: 70
```

### 2. JSON / Dictionary AST

```python
from jitto import run_jit

dict_ast = {
    "type": "BinOp",
    "op": "*",
    "left": {
        "type": "BinOp",
        "op": "+",
        "left": {"type": "Constant", "value": 5},
        "right": {"type": "Constant", "value": 15}
    },
    "right": {"type": "Constant", "value": 4}
}

result = run_jit(dict_ast)
print("Dict AST JIT Result:", result)  # Outputs: 80
```

### 3. Variable Environment Bindings

```python
import ast
from jitto import run_jit

# Evaluates (a + b) * (c - d) natively on CPU hardware
ast_tree = ast.parse("(a + b) * (c - d)", mode="eval")
variables = {"a": 5, "b": 5, "c": 20, "d": 10}

result = run_jit(ast_tree, variables=variables)
print("Variable JIT Result:", result)  # Outputs: 100
```

---

## Compiler Architecture

```
┌──────────────────────────────────────────────────────────────┐
│                    Universal AST Inputs                      │
│                                                              │
│  - Python ast.parse()  - Dataclasses (new_eval)  - Dicts     │
└──────────────────────────────┬───────────────────────────────┘
                               │
                               ▼
┌──────────────────────────────────────────────────────────────┐
│                  Universal AST Normalizer                    │
│                                                              │
│  Standardizes arbitrary AST node fields into internal nodes  │
└──────────────────────────────┬───────────────────────────────┘
                               │
                               ▼
┌──────────────────────────────────────────────────────────────┐
│             3-Address Intermediate Code (IR)                 │
│                                                              │
│  Linearizes AST into LOAD_IMM, ADD, SUB, MUL & Register Alloc│
└──────────────────────────────┬───────────────────────────────┘
                               │
                               ▼
┌──────────────────────────────────────────────────────────────┐
│         Multi-Arch Machine Code Encoder (ARM64 / x86-64)      │
│                                                              │
│  Emits 64-bit CPU binary opcodes (MOVZ, ADD, SUB, MUL, RET)  │
└──────────────────────────────┬───────────────────────────────┘
                               │
                               ▼
┌──────────────────────────────────────────────────────────────┐
│             Native RWX Memory Executor (mmap + ctypes)       │
│                                                              │
│ Executes machine bytes natively on CPU via function pointers │
└──────────────────────────────────────────────────────────────┘
```

---

## Testing & Stability

`jitto` passes 5 comprehensive test suites comprising 22 test cases and over **1,600 continuous JIT executions**:

- **ARM64 & x86-64 Code Emission**: Verified on macOS Apple Silicon, Intel Mac, and Linux.
- **Signed 64-Bit Boundaries**: Verified for negative returns (`-40`) and large integers (`6,000,000,000`).
- **Multi-Threaded Concurrency**: Verified across 10 concurrent threads with 500 parallel compilations.
- **Deep AST Trees**: Verified 30-level deep expression trees.

---

## License

[MIT](LICENSE)
