# Autolang - Full Documentation for LLMs

> version: 0.0.23 | source: https://autolang.vercel.app/llms-full.txt

An orchestration language designed from the ground up for AI to write correctly the first time - with strict host-governed capabilities.

Autolang is an AI-native orchestration language and deterministic virtual machine. It solves the critical bottleneck of executing untrusted AI-generated code in production. Instead of sandboxing entire operating systems or executing untrusted Python/JavaScript inside full containers, host applications (in Node.js, TypeScript, or C++) expose discrete business capabilities. AI scripts orchestrate those capabilities under strict host authority, explicit memory quotas, and opcode instruction budgets.

---

## Core Philosophy & Positioning

1. **AI is Untrusted:** Treat all generated code as untrusted input. Scripts may contain infinite loops, unauthorized calls, or syntax anomalies.
2. **Authority Belongs to the Host:** Host applications hold all database credentials, sockets, and sensitive tokens. The AI script acts solely as an orchestrator across explicitly registered capabilities.
3. **Surface Match with Kotlin:** Autolang borrows fundamental syntax patterns from Kotlin (`val`, `var`, `if/else`, `when`, `?.`, `arrayOf()`), so models apply a dialect they already know instead of learning a new DSL. A familiar surface reduces syntax drift; it does not replace validation - the compiler still checks every name, type, and capability before execution.
4. **Intentional Scope:** Autolang omits human-scale architectural overhead (interfaces, reflection, coroutines, deep inheritance hierarchies). Orchestration scripts focus strictly on control flow and capability coordination.
5. **Default Deny:** Zero ambient authority. No file I/O, network access, or system primitives exist unless explicitly declared and bound by the host application.
6. **Deterministic and Bounded Execution:** VM instruction budgets prevent runaway loops; managed memory quotas guarantee sub-millisecond cleanups without garbage collection spikes.

---

## 3-Layer Defense Model

```text
AI Model (Untrusted Prompt)
  │
  ▼
[ Layer 1: Compiler & AST Validation ]
  • Strict static type checking and symbol validation
  • Structured compiler diagnostics guide model auto-repair
  • Absorbs common syntax drift at compiler boundary
  │
  ▼
[ Layer 2: Host Capability Allowlist ]
  • Zero ambient authority (Default-Deny)
  • Host exposes discrete business functions via @native / @js_object
  • AI never receives database credentials or raw sockets
  │
  ▼
[ Layer 3: Deterministic VM Runtime ]
  • Opcode instruction budget prevents infinite loops
  • Managed memory quotas bounded by hot-restart arenas
  • Deterministic reference counting (cleanup < 1 ms)
  │
  ▼
Host Business Application (CRM, ERP, Billing, Inventory)
```

---

## Why Autolang Over Sequential Tool Calling

Tool calling functions well for single, isolated queries. When an agent must evaluate hundreds of items, segment records, or run multi-step computations, tool calling incurs significant overhead:

```text
Sequential Tool Calling                 Autolang Orchestration
-----------------------                 ----------------------
LLM -> call tool                        LLM -> generate orchestration script
Host -> return data                     Host VM -> compile and execute locally (<1ms)
LLM -> parse, decide next step          Host VM -> resolves loops, branches, math
LLM -> call tool (repeated N times)     Host VM -> invokes registered capabilities directly
High latency, runaway token costs       Single generation pass, deterministic execution
```

---

## Architecture & Execution Flow

1. **Generation:** The language model receives the prompt along with the host capability signatures and generates an Autolang script.
2. **Compilation:** `ACompiler` compiles the script into bytecode, validating types and resolving symbol references.
3. **VM Execution:** `AVirtualMachine` executes the bytecode within a pre-allocated memory arena and opcode budget.
4. **Capability Invocation:** When the script calls registered capabilities, the VM delegates execution directly to host native callbacks.
5. **Deterministic Teardown:** Upon script completion or error, reference counting and arena reset free all execution memory in under 1 ms.

---

## Security Model & Sandboxing

### Threat Model
Autolang assumes untrusted AI scripts will attempt to:
- Access unexposed system resources or environment variables.
- Run infinite loops or exhaust host CPU resources.
- Allocate unbounded memory to induce host out-of-memory (OOM) crashes.
- Bypass permission boundaries through dynamic code evaluation.

### Language-Level Enforcements
- **No Reflection or Dynamic Eval:** No `eval()`, `Function()`, or runtime symbol mutation.
- **No Unexposed I/O:** File I/O, network sockets, and environment variables do not exist in the language standard library unless host explicitly binds them.
- **No Subprocess Spawning:** The runtime cannot fork processes or access shell primitives.
- **Opcode Instruction Limits:** Configurable opcode cap (e.g. 100,000 opcodes) halts runaway execution instantly.
- **Managed Memory Quotas:** VM allocates objects inside an isolated arena. Host-managed objects remain outside VM accounting.

---

## Quick Syntax Example

```kotlin
@import("inventory")
@import("notifications")

// AI script orchestrating host-registered capabilities
val items = inventory.listCurrentStock()
var restockCount = 0

items.filter {|item| item.quantity < 5}
    .forEach {|item|
        notifications.sendAlert("Ops", "Low stock for " + item.sku)
        restockCount += 1
    }

println("Items flagged for restock: " + restockCount)
```

---

## Host Integration Example (TypeScript / Node.js)

