Metadata-Version: 2.4
Name: pyvorin
Version: 0.1.0a0
Summary: Pyvorin: Zero-overhead Python kernel compiler
Author: Pyvorin Team
License: MIT
Keywords: compiler,optimization,jit,llvm,runtime
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: pydantic>=2.0
Requires-Dist: typer>=0.9
Requires-Dist: rich>=13.0
Requires-Dist: llvmlite>=0.41
Requires-Dist: numpy>=1.24
Requires-Dist: msgpack>=1.0
Requires-Dist: pynacl>=1.5
Provides-Extra: track-a
Requires-Dist: llvmlite>=0.41; extra == "track-a"
Provides-Extra: track-b
Requires-Dist: torch>=2.1; extra == "track-b"
Requires-Dist: onnx>=1.15; extra == "track-b"
Requires-Dist: numpy>=1.24; extra == "track-b"
Provides-Extra: dev
Requires-Dist: pytest>=7.4; extra == "dev"
Requires-Dist: pytest-cov>=4.1; extra == "dev"
Requires-Dist: black>=23.0; extra == "dev"
Requires-Dist: ruff>=0.1; extra == "dev"
Requires-Dist: mypy>=1.5; extra == "dev"

# Pyvorin

> **Python-to-native compiler for a strict subset of Python**
>
> LLVM-based JIT compilation with automatic fallback to CPython for unsupported constructs.

[![Status](https://img.shields.io/badge/status-alpha-orange)](docs/PROJECT_STATUS.md)
[![Phase](https://img.shields.io/badge/phase-research%20prototype-blue)](docs/PROJECT_STATUS.md)

## Overview

Pyvorin compiles a strict but useful subset of Python to native machine code via LLVM (`llvmlite`). It includes two execution paths:

- **NativeCompiler** — Python AST → LLVM IR → `.so` → `ctypes` callable.
- **Columnar Engine** — A narrow data-processing frontend that lowers specific Python patterns to filter/project/aggregate/flatten operators backed by C/AVX2 kernels.

When code falls outside the supported subset, Pyvorin falls back to CPython execution rather than crashing.

## Supported Subset (Native)

- `int`, `float`, `str`, `list`, `tuple`, `dict`, `set`
- `for`, `while`, `if`/`else`, `break`/`continue`, `return`
- Functions, recursion, lambdas
- Arithmetic, bitwise, comparison, augmented assignment
- List comprehensions, dict/set comprehensions (some paths fallback)

**Not yet supported natively:** `class`, `try`/`except`/`raise`, `yield`, `async`/`await`, `import`, `with`, `*args`/`**kwargs`, walrus operator.

See [`docs/COMPATIBILITY.md`](docs/COMPATIBILITY.md) and [`docs/specs/SUPPORTED_LANGUAGE_SUBSET.md`](docs/specs/SUPPORTED_LANGUAGE_SUBSET.md) for the full truth.

## Quick Start

```bash
# Install (in a venv)
python3 -m venv .venv
source .venv/bin/activate
pip install .

# Check environment
pyvorin doctor

# Run a file
pyvorin run examples/hello.py

# Benchmark with correctness validation
pyvorin bench examples/hello.py

# Inspect generated LLVM IR
pyvorin inspect examples/hello.py
```

## Packaging

- **Linux:** `suite/build_linux_cli.sh` produces `dist/pyvorin-cli-linux.tar.gz` (portable tarball with entry script and `.so` runtimes).
- **Windows:** `suite/build_windows_cli.md` describes Windows packaging.

## Honest Performance

Pyvorin beats CPython on compatible numeric microbenchmarks. On the honest benchmark suite:

- **vs CPython:** Wins on every compatible benchmark (speedups vary by workload).
- **vs Numba:** Wins on specific workloads where Numba cannot compile (e.g., recursion) and some integer-loop kernels. Loses on raw numerical array kernels where Numba succeeds.
- **vs Polars (columnar):** Competitive on simple filter-map-reduce and flatten workloads. Not a general dataframe replacement.

See [`honest_benchmark_results.json`](honest_benchmark_results.json) and [`docs/audits/PRODUCT_CLAIMS_BOUNDARY.md`](docs/audits/PRODUCT_CLAIMS_BOUNDARY.md) for safe vs unsafe claims.

## Project Structure

```
├── docs/               # Honest docs, audits, and specs
├── pyvorin/            # NativeCompiler + columnar engine
├── suite/              # Benchmark worker and licensing
├── tests/              # Correctness tests
├── benchmarks/         # Benchmark harnesses
└── dist/               # Build artifacts
```

## Development

```bash
# Run correctness tests
make test

# Run the honest benchmark suite
python3 honest_benchmark_suite.py --benchmark df_column_sum_1m

# Run columnar tests
python3 -m pytest pyvorin/columnar/ -q
```

## Documentation

- [`docs/PROJECT_STATUS.md`](docs/PROJECT_STATUS.md) — Honest maturity assessment
- [`docs/COMPATIBILITY.md`](docs/COMPATIBILITY.md) — What works and what falls back
- [`docs/specs/SUPPORTED_LANGUAGE_SUBSET.md`](docs/specs/SUPPORTED_LANGUAGE_SUBSET.md) — Formal subset definition
- [`docs/audits/PRODUCT_CLAIMS_BOUNDARY.md`](docs/audits/PRODUCT_CLAIMS_BOUNDARY.md) — Safe vs unsafe claims

## License

MIT License — see [`LICENSE`](LICENSE) for details.
