Design rationale#

This note explains why Venn is built the way it is. The concepts page defines the terms; the benchmark, semantic boundary suite and evidence ledger carry the numbers.

The problem#

Applications that already embed their content keep asking small questions about it: which team owns this ticket, does this passage belong with these others, has the mix of incoming requests changed, which of these indexed records now match a new policy. Each question is cheap to state and expensive to answer with a generative model, and the answer is needed for every item, not once.

The idea#

A Vector Decision Model separates the embedding state from the decisions made over it. A frozen reader encodes content into reusable vectors. A small decision layer then answers typed questions against that state: Choice, Score and Noul (yes/no) for a single item, and nearest reference, set membership, population shift and streamed index decisions for collections. Because the state is reused, a compatible stored representation can serve new questions without another reader pass. Linear heads score collections with a matrix multiplication; outcome lookup and kernel heads use their respective search and prediction paths.

Venn accepts the Decisions API request format used by TypeSafe's Jev for the tested Decisions clients, and adds the space-level question types as extensions those clients can ignore.

What is learned, and where#

The generic head adds one learned "none of these" logit to centered cosine scores and applies fitted temperatures. It is the only trained component in the standard path and is 3 MB.
Families are custom predictors fitted and persisted by the service: residual Choice heads, linear classifiers, numeric ridge or kernel heads, and heads compiled from outcome stores. The reader stays frozen.
Outcome stores learn nothing in weights. The application records a vector, the option it chose and a numerical outcome; later decisions average the outcomes of similar past cases per option. Learning is the growth of the store, which the application owns.

Keeping these three separate makes it clear what changes when behavior changes, and lets the headless outcome path run with no trained head at all.

Space-level methods#

Nearest reference returns the label of the most similar exemplar. Small-set odd-one-out ranks leave-one-out centroid distances. Large-set membership uses fifth-neighbor distances rather than assuming one centroid. Population shift uses a permutation-calibrated RBF MMD test; its p-value is not a probability that drift occurred. Indexed decisions prepare the question once and stream every row rather than returning a top-k.

What this does not give you#

Embeddings are not propositional. Paraphrases, numbers, dates and negation can cross a decision boundary while the intended label stays put; the semantic boundary suite shows this. Conditional probabilities are not universally calibrated. Embeddings can be inverted, so a vector is as sensitive as its text. Venn is therefore a routing and triage layer with an explicit abstention path, not a guardrail or an authorization mechanism.

SetFit fits few-shot classifiers on sentence embeddings. Semantic Router routes by embedding similarity. ColBERT reuses token-level representations with a late interaction step, and MTEB benchmarks embedding models across tasks. Venn's distinct choices are the typed Decisions interface, the explicit abstention head, the space-level question types and the application-owned outcome store. Whether the learned components beat simple baselines on a given task is an empirical question; the evaluation plan lays out the matched comparisons that would settle it.

View this page on GitHub