AILang

Deterministic programming language designed for AI-assisted development.

AILang is a deterministic programming language for AI-assisted development. It runs on a deterministic Python interpreter and is designed to be easy for both humans and AI systems to reason about. Runtime errors are structured and diagnostic; there are no Python tracebacks in normal operation.

fn main() {
    print("Hello, AILang!");
    return 0
}

Why AILang?

• Deterministic by design — same source always produces the same output. Runtime errors are structured diagnostics, not Python tracebacks. The sandbox restricts file I/O to the project directory.
• AI-native tooling — ail mcp exposes the compiler to AI tools via Model Context Protocol. AI agents get machine-readable language specs, not blog posts.
• Fast feedback — compile and run in <2 seconds for 5000 LOC. No build server, no waiting.

Quick Start

Create a file hello.ail:

fn main() {
    print("Hello, AILang!")
    return 0
}

Note: The CLI is ail (not ailang). After pip install ailang-lang, use ail run, ail build, etc.

Build from source:

git clone https://github.com/akpersonal4/ailang-lang-AILang.git
cd ailang-lang-AILang
pip install -e .

# Run your first program
echo 'fn main() { print("Hello, AILang!"); return 0 }' > hello.ail
ail run hello.ail

Install from local wheel (pre-built in dist/):

pip install dist/ailang_lang-1.1.16-py3-none-any.whl
ail run hello.ail

Core Commands

Compilation & Execution

ail run <file.ail>       # Compile and run an AILang program
ail build <file.ail>     # Compile and check for errors (no execution)
ail check <file.ail>     # Check for forward references and ordering violations
ail fmt <file_or_dir>    # Format AILang source file(s)
ail fmt --check <file>   # Check if formatted
ail watch [<file>]       # Watch for changes, recompile incrementally

Project Management

ail new <project>         # Create a new AILang project scaffold
ail rename <old> <new>   # Rename identifier repository-wide
ail order <target>       # Analyze dependency ordering of .ail files

Testing

ail test [<file_or_dir>]  # Run test_*.ail files

Package Management

ail install              # Install dependencies from ail.toml
ail add <package>        # Add a dependency to ail.toml
ail remove <package>     # Remove a dependency from ail.toml
ail update               # Re-resolve all dependencies
ail list                 # List installed dependencies
ail publish             # Publish project to package registry

Developer Tools

ail doctor               # Diagnose environment issues
ail heal                 # Get fix suggestions for common errors
ail explain <CODE>       # Explain a compiler error code in detail
ail docs [<name>]        # Read documentation (AGENTS, LANGUAGE_SPEC, STDLIB_REFERENCE)
ail context [--json]     # Get machine-readable language context
ail mcp                  # Start MCP server for AI tool integration
ail static-analyzer      # Run static analysis on AILang source
ail benchmark            # Run the AILang benchmark suite
ail testgen              # Generate test cases for AILang apps

Other

ail lsp                  # Start the LSP server (stdin/stdout)
ail version              # Print version information
ail --version            # Print version information

Running Tests

# Run all tests in current directory
ail test

# Run tests for a specific application
ail test --root apps/inventory

# Run tests from application directory
cd apps/inventory
ail test

# Run a specific test file
ail test apps/inventory/tests/test_supplier.ail

# Run tests with verbose output
ail test --verbose

# Skip pre-flight ordering check
ail test --no-check

Supported test patterns:

• test_*.ail
• *_test.ail

Excluded directories:

• .ail/ (internal backups)
• backups/
• __pycache__/
• dist/
• build/
• .git/
• node_modules/
• .venv/

AI Agent Setup

For AI-assisted development, run this first:

# Get machine-readable language context
ail context --json

# Read the documentation
ail docs AGENTS
ail docs LANGUAGE_SPEC

Document hierarchy:

1. LANGUAGE_SPEC.md — canonical language definition (authoritative)
2. AGENTS.md — AI operational rules (derived from spec)
3. AILANG_DEVELOPMENT_PLAYBOOK.md — coding patterns and conventions
4. STDLIB_REFERENCE.md — library API documentation

If AGENTS.md conflicts with LANGUAGE_SPEC.md, the spec wins.

Language Tour

import string;
import math;
import list;

// Functions are top-level, recursion only (no loops)
fn factorial(n) {
    if (n <= 1) {
        return 1
    }
    return math.mul(n, factorial(math.sub(n, 1)))
}

// Import aliases
import map as m;

fn main() {
    // Variables with let
    let greeting = "Hello, AILang!";
    print(greeting);

    // Map operations
    let config = map.new();
    map.set(config, "version", "1.0");
    let v = map.get(config, "version");

    // Recursion
    let result = factorial(5);
    print(result);

    return 0
}

Documentation

VS Code Extension

Install the AILang extension for syntax highlighting, snippets, bracket matching, and more:

code --install-extension extensions/vscode-ailang

Or package and install from the VS Code Marketplace: extensions/vscode-ailang/.

Features

• Simple, explicit syntax — functions, variables, conditionals, recursion
• Deterministic compilation — same source always produces same output
• 16-module Standard Library — string, math, collections, file I/O, JSON, CSV, time, random, environment, conversion
• AI-native tooling — ail mcp exposes compiler to AI tools via Model Context Protocol
• AI-friendly — validated with 23 AI-generated programs at 100% first-pass success
• Fast compile times — 5000 LOC compiles in <2 seconds
• Low memory usage — 5000 LOC uses <11 MB peak memory
• Complete test coverage — 1201 tests across all compiler stages

Example

import string;
import math;
import list;

fn process(items) {
    let first = list.get(items, 0);
    return string.uppercase(first)
}

fn main() {
    let items = list.new();
    list.append(items, "hello");
    list.append(items, "world");
    let r = process(items);
    let s = math.add(1, 2);
    print(r, s);
    return 0
}

Standard Library

Project Status

For environment diagnostics: ail doctor. For error explanations: ail explain <CODE>.

See CLI Reference for all commands, Formatter for formatting rules, and Troubleshooting for common issues.

Development

# Install development tools
pip install pytest black ruff mypy

# Run all quality gates
python -m pytest
black --check .
ruff check .
mypy

License

This project is licensed under the Apache License 2.0.