Menai

Menai is a pure functional programming language with Lisp-like S-expression syntax. It is homoiconic, strictly typed, and side-effect free. It has no I/O, no mutation, no access to the filesystem, network, or any other external state.

While Menai doesn't support I/O operations, it is designed to be embedded into other software that does. It started as part of the Humbug AI project which uses Menai to perform file and data processing, sorting operations, apply mathematical reasoning, etc., but does so within its AI tool framework that does the I/O operations and handles permissioning.

The separation of concerns means we never have to worry about non-deterministic or stateful behaviour within Menai itself, leaving the stateful activities residing elsewhere.

This repo contains a number of tools and examples that demonstrate this approach, including a simple pipeline runner that can chain I/O operations implemented in Python with deterministic operations implemented in Menai.

As a pure functional language, Menai lends itself to being highly optimized. The current implementation compiles to a virtual machine bytecode but future versions will target highly optimized native code. The language design has also lent itself to very fast compilation, with Menai code compiled on demand.

Designed with AI

One of the more unusual features of Menai is that it was designed with AI, and with an assumption that AI would be heavily used in both implementing the language and in using it.

As such a key question has always been "what would you, as an AI, want in a language, as opposed to what would a human want?" This means Menai prefers precision over convenience, and explicit clarity over brevity that might make anything unclear.

An example of where this has had an impact are that there is no implicit type coercion. If you have an integer and want to use it in a floating point operation you must explicitly convert it. Similarly, there are no overloaded operators, so where other languages might have an + operator, Menai has explcit integer+, float+, and complex+ operators. It turns out AIs can generate very robust code this way.

Key characteristics

Pure functional — no side effects, no mutation, immutable data
Homoiconic — code and data share the same representation (S-expressions)
Strictly typed — no implicit coercion between numeric types; each type has its own operators (e.g. integer+, float*, complex/)
Proper lists only — no cons cells or improper lists
Tail call optimised — recursive functions don't overflow the stack
Pattern matching — declarative branching with destructuring
Module system — write and import .menai files
Atoms - atoms for integers (arbitrary precision), floating point numbers, complex floating point numbers, strings, booleans
Bytes type — with multi-byte integer read/write (little/big-endian, LEB128)
Structs — nominal typed records with functional updates
Containers - lists, dictionaries, sets
Compiled - code is compiled with an optimizing compiler to a virtual machine bytecode

An example

Here's an example that finds the occurrence of words in a string and then returns the 3 most frequent words, sorted by frequency!

(letrec
  ((count-words
    (lambda (words)
      (fold-list
        (lambda (acc word)
          (dict-set acc word
            (integer+ 1 (dict-get acc word 0))))
        (dict) words)))

   (top-words
    (lambda (text n)
      (let* ((words (string->list (string-downcase text) " "))
             (counts (count-words words))
             (pairs (sort-list
                       (lambda (a b) (integer>? (list-ref a 1) (list-ref b 1)))
                       (map-list (lambda (key)
                                   (list key (dict-get counts key)))
                                 (dict-keys counts)))))
        (list-slice pairs 0 n)))))

  (top-words "the quick brown fox jumps over the lazy dog the fox runs" 3))

This returns (("the" 3) ("fox" 2) ("quick" 1)). This is a dictionary output with the word as a key and the number of occurences as the value.

Language manual

The full language manual is in docs/. Start with docs/index.md for a table of contents and introduction.

The manual is written for both human and AI readers.

Getting started

Installation

pip install menai

The C VM is compiled into the wheels, so pip install menai includes it automatically — no separate build or download step is needed. Wheels are published for Linux, macOS, and Windows on x86_64 and ARM64, across Python 3.10–3.14.

Development

For local development, install in editable mode and build the C VM from source:

pip install -e ".[dev]"
make build

Requires a C compiler (gcc, clang, or MSVC).

Running tests

make test

A first program

(let ((greet (lambda (name)
               (string-concat "Hello, " name))))
  (greet "World"))

Evaluates to "Hello, World".

Implementation

