AILang

AI-first programming language — deterministic, specification-driven, and compiler-friendly.

AILang is an AI-first programming language designed to be deterministic, specification-first, and easy for both humans and AI systems to reason about. It features a complete compiler pipeline, a 16-module standard library, and has been validated through 1165 tests, stress testing up to 10,000 LOC, and AI-generated program verification with 100% first-pass success.

Quick Start

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.10-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 — 1037 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

CLI Command Reference

Troubleshooting

"Command not found" after pip install

# Ensure the Python Scripts directory is on your PATH:
python -m site --user-site
# Usually: ~/AppData/Roaming/Python/Python311/Scripts (Windows)
# Or: ~/.local/bin (Linux/macOS)

"Module not found" when running from outside project

# AILang v1.1.5+ resolves stdlib from the installed package automatically.
# If you still see MOD003, try reinstalling:
pip install --force-reinstall ailang-lang

"Unexpected character" on Windows

# The file may have a BOM marker. Save without BOM (UTF-8 without signature):
# In VS Code: File → Save with Encoding → UTF-8
# Then re-run: ail run <file>

"Running this file outside a project tree" warning

# This is informational — the file will still run. Create a project for
# full package management support:
ail new myproject && cd myproject
# Then copy your .ail file into myproject/

"Forward reference" error

# Functions must be defined before they are called.
# Run to see the exact ordering issue:
ail check <file>
# Then move the called function above its caller.

For detailed error explanations: ail explain <ERROR_CODE> For environment diagnostics: ail doctor

Formatter

AILang includes a deterministic source code formatter. One style only — no configuration.

# Format a file in-place
ail fmt hello.ail

# Check if a file is formatted (exit 0 = yes, 1 = no)
ail fmt --check hello.ail

# Read from stdin, write formatted to stdout
cat hello.ail | ail fmt --stdin

Formatting rules:

• 4-space indentation
• Opening brace on same line (fn foo() {, if (cond) {)
• } else { on one line
• Spaces around all binary operators (a + b, x == y, a && b)
• Space after , in parameter/argument lists
• Single blank line between function declarations
• Trailing whitespace removed
• Newline at EOF
• Comments preserved — inline and standalone comments are retained

Formatting is idempotent: formatting an already-formatted file produces no changes.

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.