Files
hermes-agent/agent/nexus_architect.py
Allegro d9cf77e382 feat: Issue #42 - Nexus Architect for autonomous Three.js world building
Implement Phase 31: Autonomous 'Nexus' Expansion & Architecture

DELIVERABLES:
- agent/nexus_architect.py: AI agent for natural language to Three.js conversion
  * Prompt engineering for LLM-driven immersive environment generation
  * Mental state integration for dynamic aesthetic tuning
  * Mood preset system (contemplative, energetic, mysterious, etc.)
  * Room and portal design generation

- tools/nexus_build_tool.py: Build tool interface with functions:
  * create_room(name, description, style) - Generate room modules
  * create_portal(from_room, to_room, style) - Generate portal connections
  * add_lighting(room, type, color, intensity) - Add Three.js lighting
  * add_geometry(room, shape, position, material) - Add 3D objects
  * generate_scene_from_mood(mood_description) - Mood-based generation
  * deploy_nexus_module(module_code, test=True) - Deploy and test

- agent/nexus_deployment.py: Real-time deployment system
  * Hot-reload Three.js modules without page refresh
  * Validation (syntax check, Three.js API compliance)
  * Rollback on error with version history
  * Module versioning and status tracking

- config/nexus-templates/: Template library
  * base_room.js - Base room template (Three.js r128+)
  * portal_template.js - Portal template (circular, rectangular, stargate)
  * lighting_presets.json - Warm, cool, dramatic, serene, crystalline presets
  * material_presets.json - 15 material presets including Timmy's gold, Allegro blue

- tests/test_nexus_architect.py: Comprehensive test coverage
  * Unit tests for all components
  * Integration tests for full workflow
  * Template file validation

DESIGN PRINCIPLES:
- Modular architecture (each room = separate JS module)
- Valid Three.js code (r128+ compatible)
- Hot-reloadable (no page refresh needed)
- Mental state integration (SOUL.md values influence aesthetic)

NEXUS AESTHETIC GUIDELINES:
- Timmy's color: warm gold (#D4AF37)
- Allegro's color: motion blue (#4A90E2)
- Sovereignty theme: crystalline structures, clean lines
- Service theme: open spaces, welcoming lighting
- Default mood: contemplative, expansive, hopeful
2026-04-01 02:45:36 +00:00

814 lines
27 KiB
Python

