hermes-agent/docs/nexus_architect.md

Nexus Architect Tool

The Nexus Architect Tool enables Timmy (the Hermes Agent) to autonomously design and build 3D environments in the Three.js-based "Nexus" virtual world. It provides a structured interface for creating rooms, portals, lighting systems, and architectural features through LLM-generated Three.js code.

Overview

┌─────────────────────────────────────────────────────────────────┐
│                     Nexus Architect Tool                         │
├─────────────────────────────────────────────────────────────────┤
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────────┐  │
│  │ Room Design  │  │ Portal Create│  │ Lighting System      │  │
│  └──────────────┘  └──────────────┘  └──────────────────────┘  │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────────┐  │
│  │ Architecture │  │ Code Validate│  │ Scene Export         │  │
│  └──────────────┘  └──────────────┘  └──────────────────────┘  │
├─────────────────────────────────────────────────────────────────┤
│                     Scene Graph Store                            │
│         (Rooms, Portals, Lights, Architecture)                   │
└─────────────────────────────────────────────────────────────────┘

Architecture

Core Components

1. NexusArchitect Class: Main orchestrator for all architectural operations
2. SceneGraph: Dataclass storing the complete world state
3. Validation Engine: Security and syntax validation for generated code
4. Prompt Generator: Structured LLM prompts for Three.js code generation
5. Tool Registry Integration: Registration with Hermes tool system

Data Models

@dataclass
class RoomConfig:
    name: str
    theme: RoomTheme  # meditation, tech_lab, nature, crystal_cave, library, void
    dimensions: Dict[str, float]  # {width, height, depth}
    features: List[str]
    lighting_profile: str
    fog_enabled: bool

@dataclass
class PortalConfig:
    name: str
    source_room: str
    target_room: str
    position: Dict[str, float]
    style: PortalStyle  # circular, rectangular, stargate, dissolve, glitch
    color: str
    one_way: bool

@dataclass
class LightConfig:
    name: str
    type: LightType  # ambient, directional, point, spot, hemisphere
    position: Dict[str, float]
    color: str
    intensity: float
    cast_shadow: bool

Available Tools

1. nexus_design_room

Design a new room in the Nexus.

Parameters:

• name (string, required): Unique room identifier
• theme (string, required): One of meditation, tech_lab, nature, crystal_cave, library, void, custom
• dimensions (object): {width, height, depth} in meters (default: 10x5x10)
• features (array): List of feature names (e.g., water_feature, floating_lanterns)
• lighting_profile (string): Preset lighting configuration
• mental_state (object): Optional context for design decisions

Returns:

{
  "success": true,
  "room_name": "meditation_chamber",
  "prompt": "... LLM prompt for Three.js generation ...",
  "config": { ... room configuration ... }
}

Example:

nexus_design_room(
    name="zen_garden",
    theme="meditation",
    dimensions={"width": 20, "height": 10, "depth": 20},
    features=["water_feature", "bamboo_grove", "floating_lanterns"],
    mental_state={"mood": "calm", "energy": 0.3}
)

2. nexus_create_portal

Create a portal connecting two rooms.

Parameters:

