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. 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

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, RegexVectorizer, ChunkedRegexVectorizer, DatasetSchema, OneHot, Collate, CollateParallel, LabelEncoder.

Components — architecture forms (Serial, Parallel, Skip), padding (FixedPadding, DynamicPadding), aggregation (Mean, MaskedMean, Attention, RNN), neural blocks (NeuralNet, Projection, Attention, TransformerBlock), connectors (Concatenate2D, Concatenate3D, ConcatenateSequence, Stack2D), gating (Gate, Highway, MoE, SparseMoE), augmentation (GaussianNoise), metrics (Accuracy, F1Score, MAE, MASE).

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. 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, Gate, Highway, MoE, SparseMoE, GaussianNoise RankPolymorphicComponent
keeps it, 3D only (B, C, D) → (B, C, D') Attention, TransformerBlock SequenceComponent
lowers it (B, C, D) → (B, D) MeanAggregator, MaskedMeanAggregator, AttentionAggregator, RNNAggregator BaseAggregator
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, schema, collation
└── components/            # pipelines, padding, aggregation, neural,
                           # connectors, gating, augmentation, metrics
docs/                      # documentation (start at docs/README.md)
notebooks/                 # tutorials, in order
scripts/                   # batch pipelines
references/                # source papers
tests/

Metadata

Release files for vectormesh 0.12.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.12.0
File Size Uploaded Provenance Actions
vectormesh-0.12.0.tar.gz 85.8 kB Without provenance Details for vectormesh-0.12.0.tar.gz

Built distribution (wheel)

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

Total release size: 152.4 kB

Release files / vectormesh-0.12.0.tar.gz

Download URL vectormesh-0.12.0.tar.gz
Size 85.8 kB
Tags Source
SHA-256 checksum
How to use checksums
67a133b8183b93ed7486608c2dd28ca1dc75b321f10c5ec0ef732df0ea94261a
BLAKE2b-256 checksum
How to use checksums
237ed416944fad68d971f603df7d16ab5a4ac78e485818a84a0a2430f1b42657
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.12.0-py3-none-any.whl

Download URL vectormesh-0.12.0-py3-none-any.whl
Size 66.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
2ef786edd106d7ffac7a21a36b7ebb225a12e33e08bfc6db8c3c7388275b1f94
BLAKE2b-256 checksum
How to use checksums
560bb452c0d074b169b6f9a18fb74efd061d5a0ddc14ddf3e82e2a5aa52fd657
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.12.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