Menai is compiled through an optimizing pipeline (lexing → AST → semantic analysis → module resolution → desugaring → constant folding → IR → IR optimisation → CFG → CFG optimisation → VCode → bytecode) and executed by a register-based C VM.

The pipeline is authoritative in src/menai/menai_compiler.py — it is always current and should be read directly rather than reproduced in documentation.

The reference implementation is in Python, but the language specification is independent of Python. Future bindings (C, Rust, etc.) will implement the same language against the same spec.

Repository structure

menai/
├── docs/                       # language manual
├── menai_modules/              # standard library (.menai files)
├── pyproject.toml              # Python package configuration
├── setup.py                    # C VM extension build (platform-specific flags)
├── src/
│   ├── menai/                  # compiler core (lexer, parser, IR, CFG, bytecode, VM)
│   ├── menai_benchmark/        # performance benchmarking tool
│   ├── menai_checker/          # parenthesis balance checker
│   ├── menai_disassembler/     # bytecode disassembler
│   ├── menai_pretty_print/     # code formatter
│   ├── menai_profiler/         # profiling tool
│   └── menai_test_runner/      # test runner for *_test.menai files
└── tests/                      # compiler core tests

Design intent

See blueprint.md for the design philosophy, core principles, and architectural decisions behind Menai.

License

Apache License, Version 2.0. See LICENSE.txt.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

menai-0.3.0.tar.gz (317.3 kB view details)

Uploaded Aug 30, 2026 Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

menai-0.3.0-cp314-cp314-win_amd64.whl (420.1 kB view details)

Uploaded Aug 30, 2026 CPython 3.14Windows x86-64

menai-0.3.0-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl (727.4 kB view details)

Uploaded Aug 30, 2026 CPython 3.14manylinux: glibc 2.17+ x86-64manylinux: glibc 2.28+ x86-64

menai-0.3.0-cp314-cp314-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl (713.6 kB view details)

Uploaded Aug 30, 2026 CPython 3.14manylinux: glibc 2.17+ ARM64manylinux: glibc 2.28+ ARM64

menai-0.3.0-cp314-cp314-macosx_11_0_arm64.whl (420.2 kB view details)

Uploaded Aug 30, 2026 CPython 3.14macOS 11.0+ ARM64

menai-0.3.0-cp314-cp314-macosx_10_15_x86_64.whl (429.1 kB view details)

Uploaded Aug 30, 2026 CPython 3.14macOS 10.15+ x86-64

menai-0.3.0-cp313-cp313-win_amd64.whl (418.6 kB view details)

Uploaded Aug 30, 2026 CPython 3.13Windows x86-64

menai-0.3.0-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl (727.2 kB view details)

Uploaded Aug 30, 2026 CPython 3.13manylinux: glibc 2.17+ x86-64manylinux: glibc 2.28+ x86-64

menai-0.3.0-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl (713.5 kB view details)

Uploaded Aug 30, 2026 CPython 3.13manylinux: glibc 2.17+ ARM64manylinux: glibc 2.28+ ARM64

menai-0.3.0-cp313-cp313-macosx_11_0_arm64.whl (420.2 kB view details)

Uploaded Aug 30, 2026 CPython 3.13macOS 11.0+ ARM64

menai-0.3.0-cp313-cp313-macosx_10_13_x86_64.whl (429.0 kB view details)

Uploaded Aug 30, 2026 CPython 3.13macOS 10.13+ x86-64

menai-0.3.0-cp312-cp312-win_amd64.whl (418.6 kB view details)

Uploaded Aug 30, 2026 CPython 3.12Windows x86-64

menai-0.3.0-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl (727.2 kB view details)

Uploaded Aug 30, 2026 CPython 3.12manylinux: glibc 2.17+ x86-64manylinux: glibc 2.28+ x86-64

menai-0.3.0-cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl (713.5 kB view details)

Uploaded Aug 30, 2026 CPython 3.12manylinux: glibc 2.17+ ARM64manylinux: glibc 2.28+ ARM64

menai-0.3.0-cp312-cp312-macosx_11_0_arm64.whl (420.2 kB view details)

Uploaded Aug 30, 2026 CPython 3.12macOS 11.0+ ARM64

