nwf-core 0.2.2

Neural Weight Fields: incremental learning with built-in uncertainty. Charge, Field, metrics, FAISS index, calibrators.

nwf-core

What is NWF?

Neural Weight Fields (NWF) is a principled approach to representing data and knowledge in machine learning. Instead of point embeddings, each object is encoded as a semantic charge (z, Σ):

• z — position vector in latent space (semantic core)
• Σ — diagonal covariance matrix expressing model uncertainty about the object

This pair induces a semantic potential — a function decaying with distance. A collection of charges forms a semantic field — a continuous measure of data density in latent space.

Why NWF?

• Incremental learning without catastrophic forgetting — add new classes by simply adding new charges to the index; no retraining, no knowledge erasure
• Built-in uncertainty — covariance Σ enables calibrated confidence estimates and out-of-distribution (OOD) detection
• Scalability — charges can be indexed with FAISS, HNSW (planned) for millions of objects

---

Installation

pip install nwf-core
# With FAISS: pip install nwf-core[faiss]
# With VAE (torch): pip install nwf-core[torch]
# All: pip install nwf-core[all]

---

Components

Charge

Base data structure: center z and diagonal covariance sigma.

• to_dict() / from_dict() — JSON serialization
• to_vector() — concatenated [z, log(sigma)] for indexing
• whiten(mean, std) — transform to whitened space
• clip_sigma(min_val) — ensure minimum sigma values

Field

Container for charges with labels and ids.

• add(charges, labels, ids) — add charges
• remove(ids) — remove by id
• search(query, k) — k-nearest search (symmetric Mahalanobis)
• save(path) / load(path) — persist to disk
• __iter__ — iterate over (charge, label, id)
• __getitem__(idx) — get charge by index

Metrics

• mahalanobis_symmetric(z1, sigma1, z2, sigma2) — symmetric Mahalanobis distance
• euclidean(z1, z2) — L2 distance
• cosine(z1, z2) — cosine distance

Indices

• BruteForceIndex — exact search for small datasets; supports l2, cosine; batch search
• FAISSIndex — FAISS-backed; metrics l2, cosine, ip; optional two-stage Mahalanobis reranking; save/load

Calibrators

• AgreementRatio — fraction of k-nearest neighbors agreeing with prediction (no training)
• PlattScaler — logistic regression for probability calibration

Encoders (optional, requires torch)

• VAEEncoder — MLP VAE for flat vectors; outputs (z, sigma)

---

Quick start

import numpy as np
from nwf import Charge, Field, mahalanobis_symmetric

# Create charges
c1 = Charge(z=np.array([0.0, 0.0]), sigma=np.array([0.1, 0.1]))
c2 = Charge(z=np.array([1.0, 1.0]), sigma=np.array([0.1, 0.1]))

# Build field and search
field = Field()
field.add([c1, c2], labels=[0, 1])
distances, indices, labels = field.search(c1, k=2)

See documentation and nwf-vision for examples.

---

Development

pip install -e ".[dev,docs]"
pre-commit install
make lint
make format
make html

---

License

MIT

---

nwf-core (Русский)

Что такое NWF?

Neural Weight Fields (Нейровесовые поля) — подход к представлению данных в машинном обучении. Каждый объект кодируется семантическим зарядом (z, Σ):

• z — вектор положения в латентном пространстве (семантическое ядро)
• Σ — диагональная ковариационная матрица (неопределённость модели)

Совокупность зарядов создаёт семантическое поле — непрерывную меру плотности данных.

Преимущества NWF

• Инкрементальность — добавление новых классов без переобучения и забывания
• Встроенная неопределённость — калибровка уверенности и OOD-детекция
• Масштабируемость — индексация через FAISS для миллионов объектов

Установка

pip install nwf-core
# С FAISS: pip install nwf-core[faiss]
# С VAE: pip install nwf-core[torch]

Компоненты

• Charge — заряд (z, sigma), сериализация, whiten, clip_sigma
• Field — контейнер зарядов, add/remove/search, save/load
• Метрики — mahalanobis_symmetric, euclidean, cosine
• Индексы — BruteForceIndex, FAISSIndex (l2, cosine, ip; rerank по Махаланобису)
• Калибраторы — AgreementRatio, PlattScaler
• VAEEncoder — MLP VAE (опционально)

Лицензия

MIT