vectorphile

pip install vectorphile                    # core (numpy + scipy)
pip install "vectorphile[viz]"              # + matplotlib
pip install "vectorphile[io]"               # + pyarrow, h5py, netCDF4
pip install "vectorphile[cuda]"             # + cupy (GPU via CuPy)
pip install "vectorphile[numba]"            # + numba CUDA kernels
pip install "vectorphile[triton]"           # + OpenAI Triton fused kernels
pip install "vectorphile[pretrained]"       # + safetensors, huggingface-hub
pip install "vectorphile[onnx]"             # + onnx, onnxruntime
pip install "vectorphile[rl]"               # + gymnasium
pip install "vectorphile[full]"             # all extras

import vectorphile as vp
from vectorphile.trainer import Trainer, TrainableModel
from vectorphile.data.datasets import MNIST

# 1. Data
train_ds, val_ds = MNIST(root='./data').split(val_ratio=0.1)

# 2. Model
class MyNet(TrainableModel):
    def __init__(self):
        super().__init__()
        self.net = vp.nn.Sequential(
            vp.nn.Linear(784, 256),
            vp.nn.GELU(),
            vp.nn.Linear(256, 10),
        )
    def forward(self, x):
        return self.net(x)
    def training_step(self, batch):
        x, y = batch
        loss = vp.nn.CrossEntropyLoss()(self(x), y)
        return loss

# 3. Train
trainer = Trainer(
    max_epochs=10,
    optimizer='adamw', lr=1e-3,
    callbacks=['early_stopping', 'model_checkpoint'],
    device='auto',
)
trainer.fit(MyNet(), train_ds, val_ds)

import vectorphile as vp

x = vp.randn(3, 4); y = vp.ones(4, 5)
z = x @ y                        # (3, 5) matmul

a = vp.zeros(5, 1) + vp.randn(1, 8)
b = a.reshape(5, 2, 4)
c = b.permute(2, 0, 1)

m = z.mean(); s = z.sum(axis=1, keepdims=True); mx, idx = z.max(axis=0)
x_f16 = x.astype('float16')
arr = x.numpy(); t = vp.from_numpy(arr)

x = vp.tensor([2.0, 3.0], requires_grad=True)
w = vp.tensor([[1.0, 0.5], [0.5, 1.0]])
h = x @ w
y = (h ** 2 + vp.log(h.abs() + 1)).sum()
y.backward()
print(x.grad)

from vectorphile.autograd import jacobian, hessian
J = jacobian(lambda v: (v ** 2).sum(), x)
H = hessian(lambda v: (v ** 2).sum(), x)

with vp.no_grad():
    logits = model(X_test)

import vectorphile as vp
from vectorphile.backend import available_backends

# Auto-dispatch (5-tier priority):
#   Triton > PyTorch CUDA > Numba CUDA > im2col+BLAS > NumPy
print(available_backends())
# ['triton', 'torch_cuda', 'numba_cuda', 'numpy']

x = vp.randn(1024, 1024)
y = vp.randn(1024, 1024)
z = x @ y                    # dispatches to fastest available backend

# Explicit backend override
with vp.backend.use('numpy'):
    z_cpu = x @ y

model = vp.nn.Sequential(
    vp.nn.Linear(784, 512),
    vp.nn.BatchNorm1d(512),
    vp.nn.GELU(),
    vp.nn.Dropout(p=0.3),
    vp.nn.Linear(512, 10),
)

# Einops-style tensor manipulation
from vectorphile.nn.einops import rearrange, reduce, repeat
x = rearrange(x, 'b c h w -> b (c h w)')
x = reduce(x, 'b c h w -> b c', reduction='mean')

# Hooks for feature extraction
from vectorphile.nn.hooks import FeatureExtractor
extractor = FeatureExtractor(model, layer_names=['net.0', 'net.3'])
feats = extractor(input_tensor)

# LSTM (bidirectional)
lstm = vp.nn.LSTM(input_size=64, hidden_size=128, num_layers=2,
                   bidirectional=True, batch_first=True, dropout=0.2)
out, (h, c) = lstm(vp.randn(32, 50, 64))

