Skip to main content

VectorMesh

🤖 Use this course from your coding assistant. These docs, plus a design-from-principles coach and a Ray Tune search coach, are also available as an MCP server, so tools like Claude Code, Cursor, or Claude Desktop can query them directly: /vectormesh:design coaches a design, /vectormesh:search a Ray Tune search. See MCP_SERVER.md.

A PyTorch framework for embed once, reuse many times.

A large pretrained encoder — a BERT-family text model, a vision CNN/ViT, or a hand-written regex feature extractor — is run over a dataset exactly once, by whoever has the hardware and the judgement to pick it. The resulting vectors go to disk as a VectorCache: a versioned, documented artefact. Everything after that trains a small head on those frozen vectors, cheaply enough to run on a laptop CPU.

That split is the point. One embedding job, many models trained against its output — and the interesting design space (fusing representations, gating, mixtures of experts) lives entirely on the cheap side of it.

📚 Documentation

Full documentation is in docs/.

Core concepts The embed-once economics, thinking at the vector level, the 1D/2D/3D tensor-flow ladder
Tensor contracts Shapes as a type system: jaxtyping + beartype, and how to read a shape error
The data layer Vectorizers, VectorCache, metadata, DatasetSchema, collation
Components Every building block, with shapes and when to reach for it
Architectures Composition patterns from a two-line baseline to chunk-level MoE fusion
Training Metrics, loss choice, vectormesh.training.Trainer wiring, the batch scripts
API reference Signature tables for everything exported
Teaching path Notebook-by-notebook map and the questions each one raises
Architecture search Searching architectures with Ray Tune instead of guessing them
Reporters cookbook mlflow/ray/TensorBoard adapters — none of them a vectormesh dependency

Installation

Using the library in your own project:

uv add vectormesh

Working on the library itself, from a clone:

uv sync

Requires Python ≥ 3.12. See pyproject.toml for the full dependency list.

Quick start

from pathlib import Path

import torch
from torch.utils.data import DataLoader

from vectormesh import VectorCache
from vectormesh.components import FixedPadding, MaskedMeanAggregator, NeuralNet, Serial
from vectormesh.data import Collate, OneHot

cache = VectorCache.load(path=Path("artefacts/my_dataset_train"))
# ...or a cache someone else already paid to compute:
# cache = VectorCache.from_hub("pttrn-io/eurosat-dinov2-small", split="train")
# ...and `cache.push_to_hub(repo)` is how one gets published in the first place.
hidden_size = cache.metadata["legal_dutch"]["hidden_size"]

data = cache.dataset.map(OneHot(num_classes=32, label_col="labels", target_col="onehot"))
loader = DataLoader(
    data,
    batch_size=32,
    shuffle=True,
    collate_fn=Collate(
        embedding_col="legal_dutch",
        target_col="onehot",
        padder=FixedPadding(max_chunks=30),
    ),
)

pipeline = Serial([
    MaskedMeanAggregator(),                  # (batch, chunks, dim) -> (batch, dim)
    NeuralNet(hidden_size, out_size=32),     # (batch, dim)         -> (batch, 32)
])

Then hand pipeline and loader to vectormesh.training.Trainer — see Training for the full wiring.

Building a cache instead of loading one, extending a cache with extra feature columns, and the image path are all covered in The data layer.

What's in the box

Data — VectorCache, Vectorizer (chunked text), ImageVectorizer, PatchImageVectorizer, RegexVectorizer, ChunkedRegexVectorizer, DatasetSchema, OneHot, Collate, CollateParallel, LabelEncoder.

Components — architecture forms (Serial, Parallel, Skip, Siamese, JEPA), padding (FixedPadding, DynamicPadding), aggregation (Mean, MaskedMean, Attention, RNN, Last), neural blocks (NeuralNet, Projection, Attention, TransformerBlock), convolution (Conv1D, Pool1D, Conv2D, Pool2D, GlobalPool2D), recurrence (Recurrent), connectors (Concatenate2D, Concatenate3D, ConcatenateSequence, Stack2D), gating (Gate, Highway, MoE, SparseMoE), augmentation (GaussianNoise), metrics in vectormesh.components.metrics (Accuracy, F1Score, MAE, MASE, RepresentationStd).

Training — Trainer, TrainerSettings, EarlyStopping, and the Reporter protocol, from vectormesh.training.

What the library does not hold. It does not fine-tune the encoder: the cache is the boundary. It ships no ray or mlflow helpers either; the integration point is the Reporter protocol, with copy-paste adapters in Architecture search and the Reporters cookbook.

Details and signatures: Components, API reference.

Components by rank

After collation a model works on two ranks: 2D (B, D), one vector per item, and 3D (B, C, D), a sequence per item. A model on images has a third: 4D (B, channels, H, W), PyTorch's image layout, channels second. Every component does one thing to the rank, and its family (components/contracts.py) says which:

