# GNS3 Lab Viewer Integration for HuggingFace Space

This module provides seamless integration between the Overgrowth HuggingFace Space and the live GNS3 network lab, allowing users to see the results of their network configurations in real-time.

## 🌐 Live Lab Access

**URL:** http://lab.grahampaasch.com:3080/static/web-ui/server/1/project/1f712057-b33d-433f-90bb-2b9b3804a95e

Users can access the live network topology through their browser at any time.

## Features

- ✅ Real-time deployment status
- ✅ Live device information (switches, routers)
- ✅ Console access URLs for each device
- ✅ HTML widgets for embedding in Gradio UI
- ✅ Markdown output for display
- ✅ JSON API for programmatic access

## Quick Start

### 1. Check Lab Status

```python
from web.gns3_viewer import GNS3Viewer

viewer = GNS3Viewer()

# Check if lab is accessible
if viewer.is_accessible():
    print("✅ Lab is online!")
    
# Get deployment summary
summary = viewer.get_deployment_summary()
print(f"Deployed switches: {summary['switches']['deployed']}")
print(f"Web UI: {summary['web_ui_url']}")
```

### 2. Get Markdown for Display

```python
from web.gns3_viewer import get_deployment_markdown

# Get formatted markdown for display in HuggingFace Space
markdown = get_deployment_markdown()
print(markdown)
```

### 3. Integrate with Gradio

```python
import gradio as gr
from web.gns3_viewer import get_deployment_markdown, GNS3Viewer

def refresh_lab_status():
    viewer = GNS3Viewer()
    return viewer.format_for_ui()

with gr.Blocks() as demo:
    gr.Markdown("# 🌐 Live Network Lab Status")
    
    status_display = gr.Markdown(get_deployment_markdown())
    refresh_btn = gr.Button("🔄 Refresh")
    
    refresh_btn.click(
        fn=refresh_lab_status,
        outputs=status_display
    )

demo.launch()
```

### 4. Show Deployment Results

```python
from examples.huggingface_integration import create_deployment_result_card

# After deploying configuration to devices
result = create_deployment_result_card(
    deployment_success=True,
    devices_configured=['SW-HQ-Core', 'SW-West', 'SW-East']
)

# result contains:
# - status: 'success' or 'error'
# - title: Display title
# - message: Description
# - lab_info: Current lab statistics
# - actions: Links to web UI and API
# - console_access: Console URLs for each device
```

## API Reference

### GNS3Viewer Class

```python
viewer = GNS3Viewer(
    base_url="http://lab.grahampaasch.com:3080",
    project_id="1f712057-b33d-433f-90bb-2b9b3804a95e"
)
```

#### Methods

- `get_web_ui_url()` - Returns the direct URL to the GNS3 web UI
- `is_accessible()` - Checks if the GNS3 server is reachable
- `get_project_info()` - Returns project metadata
- `get_devices(filter)` - Returns list of devices (optionally filtered)
- `get_deployment_summary()` - Returns comprehensive deployment status
- `format_for_ui()` - Returns markdown-formatted status for display

### Convenience Functions

```python
from web.gns3_viewer import (
    get_deployment_status,  # Get deployment summary dict
    get_web_ui_link,        # Get web UI URL
    get_deployment_markdown # Get markdown output
)
```

## Example Outputs

### JSON Status

```json
{
  "web_ui_url": "http://lab.grahampaasch.com:3080/static/web-ui/server/1/project/...",
  "accessible": true,
  "total_devices": 13,
  "switches": {
    "total": 3,
    "deployed": 3,
    "devices": [
      {
        "name": "SW-HQ-Core",
        "status": "started",
        "console": "telnet://lab.grahampaasch.com:5046"
      }
    ]
  },
  "routers": {
    "total": 0,
    "deployed": 0,
    "devices": []
  }
}
```

### Markdown Output

