docs/implementation/OBSERVATORY_TROUBLESHOOTING.md

# Observatory Troubleshooting Guide

## Issue: Blank Page on Launch

### Fixes Applied (2026-06-16)

1. **Added Welcome Screen**: When no run/task is selected, the app now shows a proper welcome screen with feature overview instead of just an error message.

2. **Improved Error Handling**: Added clearer warning messages when run/task data fails to load.

3. **Better Initial State**: The app now gracefully handles the initial render before any data is loaded.

### How to Launch

Use the provided launch script:
```bash
./launch_observatory.sh
```

Or manually:
```bash
cd /workspace/ainn-cm-poc-data-agent
source .venv/bin/activate
streamlit run src/data_agent_baseline/observatory/app.py --server.port 8501
```

### Access the App

- **Local**: http://localhost:8501
- **External**: http://138.108.24.100:8501 (if accessible)

### Common Issues

#### 1. Blank Page After Launch

**Symptoms**: Browser shows empty white/dark page

**Solutions**:
- Hard refresh the browser (Ctrl+Shift+R or Cmd+Shift+R)
- Clear browser cache
- Try a different browser
- Check browser console for JavaScript errors (F12 → Console tab)

#### 2. "No runs found" Message

**Symptoms**: Sidebar shows "⚠️ No runs found"

**Solutions**:
- Check the artifact path in the sidebar Configuration expander
- Verify the path exists: `/data3/dataFAIR/kdd-dev/public/artifacts/runs/`
- Verify run folders exist in that path
- Click the refresh button after correcting the path

#### 3. Welcome Screen Stuck

**Symptoms**: Shows welcome screen but selecting run/task doesn't load

**Solutions**:
- Check that the selected run folder contains:
  - Task subdirectories (task_XXX/)
  - `comprehensive_evaluation.csv` (optional but recommended)
- Check browser console for errors
- Try refreshing the page

#### 4. CSS/Styling Issues

**Symptoms**: Page loads but styling looks wrong or content is hidden

**Solutions**:
- The Mission Control CSS is injected when the Mission Summary tab loads
- Try switching to the Mission Summary tab
- Check browser console for CSS errors
- Disable browser extensions that might interfere with styling

#### 5. Port Already in Use

**Symptoms**: Error message "Port 8501 is not available"

**Solutions**:
```bash
# Kill existing Streamlit processes
pkill -f streamlit

# Or kill specific port
lsof -ti:8501 | xargs kill -9

# Then relaunch
./launch_observatory.sh
```

### Verification Steps

Run these commands to verify everything is set up correctly:

```bash
# 1. Verify Python environment
source .venv/bin/activate
python3 -c "import streamlit; print(f'Streamlit version: {streamlit.__version__}')"

# 2. Verify Observatory imports
python3 -c "from src.data_agent_baseline.observatory import RunDiscovery; print('✓ Imports OK')"

# 3. Verify artifact path
ls -la /data3/dataFAIR/kdd-dev/public/artifacts/runs/ | head -10

# 4. Check run count
python3 -c "from src.data_agent_baseline.observatory import RunDiscovery; d=RunDiscovery(); runs=d.discover_runs(); print(f'{len(runs)} runs found')"
```

### Expected Behavior

1. **First Load**: You should see a welcome screen with:
   - Title: "🔬 Agent Observatory"
   - Info message: "👈 Select a run and task from the sidebar"
   - Feature list
   - Quick start guide

2. **After Selecting Run**: The sidebar should show:
   - Current Context card with run details
   - Task dropdown populated with available tasks
   - Artifact status pills

3. **After Selecting Task**: The main content should show:
   - Mission Summary tab (default)
   - Hero header with gradient background
   - Executive summary card
   - KPI cards
   - Execution flow visualization

### Debug Mode

To see more detailed logs:

```bash
streamlit run src/data_agent_baseline/observatory/app.py \
    --server.port 8501 \
    --logger.level=debug
```

### Getting Help

If issues persist:

1. Check the Streamlit logs in the terminal
2. Check browser console (F12) for JavaScript errors
3. Verify all dependencies are installed: `uv sync`
4. Try the minimal test app: `streamlit run test_streamlit_minimal.py --server.port 8503`

### Known Limitations

- First load may take 1-2 seconds for run discovery
- Large trace files (>10MB) may take longer to parse
- Some older runs may lack full metadata (gracefully degraded)
- CSS styling only applies after Mission Summary tab is viewed

### Performance Tips

- Discovery is O(n) in number of runs — startup may be slower with 500+ runs
- Task loading includes trace parsing — may take 2-3 seconds for large traces
- Session state caching avoids re-loading on page interactions
- Switching between tasks reloads data — switching between tabs does not