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

```python
@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:**
```json
{
  "success": true,
  "room_name": "meditation_chamber",
  "prompt": "... LLM prompt for Three.js generation ...",
  "config": { ... room configuration ... }
}
```

**Example:**
```python
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:**
```json
{
  "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:**
```python
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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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

```python
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

```json
{
  "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

```python
# 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

```python
# 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:

```bash
# 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

```bash
# 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:

```python
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](https://threejs.org/docs/)
- [Hermes Agent Tools Guide](tools-reference.md)
- [Nexus Runtime Specification](nexus-runtime.md) (TODO)