```markdown
## 🌐 Live Network Lab View

**[📡 Open GNS3 Web UI](http://lab.grahampaasch.com:3080/...)** - View live network topology

### Deployment Status
**Total Devices:** 13

#### Switches (3/3 deployed)
- ✅ **SW-HQ-Core** - Status: `started` - Console: `telnet://lab.grahampaasch.com:5046`
- ✅ **SW-West** - Status: `started` - Console: `telnet://lab.grahampaasch.com:5059`
- ✅ **SW-East** - Status: `started` - Console: `telnet://lab.grahampaasch.com:5069`
```

## Integration with HuggingFace Space

### Add to requirements.txt

```
requests>=2.31.0
```

### Copy Files to Space

```bash
# Copy the viewer module
cp web/gns3_viewer.py <huggingface-space>/

# Copy integration example
cp examples/huggingface_integration.py <huggingface-space>/
```

### Update app.py

```python
import gradio as gr
from gns3_viewer import GNS3Viewer, get_deployment_markdown

def deploy_config(user_prompt, config_text):
    """Your deployment function"""
    # ... deployment logic ...
    
    # After deployment, show live lab status
    viewer = GNS3Viewer()
    lab_status = viewer.format_for_ui()
    
    return {
        "result": "Configuration deployed successfully!",
        "lab_status": lab_status,
        "lab_url": viewer.get_web_ui_url()
    }

# In your Gradio interface
with gr.Blocks() as demo:
    # ... your existing UI ...
    
    with gr.Tab("🌐 Live Lab"):
        lab_status = gr.Markdown(get_deployment_markdown())
        refresh_btn = gr.Button("🔄 Refresh Status")
        
        refresh_btn.click(
            fn=lambda: GNS3Viewer().format_for_ui(),
            outputs=lab_status
        )
```

## URLs for User Access

| Resource | URL |
|----------|-----|
| **GNS3 Web UI** | http://lab.grahampaasch.com:3080/static/web-ui/server/1/project/1f712057-b33d-433f-90bb-2b9b3804a95e |
| **API Endpoint** | http://lab.grahampaasch.com:3080/v2/projects/1f712057-b33d-433f-90bb-2b9b3804a95e |
| **Server Info** | http://lab.grahampaasch.com:3080/v2/version |

## Console Access

Users can connect to deployed devices via telnet:

```bash
# Connect to SW-HQ-Core
telnet lab.grahampaasch.com 5046

# Connect to SW-West
telnet lab.grahampaasch.com 5059

# Connect to SW-East
telnet lab.grahampaasch.com 5069
```

## Testing

```bash
# Test the viewer locally
python web/gns3_viewer.py

# Test HuggingFace integration
python examples/huggingface_integration.py
```

## Architecture

```
HuggingFace Space (User Interface)
         ↓
   gns3_viewer.py (Integration Layer)
         ↓
   GNS3 REST API (lab.grahampaasch.com:3080)
         ↓
   GNS3 Server (Network Lab)
         ↓
   Deployed Devices (Switches, Routers)
```

## Security Considerations

- The GNS3 server is exposed on port 3080 for read-only operations
- No authentication is currently configured (suitable for demo/hackathon)
- For production, consider adding API authentication
- Console access is via telnet (suitable for lab environment)

## Troubleshooting

### Lab Not Accessible

```python
viewer = GNS3Viewer()
if not viewer.is_accessible():
    print("Lab is offline or unreachable")
    # Show cached status or error message
```

### No Devices Showing

```python
summary = viewer.get_deployment_summary()
if summary['total_devices'] == 0:
    print("No devices in project")
    # Check project ID is correct
```

### Console Connection Fails

- Verify GNS3 devices are started (`status == 'started'`)
- Check firewall allows telnet connections to console ports
- Ensure console port numbers are correct

## Next Steps

1. **Add to HuggingFace Space**: Copy `gns3_viewer.py` to your Space repository
2. **Update UI**: Add lab status display to your Gradio interface
3. **Test Integration**: Verify users can see deployment results
4. **Add Feedback Loop**: Show real-time device status after deployments

## Support

For issues or questions:
- Check GNS3 server status: `curl http://lab.grahampaasch.com:3080/v2/version`
- View project directly: Visit the Web UI URL above
- Test API: `curl http://lab.grahampaasch.com:3080/v2/projects/1f712057-b33d-433f-90bb-2b9b3804a95e`