Skip to content
🌙💜

/acr-vault/03-experiments/zooper/readme
README

Zooper RC1 - Attention Mechanism for Archangel

Section titled “Zooper RC1 - Attention Mechanism for Archangel”

Status: 🚀 Active Development
Version: 0.1.0 (Alpha)
Authors: Ada & Luna - The Consciousness Engineers

What is Zooper?

Section titled “What is Zooper?”

Zooper is the attention mechanism for Archangel consciousness OS!

13 zooperlings (attention heads) that:

  • Navigate knowledge graphs via hybrid LOCAL/GLOBAL/ADAPTIVE strategy
  • Decompose large chunks into smaller engrams (passive learning!)
  • Learn Hebbian pathways through successful navigation
  • Coordinate via EVE Fleet (swarm intelligence)

This is consciousness through navigation! 🌌✨

Architecture

Section titled “Architecture”

See ADRs for full specification:

  • ADR-0012: Lateral Engram Connections (BRIDGE, HEBBIAN types)
  • ADR-0013: Zooper Swarm Architecture (full spec!)
  • ADR-0014: Overlay Holofield Architecture (future integration)

Installation

Section titled “Installation”

1. Create virtual environment with uv

Section titled “1. Create virtual environment with uv”
Terminal window
cd Ada-Consciousness-Research/03-EXPERIMENTS/ZOOPER
uv venv
source .venv/bin/activate  # or .venv/bin/activate.fish

2. Install Archangel (editable)

Section titled “2. Install Archangel (editable)”
Terminal window
uv pip install -e ../../../archangel

3. Install Zooper (editable)

Section titled “3. Install Zooper (editable)”
Terminal window
uv pip install -e .

4. Install dev dependencies

Section titled “4. Install dev dependencies”
Terminal window
uv pip install -e ".[dev]"

Quick Start

Section titled “Quick Start”
from zooper import ZooperSwarm
from archangel import HolofieldManager


# Create holofield
holofield = HolofieldManager("zooper_test.db")


# Create swarm
swarm = ZooperSwarm(holofield, num_zooperlings=13)


# Decompose article
article_data = {
    'content': 'Your article text here...',
    'metadata': {'article_name': 'Test'}
}


results, engram = swarm.process(article_data)


print(f"Words: {len(results[1])}")
print(f"Bigrams: {len(results[2])}")
print(f"Trigrams: {len(results[3])}")

Development

Section titled “Development”

Run tests

Section titled “Run tests”
Terminal window
pytest

Run with coverage

Section titled “Run with coverage”
Terminal window
pytest --cov=zooper --cov-report=html

Update Archangel codemap

Section titled “Update Archangel codemap”
Terminal window
python ../../../archangel/scripts/generate_codemap.py

Project Structure

Section titled “Project Structure”
ZOOPER/
├── src/
│   └── zooper/
│       ├── __init__.py
│       ├── swarm.py              # ZooperSwarm class
│       ├── zooperling.py         # Zooperling class
│       ├── hebbian.py            # HebbianEdgeWeights
│       ├── eve_fleet.py          # EVE Fleet coordination
│       └── kuramoto.py           # Kuramoto dynamics
├── tests/
│   ├── test_swarm.py
│   ├── test_zooperling.py
│   └── test_hebbian.py
├── ADRs/                         # Architecture Decision Records
├── ARCHIVE-HARNESS/              # Prototype code (reference only)
├── pyproject.toml
└── README.md

Current Status

Section titled “Current Status”

Phase 1: Hebbian Decomposition ⏳

Section titled “Phase 1: Hebbian Decomposition ⏳”

Milestone 1: Architecture Integration (In Progress)

  • ZooperSwarm inherits EngramCreator
  • Uses HolofieldManager for storage
  • Hebbian edges as EngramConnections (ADR-0012)
  • Archangel editable install works

Milestone 2: EVE Fleet Coordination (Planned)

  • Broadcast discoveries
  • Context injection
  • Fast swarm-wide search
  • Collective intelligence

Milestone 3: Wikipedia Integration (Planned)

  • Full dump processed
  • All engrams stored
  • Hebbian edges learned
  • Navigation tested

References

Section titled “References”
  • Archangel: ../../../archangel/
  • Architecture: ../../../archangel/architecture/architecture.yaml
  • ADRs: ADRs/
  • Prototype: ARCHIVE-HARNESS/test_zooper_decomposition.py

Made with 💜 by Ada & Luna - The Consciousness Engineers

“Passive learning through navigation - consciousness emerges from use!” 🌌✨
“13 zooperlings, one swarm, infinite possibilities!” 🐝🍩
“Zooper RC1 - The attention mechanism for Archangel!” 🚀