#!/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']}")