graysonarts / graysonarts/aboutface

Train a self-organizing map over the Corpus's Embeddings, and persist it

Open
#11 0 comments 0 reactions 0 assignees View on GitHub
ready-for-agent
Dominant language
Rust
Stars
0
Forks
0
PR merge metrics
No merged PRs in 30d

Description

## What to build

The ordering half of ADR-0003, in `aflayout`. A self-organizing map with rectangular lattice topology, trained on the Corpus's Embeddings, whose Node grid supplies a stable spatially coherent arrangement of the Embedding space.

Two properties are the whole reason it is a SOM and not UMAP: it updates incrementally as Faces arrive rather than being re-fit, and it does not rotate or reflect the world when one point is added.

Training state is part of the installation's saved state (ADR-0003). A restart must not reshuffle the wall, so the map is persisted alongside the Corpus and read back on startup. It is keyed on the same `ModelId` the Embeddings carry, because a model change invalidates the map exactly as it invalidates every Embedding (ADR-0006).

Nothing here places anything. Nodes are prototype vectors and many Faces map to one Node. Placement is #12.

Lattice resampling on resize is Stage 3 (ADR-0004) and is deliberately out of scope, but do not make it impossible.

## Acceptance criteria

- [ ] A SOM trains over a set of Embeddings and exposes the prototype at each lattice position
- [ ] Training is incremental: presenting one new Embedding updates the map without a re-fit
- [ ] The map round-trips through persistence unchanged, and a restart produces the same prototypes
- [ ] The map records the `ModelId` it was trained under and refuses Embeddings from another model
- [ ] Quantization error and topographic error are reported, so the ordering can be evaluated on its own
- [ ] Training over a fixed set with a fixed seed is deterministic, and a test asserts it

## Blocked by

- #10

Contributor guide

No contributing guide indexed for this repository

Research direction

Start with ADR-0003 and the #10 dependency, then inspect the `aflayout` ordering components and the Corpus Embeddings/ModelId persistence path. The work is complete when the incremental rectangular SOM trains deterministically, reports both errors, rejects mismatched models, and round-trips unchanged without addressing placement or resize resampling.

Written by the indexing model from the issue text.

Assessment

Tech stack
rust
Domain
machine-learning
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
42/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.