Finite metric spaces as a first-class numerical object.

Why metric-space numerics?

Vector search starts from coordinates and a vector distance. METRIC treats that as one useful specialization rather than the foundation. The modeling step starts with records in their natural form and a metric that expresses the cost of comparing those records.

Once records and a metric are chosen, the dataset is a finite metric space. Embeddings, sparse graphs, search trees, and neural approximators can then be introduced as mappings, representations, or strategies without hiding the metric contract that gives the space its geometry.

The stable public frame is intentionally narrow: compute with metric spaces directly, preserve research breadth behind clear stability labels, and promote algorithms only when assumptions, examples, and tests are explicit.

Engine Model

The engine is organized around one pipeline:

RecordSet + Metric -> MetricSpace -> Intent -> Strategy -> Representation -> Runtime -> Result

API Surface

METRIC separates the current revived core from the target engine facade. Promoted examples use the CI-tested core while the intent-first facade is restored.

• Core Revival API: metrics, C++ `metric::Metric`, C++ `Space::from_records`, C++ `metric::operators`, Python `Space`, `FiniteMetricSpace`, `MatrixSpace`, explicit C++ representations, nearest-neighbor helpers, and intrinsic-dimension diagnostics.
• Target Engine API: broader intent methods, strategies, runtime policies, and result objects.
• Compatibility API: lower-level compatibility names such as `metric::Matrix`, `metric::Tree`, and `metric::KNNGraph`.
• Extension API: custom metrics, representations, strategies, neural modules, and diagnostics.

Stable revival surface means CI-backed metrics, typed C++ metric callables, minimal C++ and Python Space facades, explicit spaces, C++ and Python operator helpers, nearest-neighbor helpers, intrinsic-dimension diagnostics, entropy and MGC examples, and install/export support. Python `metric.mappings` and `metric.transforms` are beta compatibility bridges. Mapping modules, transforms, neural approximators, industrial demos, and broad historical examples stay beta or experimental until deterministic tests and promoted examples cover them.

The repository keeps a path-based module status matrix in docs/stability.md, separating Core Revival APIs from compatibility, beta, experimental, and historical code. Current local revival evidence and remaining external release actions are tracked in docs/revival-status.md.

Python

from metric import Edit, Space

records = ["cat", "cot", "coat", "dog"]
space = Space(records, Edit())

print(space.distance(0, 1))
print(space.neighbors("cut", k=2))

C++

#include <metric/distance.hpp>
#include <metric/space.hpp>
#include <metric/operators.hpp>

std::vector<std::string> records = {"cat", "cot", "coat", "dog"};

auto space = metric::Space::from_records(records, metric::Edit<std::string>{});

auto nearest = space.neighbors(std::string("cut"), 2);
auto distances = metric::operators::pairwise_distance_matrix(records, metric::Edit<std::string>{});

Workflows

1. Choose records and a meaningful metric.
2. Create a finite metric space.
3. Use the current core operators for search, diagnostics, or comparison.
4. Use target intent names and strategies only where the facade is implemented and tested.
5. Use result diagnostics to inspect assumptions, costs, warnings, and lineage.

Source documentation is maintained in the repository under docs/.