menai-0.3.0-cp312-cp312-macosx_10_13_x86_64.whl (429.0 kB view details)

Uploaded Aug 30, 2026 CPython 3.12macOS 10.13+ x86-64

menai-0.3.0-cp311-cp311-win_amd64.whl (418.4 kB view details)

Uploaded Aug 30, 2026 CPython 3.11Windows x86-64

menai-0.3.0-cp311-cp311-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl (724.0 kB view details)

Uploaded Aug 30, 2026 CPython 3.11manylinux: glibc 2.17+ x86-64manylinux: glibc 2.28+ x86-64

menai-0.3.0-cp311-cp311-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl (710.6 kB view details)

Uploaded Aug 30, 2026 CPython 3.11manylinux: glibc 2.17+ ARM64manylinux: glibc 2.28+ ARM64

menai-0.3.0-cp311-cp311-macosx_11_0_arm64.whl (420.0 kB view details)

Uploaded Aug 30, 2026 CPython 3.11macOS 11.0+ ARM64

menai-0.3.0-cp311-cp311-macosx_10_9_x86_64.whl (428.5 kB view details)

Uploaded Aug 30, 2026 CPython 3.11macOS 10.9+ x86-64

menai-0.3.0-cp310-cp310-win_amd64.whl (418.5 kB view details)

Uploaded Aug 30, 2026 CPython 3.10Windows x86-64

menai-0.3.0-cp310-cp310-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl (724.2 kB view details)

Uploaded Aug 30, 2026 CPython 3.10manylinux: glibc 2.17+ x86-64manylinux: glibc 2.28+ x86-64

menai-0.3.0-cp310-cp310-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl (710.8 kB view details)

Uploaded Aug 30, 2026 CPython 3.10manylinux: glibc 2.17+ ARM64manylinux: glibc 2.28+ ARM64

menai-0.3.0-cp310-cp310-macosx_11_0_arm64.whl (420.3 kB view details)

Uploaded Aug 30, 2026 CPython 3.10macOS 11.0+ ARM64

menai-0.3.0-cp310-cp310-macosx_10_9_x86_64.whl (428.8 kB view details)

Uploaded Aug 30, 2026 CPython 3.10macOS 10.9+ x86-64

File details

Details for the file menai-0.3.0.tar.gz.

File metadata

Download URL: menai-0.3.0.tar.gz
Upload date: Aug 30, 2026
Size: 317.3 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for menai-0.3.0.tar.gz
Algorithm	Hash digest
SHA256	`95cced8f2407198b1b59c4b2a4a721862a23aeb61d20d651fba94bdff2d2ede1`
MD5	`aca0d6b6caf6cbef4b6bbb2da9a78745`
BLAKE2b-256	`4ca8144334337408b34402df4a81a05f1cb08c7aef17d3a25e67523ff452e0ee`

Algorithm	Hash digest
SHA256	`8e1498037b05e0de222b1e8076fa3b3839f62ca7a1fdb654b086197fd7636dc6`
MD5	`05fc1791d0f1497c8424221f5a3aad71`
BLAKE2b-256	`b990df8dd59088c592b43fd8cf731bb6ab120612799961564bc4eedb9cf47c49`

Algorithm	Hash digest
SHA256	`90bcf09d2d30709053062e6532d8c8d5ab2f3672d6e5ff85b3e44150876f09f5`
MD5	`5e77c7820475779f928278ca1bc91405`
BLAKE2b-256	`1e3709a1cf241978458c6ed195d245001d64c6471b40c850e566b73211befe18`

Algorithm	Hash digest
SHA256	`2f05f7bfdd4406588533f3d3684a2900640eefbb67d6e214ac01cce3df05f5f9`
MD5	`98537f35e009104b4d005c1bc4c73568`
BLAKE2b-256	`f3590dfaa6c30af8a42c2001fba69a7c185fe6bb4803900be447e7c34efd0e0f`

Algorithm	Hash digest
SHA256	`e8893045fbe4fdd2b1cb6edb7a897223966287a03b443238322301f29293f788`
MD5	`b54c463115c6a6cdc2ed8c69770f584f`
BLAKE2b-256	`06f7c4c16a25a953964cf73df34c5e18549f328b156a5c7383f221dad7cf0c6b`

