googlecloudplatform--generative-ai/gemini/multimodal-live-api/project-livewire/docs/local_setup.md

Project Livewire - Local Setup Guide

This guide provides detailed instructions for setting up and running Project Livewire on your local machine for development and testing.

Prerequisites

Before you begin, ensure you have the following installed and configured:

1. Python: Version 3.8 or higher. (Download)
2. pip: Python package installer (usually included with Python).
3. Git: For cloning the repository. (Download)
4. API Keys:
   • Google Gemini API Key: Required for interacting with the Gemini model.
     • Get one from Google AI Studio.
   • OpenWeather API Key: Required only if you want to use the weather tool.
     • Get one from OpenWeatherMap.
5. Deployed Cloud Functions (Optional but Recommended):
   • For tool integration (weather, calendar), you need the corresponding Google Cloud Functions deployed.
   • Follow the Cloud Functions Setup Guide to deploy them.
   • Note down the HTTP Trigger URLs for each function you deploy.
6. Google Cloud SDK (gcloud) (Optional):
   • Needed if you want to use Google Cloud Secret Manager locally via Application Default Credentials (ADC).
   • Install Guide
   • Authenticate: gcloud auth application-default login

Setup Steps

1. Clone the Repository:

   git clone https://github.com/heiko-hotz/project-livewire.git
   cd project-livewire
   

2. Backend Configuration (.env file):

   • Navigate to the server directory:

     cd server
     

   • Copy the example environment file:

     cp .env.example .env
     

   • Edit the .env file using a text editor (like nano, vim, or VS Code):

     nano .env
     

   • Fill in the required values:
     • GOOGLE_API_KEY: Required if not using Vertex AI or ADC. Paste your Gemini API key here.
     • WEATHER_FUNCTION_URL: Required for the weather tool. Paste the trigger URL of your deployed get-weather-tool function.
     • CALENDAR_FUNCTION_URL: Required for the calendar tool. Paste the trigger URL of your deployed get-calendar-tool function.
     • OPENWEATHER_API_KEY: Required if not storing it in Secret Manager and accessing via ADC. Paste your OpenWeather API key here.
   • Optional/Advanced Configuration:
     • GOOGLE_CLOUD_PROJECT: Your Google Cloud Project ID. Required if using Vertex AI or accessing secrets via ADC.
     • GOOGLE_CLOUD_LOCATION: Google Cloud region (e.g., us-central1). Required if using Vertex AI.
     • GOOGLE_GENAI_USE_VERTEXAI=true: Set to true to use the Vertex AI endpoint instead of the Google AI Developer endpoint. Requires GOOGLE_CLOUD_PROJECT and GOOGLE_CLOUD_LOCATION to be set, and appropriate authentication (usually ADC).
     • GOOGLE_APPLICATION_CREDENTIALS: Path to your service account key file (JSON). Use this for explicit service account authentication, often used with ADC for Secret Manager access. If gcloud auth application-default login was used, this might not be needed.
     • LOG_LEVEL: Set logging verbosity (e.g., DEBUG, INFO, WARNING). Defaults to INFO.

3. Install Backend Dependencies:

   • Make sure you are still in the server/ directory.
   • (Optional but recommended) Create and activate a virtual environment:

     python3 -m venv venv
     source venv/bin/activate # Linux/macOS
     # venv\Scripts\activate # Windows
     

   • Install required packages:

     pip install -r requirements.txt
     

4. Start the Backend Server:

   • While in the server/ directory:

     python server.py
     

   • The server will start, usually listening on 0.0.0.0:8081. Look for the log message Running websocket server on 0.0.0.0:8081.... Keep this terminal running.

5. Start the Frontend Server:

   • Open a new terminal window/tab.
   • Navigate to the client directory:

     cd ../client # Or navigate from the project root: cd project-livewire/client
     

   • Start a simple Python HTTP server:

     python -m http.server 8000
     

   • This server serves the HTML, CSS, and JavaScript files. Keep this terminal running.

6. Access the Application:

   • Open your web browser.
   • Navigate to the Development UI: http://localhost:8000/index.html
   • Or navigate to the Mobile UI: http://localhost:8000/mobile.html

Testing the Connection

1. Open your browser's developer console (usually F12).
2. Check the "Console" tab for any errors, especially WebSocket connection errors.
3. Look for a "WebSocket connection established" or similar message from the client-side JavaScript.
4. Try clicking the microphone button (or play button on mobile) and speaking, or typing a message in the text input (dev UI).
5. Observe the terminal running the server.py script for log messages indicating client connections and messages being processed.

Troubleshooting

• Connection refused errors (WebSocket):
  • Ensure the backend server (server.py) is running in the other terminal.
  • Verify the WebSocket URL in the client JavaScript (client/src/api/gemini-api.js) matches where the server is listening (default ws://localhost:8081).
• ModuleNotFoundError: Make sure you installed dependencies using pip install -r requirements.txt in the server/ directory (and activated your virtual environment if you created one).
• API Key Errors / Authentication Errors:
  • Double-check the GOOGLE_API_KEY in your .env file.
  • If using Vertex AI or ADC, ensure GOOGLE_CLOUD_PROJECT is correct and your environment is properly authenticated (gcloud auth application-default login or GOOGLE_APPLICATION_CREDENTIALS).
  • Check server logs for specific authentication failure messages.
• Tool Function Errors (e.g., Weather):
  • Verify the *_FUNCTION_URLs in your .env file are correct and point to your deployed Cloud Functions.
  • Ensure the Cloud Functions themselves are working correctly (test them directly using curl as shown in the Cloud Functions README).
  • Check if the necessary API keys (like OPENWEATHER_API_KEY) are correctly configured either in .env or accessible via Secret Manager/ADC.
• Port Conflicts: If 8081 or 8000 are already in use, the servers might fail to start. Stop the conflicting process or configure the servers/client to use different ports (requires code changes).
• Microphone/Webcam Access Denied: Ensure you grant permission in your browser when prompted. Check browser settings if you previously denied access.