#!/usr/bin/env python3
"""
Nexus Architect AI Agent
Autonomous Three.js world generation system for Timmy's Nexus.
Generates valid Three.js scene code from natural language descriptions
and mental state integration.
This module provides:
- LLM-driven immersive environment generation
- Mental state integration for aesthetic tuning
- Three.js code generation with validation
- Scene composition from mood descriptions
"""
import json
import logging
import re
from typing import Dict, Any, List, Optional, Union
from dataclasses import dataclass, field
from enum import Enum
import os
import sys
# Add parent directory to path for imports
sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
logger = logging.getLogger(__name__)
# =============================================================================
# Aesthetic Constants (from SOUL.md values)
# =============================================================================
class NexusColors:
"""Nexus color palette based on SOUL.md values."""
TIMMY_GOLD = "#D4AF37" # Warm gold
ALLEGRO_BLUE = "#4A90E2" # Motion blue
SOVEREIGNTY_CRYSTAL = "#E0F7FA" # Crystalline structures
SERVICE_WARMTH = "#FFE4B5" # Welcoming warmth
DEFAULT_AMBIENT = "#1A1A2E" # Contemplative dark
HOPE_ACCENT = "#64B5F6" # Hopeful blue
class MoodPresets:
"""Mood-based aesthetic presets."""
CONTEMPLATIVE = {
"lighting": "soft_diffuse",
"colors": ["#1A1A2E", "#16213E", "#0F3460"],
"geometry": "minimalist",
"atmosphere": "calm",
"description": "A serene space for deep reflection and clarity"
}
ENERGETIC = {
"lighting": "dynamic_vivid",
"colors": ["#D4AF37", "#FF6B6B", "#4ECDC4"],
"geometry": "angular_dynamic",
"atmosphere": "lively",
"description": "An invigorating space full of motion and possibility"
}
MYSTERIOUS = {
"lighting": "dramatic_shadows",
"colors": ["#2C003E", "#512B58", "#8B4F80"],
"geometry": "organic_flowing",
"atmosphere": "enigmatic",
"description": "A mysterious realm of discovery and wonder"
}
WELCOMING = {
"lighting": "warm_inviting",
"colors": ["#FFE4B5", "#FFA07A", "#98D8C8"],
"geometry": "rounded_soft",
"atmosphere": "friendly",
"description": "An open, welcoming space that embraces visitors"
}
SOVEREIGN = {
"lighting": "crystalline_clear",
"colors": ["#E0F7FA", "#B2EBF2", "#4DD0E1"],
"geometry": "crystalline_structures",
"atmosphere": "noble",
"description": "A space of crystalline clarity and sovereign purpose"
}
# =============================================================================
# Data Models
# =============================================================================
@dataclass
class MentalState:
"""Timmy's mental state for aesthetic tuning."""
mood: str = "contemplative" # contemplative, energetic, mysterious, welcoming, sovereign
energy_level: float = 0.5 # 0.0 to 1.0
clarity: float = 0.7 # 0.0 to 1.0
focus_area: str = "general" # general, creative, analytical, social
timestamp: Optional[str] = None
def to_dict(self) -> Dict[str, Any]:
return {
"mood": self.mood,
"energy_level": self.energy_level,
"clarity": self.clarity,
"focus_area": self.focus_area,
"timestamp": self.timestamp,
}
@dataclass
class RoomDesign:
"""Complete room design specification."""
name: str
description: str
style: str
dimensions: Dict[str, float] = field(default_factory=lambda: {"width": 20, "height": 10, "depth": 20})
mood_preset: str = "contemplative"
color_palette: List[str] = field(default_factory=list)
lighting_scheme: str = "soft_diffuse"
features: List[str] = field(default_factory=list)
generated_code: Optional[str] = None
def to_dict(self) -> Dict[str, Any]:
return {
"name": self.name,
"description": self.description,
"style": self.style,
"dimensions": self.dimensions,
"mood_preset": self.mood_preset,
"color_palette": self.color_palette,
"lighting_scheme": self.lighting_scheme,
"features": self.features,
"has_code": self.generated_code is not None,
}
@dataclass
class PortalDesign:
"""Portal connection design."""
name: str
from_room: str
to_room: str
style: str
position: Dict[str, float] = field(default_factory=lambda: {"x": 0, "y": 0, "z": 0})
visual_effect: str = "energy_swirl"
transition_duration: float = 1.5
generated_code: Optional[str] = None
def to_dict(self) -> Dict[str, Any]:
return {
"name": self.name,
"from_room": self.from_room,
"to_room": self.to_room,
"style": self.style,
"position": self.position,
"visual_effect": self.visual_effect,
"transition_duration": self.transition_duration,
"has_code": self.generated_code is not None,
}
# =============================================================================
# Prompt Engineering
# =============================================================================
class PromptEngineer:
"""Engineers prompts for Three.js code generation."""
THREE_JS_BASE_TEMPLATE = """// Nexus Room Module: {room_name}
// Style: {style}
// Mood: {mood}
// Generated for Three.js r128+
(function() {{
'use strict';
// Room Configuration
const config = {{
name: "{room_name}",
dimensions: {dimensions_json},
colors: {colors_json},
mood: "{mood}"
}};
// Create Room Function
function create{room_name_camel}() {{
const roomGroup = new THREE.Group();
roomGroup.name = config.name;
{room_content}
return roomGroup;
}}
// Export for Nexus
if (typeof module !== 'undefined' && module.exports) {{
module.exports = {{ create{room_name_camel} }};
}} else if (typeof window !== 'undefined') {{
window.NexusRooms = window.NexusRooms || {{}};
window.NexusRooms.{room_name} = create{room_name_camel};
}}
return {{ create{room_name_camel} }};
}})();"""
@staticmethod
def engineer_room_prompt(
name: str,
description: str,
style: str,
mental_state: Optional[MentalState] = None,
dimensions: Optional[Dict[str, float]] = None
) -> str:
"""
Engineer an LLM prompt for room generation.
Args:
name: Room identifier
description: Natural language room description
style: Visual style
mental_state: Timmy's current mental state
dimensions: Room dimensions
"""
# Determine mood from mental state or description
mood = PromptEngineer._infer_mood(description, mental_state)
mood_preset = getattr(MoodPresets, mood.upper(), MoodPresets.CONTEMPLATIVE)
# Build color palette
color_palette = mood_preset["colors"]
if mental_state:
# Add Timmy's gold for high clarity states
if mental_state.clarity > 0.7:
color_palette = [NexusColors.TIMMY_GOLD] + color_palette[:2]
# Add Allegro blue for creative focus
if mental_state.focus_area == "creative":
color_palette = [NexusColors.ALLEGRO_BLUE] + color_palette[:2]
# Create the engineering prompt
prompt = f"""You are the Nexus Architect, an expert Three.js developer creating immersive 3D environments for Timmy.
DESIGN BRIEF:
- Room Name: {name}
- Description: {description}
- Style: {style}
- Mood: {mood}
- Atmosphere: {mood_preset['atmosphere']}
AESTHETIC GUIDELINES:
- Primary Colors: {', '.join(color_palette[:3])}
- Lighting: {mood_preset['lighting']}
- Geometry: {mood_preset['geometry']}
- Theme: {mood_preset['description']}
TIMMY'S CONTEXT:
- Timmy's Signature Color: Warm Gold ({NexusColors.TIMMY_GOLD})
- Allegro's Color: Motion Blue ({NexusColors.ALLEGRO_BLUE})
- Sovereignty Theme: Crystalline structures, clean lines
- Service Theme: Open spaces, welcoming lighting
THREE.JS REQUIREMENTS:
1. Use Three.js r128+ compatible syntax
2. Create a self-contained module with a `create{name.title().replace('_', '')}()` function
3. Return a THREE.Group containing all room elements
4. Include proper memory management (dispose methods)
5. Use MeshStandardMaterial for PBR lighting
6. Include ambient light (intensity 0.3-0.5) + accent lights
7. Add subtle animations for living feel
8. Keep polygon count under 10,000 triangles
SAFETY RULES:
- NO eval(), Function(), or dynamic code execution
- NO network requests (fetch, XMLHttpRequest, WebSocket)
- NO storage access (localStorage, sessionStorage, cookies)
- NO navigation (window.location, window.open)
- Only use allowed Three.js APIs
OUTPUT FORMAT:
Return ONLY the JavaScript code wrapped in a markdown code block:
```javascript
// Your Three.js room module here
```
Generate the complete Three.js code for this room now."""
return prompt
@staticmethod
def engineer_portal_prompt(
name: str,
from_room: str,
to_room: str,
style: str,
mental_state: Optional[MentalState] = None
) -> str:
"""Engineer a prompt for portal generation."""
mood = PromptEngineer._infer_mood(f"portal from {from_room} to {to_room}", mental_state)
prompt = f"""You are creating a portal connection in the Nexus 3D environment.
PORTAL SPECIFICATIONS:
- Name: {name}
- Connection: {from_room}{to_room}
- Style: {style}
- Context Mood: {mood}
VISUAL REQUIREMENTS:
1. Create an animated portal effect (shader or texture-based)
2. Include particle system for energy flow
3. Add trigger zone for teleportation detection
4. Use signature colors: {NexusColors.TIMMY_GOLD} (Timmy) and {NexusColors.ALLEGRO_BLUE} (Allegro)
5. Match the {mood} atmosphere
TECHNICAL REQUIREMENTS:
- Three.js r128+ compatible
- Export a `createPortal()` function returning THREE.Group
- Include animation loop hook
- Add collision detection placeholder
SAFETY: No eval, no network requests, no external dependencies.
Return ONLY JavaScript code in a markdown code block."""
return prompt
@staticmethod
def engineer_mood_scene_prompt(mood_description: str) -> str:
"""Engineer a prompt based on mood description."""
# Analyze mood description
mood_keywords = {
"contemplative": ["thinking", "reflective", "calm", "peaceful", "quiet", "serene"],
"energetic": ["excited", "dynamic", "lively", "active", "energetic", "vibrant"],
"mysterious": ["mysterious", "dark", "unknown", "secret", "enigmatic"],
"welcoming": ["friendly", "open", "warm", "welcoming", "inviting", "comfortable"],
"sovereign": ["powerful", "clear", "crystalline", "noble", "dignified"],
}
detected_mood = "contemplative"
desc_lower = mood_description.lower()
for mood, keywords in mood_keywords.items():
if any(kw in desc_lower for kw in keywords):
detected_mood = mood
break
preset = getattr(MoodPresets, detected_mood.upper(), MoodPresets.CONTEMPLATIVE)
prompt = f"""Generate a Three.js room based on this mood description:
"{mood_description}"
INFERRED MOOD: {detected_mood}
AESTHETIC: {preset['description']}
Create a complete room with:
- Style: {preset['geometry']}
- Lighting: {preset['lighting']}
- Color Palette: {', '.join(preset['colors'][:3])}
- Atmosphere: {preset['atmosphere']}
Return Three.js r128+ code as a module with `createMoodRoom()` function."""
return prompt
@staticmethod
def _infer_mood(description: str, mental_state: Optional[MentalState] = None) -> str:
"""Infer mood from description and mental state."""
if mental_state and mental_state.mood:
return mental_state.mood
desc_lower = description.lower()
mood_map = {
"contemplative": ["serene", "calm", "peaceful", "quiet", "meditation", "zen", "tranquil"],
"energetic": ["dynamic", "active", "vibrant", "lively", "energetic", "motion"],
"mysterious": ["mysterious", "shadow", "dark", "unknown", "secret", "ethereal"],
"welcoming": ["warm", "welcoming", "friendly", "open", "inviting", "comfort"],
"sovereign": ["crystal", "clear", "noble", "dignified", "powerful", "authoritative"],
}
for mood, keywords in mood_map.items():
if any(kw in desc_lower for kw in keywords):
return mood
return "contemplative"
# =============================================================================
# Nexus Architect AI
# =============================================================================
class NexusArchitectAI:
"""
AI-powered Nexus Architect for autonomous Three.js world generation.
This class provides high-level interfaces for:
- Designing rooms from natural language
- Creating mood-based scenes
- Managing mental state integration
- Validating generated code
"""
def __init__(self):
self.mental_state: Optional[MentalState] = None
self.room_designs: Dict[str, RoomDesign] = {}
self.portal_designs: Dict[str, PortalDesign] = {}
self.prompt_engineer = PromptEngineer()
def set_mental_state(self, state: MentalState) -> None:
"""Set Timmy's current mental state for aesthetic tuning."""
self.mental_state = state
logger.info(f"Mental state updated: {state.mood} (energy: {state.energy_level})")
def design_room(
self,
name: str,
description: str,
style: str,
dimensions: Optional[Dict[str, float]] = None
) -> Dict[str, Any]:
"""
Design a room from natural language description.
Args:
name: Room identifier (e.g., "contemplation_chamber")
description: Natural language description of the room
style: Visual style (e.g., "minimalist_ethereal", "crystalline_modern")
dimensions: Optional room dimensions
Returns:
Dict containing design specification and LLM prompt
"""
# Infer mood and select preset
mood = self.prompt_engineer._infer_mood(description, self.mental_state)
mood_preset = getattr(MoodPresets, mood.upper(), MoodPresets.CONTEMPLATIVE)
# Build color palette with mental state influence
colors = mood_preset["colors"].copy()
if self.mental_state:
if self.mental_state.clarity > 0.7:
colors.insert(0, NexusColors.TIMMY_GOLD)
if self.mental_state.focus_area == "creative":
colors.insert(0, NexusColors.ALLEGRO_BLUE)
# Create room design
design = RoomDesign(
name=name,
description=description,
style=style,
dimensions=dimensions or {"width": 20, "height": 10, "depth": 20},
mood_preset=mood,
color_palette=colors[:4],
lighting_scheme=mood_preset["lighting"],
features=self._extract_features(description),
)
# Generate LLM prompt
prompt = self.prompt_engineer.engineer_room_prompt(
name=name,
description=description,
style=style,
mental_state=self.mental_state,
dimensions=design.dimensions,
)
# Store design
self.room_designs[name] = design
return {
"success": True,
"room_name": name,
"design": design.to_dict(),
"llm_prompt": prompt,
"message": f"Room '{name}' designed. Use the LLM prompt to generate Three.js code.",
}
def create_portal(
self,
name: str,
from_room: str,
to_room: str,
style: str = "energy_vortex"
) -> Dict[str, Any]:
"""
Design a portal connection between rooms.
Args:
name: Portal identifier
from_room: Source room name
to_room: Target room name
style: Portal visual style
Returns:
Dict containing portal design and LLM prompt
"""
if from_room not in self.room_designs:
return {"success": False, "error": f"Source room '{from_room}' not found"}
if to_room not in self.room_designs:
return {"success": False, "error": f"Target room '{to_room}' not found"}
design = PortalDesign(
name=name,
from_room=from_room,
to_room=to_room,
style=style,
)
prompt = self.prompt_engineer.engineer_portal_prompt(
name=name,
from_room=from_room,
to_room=to_room,
style=style,
mental_state=self.mental_state,
)
self.portal_designs[name] = design
return {
"success": True,
"portal_name": name,
"design": design.to_dict(),
"llm_prompt": prompt,
"message": f"Portal '{name}' designed connecting {from_room} to {to_room}",
}
def generate_scene_from_mood(self, mood_description: str) -> Dict[str, Any]:
"""
Generate a complete scene based on mood description.
Args:
mood_description: Description of desired mood/atmosphere
Returns:
Dict containing scene design and LLM prompt
"""
# Infer mood
mood = self.prompt_engineer._infer_mood(mood_description, self.mental_state)
preset = getattr(MoodPresets, mood.upper(), MoodPresets.CONTEMPLATIVE)
# Create room name from mood
room_name = f"{mood}_realm"
# Generate prompt
prompt = self.prompt_engineer.engineer_mood_scene_prompt(mood_description)
return {
"success": True,
"room_name": room_name,
"inferred_mood": mood,
"aesthetic": preset,
"llm_prompt": prompt,
"message": f"Generated {mood} scene from mood description",
}
def _extract_features(self, description: str) -> List[str]:
"""Extract room features from description."""
features = []
feature_keywords = {
"floating": ["floating", "levitating", "hovering"],
"water": ["water", "fountain", "pool", "stream", "lake"],
"vegetation": ["tree", "plant", "garden", "forest", "nature"],
"crystals": ["crystal", "gem", "prism", "diamond"],
"geometry": ["geometric", "shape", "sphere", "cube", "abstract"],
"particles": ["particle", "dust", "sparkle", "glow", "mist"],
}
desc_lower = description.lower()
for feature, keywords in feature_keywords.items():
if any(kw in desc_lower for kw in keywords):
features.append(feature)
return features
def get_design_summary(self) -> Dict[str, Any]:
"""Get summary of all designs."""
return {
"mental_state": self.mental_state.to_dict() if self.mental_state else None,
"rooms": {name: design.to_dict() for name, design in self.room_designs.items()},
"portals": {name: portal.to_dict() for name, portal in self.portal_designs.items()},
"total_rooms": len(self.room_designs),
"total_portals": len(self.portal_designs),
}
# =============================================================================
# Module-level functions for easy import
# =============================================================================
_architect_instance: Optional[NexusArchitectAI] = None
def get_architect() -> NexusArchitectAI:
"""Get or create the NexusArchitectAI singleton."""
global _architect_instance
if _architect_instance is None:
_architect_instance = NexusArchitectAI()
return _architect_instance
def create_room(
name: str,
description: str,
style: str,
dimensions: Optional[Dict[str, float]] = None
) -> Dict[str, Any]:
"""
Create a room design from description.
Args:
name: Room identifier
description: Natural language room description
style: Visual style (e.g., "minimalist_ethereal")
dimensions: Optional dimensions dict with width, height, depth
Returns:
Dict with design specification and LLM prompt for code generation
"""
architect = get_architect()
return architect.design_room(name, description, style, dimensions)
def create_portal(
name: str,
from_room: str,
to_room: str,
style: str = "energy_vortex"
) -> Dict[str, Any]:
"""
Create a portal between rooms.
Args:
name: Portal identifier
from_room: Source room name
to_room: Target room name
style: Visual style
Returns:
Dict with portal design and LLM prompt
"""
architect = get_architect()
return architect.create_portal(name, from_room, to_room, style)
def generate_scene_from_mood(mood_description: str) -> Dict[str, Any]:
"""
Generate a scene based on mood description.
Args:
mood_description: Description of desired mood
Example:
"Timmy is feeling introspective and seeking clarity"
→ Generates calm, minimalist space with clear sightlines
Returns:
Dict with scene design and LLM prompt
"""
architect = get_architect()
return architect.generate_scene_from_mood(mood_description)
def set_mental_state(
mood: str,
energy_level: float = 0.5,
clarity: float = 0.7,
focus_area: str = "general"
) -> Dict[str, Any]:
"""
Set Timmy's mental state for aesthetic tuning.
Args:
mood: Current mood (contemplative, energetic, mysterious, welcoming, sovereign)
energy_level: 0.0 to 1.0
clarity: 0.0 to 1.0
focus_area: general, creative, analytical, social
Returns:
Confirmation dict
"""
architect = get_architect()
state = MentalState(
mood=mood,
energy_level=energy_level,
clarity=clarity,
focus_area=focus_area,
)
architect.set_mental_state(state)
return {
"success": True,
"mental_state": state.to_dict(),
"message": f"Mental state set to {mood}",
}
def get_nexus_summary() -> Dict[str, Any]:
"""Get summary of all Nexus designs."""
architect = get_architect()
return architect.get_design_summary()
# =============================================================================
# Tool Schemas for integration
# =============================================================================
NEXUS_ARCHITECT_AI_SCHEMAS = {
"create_room": {
"name": "create_room",
"description": (
"Design a new 3D room in the Nexus from a natural language description. "
"Returns a design specification and LLM prompt for Three.js code generation. "
"The room will be styled according to Timmy's current mental state."
),
"parameters": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Unique room identifier (e.g., 'contemplation_chamber')"
},
"description": {
"type": "string",
"description": "Natural language description of the room"
},
"style": {
"type": "string",
"description": "Visual style (minimalist_ethereal, crystalline_modern, organic_natural, etc.)"
},
"dimensions": {
"type": "object",
"description": "Optional room dimensions",
"properties": {
"width": {"type": "number"},
"height": {"type": "number"},
"depth": {"type": "number"},
}
}
},
"required": ["name", "description", "style"]
}
},
"create_portal": {
"name": "create_portal",
"description": "Create a portal connection between two rooms",
"parameters": {
"type": "object",
"properties": {
"name": {"type": "string"},
"from_room": {"type": "string"},
"to_room": {"type": "string"},
"style": {"type": "string", "default": "energy_vortex"},
},
"required": ["name", "from_room", "to_room"]
}
},
"generate_scene_from_mood": {
"name": "generate_scene_from_mood",
"description": (
"Generate a complete 3D scene based on a mood description. "
"Example: 'Timmy is feeling introspective' creates a calm, minimalist space."
),
"parameters": {
"type": "object",
"properties": {
"mood_description": {
"type": "string",
"description": "Description of desired mood or mental state"
}
},
"required": ["mood_description"]
}
},
"set_mental_state": {
"name": "set_mental_state",
"description": "Set Timmy's mental state to influence aesthetic generation",
"parameters": {
"type": "object",
"properties": {
"mood": {"type": "string"},
"energy_level": {"type": "number"},
"clarity": {"type": "number"},
"focus_area": {"type": "string"},
},
"required": ["mood"]
}
},
"get_nexus_summary": {
"name": "get_nexus_summary",
"description": "Get summary of all Nexus room and portal designs",
"parameters": {"type": "object", "properties": {}}
},
}
if __name__ == "__main__":
# Demo usage
print("Nexus Architect AI - Demo")
print("=" * 50)
# Set mental state
result = set_mental_state("contemplative", energy_level=0.3, clarity=0.8)
print(f"\nMental State: {result['mental_state']}")
# Create a room
result = create_room(
name="contemplation_chamber",
description="A serene circular room with floating geometric shapes and soft blue light",
style="minimalist_ethereal",
)
print(f"\nRoom Design: {json.dumps(result['design'], indent=2)}")
# Generate from mood
result = generate_scene_from_mood("Timmy is feeling introspective and seeking clarity")
print(f"\nMood Scene: {result['inferred_mood']} - {result['aesthetic']['description']}")