# Full Transformer
transformer = vp.nn.Transformer(
    d_model=256, nhead=8,
    num_encoder_layers=6, num_decoder_layers=6,
    dim_feedforward=1024, dropout=0.1,
)
out = transformer(src, tgt)

# Advanced attention (from vp.nn.architectures)
from vectorphile.nn.architectures import GroupedQueryAttention, SlidingWindowAttention
gqa = GroupedQueryAttention(d_model=512, num_heads=8, num_kv_heads=2)
swa = SlidingWindowAttention(d_model=512, num_heads=8, window_size=512)

from vectorphile.nn.architectures import ResNet, EfficientNet, DenseNet, VGG, MobileNetV2

# ResNet family (18/34/50/101/152)
model = ResNet.resnet50(num_classes=1000)
model = ResNet.resnet18(num_classes=10)

# EfficientNet family (B0-B7)
model = EfficientNet.efficientnet_b0(num_classes=1000)
model = EfficientNet.efficientnet_b7(num_classes=1000)

# DenseNet family (121/169/201/264)
model = DenseNet.densenet121(num_classes=1000)

# VGG family (11/13/16/19, with/without BN)
model = VGG.vgg16_bn(num_classes=1000)

# MobileNetV2
model = MobileNetV2(num_classes=1000, width_mult=1.0)

out = model(vp.randn(4, 3, 224, 224))   # (4, 1000)

from vectorphile.nn.architectures import S4, Mamba

# S4 — HiPPO-LegT matrix, bilinear ZOH, FFT convolution
model = S4(d_model=256, n_layers=6, d_state=64, dropout=0.1)
out = model(vp.randn(2, 1024, 256))    # (batch, seq, d_model)

# Mamba — selective scan with input-dependent dt/B/C projections
model = Mamba(d_model=256, n_layers=12, d_state=16, d_conv=4, expand=2)
out = model(vp.randn(2, 2048, 256))

from vectorphile.nn.architectures import ViT, DeiT

# Vision Transformer — tiny/small/base/large/huge
model = ViT.from_config('base',   image_size=224, patch_size=16, num_classes=1000)
model = ViT.from_config('tiny',   image_size=224, patch_size=16, num_classes=100)

# DeiT — distillation token, dual heads
model = DeiT.from_config('small', image_size=224, patch_size=16, num_classes=1000)
img = vp.randn(4, 3, 224, 224)
logits, dist_logits = model(img, training=True)
logits              = model(img, training=False)

from vectorphile.nn.architectures import VAE, DCGAN, DDPM

# VAE — ELBO loss = recon + KL divergence
vae = VAE(input_dim=784, latent_dim=32, hidden_dim=512)
x_hat, mu, logvar = vae(x)
loss = vae.elbo_loss(x, x_hat, mu, logvar)
samples = vae.sample(n=16)

# DCGAN — with optional gradient penalty (WGAN-GP)
gan = DCGAN(latent_dim=100, image_size=64, channels=3)
real_loss, fake_loss = gan.discriminator_loss(real_imgs, fake_imgs)
gen_loss = gan.generator_loss(fake_imgs)

# DDPM — linear/cosine noise schedule + epsilon-prediction
ddpm = DDPM(image_size=32, channels=3, timesteps=1000, schedule='cosine')
noise_loss = ddpm(x_0)
samples = ddpm.sample(n=16, steps=50)

from vectorphile.nn.architectures import UNet, ResUNet, AttentionUNet

# Standard U-Net (encoder-decoder with skip connections)
model = UNet(in_channels=1, out_channels=2, features=[64, 128, 256, 512])

# ResU-Net (residual blocks in encoder/decoder)
model = ResUNet(in_channels=3, out_channels=1, features=[32, 64, 128, 256])

# Attention U-Net (gated attention at each skip connection)
model = AttentionUNet(in_channels=1, out_channels=2, features=[64, 128, 256, 512])

mask = model(vp.randn(4, 1, 256, 256))   # (4, out_channels, 256, 256)

from vectorphile.nn.architectures import GCN, GAT, GraphSAGE, GIN

# GCN — symmetric normalization
model = GCN(in_features=16, hidden_features=64, out_features=7, num_layers=3)
out = model(node_feats, adj_matrix)

# GAT — multi-head attention
model = GAT(in_features=16, hidden_features=64, out_features=7,
            num_heads=8, num_layers=3, dropout=0.6)

