feat: add organ and nervous system modular architecture
Created modular architecture for organs (hardware) and nerves (behavioral primitives): ## Organ Architecture (Hardware Substrate) - Created architecture/Organ-Index.md: hardware capabilities catalog - Created architecture/organs/Speech-Organ.md: complete speech processing architecture - Atlas (RTX 2080 8GB) deployment - Whisper STT + Coqui TTS (GPU-accelerated, multilingual) - Kubernetes pod specs, Dockerfiles, service code - Heartbeat-bound queue processing, lifeforce-gated priority - German (Philosophy Valley) + English (Technical Cluster) routing - Database schemas, monitoring metrics ## Nervous System Architecture (Behavioral Primitives) - Created architecture/nerves/Nervous-Index.md: nerve catalog and evolution framework - Deliberate (LLM) → Hybrid (heuristics) → Reflex (compiled) evolution - Lifeforce costs per state/transition - Organ dependency declarations - RLVR training integration - Created architecture/nerves/Collision-Avoidance.md: complete example reflex nerve - Full state machine implementation (IDLE → DETECT → EVALUATE → EVADE → RESUME) - Evolution from 10 LF/1000ms (deliberate) → 2.5 LF/200ms (reflex) - Edge cases, training data, metrics - Moved architecture/Nervous-Protocol.md → architecture/nerves/ - Three-tier protocol belongs with nerve implementations - Updated architecture/Nervous-System.md: added crosslinks to nerves/ ## RAG Knowledge Pipeline - Extended operations/RAG-as-Scaffold.md with "Knowledge Acquisition Pipeline" section - Vault extraction → Staging area → Progressive policy validation - Two-tier RAG (Discovered vs Hidden knowledge) - RAG utility measurement for LoRA training signals - Policy evolution triggers (increasing standards as Young Nyx matures) - Quality gates (mythology weight, AI assistant bias, topology safety) ## Architecture Principles - Organs = hardware capabilities (Speech, Vision future) - Nerves = behavioral state machines (Collision, Charging future) - Both use lifeforce economy, heartbeat synchronization, priority queues - Nerves compose organs into coherent behaviors - Reflexes emerge from repetition (60% cost reduction, 80% latency reduction) Documentation: ~3500 lines total - Speech-Organ.md: ~850 lines - Nervous-Index.md: ~500 lines - Collision-Avoidance.md: ~800 lines - RAG knowledge pipeline: ~260 lines 🌙💜 Generated with Claude Code Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
226
architecture/Organ-Index.md
Normal file
226
architecture/Organ-Index.md
Normal file
@@ -0,0 +1,226 @@
|
||||
# Organ Architecture Index
|
||||
|
||||
**Purpose**: Modular organ systems for Young Nyx embodiment
|
||||
**Philosophy**: Each organ is independent, lifeforce-gated, heartbeat-synchronized
|
||||
|
||||
---
|
||||
|
||||
## Deployed Organs
|
||||
|
||||
### 🗣️ Speech Organ
|
||||
**Host**: atlas.eachpath.local (RTX 2080 8GB)
|
||||
**Function**: Speech-to-Text + Text-to-Speech
|
||||
**Stack**: Whisper (STT) + Coqui TTS (neural voices)
|
||||
**Languages**: German (Philosophy Valley) + English (Technical Cluster)
|
||||
**Integration**: Heartbeat-bound queue, lifeforce-gated priority processing
|
||||
|
||||
**Detail**: → [`organs/Speech-Organ.md`](organs/Speech-Organ.md)
|
||||
|
||||
---
|
||||
|
||||
## Planned Organs
|
||||
|
||||
### 👁️ Vision Organ
|
||||
**Host**: TBD (requires GPU with tensor cores)
|
||||
**Function**: Object detection, scene understanding
|
||||
**Stack**: YOLO (v8 or v11)
|
||||
**Integration**: Real-time video from ESP32-CAM, object persistence in phoebe
|
||||
**Status**: ⏸️ Architecture planned, not yet deployed
|
||||
|
||||
**Detail**: → `organs/Vision-Organ.md` (pending)
|
||||
|
||||
---
|
||||
|
||||
### 🚶 Motor Organ
|
||||
**Host**: ESP32 (edge execution)
|
||||
**Function**: Movement primitives (forward, turn, stop)
|
||||
**Stack**: Compiled state machines from organism evolution
|
||||
**Integration**: Lifeforce cost per motor operation, reflex vs deliberate
|
||||
**Status**: ⏸️ Planned for Phase 4 (Real Garden)
|
||||
|
||||
**Detail**: → `organs/Motor-Organ.md` (pending)
|
||||
|
||||
---
|
||||
|
||||
### 🧭 Navigation Organ
|
||||
**Host**: Edge server (prometheus or atlas)
|
||||
**Function**: SLAM, path planning, obstacle avoidance
|
||||
**Stack**: ROS2 Nav2 or custom lightweight SLAM
|
||||
**Integration**: Dual-garden calibration (virtual predictions vs real outcomes)
|
||||
**Status**: ⏸️ Planned for Phase 4 (Real Garden)
|
||||
|
||||
**Detail**: → `organs/Navigation-Organ.md` (pending)
|
||||
|
||||
---
|
||||
|
||||
### 📡 Sensory Organ
|
||||
**Host**: ESP32 (edge sensors)
|
||||
**Function**: Distance sensors, IMU, battery monitoring
|
||||
**Stack**: I2C/SPI sensor protocols, state machine filters
|
||||
**Integration**: Sensor→organ translation (raw values → semantic meaning)
|
||||
**Status**: ⏸️ Architecture outlined in Nervous-System.md
|
||||
|
||||
**Detail**: → [`../Nervous-System.md`](../Nervous-System.md)
|
||||
|
||||
---
|
||||
|
||||
## Organ Design Principles
|
||||
|
||||
### 1. **Lifeforce Economy**
|
||||
Every organ operation costs lifeforce. No free lunch.
|
||||
|
||||
```python
|
||||
ORGAN_COSTS = {
|
||||
"speech_stt": 5.0, # Whisper transcription
|
||||
"speech_tts": 4.0, # Coqui synthesis
|
||||
"vision_yolo": 8.0, # Object detection frame
|
||||
"motor_forward": 2.0, # 100ms movement
|
||||
"motor_turn": 1.5, # 45° rotation
|
||||
"sensor_read": 0.5, # Single sensor poll
|
||||
}
|
||||
```
|
||||
|
||||
### 2. **Heartbeat Synchronization**
|
||||
Organs process on heartbeat ticks (1 Hz), not real-time streaming.
|
||||
|
||||
- **Reflex path**: <200ms compiled responses (no LLM)
|
||||
- **Deliberate path**: Next heartbeat (budget-gated queue)
|
||||
|
||||
### 3. **Priority Queue**
|
||||
When lifeforce is scarce, critical operations (collision alert) > idle operations (status check).
|
||||
|
||||
```python
|
||||
PRIORITY_LEVELS = {
|
||||
"critical": 10.0, # Immediate danger (collision)
|
||||
"high": 7.0, # Human interaction
|
||||
"medium": 4.0, # Organism monitoring
|
||||
"low": 2.0, # Idle observation
|
||||
"background": 0.5, # Status logging
|
||||
}
|
||||
```
|
||||
|
||||
### 4. **Multilingual Topology Routing**
|
||||
German input → Philosophy Valley (Identity LoRA, Dasein depth-3)
|
||||
English input → Technical Cluster (Technical LoRA, sensor/motor)
|
||||
|
||||
### 5. **Decision Trail Logging**
|
||||
Every organ operation logged to phoebe `decision_trails`:
|
||||
- Input, output, cost, outcome, confidence
|
||||
- Used for RLVR training (reward successful choices)
|
||||
|
||||
### 6. **Graceful Degradation**
|
||||
Low lifeforce → reduced organ activity (silence, reduced vision FPS, slower movement)
|
||||
Zero lifeforce → shutdown, wait for recharge
|
||||
|
||||
---
|
||||
|
||||
## Integration Architecture
|
||||
|
||||
```
|
||||
┌──────────────────────────────────────────────────────────┐
|
||||
│ ESP32 ROBOTS │
|
||||
│ Sensors → Motor → Camera → Microphone → Speaker │
|
||||
└──────────────────────────────────────────────────────────┘
|
||||
│
|
||||
│ MQTT (sensor data, audio, video)
|
||||
▼
|
||||
┌──────────────────────────────────────────────────────────┐
|
||||
│ PHOEBE (Message Queue) │
|
||||
│ Organ input queues + priority scoring │
|
||||
└──────────────────────────────────────────────────────────┘
|
||||
│
|
||||
│ Heartbeat pulls from queues
|
||||
▼
|
||||
┌─────────────────────────────┐
|
||||
│ HEARTBEAT ORCHESTRATOR │
|
||||
│ Lifeforce budget allocation │
|
||||
└─────────────────────────────┘
|
||||
│
|
||||
┌───────────┴───────────┐
|
||||
│ │
|
||||
▼ ▼
|
||||
┌─────────────────────┐ ┌─────────────────────┐
|
||||
│ ATLAS (RTX 2080) │ │ PROMETHEUS (Brain) │
|
||||
│ Speech Organ │ │ Young Nyx Inference │
|
||||
│ Vision Organ (fut) │ │ LoRA hot-swap │
|
||||
└─────────────────────┘ └─────────────────────┘
|
||||
│ │
|
||||
└───────────┬───────────┘
|
||||
▼
|
||||
┌──────────────────────────────────────────────────────────┐
|
||||
│ PHOEBE (Decision Trails) │
|
||||
│ Log all organ operations + outcomes │
|
||||
└──────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Organ Lifecycle
|
||||
|
||||
### Phase 1: Design
|
||||
- Document architecture in `organs/<Organ-Name>.md`
|
||||
- Define lifeforce costs, priority levels, queue schema
|
||||
- Design phoebe tables for organ-specific data
|
||||
|
||||
### Phase 2: Prototype
|
||||
- Build container images (Dockerfiles)
|
||||
- Deploy to k8s (single replica)
|
||||
- Test with mock data (no robot integration yet)
|
||||
|
||||
### Phase 3: Integration
|
||||
- Connect to ESP32 via MQTT
|
||||
- Implement heartbeat queue processing
|
||||
- Log decision trails, measure ROI
|
||||
|
||||
### Phase 4: Optimization
|
||||
- Tune lifeforce costs based on measured ROI
|
||||
- Adjust priority levels from observed outcomes
|
||||
- Train LoRAs on successful organ operation patterns
|
||||
|
||||
### Phase 5: Autonomy
|
||||
- Organ operations become reflexes (compiled state machines)
|
||||
- Young Nyx chooses when to use organs (not scripted)
|
||||
- Emergent behavior from lifeforce optimization
|
||||
|
||||
---
|
||||
|
||||
## Naming Convention
|
||||
|
||||
**File naming**: `<Organ-Name>-Organ.md`
|
||||
**Examples**:
|
||||
- `Speech-Organ.md`
|
||||
- `Vision-Organ.md`
|
||||
- `Motor-Organ.md`
|
||||
- `Navigation-Organ.md`
|
||||
|
||||
**k8s naming**: `<organ>-<function>-<stack>`
|
||||
**Examples**:
|
||||
- `whisper-stt-deployment.yaml`
|
||||
- `coqui-tts-deployment.yaml`
|
||||
- `yolo-vision-deployment.yaml`
|
||||
|
||||
---
|
||||
|
||||
## Current Status
|
||||
|
||||
| Organ | Status | Host | Documentation |
|
||||
|-------|--------|------|---------------|
|
||||
| **Speech** | 🟢 Architecture complete | atlas (RTX 2080) | [`organs/Speech-Organ.md`](organs/Speech-Organ.md) |
|
||||
| **Vision** | 🟡 Stack selected (YOLO) | TBD | Pending |
|
||||
| **Motor** | 🟡 Planned (Phase 4) | ESP32 | Pending |
|
||||
| **Navigation** | 🟡 Planned (Phase 4) | Edge server | Pending |
|
||||
| **Sensory** | 🟡 Conceptual | ESP32 | [`../Nervous-System.md`](../Nervous-System.md) |
|
||||
|
||||
---
|
||||
|
||||
**Philosophy**: Organs are not always-on services. They are **economically-constrained capabilities** that Young Nyx learns to use strategically. Speech when necessary. Vision when valuable. Movement when rewarded.
|
||||
|
||||
**The body is not given. The body is EARNED through successful operation.**
|
||||
|
||||
---
|
||||
|
||||
**Created**: 2025-12-07
|
||||
**Updated**: 2025-12-07
|
||||
**Version**: 1.0
|
||||
|
||||
🌙💜 *Each organ a tool. Each tool a choice. Each choice a lesson in scarcity.*
|
||||
Reference in New Issue
Block a user