# 🚀 Luna API Server - Grok Backend Setup Guide This guide explains how to host the Luna API server using Grok (xAI) as the AI backend. ## Quick Start ### Option 1: Using Python Script (Recommended) ```bash export GROK_API_KEY="your-grok-api-key" python start_server_grok.py ``` ### Option 2: Using Bash Script ```bash export GROK_API_KEY="your-grok-api-key" ./start_server_grok.sh ``` ### Option 3: Using main.py Directly ```bash python main.py \ --host 127.0.0.1 \ --port 8000 \ --ai-backend grok \ --grok-api-key "your-grok-api-key" ``` ## Configuration ### Environment Variables ```bash # Required export GROK_API_KEY="your-grok-api-key" # Optional (with defaults) export HOST="127.0.0.1" # Default: 127.0.0.1 export PORT="8000" # Default: 8000 export LOG_LEVEL="INFO" # Default: INFO (DEBUG|INFO|WARNING|ERROR|CRITICAL) ``` ### Command Line Arguments ```bash python main.py \ --host 0.0.0.0 # Listen on all interfaces (for remote access) --port 8000 # Change port if needed --log-level DEBUG # More verbose logging --ai-backend grok # Use Grok backend --grok-api-key "your-key" # Your Grok API key ``` ## API Endpoints Once the server is running, access these endpoints: | Endpoint | Method | Purpose | | --------------- | --------- | ------------------------------------------ | | `/docs` | GET | Interactive API documentation (Swagger UI) | | `/redoc` | GET | ReDoc API documentation | | `/ai` | POST | Send AI requests with tool support | | `/execute-tool` | POST | Execute a specific plugin tool | | `/ws` | WebSocket | Real-time streaming responses | ## Example API Requests ### 1. Chat Request with Tool Support ```bash curl -X POST "http://127.0.0.1:8000/ai" \ -H "Content-Type: application/json" \ -d '{ "text": "create a note called Ideas", "mode": "act", "approved": false }' ``` ### 2. Tool Execution ```bash curl -X POST "http://127.0.0.1:8000/execute-tool" \ -H "Content-Type: application/json" \ -d '{ "plugin_name": "notebook", "tool_name": "create_note", "inputs": { "title": "My Ideas", "content": "Important thoughts" } }' ``` ### 3. WebSocket Connection (Real-time Streaming) ```bash websocat ws://127.0.0.1:8000/ws # Send JSON messages for streaming responses {"text": "explain this code", "mode": "explain_only"} ``` ## Troubleshooting ### "Invalid API Key" ``` ❌ Error: Grok API request failed: 401 Unauthorized ``` **Solution:** Check that your GROK_API_KEY is correct and valid. ```bash # Verify the key is set echo $GROK_API_KEY # Get a new key from https://console.x.ai ``` ### "Connection Refused" ``` ❌ Error: Failed to connect to Grok API ``` **Solution:** Ensure you have internet connectivity. Grok API requires external network access. ### "Port Already in Use" ``` ❌ Error: Address already in use ``` **Solution:** Use a different port: ```bash export PORT="8001" python start_server_grok.py ``` Or kill the existing process: ```bash lsof -i :8000 kill -9 <PID> ``` ## Running in Background ### Using `nohup` ```bash nohup env GROK_API_KEY="your-key" python start_server_grok.py > luna_server.log 2>&1 & ``` ### Using `screen` ```bash screen -S luna export GROK_API_KEY="your-key" python start_server_grok.py # Press Ctrl+A then D to detach ``` ### Using `systemd` (Linux) Create `/etc/systemd/system/luna.service`: ```ini [Unit] Description=Luna API Server with Grok Backend After=network.target [Service] Type=simple User=arya WorkingDirectory=/home/arya/Project/Luna Environment="GROK_API_KEY=your-grok-api-key" Environment="HOST=0.0.0.0" Environment="PORT=8000" ExecStart=/usr/bin/python3 start_server_grok.py Restart=always RestartSec=10 [Install] WantedBy=multi-user.target ``` Then: ```bash sudo systemctl daemon-reload sudo systemctl enable luna sudo systemctl start luna sudo systemctl status luna ``` ## Integration with Intent Classification The Luna server automatically uses the Intent Classification system when receiving `/ai` requests: 1. **Intent Classification Layer**: User text is classified using the Grok backend 2. **Tool Resolution**: Classified intent is mapped to specific tools 3. **Execution**: Tools are executed with appropriate approval gating 4. **Response**: Results are returned via REST or WebSocket ## Monitoring ### View Logs ```bash # Real-time logs tail -f luna_server.log # Last 100 lines tail -100 luna_server.log # Filter by error level grep ERROR luna_server.log ``` ### Check Server Health ```bash curl http://127.0.0.1:8000/docs ``` If you see the Swagger UI, the server is running correctly. ## Security Considerations 1. **API Key Management** - Never commit API keys to version control - Use environment variables or `.env` files - Rotate keys regularly 2. **Network Access** - By default, server listens on `127.0.0.1` (localhost only) - For remote access, use `--host 0.0.0.0` and implement authentication - Consider using a reverse proxy (nginx, etc.) for production 3. **CORS Headers** - The server includes CORS middleware - Configured to accept requests from any origin in development - Customize for production use ## Advanced Configuration ### Using Policy File ```bash python start_server_grok.py --policy /path/to/policy.yaml ``` ### Custom Logging ```bash python main.py \ --ai-backend grok \ --grok-api-key "your-key" \ --log-level DEBUG \ --log-file luna.log ``` ### Multiple Backends You can run multiple Luna instances with different backends: ```bash # Terminal 1: Grok backend on port 8000 export GROK_API_KEY="gsk_..." PORT=8000 python start_server_grok.py # Terminal 2: Gemini backend on port 8001 export GEMINI_API_KEY="AIza..." PORT=8001 python main.py --ai-backend gemini --gemini-api-key $GEMINI_API_KEY ``` ## Performance Tips 1. **Use `grok-4-fast`** (default) for faster responses 2. **Increase `max_tokens`** if generating long responses 3. **Adjust temperature** for different response styles 4. **Use connection pooling** for high-volume requests ## Next Steps - 📖 Read the [API Documentation](http://127.0.0.1:8000/docs) (once server is running) - 🧪 Test with the CLI: `python luna_cli.py --ai-backend grok --grok-api-key "..."` - 🔌 Integrate with your applications using the REST or WebSocket APIs - 📊 Monitor server performance and logs ## Useful Resources - **Grok/xAI API Docs**: https://docs.x.ai/docs/api-reference - **FastAPI Docs**: https://fastapi.tiangolo.com/ - **Luna Architecture**: See `ARCHITECTURE.md` - **Intent Classification**: See `INTENT_CLASSIFICATION_ARCHITECTURE.md` --- For more help, check the project README.md or QUICKSTART.md