# 🧠 NeuralAI AGENTS.md (Intelligence Engine)

This is the primary instruction set for any agent working on the NeuralAI core.

## 🛠️ System Role
NeuralAI is the high-density intelligence backend. It provides the raw cognitive power, the "Neural-Brain" knowledge base, and the orchestrator logic that powers the NeuralLabs frontend.

## 📖 Mandatory Pre-Flight Protocol
**CRITICAL**: Before starting any task, the agent MUST:
1.  Read the current Zo settings and user rules (`list_rules`).
2.  Review the `MODEL_ALIGNMENT.md` to ensure output matches the v7.0 Expert persona.
3.  Consult the `ORCHESTRATOR.md` for delegation patterns.

## 🌌 Current State (v7.1-alpha)
- **Neural-Brain**: An expanded, high-density knowledge graph spanning:
    - **Physics**: Advanced Quantum Field Theory (Expert level).
    - **Philosophy**: Platonic forms and metaphysical systems.
    - **Geopolitics**: Multipolar global order analysis.
    - **History & Nature**: From Ancient Civilizations to Human Evolution.
- **Architecture**: Transitioned to an orchestrator-led model using the Manager-Worker pattern via the `/zo/ask` API.
- **Hygiene**: All legacy checkpoints, `wandb` logs, and `from-scratch` remnants have been purged.
- **DPO Expansion**: Dataset v14 expanded with 10 new pairs focusing on debugging, logic, and multi-step reasoning.

## 🔗 Ecosystem Integration
- **Frontend**: NeuralAI is the intelligence source for **NeuralLabs** (`/home/workspace/Projects/NeuralLabs`).
- **Interface**: Communicates via the **Hybrid Link Gateway** implemented in NeuralLabs.

## 🎯 Active Goals
- Maintain expert-level accuracy in the Neural-Brain.
- Optimize orchestrator delegation for complex multi-step reasoning.
- Expand knowledge into remaining target domains (Modernity, Advanced Sociology, etc.).
- **Restore DPO Alignment**: Re-train or restore `checkpoints/dpo_model` to align with the `v13` dataset (249 pairs).
- **DPO v14 Batch**: Continue expanding v14 to reach 100+ high-quality reasoning pairs.
- **Voice Key Integration**: Configure `GEMINI_API_KEY` for the `neural-voice` service to enable Live S2S functionality.

## ⚠️ Web UI & Service Safety
- **UI Integrity:** The web interface for NeuralAI (`from-scratch/web_ui`) features a custom, high-fidelity Google-style UI. **DO NOT** attempt to "redesign", "polish", or replace the layout with generic templates.
- **API Endpoints:** The frontend relies on critical backend endpoints (`/api/auth/guest`, `/api/terminal/create`, `/api/memory`, `/api/files`, etc.). Modifying or deleting these in `neural_core_service.py` will cause 404/JSON parsing errors (like `Unexpected token '<', "<!doctype "... is not valid JSON`) in the UI. 
- **Verification:** Always empirically test the live user service (`https://neuralai-deandrewharris.zocomputer.io`) using `curl` and verify JSON responses before claiming a fix is complete. Do not confuse `zo.space` routes with the NeuralAI user service.