mxframe 0.2.3__tar.gz → 0.3.0__tar.gz

{mxframe-0.2.3 → mxframe-0.3.0}/CHANGELOG.md

@@ -5,6 +5,27 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
 ---
 
+## [0.3.0] — 2026-07-10
+
+### 📚 Docs & Benchmarks
+- README restructured: 543 lines → 119 lines. Intro, quick start, and 4-row teaser only — all detail moved to dedicated docs.
+- New `docs/benchmarks.md`: full 22-query TPC-H tables (1 M + 10 M rows), Mojo kernel catalogue, current limitations, roadmap, and reproduce instructions.
+- New `docs/api.md`: LazyFrame method reference, expression syntax, SQL frontend, supported operations, project structure.
+- `docs/vision-and-architecture.md`: fixed garbled sections 2.5/2.6/3; success criteria table repaired; all milestones marked ✅.
+- `docs/archive/` added to `.gitignore` — old dev notes moved there, not published.
+- All stale `Mojo 0.26.2` / `MAX Graph shape-cached join` references updated to reflect v0.2.3 reality (Mojo 26.4, AOT ctypes everywhere).
+
+### 📊 Benchmark updates
+- Q5/Q7/Q8/Q10/Q13/Q19 re-measured with per-run join-cache clearing (fresh-join). Previous v0.2.0 numbers for those queries were warm join-cache hits.
+- Summary corrected: CPU 20/22 (Q13 loses fresh-join), GPU 12/22 (Q5/Q7 no longer win at 1 M without cache warmup).
+- Q8 GPU marked `—` (MAX Graph `year()` groupby JIT too slow to benchmark; Phase 6 target).
+
+### 🔨 Infrastructure
+- `modular >= 26.4` requirement added to `pyproject.toml` runtime deps and Dependencies table in README.
+- `docs/archive/` gitignored; previously committed archive files removed from history.
+
+---
+
 ## [0.2.3] — 2026-07-09
 
 ### ⚡ Performance

mxframe-0.3.0/PKG-INFO