Algorithm	Hash digest
SHA256	`08be5c8567253b12759980a2be2c19e4434cd913102b8d05b002d58c954bfd2a`
MD5	`2934e3fc9e4b76182b9cd3cf1b82d0b6`
BLAKE2b-256	`b3a2cff78e2b5c318b1c000c142c9f00c6246fd289ec82ee17c5c2411438252b`

Algorithm	Hash digest
SHA256	`232a8a29329098c6f168d8b5a404c689a0c47d21b0a74d35c981c171ce101002`
MD5	`84923cb3a3cd19aa7592a836d807942e`
BLAKE2b-256	`ff12e3b61c0566ba8581c59bc2243f7e6b1af86fa5c5669c76e6e7ac32e8b894`

Algorithm	Hash digest
SHA256	`9f8b5a573fa46995e262e73c9f73b2b89e4d5a83650bd9ff747b034a22f6b28f`
MD5	`ef97c62c8ecb76a9569ea0f195bb9645`
BLAKE2b-256	`f14e8fa331fe80656a268e815dcd5bb5eaf0e256c34b4587dfb29e9aea111f7e`

Algorithm	Hash digest
SHA256	`d3149e4b5068026e5d9579c0562d8caaa8c42d2723ff79408d48755cdc406e7d`
MD5	`9aba467fe1260d658a9ad0febd282478`
BLAKE2b-256	`44b77bdd03bb76bfe41dacbd380b5605f3d848cbe06065d3b323025a9f7de5b7`

Algorithm	Hash digest
SHA256	`01fcffe0e5033c021c1a73f76f9d86b2842a7e897abe2bc6ea4900e7fc1f03c8`
MD5	`03af06922cce07dc4596b5025c4f38d7`
BLAKE2b-256	`16b6810a73a365560b13af5f765e377231ad4581d69007691bc4422126243a25`

Algorithm	Hash digest
SHA256	`f602195e57aa268f9825ec5dde712a119869220cc91c03cb927d716b12337243`
MD5	`d4e0093f4440d7d18bf1f45e6d0ea197`
BLAKE2b-256	`680a16d62ce1edd2374efa513e74ce31357f4c2c3b50055c7c4903c5e3d5c1de`

Algorithm	Hash digest
SHA256	`edf14b9279de6795e0444153bc0d4a3e8a132528cee32faca07d424407b6b4fa`
MD5	`7cf15090f10a87647b9264eeb59040b5`
BLAKE2b-256	`5655c1f98ca9346c0a4a19579a980d8953ce440da9743cec83f9aab3b71ce200`

Algorithm	Hash digest
SHA256	`3e7958fbedccb1bd52c334b977e78724d0a0a02abfd3175ea359647538ffd84e`
MD5	`ec6945cc3fde934b70d089dc057becdf`
BLAKE2b-256	`f005bd3bc16b830a7a6e06da8fc51aeb6ea860532333ef6825c8cbb9790af9d9`

Algorithm	Hash digest
SHA256	`a8b24d5eebba4639742d69d447234df270cb4106f1bbf53cd49b76061bc85f1e`
MD5	`c6797d6c98117df3ae25dc056cf9b9be`
BLAKE2b-256	`d6641ed39c2c27483a5e6b189fe4ee98bd529f3c9247172374ef84b4871e8061`

Algorithm	Hash digest
SHA256	`934fc3bcd1832ddb7e89f07f722856a718e53e6f405c09671adb2e786223c576`
MD5	`13fc4354f540ea8c19f7743596de45e3`
BLAKE2b-256	`35e4bd390ffb24a6d465723bebfba2ce1d137958d70d2fab8d0e2dcf3a48e8c3`

Algorithm	Hash digest
SHA256	`824d21997706d77a5319ed2620f29b7cefcdf765de8c735290e654591d8e3c6c`
MD5	`8a7f4fa4d75f92fc5ca27066696dda38`
BLAKE2b-256	`0cec0296398e62796b44297b1c7f6d7b981ff8d473d0453d5d23aff4f2009bbc`

