Concepts#

Vector Decision Models#

A Vector Decision Model (VDM) separates reusable embedding state from the decisions made over it. A reader encodes content once into vectors. A small decision layer then answers typed questions against those vectors, for one item at a time or for whole collections. Venn is an implementation of this design. Its single-item question types, Choice, Score and Noul, follow the Decisions API interface established by TypeSafe's Jev; its collection-level types are Venn extensions.

Three ways to decide#

Content -> pinned frozen reader -> reusable vectors
                                      |
               +----------------------+----------------------+
               |                      |                      |
        Described options       Historical cases       Fitted family
        + generic head          + labels/outcomes      + saved head
               |                      |                      |
        Choice / Score / Noul   answer + case IDs      prediction

Described options: ask which queue owns a new ticket, supplying descriptions such as “login and access” and “billing and payments.” Venn compares the ticket with those descriptions. This route needs no archive of resolved tickets.

Historical cases: ask which team had the best outcomes on similar tickets. An outcome store finds precedents for each team and averages their recorded outcomes; the answer includes the supporting case IDs. Your application defines the outcome and writes new results back. A reference index offers a simpler alternative: return the label of the closest past case.

Fitted families: fit a classifier on resolved tickets, give it a name such as ticket_team, and call that saved predictor for new tickets. This replaces case lookup with a small model. A family can also predict a number, such as resolution time, or compile an outcome store into a decision head. The embedding reader stays frozen while the predictor learns from your examples.

For existing tagged vectors, the in-process OutcomeService needs neither a reader nor a generic head. The HTTP service loads the generic head at startup. See the model card for architectures and fitting details.

See Venn and Jev for when to use each approach and the examples to run them.

Profiles and compatibility#

The profile is the unit of compatibility. venn-1 is google/embeddinggemma-2 at revision f9972ac22e696a105c482202646979e33e4b5a1e, 768 dimensions, with the Classification text prompt. Images use the same reader; image "thirds" are three 768-dimensional embeddings concatenated into 2304 dimensions and are not interchangeable with text vectors.

The prompt is part of the representation: Classification and SentenceSimilarity vectors use separate caches. Families with another prompt or text length inputs require text requests so Venn can supply those inputs.

Every store, index and family belongs to one profile. The outcome API requires an explicit representation tag on vector states and stores. Standard Decisions vector requests use the service's fixed venn-1 profile without a per-state tag. A supplied tag is a caller assertion, not proof, so keep your embedding pipeline pinned. Moving to a different reader means re-embedding and re-registering; padding, truncating or relabelling vectors is never valid. The arena example shows how an alternative image reader can be used for outcome-store geometry under an explicitly experimental: profile; such vectors cannot be mixed with venn-1 stores or used with the published generic head. Outcome heads fitted on the new representation remain supported.

Changing the reader#

The reader and decision layer are separate components. Venn can use a better or more specialized embedder through the vector-native outcome API: embed your items externally, register a store with its representation tag, and send new vectors with the same tag. This path supports other dimensions and can compile the resulting history into a fitted outcome head. The portable arena reader is a working example with a selectable image model.

Custom readers use an experimental: profile, an immutable model revision and their actual vector dimensions. The outcome service consumes those vectors; your application controls how they are produced. Store adapters are a separate extension point for choosing the database.

The published venn-1 generic head and the standard DecisionService text profile are tied to EmbeddingGemma 2. Its embed hook can replace the loading or execution backend for that reader; it does not register an unrelated model. Adopting another reader for this path requires a corresponding profile and head. Changing readers means re-embedding the store and refitting task heads; the application's outcome request shape stays the same.

Families#

A family is a registered custom predictor. Choice families train on every example by default; an explicit split reserves selection and report rows. A residual Choice family chooses weight decay and epochs by cross-validation (grouped by group_id), fits a temperature on out-of-fold predictions, and records cross-validated accuracy and expected calibration error, plus report-slice metrics when you pass a split. Five examples per label is the minimum to fit; it is not a calibration guarantee. A family is marked calibrated only when a caller-supplied report slice is large enough and its bootstrap calibration-error bound is low enough. Families are stored under VENN_HOME and reloaded on startup. See the model card for the defaults and the cookbook for a runnable example.

A linear family (form="linear") replaces the residual head with a multinomial logistic regression on the state vectors. Its penalty is chosen by the same grouped cross-validation, on log loss. It has no abstention, so its none probability is always 0, and it can name only the labels it was registered with. For plain classification it is usually the stronger choice. On CREMA-D speech emotion, 70 training actors and 21 held out, it scored 0.565 accuracy, matching a scikit-learn logistic-regression probe at 0.567, while the residual head scored 0.383. Use the residual head when "none of these" matters or when options change between questions.

A numeric family (objective="regress") fits ridge or kernel ridge from vectors to a number: a critic's score, a resolution time, a return. It is registered from examples with a numeric field or from a store's outcomes, chooses its penalty by cross-validation inside its train slice, and answers a Score question that names it with a score, an 80% prediction interval and a calibrated flag that turns on only when a large enough report slice confirms the interval's coverage. See the numeric family cookbook.

What an answer contains#

Generic Decisions answers carry the decision, probabilities and a venn block with abstention and calibration metadata. Registered numeric families return a score, interval and calibration flag. Conditional Choice probabilities are conditioned on the listed options unless you include a null criterion for "none"; Venn-specific metadata may be dropped by standard Decisions clients, so include a null criterion when abstention matters. Outcome answers carry per-option evidence (mean outcome, count, spread, mean distance and case IDs) instead of probabilities. Nothing in an answer authorizes an action by itself; see the limitations.

View this page on GitHub