```typescript
import { ACompiler } from 'autolang-compiler';

const compiler = await ACompiler.create();

// Register host capabilities
compiler.registerBuiltInLibrary("inventory", `
    class Product(
        sku: String,
        quantity: Int,
        price: Int
    )

    @js_object
    class InventoryService {
        @native("listCurrentStock")
        fun listCurrentStock(): Array<Product>
    }
`, { autoImport: true }, {
    listCurrentStock: () => inventoryBackend.queryStock()
});

compiler.registerBuiltInLibrary("notifications", `
    @native("sendAlert")
    fun sendAlert(channel: String, msg: String): Bool
`, { autoImport: true }, {
    sendAlert: (channel, msg) => alertService.dispatch(channel, msg)
});

// Compile and execute AI script
await compiler.compileAndRun("workflow.atl", `
    @import("inventory")
    @import("notifications")

    val items = InventoryService.listCurrentStock()
    items.forEach {|item|
        if (item.quantity < 2) {
            notifications.sendAlert("Urgent", "Restock " + item.sku)
        }
    }
`);
```

---

## Language Reference Summary

Autolang is a statically-typed scripting language with Kotlin surface conventions. File extension: `.atl`. Code executes top-to-bottom at file scope. No semicolons required.

### Variables
- `val x = 10` - immutable
- `var y = 20` - mutable
- Nullable types: `var child: Int?`, `val email? = "a@b.com"`, `val id! = 42`
- Primitive types: `Int` (64-bit), `Float` (64-bit), `Bool`, `String`, `Any`

### Control Flow
- `if / else` (supports expression syntax)
- `when` (pattern matching, no fall-through)
- `for (item in collection) { ... }`
- `while (condition) { ... }`

### Functions
- `fun greet(name: String) { ... }`
- Single-expression: `fun multiply(a: Int, b: Int): Int = a * b`
- Default parameters and higher-order functions supported

### Closures
- `val square = {|x: Int| x * x }`
- Always use `||` parameter delimiters

### Classes & Host Objects
- Primary constructor: `class Person(val name: String, var age: Int)`
- Host wrapper: `@js_object class Service { @native("method") fun method(): ReturnType }`
- Access modifiers: public (default), private, protected
- Extension functions and operator overloading supported

### Null Safety
- Safe call: `x?.size()`
- Null coalescing: `val len = x?.size() ?? 0`
- Non-null assertion: `x!.size()`

### Collections
- Array: `val nums = <Int>[1, 2, 3]` - `add()`, `filter()`, `forEach()`, `map()`, `sort()`
- Map: `val m = <String, Int>{"Apple": 10}` - `containsKey()`, `keys()`, `values()`
- Set: `val s = <Int>{1, 2, 3}` - `add()`, `remove()`, `contains()`, `union()`

### Standard Library Modules
- `@import("std/math")` - `Math.PI`, `Math.abs`, `Math.pow`, `Math.sqrt`
- `@import("std/date")` - `Date.now()`, `Date.parse()`, `Date.format()`
- `@import("std/json")` - `JSON.parse()`, `JSON.stringify()`
- `@import("std/regex")` - Regular expression matching

---

## Technical Performance Characteristics

| Metric | Autolang (Native C++) | Autolang (npm / WASM) | Node.js / Python Runtime | Full Container (Docker) |
|---|---|---|---|---|
| RAM per session | ~0.5MB – 0.7MB | ~10MB shared | ~30MB – 50MB+ | Process RAM only |
| Cold start | < 10ms | ~20ms | ~100ms – 300ms | ~50ms – 200ms |
| Warm restart | ~1–2ms | ~1–2ms | - | - |
| Isolation boundary | Language capability sandbox | Language capability sandbox | Process boundary | OS kernel (cgroups/namespaces) |
| Resource governance | VM opcode & memory budget | VM opcode & memory budget | Unbounded by default | Host cgroup quotas |

---

## When to Use Autolang

### Use Autolang when:
- Executing AI-generated orchestration logic in real-time with explicit capability controls.
- Running concurrent agent pipelines where per-session memory and startup latency matter.
- Connecting existing backend services (Node.js, TypeScript, Go, C++) without exposing credentials to untrusted code.
- Batch processing collections where multi-step tool calling causes latency bottlenecks.

### Do NOT use Autolang when:
- Building general-purpose monolithic software (use TypeScript, Go, or Python).
- Scripts require unrestricted operating system access or raw socket networking.
- Applications do not execute untrusted AI-generated code.

---

## Documentation Links

- AI Agent Language Reference: https://autolang.vercel.app/autolang-ai-reference.md
- Documentation Overview: https://autolang.vercel.app/docs
- Philosophy & Vision: https://autolang.vercel.app/docs/philosophy-vision
- System Architecture: https://autolang.vercel.app/docs/architecture
- Security Model: https://autolang.vercel.app/docs/security-model
- NPM Integration Guide: https://autolang.vercel.app/docs/integration-npm
- Native Libraries Guide: https://autolang.vercel.app/docs/integration-npm/native-libraries
- Best Practices: https://autolang.vercel.app/docs/integration-npm/best-practices
- Language Syntax Guide: https://autolang.vercel.app/docs/language-guide/syntax
- Interactive Playground: https://autolang.vercel.app/docs/editor
- Frequently Asked Questions (FAQ): https://autolang.vercel.app/docs/faq
- GitHub: https://github.com/hoansdz/Autolang
- npm: https://www.npmjs.com/package/autolang-compiler