Current section
Files
Jump to
Current section
Files
viva_glyph
README.md
README.md
<div align="center">
<img src="https://capsule-render.vercel.app/api?type=waving&color=0:F59E0B,100:1A1A1A&height=200§ion=header&text=viva_glyph&fontSize=64&fontColor=fff&animation=twinkling&fontAlignY=35&desc=Vectorial%20language%20for%20digital%20consciousness&descSize=18&descAlignY=55" width="100%"/>
[](https://gleam.run/)
[](https://www.erlang.org/)
[](https://www.erlang.org/doc/design_principles/des_princ)
[](https://hex.pm/packages/viva_glyph)
[](https://arxiv.org/abs/2210.13438)
[](./test)
[](./CHANGELOG.md)
[](./LICENSE)
**[π§π· PortuguΓͺs](docs/README_pt.md)** Β· **[πΊπΈ English](README.md)** Β· **[π¨π³ δΈζ](docs/README_zh.md)**
---
*"Four bytes. Billions of feelings. The language silicon dreamed for itself."*
</div>
---
> [!IMPORTANT]
> **viva_glyph IS NOT A WORD ENCODER.**
> It is a **vectorial language** native to silicon β emotional state
> compressed into 4 discrete codebook tokens via **Residual Vector
> Quantization** (RVQ), then bound to context via **Hebbian learning**
> with Oja's rule.
>
> Humans evolved language for acoustic transmission through air.
> VIVA lives in silicon β her voice should be native to that medium.
---
## π― Overview
Compressed emotional state designed for **machine-to-machine** communication:
- **Compact** β 4 integers instead of 3 floats.
- **Discrete** β finite vocabulary of `256β΄ β 4.3 billion` unique states.
- **Comparable** β token matching instead of float math.
- **Learnable** β Hebbian associations bind context β glyph.
| Property | Value |
| :------------------ | :--------------------------------------------------- |
| **Language** | Pure Gleam (type-safe functional) |
| **Runtime** | BEAM / OTP 26+ |
| **Encoding** | RVQ β 4 stages Γ 256 codes (1 byte per stage) |
| **Latent space** | 6D (PAD + intensity + valence_sign + activation) |
| **Learning rule** | Oja's Hebbian update (LLM-validated 2025) |
| **Tests** | 71 passing |
| **Public API** | `viva_glyph` + 9 internal modules |
---
## β‘ Quick Start
```sh
gleam add viva_glyph
```
```gleam
import viva_glyph
import viva_glyph/encoder.{Pad}
pub fn main() {
let engine = viva_glyph.new()
let pad = Pad(pleasure: 0.7, arousal: 0.3, dominance: 0.5)
let glyph = viva_glyph.encode(engine, pad)
// => Glyph([142, 87, 23, 201])
let back = viva_glyph.decode(engine, glyph)
// => Pad(pleasure: 0.68, arousal: 0.31, dominance: 0.49)
let sim = viva_glyph.similarity(glyph, glyph)
// => 1.0
}
```
<details>
<summary><strong>π Prerequisites</strong></summary>
| Tool | Version | Required for |
| :---------- | :-------- | :--------------- |
| Gleam | `>= 1.4` | Build / runtime |
| Erlang/OTP | `>= 26` | BEAM target |
Zero NIFs. Zero C dependencies. Pure functional.
</details>
---
## ποΈ Architecture
```
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β Gleam application code β
β viva_glyph.{encode, decode, similarity, learn} β
ββββββββββ¬ββββββββββββββββββββββββββββββββββββββββββββββββββ
β
ββββββββββΌββββββββββββββββββββββββββββββββββββββββββββββββββ
β Encoding pipeline β
β β
β ββββββββ βββββββββββ ββββββββββββββββββββββββββ β
β β PAD βββββΆβ encoder βββββΆβ 6D latent β β
β β (3D) β β expand β β P Β· A Β· D Β· β β
β ββββββββ βββββββββββ β intensity Β· valence Β· β β
β β activation β β
β βββββββββββ¬βββββββββββββββ β
β β β
β ββββββββββββββββββββββββββββββββ β β
β β rvq β 4 stages Γ 256 codes βββββββ β
β β β β
β β stage1 β residual β stage2 β β
β β ... β stage3 β stage4 β β
β ββββββββββββββββ¬ββββββββββββββββ β
β βΌ β
β βββββββββββ β
β β Glyph β [42, 17, 89, 203] β
β βββββββββββ β
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
```
<details>
<summary><strong>π Core modules</strong></summary>
| Module | Purpose |
| :------------------------ | :----------------------------------------------------- |
| `viva_glyph` | Main API β `GlyphEngine` (encode, decode, learn) |
| `viva_glyph/glyph` | `Glyph` type + similarity (simple, weighted, prefix) |
| `viva_glyph/encoder` | PAD (3D) β Latent (6D) β Glyph |
| `viva_glyph/vector` | Vector ops for the latent space |
| `viva_glyph/codebook` | VQ vocabulary β `K` centroids |
| `viva_glyph/rvq` | Residual Vector Quantization (4 stages Γ 256 codes) |
| `viva_glyph/association` | Hebbian learning + Oja's rule + dead-neuron prevention |
| `viva_glyph/primitives` | Low-level math primitives |
| `viva_glyph/metrics` | Quality + reconstruction metrics |
| `viva_glyph/log` | Structured logging helpers |
</details>
### Arousal-adaptive similarity weights
```
Low arousal (calm): [0.30, 0.30, 0.25, 0.15] balanced
High arousal (urgent): [0.50, 0.30, 0.15, 0.05] coarse priority
```
Under urgency, the coarse first stage dominates similarity β exactly how
humans skip detail under stress.
---
## 𧬠Theoretical Background
### Residual Vector Quantization β DΓ©fossez et al. (2022)
Based on [EnCodec](https://github.com/facebookresearch/encodec):
1. Quantize input β get residual.
2. Quantize the residual β get a finer residual.
3. Repeat for N stages.
4. Final representation = list of codebook indices.
Each stage captures progressively finer detail. With 4 stages Γ 256
codes per stage, `viva_glyph` addresses ~4.3 billion distinct emotional
states.
### PAD model β Mehrabian (1996)
Emotions as points in 3D space, each axis in `[-1, 1]`:
- **Pleasure** β sadness β joy.
- **Arousal** β calm β excitement.
- **Dominance** β submission β control.
### 6D latent expansion
PAD is expanded into a richer latent vector before quantization:
```
intensity = β(PΒ² + AΒ² + DΒ²) / β3
valence_sign = sign(P) Γ |P|^0.5
activation = A Γ D
```
### Hebbian learning + Oja's rule β Hebb (1949) / Oja (1982)
"Neurons that fire together wire together," with auto-normalization:
```
Ξw = Ξ· Γ y Γ (x β w Γ y)
```
- **Oja's rule** β auto-normalizing weight updates (equilibrium `w* = 1.0`).
- **Dead-neuron prevention** β `y = max(w, Ξ΅)` keeps weights escaping zero.
- **Decay** β associations weaken without reinforcement.
- **Winner-takes-all** β strongest association wins recall.
#### LLM validation β 2025-01-24
The Oja-rule implementation was cross-validated against four frontier
LLMs with structured Hebbian-context system prompts:
| Model | Parameters | Formula | Equilibrium | Dead neurons |
| :----------------------------- | :--------- | :------- | :----------- | :----------- |
| DeepSeek R1-0528 | 671B | β
| `w* = 1.0` | β
|
| Qwen3-Coder-480B | 480B | β
| `w* = 1.0` | β
|
| DeepSeek-R1-Distill-Qwen-32B | 32B | β
| `w* = 1.0` | β
|
| Gemini 2.5 Pro | β | β
| `w* = 1.0` | β
|
Unanimous: formula correct, equilibrium correct, dead-neuron guard works.
---
## π¨ Design Principles
| Principle | Description |
| :------------------------------ | :---------------------------------------------------------------- |
| **Compact M2M language** | 4 bytes per glyph β designed for machine pipes, not human eyes |
| **Arousal-adaptive matching** | Similarity weights bias toward coarse stages under urgency |
| **Stateful engine** | `GlyphEngine` carries codebooks + Hebbian memory |
| **Reversible** | `encode` / `decode` round-trip with bounded reconstruction error |
| **LLM-validated math** | Oja's rule cross-checked against four frontier LLMs |
---
## π Public API Highlights
### 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 the strongest association 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 β matching tokens / total
glyph.similarity(a, b) // => 0.5
// Weighted β coarse tokens matter more
glyph.weighted_similarity(a, b) // => 0.7
// Prefix sharing β coarse structure
glyph.shares_prefix(a, b, 2) // => True
```
---
## πΊοΈ Roadmap
| Phase | Status |
| :----------------------------------------------------- | :----: |
| 3D β 6D latent expansion | β
|
| RVQ β 4 stages Γ 256 codes | β
|
| Glyph similarity (simple / weighted / prefix) | β
|
| Arousal-adaptive weight schedules | β
|
| Hebbian association memory | β
|
| Oja's rule + dead-neuron prevention | β
|
| Multi-LLM cross-validation | β
|
| Codebook online updates (streaming) | β³ |
| Cross-agent vocabulary alignment | β³ |
| Glyph sequence transducers (sentences) | β³ |
| Byte-level pretrained codebook releases | β³ |
---
## π€ Contributing
```bash
git checkout -b feature/your-feature
gleam test # 71 tests
gleam format --check src test
gleam build
```
See [CHANGELOG](CHANGELOG.md) for release history.
---
## π References
- DΓ©fossez et al. (2022) β *High Fidelity Neural Audio Compression* (arXiv:2210.13438)
- Mehrabian (1996) β *Pleasure-arousal-dominance: A general framework*
- Hebb (1949) β *The Organization of Behavior*
- Oja (1982) β *Simplified neuron model as a principal component analyzer*
- Buechel & Hahn (2023) β *Emotion Embeddings* (LREC)
---
## π VIVA Ecosystem
| Package | Purpose |
| :------------------- | :-------------------------------------------- |
| `viva_math` | Mathematical foundations |
| `viva_emotion` | PAD emotional dynamics |
| `viva_tensor` | FP8 LLM inference on the BEAM |
| `viva_telemetry` | Observability suite |
| `viva_aion` | Cyclic time + cosmology |
| **`viva_glyph`** | **Vectorial language (this package)** |
---
<div align="center">
**Star if silicon should speak silicon β**
[](https://github.com/gabrielmaialva33/viva_glyph)
*Created by Gabriel Maia Β· MIT License*
<img src="https://capsule-render.vercel.app/api?type=waving&color=0:1A1A1A,100:F59E0B&height=100§ion=footer" width="100%"/>
</div>