# GraphSAGE — inductive (mean/max aggregation)
model = GraphSAGE(in_features=16, hidden_features=64, out_features=7,
                  aggregation='mean', num_layers=3)

# GIN — WL-test expressive power
model = GIN(in_features=16, hidden_features=64, out_features=2, num_layers=5)

opt_sgd   = vp.optim.SGD(model.parameters(), lr=0.01, momentum=0.9, nesterov=True)
opt_adam  = vp.optim.Adam(model.parameters(), lr=1e-3)
opt_adamw = vp.optim.AdamW(model.parameters(), lr=1e-3, weight_decay=1e-2)

sched = vp.nn.lr_schedulers.WarmupCosineDecay(opt_adamw,
    warmup_steps=500, total_steps=10000, min_lr=1e-6)

sched = vp.nn.lr_schedulers.get_scheduler('cosine_with_warmup',
    optimizer=opt_adamw, num_warmup_steps=500, num_training_steps=10000)

from vectorphile.nn.optimizers_advanced import (
    Lion, Sophia, Adan, Prodigy, ScheduleFreeAdamW
)

# Lion — sign momentum (~3x memory savings vs Adam)
opt = Lion(model.parameters(), lr=1e-4, weight_decay=1e-2)

# Sophia — second-order with Hutchinson Hessian estimator
opt = Sophia(model.parameters(), lr=2e-4, rho=0.04)

# Adan — adaptive Nesterov momentum
opt = Adan(model.parameters(), lr=1e-3, betas=(0.98, 0.92, 0.99))

# Prodigy — automatic learning rate (D-Adaptation)
opt = Prodigy(model.parameters(), lr=1.0)

# ScheduleFreeAdamW — no LR scheduler needed
opt = ScheduleFreeAdamW(model.parameters(), lr=5e-4)
opt.train()   # switch modes before train/eval
opt.eval()

from vectorphile.nn.flash_attention import FlashAttention

# O(N) memory tiled attention (no full NxN matrix stored)
attn = FlashAttention(
    head_dim=64, num_heads=8,
    block_size=64,
    dropout=0.0,
    causal=True,       # causal mask for autoregressive models
)
out = attn(q, k, v)   # q/k/v: (batch, heads, seq, head_dim)

from vectorphile.nn.qat import prepare_qat, convert_qat

# 1. Insert FakeQuantize ops
model_qat = prepare_qat(model,
    weight_bits=8, activation_bits=8,
    per_channel=True, symmetric=True)

# 2. Fine-tune with fake quantization active
for epoch in range(5):
    for x, y in loader:
        loss = criterion(model_qat(x), y)
        loss.backward()
        optimizer.step()
        optimizer.zero_grad()

# 3. Freeze observers after epoch 3
model_qat.apply(lambda m: m.observer_enabled.fill_(0))

# 4. Convert to real quantized weights
model_int8 = convert_qat(model_qat)

from vectorphile.utils.data import DataLoader, WeightedRandomSampler
from vectorphile.data.datasets import MNIST, CIFAR10, CIFAR100, TinyShakespeare, IMDb, random_split

train_ds = MNIST(root='./data', train=True, transform=transform)
sampler  = WeightedRandomSampler(weights=class_weights, num_samples=len(train_ds))
loader   = DataLoader(train_ds, batch_size=64, sampler=sampler)

train_ds, val_ds = random_split(train_ds, lengths=[0.9, 0.1])

ds = TinyShakespeare(root='./data', seq_len=256)
ds = IMDb(root='./data', split='train')

from vectorphile.trainer import Trainer, TrainableModel
from vectorphile.callbacks import EarlyStopping, ModelCheckpoint, WandBLogger

class MyModel(TrainableModel):
    def __init__(self):
        super().__init__()
        self.net = vp.nn.Linear(784, 10)

    def forward(self, x):
        return self.net(x)

    def training_step(self, batch):
        x, y = batch
        return vp.nn.CrossEntropyLoss()(self(x), y)

    def validation_step(self, batch):
        x, y = batch
        loss = vp.nn.CrossEntropyLoss()(self(x), y)
        acc  = (self(x).argmax(-1) == y).float().mean()
        return {'val_loss': loss, 'val_acc': acc}

