Metadata-Version: 2.2
Name: ace-fhe
Version: 0.2.2
Summary: ACE-Compiler: An FHE Domain-Specific Compiler
Author-Email: ACE <ace_group@antgroup.com>
License: Apache-2.0 WITH LLVM-exception
Project-URL: Homepage, https://github.com/ant-research/ace-compiler
Project-URL: Documentation, https://github.com/ant-research/ace-compiler/blob/master/docs/README.md
Project-URL: Repository, https://github.com/ant-research/ace-compiler
Requires-Python: >=3.12
Requires-Dist: torch>=2.0
Requires-Dist: numpy>=1.20
Requires-Dist: PyYAML>=5.3
Provides-Extra: onnx
Requires-Dist: onnx>=1.10; extra == "onnx"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-xdist; extra == "dev"
Requires-Dist: pytest-dependency; extra == "dev"
Requires-Dist: pytest-benchmark>=4.0; extra == "dev"
Requires-Dist: pytest-regressions>=2.0; extra == "dev"
Requires-Dist: pytest-env; extra == "dev"
Description-Content-Type: text/markdown

# ACE-Compiler: An FHE Domain-Specific Compiler

ACE-Compiler is the compiler component of the ANT-ACE framework. It compiles PyTorch models, Python functions, and ONNX models into optimized FHE ciphertext programs, targeting multiple libraries (CPU/GPU) and encryption schemes (CKKS, TFHE).

Plaintext and FHE computation are seamlessly integrated: write code using familiar PyTorch/ONNX/Python, and the framework automatically converts it to encrypted execution.

## Features

- **Multi-frontend input**: PyTorch (FX trace), Python AST, ONNX file, or via-ONNX conversion
- **Multi-target execution**: CPU (antlib, SEAL, OpenFHE) and GPU (phantom, acelib) targets
- **CKKS scheme support**: Configurable polynomial degree, scaling factor, and multiplication depth
- **One-step or two-step workflow**: `@fhe.compute` for compile+run; `@fhe.compile` for compile-then-run
- **Batch and dataset inference**: Single input, batch parallelism, or full dataset with accuracy metrics
- **CUDA Graph acceleration**: Replay captured GPU execution graph for reduced launch overhead
- **Built-in profiler**: Profile FHE execution with `program.profile()` using torch.profiler

## Quick Start

- One-step: compile and run
```python
import torch
from ace import fhe

@fhe.compute(frontend="torch", library="ant", validate=True)  # device auto-derives from library
def add(x, y):
    return x + y

x = torch.ones(1, 4)
y = torch.ones(1, 4) * 2
result = add(x, y)                  # FHE inference with auto-validation
```

- Two-step: compile first, then run
```python
@fhe.compile(frontend="torch", library="ant")  # device auto-derives from library
def add(x, y):
    return x + y

program = add.compile([x, y])       # Compile
result = program(x, y)              # Run inference
program.validate()                  # Verify correctness
```

- GPU inference with compile options
```python
@fhe.compile(frontend="torch", library="phantom", device="cuda",
             ckks={"N": 65536, "sf": 56})
def add(x, y):
    return x + y

program = add.compile([x, y])
result = program(x, y)
```

- Batch inference with accuracy metrics
```python
program = model.compile([example_input])
result = program.run_dataset(images, labels, top_k=1)
print(f"Top-1 accuracy: {result.top1_accuracy:.2%}")
```

## Compilation Pipeline

![Compilation Pipeline](docs/design/compilation-pipeline.png)

## Installation

### From PyPI (recommended)

```bash
pip install ace-fhe
```

The published wheel bundles the prebuilt runtime and compiler binaries, so
`pip install` is enough to start using ACE on a supported platform — no
source build required.

> **TBD:** the `ace-fhe` PyPI package is being published; until it is
> available, use the from-source build below.

### From source

The compiler backend sources (`compiler/air-infra/`, `compiler/nn-addon/`,
`compiler/fhe-cmplr/`) are included directly in this repository, so a source
build needs no extra credentials or fetches beyond the runtime backends
(phantom / ckks-infra / spdlog), which are pulled from public GitHub at
configure time. See [Developer Guide](docs/dev/develop.md) for the full
workflow:

```bash
./scripts/dev-build.sh                                  # build + install (Release)
python -c "from ace import frontend, runtime; print('OK')"
```

> **Build type defaults:** `./scripts/dev-build.sh` defaults to `Release`,
> while `make` defaults to `Debug`. Both write to the same `build/` directory
> — pick one and stick with it to avoid stale-cache confusion.

> **`libFHErt_common.so not found`?** Set the runtime library path:
> `export LD_LIBRARY_PATH=$(python -c "import sysconfig; print(sysconfig.get_path('platlib'))")/ace/lib:$LD_LIBRARY_PATH`

> **Ant Group internal developers:** building inside the internal network
> needs a `CI_TOKEN`, the internal Docker registry
> (`reg.docker.alibaba-inc.com/ace/...`), and internal git mirrors. See the
> [Internal Onboarding Guide](.aci/ONBOARDING.md).

## API Reference

| API | Description | Details |
|-----|-------------|---------|
| `@fhe.compile` | Compile function/model to FHE program | [Decorators API](docs/api/decorators.md) |
| `@fhe.compute` | Compile and run in one step | [Decorators API](docs/api/decorators.md) |
| `@fhe.export` | Export IR to file (AIR/ONNX) | [Decorators API](docs/api/decorators.md) |
| `program(x, y)` | High-level FHE inference | [Runtime API](docs/api/runtime.md) |
| `program.run_dataset()` | Batch inference with accuracy | [Runtime API](docs/api/runtime.md) |
| `KernelExecutor` | Low-level kernel management, CUDA Graph | [Runtime API](docs/api/runtime.md) |
| `ckks`, `vec`, `p2c`, ... | Compile options | [Compile Options](docs/api/compile-options.md) |

## Libraries

| Library | Device | Binary | Status |
|---------|--------|---------|--------|
| `ant` | CPU | `libFHErt_ant` | Available |
| `phantom` | CUDA | `libFHErt_phantom` | Available |
| `acelib` | CUDA | `libFHErt_ace` | Available |
| `seal` | CPU | Microsoft SEAL | Planned |
| `openfhe` | CPU | OpenFHE | Planned |

## Project Structure

```
ace-compiler/
├── fhe_dsl/                # FHE DSL source (Python + C++)
│   ├── python/             # Python package (installed as `ace-fhe`)
│   └── csrc/               # C++ extension (frontend, runtime)
├── fhe_lib/                # FHE runtime libraries
│   ├── ant/                # antlib (CPU)
│   ├── ace/                # acelib (CUDA)
│   └── common/             # Shared runtime code
├── compiler/               # FHE compiler (fhe_cmplr)
├── examples/               # Example scripts
├── tests/                  # Test suites
└── scripts/                # Build and development scripts
```

## Publications

- **CGO '26** — **FHEFusion**: Enabling Operator Fusion in FHE Compilers for Depth-Efficient DNN Inference
- **OOPSLA '25** — **MetaKernel**: Enabling Efficient Encrypted Neural Network Inference through Unified MVM and Convolution
- **ASPLOS '25** — **ReSBM**: Region-based Scale and Minimal-Level Bootstrapping Management for FHE via Min-Cut
- **CGO '25** — **ANT-ACE**: An FHE Compiler Framework for Automating Neural Network Inference

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for code style, lint setup, and pull request guidelines.

## License

Apache License 2.0 with LLVM-exception
