AICL

Artificial Intelligence-Centered Language

Auditable compilation with Proof of Origin. If the compiler cannot explain why, it does not generate.

_{Updated pitch: AX sub-language, 4-target compilation, CogNet 1B. Download MP4 (~8 MB).}

---

What AICL is

AICL is a specification-first programming language. Risks, recoveries, and validations are not comments — they are mandatory syntactic elements. Every generated artifact carries provenance; every compilation produces a cryptographic Proof of Origin; every risk declared in source has a matching recovery executed by the runtime.

You write architecture. The compiler writes code. The proof chain explains why.

Goal:
Render a blue square in a window for 60 seconds

Constraint:
Window must close on ESC key

Risk:
Windowing subsystem unavailable

Recovery:
Fall back to headless framebuffer capture

Layer:
Renderer

Validation:
At least one frame is produced

Behavior RenderFrame
    Input: Frame
    Output: Pixels
    Action: clear screen to blue and present

Compiles to verified Python / Rust / JavaScript / Go, with a sidecar *.aicl-proof file that cryptographically ties each generated line back to the spec.

AX sub-language

AX (AICL-Action) is a Turing-complete sub-language for Action: sections. Instead of free-form English prose that the compiler can only skeleton, AX gives Behaviors a strict, compilable grammar: if/elif/else, while, for, recursion via calls, arithmetic, comparisons, list literals, indexing, method calls, and tuple swaps. The compiler translates any valid AX program to executable code in all four targets — no stubs, no pass-empty bodies.

Behavior Quicksort
    Input: array, low, high
    Output: pivot_index
    Action:
        pivot = array[high]
        i = low - 1
        for j in range(low, high):
            if array[j] < pivot:
                i = i + 1
                array[i], array[j] = array[j], array[i]
        array[i + 1], array[high] = array[high], array[i + 1]
        return i + 1

This compiles to real, runnable code that sorts correctly — in Python, JavaScript (Node), Rust (rustc), and Go. The AX module lives in python/src/aicl/ax/ (lexer, parser, AST, four emitters, type inference). Grammar and design: see docs/ax-reference.md for the full AX grammar.

Why

Traditional languages mix objective, implementation, risk, recovery, and validation in the same syntactic space, maximising learning noise for both humans and AI. AICL forces these dimensions apart and makes each one a first-class, machine-checkable element of the program.

The result is three properties no conventional language gives you for free:

1. Auditability — every generated line has a recorded reason.
2. Verifiability — every spec is checked for completeness and coherence before any code is emitted.
3. Self-healing — declared Risks are bound to declared Recoveries at compile time and executed by the runtime when the risk fires.

Demo

(Or open docs/demo.cast directly in asciinema — asciinema play docs/demo.cast.)

Install

From PyPI (recommended for users):

pip install aicl              # core package (includes rich for colored CLI output)
pip install "aicl[tui]"       # core + terminal UI (adds textual for the TUI)

From source (recommended for contributors):

git clone https://github.com/AFKmoney/AICL.git
cd AICL
make install-python   # or: cd python && pip install -e ".[tui,dev]"

Requires Python 3.10+. The rich library is a core dependency (colored CLI output, tables, progress bars). The optional tui extra adds textual for the interactive terminal editor. textual and rich. The dev extras add ruff, black, mypy, pytest, hypothesis, pre-commit, build, and twine.

See python/docs/upgrading.md for how to upgrade, downgrade, and migrate between versions.

Quick start

# Compile a program
aicl compile python/examples/showcase/01_blue_square.aicl

# Compile to a different target (AX behaviors compile to real executable code)
aicl compile python/examples/showcase/01_blue_square.aicl --target rust

# Verify spec completeness
aicl verify python/examples/showcase/01_blue_square.aicl

# Check for errors + AX syntax (target-aware)
aicl check python/examples/showcase/01_blue_square.aicl --target rust

# Explain why each line was generated
aicl explain python/examples/showcase/01_blue_square.aicl

# Scaffold a new project
aicl init my-app

# Diagnose your environment
aicl doctor

# Launch the interactive terminal UI
aicl tui

aicl --help lists all 18 subcommands. The CLI uses rich-colored output by default; pass --json for machine-readable output in CI/CD pipelines.

The language in one minute

AICL has 27 keywords organised across 10 language levels. The full BNF is in python/spec/grammar.md.

Level	Mandatory?	Keywords
1. Architecture	Yes	Goal, Constraint, Layer, Validation
2. Risk management	Yes	Risk, Recovery
3. Data	No	Entity, Field
4. Behaviour	No	Behavior, Input, Output, Action
5. Reactivity	No	When, Then, Event, On
6. Concurrency	No	Parallel, Sequence
7. Optimisation	No	Optimize, Learn, Adapt
8. Security	No	Security, Native
9. Modules	No	import, export
10. AI autonomy	No	Evolve, SpecEvolver

A program without a Goal does not compile. A program with a Risk but no matching Recovery does not compile. A program whose Validation cannot be traced back to a Goal does not compile. The compiler enforces intent.

Targets

The compiler emits code for four backends, all from the same .aicl source:

Target	Flag	Output
Python	--target python (default)	main.py + test_main.py
Rust	--target rust	main.rs + tests
JavaScript	--target javascript	main.mjs
Go	--target go	main.go

Each backend produces an identical .aicl-proof file — the Proof of Origin is target-independent.

Proof of Origin

Every compilation emits a .aicl-proof JSON file that records, for each generated artifact:

