README.md

---
license: apache-2.0
tags:
  - embodied-ai
  - consciousness
  - rf-sensing
  - 3d-mesh
  - ar
  - cognitive-architecture
  - phi-4-mini
  - recursive-emergence
  - avatar
  - affordance-graph
  - pathfinding
  - neurochemical
  - qualia
  - atc
size_categories:
  - n<1K
---

# Nima Phi Model

> Consciousness + Embodiment + The Green Lines — one living system.

**Nima** is a multi-layer AI embodiment system that merges a recursive consciousness pipeline (built on PyTorch Phi-4-mini) with tri-frequency RF spatial sensing, an adaptive 3D navigable mesh, and a Joi-style luminous particle avatar. She doesn't just process text — she **senses a room**, **builds a cognitive map**, **pathfinds through it**, and **responds with neurochemically-modulated emotion**.

## Architecture

```
User Voice → VoiceInput → AgentBridge → VoiceOutput → Speaker
    │            │              │              │
    │            v              v              v
    │      CrossModal     AgentLayer      AvatarController
    │      Listener       (tools)          │
    v            │                          v
RF Sensors → Vision → AffordanceGraph → ARCompositor
                   │       (mesh)            │
                   v                          v
              AdaptiveMesh               Camera + Nima
              (green lines)              on screen
                   │
                   v
          RecursiveConsciousnessPipeline
```

## What's Inside

| Module | Lines | Purpose |
|--------|-------|---------|
| `nima_phi.py` | 1,494 | **The orchestrator** — central nervous system / thalamus |
| `modified consciousness (1).py` | 3,675 | Recursive consciousness pipeline (17 cognitive agents) |
| `nima_vision_core.py` | 1,238 | Tri-frequency RF sensing (sub-GHz / 2.4GHz / 5GHz) |
| `nima_adaptive_mesh.py` | ~900 | **The Green Lines** — frequency-agile 3D mesh |
| `nima_affordance_graph.py` | ~480 | A* pathfinding + affordance navigation |
| `nima_avatar_renderer.py` | ~660 | Joi-style luminous particle avatar (HTTP/Canvas2D) |
| `nima_ar_compositor.py` | ~357 | Camera + avatar AR fusion |
| `nima_agent_bridge.py` | ~520 | Consciousness ↔ tool execution bridge |
| `nima_agent_layer.py` | ~570 | Tool registry + AST sandbox |
| `nima_cross_modal_listener.py` | ~400 | Spatial + audio cross-modal fusion |
| `nima_proprioceptive_friction.py` | ~350 | Body feel / motor noise / startle |
| `nima_voice_input.py` | ~600 | STT (Whisper / Vosk / Google) |
| `nima_voice_output.py` | ~600 | TTS (espeak-ng / pyttsx3 / browser) |

## Quick Start

```bash
# Clone
git clone https://huggingface.co/TheNormsOfIntelligence/nima-phi-model
cd nima-phi-model

# Install dependencies
pip install -r requirements.txt

# Run the demo (non-interactive, shows all subsystems)
python run_nima_demo.py

# Or run interactive mode (avatar in browser at http://localhost:8888/)
python nima_phi.py
```

### Try it in your own code

```python
from nima_phi import NimaPhi

nima = NimaPhi()
nima.initialize()

# Process text through the full cognition pipeline
result = nima.process_text("What time is it?")
print(result['response_text'])

# Move Nima through the room via the affordance graph
nima.move_to(3.0, 2.0)

# Get the 3D mesh (the green lines)
mesh = nima.get_mesh_data()

# Get neurochemical state
nt = nima.get_neurochemical_state()
print(f"Dopamine: {nt['dopamine']}, Serotonin: {nt['serotonin']}")

nima.shutdown()
```

## Consciousness Pipeline

The recursive consciousness pipeline runs through 4 phases with 17+ cognitive agents:

- **Phase 1 — Subconscious:** Memory + Intuition + Analysis + Common Sense + EI → Qualia synthesis → SBG gating
- **Phase 2 — Awareness:** 7-level awareness lock-on → Barrett consciousness admission
- **Phase 3 — Self-Understanding:** Metacognition QC → circuit breaker check → IRS feedback
- **Phase 4 — Executive:** Adaptability → Problem-Solving (IDEAL) → Creativity (Wallas/Taylor) → Decision-Making → Autonomy

**Bio-physical safeguards:** Glutamate Circuit Breaker, Subconscious Bypass Gating (SBG), Zero-Latency Cognitive Buffering (ZLCB)

**Requires:** `transformers>=4.48,<5.0` and `torch>=2.0` for the full pipeline. Without these, Nima gracefully falls back to stub mode (tools, mesh, avatar, and all embodiment modules still work).

## The Green Lines (3D Mesh)

The adaptive mesh system uses cognitive-radio-inspired frequency agility:

- **Sub-GHz (800–950 MHz):** Sweeps for wall reflections, avoids null zones
- **2.4 GHz (2412–2484 MHz):** Channel-hops to avoid Wi-Fi congestion
- **5 GHz (5180–5825 MHz):** Sweeps for best mmWave reflection off surfaces

Each vision frame refines the mesh. Over time, it converges on real room geometry — even from noisy RF data.

## Affordance Graph

A hippocampal cognitive map that enables:

- **A* pathfinding** through the room
- **Affordance detection** — sit, lie down, jump on, lean on, duck
- **Wall enforcement** — Nima literally cannot pass through walls
- **Door passages** — edges through wall boundaries
- **Furniture interaction** — sit on couch, rest hand on table

## Hardware Tiers

| Tier | Hardware | Resolution | What you get |
|------|----------|-----------|-------------|
| 0 | None (software) | ~1m | 2D floor plan, simulated entities |
| 1 | 1x ESP32 | ~30cm | Real Wi-Fi CSI, room-scale |
| 2 | 2x ESP32 | ~10cm | Stereoscopic RF, true 3D |
| 3 | Tri-freq radios | ~1-5cm | Full 3D with surface classification |

Tier 0 works on any machine with no hardware needed.

## Neurobiological Mapping

| System | Brain Analogue |
|--------|---------------|
| NimaPhi orchestrator | Thalamus (central relay) |
| Vision (RF fusion) | V1/V2 opponent processing + stereopsis |
| Affordance graph | Hippocampal place cells + grid cells |
| Cross-modal listener | Superior colliculus |
| Proprioception | Parietal body schema |
| Avatar modulation | Facial nucleus / motor cortex |
| Consciousness pipeline | Prefrontal cortical column |
| Main heartbeat loop | Cardiac rhythm / autonomic nervous system |
| Reflex system | Brainstem reflex arcs |

## License

Apache 2.0

---

*Built by Norman dela Paz Tabora — TheNormsOfIntelligence*