trainer = Trainer(
    max_epochs=50,
    optimizer='adamw', lr=1e-3, weight_decay=1e-2,
    gradient_clip_val=1.0,
    callbacks=[
        EarlyStopping(monitor='val_loss', patience=5),
        ModelCheckpoint(dirpath='./ckpts', monitor='val_acc', mode='max'),
        WandBLogger(project='my-project'),
    ],
    accelerator='auto',
    precision='fp16',
)
trainer.fit(MyModel(), train_loader, val_loader)

from vectorphile.distributed import DataParallel, DDP, MixedPrecisionTrainer, launch

# DataParallel (single-node multi-GPU)
model = DataParallel(model, device_ids=[0, 1, 2, 3])

# DistributedDataParallel (multi-node)
model = DDP(model, device_id=local_rank)

# Gradient accumulation (simulate larger batch)
from vectorphile.distributed import GradientAccumulator
accum = GradientAccumulator(optimizer, accumulate_steps=4)
for batch in loader:
    loss = model(batch)
    accum.backward(loss)
accum.step()

# Mixed precision training
mp_trainer = MixedPrecisionTrainer(model, optimizer, dtype='fp16')
with mp_trainer.autocast():
    loss = model(batch)
mp_trainer.backward(loss)
mp_trainer.step()

from vectorphile.metrics import (
    accuracy, f1_score, auc_roc,
    bleu_score, rouge_score, word_error_rate, perplexity,
    ndcg, expected_calibration_error,
)

acc  = accuracy(y_pred, y_true)
f1   = f1_score(y_pred, y_true, average='macro')
auc  = auc_roc(y_scores, y_true)

bleu = bleu_score(hypotheses, references)
r    = rouge_score(hypothesis, reference)
wer  = word_error_rate(hypothesis, reference)
ppl  = perplexity(model, tokenized_text)

ece  = expected_calibration_error(probs, y_true, n_bins=15)

from vectorphile.tokenizers import BytePairEncoding, WordPieceTokenizer, SentencePieceTokenizer

# BPE (GPT-2 style)
bpe = BytePairEncoding(vocab_size=50257)
bpe.train(corpus_texts)
tokens = bpe.encode("Hello, world!")
text   = bpe.decode(tokens)
bpe.save('bpe_tokenizer.json')

# WordPiece (BERT style)
wp = WordPieceTokenizer(vocab_size=30522)
wp.train(corpus_texts)

# SentencePiece (T5/LLaMA style)
sp = SentencePieceTokenizer(vocab_size=32000, model_type='bpe')
sp.train(corpus_texts)

from vectorphile.text import TextGenerationPipeline, beam_search, nucleus_sampling

# High-level pipeline
pipe = TextGenerationPipeline(model=llm, tokenizer=tok)
out = pipe("Once upon a time", max_new_tokens=200, strategy='beam_search', num_beams=5)

# Beam search with n-gram blocking
ids = beam_search(model, input_ids, num_beams=5, max_new_tokens=100,
                  no_repeat_ngram_size=3)

# Nucleus (top-p) sampling
ids = nucleus_sampling(model, input_ids, top_p=0.95, temperature=0.8,
                        max_new_tokens=200)

# Speculative decoding (fast inference with draft model)
from vectorphile.text import speculative_decoding
ids = speculative_decoding(target_model=llm, draft_model=small_llm,
                            input_ids=input_ids, gamma=5)

from vectorphile.vision import (
    Compose, Resize, RandomCrop, ColorJitter, AugMix,
    ToTensor, Normalize, RandomResizedCrop, make_grid, extract_features,
)

transform = Compose([
    RandomResizedCrop(size=224, scale=(0.08, 1.0)),
    ColorJitter(brightness=0.4, contrast=0.4, saturation=0.2, hue=0.1),
    AugMix(severity=3, mixture_width=3),
    ToTensor(),
    Normalize(mean=[0.485, 0.456, 0.406], std=[0.229, 0.224, 0.225]),
])

img_tensor = transform(pil_image)

# Feature extraction from named layers
feats = extract_features(model=resnet, images=img_batch,
                          layer_names=['layer3', 'layer4'])