@@ -0,0 +1,152 @@
+Metadata-Version: 2.4
+Name: mxframe
+Version: 0.3.0
+Summary: GPU-accelerated DataFrame engine: Python ergonomics + Mojo AOT kernels, cross-vendor (NVIDIA/AMD/Apple).
+Author-email: Abhishek Sreesaila <abhisheksreesaila@users.noreply.github.com>
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/abhisheksreesaila/mxframe
+Project-URL: Repository, https://github.com/abhisheksreesaila/mxframe
+Keywords: dataframe,gpu,mojo,arrow,analytics,tpch
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Classifier: Topic :: Database
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: pyarrow>=14.0
+Requires-Dist: numpy>=1.24
+Requires-Dist: pandas>=2.0
+Provides-Extra: runtime
+Requires-Dist: modular>=26.4; extra == "runtime"
+Provides-Extra: polars
+Requires-Dist: polars>=0.20; extra == "polars"
+Provides-Extra: sql
+Requires-Dist: sqlglot>=25.0; extra == "sql"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: polars>=0.20; extra == "dev"
+Requires-Dist: sqlglot>=25.0; extra == "dev"
+Requires-Dist: duckdb>=0.9; extra == "dev"
+
+# 🚀 MXFrame
+
+> **GPU-accelerated DataFrames — Python ergonomics, Mojo speed, every GPU.**
+
+MXFrame is a DataFrame query engine that pairs a Polars-style Python API with
+pre-compiled Mojo AOT kernels. The same code runs on **NVIDIA, AMD, and Apple Silicon** —
+no CUDA required, no JIT compilation at query time.
+
+[![TPC-H](https://img.shields.io/badge/TPC--H-22%2F22%20queries-brightgreen)](docs/benchmarks.md)
+[![Python](https://img.shields.io/badge/python-3.12%2B-blue)](pyproject.toml)
+[![Platform](https://img.shields.io/badge/platform-linux--x86__64-lightgrey)](pyproject.toml)
+[![License](https://img.shields.io/badge/license-Apache%202.0-blue)](LICENSE)
+
+---
+
+## ✨ Why MXFrame?
+
+| | pandas | Polars | cuDF (Rapids) | **MXFrame** |
+|---|---|---|---|---|
+| GPU support | ❌ | ❌ | ✅ NVIDIA only | ✅ **Any GPU** |
+| Compiled kernels | ❌ | ✅ Rust | ✅ CUDA | ✅ **Mojo AOT** |
+| Install complexity | pip | pip | CUDA + Rapids stack | **pixi install** |
+| TPC-H competitive | ❌ | ✅ | ✅ | ✅ |
+| Cross-vendor | ❌ | ❌ | ❌ | ✅ NVIDIA/AMD/Apple |
+
+MXFrame is the **cuDF architecture without the CUDA lock-in**.  
+Kernels are compiled **once** to a `.so` at build time — loaded in ~1 ms, then pure dispatch on every query.
+
+---
+
+## ⚡ Quick Start
+
+```sh
+# 1. Install pixi (Modular's package manager)
+curl -fsSL https://pixi.sh/install.sh | bash
+
+# 2. Clone and set up
+git clone https://github.com/abhisheksreesaila/mxframe
+cd mxframe
+pixi install
+
+# 3. Verify GPU is working
+pixi run python3 scripts/_check_gpu.py
+```
+
+```python
+import pyarrow as pa
+from mxframe import LazyFrame, Scan, col, lit
+
+data = pa.table({
+    "dept":   pa.array(["eng", "eng", "mkt", "mkt", "eng"]),
+    "salary": pa.array([120.0, 95.0, 80.0, 110.0, 130.0], pa.float32()),
+    "age":    pa.array([32, 28, 35, 29, 40], pa.int32()),
+})
+
+result = (
+    LazyFrame(Scan(data))
+    .filter(col("age") > lit(28))
+    .groupby("dept")
+    .agg(
+        col("salary").sum().alias("total_salary"),
+        col("age").count().alias("headcount"),
+    )
+    .sort(col("total_salary"), descending=True)
+    .compute(device="gpu")   # or "cpu"
+)
+print(result.to_pandas())
+```
+
+```
+  dept  total_salary  headcount
+0  eng         345.0          3
+1  mkt         110.0          1
+```
+
+---
+
+## 📊 Performance — TPC-H at 1 M rows *(v0.3.0)*
+
+MX CPU beats Polars on **20/22** queries. GPU advantage compounds at 10 M+ rows where kernel parallelism dominates PCIe upload cost.
+
+| Query | MX CPU | MX GPU | Polars | CPU vs Polars |
+|---|---:|---:|---:|---:|
+| Q9 · Product profit (6-table join) | **0.6 ms** | 6.6 ms | 39.9 ms | **67×** |
+| Q12 · 2-table join + agg           | **0.5 ms** | 3.4 ms | 23.2 ms | **46×** |
+| Q3 · 3-table join + agg            | **2.6 ms** | 8.7 ms | 23.3 ms | **9×** |
+| Q1 · Filter + 8 aggregations       | **10.7 ms** | 42.1 ms | 33.3 ms | **3.1×** |
+
+→ [Full 22-query tables (1 M + 10 M rows), methodology, and reproduce instructions](docs/benchmarks.md)
+
+---
+
+## 📚 Docs
+
+| | |
+|---|---|
+| [**API Reference**](docs/api.md) | LazyFrame, expressions, SQL frontend, supported operations, running tests |
+| [**Benchmarks**](docs/benchmarks.md) | Full TPC-H tables, kernel catalogue, limitations, roadmap, reproduce instructions |
+| [**Architecture**](docs/vision-and-architecture.md) | Design philosophy, internal layers, how MAX Graph fits in |
+| [**Contributing**](CONTRIBUTING.md) | Dev setup, writing Mojo kernels, adding queries |
+
+---
+
+## 📦 Dependencies
+
+| Package | Required | Purpose |
+|---|---|---|
+| `pyarrow >= 14` | ✅ | Column storage, zero-copy NumPy bridge |
+| `numpy >= 1.24` | ✅ | Vectorized pre/post processing |
+| `pandas >= 2.0` | ✅ | Reference implementations |
+| `modular >= 26.4` | GPU only | MAX Engine runtime, Mojo GPU dispatch |
+| `polars >= 0.20` | optional | Benchmark comparison |
+| `sqlglot >= 25` | optional | SQL frontend parsing |
+
+---
+
+## 📄 License
+
+Apache 2.0 — see [LICENSE](LICENSE).

mxframe-0.3.0/README.md

@@ -0,0 +1,119 @@
+# 🚀 MXFrame
+
+> **GPU-accelerated DataFrames — Python ergonomics, Mojo speed, every GPU.**
+
+MXFrame is a DataFrame query engine that pairs a Polars-style Python API with
+pre-compiled Mojo AOT kernels. The same code runs on **NVIDIA, AMD, and Apple Silicon** —
+no CUDA required, no JIT compilation at query time.
+
+[![TPC-H](https://img.shields.io/badge/TPC--H-22%2F22%20queries-brightgreen)](docs/benchmarks.md)
+[![Python](https://img.shields.io/badge/python-3.12%2B-blue)](pyproject.toml)
+[![Platform](https://img.shields.io/badge/platform-linux--x86__64-lightgrey)](pyproject.toml)
+[![License](https://img.shields.io/badge/license-Apache%202.0-blue)](LICENSE)
+
+---
+
+## ✨ Why MXFrame?
+
+| | pandas | Polars | cuDF (Rapids) | **MXFrame** |
+|---|---|---|---|---|
+| GPU support | ❌ | ❌ | ✅ NVIDIA only | ✅ **Any GPU** |
+| Compiled kernels | ❌ | ✅ Rust | ✅ CUDA | ✅ **Mojo AOT** |
+| Install complexity | pip | pip | CUDA + Rapids stack | **pixi install** |
+| TPC-H competitive | ❌ | ✅ | ✅ | ✅ |
+| Cross-vendor | ❌ | ❌ | ❌ | ✅ NVIDIA/AMD/Apple |
+
+MXFrame is the **cuDF architecture without the CUDA lock-in**.  
+Kernels are compiled **once** to a `.so` at build time — loaded in ~1 ms, then pure dispatch on every query.
+
+---
+
+## ⚡ Quick Start
+
+```sh
+# 1. Install pixi (Modular's package manager)
+curl -fsSL https://pixi.sh/install.sh | bash
+
+# 2. Clone and set up
+git clone https://github.com/abhisheksreesaila/mxframe
+cd mxframe
+pixi install
+
+# 3. Verify GPU is working
+pixi run python3 scripts/_check_gpu.py
+```
+
+```python
+import pyarrow as pa
+from mxframe import LazyFrame, Scan, col, lit
+
+data = pa.table({
+    "dept":   pa.array(["eng", "eng", "mkt", "mkt", "eng"]),
+    "salary": pa.array([120.0, 95.0, 80.0, 110.0, 130.0], pa.float32()),
+    "age":    pa.array([32, 28, 35, 29, 40], pa.int32()),
+})
+
+result = (
+    LazyFrame(Scan(data))
+    .filter(col("age") > lit(28))
+    .groupby("dept")
+    .agg(
+        col("salary").sum().alias("total_salary"),
+        col("age").count().alias("headcount"),
+    )
+    .sort(col("total_salary"), descending=True)
+    .compute(device="gpu")   # or "cpu"
+)
+print(result.to_pandas())
+```
+
+```
+  dept  total_salary  headcount
+0  eng         345.0          3
+1  mkt         110.0          1
+```
+
+---
+
+## 📊 Performance — TPC-H at 1 M rows *(v0.3.0)*
+
+MX CPU beats Polars on **20/22** queries. GPU advantage compounds at 10 M+ rows where kernel parallelism dominates PCIe upload cost.
+
+| Query | MX CPU | MX GPU | Polars | CPU vs Polars |
+|---|---:|---:|---:|---:|
+| Q9 · Product profit (6-table join) | **0.6 ms** | 6.6 ms | 39.9 ms | **67×** |
+| Q12 · 2-table join + agg           | **0.5 ms** | 3.4 ms | 23.2 ms | **46×** |
+| Q3 · 3-table join + agg            | **2.6 ms** | 8.7 ms | 23.3 ms | **9×** |
+| Q1 · Filter + 8 aggregations       | **10.7 ms** | 42.1 ms | 33.3 ms | **3.1×** |
+
+→ [Full 22-query tables (1 M + 10 M rows), methodology, and reproduce instructions](docs/benchmarks.md)
+
+---
+
+## 📚 Docs
+
+| | |
+|---|---|
+| [**API Reference**](docs/api.md) | LazyFrame, expressions, SQL frontend, supported operations, running tests |
+| [**Benchmarks**](docs/benchmarks.md) | Full TPC-H tables, kernel catalogue, limitations, roadmap, reproduce instructions |
+| [**Architecture**](docs/vision-and-architecture.md) | Design philosophy, internal layers, how MAX Graph fits in |
+| [**Contributing**](CONTRIBUTING.md) | Dev setup, writing Mojo kernels, adding queries |
+
+---
+
+## 📦 Dependencies
+
+| Package | Required | Purpose |
+|---|---|---|
+| `pyarrow >= 14` | ✅ | Column storage, zero-copy NumPy bridge |
+| `numpy >= 1.24` | ✅ | Vectorized pre/post processing |
+| `pandas >= 2.0` | ✅ | Reference implementations |
+| `modular >= 26.4` | GPU only | MAX Engine runtime, Mojo GPU dispatch |
+| `polars >= 0.20` | optional | Benchmark comparison |
+| `sqlglot >= 25` | optional | SQL frontend parsing |
+
+---
+
+## 📄 License
+
+Apache 2.0 — see [LICENSE](LICENSE).

{mxframe-0.2.3 → mxframe-0.3.0}/__init__.py

@@ -1,6 +1,6 @@
 """mxframe - GPU-accelerated DataFrames with MAX Engine"""
 
-__version__ = "0.2.3"
+__version__ = "0.3.0"
 
 # Lazy expression layer
 from .lazy_expr import Expr, col, lit, when, row_number

{mxframe-0.2.3 → mxframe-0.3.0}/custom_ops.py

@@ -1508,7 +1508,20 @@ class CustomOpsCompiler(GraphCompiler):
         # derived columns (e.g. __cw_0__, __cw_1__ from case_when substitution).
         # Engine slots (__group_ids__, __filter_mask__) live in extra_inputs, not
         # col_arrays, so no exclusion filter is needed here.
-        mini_cols = {k: pa.array(v) for k, v in col_arrays.items()}
+        # Perf: skip string/object dtype columns — they are group keys, not agg
+        # values; converting numpy object arrays (800K strings) to pa.array is O(N)
+        # slow and would dominate hot-call time.
+        mini_cols = {}
+        for k, v in col_arrays.items():
+            if v.dtype.kind in ("f", "i", "u"):   # float, int, uint only
+                mini_cols[k] = pa.array(v)
+            else:
+                # String/object columns: preserve as-is via zero-copy pa.array
+                # (stays as dictionary/string type, no Python iteration needed)
+                try:
+                    mini_cols[k] = pa.array(v, from_pandas=True)
+                except Exception:
+                    pass  # skip columns that can't be converted
         mini_table = pa.table(mini_cols) if mini_cols else None
 
         agg_names: list = []

{mxframe-0.2.3 → mxframe-0.3.0}/docs/vision-and-architecture.md

@@ -182,47 +182,24 @@ LogicalPlan tree  ←── identical to what DataFrame API builds
     │
     ▼  (compiler compiles)
 
-MAX Graph → Mojo kernels → result### 3.1 Syntax — Polars-Inspired, Simplified
-
+MAX Graph → Mojo kernels → result
 ```
 
-## 3. API Design Philosophy
-
-We use [`sqlglot`](https://github.com/tobymao/sqlglot) (already in `pixi.toml`) for parsing.
+We use [`sqlglot`](https://github.com/tobymao/sqlglot) for parsing. It handles SQL dialects, produces a clean AST, and we translate from `sqlglot.Expression` → our `LogicalPlan` nodes.
 
-It handles SQL dialects, produces a clean AST, and we only need to write a---
+**Why this works:** Our `LogicalPlan` is the universal intermediate representation. Whether the user writes DataFrame API or SQL, both produce the same plan tree — the compiler is completely unaware of which frontend was used.
 
-translator from `sqlglot.Expression` → our `LogicalPlan` nodes.
+### 2.6 Why MAX Graph (Not Direct Mojo FFI)?
 
+MAX Graph provides:
 - **Session caching** — compiled graphs are cached, subsequent runs are instant
-
-**Why this works:** Our `LogicalPlan` is the universal intermediate representation.- **Mixed ops** — combine built-in MAX ops with custom Mojo kernels in one graph
-
-Whether the user writes:- **Device placement** — the graph runtime handles CPU↔GPU data transfers
-
+- **Mixed ops** — combine built-in MAX ops with custom Mojo kernels in one graph
+- **Device placement** — the graph runtime handles CPU↔GPU data transfers
 - **Fusion opportunities** — MAX can fuse adjacent ops into single kernel launches
 
-```python- **Automatic memory management** — tensors flow through the graph, no manual alloc/free
-
-# DataFrame APIMAX Graph provides:
-
-df.filter(col('x') > 30).groupby('y').agg(col('z').sum().alias('total')).compute()
-
-### 2.6 Why MAX Graph (Not Direct Mojo FFI)?
-
-# SQL API
-
-mx.sql("SELECT y, sum(z) AS total FROM t WHERE x > 30 GROUP BY y", t=table)completely unaware of which frontend was used.
-
-```The compiler, the Mojo kernels, the GPU dispatch — everything downstream is
-
-
-
-Both produce:```
-
-```        └─ Scan(table)
+## 3. API Design Philosophy
 
-Aggregate(group_by=[col('y')], aggs=[sum(col('z')).alias('total')])    └─ Filter(predicate=col('x') > lit(30))
+### 3.1 Syntax — Polars-Inspired, Simplified
 
 ```python
 import mxframe as mx
@@ -294,11 +271,11 @@ TPC-H has 22 queries. We target them incrementally:
 
 ## 5. Success Criteria
 
-| Milestone | Definition of Done |
-|-----------|-------------------|
-| **v0.1 — Core Pipeline** | `filter` + `select` + `groupby` + `sum/min/max/mean/count` all compile to MAX Graph and produce correct results on CPU |
-| **v0.2 — GPU Path** | Same ops run on GPU with automatic device selection |
-| **v0.3 — TPC-H Q1 & Q6** | Both queries run correctly and beat pandas in speed |
-| **v0.4 — Joins & Sort** | Hash join, sort, limit plan nodes working |
-| **v0.5 — TPC-H Q3** | 3-way join query runs correctly |
-| **v1.0 — Public Release** | 10+ TPC-H queries, docs site, pip-installable, benchmarks published |
+| Milestone | Definition of Done | Status |
+|-----------|-------------------|--------|
+| **v0.1 — Core Pipeline** | `filter` + `select` + `groupby` + `sum/min/max/mean/count` compile to MAX Graph, correct results on CPU | ✅ Done |
+| **v0.2 — GPU Path** | Same ops run on GPU with automatic device selection | ✅ Done |
+| **v0.3 — TPC-H Q1 & Q6** | Both queries run correctly and beat pandas in speed | ✅ Done |
+| **v0.4 — Joins & Sort** | Hash join, sort, limit plan nodes working | ✅ Done |
+| **v0.5 — TPC-H Q3** | 3-way join query runs correctly | ✅ Done |
+| **v1.0 — Public Release** | 22/22 TPC-H queries, docs site, pip-installable, benchmarks published | ✅ **v0.2.3** (22/22 queries, all docs live) |

mxframe-0.3.0/mxframe.egg-info/PKG-INFO

@@ -0,0 +1,152 @@
+Metadata-Version: 2.4
+Name: mxframe
+Version: 0.3.0
+Summary: GPU-accelerated DataFrame engine: Python ergonomics + Mojo AOT kernels, cross-vendor (NVIDIA/AMD/Apple).
+Author-email: Abhishek Sreesaila <abhisheksreesaila@users.noreply.github.com>
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/abhisheksreesaila/mxframe
+Project-URL: Repository, https://github.com/abhisheksreesaila/mxframe
+Keywords: dataframe,gpu,mojo,arrow,analytics,tpch
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Classifier: Topic :: Database
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: pyarrow>=14.0
+Requires-Dist: numpy>=1.24
+Requires-Dist: pandas>=2.0
+Provides-Extra: runtime
+Requires-Dist: modular>=26.4; extra == "runtime"
+Provides-Extra: polars
+Requires-Dist: polars>=0.20; extra == "polars"
+Provides-Extra: sql
+Requires-Dist: sqlglot>=25.0; extra == "sql"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: polars>=0.20; extra == "dev"
+Requires-Dist: sqlglot>=25.0; extra == "dev"
+Requires-Dist: duckdb>=0.9; extra == "dev"
+
+# 🚀 MXFrame
+
+> **GPU-accelerated DataFrames — Python ergonomics, Mojo speed, every GPU.**
+
+MXFrame is a DataFrame query engine that pairs a Polars-style Python API with
+pre-compiled Mojo AOT kernels. The same code runs on **NVIDIA, AMD, and Apple Silicon** —
+no CUDA required, no JIT compilation at query time.
+
+[![TPC-H](https://img.shields.io/badge/TPC--H-22%2F22%20queries-brightgreen)](docs/benchmarks.md)
+[![Python](https://img.shields.io/badge/python-3.12%2B-blue)](pyproject.toml)
+[![Platform](https://img.shields.io/badge/platform-linux--x86__64-lightgrey)](pyproject.toml)
+[![License](https://img.shields.io/badge/license-Apache%202.0-blue)](LICENSE)
+
+---
+
+## ✨ Why MXFrame?
+
+| | pandas | Polars | cuDF (Rapids) | **MXFrame** |
+|---|---|---|---|---|
+| GPU support | ❌ | ❌ | ✅ NVIDIA only | ✅ **Any GPU** |
+| Compiled kernels | ❌ | ✅ Rust | ✅ CUDA | ✅ **Mojo AOT** |
+| Install complexity | pip | pip | CUDA + Rapids stack | **pixi install** |
+| TPC-H competitive | ❌ | ✅ | ✅ | ✅ |
+| Cross-vendor | ❌ | ❌ | ❌ | ✅ NVIDIA/AMD/Apple |
+
+MXFrame is the **cuDF architecture without the CUDA lock-in**.  
+Kernels are compiled **once** to a `.so` at build time — loaded in ~1 ms, then pure dispatch on every query.
+
+---
+
+## ⚡ Quick Start
+
+```sh
+# 1. Install pixi (Modular's package manager)
+curl -fsSL https://pixi.sh/install.sh | bash
+
+# 2. Clone and set up
+git clone https://github.com/abhisheksreesaila/mxframe
+cd mxframe
+pixi install
+
+# 3. Verify GPU is working
+pixi run python3 scripts/_check_gpu.py
+```
+
+```python
+import pyarrow as pa
+from mxframe import LazyFrame, Scan, col, lit
+
+data = pa.table({
+    "dept":   pa.array(["eng", "eng", "mkt", "mkt", "eng"]),
+    "salary": pa.array([120.0, 95.0, 80.0, 110.0, 130.0], pa.float32()),
+    "age":    pa.array([32, 28, 35, 29, 40], pa.int32()),
+})
+
+result = (
+    LazyFrame(Scan(data))
+    .filter(col("age") > lit(28))
+    .groupby("dept")
+    .agg(
+        col("salary").sum().alias("total_salary"),
+        col("age").count().alias("headcount"),
+    )
+    .sort(col("total_salary"), descending=True)
+    .compute(device="gpu")   # or "cpu"
+)
+print(result.to_pandas())
+```
+
+```
+  dept  total_salary  headcount
+0  eng         345.0          3
+1  mkt         110.0          1
+```
+
+---
+
+## 📊 Performance — TPC-H at 1 M rows *(v0.3.0)*
+
+MX CPU beats Polars on **20/22** queries. GPU advantage compounds at 10 M+ rows where kernel parallelism dominates PCIe upload cost.
+
+| Query | MX CPU | MX GPU | Polars | CPU vs Polars |
+|---|---:|---:|---:|---:|
+| Q9 · Product profit (6-table join) | **0.6 ms** | 6.6 ms | 39.9 ms | **67×** |
+| Q12 · 2-table join + agg           | **0.5 ms** | 3.4 ms | 23.2 ms | **46×** |
+| Q3 · 3-table join + agg            | **2.6 ms** | 8.7 ms | 23.3 ms | **9×** |
+| Q1 · Filter + 8 aggregations       | **10.7 ms** | 42.1 ms | 33.3 ms | **3.1×** |
+
+→ [Full 22-query tables (1 M + 10 M rows), methodology, and reproduce instructions](docs/benchmarks.md)
+
+---
+
+## 📚 Docs
+
+| | |
+|---|---|
+| [**API Reference**](docs/api.md) | LazyFrame, expressions, SQL frontend, supported operations, running tests |
+| [**Benchmarks**](docs/benchmarks.md) | Full TPC-H tables, kernel catalogue, limitations, roadmap, reproduce instructions |
+| [**Architecture**](docs/vision-and-architecture.md) | Design philosophy, internal layers, how MAX Graph fits in |
+| [**Contributing**](CONTRIBUTING.md) | Dev setup, writing Mojo kernels, adding queries |
+
+---
+
+## 📦 Dependencies
+
+| Package | Required | Purpose |
+|---|---|---|
+| `pyarrow >= 14` | ✅ | Column storage, zero-copy NumPy bridge |
+| `numpy >= 1.24` | ✅ | Vectorized pre/post processing |
+| `pandas >= 2.0` | ✅ | Reference implementations |
+| `modular >= 26.4` | GPU only | MAX Engine runtime, Mojo GPU dispatch |
+| `polars >= 0.20` | optional | Benchmark comparison |
+| `sqlglot >= 25` | optional | SQL frontend parsing |
+
+---
+
+## 📄 License
+
+Apache 2.0 — see [LICENSE](LICENSE).

{mxframe-0.2.3 → mxframe-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "mxframe"
-version = "0.2.3"
+version = "0.3.0"
 description = "GPU-accelerated DataFrame engine: Python ergonomics + Mojo AOT kernels, cross-vendor (NVIDIA/AMD/Apple)."
 readme = "README.md"
 requires-python = ">=3.12"