Algorithm	Hash digest
SHA256	`f898f5ab6c94b59bfdbb78cc8cc678f4da833809121705683336444e5da33c98`
MD5	`b58c92512e40114a40ad36f078523563`
BLAKE2b-256	`6ee82a120669dc23bb819fba5fb56e9722118c531bfa842e9abb5a4dd686d9cb`

Algorithm	Hash digest
SHA256	`606b6dfd91cf91836ea90061456e32bc2d2b367f21f7df56422be446bf696649`
MD5	`4e405fe17be48573dc90275c469f95b1`
BLAKE2b-256	`5f435d60f44c507da09bde9421eb435f54801d97499cb9b563565e5a8a072747`

Algorithm	Hash digest
SHA256	`9ae65e7c192cebe542824b6479446328e1d84856cd5842d90620f5d564798723`
MD5	`021d77184fe3ff54b4a8e7fc39d45d61`
BLAKE2b-256	`ccf8a587ad3f8ccdf697fbfc0dbece8cc00d22d2391bdb1b8f899ad49dfe0583`

Algorithm	Hash digest
SHA256	`6411a8e84a1a138b6313bf6d21822eeaceb0d7f55937a1fd9c83437590c8abf9`
MD5	`fae52949d1b2d7ebadceed1c6e9abb43`
BLAKE2b-256	`d5b8e99a838a6514af75bbd0da86d7c7b44e81f7b1d9cc962d8da9378e879710`

Algorithm	Hash digest
SHA256	`6ce5f41547b005965d86c3ac6a135a2c7df01d4c925340bfc7a5aa06f3ea00ed`
MD5	`15519eed9fcf990610422c3dbcc23bcc`
BLAKE2b-256	`5c7dd4982871fa9790aab7856e302017454bd7cf4fecedba226a847caae9438c`

menai 0.3.0

Menai

Designed with AI

Key characteristics

An example

Language manual

Getting started

Installation

Development

Running tests

A first program

Implementation

Repository structure

Design intent

License

Project links

Key dates

1 maintainer

GitHub Statistics

License expression

Requires

Provides Extra

Download files

Source Distribution

Built Distributions

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Algorithm	Hash digest
SHA256	`7a79458cf7190b457210a7a2732adc43ec703135c7df1ce9628b0b3f0c456763`
MD5	`75334d31151edc35d36fa16aade57c9c`
BLAKE2b-256	`84288a6d1126c6905a17e934d1ad1f0b488616990a49fb498d3c62a38cfc65c4`

Algorithm	Hash digest
SHA256	`18402541ca247f118aef28290b265eb8d255465f8529579cefe466d8bcc9539a`
MD5	`02be7e0d82a1dabb42f6526fa394dffb`
BLAKE2b-256	`a53dbd2fd8f5ba397ad0665362ecb17760b30847d6655ac49c72e0ce43bf7aa7`

Algorithm	Hash digest
SHA256	`73af04cf367aeaae17d08b38f573fc437ceb9b19fb5e1bb17bb796c459b15aa0`
MD5	`4c3d5c43d73991fd20714e08699f8f3a`
BLAKE2b-256	`d0017499cde2b0158fa447f6dfc4346ac94c1d539edaaec6d2c6fb1e4b5e3fc8`

Algorithm	Hash digest
SHA256	`ae8b575bf67640445a140a0a4d26d40ee42d698ca5495c30f591455c07bf1818`
MD5	`12ded6791a42793f101ecc6a9a26669d`
BLAKE2b-256	`12aeac93b18f1ed5bd9fe62d7db6611fce2e64e4524f0aba97cd943766015ba3`

Algorithm	Hash digest
SHA256	`303f7141cfc1f19c468f0b56e80c09fd2fe8de6965faf5c6698e61d5ef697148`
MD5	`6772705cce8678fbb51247e5ed4e70b5`
BLAKE2b-256	`9c304a35f9de1b5154eab9f6aa882e76e59d9e140eaa6c4acbf82b0f4fd604b9`