ailang-lang 1.1.4

Deterministic business application platform optimized for AI-assisted development

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 1079 tests, stress testing up to 10,000 LOC, and AI-generated program verification with 100% first-pass success.

Quick Start

# Install from PyPI
pip install ailang-lang

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

Or install 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

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

Guide	Description
Getting Started	Step-by-step introduction
Language Tour	Complete language feature tour
Standard Library Reference	All 16 modules documented
MCP Quick Start	AI tool integration via MCP
Compiler Architecture	Pipeline and design
Contributor Guide	How to contribute
Testing Guide	Test patterns and practices
Quick Start	5-minute setup guide
Quick Start (concise)	Minimal path: install → write → run
Onboarding Checklist	Day-by-day guide for new developers
VS Code Extension	AILang VS Code extension

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 — 1079 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

Module	Operations
string	concat, equals, uppercase, lowercase, length, contains, starts_with, ends_with, trim, substring, find, find_from, split, join, from_int, from_bool
math	add, sub, mul, div, abs, min, max
list	new, append, len, get, contains, remove, clear, sum, find_by_key, filter_by_key, filter_by_contains, collect_key, group_by_key, sum_by_key, take, skip, search_by_name, exists_by_key, sort, sort_by_key, copy
array	new, push, len, get, contains, remove, clear
map	new, set, get, has, delete, keys, clear, values, get_or_default, safe_get
set	new, add, contains, len, remove, clear
file	exists, read, write, append, remove, listdir
path	join, basename, dirname, extension, normalize
json	parse, stringify
csv	parse, parse_header, stringify
time	now, timestamp, sleep, format
random	int, float, choice
environment	get, cwd, args
convert	to_string, to_int, to_bool, to_number
io	write, writeln, println, read
system	exit

Project Status

Metric	Value
Python version	3.11+
Compiler LOC	~3,950 (39 Python files)
Stdlib modules	16
Tests	1079 passing
Example programs	55+
Application programs	43+
DX Tools	ail context, ail doctor, ail static_analyzer, ail benchmark, ail testgen, ail docs, ail mcp
Quality gates	black, ruff, mypy all clean
Validation	Deterministic, AI-verified, stress-tested

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.