Metadata-Version: 2.4
Name: npmai-fast
Version: 1.0.0
Summary: Zero-dependency AST-to-native compiler for hot numeric Python functions
Author: Sonu Kumar / NPMAI ECOSYSTEM
License: MIT
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development :: Compilers
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# npmai-fast

Zero-dependency AST-to-native compiler for hot numeric Python functions.

```python
from npmai_fast import optimize

@optimize
def total(a: int, b: int) -> int:
    result = 0
    for i in range(a):
        result += b
    return result
```

Just decorate and call. No config, no build step you have to run yourself.

## What actually happens

On first call, the function's source is analyzed. If it fits the
**compilable numeric subset** (int/float params and return, arithmetic,
comparisons, if/while/for-range loops — see below), it is transpiled to
C++20, compiled once with whatever compiler is on your machine (g++,
clang++, or MSVC), cached in `~/.cache/npmai_fast/`, and called natively
through `ctypes` on every call after that.

If the function does **not** fit that subset (dicts, lists, generators,
closures, exceptions, dynamic typing, etc.) — or no C++ compiler is
installed — it transparently falls back to plain CPython. Same result,
just not accelerated. This is by design: correctness first, speed second.

## Supported today

- Parameters and return value annotated `int` or `float`
- `+ - * / // % **` (with correct Python floor-division/modulo semantics)
- Comparisons, `and`/`or`/`not`
- `if/elif/else`, `while`, `for x in range(...)`
- Single-name local variables (no re-typing a variable mid-function)

## Not yet supported (falls back automatically, does not error)

- Lists, dicts, strings, objects, classes
- Function calls to anything other than `range()`
- Exceptions, generators, closures over outer state
- `*args`/`**kwargs`, default arguments

This puts npmai-fast in the same category as Numba's `@njit` or Pythran —
a numeric hot-loop compiler, not a general Python-to-native compiler. The
difference is a zero-dependency implementation (no LLVM) plus AST-level
inlining planned for a future release.

## CLI

```
npmai-fast check   # is a C++ compiler available on this machine?
npmai-fast stats   # cache size / compiled function count
npmai-fast clear   # wipe the compiled-function cache
```

## Requirements

A C++20-capable compiler must be installed for acceleration to kick in:

- **Linux**: `sudo apt install g++` (or your distro's equivalent)
- **macOS**: `xcode-select --install`
- **Windows**: Visual Studio Build Tools, "Desktop development with C++"

Without one, functions still run correctly — just as plain Python.