• name (string, required): Unique portal identifier
• source_room (string, required): Source room name
• target_room (string, required): Target room name
• position (object): {x, y, z} coordinates in source room
• style (string): Visual style (circular, rectangular, stargate, dissolve, glitch)
• color (string): Hex color code (default: #00ffff)

Returns:

{
  "success": true,
  "portal_name": "portal_alpha",
  "source": "room_a",
  "target": "room_b",
  "prompt": "... LLM prompt for portal generation ..."
}

3. nexus_add_lighting

Add lighting elements to a room.

Parameters:

• room_name (string, required): Target room
• lights (array): List of light configurations
  • name (string): Light identifier
  • type (string): ambient, directional, point, spot, hemisphere
  • position (object): {x, y, z}
  • color (string): Hex color
  • intensity (number): Light intensity
  • cast_shadow (boolean): Enable shadows

Example:

nexus_add_lighting(
    room_name="meditation_chamber",
    lights=[
        {"name": "ambient", "type": "ambient", "intensity": 0.3},
        {"name": "main", "type": "point", "position": {"x": 0, "y": 5, "z": 0}}
    ]
)

4. nexus_validate_scene

Validate generated Three.js code for security and syntax.

Parameters:

• code (string, required): JavaScript code to validate
• strict_mode (boolean): Enable stricter validation (default: false)

Returns:

{
  "is_valid": true,
  "errors": [],
  "warnings": [],
  "safety_score": 95,
  "extracted_code": "... cleaned code ..."
}

Security Checks:

• Banned patterns: eval(), Function(), setTimeout(string), document.write
• Network blocking: fetch(), WebSocket, XMLHttpRequest
• Storage blocking: localStorage, sessionStorage, indexedDB
• Syntax validation: Balanced braces and parentheses

5. nexus_export_scene

Export the current scene configuration.

Parameters:

• format (string): json or js (default: json)

Returns:

{
  "success": true,
  "format": "json",
  "data": "... exported scene data ...",
  "summary": {
    "rooms": 3,
    "portals": 2,
    "lights": 5
  }
}

6. nexus_get_summary

Get a summary of the current scene state.

Returns:

{
  "rooms": [
    {"name": "room_a", "theme": "void", "connected_portals": ["p1"]}
  ],
  "portal_network": [
    {"name": "p1", "source": "room_a", "target": "room_b"}
  ],
  "total_lights": 5
}

LLM Integration Flow

┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│  User Request │────▶│   Architect  │────▶│    Prompt    │
│  ("Create a   │     │    Tool      │     │  Generator   │
│   zen room")  │     └──────────────┘     └──────────────┘
└──────────────┘                                    │
                                                    ▼
┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│    Nexus     │◀────│  Validation  │◀────│     LLM      │
│    Runtime   │     │    Engine    │     │  (generates  │
│              │     │              │     │  Three.js)   │
└──────────────┘     └──────────────┘     └──────────────┘

1. Request Parsing: User request converted to structured configuration
2. Prompt Generation: Architect generates structured LLM prompt
3. Code Generation: LLM generates Three.js code based on prompt
4. Validation: Code validated for security and syntax
5. Execution: Validated code ready for Nexus runtime

Code Validation

Allowed Three.js APIs

The validation system maintains an allowlist of safe Three.js APIs:

Core:

• THREE.Scene, THREE.Group, THREE.Object3D
• THREE.PerspectiveCamera, THREE.OrthographicCamera

Geometries:

• THREE.BoxGeometry, THREE.SphereGeometry, THREE.PlaneGeometry
• THREE.CylinderGeometry, THREE.ConeGeometry, THREE.TorusGeometry
• THREE.BufferGeometry, THREE.BufferAttribute

Materials:

• THREE.MeshBasicMaterial, THREE.MeshStandardMaterial
• THREE.MeshPhongMaterial, THREE.MeshPhysicalMaterial
• THREE.SpriteMaterial, THREE.PointsMaterial

Lights:

• THREE.AmbientLight, THREE.DirectionalLight, THREE.PointLight
• THREE.SpotLight, THREE.HemisphereLight

Math:

• THREE.Vector3, THREE.Euler, THREE.Quaternion, THREE.Matrix4
• THREE.Color, THREE.Raycaster, THREE.Clock

Banned Patterns

BANNED_JS_PATTERNS = [
    r"eval\s*\(",           # Code injection
    r"Function\s*\(",       # Dynamic function creation
    r"setTimeout\s*\(\s*['\"]",  # Timers with strings
    r"document\.write",      # DOM manipulation
    r"window\.location",     # Navigation
    r"XMLHttpRequest",       # Network requests
    r"fetch\s*\(",           # Fetch API
    r"localStorage",         # Storage access
    r"navigator",            # Browser API access
]

Scene Graph Format

JSON Export Structure

{
  "version": "1.0.0",
  "rooms": {
    "meditation_chamber": {
      "name": "meditation_chamber",
      "theme": "meditation",
      "dimensions": {"width": 20, "height": 10, "depth": 20},
      "features": ["water_feature", "floating_lanterns"],
      "fog_enabled": false
    }
  },
  "portals": {
    "portal_1": {
      "name": "portal_1",
      "source_room": "room_a",
      "target_room": "room_b",
      "position": {"x": 5, "y": 2, "z": 0},
      "style": "circular",
      "color": "#00ffff"
    }
  },
  "lights": {
    "ambient": {
      "name": "ambient",
      "type": "AmbientLight",
      "color": "#ffffff",
      "intensity": 0.3
    }
  },
  "global_settings": {
    "shadow_map_enabled": true,
    "antialias": true
  }
}

Usage Examples

Creating a Meditation Space

# Step 1: Design the room
room_result = nexus_design_room(
    name="zen_garden",
    theme="meditation",
    dimensions={"width": 25, "height": 12, "depth": 25},
    features=["water_feature", "bamboo_grove", "stone_path", "floating_lanterns"],
    mental_state={"mood": "peaceful", "energy": 0.2}
)

# Step 2: Generate the Three.js code (send prompt to LLM)
prompt = room_result["prompt"]
# ... LLM generates code ...

# Step 3: Validate the generated code
generated_code = """
function createRoom() {
    const scene = new THREE.Scene();
    // ... room implementation ...
    return scene;
}
"""
validation = nexus_validate_scene(code=generated_code)
assert validation["is_valid"]

# Step 4: Add lighting
nexus_add_lighting(
    room_name="zen_garden",
    lights=[
        {"name": "ambient", "type": "ambient", "intensity": 0.2, "color": "#ffe4b5"},
        {"name": "sun", "type": "directional", "position": {"x": 10, "y": 20, "z": 5}},
        {"name": "lantern_glow", "type": "point", "color": "#ffaa00", "intensity": 0.8}
    ]
)

Creating a Portal Network

# Create hub room
nexus_design_room(name="hub", theme="tech_lab", dimensions={"width": 30, "height": 15, "depth": 30})

# Create destination rooms
nexus_design_room(name="library", theme="library")
nexus_design_room(name="crystal_cave", theme="crystal_cave")
nexus_design_room(name="nature", theme="nature")

# Create portals
nexus_create_portal(name="to_library", source_room="hub", target_room="library", style="rectangular")
nexus_create_portal(name="to_cave", source_room="hub", target_room="crystal_cave", style="stargate")
nexus_create_portal(name="to_nature", source_room="hub", target_room="nature", style="circular", color="#00ff00")

# Export the scene
export = nexus_export_scene(format="json")
print(export["data"])

Testing

Run the test suite:

# Run all tests
pytest tests/tools/test_nexus_architect.py -v

# Run specific test categories
pytest tests/tools/test_nexus_architect.py::TestCodeValidation -v
pytest tests/tools/test_nexus_architect.py::TestNexusArchitect -v
pytest tests/tools/test_nexus_architect.py::TestSecurity -v

# Run with coverage
pytest tests/tools/test_nexus_architect.py --cov=tools.nexus_architect --cov-report=html

Test Coverage

• Unit Tests: Data models, validation, prompt generation
• Integration Tests: Complete workflows, scene export
• Security Tests: XSS attempts, code injection, banned patterns
• Performance Tests: Large scenes, complex portal networks

Future Enhancements

Planned Features

1. Asset Library Integration

   • Pre-built furniture and decor objects
   • Material library (PBR textures)
   • Audio ambience presets

2. Advanced Validation

   • AST-based JavaScript parsing
   • Sandboxed code execution testing
   • Performance profiling (polygon count, draw calls)

3. Multi-Agent Collaboration

   • Room ownership and permissions
   • Concurrent editing with conflict resolution
   • Version control for scenes

4. Runtime Integration

   • Hot-reload for scene updates
   • Real-time collaboration protocol
   • Physics engine integration (Cannon.js, Ammo.js)

5. AI-Assisted Design

   • Automatic room layout optimization
   • Lighting analysis and recommendations
   • Accessibility compliance checking

Configuration

Environment Variables

# Enable debug logging
NEXUS_ARCHITECT_DEBUG=1

# Set maximum scene complexity
NEXUS_MAX_ROOMS=100
NEXUS_MAX_PORTALS=500
NEXUS_MAX_LIGHTS=1000

# Strict validation mode
NEXUS_STRICT_VALIDATION=1

Toolset Registration

The tool automatically registers with the Hermes tool registry:

from tools.registry import registry

registry.register(
    name="nexus_design_room",
    toolset="nexus_architect",
    schema=NEXUS_ARCHITECT_SCHEMAS["nexus_design_room"],
    handler=...,
    emoji="🏛️",
)

Troubleshooting

Common Issues

"Room already exists" error:

• Room names must be unique within a session
• Use nexus_get_summary() to list existing rooms

"Invalid theme" error:

• Check theme spelling against allowed values
• Use lowercase theme names

Code validation failures:

• Ensure no banned APIs are used
• Check for balanced braces/parentheses
• Try strict_mode=false for less strict validation

Missing room errors:

• Rooms must be created before adding lights or portals
• Verify room name spelling matches exactly

References

• Three.js Documentation
• Hermes Agent Tools Guide
• Nexus Runtime Specification (TODO)