What it does to the rank In → out Components Family
keeps it, any rank (works on the last axis) (*lead, D) → (*lead, D') NeuralNet, Projection, Dense, Norm, Activation, Gate, Highway, MoE, SparseMoE, GaussianNoise RankPolymorphicComponent
keeps it, 3D only (B, C, D) → (B, C, D') Attention, TransformerBlock, Recurrent SequenceComponent
keeps it, 3D only; a window may shorten the sequence (B, C, D) → (B, C', D') Conv1D, Pool1D SlidingComponent
keeps it, 4D only (B, channels, H, W) → (B, channels', H', W') Conv2D, Pool2D ImageComponent
lowers it (B, C, D) → (B, D) MeanAggregator, MaskedMeanAggregator, AttentionAggregator, RNNAggregator, LastAggregator BaseAggregator
lowers it, image to vector (B, channels, H, W) → (B, channels) GlobalPool2D none
joins a tuple, keeps the rank (B, D₁), (B, D₂) → (B, D₁+D₂) Concatenate2D Connector
(B, C, D₁), (B, C, D₂) → (B, C, D₁+D₂) Concatenate3D Connector
(B, C₁, D), (B, C₂, D) → (B, C₁+C₂, D) ConcatenateSequence Connector
joins a tuple, raises the rank (B, D), (B, D) → (B, N, D) Stack2D Connector
has no rank of its own that of what it holds Serial, Parallel, Skip, Lift none: architecture forms

Padding sits before all of these: FixedPadding and DynamicPadding turn a list of (C_i, D) items into (B, C, D). The full ladder, from one item to a batch, is in Tensor contracts §2.5–2.6.

Runtime type checking

VectorMesh annotates every forward with jaxtyping shapes, checked at runtime by beartype:

@jaxtyped(typechecker=beartype)
def forward(self, tensors: Float[Tensor, "batch chunks dim"]) -> Float[Tensor, "batch dim"]:
    return tensors.mean(dim=1)

This catches the failure mode that matters most here: nn.Linear accepts any leading shape, so feeding it (batch, chunks, dim) when you meant (batch, dim) raises no error — it just trains a model that quietly answers the wrong question. A BeartypeCallHintParamViolation naming a 3D tensor where a 2D one was expected almost always means a missing aggregator.

How to read those errors: Tensor contracts.

Notebooks

Notebook Topic
0_vectorizer.ipynb Creating vector caches; extending one with regex features
1_training.ipynb Cache → padding → aggregation → pipeline → trained model
2_design.ipynb Parallel branches, fusing two representations, skip connections
3_moe.ipynb Mixture of experts
4_image_vectorizer.ipynb The same pipeline on images; feature-space augmentation

Walkthrough and exercises: Teaching path.

Scripts

Batch counterparts to the notebooks, for real dataset sizes:

uv run python scripts/create_cache_aktes.py    # embeddings
uv run python scripts/add_chunked_regex.py     # + chunk-aligned regex column
uv run python scripts/train_moe_parallel.py    # train

Full list: Training §6.5.

Development

uv run pytest -m "not integration"   # unit tests, no model downloads
uv run pytest                        # everything, downloads HF models
uv run ruff check src tests
uv run ty check

Project structure

src/vectormesh/
├── types.py               # VectorMeshError, Cachable, BaseComponent, TensorInput
├── data/                  # vectorizers, cache, hub, schema, collation
├── components/            # pipelines, padding, aggregation, neural, convolution,
│                          # recurrent, connectors, gating, augmentation, metrics
└── training/              # Trainer, TrainerSettings, EarlyStopping, Reporter
docs/                      # documentation (start at docs/README.md)
notebooks/                 # tutorials, in order
scripts/                   # batch pipelines
references/                # source papers
tests/

Metadata

Release files for vectormesh 0.17.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for vectormesh 0.17.0
File Size Uploaded Provenance Actions
vectormesh-0.17.0.tar.gz 114.2 kB Without provenance Details for vectormesh-0.17.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for vectormesh 0.17.0
File Interpreter ABI Platform Actions
vectormesh-0.17.0-py3-none-any.whl Python 3 none any Details for vectormesh-0.17.0-py3-none-any.whl

Total release size: 192.5 kB

Release files / vectormesh-0.17.0.tar.gz

Download URL vectormesh-0.17.0.tar.gz
Size 114.2 kB
Tags Source
SHA-256 checksum
How to use checksums
d3963fc4b7071f76ab34f1b82af7751d5a431fb7d432437242c32eec187a6754
BLAKE2b-256 checksum
How to use checksums
ced0a9138346c073bb7362244c2ed2604a1acca0d42e9f1315843e5e9979bb36
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.12.3 {"installer":{"name":"uv","version":"0.12.3","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Release files / vectormesh-0.17.0-py3-none-any.whl

Download URL vectormesh-0.17.0-py3-none-any.whl
Size 78.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
3f2fe6659af3c4ddd96398b47f4d0af913039acb9258e95207215623c74dde9b
BLAKE2b-256 checksum
How to use checksums
5813feb869dd309e0687f877222c39d457802987f1071d6df1815c4e1c1bd0a2
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.12.3 {"installer":{"name":"uv","version":"0.12.3","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Security for vectormesh 0.17.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page