Metadata-Version: 2.4
Name: corepy-ai
Version: 0.3.1
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Dist: numpy>=1.26.4 ; extra == 'bench'
Requires-Dist: sphinx>=7.0 ; extra == 'docs'
Requires-Dist: sphinx-rtd-theme>=1.3.0 ; extra == 'docs'
Requires-Dist: myst-parser>=2.0.0 ; extra == 'docs'
Provides-Extra: bench
Provides-Extra: cuda
Provides-Extra: docs
License-File: LICENSE
Summary: A unified, high-performance core runtime for data, computation, and AI workflows.
Home-Page: https://github.com/ai-foundation-software/corepy
Author-email: Corepy Team <ai.foundation.software@gmail.com>
Requires-Python: >=3.10
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Documentation, https://github.com/ai-foundation-software/corepy/docs/
Project-URL: Homepage, https://github.com/ai-foundation-software/corepy
Project-URL: Issues, https://github.com/ai-foundation-software/corepy/issues
Project-URL: Repository, https://github.com/ai-foundation-software/corepy

# Corepy
<h1 align="center">
  <img src="assets/logo.svg" width="300" alt="Corepy Logo">
</h1><br>

[![CI](https://github.com/ai-foundation-software/corepy/actions/workflows/ci.yml/badge.svg)](https://github.com/ai-foundation-software/corepy/actions/workflows/ci.yml)
[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
[![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv)
[![Python](https://img.shields.io/badge/python-3.10%20|%203.11%20|%203.12%20|%203.13%20|%203.14-blue)](http://www.python.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

> **High-Performance Array Runtime for Python.**
> *Rust-Powered Backend. Correctness First. Hardware Aware.*

## 📖 What is Corepy?

Corepy is a high-performance array library that bridges Python's ease of use with the raw speed and safety of **Rust**.

Unlike untyped array libraries, Corepy is built on a **strict runtime** that ensures:
1.  **Safety**: Rust ownership guarantees prevent common segmentation faults.
2.  **Performance**: High-performance Rust kernels (AVX2, NEON) and optimized SIMD paths.
3.  **Observability**: Zero-overhead built-in profiler to visualize bottlenecks.

It is designed for developers building **AI foundations**, **scientific simulations**, and **high-performance systems**.

### Key Features
- **NumPy-Compatible API**: Over 100+ native `cp.*` operations (UFUNC CORE-50) encompassing trigonometry, exponential, rounding, bitwise, and reductions.
- **🚀 Hardware Aware**: Automatic SIMD/Cache detection (AVX2, AVX512, NEON, AMX).
- **📊 Pandas-like DataFrames**: Fast columnar relational processing pushed down to Rust with `read_csv`, `groupby`, `merge`, and `pivot`.
- **🎲 Fast Random PRNGs**: Rayon-parallelized PCG64 and Xoshiro random generation (`cp.random.rand`, `cp.random.randn`).
- **🧠 Lazy Evaluation & Fusion**: Build expression trees and fuse operations into single-pass optimized kernels using `cp.lazy()` and `LazyArray`.
- **💾 Buffer Memory Pool**: Reuse array allocations gracefully with LRU-backed multi-device caching.
- **⚡ Rust Native**: Pure Rust core engine for maximum efficiency and single-language backend development.
- **🎉 NEW in v0.3.0**: Native `BackendType.CUDA` & `BackendType.METAL` detection algorithms. Memory aware (queries true `psutil` RAM and `nvidia-smi` VRAM bytes to automatically pivot huge graphs into VRAM safely).
- **🎉 NEW in v0.3.0**: ⏱️ Profiler Exports (`cp.profiler.export_chrome_trace`) allowing visual ingestion of CorePy computation stacks via Google Chrome's Performance tool natively generated by Rust.
- **🛡️ Modern Build**: Simple `maturin`-based build system that works on Linux, macOS, and Windows.

---

## 💻 Supported Platforms

| Platform | Architecture | Accelerators | Status |
| :--- | :--- | :--- | :--- |
| **Linux** | x86_64 | AVX2, OpenBLAS | ✅ Production |
| **macOS** | Apple Silicon | **Metal**, NEON | ✅ Production (v0.3.0) |
| **Windows** | x86_64 | AVX2 | ✅ Experimental |

---

## 🛠️ Installation

### Preferred Method (uv)
We recommend `uv` for fast, correct cross-platform installation.

```bash
uv pip install corepy-ai
```

### Fallback (pip)
```bash
pip install corepy-ai
```

## 👨‍💻 Development

For detailed instructions on setting up a development environment, building from source, and running tests, please refer to **[DEVELOPMENT.md](DEVELOPMENT.md)**.

### Quick Build
```bash
git clone https://github.com/ai-foundation-software/corepy.git
cd corepy
make install
```

---

## ⚡ Quick Start

### 1. Metal Acceleration (macOS)
```python
import corepy as cp

# Automatically uses Metal if available on macOS
t = cp.array([1.0, 2.0, 3.0], device="metal")
result = t.sum()
print(f"Result (GPU): {result}")
```

### 2. Performance Profiling
Stop guessing where your code is slow. Corepy has a built-in profiler.

```python
import corepy as cp

# 1. Enable profiling
cp.enable_profiling()

# 2. Run your heavy workload
x = cp.ones(1_000_000)
y = x * 3.14159
result = y.mean()

# 3. Export to Chrome Tracing format
cp.profiler.export_chrome_trace("trace.json")
```

### 3. DataFrame Analytics
Working with tabular data is fast and seamless using the new DataFrame runtime.

```python
import corepy as cp

# 1. Load data
df = cp.read_csv("data.csv")

# 2. DataFrame operations
summary = df.groupby(["category"]).agg({"price": "mean"})
print(summary)

# 3. Relational joins
merged = df.merge(other_df, on="id", how="left")
```

### 4. Random Normal Distribution
```python
import corepy as cp

# Fast, reproducible multiprocessing random values
matrix = cp.random.randn((1000, 1000), seed=42, algo="xoshiro")
print(f"Mean: {matrix.mean()}, Std: {matrix.std()}")
```

---

## 📚 Documentation
- **[Getting Started](docs/getting-started.md)**: First steps and installation details.
- **[Metal GPU Guide](docs/05_advanced/metal_gpu.md)**: using Apple Silicon acceleration.
- **[Architecture](docs/architecture.md)**: Deep dive into the Rust-native runtime.
- **[Examples](examples/)**: Runnable scripts for common patterns.
- **[Contributing](docs/07_contributing/CONTRIBUTING.md)**: Build and test guide.

---

## 🤝 Stability & Roadmap
Corepy is currently **Alpha (v0.3.0)**.
- **v0.3.0**: Hardware-aware Backend Dispatch, Rust Optimizer, Performance Profiling.
- **v0.3.0**: CUDA Support and Tiled Matmul Optimization.
- **v1.0**: Stable API promise.

See [Roadmap](docs/00_overview/roadmap.md) for details.