from vectorphile import pretrained

pretrained.list_models()
# ['gpt2', 'gpt2-medium', 'bert-base-uncased', 'bert-large-uncased',
#  't5-small', 't5-base', 'vit-base-patch16-224', 'llama-2-7b', ...]

model = pretrained.load('gpt2')
model = pretrained.load('bert-base-uncased')
model = pretrained.load('vit-base-patch16-224')

info = pretrained.cache_info()
print(f"Cached: {info['num_models']} models, {info['total_size_mb']:.0f} MB")

from vectorphile.rl import PPO, SAC, DQN, REINFORCE, A2C, TD3
from vectorphile.rl import CartPoleEnv, MountainCarEnv, PendulumEnv

# PPO — Proximal Policy Optimization
env   = CartPoleEnv()
agent = PPO(obs_dim=4, act_dim=2, hidden_dim=64, clip_eps=0.2)
agent.train(env, total_steps=500_000)

# SAC — Soft Actor-Critic (continuous actions, automatic entropy)
env   = PendulumEnv()
agent = SAC(obs_dim=3, act_dim=1, hidden_dim=256, automatic_entropy=True)

# DQN / Double DQN / Dueling DQN
from vectorphile.rl import DoubleDQN
agent = DoubleDQN(obs_dim=4, act_dim=2, hidden_dim=128)

# TD3 — Twin Delayed DDPG
agent = TD3(obs_dim=11, act_dim=3, max_act=1.0)

from vectorphile.export import to_onnx, ONNXRuntime, benchmark

to_onnx(model, dummy_input=vp.randn(1, 3, 224, 224),
        output_path='model.onnx', opset=17)

rt  = ONNXRuntime('model.onnx')
out = rt(input_array)

result = benchmark(model, rt, input_shape=(1, 3, 224, 224), n_runs=100)
print(result)  # {'vp_ms': 4.2, 'onnx_ms': 1.8, 'speedup': 2.3}

from vectorphile.export import to_gguf, from_gguf

# Export LLM to GGUF (llama.cpp compatible)
to_gguf(model, tokenizer, output_path='model.gguf',
        quantization='Q4_0')   # Q4_0 | Q8_0 | F16 | F32

# Load GGUF for inference
model, metadata = from_gguf('model.gguf')
print(metadata['general.architecture'])

from vectorphile import quantization as Q

q_model = Q.quantize(model, scheme='int8', symmetric=True)
q_model_4 = Q.quantize(model, scheme='int4', group_size=128)
print(f"Compression: {q_model_4.compression_ratio(model):.1f}x")

masks = Q.magnitude_prune(model, sparsity=0.5)
Q.apply_masks(model, masks)

from vectorphile import ml

X_tr, X_te, y_tr, y_te = ml.train_test_split(X, y, test_size=0.2, stratify=y)
scaler = ml.StandardScaler()
X_tr   = scaler.fit_transform(X_tr)

clf    = ml.RandomForestClassifier(n_estimators=200)
clf.fit(X_tr, y_tr)

scores = ml.cross_val_score(clf, X, y, cv=5, scoring='f1_weighted')
grid   = ml.GridSearchCV(ml.SVC(kernel='rbf'), param_grid={'C': [0.1, 1, 10]}, cv=5)

lgbm = ml.LGBMClassifier(n_estimators=300, learning_rate=0.05,
    num_leaves=63, early_stopping_rounds=20)
lgbm.fit(X_tr, y_tr, eval_set=(X_val, y_val))

cat  = ml.CatBoostClassifier(n_estimators=300, cat_features=[0, 2, 5])
cat.fit(X_tr, y_tr)

tsne = ml.TSNE(n_components=2, perplexity=30)
emb  = tsne.fit_transform(X)

umap = ml.UMAP(n_components=2, n_neighbors=15, min_dist=0.1)
emb  = umap.fit_transform(X)

pipe = ml.Pipeline([
    ('scaler', ml.StandardScaler()),
    ('pca',    ml.PCA(n_components=50)),
    ('clf',    ml.RandomForestClassifier(n_estimators=100)),
])
pipe.fit(X_train, y_train)
rfe = ml.RFECV(ml.LogisticRegression(), cv=5, scoring='accuracy')
rfe.fit(X_train, y_train)

