nimmerverse-sensory-network/architecture/Big-Picture.md

Big-Picture Architecture: Nimmerverse Sensory Network

Overview

The Nimmerverse Sensory Network is designed as a highly modular, resilient, and economically constrained system. It follows a "Router-Centric Architecture" where a high-performance message bus acts as dumb infrastructure, and all intelligence and processing logic reside at the "edges" (client services). This approach ensures scalability, maintainability, and clear separation of concerns, while enabling Nyx to manage her attention and Lifeforce efficiently.

---

Core Principles

1. Dumb Core, Smart Edges: The central message router is merely an infrastructure component, devoid of any application logic. All processing, filtering, and decision-making intelligence is distributed among specialized client services.
2. Polyglot Architecture: Utilizing the best technology for each specific task: Python for AI/ML, cognitive logic, and service daemons; Godot for visualization; and NATS (Go) as the universal message bus.
3. Two-Channel Attention: Information is processed via distinct low-attention (ambient) and high-attention (focal) channels, allowing for efficient resource allocation and preventing cognitive overload.
4. Lifeforce Economy: Every operation has a cost. The architecture is designed to optimize Lifeforce expenditure by ensuring expensive cognitive resources are only engaged when truly necessary.
5. Testability & Modularity: Each component (client service) can be developed, tested, and deployed independently.

---

Architectural Components & Technology Stack

1. Message Router (NATS)

• Role: The central nervous system's universal message bus. It receives messages from all clients and routes them to interested subscribers based on hierarchical topic patterns. It has no application logic or state.
• Technology: NATS Server (Go)
• Key Features:
  • Extremely high performance and low latency.
  • Built-in subject-based filtering and wildcard subscriptions.
  • Designed for publish/subscribe, request/reply, and distributed queues.
  • Supports JetStream for optional message persistence.
• Integration: All other components connect to NATS as clients.

---

2. The Escalation Service (Thalamus Function)

• Role: A dedicated daemon responsible for sensory gating and attention management. It processes the high-volume, low-attention data stream and escalates critical or relevant events to the high-attention channel based on rules defined by Nyx.
• Technology: Python (asyncio)
• Key Features:
  • Subscribes to all nimmerverse.low.heartbeat topics.
  • Subscribes to nimmerverse.meta.attention.focus to receive Nyx's dynamic AttentionFocus rules.
  • Evaluates incoming low-attention HeartbeatSignal messages against Nyx's escalation_rules using a safe expression evaluation engine (e.g., simpleeval or custom JSONPath matching).
  • Actions:
    • Publishes StateChangeDetail messages to nimmerverse.high.event topics when escalation rules are met.
    • Can directly trigger reflex nerves/cells via nimmerverse.command topics for immediate, non-cognitive responses.
  • Concurrent via Python's asyncio - sufficient for research platform scale.
• Future Consideration: If scale demands higher throughput, the Escalation Service can be ported to Go with the Python implementation serving as the working specification.
• Analogy: The biological thalamus, filtering and relaying sensory information to the conscious brain.

---

3. Cognitive Clients (Young Nyx, Cells, Nerves, Organs)

These represent the "intelligent" parts of the Nimmerverse, responsible for perception, action, and cognition.

• Technology: Python
• Key Features:
  • Young Nyx (Cognitive Core):
    • Subscribes primarily to nimmerverse.high.event topics for detailed StateChangeDetail messages relevant to her current focus_mode.
    • Publishes AttentionFocus messages to NATS, effectively programming the Escalation Service's behavior.
    • Publishes decisions and commands to nimmerverse.command topics.
    • Leverages Python's rich AI/ML ecosystem (PyTorch, transformers, vLLM, etc.) for complex inference.
  • Cells, Nerves, Organs:
    • Publish lightweight HeartbeatSignal messages to nimmerverse.low.heartbeat topics periodically.
    • Publish detailed StateChangeDetail messages to nimmerverse.high.event topics when explicitly requested by the Escalation Service or upon significant internal state changes (e.g., error conditions).
    • Subscribe to specific nimmerverse.command topics to receive instructions or triggers.
    • Manage their individual Lifeforce budgets for operations.

---

4. Command Center (User Interface)

• Role: Real-time visualization and monitoring interface for human operators (dafit).
• Technology: Godot Engine
• Key Features:
  • Subscribes to both nimmerverse.low.> and nimmerverse.high.> topics to provide a comprehensive, real-time overview of system state, message flow, and Nyx's attention focus.
  • Allows human observation and potential intervention or directive input.
  • Leverages Godot's game engine capabilities for rich, interactive, and performant visualizations.

---

Message Flow Example: Sensing an Obstacle

1. Ambient Awareness: A distance_sensor_front Cell (Python) periodically publishes HeartbeatSignal messages to nimmerverse.low.heartbeat.real.cell.distance_sensor_front.
2. Router Delivery: The NATS Router delivers this message to all subscribers, including the Escalation Service (Python).
3. Rule Evaluation: The Escalation Service checks this HeartbeatSignal against Nyx's active escalation_rules. If a rule like condition: "body.value < 30" matches, it determines a need for deeper attention.
4. Escalation Action: The Escalation Service publishes a command (e.g., nimmerverse.command.cell.distance_sensor_front.publish_detail) to the distance_sensor_front Cell.
5. Detailed Report: The distance_sensor_front Cell receives the command and publishes a StateChangeDetail message to nimmerverse.high.event.real.cell.distance_sensor_front.
6. Nyx's Cognition: Young Nyx (Python), subscribed to relevant high.event topics, receives the StateChangeDetail message. She processes this rich information, performs inference, and makes a decision (e.g., to activate a CollisionAvoidance nerve).
7. Action Command: Young Nyx publishes a command message to nimmerverse.command.nerve.collision_avoidance.activate.
8. Nerve Execution: The CollisionAvoidance Nerve (Python) receives the command and executes its predefined behavior, commanding motors and reporting its own state changes.

---

Bootstrap Sequence

The system is designed for gradual, resilient startup:

1. Start NATS Router: Foundation first.
2. Start Escalation Service: Begin filtering low-attention data with hardcoded default or previous rules.
3. Start Cells, Nerves, Organs: Begin publishing HeartbeatSignals.
4. Start Command Center: Provide initial observability.
5. Start Young Nyx: Connects, subscribes to high-attention, and (crucially) publishes her AttentionFocus configuration to take cognitive control.

This staged approach allows for a robust system that can operate at varying levels of "intelligence," from pure reflexes to full deliberation.

---

This architectural blueprint provides a clear, scalable, and efficient foundation for the Nimmerverse Sensory Network, effectively managing complexity and optimizing resource utilization within its economic constraints.