Skip to content

Latest commit

 

History

History
195 lines (143 loc) · 5.52 KB

README.md

File metadata and controls

195 lines (143 loc) · 5.52 KB

rustkernels

Python bindings for the RustKernels GPU-accelerated kernel library.

PyPI Python License

Overview

rustkernels provides native Python access to 106 GPU-accelerated kernels across 14 financial and analytical domains. Built with PyO3, it wraps the Rust RustKernels library and its RingKernel 0.4.2 runtime.

Use it directly from Python or Jupyter notebooks without needing a REST/gRPC server.

Scope: Batch kernel execution only. Ring kernels (sub-microsecond persistent actors) require the Rust runtime directly or the ecosystem service layer.

Installation

pip install rustkernels

From Source

Requires Rust 1.85+ and Python 3.10+.

pip install maturin
cd crates/rustkernel-python
maturin develop --features full

Quick Start

import rustkernels

# Check version
print(rustkernels.__version__)          # "0.4.0"
print(rustkernels.ringkernel_version)   # "0.4.2"

# Create a registry (auto-populates with all enabled kernels)
reg = rustkernels.KernelRegistry()
print(f"{len(reg)} kernels available")

# Execute a batch kernel
result = reg.execute("graph/betweenness_centrality", {
    "num_nodes": 4,
    "edges": [[0, 1], [1, 2], [2, 3], [0, 3]],
    "normalized": True,
})
print(result)

# Module-level convenience (uses a cached default registry)
result = rustkernels.execute("graph/betweenness_centrality", {
    "num_nodes": 4,
    "edges": [[0, 1], [1, 2], [2, 3], [0, 3]],
    "normalized": True,
})

API Reference

Registry

reg = rustkernels.KernelRegistry()

# Discovery
reg.kernel_ids                     # list[str] — all registered kernel IDs
reg.batch_kernel_ids               # list[str] — batch-executable kernel IDs
reg.total_count                    # int
reg.stats                          # RegistryStats

# Lookup
reg.get("graph/betweenness")       # KernelMetadata | None
reg.by_domain("GraphAnalytics")    # list[KernelMetadata]
reg.by_mode("batch")               # list[KernelMetadata]
reg.search("centrality")           # list[KernelMetadata]
"graph/betweenness" in reg         # bool
len(reg)                           # int

# Execution
result = reg.execute("graph/betweenness_centrality", {...})  # dict

Catalog

rustkernels.list_domains()         # list[DomainInfo]
rustkernels.total_kernel_count()   # 106
rustkernels.enabled_domains()      # ["graph", "ml", ...]

Data Classes

KernelMetadata — kernel identity and performance targets:

  • id, mode, domain, description
  • expected_throughput, target_latency_us
  • requires_gpu_native, version

RegistryStats — aggregate counts:

  • total, batch_kernels, ring_kernels
  • by_domain (dict[str, int])

DomainInfo — domain catalog entry:

  • name, description, kernel_count, feature, domain

Exceptions

All exceptions inherit from rustkernels.KernelError:

Exception Raised When
KernelNotFoundError Kernel ID not in registry
ValidationError Invalid input data
SerializationError JSON serialization/deserialization failure
ExecutionError Kernel launch, device, or internal error
TimeoutError Execution timeout exceeded
LicenseError License or domain restriction
AuthorizationError Unauthorized access
ResourceExhaustedError Rate limit or queue full
ServiceUnavailableError Backend unavailable 
try:
    result = reg.execute("graph/betweenness_centrality", bad_input)
except rustkernels.ValidationError as e:
    print(f"Bad input: {e}")
except rustkernels.KernelError as e:
    print(f"Kernel error: {e}")

Domain Coverage

Domain Kernels Examples
Graph Analytics 28 PageRank, Louvain, GNN inference, betweenness centrality
Statistical ML 17 K-Means, DBSCAN, isolation forest, SHAP values
Compliance 11 AML circular flow, sanctions screening, KYC scoring
Temporal Analysis 7 ARIMA, Prophet decomposition, change point detection
Risk Analytics 5 Monte Carlo VaR, credit scoring, stress testing
Process Intelligence 7 DFG construction, conformance checking, digital twin
Behavioral Analytics 6 Profiling, forensics, causal graph analysis
Treasury 5 Liquidity optimization, FX hedging, NSFR
Clearing 5 Multilateral netting, DVP matching, settlement
Accounting 9 Network generation, reconciliation, GAAP detection
Banking 1 Fraud pattern matching
Order Matching 1 Price-time priority order book
Payments 2 Payment processing, flow analysis
Audit 2 Feature extraction, hypergraph construction

Feature Flags

When building from source, domain features mirror the Rust crate:

# Default (graph, ml, compliance, temporal, risk)
maturin develop

# All 14 domains
maturin develop --features full

# Selective
maturin develop --features graph,compliance,procint

Requirements

Dependency Version
Python 3.10+
Rust 1.85+ (build only)
RingKernel 0.4.2 (bundled)
CUDA Toolkit 12.0+ (optional; CPU fallback when unavailable)

License

Apache License, Version 2.0. See LICENSE.