graysonarts / graysonarts/aboutface
Train a self-organizing map over the Corpus's Embeddings, and persist it
- 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