# digital-galaxy_agent

**Repository Path**: agent-research/digital-galaxy_agent

## Basic Information

- **Project Name**: digital-galaxy_agent
- **Description**: testing dg agent
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-06-12
- **Last Updated**: 2025-11-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# SpecClip Frontend with Qwen-Agent Integration

A sophisticated astronomical data visualization platform with AI-powered navigation capabilities, integrating SpecClip frontend with Qwen-Agent backend and MCP (Model Context Protocol) tools for intelligent celestial object navigation.

## 🌟 Features

### Core Features
- **Interactive Astronomical Visualization**: Powered by Aladin Lite for real-time sky exploration
- **AI-Powered Navigation**: Intelligent celestial object navigation using Qwen-Agent
- **Real-time Chat Interface**: Stream-based communication with structured thinking display
- **MCP Tool Integration**: Advanced navigation tools with coordinate validation and zoom control
- **Multi-format Data Support**: FITS, CSV, and various astronomical data formats

### Navigation Capabilities
- Navigate to celestial coordinates (RA/Dec)
- Navigate to named celestial objects (stars, galaxies, nebulae)
- Automatic zoom control with object-specific optimization
- Real-time navigation within current page (no new tabs)
- Coordinate validation and error handling

### AI Features
- **Structured Thinking**: AI shows reasoning process using `<think></think>` tags
- **Streaming Responses**: Real-time message updates
- **Context Awareness**: Maintains conversation history
- **Specialized Prompts**: Optimized for astronomical navigation tasks

## 🏗️ Architecture

```
┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   Frontend      │    │   Qwen-Agent     │    │   MCP Server    │
│   (React/Vite)  │◄──►│   Backend        │◄──►│   (Navigation)  │
│                 │    │   (FastAPI)      │    │   Tools         │
└─────────────────┘    └──────────────────┘    └─────────────────┘
         │                        │                       │
         │                        │                       │
         ▼                        ▼                       ▼
┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   Aladin Lite   │    │   Custom LLM     │    │   Coordinate    │
│   Viewer        │    │   Server         │    │   Validation    │
└─────────────────┘    └──────────────────┘    └─────────────────┘
```

## 🚀 Quick Start

### Prerequisites
- Node.js 18+ and npm/yarn
- Python 3.8+
- Custom LLM server (OpenAI-compatible API)

### 1. Frontend Setup
```bash
# Clone and install dependencies
cd specclip-frontend
npm install

# Start development server
npm run dev
```

### 2. Backend Setup
```bash
# Navigate to MCP server directory
cd mcp-server-demo

# Create virtual environment
python -m venv qwen-agent_venv
source qwen-agent_venv/bin/activate  # On Windows: qwen-agent_venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Configure your LLM server in config.py
# Edit LLM_CONFIG with your server details

# Start integrated system
python start_integrated_system.py
```

### 3. Access the Application
- Frontend: http://localhost:5173
- Backend API: http://localhost:8001
- Navigate to: http://localhost:5173/digital-galaxy

## ⚙️ Configuration

### LLM Configuration (`mcp-server-demo/config.py`)
```python
LLM_CONFIG = {
    'model_type': 'oai',  # OpenAI-compatible API
    'model': 'your-model-name',
    'api_base': 'http://your-llm-server:port/v1',
    'api_key': 'your-api-key',
}
```

### Environment Variables
```bash
# Frontend (.env.development)
VITE_USE_MOCK=false
VITE_API_BASE_URL=http://localhost:8001
```

## 🎯 Usage Examples

### Navigation Commands
```
# Navigate to coordinates
"Go to coordinates RA: 83.8, Dec: -5.4"

# Navigate to named objects
"Navigate to Sirius"
"Show me M31 galaxy"
"Navigate to the Orion Nebula"

# With custom zoom
"Show me Betelgeuse with maximum zoom"
```

### AI Response Format
```
<think>
The user wants to navigate to Sirius. I need to:
1. Identify Sirius as the brightest star
2. Use navigation tools to get coordinates
3. Set appropriate zoom for a star
</think>

I'll help you navigate to Sirius, the brightest star in the night sky...

📍 Navigation Command: {"action":"navigate_to_object","object_name":"Sirius","auto_zoom":true,"zoom_level":90}
```

## 🛠️ Development

### Project Structure
```
specclip-frontend/
├── src/
│   ├── pages/AladinLite/          # Main astronomical viewer
│   ├── pages/Chat/                # Chat interface components
│   ├── hooks/useChatStore.ts      # Chat state management
│   └── hooks/useAladinStore.ts    # Aladin viewer state
├── mcp-server-demo/
│   ├── qwen_agent_backend.py      # Main backend server
│   ├── config.py                  # Configuration
│   ├── main.py                    # MCP server entry
│   └── mcp_server_demo/
│       └── server.py              # MCP navigation tools
└── README.md
```

### Key Components

#### Frontend
- **AladinViewer**: Main astronomical visualization component
- **DigitalChat**: AI chat interface with streaming support
- **useChatStore**: State management for chat functionality
- **Navigation Handler**: Processes navigation commands from AI