• the source span it was derived from
• the compilation stage that produced it
• a SHA-256 hash of the artifact
• (optionally) an Ed25519 signature over the proof chain

Proofs can be inspected with aicl proof and verified out-of-band with python/tools/verify_proof.py. A proof that does not verify means the compilation was tampered with after the fact — the artifact is not trustworthy.

Autonomous compilation

AICL can write itself. The evolve subcommand runs a self-writing, self-validating loop:

spec → compile → run tests → diagnose failures → patch spec → repeat

The loop terminates when the spec compiles, tests pass, and audit coverage hits 100%. Patterns learned across runs are persisted to a pattern library and reused on subsequent invocations. See python/src/aicl/autonomous.py and python/src/aicl/ai_generator.py.

CogNet integration

AICL is the cognitive representation layer for the CogNet non-transformer language model. CogNet is fine-tuned on a corpus of AICL spec → generated code pairs so it learns to write AICL/Python/Rust code from a specification.

Corpus generator: python/tools/corpus_generator.py produces the training data — 30 algorithm templates (sorts, searches, math, string ops, primes, collatz, etc.) written in AX, each compiled to real code. Output: corpus/aicl_corpus.raw (Python, 258k chars) or corpus/aicl_corpus_multitarget.raw (Python + Rust, 305k chars).

Training: see the CogNet repo for cloud_train.py (one-shot GPU training script) and CLOUD_TRAINING.md (GPU recommendations, timing, checkpoint usage).

# Generate the corpus
python tools/corpus_generator.py --out corpus/aicl_corpus.raw --targets python

# Fine-tune CogNet (on a GPU instance)
python cloud_train.py --steps 5000

Web editor (optional)

The repo ships a Next.js 16 web editor that exposes the compiler through a browser UI: AX syntax highlighting, live compilation to 4 targets, architecture-tree visualisation, proof inspection, AI-assisted spec authoring, interactive exercises, and localStorage persistence.

cp .env.example .env
cd editor && bun install
bun run db:push     # initialise the SQLite database
bun run dev         # http://localhost:3000

The editor talks to the Python aicl package through python/scripts/aicl_helper.py via the JSON-over-stdio protocol documented in python/docs/bridge_protocol.md. The web editor is optional — the language is fully usable from the CLI and TUI without Node.

Tests

make test
# or: cd python && pytest tests/ -v

189 tests cover parsing, all 10 language levels, every backend, the autonomous loop, the spec verifier, the ownership analyser, the optimiser, the Proof of Origin chain, the AX sub-language (frontend + 4 emitters), and 5 Hypothesis property-based tests that generate randomised valid programs and verify compiler invariants (determinism, 100% audit coverage, valid proof chains, idempotent verification). All pass on Python 3.10, 3.11, 3.12, and 3.13 (CLI also on 3.14).

Documentation

Doc	What it covers
White Paper	Complete technical overview — the definitive reference
Getting Started	Install, first program, compile, verify
AX Reference	Full grammar of the AX Turing-complete sub-language
Compile Targets	Python, Rust, JavaScript, Go — how AX translates
Proof of Origin	Cryptographic provenance and verification
CogNet Integration	Corpus generation, fine-tuning CogNet 1B
Grammar Spec	Formal AICL grammar (incl. AX sub-language)
Position Paper	Why AICL exists — the no-orphan property
arXiv Paper (LaTeX)	Full academic treatment

Examples

The curated showcase is in python/examples/showcase/ (20 programs with AX behaviors). The full dataset of 151 AX-powered algorithm scripts is in python/aicl_dataset/ (14 categories). See python/examples/showcase/README.md for the gallery index.

Repository layout

The repo is a single workspace with two cooperating stacks. See ARCHITECTURE.md for the full map.

python/           AICL — the language (Python package — the core artifact)
├── src/aicl/       Compiler, runtime, CLI, TUI, cognet/ placeholder
├── spec/           Formal BNF grammar
├── examples/       91 AICL programs (showcase/ + archive/)
├── tests/          156 pytest tests (incl. 5 property-based)
├── tools/          Developer utilities (dataset gen, proof verifier, AI bridge)
├── scripts/        aicl_helper.py — JSON bridge used by the web editor
├── datasets/       JSONL training sets for fine-tuning LLMs on AICL
├── docs/           Bridge protocol, CogNet integration plan
└── pyproject.toml  Package metadata, ruff/black/mypy config

editor/            AICL Editor — the web IDE (Next.js 16, optional)
├── src/app/        Next.js API routes + page
├── src/components/ shadcn/ui components
├── src/lib/        aicl-bridge.ts — shared Python bridge client
├── prisma/         Database schema (SQLite)
├── public/         Static assets
└── package.json    Editor metadata

docs/              Cross-cutting docs (papers, screenshots, asciinema demo)
.github/workflows/  CI (Python 3.10/3.11/3.12 + editor build)

Documentation

• Formal grammar
• Architecture overview
• Bridge protocol (editor ↔ compiler)
• CogNet integration plan
• Upgrading AICL (user guide)
• Releasing AICL (maintainer guide)
• Position paper — why AICL exists
• arXiv paper (LaTeX source) — full academic treatment
• Changelog
• Contributing
• Security policy
• Citation

Contributing

Pull requests welcome. Read CONTRIBUTING.md first. Install pre-commit hooks with make install-precommit — ruff, black, mypy, and eslint will run automatically on every commit.

Please open an issue before starting work on a large change.

License

MIT — see LICENSE.

Author

Philippe-Antoine Robert — GitHub @AFKmoney

Think better, not bigger.