Metadata-Version: 2.4
Name: ailang-lang
Version: 1.1.10
Summary: Deterministic business application platform optimized for AI-assisted development
Author: AILang Contributors
License: Apache-2.0
Project-URL: Homepage, https://github.com/akpersonal4/ailang-lang-AILang
Project-URL: Repository, https://github.com/akpersonal4/ailang-lang-AILang
Project-URL: Documentation, https://github.com/akpersonal4/ailang-lang-AILang/tree/main/docs
Project-URL: Issues, https://github.com/akpersonal4/ailang-lang-AILang/issues
Project-URL: Changelog, https://github.com/akpersonal4/ailang-lang-AILang/blob/main/CHANGELOG.md
Keywords: programming-language,compiler,ai,business-applications,deterministic
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Software Development :: Compilers
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: LICENSE_AUDIT_REPORT.md
License-File: NOTICE
License-File: AUTHORS.md
Requires-Dist: watchdog>=4.0
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: pytest-timeout>=2; extra == "dev"
Requires-Dist: black>=24; extra == "dev"
Requires-Dist: ruff>=0.4; extra == "dev"
Requires-Dist: mypy>=1; extra == "dev"
Provides-Extra: openai
Requires-Dist: openai>=1.0; extra == "openai"
Requires-Dist: tiktoken>=0.5; extra == "openai"
Provides-Extra: anthropic
Requires-Dist: anthropic>=0.30; extra == "anthropic"
Provides-Extra: google
Requires-Dist: google-generativeai>=0.4; extra == "google"
Provides-Extra: local
Requires-Dist: openai>=1.0; extra == "local"
Provides-Extra: all
Requires-Dist: openai>=1.0; extra == "all"
Requires-Dist: tiktoken>=0.5; extra == "all"
Requires-Dist: anthropic>=0.30; extra == "all"
Requires-Dist: google-generativeai>=0.4; extra == "all"
Dynamic: license-file

# AILang

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

[![Tests](https://img.shields.io/badge/tests-1165%20passing-brightgreen)](#)
[![Python](https://img.shields.io/badge/python-3.11%2B-blue)](#)
[![Version](https://img.shields.io/badge/build-v1.1.10-blue)](#)
[![License](https://img.shields.io/badge/license-Apache%202.0-green)](#)

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:

```bash
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/`):

```bash
pip install dist/ailang_lang-1.1.10-py3-none-any.whl
ail run hello.ail
```

## Core Commands

### Compilation & Execution

```bash
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

```bash
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

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

### Package Management

```bash
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

```bash
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

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

## Running Tests

```bash
# 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:

```bash
# 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

```ail
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](docs/reference/GETTING_STARTED.md) | Step-by-step introduction |
| [Language Tour](docs/reference/LANGUAGE_TOUR.md) | Complete language feature tour |
| [Standard Library Reference](docs/reference/STDLIB_REFERENCE.md) | All 16 modules documented |
| [MCP Quick Start](docs/reference/MCP_QUICKSTART.md) | AI tool integration via MCP |
| [Compiler Architecture](docs/reference/COMPILER_ARCHITECTURE.md) | Pipeline and design |
| [Contributor Guide](docs/governance/CONTRIBUTING.md) | How to contribute |
| [Testing Guide](docs/reference/TESTING.md) | Test patterns and practices |
| [Quick Start](docs/QUICKSTART.md) | 5-minute setup guide |
| [Quick Start (concise)](docs/getting-started/QUICK_START.md) | Minimal path: install → write → run |
| [Onboarding Checklist](docs/getting-started/ONBOARDING_CHECKLIST.md) | Day-by-day guide for new developers |
| [VS Code Extension](extensions/vscode-ailang/README.md) | AILang VS Code extension |

## VS Code Extension

Install the AILang extension for syntax highlighting, snippets, bracket matching, and more:
```bash
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

```ail
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](docs/reference/STDLIB_REFERENCE.md#string) | `concat`, `equals`, `uppercase`, `lowercase`, `length`, `contains`, `starts_with`, `ends_with`, `trim`, `substring`, `find`, `find_from`, `split`, `join`, `from_int`, `from_bool` |
| [math](docs/reference/STDLIB_REFERENCE.md#math) | `add`, `sub`, `mul`, `div`, `abs`, `min`, `max` |
| [list](docs/reference/STDLIB_REFERENCE.md#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](docs/reference/STDLIB_REFERENCE.md#array) | `new`, `push`, `len`, `get`, `contains`, `remove`, `clear` |
| [map](docs/reference/STDLIB_REFERENCE.md#map) | `new`, `set`, `get`, `has`, `delete`, `keys`, `clear`, `values`, `get_or_default`, `safe_get` |
| [set](docs/reference/STDLIB_REFERENCE.md#set) | `new`, `add`, `contains`, `len`, `remove`, `clear` |
| [file](docs/reference/STDLIB_REFERENCE.md#file) | `exists`, `read`, `write`, `append`, `remove`, `listdir` |
| [path](docs/reference/STDLIB_REFERENCE.md#path) | `join`, `basename`, `dirname`, `extension`, `normalize` |
| [json](docs/reference/STDLIB_REFERENCE.md#json) | `parse`, `stringify` |
| [csv](docs/reference/STDLIB_REFERENCE.md#csv) | `parse`, `parse_header`, `stringify` |
| [time](docs/reference/STDLIB_REFERENCE.md#time) | `now`, `timestamp`, `sleep`, `format` |
| [random](docs/reference/STDLIB_REFERENCE.md#random) | `int`, `float`, `choice` |
| [environment](docs/reference/STDLIB_REFERENCE.md#environment) | `get`, `cwd`, `args` |
| [convert](docs/reference/STDLIB_REFERENCE.md#convert) | `to_string`, `to_int`, `to_bool`, `to_number` |
| [io](docs/reference/STDLIB_REFERENCE.md#io) | `write`, `writeln`, `println`, `read` |
| [system](docs/reference/STDLIB_REFERENCE.md#system) | `exit` |

## Project Status

| Metric | Value |
|--------|-------|
| Python version | 3.11+ |
| Compiler LOC | ~3,950 (39 Python files) |
| Stdlib modules | 16 |
| Tests | **1165 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 |

## CLI Command Reference

| Command | Action |
|---------|--------|
| `ail run <file>` | Compile and run an AILang program |
| `ail build <file>` | Compile and check for errors (no execution) |
| `ail check <file>` | Check for forward references and ordering violations |
| `ail fmt <file\|dir>` | Format AILang source file(s) |
| `ail test [<file\|dir>]` | Run test_*.ail files |
| `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 |
| `ail watch [<file>]` | Watch for changes, recompile incrementally |
| `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 |
| `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 offline |
| `ail context [--json]` | Get machine-readable language context |
| `ail mcp` | Start MCP server for AI tool integration |
| `ail lsp` | Start the LSP server (stdin/stdout) |
| `ail --version` | Print version information |

### Troubleshooting

**"Command not found" after pip install**
```bash
# 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**
```bash
# 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**
```bash
# 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**
```bash
# 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**
```bash
# 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.

```bash
# 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

```bash
# 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.