#### Backend
- **FastAPI Server**: Handles chat requests and streaming
- **Qwen-Agent Integration**: AI agent with MCP tools
- **MCP Navigation Tools**: Coordinate validation and navigation
- **EventSource Streaming**: Real-time message delivery

### Adding New Navigation Tools
1. Add tool function in `mcp_server_demo/server.py`
2. Register tool with `@mcp.tool()` decorator
3. Update tool descriptions and parameters
4. Test with frontend navigation handler

## 🔧 Troubleshooting

### Common Issues

**EventSource Connection Errors**
```bash
# Check backend is running
curl http://localhost:8001/

# Verify CORS headers
# Check browser console for CORS errors
```

**Navigation Not Working**
```javascript
// Check Aladin instance in browser console
console.log(window.aladinInstance);

// Verify navigation commands in console
// Look for "执行导航指令" messages
```

**LLM Connection Issues**
```python
# Verify LLM server configuration
# Check API key and endpoint
# Test with curl:
curl -X POST http://your-llm-server/v1/chat/completions \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"model":"your-model","messages":[{"role":"user","content":"Hello"}]}'
```

### Debug Mode
Enable detailed logging:
```bash
# Backend
export LOG_LEVEL=DEBUG
python start_integrated_system.py

# Frontend
# Open browser console for detailed logs
```

## 📝 API Reference

### Chat Endpoint
```
GET /api/v1/data-astron/chat/chat
Parameters:
  - question: string (required)
  - sessionId: string (optional)
  - fileIds: array (optional)

Response: text/event-stream
```

### Navigation Commands
```javascript
// Coordinate navigation
{
  "action": "navigate_to_coordinates",
  "ra": 83.8,
  "dec": -5.4,
  "auto_zoom": true,
  "zoom_level": 60
}

// Object navigation
{
  "action": "navigate_to_object",
  "object_name": "Sirius",
  "auto_zoom": true,
  "zoom_level": 90
}
```

## 🔄 System Integration Flow

### 1. User Interaction Flow
```
User Input → Frontend Chat → Qwen-Agent Backend → MCP Tools → Navigation Response → Frontend Display → Aladin Navigation
```

### 2. Message Processing
1. **User sends navigation request** (e.g., "Navigate to Sirius")
2. **Frontend creates EventSource connection** to backend
3. **Backend processes with Qwen-Agent** using MCP navigation tools
4. **AI generates structured response** with `<think></think>` tags and navigation commands
5. **Frontend parses response** and extracts navigation instructions
6. **Navigation executed** directly in current Aladin viewer
7. **Real-time feedback** displayed in chat interface

### 3. Navigation Command Processing
```javascript
// AI Response Example
<think>
User wants to navigate to Sirius. I need to:
1. Identify Sirius coordinates
2. Set appropriate zoom for a star
3. Generate navigation command
</think>

I'll navigate to Sirius, the brightest star...

📍 Navigation Command: {"action":"navigate_to_object","object_name":"Sirius","zoom_level":90}
```

## 🎨 UI/UX Features

### Chat Interface
- **Real-time streaming**: Messages appear as they're generated
- **Thinking display**: Shows AI reasoning process with timer
- **Navigation feedback**: Visual confirmation of navigation actions
- **Message history**: Persistent conversation context
- **Error handling**: Graceful degradation with fallback responses

### Astronomical Viewer
- **Interactive controls**: Pan, zoom, and navigate
- **Coordinate display**: Real-time RA/Dec information
- **Object information**: Detailed astronomical data
- **Grid overlay**: Coordinate reference system
- **Smooth transitions**: Animated navigation to targets

## 🧪 Testing

### Manual Testing
```bash
# Test navigation commands
"Navigate to coordinates RA: 266.4, Dec: -29.0"
"Show me the Andromeda Galaxy"
"Go to Betelgeuse with maximum zoom"

# Test error handling
"Navigate to invalid-object-name"
"Go to coordinates RA: 400, Dec: 100"  # Invalid coordinates

# Test chat functionality
"What can you help me with?"
"Explain the navigation tools"
```

### Browser Console Testing
```javascript
// Check Aladin instance
console.log(window.aladinInstance);

// Test navigation directly
window.aladinInstance.gotoRaDec(83.8, -5.4);
window.aladinInstance.setFov(1.0);

// Monitor navigation commands
// Look for console logs starting with "执行导航指令"
```

## 🤝 Contributing

1. Fork the repository
2. Create feature branch (`git checkout -b feature/amazing-feature`)
3. Commit changes (`git commit -m 'Add amazing feature'`)
4. Push to branch (`git push origin feature/amazing-feature`)
5. Open Pull Request

## 📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

## 🙏 Acknowledgments

- **Aladin Lite**: Astronomical visualization engine
- **Qwen-Agent**: AI agent framework and MCP integration
- **MCP Protocol**: Model Context Protocol specification
- **FastAPI**: High-performance backend framework
- **React + Vite**: Modern frontend development stack
- **Ant Design**: UI component library
- **Styled Components**: CSS-in-JS styling solution

---

## 📞 Support

For questions and support:
- Create an issue in this repository
- Check the troubleshooting section above
- Review browser console logs for debugging

**Happy exploring the universe! 🌌✨**