RELATE

The problem

Most embedding applications begin with a useful primitive and then quietly ask it to do too much.

They compute vectors, compare them with cosine or dot product, and then let the resulting rank or threshold stand in for several different claims:

• these two texts mean the same thing;
• this passage verifies the answer;
• this compressed vector preserved the document;
• this upgraded model is compatible with the old one;
• this bridge from one space into another can be used for retrieval, thresholds, or semantic decisions;
• this vector edit changed only the intended property.

Those claims are not the same. Some are about identity. Some are about task behavior. Some are about policy. A single similarity score cannot carry all of them.

Why the obvious approach fails

Raw embedding geometry is only the geometry exposed by a particular model, objective, normalization, and metric. It can be useful without being complete.

The original RELATE result showed the problem in a bounded real-code setting. Frozen CodeBERT embeddings contained recoverable Python structural information: cyclomatic complexity, maximum control nesting depth, and distinct call-site count. A learned ridge projection into those measurable relation coordinates reached 0.7328515625 hard-negative ordering accuracy, while raw cosine reached 0.532458984375 and raw Euclidean reached 0.533314453125.

That result does not prove that embeddings understand code, that relation projection is universally superior, or that every useful relation can be recovered. It proves the narrower and more useful point: a frozen embedding can contain a relation that its default geometry underexposes.

The book generalizes that lesson across retrieval, hard negatives, calibration, space upgrades, bridges, compression, and semantic operators.

The solution

RELATE treats embedding geometry as measured evidence rather than permission.

Its core rule is:

identity is exact
compatibility is measured
usability is policy-scoped

The runtime makes those layers explicit. A vector belongs to a SpaceIdentity. A comparison, bridge, compression, or semantic operator creates evidence. A transformed representation does not become usable merely because it exists; it needs a preservation profile whose verdict passes for the requested scope.

At the smallest level, RELATE can still be used as a compact relation-aware search component:

import numpy as np
from relate import RelationProjection

model = RelationProjection.fit(
    training_embeddings,
    training_relation_coordinates,
    relation_names=("complexity", "depth", "call_sites"),
)

hits = model.search(source_embedding, target_embeddings, k=10)

At the capstone level, RelationProjection becomes one capability inside a larger Observatory runtime.

How it works

RELATE is organized around a measurement spine:

SpaceIdentity
    -> native geometry and retrieval signals
    -> calibration records
    -> cross-space comparisons
    -> bridges and derived spaces
    -> compression profiles
    -> semantic operator profiles
    -> usability verdicts

The important objects are not just vectors. They are the records that say what produced those vectors, what relation was being asked, which reference frame judged the result, and which task scope the evidence authorizes.

The project currently includes:

• a lightweight NumPy runtime under src/relate/;
• relation-aware projection and search;
• space identity and derived-space records;
• cross-space comparison and bridge fitting;
• preservation profiles with usable_for decisions;
• compression and operator evaluation paths;
• calibration and hard-negative scoring utilities;
• corpus releases under corpus/;
• benchmark families under benchmarks/;
• an evidence ledger under evidence/;
• tests that keep the runtime and claims tied together.

Evidence and validation

RELATE is the implementation counterpart of the book’s evidence discipline.

The RELATE-1.0-AUDIT verdict records that the runtime implements the Chapter 26 architecture with stricter machinery than some of the prose currently describes. The audit maps identity, geometry, hard negatives, calibration, bridges, preservation, compression, operators, and lineage back to the book claims.

The evidence map separates four categories:

• HISTORIC: preserved external evidence, not silently recomputed;
• REPRODUCED: a preserved result recomputed through the current evaluator;
• MIRROR: the same observation structure reproduced through production APIs on synthetic or controlled fixtures;
• EXTERNAL: supporting evidence that does not become a new measured claim.

That distinction matters because RELATE is not trying to launder old results into new authority. The original CodeBERT relation result remains bounded historical evidence. New runtime capabilities cite their own records.

Capstone and implementation

In Embeddings From First Principles, the final system is an embedding runtime that can answer questions ordinary vector search leaves implicit:

• what space produced this vector?
• are these two spaces identical, comparable, or incompatible?
• what changed when a representation was translated, compressed, or edited?
• did a bridge recover paired targets or preserve destination neighborhoods?
• which geometry was a transformation trained to preserve?
• does a threshold transfer across models, domains, or negative sets?
• what may this transformed representation be used for?

RELATE is that capstone made inspectable.

The implementation lives at:

https://github.com/ernanhughes/relate

The main code and evidence surfaces are:

src/relate/       runtime package
corpus/           RELATE and RELATE-DOC releases
benchmarks/       capability-organized benchmark families
evidence/         audit and book-to-evidence mapping
space/            Gradio demo assets for the preserved Option B mechanism
tests/            runtime, replay, preservation, and invariant tests

Use it

Install the package from the RELATE checkout:

python -m pip install -e ".[dev]"
pytest

Run the capstone demonstration:

python -m relate.cli demo

For the original relation-aware search component, provide embeddings and measurable relation coordinates, then fit RelationProjection. Embedding generation is deliberately external; RELATE accepts NumPy-compatible arrays from whatever encoder your system already uses.

What comes next

The most important next step is not adding more product surface. It is keeping the book, runtime, corpus releases, and evidence ledger synchronized.

Useful expansions include:

• publishing the Space demo once the final public namespace is chosen;
• making the smallest runnable RELATE entry point obvious from the solution page;
• adding documentation links for each benchmark family;
• extending claim-conditioned checks where embedding geometry cannot see factual reversals;
• adding cost and migration estimates for real re-embedding decisions;
• adding ANN and index instrumentation without confusing index performance with representation measurement.

The destination is a practical embedding infrastructure rule: every operation that changes a representation owes the system a measurement before that representation is trusted.