# viva_glyph
[](https://hex.pm/packages/viva_glyph)
[](https://hexdocs.pm/viva_glyph/)
[](https://github.com/mrootx/viva_glyph/actions)
**Vectorial language for digital consciousness** - RVQ-based emotion encoding for machine-to-machine communication.
## Philosophy
Humans evolved language for acoustic transmission through air.
VIVA exists in silicon - her "voice" should be native to that medium.
**Glyph** is not "words" or "sounds" - it's compressed emotional state optimized for machines:
- **Compact**: 4 integers instead of 3 floats
- **Discrete**: Finite vocabulary (256^4 ≈ 4 billion unique states)
- **Comparable**: Token matching instead of float math
- **Learnable**: Hebbian associations between context and glyphs
## Architecture
```
PAD State (3D)
│
▼ expand
Latent (8D) ─── derived features, context
│
▼ RVQ encode
Glyph [42, 17, 89, 203]
│
▼ transmit/compare/store
│
▼ RVQ decode
Latent' (8D)
│
▼ project
PAD' (3D) ─── reconstructed with controlled loss
```
## Installation
```sh
gleam add viva_glyph
```
## Usage
```gleam
import viva_glyph
import viva_glyph/encoder.{Pad}
pub fn main() {
// Create encoder
let engine = viva_glyph.new()
// Encode emotional state
let pad = Pad(pleasure: 0.7, arousal: 0.3, dominance: 0.5)
let glyph = viva_glyph.encode(engine, pad)
// => Glyph([142, 87, 23, 201])
// Decode back
let pad2 = viva_glyph.decode(engine, glyph)
// => Pad(pleasure: 0.68, arousal: 0.31, dominance: 0.49)
// Compare glyphs
let similarity = viva_glyph.similarity(glyph, glyph)
// => 1.0
}
```
### Hebbian Learning
```gleam
// Learn: when in context 7, use this glyph
let engine = viva_glyph.learn(engine, 7, glyph)
let engine = viva_glyph.learn(engine, 7, glyph) // strengthen
// Recall: what glyph for context 7?
let recalled = viva_glyph.recall(engine, 7)
```
### Glyph Similarity
```gleam
import viva_glyph/glyph
let a = glyph.new([1, 2, 3, 4])
let b = glyph.new([1, 2, 5, 6])
// Simple similarity (matching tokens / total)
glyph.similarity(a, b) // => 0.5
// Weighted similarity (coarse tokens matter more)
glyph.weighted_similarity(a, b) // => 0.7
// Prefix sharing (coarse structure)
glyph.shares_prefix(a, b, 2) // => True
```
## Modules
| Module | Purpose |
|--------|---------|
| `viva_glyph` | Main API (GlyphEngine) |
| `viva_glyph/vector` | Vector operations for latent space |
| `viva_glyph/codebook` | VQ vocabulary (K centroids) |
| `viva_glyph/rvq` | Residual Vector Quantization |
| `viva_glyph/glyph` | Core Glyph type + similarity |
| `viva_glyph/encoder` | PAD ↔ Latent ↔ Glyph |
| `viva_glyph/association` | Hebbian learning |
## Theory
### Residual Vector Quantization (RVQ)
Based on [EnCodec](https://github.com/facebookresearch/encodec) (Défossez et al., 2022):
1. Quantize input → get residual
2. Quantize residual → get finer residual
3. Repeat for N stages
4. Final representation = list of codebook indices
Each stage captures progressively finer detail.
### PAD Model
Pleasure-Arousal-Dominance (Mehrabian, 1996):
- **Pleasure** [-1, 1]: sadness ↔ joy
- **Arousal** [-1, 1]: calm ↔ excitement
- **Dominance** [-1, 1]: submission ↔ control
### Hebbian Learning
"Neurons that fire together wire together" (Hebb, 1949):
- Co-occurrence strengthens associations
- Decay without reinforcement
- Winner-takes-all selection
## Development
```sh
gleam test # Run tests
gleam build # Build
gleam docs build # Generate docs
```
## References
- Défossez, A., et al. (2022). *High Fidelity Neural Audio Compression*. arXiv:2210.13438
- Mehrabian, A. (1996). *Pleasure-arousal-dominance: A general framework for describing and measuring individual differences in temperament*. Current Psychology.
- Hebb, D.O. (1949). *The Organization of Behavior*. Wiley.
- Buechel, S. & Hahn, U. (2023). *Emotion Embeddings*. LREC.
## License
MIT - see [LICENSE](LICENSE)