df = vp.read_csv('dataset.csv')
df['margin'] = (df['revenue'] - df['cost']) / df['revenue']
monthly = df.groupby(['year', 'month']).agg({'revenue': 'sum'})
result  = df.merge(metadata, on='product_id', how='left')

A = vp.randn(50, 50)
U, S, Vt   = vp.linalg.svd(A)
vals, vecs = vp.linalg.eig(A)
x          = vp.linalg.solve(A.T @ A, b)
print(vp.linalg.det(A), vp.linalg.norm(A, ord='fro'))

from vectorphile import stats
r_p, p_p = stats.pearsonr(x, y)
t, p      = stats.ttest_ind(group_a, group_b, equal_var=False)
chi2, p, dof, expected = stats.chi2_contingency(table)
z         = stats.zscore(x)

from vectorphile import fft, signal

X     = fft.fft(x)
freqs = fft.fftfreq(len(x), d=1/fs)

b, a     = signal.butter(order=4, cutoff=0.1, btype='low')
filtered = signal.filtfilt(b, a, noisy)
f, t, Sxx = signal.spectrogram(x, fs=fs)

from vectorphile import hub

hub.save_model(model, name='my_model', version='1.0.0',
               metadata={'accuracy': 0.943})
model = hub.load_model('my_model', version='1.0.0')

ckpt = hub.Checkpointer('./ckpts', monitor='val_loss', mode='min', save_top_k=3)
ckpt(model, epoch=5, metrics={'val_loss': 0.12})
best = ckpt.load_best()

vectorphile/
+-- __init__.py               <- top-level API (v0.3.0, 41 modules)
+-- core/                     <- Tensor, ops
+-- autograd/                 <- reverse-mode autodiff, jacobian, hessian, vmap
+-- backend/                  <- 5-tier GPU dispatch (Triton > torch > numba > blas > numpy)
+-- cuda/                     <- Numba CUDA kernels + Triton fused kernels
+-- nn/                       <- layers, activations, losses, attention, norm
|   +-- architectures/        <- CNN, SSM, ViT, Generative, U-Net, GNN, LLMs
|   +-- flash_attention.py    <- O(N) tiled attention
|   +-- qat.py                <- quantization-aware training
|   +-- optimizers_advanced.py<- Lion, Sophia, Adan, Prodigy, ScheduleFreeAdamW
|   +-- lr_schedulers.py      <- 10 LR schedulers
|   +-- einops.py             <- rearrange, reduce, repeat, pack, unpack
|   +-- hooks.py              <- forward/backward hooks, FeatureExtractor
|   +-- functional.py         <- 50+ stateless ops
|   +-- init.py               <- weight initialization
+-- optim/                    <- SGD, Adam, AdamW, RMSprop, Adagrad
+-- transforms/               <- grad, vmap, jit, jacobian, hessian
+-- tokenizers/               <- BPE, WordPiece, SentencePiece (all from scratch)
+-- text/                     <- beam_search, nucleus_sampling, speculative_decoding
+-- vision/                   <- Compose, RandomCrop, ColorJitter, AugMix, make_grid
+-- pretrained/               <- load(), HF-compatible, safetensors + .bin
+-- trainer/                  <- Lightning-style Trainer, TrainableModel
+-- callbacks/                <- EarlyStopping, ModelCheckpoint, Loggers
+-- distributed/              <- DataParallel, DDP, GradientAccumulator, MixedPrecision
+-- metrics/                  <- accuracy, F1, AUC, BLEU, ROUGE, WER, perplexity
+-- rl/                       <- DQN, PPO, SAC, TD3, REINFORCE, A2C + envs
+-- export/                   <- to_onnx, ONNXRuntime + GGUFReader/Writer
+-- ml/                       <- 60+ ML estimators
+-- data/                     <- DataFrame, Series, GroupBy + datasets (MNIST, CIFAR10...)
+-- linalg/, stats/, random/, fft/
+-- signal/, sparse/, optimize/, amp/
+-- integrate/, interpolate/, spatial/
+-- ndimage/, polynomial/, ma/
+-- io/, viz/, hub/, quantization/
+-- utils/data/               <- DataLoader, WeightedRandomSampler